【最新版】WhatsAppでOpenClawを使う方法（WhatsApp Web連携）

WhatsApp

WhatsApp（Web channel）

ステータス：WhatsApp Web（Baileys）経由で本番運用可能。Gateway がリンクされたセッションを所有します。

• Pairing（未知の送信者の DM はデフォルトでペアリング）： /channels/pairing
• Channel troubleshooting（横断トラブルシュート）： /channels/troubleshooting
• Gateway configuration（設定例）： /gateway/configuration

クイックセットアップ

Step 1：WhatsApp のアクセス制御（ポリシー）を設定

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

Step 2：WhatsApp をリンク（QR）

openclaw channels login --channel whatsapp

特定アカウントを指定する場合：

openclaw channels login --channel whatsapp --account work

Step 3：Gateway を起動

openclaw gateway

Step 4：最初のペアリング要求を承認（pairing mode の場合）

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

ペアリング要求は 1 時間で期限切れになります。保留中の要求は、チャネルあたり最大 3 件までです。

デプロイパターン（Deployment patterns）

Dedicated number（推奨）

運用として最もクリーンなモードです：

• OpenClaw 用に WhatsApp アイデンティティを分離
• DM allowlist とルーティング境界が明確
• 自分宛てチャット（self-chat）混乱の可能性が低い

最小ポリシーパターン：

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

Personal-number fallback（個人番号での運用）

オンボーディングは個人番号モードをサポートし、self-chat しやすいベースラインを書き込みます：

• dmPolicy: "allowlist"
• allowFrom に個人番号が含まれる
• selfChatMode: true

ランタイムでは、リンクされた self number と allowFrom に基づいて self-chat 保護が動きます。

WhatsApp Web-only channel scope

現在の OpenClaw のチャネルアーキテクチャでは、WhatsApp チャネルは WhatsApp Web（Baileys）ベースです。 ビルトインの chat-channel registry に、Twilio の WhatsApp messaging チャネルは別途存在しません。

ランタイムモデル（Runtime model）

• Gateway が WhatsApp ソケットと再接続ループを所有します。
• アウトバウンド送信には、対象アカウントのアクティブな WhatsApp listener が必要です。
• Status と broadcast チャットは無視されます（@status、@broadcast）。
• Direct chats は DM セッションルール（session.dmScope。デフォルト main は DM をエージェントの main セッションへ集約）を使います。
• Group セッションは分離されます（agent:<agentId>:whatsapp:group:<jid>）。

アクセス制御と有効化（Access control and activation）

DM policy

channels.whatsapp.dmPolicy は direct chat のアクセスを制御します：

• pairing（デフォルト）
• allowlist
• open（allowFrom に "*" を含める必要あり）
• disabled

allowFrom は E.164 形式の電話番号を受け付けます（内部で正規化）。

マルチアカウントの上書き：channels.whatsapp.accounts.<id>.dmPolicy（および allowFrom）が、そのアカウントのチャネルデフォルトより優先されます。

ランタイム挙動の詳細：

• ペアリングはチャネル allow-store に永続化され、設定済み allowFrom とマージされます。
• allowlist が未設定の場合、リンクされた self number がデフォルトで許可されます。
• アウトバウンドの fromMe DM は自動でペアリングされません。

Group policy + allowlists

グループアクセスは 2 層です：

1. グループ参加 allowlist（channels.whatsapp.groups）
   • groups を省略すると、すべてのグループが対象になり得ます。
   • groups が存在する場合、グループ allowlist として振る舞います（"*" 可）。
2. グループ送信者ポリシー（channels.whatsapp.groupPolicy + groupAllowFrom）
   • open：送信者 allowlist をバイパス
   • allowlist：送信者は groupAllowFrom（または *）にマッチする必要があります
   • disabled：グループの inbound をすべてブロック

送信者 allowlist のフォールバック：

• groupAllowFrom が未設定の場合、可能ならランタイムは allowFrom にフォールバックします。
• 送信者 allowlist は、mention/reply による activation より先に評価されます。

Note：channels.whatsapp ブロックがまったく存在しない場合、ランタイムの group-policy フォールバックは（警告ログとともに）allowlist になります。 これは channels.defaults.groupPolicy が設定されていても同様です。

Mentions + /activation

グループ返信はデフォルトでメンションが必要です。

メンション検出には次が含まれます：

• ボット identity への明示的な WhatsApp メンション
• 設定された mention 正規表現パターン（agents.list[].groupChat.mentionPatterns、フォールバック：messages.groupChat.mentionPatterns）
• reply-to-bot の暗黙検出（reply の送信者が bot identity に一致）

Security note:

• 引用/返信（quote/reply）はメンションゲートを満たすだけで、送信者の認可を付与しません。
• groupPolicy: "allowlist" の場合、allowlist 外の送信者は、allowlist 内ユーザーのメッセージに返信してもブロックされます。

セッション単位の activation コマンド：

• /activation mention
• /activation always

activation はセッション状態を更新します（グローバル設定ではありません）。owner-gated です。

個人番号と self-chat の挙動（Personal-number and self-chat behavior）

リンクされた self number が allowFrom にも含まれている場合、WhatsApp self-chat の安全策が有効になります：

• self-chat ターンでは既読（read receipts）をスキップ
• 本来は自分を ping しうる mention-JID の自動トリガー挙動を無視
• messages.responsePrefix が未設定の場合、self-chat の返信はデフォルトで [{identity.name}] または [openclaw]

メッセージ正規化とコンテキスト（Message normalization and context）

