WhatsApp の設定

Hermes は Baileys をもとにした内蔵のブリッジを通して WhatsApp につながります。これは WhatsApp Web のセッションをまねる方式で、公式の WhatsApp Business API を使うものでは ありません。Meta の開発者アカウントもビジネスの審査も要りません。

> hermes gateway setup を実行して WhatsApp を選ぶと、案内に沿って設定を進められます。

複数のプロファイル

ホストのマルチプレクサーは、プロファイルごとに別々の連携済み WhatsApp セッションを扱えます。 hermes -p work whatsapp を実行して2つ目以降のプロファイルを連携し、そのプロファイルで WhatsApp を有効にしてください。 WhatsApp を有効にしていても creds.json がないプロファイルは、 whatsapp_unpaired の状態と、連携に使うコマンドを示したうえでスキップされます。

platforms.whatsapp.extra.bridge_port を明示している場合は、その値が優先されます。指定がなければ、 2つ目以降のプロファイルは 3001〜3999 のうち、ほかのプロファイルの記録が使っていない最初の空きポートを選び、 次回以降の起動に備えて自分の platforms/whatsapp/bridge_port ファイルに保存します。運用する側がポート番号を書いたこのファイルを先に作っておくこともできます。 ファイルを消すと、新しいポートが割り当てられます。起動したプロファイルはポート 3000 を使います。 ただし、（2つ目以降のプロファイルとして使われたことがあって）このファイルをすでに持っている場合は、そのゲートウェイも hermes send --to whatsapp:<chat_id> も、記録されたポートを使い続けます。

2つ目以降のプロファイルが、自分のポートですでに動いているブリッジを引き継ぐのは、自分のセッションの pidfile がそのプロセスを特定できる場合（pid、カーネル上の起動時刻、起動時のポート）だけです。 これは、ゲートウェイがクラッシュしたときに残る状態です。 正常に動いていないブリッジは、同じ特定方法で片付けられてから再起動されます。そのポートを使っているそれ以外のプロセスがあると、 そのプロファイルだけが致命的なエラーになります。platforms.whatsapp.extra.bridge_port に別の空きポートを設定するか、 ポートを使っているプロセスを止めてください。ほかの プロファイルは動き続けます。hermes gateway status --profile work は、共有の受け口ではなく、 そのプロファイル自身の WhatsApp アダプターの状態を表示します。

1つのゲートウェイにまとめず、プロファイルごとに別々のゲートウェイを動かす場合は、 設定しない限りどれもポート 3000 を使います。それぞれのプロファイルの config.yaml で、別々のポートを割り当ててください。

platforms:
  whatsapp:
    extra:
      bridge_port: 3001        # one distinct port per profile

ゲートウェイは、動いているブリッジを、そのブリッジが /health で報告するセッションのディレクトリで見分けます。 ほかのプロファイルのセッションを扱っているブリッジを引き継ぐことも、止めることもありません。 このとき2つ目のプロファイルの WhatsApp は、ポートと相手のセッションを示した whatsapp_bridge_foreign_session で起動に失敗します。ポートを使っているのに /health に時間内に応答しないプロセスも、 そのまま動かしておきます。このとき WhatsApp は、再試行できる whatsapp_bridge_unresponsive で失敗します。hermes send --to whatsapp:<chat_id> と cron の 配信も同じ項目を確かめ、ほかのプロファイルのブリッジや、/health に失敗するブリッジを通しては何も送りません。 session_path を上書きする場合は、プロファイルごとに別の値にしてください。同じ値にすると、プロファイル同士で 1つの WhatsApp のログインを共有することになります。古い Hermes が起動したブリッジはセッションのディレクトリを報告しないので、 ブリッジを更新したときと同じように一度だけ再起動されます。

二つの使い方

事前に必要なもの

• Node.js v18 以上 と npm — WhatsApp のブリッジは Node.js のプロセスとして動きます
• WhatsApp を入れた 電話 — QR コードを読み取るために使います

以前のブラウザを動かす方式のブリッジと違い、いまの Baileys 方式のブリッジでは、手元に Chromium や Puppeteer 一式を用意する必要は ありません。

ステップ 1: 設定のウィザードを動かす

hermes whatsapp

ウィザードは次のように進みます。

1. どちらの使い方にするかを聞きます（bot か self-chat）
2. 必要ならブリッジの依存を入れます
3. 端末の画面に QR コード を出します
4. 読み取られるのを待ちます

QR コードの読み取り方

1. 電話で WhatsApp を開きます
2. 設定 → リンク済みデバイス を開きます
3. デバイスをリンク を選びます
4. カメラを端末の QR コードに向けます

連携できるとウィザードが接続を知らせて終わります。セッションは自動で保存されます。

