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 つのシグナルを個別に追跡します。静かだが接続中のセッションは、最近メッセージが到着していないという理由だけでは再起動されません。トランスポートフレームが固定の内部ウィンドウ (ユーザー設定不可) の間到着しなくなった場合、またはアプリケーションメッセージが通常のメッセージタイムアウトの 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 Channels/Newsletters は、DM セマンティクスではなくチャネルセッションメタデータ (agent:<agentId>:whatsapp:channel:<jid>) を使用し、ネイティブの @newsletter JID を通じて明示的な送信先にできます。
• WhatsApp Web トランスポートは Gateway ホスト上の標準プロキシ環境変数 (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, 小文字のバリアント) を尊重します。チャネル単位の設定よりもホストレベルのプロキシ設定を優先してください。
• messages.removeAckAfterReply が有効な場合、OpenClaw は表示可能な返信が配信されると ack リアクションを消去します。

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 は exec および 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 セッションの存在を保証する前に、グループ allowlist、送信者ポリシー、メンション/アクティベーションゲートが実行される。一致したバインディングがルートを所有する。ブロードキャストグループはそのターンを通常の WhatsApp セッションへファンアウトしない。

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

リンク済みの自分の番号が allowFrom にも存在する場合、セルフチャット保護が有効になる。セルフチャットターンの既読通知をスキップし、自分自身に ping してしまうメンション 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 はルーティングされたエージェントの ID 絵文字を使用し、なければ "👀" にフォールバックする（確認なしにするには ackReaction を省略するか emoji: "" を設定する）。失敗はログに記録されるが返信配信はブロックしない。グループモード mentions はメンションでトリガーされたターンでのみリアクションし、グループアクティベーション always はそのチェックをバイパスする。WhatsApp は channels.whatsapp.ackReaction のみを使用する（レガシーの messages.ackReaction はここでは適用されない）。

ライフサイクルステータスリアクション

messages.statusReactions.enabled: true を設定すると、ターン中に静的な受領絵文字を残す代わりに、WhatsApp が Ack リアクションを置き換え、キュー済み、思考中、ツール活動、Compaction、完了、エラーなどの状態を巡回できる:

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

注記: channels.whatsapp.ackReaction は引き続きダイレクトメッセージとグループの適格性を制御する。キュー済み状態は通常の Ack リアクションと同じ有効絵文字を使用する。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 キーを少しでも定義している場合、それはルートの 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: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

設定リファレンスの参照先

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

関連

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