WhatsApp の設定

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

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

二つの使い方

事前に必要なもの

• 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 が何も返さなくなります。私用の番号ではたいていこちらのほうが向いています。

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

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

# ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # quiet period before flushing a batch
        text_batch_split_delay_seconds: 10.0  # extended delay near the split threshold

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

困ったときは

セキュリティ

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

whatsapp:
  unauthorized_dm_behavior: ignore

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