ステップ 2: 二つ目の電話番号を用意する（ボットの使い方）

ボットとして使う場合、WhatsApp にまだ登録していない電話番号が必要です。選び方は三つあります。

番号を用意したら次のようにします。

1. 電話に WhatsApp を入れます（デュアル SIM なら WhatsApp Business アプリでも構いません）
2. 新しい番号を WhatsApp に登録します
3. hermes whatsapp を実行し、その WhatsApp アカウントで QR コードを読み取ります

ステップ 3: Hermes を設定する

~/.hermes/.env に次を書き足します。

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" or "self-chat"

# Access control — pick ONE of these options:
WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)
# WHATSAPP_ALLOWED_USERS=*                 # OR use * to allow everyone
# WHATSAPP_ALLOW_ALL_USERS=true            # OR set this flag instead (same effect as *)

~/.hermes/config.yaml では、動きを変える設定も選べます。

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• unauthorized_dm_behavior: pair が全体の初期値です。知らない相手から個別のメッセージが来ると、ペアリング用のコードを返します。
• whatsapp.unauthorized_dm_behavior: ignore にすると、許可していない相手からの個別のメッセージに WhatsApp が何も返さなくなります。私用の番号ではたいていこちらのほうが向いています。

グループのトーク（ボットの使い方）

グループを通すかどうかを決めるのは、個別のメッセージ向けの許可リストではなくグループの方針です。WHATSAPP_GROUP_POLICY / whatsapp.group_policy の初期値は pairing で、グループからは何も転送しません。allowlist にして WHATSAPP_GROUP_ALLOWED_USERS / whatsapp.group_allow_from（カンマ区切りのグループ JID。たとえば 120363001234567890@g.us）を並べると、書いたグループだけが通ります。 open なら、ボットが入っているグループはすべて通ります。送り主は、そのうえでほかのゲートウェイの相手と同じように確かめられます。 WHATSAPP_ALLOWED_USERS を設定している場合、発言した人がその一覧に載っているか、ペアリング済みである必要があります。WhatsApp が LID で 指してくる送り主は、Baileys がそれと一緒に渡してくる電話番号で照合されるので、lid-mapping のファイルがまだ無い初めての相手でも 取りこぼしません。送り主の許可リストを置いていない場合、 allowlist はグループ JID の一覧だけを信頼して、載っているグループの参加者全員を通します。open のほうは、やはり参加者がペアリング済みか WHATSAPP_ALLOW_ALL_USERS=true である必要があります。初期状態では、通したグループのメッセージにはボットが毎回返します。 require_mention: true / WHATSAPP_REQUIRE_MENTION=true にすると、@メンション・ボットへの返信・/commands のときだけ返すようになります（free_response_chats に入れたグループは対象外です）。

そのあとゲートウェイを起動します。

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

ゲートウェイは、保存されたセッションを使って WhatsApp のブリッジを自動で立ち上げます。

セッションの保存

Baileys のブリッジはセッションを ~/.hermes/platforms/whatsapp/session に保存します。つまり次のようになります。

• 再起動してもセッションは残ります — 毎回 QR コードを読み取り直す必要はありません
• セッションのデータには暗号鍵と端末の資格情報が入っています
• このセッションのディレクトリを人に渡したり、リポジトリに入れたりしないでください — WhatsApp のアカウントに丸ごと入れてしまうものです

連携をやり直す

セッションが壊れると（電話の初期化、WhatsApp の更新、手動での連携解除など）、ゲートウェイのログに接続のエラーが出ます。直すには次を実行します。

hermes whatsapp

新しい QR コードが出ます。もう一度読み取ればセッションがつなぎ直されます。一時的な 切断（通信の乱れ、電話が短いあいだ圏外になるなど）は、ゲートウェイが再接続の仕組みで自動的に処理します。

音声メッセージ

Hermes は WhatsApp の音声にも対応しています。

• 受け取る側: 音声メッセージ（.ogg の opus）は、設定した音声認識の提供元で自動的に文字に起こされます。手元で動く faster-whisper、Groq の Whisper（GROQ_API_KEY）、OpenAI の Whisper（VOICE_TOOLS_OPENAI_KEY）のいずれかです
• 送る側: 音声合成の返事は MP3 の音声ファイルとして添付されます
• エージェントの返事には初期状態で「☤ Hermes Agent」が先頭に付きます。これは config.yaml で変えたり、なくしたりできます。

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)
  send_read_receipts: false                 # Mark accepted inbound messages as read (blue ticks)

send_read_receipts が true のとき、アダプターは個別・グループ・メンションの絞り込みを通ったメッセージを既読にします。弾かれたメッセージ（許可リストにない相手からのものなど）は既読になりません。プライバシーへの配慮から初期状態では無効です。この設定を変えると、次に接続するときブリッジの子プロセスが自動で立ち上げ直されます。

