OpenClaw WhatsApp 連携完全ガイド

ペアリングコードは 1時間 で期限切れになり、保留中のリクエストはチャンネルあたり最大3件に制限されています。

許可リストモード

channels.whatsapp.allowFrom にリストされた電話番号のみがチャットを開始できます。

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

オープンモード

channels.whatsapp.allowFrom に "*" を含める必要があります。

注意： リンクされた WhatsApp 番号は暗黙的に信頼されます。セルフメッセージは dmPolicy と allowFrom のチェックをスキップします。

既読通知

デフォルトでは、ゲートウェイは受信した WhatsApp メッセージを受理した時点で既読マーク（青いチェック）を付けます。

グローバルに無効化：

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

アカウントごとに無効化：

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

セルフチャットモードでは既読通知は常にスキップされます。

グループチャットサポート

グループは専用セッションにマッピングされます。グループの動作は以下で設定します：

• グループポリシー： channels.whatsapp.groupPolicy — open 、 disabled 、または allowlist （デフォルト： allowlist ）
• アクティベーションモード：
  • mention （デフォルト）：@メンションまたは正規表現マッチが必要
  • always ：常に応答をトリガー

オーナー専用コマンドでアクティベーションを切り替えます（スタンドアロンメッセージである必要があります）：

/activation mention
/activation always

オーナーは channels.whatsapp.allowFrom （未設定の場合はセルフ E.164）によって決定されます。

グループ履歴コンテキスト

最近の未処理メッセージ（デフォルト50件）がコンテキストとして自動的に注入されます：

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

各メッセージには送信者サフィックスが含まれます： [from: Name (+E164)] 。

グループメタデータ（件名 + 参加者）は5分間キャッシュされます。

確認リアクション

WhatsApp は受信メッセージに絵文字リアクションを自動的に送信できます。ボットが返信を生成する前に即座にフィードバックを提供します。

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

オプション：

• emoji ：リアクションに使用する絵文字（例："👀"、"✅"）。空または省略すると機能が無効になります。
• direct （デフォルト： true ）：DM チャットでリアクションを送信。
• group （デフォルト： "mentions" ）：
  • "always" ：すべてのグループメッセージにリアクション
  • "mentions" ：ボットが @メンションされた場合のみリアクション
  • "never" ：グループではリアクションしない

アカウントごとのオーバーライド：

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

リアクションは受信時に即座に送信され、タイピングインジケーターやボットの返信の前に行われます。失敗はログに記録されますが、ボットの返信は妨げられません。

メッセージ処理

受信メッセージ

• メッセージは Baileys の messages.upsert イベントを通じて到着
• ステータス/ブロードキャストチャットは無視される
• ダイレクトチャットは E.164 形式を使用、グループはグループ JID を使用
• 引用返信のコンテキストは常に追加され、会話のコンテキストを提供
• メディアのみのメッセージはプレースホルダーを使用： <media:image|video|audio|document|sticker>

送信メッセージ

• テキストはデフォルトで 4,000文字 にチャンク分割される（ channels.whatsapp.textChunkLimit で設定可能）
• オプションの改行チャンキング： channels.whatsapp.chunkMode="newline" を設定すると、長さチャンキングの前に段落境界で分割
• サポートされるメディアタイプ：image、video、audio、document
• 音声はボイスノート（PTT）として送信。OGG/Opus 形式が最適
• キャプションは最初のメディアアイテムのみに付与
• アニメーション GIF：WhatsApp はインラインループ再生に gifPlayback: true 付きの MP4 を期待

メディア制限

• 受信 メディア保存上限：50 MB（ channels.whatsapp.mediaMaxMb で設定可能）
• 送信 メディア上限：アイテムあたり 5 MB（ agents.defaults.mediaMaxMb で設定可能）
• 画像は上限以下の場合、JPEG に自動最適化（リサイズ + 品質スイープ）
• サイズ超過のメディアはエラーとなり、メディア返信はテキスト警告にフォールバック

認証情報とストレージ

• 認証情報の保存場所： ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• creds.json.bak に自動バックアップ（破損時に復元）
• ログアウト： openclaw channels logout （または --account <id> ）は WhatsApp 認証状態を削除しますが、共有の oauth.json は保持

マルチアカウントサポート

複数の WhatsApp アカウントを単一のゲートウェイプロセスで実行できます。設定でアカウント識別子を使用します：

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* アカウントごとの設定 */ },
        work: { /* アカウントごとの設定 */ },
      },
    },
  },
}

アカウントごとの設定では、 sendReadReceipts 、 ackReaction 、 mediaMaxMb 、 historyLimit などのオーバーライドがサポートされています。

なぜ Twilio / WhatsApp Business API を使わないのか？

初期の OpenClaw ビルドでは Twilio の WhatsApp Business 連携をサポートしていましたが、以下の理由で削除されました：

• WhatsApp Business 番号は個人アシスタントには不向き
• Meta は 24時間の返信ウィンドウ を強制 — 過去24時間以内に返信していない場合、ビジネス番号から新しいメッセージを開始できない
• 大量または「おしゃべりな」使用は積極的なブロックをトリガーする。ビジネスアカウントは個人アシスタントスタイルのメッセージング向けに設計されていないため
• 結果：配信が不安定で、頻繁にブロックされる

設定クイックリファレンス

| 設定キー | 説明 | |---|---| | channels.whatsapp.dmPolicy | DM ポリシー： pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | 個人番号セットアップ用に有効化 | | channels.whatsapp.allowFrom | DM 許可リスト（E.164 電話番号） | | channels.whatsapp.sendReadReceipts | 自動既読通知（デフォルト：true） | | channels.whatsapp.ackReaction | メッセージ受信時の自動リアクション | | channels.whatsapp.groupPolicy | グループポリシー： open / disabled / allowlist | | channels.whatsapp.textChunkLimit | 送信テキストチャンクサイズ（デフォルト：4000） | | channels.whatsapp.mediaMaxMb | 受信メディア上限（デフォルト：50 MB） | | channels.whatsapp.configWrites | /config コマンドによる設定書き込みを許可 | | agents.defaults.mediaMaxMb | 送信メディア上限（デフォルト：5 MB） |

トラブルシューティング

未リンク / QR ログインが必要

症状： channels status が linked: false と表示、または「Not linked」と警告。

対処法： ゲートウェイホストで openclaw channels login を実行し、QR コードをスキャン（WhatsApp > 設定 > リンク済みデバイス）。

リンク済みだが切断 / 再接続ループ

症状： channels status が running, disconnected と表示、または「Linked but disconnected」と警告。

対処法： openclaw doctor を実行するか、ゲートウェイを再起動。問題が続く場合は、 openclaw channels login で再リンクし、 openclaw logs --follow を確認。

Bun ランタイムの問題

Bun は 非推奨 です。WhatsApp（Baileys）と Telegram は Bun 上で不安定です。ゲートウェイは Node.js で実行してください。

再接続動作

ゲートウェイはバックオフポリシー（ web.reconnect ）を使用し、 initialMs 、 maxMs 、 factor 、 jitter 、 maxAttempts が設定可能です。最大試行回数に達すると、Web 監視が停止します（劣化モード）。ログアウトされたソケットは停止し、再リンクが必要になります。

次のステップ

• Telegram 連携ガイド
• Discord 連携ガイド
• 公式 WhatsApp ドキュメント