OpenClawでWhatsAppを連携する方法

メッセージアプリを自分のシステムに統合しようとすると、APIの制限や複雑な認証プロセスに直面することがよくあります。特に WhatsApp のような広く使われているプラットフォームを自動化のフローに組み込むのは、一筋縄ではいかない作業です。

OpenClaw を使えば、WhatsApp Web (Baileys) を介して、既存のワークフローにメッセージ機能を組み込むことができます。このガイドでは、そのセットアップ手順を分かりやすく解説します。

必要なもの

WhatsApp アカウント（専用の電話番号での運用を推奨）
OpenClaw の実行環境

クイックスタート

5分ほどで WhatsApp チャンネルを有効化できます。以下の手順に沿って進めてください。

1. WhatsApp access policy の設定

まず、設定ファイルでアクセス権限を定義します。

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

2. WhatsApp のリンク (QRコード)

CLI を使用して WhatsApp アカウントをリンクします。実行すると QR コードが表示されるので、スマートフォンの WhatsApp アプリでスキャンしてください。

openclaw channels login --channel whatsapp

特定のアカウント（例：仕事用）を指定してログインする場合は、以下のコマンドを使用します。

openclaw channels login --channel whatsapp --account work

3. Gateway の起動

次に、Gateway を起動して接続を確立します。

openclaw gateway

4. ペアリングリクエストの承認

pairing モードを使用している場合、最初のペアリングリクエストを承認する必要があります。

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Deployment patterns

運用の目的に合わせて、2つの主要なパターンから選択できます。

推奨：専用番号での運用

OpenClaw 用に別の WhatsApp 番号を用意するのが、最もクリーンな方法です。

OpenClaw 専用のアイデンティティを持てる
DM の許可リストやルーティングの境界が明確になる
自分自身とのチャット（self-chat）による混乱を避けられる

この場合の最小限のポリシー設定は以下の通りです。

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

個人番号の利用

個人の番号をそのまま利用することも可能です。この場合、自分自身とのチャットに適した設定が適用されます。

dmPolicy: "allowlist" を使用
allowFrom に自分の番号を含める
selfChatMode: true を設定する

実行時は、リンクされた自身の番号と allowFrom に基づいて、セルフチャット保護機能が動作します。

技術的な注意点

現在の OpenClaw のアーキテクチャでは、WhatsApp チャンネルは WhatsApp Web ベース（Baileys）で動作します。組み込みのチャンネルレジストリには、個別の Twilio WhatsApp チャンネルは含まれていません。

Runtime model

動作の仕組みについて、いくつか重要なポイントがあります。

Gateway の役割: Gateway が WhatsApp の Socket と再接続ループを管理します。
送信の条件: メッセージを送信するには、対象のアカウントに対してアクティブな WhatsApp リスナーが存在している必要があります。
無視されるチャット: ステータス更新（@status）やブロードキャスト（@broadcast）は無視されます。
セッションの管理: ダイレクトチャットは DM セッションルールに従います。グループセッションは agent:<agentId>:whatsapp:group:<jid> として隔離されます。

トラブルシューティング

ペアリングの期限: ペアリングリクエストは 1 時間で期限切れになります。
リクエストの制限: 保留中のリクエストは、1 チャンネルにつき最大 3 つまでです。

セットアップで困ったときは、こちらのツールも活用してください。 AI Setup Assistant

次のステップ

Pairing: ペアリングポリシーの詳細
Gateway configuration: Gateway の詳細な設定例
Channel troubleshooting: チャンネル全般の診断と修復手順

ボットを公開した際、意図しないユーザーから大量のメッセージが届いたり、知らないグループに追加されて勝手に動作してしまったりするのは避けたいですよね。開発者にとって、ボットが誰に応答し、どの環境でアクティブになるかを正確にコントロールすることは、安定した運用のための第一歩です。

ここでは、WhatsApp におけるアクセス制御とアクティベーションの仕組みを整理して解説します。

必要なもの

設定を始める前に、以下の準備ができているか確認してください。

channels.whatsapp の設定ブロック
許可する電話番号（E.164 形式）
メンション検知用の設定項目

クイックスタート

最短でアクセス制御を構成するためのステップです。

