WhatsApp

​

インストール

openclaw plugins install clawhub:@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-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 の生のトランスポートアクティビティと、アプリケーションメッセージのアクティビティという 2 つのシグナルを個別に追跡します。接続中だが通信が少ないセッションは、最近メッセージを受信していないという理由だけでは再起動されません。一定の内部時間枠（ユーザーによる設定不可）にわたってトランスポートフレームが届かなくなった場合、または通常のメッセージタイムアウトの 4x を超えてアプリケーションメッセージが届かない場合にのみ、強制的に再接続します。最近アクティブだったセッションを再接続した直後は、最初の時間枠に 4x の時間枠ではなく、より短い通常のメッセージタイムアウトを使用します。OpenClaw は、その再接続時に Baileys が早期に配信するオフラインメッセージへ自動返信できます。対象範囲は受信メッセージ ID の重複排除期間によって制限されます。初回起動時には、短い古い履歴ガードが維持されます。
• 送信には、対象アカウントのアクティブな WhatsApp リスナーが必要です。存在しない場合は即座に失敗します。
• グループ送信では、トークンが現在の参加者メタデータと一致する場合、@+<digits> および @<digits> トークン（テキストとメディアのキャプション内）にネイティブのメンションメタデータを付加します。LID ベースのグループも対象です。
• ステータスチャットとブロードキャストチャット（@status、@broadcast）は無視されます。
• ダイレクトチャットには DM セッションルールを使用します（session.dmScope。デフォルトの main では、DM をエージェントのメインセッションに統合します）。グループセッションは JID ごとに分離されます（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、および小文字のバリアント）に従います。チャンネルごとの設定よりも、ホストレベルのプロキシ設定を推奨します。

​

MeowCaller で現在のリクエスト元に電話する（実験的）

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

​

承認プロンプト

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

質問へのリアクション

​

Plugin フックとプライバシー

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

​

アクセス制御と有効化

​

設定済み 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" },
      },
    },
  ],
}

​

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

​

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

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

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

​

配信、チャンク分割、メディア

​

返信の引用

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

​

リアクションレベル

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

​

確認リアクション

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

​

ライフサイクル状態リアクション

{
  messages: {
    statusReactions: {
      enabled: true,
    },
  },
}

​

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

​

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

• エージェントツールのサポートには、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 whatsapp
openclaw channels status

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

システムプロンプト

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

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

{
  channels: {
    whatsapp: {
      groups: {
        // ルートスコープですべてのグループを許可する場合にのみ使用します。
        // 独自の groups マップを定義していないすべてのアカウントに適用されます。
        "*": { systemPrompt: "すべてのグループ向けのデフォルトプロンプト。" },
      },
      direct: {
        // 独自の direct マップを定義していないすべてのアカウントに適用されます。
        "*": { systemPrompt: "すべてのダイレクトチャット向けのデフォルトプロンプト。" },
      },
      accounts: {
        work: {
          groups: {
            // このアカウントは独自の groups を定義しているため、ルートの groups は完全に
            // 置き換えられます。ワイルドカードを維持するには、ここでも "*" を明示的に定義します。
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "プロジェクト管理に集中する。",
            },
            // このアカウントですべてのグループを許可する場合にのみ使用します。
            "*": { systemPrompt: "仕事用グループ向けのデフォルトプロンプト。" },
          },
          direct: {
            // このアカウントは独自の direct マップを定義しているため、ルートの direct エントリは
            // 完全に置き換えられます。ワイルドカードを維持するには、ここでも "*" を明示的に定義します。
            "+15551234567": { systemPrompt: "特定の仕事用ダイレクトチャット向けのプロンプト。" },
            "*": { systemPrompt: "仕事用ダイレクトチャット向けのデフォルトプロンプト。" },
          },
        },
      },
    },
  },
}

​

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

​

関連項目

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