Hermes WhatsApp セットアップの新機能

Hermes Agent シリーズをフォローしてくれている方ならご存知の通り、私たちは「いかにシンプルにするか」を常に追求しています。今回は、アップデートされた WhatsApp セットアップについて詳しく解説します — 内部には大きな変更が加わっています。

Hermes は現在、Baileys ベースの内蔵ブリッジを通じて WhatsApp に接続します。これは WhatsApp Web セッションをエミュレートするようなものだと考えてください。Meta 開発者アカウントも、ビジネス認証も、公開 URL も不要 — 必要なのは、あなたとスマホ、そして QR コードだけです。

クイックスタート: hermes gateway setup を実行して WhatsApp を選択すれば、ガイド付きでセットアップが進みます。

2つの WhatsApp 統合 — 違いを理解しよう

先に進む前に、よくある混乱ポイントを整理しておきましょう。WhatsApp を Hermes に接続する方法は2つあります：

統合方法	最適な用途	必要なもの
Baileys ブリッジ（このガイド）	個人用ボット、クイックテスト、公開 URL 不要	WhatsApp が入ったスマホだけ
WhatsApp Business Cloud API	本格的なビジネスボット、安定性、禁止リスクゼロ	Meta ビジネスアカウント、公開 Webhook URL

Baileys ブリッジは非公式であり、わずかにアカウント停止リスクがあります。Business Cloud API は Meta 公式サポートの経路です。必要であれば、異なる電話番号で両方を並行して運用することも可能です。

⚠️ 2つの重要な警告

アカウント停止リスク: WhatsApp は Business API 以外のサードパーティ製ボットを公式にはサポートしていません。安全に運用するために：

ボットには専用の電話番号を使用する（個人番号は使わない）
一括送信やスパムメッセージは送らない — 会話形式を維持する
先にメッセージを送ってきていない人への自動アウトバウンドメッセージは送らない

プロトコル更新: WhatsApp は定期的に Web プロトコルを更新するため、サードパーティ製ブリッジが一時的に機能しなくなることがあります。WhatsApp のアップデート後にボットが動作しなくなったら、最新の Hermes バージョンを取得して再ペアリングしてください。

2つのモード — 自分のスタイルに合わせて選ぶ

モード	動作方法	最適な用途
専用ボット番号（推奨）	ボット専用の番号を用意し、ユーザーが直接メッセージを送る	クリーンな UX、複数ユーザー、停止リスクが低い
個人セルフチャット	自分の WhatsApp を使用し、自分自身にメッセージを送ってエージェントと会話	クイックセットアップ、単一ユーザー、テスト用

前提条件

Node.js v18+ と npm — ブリッジは Node.js プロセスとして動作します
WhatsApp がインストールされたスマホ（QR コードスキャン用）

良い知らせ：現在の Baileys ベースのブリッジは、Chromium や Puppeteer が不要になりました。かなり軽量です。

ステップ 1: セットアップウィザードを実行

hermes whatsapp

ウィザードは以下のことを行います：

どのモードを使うか尋ねます（bot または self-chat）
必要に応じてブリッジの依存関係をインストール
ターミナルに QR コードを表示
スキャンされるのを待ちます

QR コードのスキャン方法：

スマホで WhatsApp を開く
設定 → 連携デバイス に移動
デバイスを連携 をタップ
カメラをターミナルの QR コードに向ける

ペアリングが完了すると、ウィザードが接続を確認して終了します。セッションは自動的に保存されます。

ヒント: QR コードが文字化けしている場合は、ターミナルの幅が60カラム以上あり、Unicode に対応していることを確認してください。

ステップ 2: 2つ目の電話番号を取得（ボットモード）

ボットモードでは、WhatsApp に未登録の番号が必要です。3つの選択肢があります：

選択肢	費用	備考
Google Voice	無料	米国のみ。Google Voice アプリ経由で SMS による WhatsApp 認証を行います。
プリペイド SIM	5〜15ドル（一回限り）	アクティベートして認証後、SIM は引き出しにしまっておけます。90日ごとに一度通話してアクティブ状態を維持します。
VoIP サービス	無料〜月5ドル	TextNow、TextFree など。一部の番号は WhatsApp にブロックされる場合があるので、いくつか試してみてください。

番号を取得したら：

スマホに WhatsApp をインストール（デュアルSIM対応の WhatsApp Business アプリでも可）
新しい番号を登録
hermes whatsapp を実行し、そのアカウントから QR コードをスキャン

ステップ 3: Hermes を設定

~/.hermes/.env ファイルに以下を追加します：

# 必須
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" または "self-chat"

# アクセス制御 — いずれか1つを選択：
WHATSAPP_ALLOWED_USERS=15551234567         # カンマ区切りの番号（国番号、+ なし）
# WHATSAPP_ALLOWED_USERS=*                 # または全員を許可
# WHATSAPP_ALLOW_ALL_USERS=true            # またはこのフラグを設定（* と同じ）

全員許可の省略記法: WHATSAPP_ALLOWED_USERS=* を設定すると全送信者が許可されます — WHATSAPP_ALLOW_ALL_USERS=true と同等です。代わりにペアリングフローを使用する場合は、両方の変数を削除して DM ペアリングシステムに依存してください。

~/.hermes/config.yaml のオプション設定：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair（グローバルデフォルト）は、DM を送ってきた未知の送信者にペアリングコードを送信します。
ignore は、許可されていない DM に対して WhatsApp を沈黙させます — プライベート番号では通常こちらが良いでしょう。

次にゲートウェイを起動します：

hermes gateway              # フォアグラウンド
hermes gateway install      # ユーザーサービスとしてインストール
sudo hermes gateway install --system   # Linux: 起動時のシステムサービス

セッションの永続化と再ペアリング

ブリッジはセッションを ~/.hermes/platforms/whatsapp/session に保存します。つまり：

セッションは再起動後も維持されます — 毎回スキャンし直す必要はありません
セッションデータには暗号化キーとデバイス認証情報が含まれます
このディレクトリを共有したりコミットしたりしないでください — アカウントへの完全なアクセス権が付与されます

セッションが壊れた場合（スマホのリセット、WhatsApp のアップデート、手動でのリンク解除）、ログに接続エラーが表示されます。以下のコマンドで修正できます：

hermes whatsapp

これにより、再ペアリング用の新しい QR コードが生成されます。

新しい WhatsApp セットアップはざっとこんな感じです。迅速、軽量、そして Meta の書類手続きは一切不要。シリーズの次回は、このブリッジと WhatsApp Business Cloud API を徹底比較します — お楽しみに！