WhatsApp

Status: WhatsApp Web（Baileys）経由で本番利用可能。Gateway がリンク済みセッションを管理します。独立した Twilio WhatsApp チャンネルはありません。

インストール

openclaw onboard と openclaw channels add --channel whatsapp では、初めて選択したときに Plugin のインストールを求められます。Plugin がない場合、openclaw channels login --channel whatsapp でも同じインストールフローが提示されます。開発用チェックアウトではローカル Plugin パスを使用します。stable/beta では、まず ClawHub から @openclaw/whatsapp をインストールし、失敗した場合は npm にフォールバックします。WhatsApp ランタイムは OpenClaw のコア npm パッケージとは別に提供されるため、ランタイム依存関係は外部 Plugin 側に保持されます。手動でインストールするには、次を実行します。

openclaw plugins install clawhub:@openclaw/whatsapp

裸の npm パッケージ（@openclaw/whatsapp）はレジストリへのフォールバックにのみ使用してください。再現可能なインストールが必要な場合に限り、正確なバージョンを固定してください。

クイックセットアップ

{channels: {whatsapp: {  dmPolicy: "pairing",  allowFrom: ["+15551234567"],  groupPolicy: "allowlist",  groupAllowFrom: ["+15551234567"],},},}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

デプロイパターン

