​

WhatsApp（Web チャンネル）

​

インストール（必要時）

• オンボーディング（openclaw onboard）と openclaw channels add --channel whatsapp では、初めて WhatsApp plugin を選択したときにインストールを促します。
• openclaw channels login --channel whatsapp でも、plugin がまだ存在しない場合は インストールフローが提供されます。
• 開発チャンネル + git checkout: デフォルトでローカル plugin パスを使用します。
• Stable/Beta: デフォルトで npm package @openclaw/whatsapp を使用します。

openclaw plugins install @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 gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

デプロイパターン

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

​

ランタイムモデル

• Gateway が WhatsApp socket と再接続ループを管理します。
• 外向き送信には、対象アカウントに対するアクティブな WhatsApp listener が必要です。
• ステータスチャットとブロードキャストチャットは無視されます（@status, @broadcast）。
• ダイレクトチャットは DM session ルール（session.dmScope）を使用します。デフォルトの main では DM は agent の main session に集約されます。
• グループセッションは分離されます（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Web transport は Gateway host 上の標準 proxy 環境変数（HTTPS_PROXY, HTTP_PROXY, NO_PROXY / 小文字版）を尊重します。チャンネル固有の WhatsApp proxy 設定よりも host レベルの proxy 設定を推奨します。

​

アクセス制御と有効化

​

個人番号と self-chat の動作

• self-chat ターンでは既読通知をスキップします
• 本来なら自分自身を ping してしまう mention-JID 自動トリガー動作を無視します
• messages.responsePrefix が未設定の場合、self-chat 返信のデフォルトは [{identity.name}] または [openclaw] になります

​

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

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

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

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

​

配信、chunking、media

​

Reaction level

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

​

Acknowledgment reaction

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

• 受信が受理された直後に送信されます（返信前）
• 失敗はログに記録されますが、通常の返信配信は妨げません
• グループモード mentions は mention によってトリガーされたターンで reaction します。グループ activation の always はこのチェックのバイパスとして機能します
• WhatsApp は channels.whatsapp.ackReaction を使用します（レガシーの messages.ackReaction はここでは使われません）

​

マルチアカウントと認証情報

​

Tools、actions、および config 書き込み

• agent tool サポートには WhatsApp reaction action（react）が含まれます。
• Action ゲート:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• チャンネル起点の config 書き込みはデフォルトで有効です（channels.whatsapp.configWrites=false で無効化）。

​

トラブルシューティング

openclaw channels login --channel whatsapp
openclaw channels status

openclaw doctor
openclaw logs --follow

​

System prompt

1. グループ固有の system prompt（groups["<groupId>"].systemPrompt）: 特定のグループエントリが systemPrompt を定義している場合に使用されます。
2. グループ wildcard system prompt（groups["*"].systemPrompt）: 特定のグループエントリが存在しないか、systemPrompt を定義していない場合に使用されます。

1. ダイレクト固有の system prompt（direct["<peerId>"].systemPrompt）: 特定の peer エントリが systemPrompt を定義している場合に使用されます。
2. ダイレクト wildcard system prompt（direct["*"].systemPrompt）: 特定の peer エントリが存在しないか、systemPrompt を定義していない場合に使用されます。

• channels.whatsapp.groups は、グループごとの config マップであると同時に、チャットレベルのグループ allowlist でもあります。ルートまたはアカウントスコープのいずれでも、groups["*"] はそのスコープに対して「すべてのグループを受け入れる」ことを意味します。
• wildcard グループ systemPrompt は、そのスコープですでにすべてのグループを受け入れたい場合にのみ追加してください。引き続き固定のグループ ID のみを対象にしたい場合は、prompt のデフォルトとして groups["*"] を使用しないでください。代わりに、明示的に allowlist した各グループエントリに prompt を繰り返し設定してください。
• グループ受け入れと送信者認可は別のチェックです。groups["*"] はグループ処理に到達できるグループの集合を広げますが、それ自体でそれらのグループ内のすべての送信者を認可するわけではありません。送信者アクセスは、引き続き channels.whatsapp.groupPolicy と channels.whatsapp.groupAllowFrom によって個別に制御されます。
• channels.whatsapp.direct には DM に対して同じ副作用はありません。direct["*"] は、DM が dmPolicy と allowFrom または pairing-store ルールによってすでに受け入れられた後にのみ、デフォルトのダイレクトチャット config を提供します。

{
  channels: {
    whatsapp: {
      groups: {
        // ルートスコープですべてのグループを受け入れるべき場合にのみ使用します。
        // 独自の groups マップを定義していないすべてのアカウントに適用されます。
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // 独自の direct マップを定義していないすべてのアカウントに適用されます。
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // このアカウントは独自の groups を定義しているため、ルート groups は完全に
            // 置き換えられます。wildcard を維持したい場合は、ここでも明示的に "*" を定義してください。
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // このアカウントですべてのグループを受け入れるべき場合にのみ使用します。
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // このアカウントは独自の direct マップを定義しているため、ルート direct エントリは
            // 完全に置き換えられます。wildcard を維持したい場合は、ここでも明示的に "*" を定義してください。
            "+15551234567": { systemPrompt: "特定の仕事用ダイレクトチャット向けの prompt。" },
            "*": { systemPrompt: "仕事用ダイレクトチャットのデフォルト prompt。" },
          },
        },
      },
    },
  },
}

​

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

• Configuration reference - WhatsApp

• アクセス: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• 配信: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• マルチアカウント: accounts.<id>.enabled, accounts.<id>.authDir, アカウントレベルの上書き
• 運用: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• セッション動作: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompt: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

関連

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