OpenClaw WhatsApp 連携完全ガイド

概要

WhatsApp 連携により、WhatsApp を通じて直接 OpenClaw AI アシスタントとチャットできます。OpenClaw は Baileys を介した WhatsApp Web を使用しており、ゲートウェイがセッションを所有し、すべての通信を管理します。ブラウザで WhatsApp Web をリンクするのと同じ方法で、WhatsApp アカウントをリンクします。

前提条件

開始する前に、以下を確認してください：

• OpenClaw がインストールされ、ゲートウェイが実行中であること
• 実際の携帯電話番号を持つ WhatsApp アカウント（VoIP や仮想番号は WhatsApp にブロックされることが多い）
• Node.js ランタイム（Bun は非推奨 — WhatsApp/Baileys は Bun 上で不安定）

電話番号の取得

WhatsApp は認証に実際の携帯電話番号を必要とします。サポートされるモードは2つあります：

専用番号（推奨）

OpenClaw 用に別の電話番号を使用します。クリーンなルーティングとセルフチャットの問題がないため、最良の UX が得られます。理想的なセットアップは、予備/古い Android スマートフォン + eSIM です。Wi-Fi と電源に接続したまま放置し、QR でリンクします。

番号の入手方法：

• ローカル eSIM — お住まいの国のモバイルキャリアから（最も信頼性が高い）
• プリペイド SIM — 安価で、認証 SMS を1通受信するだけで済む
• 避けるべきもの： TextNow、Google Voice、ほとんどの「無料SMS」サービス — WhatsApp はこれらを積極的にブロックする

番号は認証 SMS を1通受信するだけで済みます。その後、WhatsApp Web セッションは creds.json を通じて維持されます。

ヒント： WhatsApp Business を同じデバイスで別の番号を使って利用できます。個人の WhatsApp を分離するのに最適です。WhatsApp Business をインストールし、OpenClaw 用の番号をそこに登録してください。

個人番号（フォールバック）

簡単なフォールバック：OpenClaw を自分自身の番号で実行します。テスト用に自分自身にメッセージを送信（WhatsApp の「自分にメッセージ」）することで、連絡先にスパムを送ることを避けられます。この場合、セルフチャットモードを有効にする必要があります。

ステップ1：WhatsApp を設定

~/.openclaw/openclaw.json を編集します。

専用番号の設定

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

+15551234567 をアシスタントとチャットを許可する電話番号（E.164 形式）に置き換えてください。

個人番号の設定（セルフチャットモード）

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

セルフチャットモードを使用する場合、メッセージを送信する電話番号（所有者/送信者）を入力してください。アシスタントの番号ではありません。セルフチャットの返信はデフォルトで [{identity.name}] がプレフィックスとして付きます（未設定の場合は [openclaw]）。messages.responsePrefix でカスタマイズするか、"" に設定して削除できます。

ステップ2：WhatsApp アカウントをリンク

ログインコマンドを実行します：

openclaw channels login

ターミナルに QR コードが表示されます。スマートフォンで：

1. WhatsApp を開く
2. 設定 > リンク済みデバイス に移動
3. デバイスをリンク をタップ
4. ターミナルに表示された QR コードをスキャン

マルチアカウントセットアップの場合、アカウントを指定します：

openclaw channels login --account <accountId>

デフォルトアカウント（--account を省略した場合）は、default が存在すればそれが使用され、なければ最初に設定されたアカウント ID（ソート順）が使用されます。

ステップ3：ゲートウェイを起動

OpenClaw ゲートウェイを起動してメッセージの受信を開始します。ゲートウェイは Baileys ソケットと受信ループを所有しています。CLI と macOS アプリはゲートウェイと通信し、Baileys を直接使用しません。

重要： 送信にはアクティブなリスナーが必要です。リスナーがない場合、送信は即座に失敗します。

DM アクセス制御

OpenClaw は channels.whatsapp.dmPolicy を通じて3つの DM ポリシーモードを提供します：

ペアリングモード（デフォルト）

未知の送信者には有効期限付きのペアリングコードが送信されます。メッセージは承認されるまで処理されません。

# ペアリングリクエストを承認
openclaw pairing approve whatsapp <code>

# 保留中のペアリングリクエストを一覧表示
openclaw pairing list 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 ドキュメント