WhatsApp

ステータス: WhatsApp Web (Baileys) 経由で本番環境に対応済み。Gateway がリンク済みセッションを管理し、個別の Twilio WhatsApp チャネルはありません。

インストール

openclaw onboard と openclaw channels add --channel whatsapp では、初めて選択したときに Plugin のインストールを求められます。Plugin がない場合、openclaw channels login --channel whatsapp でも同じインストールフローが提示されます。開発用チェックアウトではローカルの Plugin パスを使用します。安定版/ベータ版では、まず 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 ソケットと再接続ループを管理します。
• ウォッチドッグは 2 つのシグナルを個別に追跡します。生の WhatsApp Web トランスポートアクティビティと、アプリケーションメッセージのアクティビティです。接続中で静かなセッションは、最近メッセージが届いていないという理由だけでは再起動されません。一定の内部時間枠 (ユーザーによる設定不可) にわたってトランスポートフレームが届かない場合、または通常のメッセージタイムアウトの 4 倍を超えてアプリケーションメッセージが届かない場合にのみ、再接続を強制します。最近アクティブだったセッションの再接続直後は、最初の時間枠に 4 倍の時間枠ではなく、より短い通常のメッセージタイムアウトを使用します。OpenClaw は、その再接続の早い段階で Baileys が配信するオフラインメッセージに自動返信できます。その範囲は受信メッセージ ID の重複排除期間によって制限されます。初回起動時は、短い古い履歴のガードが維持されます。
• Baileys ソケットのタイミングは web.whatsapp.* で明示的に設定されます。keepAliveIntervalMs (アプリケーションの ping 間隔)、connectTimeoutMs (接続開始時のハンドシェイクタイムアウト)、defaultQueryTimeoutMs (Baileys のクエリ待機時間、および OpenClaw の送信/プレゼンスと受信開封確認のタイムアウト) です。
• 送信には、対象アカウントでアクティブな WhatsApp リスナーが必要です。存在しない場合は即座に失敗します。
• グループ送信では、@+<digits> および @<digits> トークン (テキストとメディアのキャプション内) が現在の参加者メタデータと一致する場合、LID ベースのグループを含め、ネイティブのメンションメタデータを付加します。
• ステータスチャットとブロードキャストチャット (@status、@broadcast) は無視されます。
• ダイレクトチャットでは DM セッションルールを使用します (session.dmScope。デフォルトの main では DM をエージェントのメインセッションに統合します)。グループセッションは JID ごとに分離されます (agent:<agentId>:whatsapp:group:<jid>)。
• WhatsApp のチャネル/ニュースレターは、ネイティブの @newsletter JID を使用して明示的な送信先にできます。この場合、DM のセマンティクスではなくチャネルセッションのメタデータ (agent:<agentId>:whatsapp:channel:<jid>) を使用します。
• WhatsApp Web トランスポートは、Gateway ホスト上の標準プロキシ環境変数 (HTTPS_PROXY、HTTP_PROXY、NO_PROXY、および小文字のバリアント) に従います。チャネル単位の設定よりも、ホストレベルのプロキシ設定を推奨します。
• messages.removeAckAfterReply が有効な場合、OpenClaw は表示可能な返信が配信されると確認リアクションを消去します。

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 秒、MeowCaller の応答/再生/切断完了以外に端末側で聞こえたことを確認する受領通知はなし、OpenClaw は 115～175 秒の制限時間枠 (MeowCaller の接続、応答、再生、終了フェーズを含む) の経過後に補助プロセスを停止します。

承認プロンプト

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

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

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

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

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 の自動トリガー動作を無視し、messages.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      },    },  },}

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

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

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

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

注：channels.whatsapp.ackReaction は引き続きダイレクトメッセージとグループでの適用可否を制御します。キュー待ち状態では通常の確認リアクションと同じ実効絵文字が使用されます。WhatsApp ではメッセージごとにボットのリアクション枠が 1 つしかないため、ライフサイクル更新は現在のリアクションをその場で置き換えます。messages.removeAckAfterReply: true を設定すると、設定された完了／エラーの保持時間後に最終状態リアクションが消去されます。ツール絵文字のカテゴリには tool、coding、web、deploy、build、concierge が含まれます。

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

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

• エージェントツールでは、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

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

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 キーを1つでも定義している場合、ルートの groups マップを完全に置き換えます（ディープマージは行われません）。その後、プロンプトの検索は、その結果得られた単一のマップに対して実行されます。

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

ダイレクトメッセージの解決方法も、direct マップと direct["*"] に対して同じパターンに従います。

Telegram との違い: Telegram は、複数アカウント構成では、各アカウントに独自の groups がない場合でも、すべてのアカウントに対してルートの groups を抑制します。これは、ボットが所属していないグループのグループメッセージを受信するのを防ぐためです。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

関連項目

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