WhatsApp

ZeroClaw は同じ channels.whatsapp 設定ファミリーの下で 2 つの WhatsApp バックエンドをサポートしています:

後方互換性のために意図的に Cloud API モードを優先させたい場合を除き、同じチャネルで両方のセレクターを設定しないでください。

エージェントと対話できるユーザー

受信側の送信者は、バインドされたエージェントに対して解決されたピアセットに照らして制御されます。これはエージェントが所属する peer_groups 設定から導出されます。照合では先頭の @ を取り除き、チャネルのネイティブな送信者識別子に対して大文字・小文字を区別せずに行われます。空のセットはすべてを拒否し、"*" を含むセットはすべてを受け入れます。それ以外の場合は、リストに記載された外部ピア（およびピアエージェント）のみが受け入れられます。これはゲートウェイのペアリング（gateway.require_pairing）とは別物であり、ペアリングはチャットチャネルの送信者ではなく HTTP/WebSocket クライアントを認証します。

whatsapp 用のピアグループでは、channel を whatsapp に設定し、許可する送信者を external_peers に列挙します（whatsapp の場合は電話番号識別子（Cloud API）または JID のユーザー部分（Web モード）。["*"] は誰でも受け入れます）。オプションで、エージェント間ディスパッチ用のピア agents、ignore ブロックリスト、output_modality（mirror、voice、または text）を指定できます。フィールドのリファレンスについては Peer Groups を参照してください。

この設定の場所:

クラウド API モード

Cloud API モードは、Meta Business Platform と連携するモードです。Meta Business アカウント、WhatsApp Business アプリ、電話番号 ID、検証トークン、アクセストークン、アプリシークレットが必要です。Meta の Webhook 経由でメッセージを受信するビジネス向けのデプロイには、このモードが適しています。

受信 Webhook は app_secret に対して署名検証され、検証は必須です。アプリシークレットが設定されていない場合、ゲートウェイはリクエストを検証できないため、401 を返し、何も処理しません。Meta にコールバック URL を指定する前に app_secret を設定してください。

ゲートウェイは、受信 Webhook のために Meta から到達可能である必要があります。トップレベルの [tunnel] セクション（tunnel_provider と関連するプロバイダーブロック、設定リファレンスを参照）でトンネルを設定するか、ローカルで開発する場合は独自のリバースプロキシをゲートウェイの前段に配置してください。

Meta の Callback URL は、受信させたい [channels.whatsapp.<alias>] インスタンスのエイリアスに向けてください: GET/POST https://<your-public-url>/whatsapp/<alias>（例: [channels.whatsapp.work] → /whatsapp/work）。このエイリアスごとのルーティング（#6312）により、複数の WhatsApp 番号を並行して運用できます。素の /whatsapp パスは引き続き機能しますが非推奨です: 辞書順で最初のエイリアス（再起動をまたいで決定的）に解決され、X-Zeroclaw-Deprecation レスポンスヘッダーを設定します。不明なエイリアスは 404 を返します。単一インスタンスのデプロイでは変更は不要です。

Webモード

WhatsApp Web モードでは、オプションの Web バックエンドを介して通常の WhatsApp アカウントをリンクします。Meta Business アカウントは不要です。ただし、whatsapp-web フィーチャーを有効にした ZeroClaw ビルドと、永続的なセッションデータベースのパスが必要です。

初回起動時、Web バックエンドは QR またはペアコードによるリンク方式でアカウントをペアリングします（pair_phone はペアコードリンクのシードとなり、QR を使う場合は未設定のままにします）。session_path は永続ストレージ上に保持してください。これを削除すると、デバイスの再リンクが強制されます。チャネルは、対象エージェントの channels リストを介してそのエージェントにバインドします。

push_name は受信者に表示される表示名を設定します。未設定のままにすると、アカウントには電話番号の登録時に使用した名前が保持されます。これは接続時に適用され、リンク済みデバイスにすでに設定されている名前と異なる場合にのみ適用されます。適用に失敗してもログに記録されるだけで、チャネルは停止しません。Cloud API モードでは無視され、その場合、表示名は Meta Business プロフィールから取得されます。

共有の interrupt_on_new_message オプションは、Cloud API モードと Web モードの両方に適用されます。有効にすると、同じ送信者/チャットからの新しい WhatsApp メッセージが、処理中の応答をキャンセルします。

個人およびビジネスの行動

Webモードでは、dm_policy と group_policy は両方のモードに適用されます。self_chat_mode は個人専用です：

self_chat_mode は、セルフチャット機能が設計上個人ブランチに限定されているため、個人専用のままです。mode は WhatsApp アカウントの種類ではなく、ZeroClaw のポリシー方針を選択します。どちらのモードでも同じリンク済みデバイスセッションを使用します。