{  channels: {    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15551234567"],    },  },}

ランタイムモデル

• Gateway が WhatsApp ソケットと再接続ループを管理します。
• ウォッチドッグは、WhatsApp Web の生のトランスポートアクティビティと、アプリケーションメッセージのアクティビティという 2 つのシグナルを個別に追跡します。接続中だが通信が少ないセッションは、最近メッセージを受信していないという理由だけでは再起動されません。一定の内部時間枠（ユーザーによる設定不可）にわたってトランスポートフレームが届かなくなった場合、または通常のメッセージタイムアウトの 4x を超えてアプリケーションメッセージが届かない場合にのみ、強制的に再接続します。最近アクティブだったセッションを再接続した直後は、最初の時間枠に 4x の時間枠ではなく、より短い通常のメッセージタイムアウトを使用します。OpenClaw は、その再接続時に Baileys が早期に配信するオフラインメッセージへ自動返信できます。対象範囲は受信メッセージ ID の重複排除期間によって制限されます。初回起動時には、短い古い履歴ガードが維持されます。
• 送信には、対象アカウントのアクティブな WhatsApp リスナーが必要です。存在しない場合は即座に失敗します。
• グループ送信では、トークンが現在の参加者メタデータと一致する場合、@+<digits> および @<digits> トークン（テキストとメディアのキャプション内）にネイティブのメンションメタデータを付加します。LID ベースのグループも対象です。
• ステータスチャットとブロードキャストチャット（@status、@broadcast）は無視されます。
• ダイレクトチャットには DM セッションルールを使用します（session.dmScope。デフォルトの main では、DM をエージェントのメインセッションに統合します）。グループセッションは JID ごとに分離されます（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters は、ネイティブの @newsletter JID を使用して、明示的な送信先に指定できます。この場合、DM のセマンティクスではなく、チャンネルセッションのメタデータ（agent:<agentId>:whatsapp:channel:<jid>）を使用します。
• WhatsApp Web トランスポートは、Gateway ホストの標準プロキシ環境変数（HTTPS_PROXY、HTTP_PROXY、NO_PROXY、および小文字のバリアント）に従います。チャンネルごとの設定よりも、ホストレベルのプロキシ設定を推奨します。

MeowCaller で現在のリクエスト元に電話する（実験的）

Plugin は、WhatsApp から開始されたエージェントターンで whatsapp_call を公開できます。MeowCaller を使用して、現在承認されているリクエスト元に WhatsApp 音声通話を発信し、相手が応答した後に OpenClaw の TTS メッセージを再生します。このツールには宛先番号のパラメータがないため、プロンプトによって通話先を変更することはできません。デフォルトでは無効です。

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

制限: 1 対 1 の音声発信のみ、任意の宛先番号は不可、チャット接続との認証共有は不可、個人番号または自分宛てチャットのモードからの自分自身への通話は不可、合成音声は最大 60 seconds、MeowCaller による応答、再生、切断の完了以外に受話器側で聞こえたことを示す受信確認はありません。また、OpenClaw は 115-175 second の制限時間後にコンパニオンプロセスを停止します。この時間枠には、MeowCaller の接続、応答、再生、シャットダウンの各フェーズが含まれます。

承認プロンプト

WhatsApp は、exec および Plugin の承認プロンプトを 👍/👎 リアクションとして表示できます。これはトップレベルの承認転送設定で制御されます。

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec と approvals.plugin は独立しています。WhatsApp をチャンネルとして有効にしても、トランスポートがリンクされるだけです。対応する承認種別が有効化され、WhatsApp にルーティングされていない限り、何も送信されません。セッションモードでは、WhatsApp から発生した承認に限り、ネイティブの絵文字承認を配信します。ターゲットモードでは、明示的なターゲットに対して共有転送パイプラインを使用し、承認者 DM への個別のファンアウトは作成しません。

WhatsApp の承認リアクションには、allowFrom（または "*"）で承認者を明示的に指定する必要があります。defaultTo は通常のデフォルトメッセージ送信先を設定するものであり、承認者リストではありません。手動の /approve コマンドも、承認を解決する前に通常の WhatsApp 送信者認可フローを通過します。

質問へのリアクション

非機密の単一選択質問が 1 つあり、選択肢が 1〜4 個ある ask_user プロンプトでは、WhatsApp は選択肢ラベルの横に 1️⃣ から 4️⃣ を表示します。配信されたプロンプトに対応する番号でリアクションすると回答できます。OpenClaw は Gateway を通じて、その番号を正規の選択肢に対応付けます。期限切れまたは重複したタップは無視されます。複数質問、複数選択、自由入力のプロンプトは、引き続きテキスト返信のみです。通常の WhatsApp DM/グループ参加ルールによって、リアクションした送信者が認可されます。

Plugin フックとプライバシー

WhatsApp の受信メッセージには、個人的な内容、電話番号、グループ識別子、送信者名、セッション相関フィールドが含まれる場合があります。オプトインしない限り、WhatsApp は受信した message_received フックのペイロードを Plugin にブロードキャストしません。

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

オプトインの範囲を channels.whatsapp.accounts.<id>.pluginHooks.messageReceived 配下の 1 つのアカウントに限定してください。WhatsApp の受信内容と識別子を信頼して預けられる Plugin に対してのみ有効にしてください。

アクセス制御と有効化

設定済み ACP バインディング

WhatsApp は、トップレベルの bindings[] による永続的な ACP バインディングをサポートします:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

ダイレクトチャットは E.164 番号と照合され、グループは WhatsApp グループ JID と照合されます。グループ許可リスト、送信者ポリシー、およびメンション/アクティベーションのゲート処理は、OpenClaw がバインドされた ACP セッションの存在を確保する前に実行されます。一致したバインディングがそのルートを所有します。ブロードキャストグループが、そのターンを通常の WhatsApp セッションへファンアウトすることはありません。

個人番号とセルフチャットの動作

リンク済みの自己番号が allowFrom にも含まれている場合、セルフチャットの安全策が有効になります。セルフチャットのターンでは既読通知をスキップし、自分自身に通知してしまうメンション JID の自動トリガー動作を無視し、チャンネル/アカウントの responsePrefix が未設定の場合は返信先をデフォルトで [{identity.name}]（または [openclaw]）にします。

メッセージの正規化とコンテキスト

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

配信、チャンク分割、メディア

返信の引用

channels.whatsapp.replyToMode は、ネイティブの返信引用（送信返信で受信メッセージを視覚的に引用する機能）を制御します:

アカウントごとのオーバーライド: channels.whatsapp.accounts.<id>.replyToMode。

{ channels: { whatsapp: { replyToMode: "first" } } }

リアクションレベル

channels.whatsapp.reactionLevel は、エージェントが絵文字リアクションを使用する範囲を制御します:

アカウントごとのオーバーライド: channels.whatsapp.accounts.<id>.reactionLevel。

{ channels: { whatsapp: { reactionLevel: "ack" } } }

確認リアクション

channels.whatsapp.ackReaction は、受信時に即座にリアクションを送信します。これは reactionLevel によって制御されます（"off" の場合は抑止されます）:

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

注意: 受信が受理された直後（返信前）に送信されます。emoji なしで ackReaction が存在する場合、WhatsApp はルーティングされたエージェントの ID 絵文字を使用し、なければ「👀」にフォールバックします（確認リアクションを使用しない場合は ackReaction を省略するか、emoji: "" を設定します）。失敗はログに記録されますが、返信の配信はブロックされません。グループモードの mentions はメンションによってトリガーされたターンにのみリアクションしますが、グループアクティベーションの always はこのチェックをバイパスします。WhatsApp では channels.whatsapp.ackReaction のみが使用されます（従来の messages.ackReaction はここでは適用されません）。

ライフサイクル状態リアクション

messages.statusReactions.enabled: true を設定すると、WhatsApp はターン中に静的な受信絵文字を残す代わりに確認リアクションを置き換え、キュー待ち、思考中、ツール実行、Compaction、完了、エラーなどの状態を順に表示します:

{  messages: {    statusReactions: {      enabled: true,    },  },}

注意: channels.whatsapp.ackReaction は引き続きダイレクトメッセージとグループの適格性を制御します。キュー待ち状態では、通常の確認リアクションと同じ有効な絵文字が使用されます。WhatsApp ではメッセージごとにボット用のリアクションスロットが 1 つだけなので、ライフサイクルの更新は現在のリアクションをその場で置き換え、最終的な完了/エラー状態の後に確認リアクションを復元します。

複数アカウントと認証情報

ツール、アクション、設定の書き込み

• エージェントツールのサポートには、WhatsApp のリアクションアクション（react）が含まれます。
• アクションゲート: channels.whatsapp.actions.reactions、channels.whatsapp.actions.polls（既存のアクションのデフォルトは true）、channels.whatsapp.actions.calls（デフォルトは false。上記の MeowCaller を参照）。
• チャンネルから開始される設定の書き込みはデフォルトで有効です。無効にするには channels.whatsapp.configWrites: false を使用します。

トラブルシューティング

openclaw channels login --channel whatsappopenclaw channels status

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

システムプロンプト

WhatsApp は、groups および direct のマップを介して、グループとダイレクトチャット向けの Telegram 形式のシステムプロンプトをサポートします。

グループメッセージの解決: まず、有効な groups マップが決定されます。アカウントが独自の groups キーを定義している場合、その内容にかかわらず、ルートの groups マップを完全に置き換えます（ディープマージは行われません）。その後、プロンプトの検索は、結果として得られた単一のマップに対して実行されます。

1. グループ固有のプロンプト（groups["<groupId>"].systemPrompt）: グループのエントリが存在し、かつその systemPrompt キーが定義されている場合に使用されます。空文字列（""）を指定するとワイルドカードが抑制され、プロンプトは適用されません。
2. グループのワイルドカードプロンプト（groups["*"].systemPrompt）: 特定のグループエントリが存在しない場合、または存在していても systemPrompt キーがない場合に使用されます。

ダイレクトメッセージの解決では、direct マップと direct["*"] に対して同一のパターンが適用されます。

Telegram との違い: Telegram は、複数アカウント構成におけるすべてのアカウントで、ルートの groups を抑制します（独自の groups を持たないアカウントも含みます）。これは、Bot が所属していないグループのグループメッセージを受信することを防ぐためです。WhatsApp はこのガードを適用しません。アカウント数にかかわらず、独自の上書きを持たないすべてのアカウントは、ルートの groups／direct を継承します。複数アカウントの WhatsApp 構成でアカウントごとのプロンプトを使用する場合は、各アカウントの下に完全なマップを明示的に定義してください。

重要な動作:

• channels.whatsapp.groups は、グループごとの設定マップであると同時に、チャットレベルのグループ許可リストでもあります。ルートまたはアカウントのいずれのスコープでも、groups["*"] は、そのスコープで「すべてのグループを許可する」ことを意味します。
• そのスコープですべてのグループを許可する必要がある場合にのみ、ワイルドカード systemPrompt を追加してください。対象を固定されたグループ ID のセットのみに限定するには、groups["*"] を使用せず、明示的に許可リストへ追加した各エントリでプロンプトを繰り返し指定します。
• グループの許可と送信者の認可は別々に確認されます。groups["*"] は、グループ処理に到達できるグループの範囲を広げますが、それらのグループ内のすべての送信者を認可するものではありません。送信者の認可は引き続き groupPolicy／groupAllowFrom で管理されます。
• channels.whatsapp.direct には、DM に対する同等の副作用はありません。direct["*"] は、DM が dmPolicy と allowFrom、またはペアリングストアのルールによってすでに許可された後にのみ、デフォルト設定を提供します。

例:

{  channels: {    whatsapp: {      groups: {        // ルートスコープですべてのグループを許可する場合にのみ使用します。        // 独自の groups マップを定義していないすべてのアカウントに適用されます。        "*": { systemPrompt: "すべてのグループ向けのデフォルトプロンプト。" },      },      direct: {        // 独自の direct マップを定義していないすべてのアカウントに適用されます。        "*": { systemPrompt: "すべてのダイレクトチャット向けのデフォルトプロンプト。" },      },      accounts: {        work: {          groups: {            // このアカウントは独自の groups を定義しているため、ルートの groups は完全に            // 置き換えられます。ワイルドカードを維持するには、ここでも "*" を明示的に定義します。            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "プロジェクト管理に集中する。",            },            // このアカウントですべてのグループを許可する場合にのみ使用します。            "*": { systemPrompt: "仕事用グループ向けのデフォルトプロンプト。" },          },          direct: {            // このアカウントは独自の direct マップを定義しているため、ルートの direct エントリは            // 完全に置き換えられます。ワイルドカードを維持するには、ここでも "*" を明示的に定義します。            "+15551234567": { systemPrompt: "特定の仕事用ダイレクトチャット向けのプロンプト。" },            "*": { systemPrompt: "仕事用ダイレクトチャット向けのデフォルトプロンプト。" },          },        },      },    },  },}

設定リファレンスへのポインター

主要なリファレンス: 設定リファレンス - WhatsApp

関連項目

• ペアリング
• グループ
• セキュリティ
• チャンネルルーティング
• マルチエージェントルーティング
• トラブルシューティング