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 つのシグナルを個別に追跡します。静かだが接続中のセッションは、最近メッセージが到着していないという理由だけでは再起動されません。トランスポートフレームが固定の内部ウィンドウ (ユーザー設定不可) の間到着しなくなった場合、またはアプリケーションメッセージが通常のメッセージタイムアウトの 4 倍を超えて無音のままの場合にのみ、再接続を強制します。最近アクティブだったセッションの再接続直後は、その最初のウィンドウで 4 倍ウィンドウではなく短い通常のメッセージタイムアウトを使用します。OpenClaw は、その再接続の早い段階で Baileys が配信するオフラインメッセージに自動返信できます。これは受信メッセージ ID の重複排除有効期間に制限されます。初回起動では短い古い履歴ガードを維持します。
• Baileys ソケットのタイミングは web.whatsapp.* の下で明示されます: keepAliveIntervalMs (アプリケーション ping 間隔)、connectTimeoutMs (開始ハンドシェイクタイムアウト)、defaultQueryTimeoutMs (Baileys クエリ待機に加え、OpenClaw の送信/プレゼンスおよび受信既読確認タイムアウト)。
• 送信には対象アカウントのアクティブな WhatsApp リスナーが必要です。そうでない場合、送信は即座に失敗します。
• グループ送信では、トークンが現在の参加者メタデータと一致する場合、@+<digits> と @<digits> トークン (テキストとメディアキャプション内) にネイティブのメンションメタデータを付与します。LID ベースのグループも含まれます。
• ステータスおよびブロードキャストチャット (@status, @broadcast) は無視されます。
• ダイレクトチャットは DM セッションルール (session.dmScope; 既定の main は DM をエージェントのメインセッションにまとめます) を使用します。グループセッションは JID ごとに分離されます (agent:<agentId>:whatsapp:group:<jid>)。
• WhatsApp Channels/Newsletters は、DM セマンティクスではなくチャネルセッションメタデータ (agent:<agentId>:whatsapp:channel:<jid>) を使用し、ネイティブの @newsletter JID を通じて明示的な送信先にできます。
• WhatsApp Web トランスポートは Gateway ホスト上の標準プロキシ環境変数 (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, 小文字のバリアント) を尊重します。チャネル単位の設定よりもホストレベルのプロキシ設定を優先してください。
• messages.removeAckAfterReply が有効な場合、OpenClaw は表示可能な返信が配信されると ack リアクションを消去します。

​

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,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

​

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

​

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

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

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

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: {
        // 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." },
          },
        },
      },
    },
  },
}

​

設定リファレンスの参照先

​

関連

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