WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

インストール (必要時)

• オンボーディング (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

winget install --id Git.Git -e

​

クイックセットアップ

{
  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 フックとプライバシー

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

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

​

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

​

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

• セルフチャットのターンでは既読通知をスキップ
• 自分自身に 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,
        },
      },
    },
  },
}

​

配信、分割、メディア

​

返信引用

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

​

リアクションレベル

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

​

確認リアクション

{
  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

​

システムプロンプト

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

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

• 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.
            "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

• アクセス: 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

​

関連

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