WhatsApp

ステータス: WhatsApp Web (Baileys) 経由で本番対応済み。Gateway がリンク済みセッションを所有します。

# インストール (必要時)

• オンボーディング (openclaw onboard) と openclaw channels add --channel whatsapp は、 初めて WhatsApp plugin を選択したときにインストールを促します。
• openclaw channels login --channel whatsapp も、plugin がまだ存在しない場合は インストールフローを提示します。
• 開発チャンネル + git checkout: デフォルトでローカル plugin パスを使用します。
• Stable/Beta: 現在の公式リリースタグの npm パッケージ @openclaw/whatsapp を使用します。

手動インストールも引き続き利用できます。

openclaw plugins install @openclaw/whatsapp

現在の公式リリースタグに追従するには、素のパッケージを使用します。再現可能なインストールが必要な場合にのみ、正確な バージョンを固定してください。

Windows では、WhatsApp plugin は npm install 中に PATH 上の Git を必要とします。これは Baileys/libsignal 依存関係の 1 つが git URL から取得されるためです。Git for Windows をインストールしてから、シェルを再起動し、インストールを再実行します。

winget install --id Git.Git -e

Portable Git も、その bin ディレクトリが PATH 上にあれば動作します。

# クイックセットアップ

{
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-auth
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 ソケットと再接続ループを所有します。
• 再接続ウォッチドッグは、受信アプリメッセージ量だけでなく WhatsApp Web トランスポート活動を使用するため、静かなリンク済みデバイスセッションは、最近誰もメッセージを送信していないという理由だけでは再起動されません。トランスポートフレームは到着し続けているが、ウォッチドッグ期間中にアプリケーションメッセージが処理されない場合は、より長いアプリケーション沈黙上限により引き続き再接続が強制されます。最近アクティブだったセッションの一時的な再接続後は、そのアプリケーション沈黙チェックは最初の復旧期間に通常のメッセージタイムアウトを使用します。
• Baileys ソケットタイミングは web.whatsapp.* 配下で明示されています: keepAliveIntervalMs は WhatsApp Web アプリケーション ping を制御し、connectTimeoutMs は開始ハンドシェイクのタイムアウトを制御し、defaultQueryTimeoutMs は Baileys クエリタイムアウトを制御します。
• 送信には、対象アカウントのアクティブな WhatsApp リスナーが必要です。
• グループ送信では、テキストおよびメディアキャプション内の @+<digits> と @<digits> トークンが、LID ベースのグループを含む現在の WhatsApp 参加者メタデータに一致する場合、ネイティブのメンションメタデータを付与します。
• ステータスとブロードキャストチャットは無視されます (@status, @broadcast)。
• 再接続ウォッチドッグは、受信アプリメッセージ量だけでなく WhatsApp Web トランスポート活動に従います。静かなリンク済みデバイスセッションはトランスポートフレームが継続している間は維持されますが、トランスポート停止は後続のリモート切断パスよりかなり前に再接続を強制します。
• ダイレクトチャットは DM セッションルールを使用します (session.dmScope; デフォルトの main は DM をエージェントのメインセッションに集約します)。
• グループセッションは分離されます (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 / 小文字バリアント) を尊重します。チャンネル固有の WhatsApp プロキシ設定よりも、ホストレベルのプロキシ設定を優先してください。
• messages.removeAckAfterReply が有効な場合、OpenClaw は表示される返信が配信された後に WhatsApp の ack リアクションをクリアします。

# Plugin フックとプライバシー

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

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

オプトインは 1 つのアカウントにスコープできます。

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

受信 WhatsApp メッセージの内容と識別子を受け取ることを信頼できる plugins に対してのみ、これを有効にしてください。

# アクセス制御とアクティベーション

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

リンク済みの自分の番号が allowFrom にも存在する場合、WhatsApp のセルフチャット保護が有効になります。

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

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

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

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

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

# 配信、分割、メディア

# 返信引用

WhatsApp はネイティブの返信引用をサポートしており、送信返信で受信メッセージを視覚的に引用できます。channels.whatsapp.replyToMode で制御します。

デフォルトは "off" です。アカウントごとの上書きには channels.whatsapp.accounts.<id>.replyToMode を使用します。

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

# リアクションレベル

channels.whatsapp.reactionLevel は、エージェントが WhatsApp で絵文字リアクションをどの程度広く使用するかを制御します。

デフォルト: "minimal"。

アカウントごとの上書きには channels.whatsapp.accounts.<id>.reactionLevel を使用します。

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

# 確認リアクション

WhatsApp は、channels.whatsapp.ackReaction により、受信時の即時 ack リアクションをサポートします。 Ack リアクションは reactionLevel によって制御されます。reactionLevel が "off" の場合は抑制されます。

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

動作メモ:

• 受信が受け入れられた直後に送信されます（返信前）
• 失敗はログに記録されますが、通常の返信配信はブロックしません
• グループモード mentions はメンションでトリガーされたターンにリアクションします。グループ有効化 always はこのチェックのバイパスとして機能します
• WhatsApp は channels.whatsapp.ackReaction を使用します（レガシーの messages.ackReaction はここでは使用されません）

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

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

• エージェントツールのサポートには WhatsApp リアクションアクション（react）が含まれます。
• アクションゲート:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• チャネル開始の設定書き込みはデフォルトで有効です（channels.whatsapp.configWrites=false で無効化）。

# トラブルシューティング

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# システムプロンプト

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

グループメッセージの解決階層:

有効な groups マップが最初に決定されます。アカウントが独自の groups を定義している場合、それはルートの groups マップを完全に置き換えます（ディープマージなし）。その後、プロンプト検索は結果として得られた単一のマップ上で実行されます。

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

ダイレクトメッセージの解決階層:

有効な direct マップが最初に決定されます。アカウントが独自の direct を定義している場合、それはルートの direct マップを完全に置き換えます（ディープマージなし）。その後、プロンプト検索は結果として得られた単一のマップ上で実行されます。

1. Direct 固有のシステムプロンプト (direct["<peerId>"].systemPrompt): マップ内に特定のピアエントリが存在し、かつその systemPrompt キーが定義されている場合に使用されます。systemPrompt が空文字列 ("") の場合、ワイルドカードは抑制され、システムプロンプトは適用されません。
2. Direct ワイルドカードシステムプロンプト (direct["*"].systemPrompt): 特定のピアエントリがマップにまったく存在しない場合、または存在していても systemPrompt キーを定義していない場合に使用されます。

Telegram のマルチアカウント動作との違い: Telegram では、マルチアカウント設定内のすべてのアカウントについて、ルートの groups が意図的に抑制されます。自分の groups を定義していないアカウントでも同様です。これは、ボットが所属していないグループのグループメッセージを受信しないようにするためです。WhatsApp ではこの保護は適用されません。ルートの groups とルートの direct は、構成されているアカウント数に関係なく、アカウントレベルのオーバーライドを定義していないアカウントに常に継承されます。マルチアカウントの WhatsApp 設定で、アカウントごとのグループプロンプトまたは Direct プロンプトを使いたい場合は、ルートレベルのデフォルトに依存せず、各アカウント配下に完全なマップを明示的に定義してください。

重要な動作:

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

例:

{
  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.
            "[email protected]": {
              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

重要な 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.*, web.whatsapp.*
• セッション動作: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• プロンプト: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# 関連

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