Inbound envelope + reply context

受信した WhatsApp メッセージは共通の inbound envelope にラップされます。

quoted reply が存在する場合、コンテキストは次の形式で追記されます：

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

可能な場合、reply メタデータフィールド（ReplyToId、ReplyToBody、ReplyToSender、sender の JID/E.164）も設定されます。

Media placeholders と location/contact 抽出

メディアのみの受信メッセージは、次のようなプレースホルダーで正規化されます：

• <media:image>
• <media:video>
• <media:audio>
• <media:document>
• <media:sticker>

Location と contact のペイロードは、ルーティング前にテキストコンテキストへ正規化されます。

Pending group history injection

グループでは、ボットがトリガーされるまで未処理メッセージをバッファし、トリガー時にコンテキストとして注入できます。

• デフォルト上限：50
• config：channels.whatsapp.historyLimit
• フォールバック：messages.groupChat.historyLimit
• 0 で無効化

注入マーカー：

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

Read receipts（既読）

既読は、受理された inbound WhatsApp メッセージに対してデフォルトで有効です。

全体で無効化：

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

アカウント単位の上書き：

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

self-chat ターンは、全体で有効でも既読をスキップします。

配信、分割、メディア（Delivery, chunking, and media）

Text chunking

• デフォルト chunk 上限：channels.whatsapp.textChunkLimit = 4000
• channels.whatsapp.chunkMode = "length" | "newline"
• newline は段落境界（空行）を優先し、その後 length-safe chunking にフォールバックします。

Outbound media behavior

• image / video / audio（PTT voice-note）/ document をサポート
• voice-note 互換のため、audio/ogg は audio/ogg; codecs=opus に書き換えられます
• 動画送信時に gifPlayback: true を指定するとアニメ GIF 再生をサポート
• マルチメディア返信を送る場合、caption は最初のメディア item に適用されます
• メディア source は HTTP(S)、file://、またはローカルパスを指定できます

Media size limits とフォールバック

• inbound 保存上限：channels.whatsapp.mediaMaxMb（デフォルト 50）
• outbound 送信上限：channels.whatsapp.mediaMaxMb（デフォルト 50）
• アカウント単位の上書き：channels.whatsapp.accounts.<accountId>.mediaMaxMb
• 画像は上限に収めるため自動最適化（リサイズ/品質スイープ）されます
• メディア送信が失敗した場合、先頭 item のフォールバックとして、レスポンスを黙って捨てずテキスト警告を送ります

ACK リアクション（Acknowledgment reactions）

WhatsApp は、受信（inbound receipt）に対して即時の ack リアクションを channels.whatsapp.ackReaction でサポートします。

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

挙動メモ：

• inbound が受理された直後（返信前）に送信されます
• 失敗はログに出ますが、通常の返信配信をブロックしません
• group mode mentions は、メンションでトリガーされたターンにリアクションします。group activation always はこのチェックをバイパスする扱いです
• WhatsApp は channels.whatsapp.ackReaction を使用します（レガシーの messages.ackReaction はここでは使いません）

マルチアカウントと認証情報（Multi-account and credentials）

アカウント選択とデフォルト

• account id は channels.whatsapp.accounts から取得されます
• デフォルトアカウント選択：default があればそれ、なければ（ソートされた）最初の account id
• account id は内部で正規化され、lookup に使われます

credential path とレガシー互換

• 現在の auth path：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• バックアップファイル：creds.json.bak
• レガシーのデフォルト auth（~/.openclaw/credentials/）も認識され、default-account のフローではマイグレーションされます

Logout の挙動

openclaw channels logout --channel whatsapp [--account <id>] は、そのアカウントの WhatsApp auth state を消去します。

レガシー auth ディレクトリでは、oauth.json は保持され、Baileys auth ファイルは削除されます。

ツール、アクション、config writes（Tools, actions, and config writes）

• エージェントのツールは WhatsApp の reaction action（react）をサポートします。
• Action gate：channels.whatsapp.actions.reactions / channels.whatsapp.actions.polls
• チャネル主導の config 書き込みはデフォルトで有効です（channels.whatsapp.configWrites=false で無効化）。

トラブルシューティング

Not linked（QR が必要）

症状：channel status が not linked を報告する。

対処：

openclaw channels login --channel whatsapp
openclaw channels status

Linked but disconnected / reconnect loop

症状：リンク済みアカウントが、切断/再接続を繰り返す。

対処：

openclaw doctor
openclaw logs --follow

必要なら channels login で再リンクします。

No active listener when sending

アウトバウンド送信は、対象アカウントのアクティブな gateway listener が存在しない場合に即座に失敗します。Gateway が動いていて、アカウントがリンク済みであることを確認してください。

Group messages unexpectedly ignored

次の順に確認します：

• groupPolicy
• groupAllowFrom / allowFrom
• groups allowlist エントリ
• mention gating（requireMention + mention patterns）
• openclaw.json（JSON5）内の重複キー：後勝ちで上書きされるため、各スコープで groupPolicy は 1 つに保つ

Bun runtime warning

WhatsApp gateway runtime は Node を使用してください。Bun は安定した WhatsApp/Telegram gateway 運用と互換性がないとしてフラグされます。

Configuration reference pointers

Primary reference：

• Configuration reference - WhatsApp

High-signal WhatsApp fields：

• access：dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• delivery：textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• multi-account：accounts.<id>.enabled, accounts.<id>.authDir, account-level overrides
• operations：configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• session behavior：session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting

参考

• https://docs.openclaw.ai/channels/whatsapp.md