メッセージの書式と送り方

WhatsApp は 少しずつ書き足していく返事 に対応しています。AI が文章を作るのに合わせてボットが自分のメッセージをその場で書き換えていく方式で、Discord や Telegram と同じです。内部では、送信のできることの区分として WhatsApp を TIER_MEDIUM のプラットフォームとして扱っています。

分割

長い返事は 4,096 文字 ごとに自動で複数のメッセージに分けられます（WhatsApp が実際に表示できる上限です）。設定は要りません。ゲートウェイが分割し、順番に送ります。

WhatsApp に合わせたマークダウン

AI の返事に含まれる通常のマークダウンは、WhatsApp 本来の書式に自動で置き換えられます。

コードブロックと文中のコードは、WhatsApp がバッククォート三つの書式にもとから対応しているため、そのまま残ります。

ツールの進み具合

エージェントがツールを呼ぶと（ウェブ検索、ファイルの操作など）、WhatsApp にはどのツールが動いているかがその場で表示されます。初期状態で有効なので、設定は要りません。

アンケート・選択肢の質問・位置情報

Baileys ブリッジのアダプター（ボットの使い方）は、WhatsApp のいくつかの機能をそのまま使えます。

• アンケート — エージェントはブリッジの /send-poll の窓口を通して、WhatsApp のアンケート（質問と選択肢）を送れます。投票の結果は会話に戻ってきます。
• 選択肢の質問をアンケートで出す — エージェントが選択肢のある確認の質問をするとき、一つだけ選べるアンケートとして表示されます。選択肢をタップすれば答えたことになります。アンケートを送れなかった場合、アダプターはふつうの文章の質問に切り替えます。承認を求める場面がアンケートになることは ありません。アンケートを使うのは、本当に選択肢から選ぶ質問だけです。
• 位置情報のピン — エージェントは /send-location を通して位置情報のピン（緯度と経度、必要なら名前や住所）を送れます。届いた位置情報（現在地の共有を含みます）は、位置情報のメッセージとしてエージェントに渡されます。

どれもボット（Baileys）の使い方なら最初から動きます。設定は要りません。

メッセージのまとめ送り（待ち合わせ）

WhatsApp はメッセージを一通ずつ届けます。そのため、立て続けに届いた場合（まとめての転送、貼り付けで分かれたもの、複数行の文章）、そのままでは断片ごとにエージェントが呼ばれてしまい、トークンを無駄にしたうえ、ばらばらの返事がいくつも並ぶことになります。アダプターは同じチャットから続けて届いた文章をためておき、少し静かになってから一つの依頼としてまとめて渡します（初期値は 0.3 秒、断片がとても長い場合は 1 秒 に延びます。上限はそれぞれ 2 秒と 4 秒です）。config.yaml で調整できます。

# ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 0.3         # quiet period before flushing a batch (max 2.0)
        text_batch_split_delay_seconds: 1.0   # extended delay near the split threshold (max 4.0)

text_batch_delay_seconds: 0 にすると、メッセージごとにすぐ渡されます（まとめ送りは無効になります）。

引用した返信

以前のメッセージに返信する（引用する）と、エージェントは引用された文面を文脈として受け取ります。画像、ボイスメモ、動画、文書を引用すると、そのファイルもそのターンに添えられるので、引用した画像の下に「これは何？」と書けば通じます。添付がほかの人から届いたものでも、ボット自身が送ったもの（cron で届いたグラフや生成した画像）でも同じです。WhatsApp が引用に付けて送るのはサムネイルの切れ端だけなので、ファイルはブリッジのダウンロードのキャッシュ（受け取ったメディア。ブリッジが動いているあいだだけメモリに保持）か、ボット自身が送ったものを記録した手元の索引（直近 1000 件）から引き当てます。それより古いものを引用しても、ファイルは添えられません。

困ったときは

セキュリティ

初期状態では、許可していない個別のメッセージにもペアリングのコードが返ります。私用の WhatsApp の番号で知らない相手に一切反応させたくない場合は、次を設定します。

whatsapp:
  unauthorized_dm_behavior: ignore

• ~/.hermes/platforms/whatsapp/session にはセッションの資格情報がそのまま入っています。パスワードと同じように守ってください
• ファイルの権限を絞ります: chmod 700 ~/.hermes/platforms/whatsapp/session
• 個人のアカウントに影響が及ばないよう、ボットには 専用の電話番号 を使います
• 乗っ取られた疑いがあるときは、WhatsApp の 設定 → リンク済みデバイス から連携を解除します
• ログの電話番号は一部が伏せられますが、ログをどれだけ残すかの方針も見直してください