DM Policy の決定: デフォルトでは pairing が適用されます。特定の番号のみに制限したい場合は allowlist を選択してください。
グループアクセスの制限: channels.whatsapp.groups に許可するグループ ID をリストアップします。
メンション設定: グループ内での誤反応を防ぐため、ボットへのメンションを必須にする設定を確認します。
アクティベーション: 必要に応じてチャット内で /activation コマンドを実行し、応答モードを切り替えます。

1. DM Policy と allowlist

channels.whatsapp.dmPolicy を使用して、ダイレクトチャットへのアクセス権限を管理します。

pairing (デフォルト): ペアリングされたユーザーのみ許可。
allowlist: allowFrom に記載された番号のみ許可。
open: 全員に開放（allowFrom に "*" を含める必要があります）。
disabled: DM をすべてブロック。

allowFrom に指定する電話番号は、内部で正規化されるため E.164 スタイルで記述してください。

ランタイムの挙動

ペアリング情報はチャネルの allow-store に保存され、設定ファイルの allowFrom とマージされます。
allowlist が設定されていない場合、デフォルトでリンクされている自分自身の番号が許可されます。
自分自身から送信した（fromMe）アウトバウンド DM によって自動的にペアリングされることはありません。

2. グループポリシーと allowlist

グループチャットへのアクセスは、2 つのレイヤーで制御されます。

レイヤー 1: グループメンバーシップ allowlist

channels.whatsapp.groups を使用します。

この項目を省略した場合、すべてのグループが対象となります。
項目が存在する場合、ホワイトリストとして機能します（"*" で全許可も可能）。

レイヤー 2: グループ送信者ポリシー

channels.whatsapp.groupPolicy と groupAllowFrom で制御します。

open: 送信者の allowlist をバイパスします。
allowlist: 送信者が groupAllowFrom（または *）に一致する必要があります。
disabled: グループへのインバウンドメッセージをすべてブロックします。

フォールバックの仕組み: groupAllowFrom が未設定の場合、ランタイムは allowFrom の設定を代わりに使用します。なお、channels.whatsapp ブロック自体が存在しない場合、グループポリシーは実質的に open として動作します。

3. メンションと /activation コマンド

デフォルトでは、グループ内での応答にメンションが必要です。

メンションの検知条件

ボットは以下のいずれかを確認して反応します。

ボットの identity に対する明示的な WhatsApp メンション。
設定された正規表現パターン（agents.list[].groupChat.mentionPatterns、未設定時は messages.groupChat.mentionPatterns を参照）。
暗黙的なリプライ検知（リプライ先の送信者がボットの identity と一致する場合）。

セッションレベルのアクティベーション

特定のチャットセッションの状態を更新するために、以下のコマンドを使用できます。これはグローバルな設定ではなく、セッションごとの状態を上書きします。また、このコマンドの実行はオーナー権限を持つユーザーに限定されます。

/activation mention: メンション時のみ反応。
/activation always: 常に反応。

自分自身の番号（Self-chat）の挙動

リンクされている自分自身の番号が allowFrom に含まれている場合、WhatsApp のセルフチャット用セーフガードが有効になります。

セルフチャットにおける既読メッセージ（read receipts）の送信をスキップします。
自分自身に通知が飛ばないよう、メンション JID による自動トリガー挙動を無視します。
messages.responsePrefix が未設定の場合、セルフチャットへの返信にはデフォルトで [{identity.name}] または [openclaw] が付与されます。

トラブルシューティング

グループでボットが反応しない: channels.whatsapp.groups にそのグループが含まれているか、またはメンションが正しく検知されているか確認してください。
特定のユーザーを拒否したい: dmPolicy を allowlist に変更し、allowFrom にそのユーザーを含めないように設定します。

設定の詳細については、AI Setup Assistant で質問することも可能です。

次のステップ

メッセージの処理は、開発者にとって頭の痛い問題です。特に、引用返信やメディアファイルが混ざると、データの整形だけで時間が過ぎてしまいます。

こうした複雑なデータを扱いやすくするために、システムがどのようにメッセージを正規化し、コンテキストを保持しているかを知っておくと開発がスムーズになります。