fromMe ガードも個人ブランチ内に残りますが、それはビジネスモードに同等のものがないためではありません。ビジネスモードも依然として WhatsApp Web のリンク済みデバイスセッションであり、WhatsApp はどちらのモードでも、オペレーター自身が送信したメッセージをリンク済みデバイスに fromMe としてミラーリングします。リンク済みアカウントは承認済みピアとして永続化されるため、ビジネスモードではそのミラーが許可リストを満たしてディスパッチに到達する可能性があり、これは #6353 が個人モードで解消したのと同じ形です。この挙動は今回の変更より前から存在し、ここで導入されたものではありません。無視して解消済みとするのではなく明記しており、修正は別途追跡されています。

mode = "business" の互換性に関する注記

ビジネスモードでは以前、dm_policy と group_policy を受け付けていたものの、そのどちらも参照していなかったため、制限的と解釈されるチャンネルが受信したすべてのメッセージに応答していました。現在は、ビジネスモードで両方のキーが適用されます。

dm_policy はデフォルトで allowlist に設定されるため、以前の寛容な動作に依存していたビジネスモードのデプロイメントでは、次のいずれかを選択する必要があります:

• 全員への回答を続ける - dm_policy = "all" と group_policy = "all" を明示的に設定します。
• 制限を維持 - デフォルトのままにし、サービス対象とする送信者が、チャネルのピアグループを介して [peer_groups.<name>].external_peers 経由で到達可能であることを確認します。

config validate にこれを教えてもらうまで待ってはいけません。mode = "business" では、self_chat_mode は機能しないと報告され、dm_policy や group_policy については何も述べません。まさにその2つが、現在は機能しないのではなく有効になっているためです。つまり、実際に動作が変わったキーは、バリデーターが言及しないものです。アップグレードする前にこのセクションを読んでください。これが、ビジネスモードのデプロイメントに提供される唯一の通知です。

passive_group_context = true はオプトインであり、WhatsApp Web のグループチャットにのみ適用されます。許可された宛先指定のないグループメッセージは、エージェントのターンを開始したり、リアクションを送信したり、メディアをダウンロードしたり、モデルを呼び出したりすることなく、ルームスコープの会話履歴に保存されます。同じグループ内で後から送信される宛先指定のあるメッセージは、そのパッシブコンテキストを利用できます。

グループの制限（allowed_groups）

allowed_groups（Web モード）は、JID によって指定されたグループチャットの集合にボットの対象を限定します。これはmodeから独立しており、ビジネスモードと個人モードの両方に適用され、チャット種別ポリシーより先に実行されます。空のリストは権限を意味しません。その意味はgroup_policyによって決まります。allowlist（デフォルト）またはignoreでは空のリストはどのグループも許可せず、allではすべてのグループを許可します。すべてを許可するリストは、誰も設定していないリストと区別できないため、グループへの公開アクセスは名前を指定して要求する必要があります。空でないリストの場合、チャット JID がどのエントリにも一致しないグループメッセージはすべて除外され、allを含むすべてのポリシーでこの動作が続きます。つまり、allは空のリストのデフォルトを広げるものであり、明示的なリストを上書きするものではありません。ダイレクトメッセージは常にこのフィルターを迂回します。

各エントリは、完全なグループJID（123456789012345@g.us）またはJIDのユーザー部分 - @の前のセグメント（123456789012345）- のいずれかに一致し、完全に比較されます。文字列のプレフィックスとしては比較されません（したがって 123 は 123@g.us を許可しますが、123999@g.us は決して許可しません）。これはグループの_identity_をゲートするものであり、group_policy（チャットタイプ）と送信者許可リスト（sender）では行われません。

[channels.whatsapp.myaccount]
enabled = true
session_path = "/var/lib/zeroclaw/wa.db"
# これら2つのグループでのみ動作し、その他のグループはすべて破棄されます。
allowed_groups = ["120363012345678901@g.us", "120363098765432109"]

チャット経由のツール承認（approval_timeout_secs）

ツールの承認が必要な場合（always_ask に含まれている、またはリスクプロファイルによって自動承認されない場合）、エージェントはメッセージの送信元チャットにリクエストを投稿し、返信を待ちます。プロンプトに含まれるトークンで回答してください：

a1b2c3 yes
a1b2c3 no
a1b2c3 always

approval_timeout_secs はその待機時間に上限を設けます。デフォルトは 300 秒で、0 にすると承認を無効にするのではなく即座に拒否します。つまり、0 は承認が必要なすべてのツールを拒否する方法であり、永遠に待機する方法ではありません。タイムアウトするとリクエストは拒否され、トークンは破棄されるため、遅れて届いた返信によって、もはや誰も待機していない呼び出しが承認されることはありません。

回答できる人。 トークンはパスワードではなく、照合用の値です。チャットには平文で送信されるため、グループではすべてのメンバーが読み取れます。

2 つのモードは異なり、その違いは実装の詳細ではなく、セキュリティ境界です。

