openclaw-weixin-cli · QR 绑定 · 灰度プラグイン · Gateway 再起動 · 本番 Runbook
WeChat 上で ClawBot を開き、OpenClaw Gateway 経由で AI Agent と会話したい——そう考えて npx @tencent-weixin/openclaw-weixin-cli を実行したのに、QR スキャンが失敗する、連絡先が現れない、Gateway 再起動後に返信が止まる、といった症状に当たる方へ向けたガイドです。2026 年時点の公式プラグイン経路を前提に、前置チェック、インストール Runbook、绑定验收、本番注意点までを一気通貫で整理します。Gateway インストール排障チェックリストとマルチチャネル強化チェックリストと併読することをお勧めします。
2026 年、Tencent が提供する WeChat ClawBot は、WeChat クライアント内の公式プラグインとして AI 会話を可能にする機能です。OpenClaw 側では @tencent-weixin/openclaw-weixin パッケージが Gateway のチャネルプラグインとして動作し、Telegram や Discord と同列の IM 入口になります。サードパーティの Webhook 桥接や個人 bot フレームワークとは異なり、メッセージは WeChat 公式クライアント ↔ Gateway ↔ モデルバックエンドという正規経路を通ります。
アーキテクチャ上、ClawBot は「WeChat 専用の会話 UI」、OpenClaw は「スキル実行・モデルルーティング・永続 Gateway」の役割分担です。2026.3.22 以降の OpenClaw リリースではプラグイン API が安定しており、openclaw plugins install で WeChat チャネルを追加できます。モデルがクラウド API か Ollama ローカルかは WeChat チャネルとは独立です。
公式 vs 非公式：本番は @tencent-weixin スコープの CLI/プラグインのみを使い、非公式桥接は鍵漏えい・規約違反リスクがあります。
Gateway 必須：WeChat からのイベントは Gateway が受け取り、Skill とモデルへルーティングします。Gateway 未起動では QR 绑定も完了しません。
24/7 前提：ノート PC のスリープは WeChat 返信 SLA を壊します。クラウド Mac 常駐ガイドと同型の課題です。
灰度（段階公開）：WeChat クライアントと ClawBot プラグインは地域・バージョンで段階公開中です。最新安定版への更新が前提条件になります。
単聊中心：2026 年時点ではグループ会話やファイル転送に制限があります。ユースケースを 1 対 1 相談に限定して設計してください。
次節では、インストール前に必ず確認すべきバージョン・账号・ノード選定のチェックリストを示します。
ClawBot 導入の失敗の多くは「CLI は成功したが WeChat 側が未対応」です。以下をチケットに貼ってから Runbook に進んでください。
| 項目 | 確認内容 | 未達時の典型症状 |
|---|---|---|
| WeChat クライアント | 最新安定版、ClawBot プラグイン灰度が有効 | 設定に ClawBot 入口がない、QR が無効 |
| OpenClaw | 2026.3.22+、Node 22.14+、openclaw doctor 緑 | プラグイン API 不一致、Gateway 起動失敗 |
| WeChat 账号 | 実名認証済み、本番用はサブ账号分離推奨 | 绑定拒否、規約上の利用制限 |
| 実行ノード | Gateway 24/7、18789 系ポート到達 | 返信遅延、再起動後に無応答 |
| npm レジストリ | 公式 npm または信頼できるミラー | npx タイムアウト、checksum エラー |
WeChat はクライアント側の灰度が最後のゲートです。サーバーだけ整えても、端末が対象外なら绑定は始まりません。
個人検証はノート PC でも可能ですが、本番 IM 連携では Docker/VPS またはDocker Compose 本番ベースラインに沿った隔離デプロイを推奨します。WeChat 用の API 鍵と Telegram 用鍵は別ファイル・別環境変数で管理し、マルチチャネル強化チェックリストの最小権限原則に合わせてください。
2026 年の推奨経路は二つです。初回検証は npx @tencent-weixin/openclaw-weixin-cli、本番・再現性重視は openclaw plugins install です。どちらも Gateway 起動前後の順序を守ってください。
Gateway 前提確認：openclaw gateway status が healthy。openclaw doctor --fix で Node とポートを揃えます。
経路 A — npx CLI：下記コマンドでプラグイン導入と绑定ウィザードを起動します。対話で QR が表示されます。
経路 B — 手動プラグイン：openclaw plugins install @tencent-weixin/openclaw-weixin の後、設定ファイルにチャネルを有効化します。
Gateway 再起動：プラグイン追加後は必ず openclaw gateway restart。channels キャッシュの更新に必要です。
openclaw doctor --fix openclaw gateway status npx @tencent-weixin/openclaw-weixin-cli install openclaw plugins install @tencent-weixin/openclaw-weixin openclaw gateway restart openclaw channels status
npx @tencent-weixin/openclaw-weixin-cli bind openclaw logs --follow openclaw channels status --channel weixin
ヒント：npm ミラー利用時は @tencent-weixin スコープが同期されているか確認してください。古いキャッシュは npm cache clean --force の後に再実行します。
绑定成功の判定は「WeChat 連絡先に ClawBot が現れ、送信したテスト文が Gateway ログに現れ、Agent から返信が戻る」の三点セットです。Telegram の BotFather トークン方式とは手順が異なります。
| チャネル | 認証方式 | コールバック | 本番注意 |
|---|---|---|---|
| WeChat ClawBot | QR スキャン + プラグイン灰度 | Gateway 常駐、WeChat クライアント依存 | 単聊のみ、ファイル制限、账号分離 |
| Telegram | Bot Token + webhook/setWebhook | 公网 HTTPS 必須 | グループ・チャネル対応、Token ローテーション |
| Discord | Bot Intents + Gateway WS | Intents 設定ミスで無音 | Guild 権限、Slash コマンド |
QR 表示：CLI の QR は通常 2〜3 分で失効します。失効時は bind を再実行し、WeChat で「扫一扫」を速やかに完了してください。
連絡先確認：WeChat 連絡先一覧に ClawBot が追加されていることを目視確認します。
初回回环：短いテキスト（例：ping）を送信し、openclaw logs --follow で inbound/outbound を確認します。
channels status：openclaw channels status で weixin が connected と表示されることを验收基準にします。
返信が無い場合はモデル API ではなくチャネル層を先に疑ってください。Gateway 排障チェックリストの三段式ログ（Gateway → チャネル → モデル）に沿うと二分探索が速くなります。
| 症状 | 先に確認 | よくある対処 |
|---|---|---|
| QR スキャン失敗 | WeChat 版本、灰度、QR 失効 | クライアント更新、bind 再実行 |
| メッセージが届かない | Gateway 停止、channels status | gateway restart、ログ三段式確認 |
| 再起動後に無応答 | プラグイン読込、WeChat 側セッション | 再绑定、設定ファイルの weixin 有効化確認 |
| npx タイムアウト | npm ミラー、ネットワーク | 公式 registry、プロキシ設定見直し |
| ファイル・画像不可 | 2026 機能制限 | テキストのみの Skill 設計に限定 |
@tencent-weixin/openclaw-weixin の semver を compose または lockfile に固定し、不意のメジャー更新を防ぎます。注意：同一変更チケットで WeChat 再绑定、Gateway イメージ更新、モデル API Key ローテーションを同時に行わないでください。三角変更は原因特定を不可能にします。
WeChat ClawBot をチームで使う場合、Gateway は常時起動・監視可能・鍵分離が必須です。ノート PC 検証後は、Ollama やクラウド API と同様にリモートノードへ移すのが定石です。
Docker Compose 本番ベースラインに沿って Gateway コンテナを 127.0.0.1 绑定し、WeChat プラグインをボリュームに永続化します。ログは Gateway → チャネル → モデルの順で切り分け、週次で openclaw channels status を自動巡检に組み込んでください。
Apple Silicon の統一メモリと低消費電力は、WeChat 返信の体感 latency にも効きます。専有算力と監査可能な変更が必要なチームには、VpsMesh の Mac Mini クラウドレンタルで Gateway を 24/7 常駐させる構成が向いています。料金は 価格ページ、手順は ヘルプセンター、申込は 申込ページをご覧ください。クラウド Mac 常駐ガイドと併せると、WeChat と Telegram のマルチチャネル運用まで一本化できます。
はい。各 IM は Gateway 上の独立チャネルです。WeChat プラグインと Telegram Bot を並行有効化できます。必要なのは Gateway の24/7と openclaw channels status の定期確認です。詳細は マルチチャネル強化チェックリストを参照してください。
WeChat クライアントを最新版に更新し、ClawBot プラグイン灰度が有効か確認してください。Gateway が healthy な状態で npx @tencent-weixin/openclaw-weixin-cli bind を再実行し、QR 失効前にスキャンを完了します。それでも失敗する場合は Gateway 排障チェックリストで Node とポートを確認してください。
openclaw gateway restart 後に openclaw channels status --channel weixin を確認し、connected でなければ再绑定を行います。本番では 24/7 常駐ガイドに沿ったデーモンと、リモート Mac 申込によるノード固定を検討してください。