必要なもの

この機能を利用するには、以下の設定や環境が必要です。

WhatsApp チャンネルの設定
設定ファイル（config）へのアクセス権限
インバウンドメッセージを受信するための Gateway 設定

クイックスタート

WhatsApp メッセージを効率よく処理するための、5分でわかる基本ステップです。

1. インバウンドエンベロープと返信コンテキスト

受信した WhatsApp メッセージは、共通のインバウンドエンベロープに包まれます。引用返信がある場合、以下の形式でコンテキストが追加されます。

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

また、利用可能な場合は以下のメタデータフィールドも入力されます。

ReplyToId
ReplyToBody
ReplyToSender
送信者の JID/E.164

2. メディアプレースホルダーと情報の抽出

メディアのみのメッセージは、以下のようなプレースホルダーに正規化されます。

<media:image>
<media:video>
<media:audio>
<media:document>
<media:sticker>

位置情報や連絡先のペイロードは、ルーティングの前にテキスト形式のコンテキストに正規化されます。

3. グループ履歴の注入

グループチャットでは、未処理のメッセージをバッファリングし、Bot が起動した際にコンテキストとして注入できます。

デフォルト制限: 50
設定項目: channels.whatsapp.historyLimit
フォールバック: messages.groupChat.historyLimit
0 を指定すると無効化

注入時には以下のマーカーが付与されます。

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

4. 既読確認（Read receipts）の設定

WhatsApp メッセージを受信すると、デフォルトで既読確認が送信されます。これを無効にするには、設定を変更してください。

グローバルで無効にする場合:

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

アカウント単位で設定する場合:

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

トラブルシューティング

よくある挙動の疑問と解決策です。

自分宛てのチャットで既読にならない: セルフチャット（自分自身とのチャット）では、グローバル設定が有効であっても既読確認はスキップされます。
グループ履歴が表示されない: channels.whatsapp.historyLimit が 0 に設定されていないか確認してください。

不明な点がある場合は、AI Setup Assistant も活用してみてください。

次のステップ

チャットボットを運用していると、長いメッセージが途中で切れてしまったり、大容量のメディア送信が失敗してユーザーに何も届かなかったりといった問題に直面することがあります。特に WhatsApp のようなプラットフォームでは、配信の挙動を細かく制御することが、ユーザー体験を損なわないための重要なポイントです。

ここでは、メッセージを適切に分割し、メディアを確実に届けるための設定方法について解説します。

必要なもの

設定を始める前に、以下の準備ができているか確認してください。

channels.whatsapp.accounts で設定された有効なアカウント ID
認証情報ファイル（~/.openclaw/credentials/whatsapp/<accountId>/creds.json）
送信したいメディアのソース（HTTP(S) URL、file://、またはローカルパス）
WhatsApp チャンネルが有効化された環境

クイックスタート

5 分で完了する、基本的な配信とメディアの設定手順です。

1. テキスト分割（Chunking）の設定

長いテキストを送る際の分割ルールを定義します。デフォルトの制限は 4000 文字です。

// 設定例
channels.whatsapp.textChunkLimit = 4000
channels.whatsapp.chunkMode = "newline" // "length" または "newline"

newline モードを選択すると、まず段落の境界（空行）での分割を試み、その後に文字数ベースの安全な分割を行います。

2. メディア送信の最適化

画像、動画、音声（PTT ボイスノート）、ドキュメントを送信できます。

音声: audio/ogg は、ボイスノートとしての互換性を保つために audio/ogg; codecs=opus へ自動的に書き換えられます。
GIF: 動画送信時に gifPlayback: true を設定することで、アニメーション GIF として再生可能です。
キャプション: 複数のメディアを一度に送る場合、最初のアイテムにキャプションが適用されます。

3. 受信確認（Acknowledgment）の設定

メッセージを受信した直後に、自動でリアクションを返すことができます。

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

group モードを mentions にするとメンション時のみ反応し、always にすると常に反応します。

4. メディアサイズ制限の調整

送受信できるメディアのサイズ上限を設定します。

受信: channels.whatsapp.mediaMaxMb (デフォルト 50MB)
送信: agents.defaults.mediaMaxMb (デフォルト 5MB) 送信する画像は、制限内に収まるよう自動的にリサイズや品質調整が行われます。