Web モードでは、返信が受け付けられるのは、プロンプトが投稿されたのと同じチャットからのもので、かつこのエイリアスが指示を受けることを許可されているピアからのものである場合に限られます。いずれかのチェックに失敗した返信はログに記録されて無視されますが、オペレーターが引き続き応答できるよう、リクエストはオープンのまま残ります。グループではプロンプトにその旨が示されます。そうしないと、傍観者の返信が何の効果も及ぼさなかった理由を知る方法がないためです。

認証されたピアとは、このエイリアスに対して正規リゾルバーが返すピア、つまり channel がこのエイリアスを指しているピアグループです：

[peer_groups.whatsapp_default]
channel = "whatsapp.personal"   # このエイリアスのみ。裸の "whatsapp" はすべてのエイリアスを対象とします
external_peers = ["+15550100"]

設定する allowed_numbers フィールドはありません。これは v2 での表記であり、移行時に上記のようなピアグループへ統合されるため、v2 の設定は引き続き動作しますが、v3 の設定には古いキーを置く場所がありません。

完全なフィールド一覧と、各チャネルが照合する識別子の形式については、ピアグループを参照してください。

Cloud API モードでは、どちらのチェックも適用されません。その保留エントリは、トークンをキーとする応答者だけで構成され、チャットも身元情報も併せて記録されないため、Webhook はトークンを所持していること自体を権限として扱います。グループでは、プロンプトを読めるメンバーなら誰でも、別のチャットからでも回答できることになります。この経路が強化されるまでは、Cloud モードでの承認は、誰かがトークンを所持していたことの証明にすぎません。チャットも応答者も認証しないため、どちらかが重要になる場合は Web モードを優先してください。

設定サーフェス

zeroclaw config set channels.whatsapp.<alias>.access_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__whatsapp__<alias>__access_token=

zeroclaw config set channels.whatsapp.<alias>.allowed_groups <value>

export ZEROCLAW_channels__whatsapp__<alias>__allowed_groups=

zeroclaw config set channels.whatsapp.<alias>.app_secret    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__whatsapp__<alias>__app_secret=

zeroclaw config set channels.whatsapp.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__approval_timeout_secs=

zeroclaw config set channels.whatsapp.<alias>.dm_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.dm_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_policy=

zeroclaw config set channels.whatsapp.<alias>.excluded_tools <value>

export ZEROCLAW_channels__whatsapp__<alias>__excluded_tools=

zeroclaw config set channels.whatsapp.<alias>.group_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.group_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_policy=

zeroclaw config set channels.whatsapp.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__whatsapp__<alias>__interrupt_on_new_message=

zeroclaw config set channels.whatsapp.<alias>.mention_only <value>

export ZEROCLAW_channels__whatsapp__<alias>__mention_only=

zeroclaw config set channels.whatsapp.<alias>.mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__mode=

zeroclaw config set channels.whatsapp.<alias>.pair_code <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_code=

zeroclaw config set channels.whatsapp.<alias>.pair_phone <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_phone=

zeroclaw config set channels.whatsapp.<alias>.passive_group_context <value>

export ZEROCLAW_channels__whatsapp__<alias>__passive_group_context=

zeroclaw config set channels.whatsapp.<alias>.phone_number_id <value>

export ZEROCLAW_channels__whatsapp__<alias>__phone_number_id=

zeroclaw config set channels.whatsapp.<alias>.proxy_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__proxy_url=

zeroclaw config set channels.whatsapp.<alias>.push_name <value>

export ZEROCLAW_channels__whatsapp__<alias>__push_name=

zeroclaw config set channels.whatsapp.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_min_interval_secs=

zeroclaw config set channels.whatsapp.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_queue_depth_max=

zeroclaw config set channels.whatsapp.<alias>.self_chat_mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__self_chat_mode=

zeroclaw config set channels.whatsapp.<alias>.session_path <value>

export ZEROCLAW_channels__whatsapp__<alias>__session_path=

zeroclaw config set channels.whatsapp.<alias>.verify_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__whatsapp__<alias>__verify_token=

zeroclaw config set channels.whatsapp.<alias>.ws_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__ws_url=

channels.whatsapp.<alias>.access_token はシークレットです。 暗号化して保存され、平文の config.toml には保存されません。書き込み時に暗号化される以下のいずれかの方法で設定してください:

zeroclaw config set channels.whatsapp.<alias>.access_token    # マスク入力のプロンプトを表示し、暗号化して保存

同じことが verify_token と app_secret（Cloud API）にも当てはまります。

開始と確認

1つのモードを設定したら、チャンネルランナーを起動します:

zeroclaw channel start

まず最初のチェックとして zeroclaw channel doctor を使用してください。Web モードの場合は、バイナリが whatsapp-web でビルドされていることも確認してください。Cloud API モードの場合は、Webhook トンネルと Meta の verify token が一致していることを確認してください。