トラブルシューティング

よくある問題と解決策です。

メディアの送信に失敗する: メディアの送信に失敗した場合、システムはレスポンスを無言で破棄するのではなく、最初のアイテムの代わりにテキストによる警告を送信します。ログを確認し、ファイルパスや URL が正しいかチェックしてください。
アカウントのログアウト: 認証状態をクリアしたい場合は、以下の CLI コマンドを使用します。 openclaw channels logout --channel whatsapp [--account <id>] これにより、指定したアカウントの認証情報が削除されます（oauth.json は保持され、Baileys の認証ファイルが削除されます）。

不明な点がある場合は、AI Setup Assistant で質問してください。

次のステップ

---
title: "WhatsApp Gateway トラブルシューティングガイド"
description: "WhatsApp Gateway の接続問題やメッセージ送信エラーを素早く解決するためのガイドです。"
---

開発を進めている中で、メッセージが届かなかったり、接続が予期せず切れてしまったりすることは、誰しもが経験する悩みです。設定は正しいはずなのに、なぜか動かない。そんな時に、どこを確認してどう対処すべきかを知っておくことは非常に重要です。

この記事では、WhatsApp Gateway を利用する際によく遭遇する問題とその具体的な解決策をまとめました。スムーズな開発環境を取り戻すために、ぜひ参考にしてください。

## 必要なもの

作業を始める前に、以下の環境が整っているか確認してください。

- **Node.js**: WhatsApp Gateway の安定動作のために必須です。
- **OpenClaw CLI**: 各種コマンド操作に使用します。
- **WhatsApp アカウント**: 連携対象となるアカウントが必要です。

## クイックスタート

まずは、以下の 5 分でできる基本チェックから始めましょう。

1. **ステータスの確認**: チャンネルが正しくリンクされているか確認します。
   ```bash
   openclaw channels status

再ログイン: リンクされていない場合は、QR コードを使用してログインします。
Terminal window
```
openclaw channels login --channel whatsapp
```
診断コマンドの実行: システムの状態をチェックします。
Terminal window
```
openclaw doctor
```
ログの監視: リアルタイムでエラーを確認します。
Terminal window
```
openclaw logs --follow
```

トラブルシューティング

よくある症状と、その解決方法を整理しました。

連携されていない（QR コードが必要な場合）

症状: チャンネルステータスに「not linked」と表示される。

解決策: 以下のコマンドを実行して再ログインし、ステータスを更新してください。

openclaw channels login --channel whatsapp
openclaw channels status

連携済みだが切断される / 再接続ループが発生する

症状: アカウントは連携されているが、頻繁に切断されたり再接続を繰り返したりする。

解決策: まずは診断コマンドとログを確認してください。

openclaw doctor
openclaw logs --follow

必要に応じて、channels login を使用して再度リンクし直してください。

送信時にアクティブなリスナーがない

症状: 送信（Outbound）が即座に失敗する。

ターゲットアカウントに対して Gateway のアクティブなリスナーが存在しない場合に発生します。Gateway が起動していること、およびアカウントが正しくリンクされていることを確認してください。

グループメッセージが予期せず無視される

症状: グループ向けのメッセージが処理されない。

以下の項目を順番に確認してください。

groupPolicy の設定
groupAllowFrom / allowFrom の設定
groups 許可リストのエントリ
メンションによる制限（requireMention + メンションパターン）

Bun ランタイムに関する警告

症状: 動作が不安定、または警告が表示される。

WhatsApp Gateway のランタイムには Node.js を使用してください。Bun は、WhatsApp および Telegram Gateway の安定した動作において互換性がないと判断されています。

Configuration reference pointers

設定の詳細については、以下のリファレンスを参照してください。

Configuration reference - WhatsApp

特に重要な WhatsApp 関連フィールドは以下の通りです。

アクセス制御: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
配信設定: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
マルチアカウント: accounts.<id>.enabled, accounts.<id>.authDir, アカウントレベルの上書き
運用設定: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
セッション挙動: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

解決しない場合は、AI Setup Assistant で詳細な状況を教えてください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。