wechat-rpa-bot

WeChat RPA Bot Skill（MCP 版）

このスキルは、ローカルの yoko WeChat RPA MCP サーバーをセットアップし、MCP ツールを通じて WeChat を操作することで、MCP 対応ホスト（OpenClaw / QClaw / WorkBuddy …）を WeChat アシスタントにします。

メンタルモデル（必ず最初に理解してください）

• WeChat の自動化機能は、ユーザーのデスクトップ（Session 1）で yoko_rpa_mcp.exe が常駐して提供します。ポートは 9922、同じプロセスが次の 3 つのインターフェースを提供します。
  • /mcp — Streamable-HTTP MCP エンドポイント（本スキルの主要な通信経路。Bearer token 認証）
  • /api/* — REST（本スキルではインストール／アクティベーション／token 取得などのセットアップ手順でのみ使用します）
  • / — ビジュアルコンソール（手動での代替手段）
• 本スキルは WeChat のメッセージを直接送信しません。MCP サーバーをインストールし、起動してアクティベートし、/mcp と token をホストの mcp.json に書き込みます。 ホストが設定を再読み込みすると、約 27 個の WeChat ツールがホストでネイティブに利用可能になり、その後はホストのエージェントが直接呼び出します。
• エージェントはこの exe を自分で spawn してはいけません。spawn されたプロセスはサンドボックス／セッション分離を継承し、WeChat のデスクトップを認識できません。exe はユーザー自身が対話セッション内で起動する必要があります（初回のみ。以後、exe は自動起動に登録され、自動で再起動します）。

---

0. エンドツーエンドのフロー概要

安装 exe ──▶ 用户首启(Session 1) ──▶ 健康检查(REST) ──▶ 激活 license(REST)
   └──▶ 取 MCP token(REST) ──▶ 生成 mcp.json ──▶ 用户粘贴+重载宿主 ──▶ 验活(MCP tools/list)
        ──▶ 之后所有微信能力走 MCP 工具(自带 read_manual 手册)

---

1. インストール（ユーザーがインストーラーを実行し、エージェントは案内のみ）

⚠️ この手順はユーザー本人が行う必要があり、自動ではありません。 WeChat 機能は、公式インストーラー yoko_rpa_mcp_setup.exe でインストールするデスクトッププログラムが提供します。 エージェントは手順を明確に説明し、ダウンロードリンクを提示するだけです。ユーザーに代わってサイレントインストールしたり、インストーラーや exe を自分で実行したりしないでください。理由は §2（サンドボックス／セッション分離により、自動起動したプロセスでは WeChat を操作できない）を参照してください。 ユーザーには一度に、明確に次のように伝えてください。「WeChat の自動化には、お使いの PC にローカルプログラムをインストールする必要があります。以下にダウンロードとインストールの手順をお送りしますので、インストーラーを一度ご自身で実行してください（管理者権限の確認が表示されます）。」

1. 環境を確認します。Windows + WeChat デスクトップ版 ≥ 4.1.7（音声送信には ≥ 4.1.9 が必要です）。
   • バージョンの確認方法：WeChat → ヘルプ → バージョン情報。バージョンが合わない場合は、公式チャネルからアップグレードしてください。
2. インストーラー yoko_rpa_mcp_setup.exe をダウンロードして実行します（Inno Setup インストーラーパッケージ）。
   • ダウンロード先：https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/latest/download/yoko_rpa_mcp_setup.exe
   • エージェントはユーザーのダウンロードフォルダーに代わりにダウンロードできます。その後、ユーザーにダブルクリックして実行するよう依頼してください（エージェント自身はインストーラーを実行しないでください）。

     curl -L -o "$HOME/Downloads/yoko_rpa_mcp_setup.exe" https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/latest/download/yoko_rpa_mcp_setup.exe
     

   • ユーザーがダブルクリックして実行 → UAC が表示されたら「はい」をクリックし、管理者権限を付与します（C:\Program Files\yoko_rpa_mcp\ にインストールします。中国語のパスによる読み込み問題を避けるため、ASCII パスを使用します）。
   • インストーラーは自動で次の処理を行います。① プログラムを Program Files にインストールします。② 標準ユーザーとして（管理者ではなく、ユーザーの対話セッション Session 1 で）サービス --supervisor --no-ui を直ちに起動します。③ 3 つのチャネルでの自動起動を登録します（ログイン時のスケジュールタスク + HKCU Run キー + スタートアップフォルダー）。④ デスクトップ／スタートメニューに 「微信 RPA MCP 服务」 アイコンを作成します。
   • インストール完了時点で実行中です。手動で起動する必要はありません。exe 本体は C:\Program Files\yoko_rpa_mcp\yoko_rpa_mcp.exe にあります（skill 自体には exe は付属しません）。
3. VB-Cable 仮想オーディオドライバー（「音声メッセージの送信」にのみ必要）：https://vb-audio.com/Cable/ からダウンロードしてインストールし、インストール後に PC を再起動してください。テキスト／画像／ファイルなどの機能には不要です。
4. .env は不要です。アクティベーションコード方式を採用しています。アクティベーションコードは www.yokoagi.com から取得してください。

---

2. サービスの実行確認（インストーラーが自動起動するため、通常は手動操作不要）

なぜエージェントが spawn してはいけないのか：WeChat の自動化は、ユーザーに見えるデスクトップ上で実際のマウスとキーボードをシミュレートして行います。エージェント（特にサンドボックス内のエージェント）が自分で exe を起動すると、分離されたセッション内で起動するため、WeChat が見えません。これは仕様です。サービスはインストーラー／自動起動によってユーザーのセッション内で実行され、エージェントはネットワーククライアントとしてのみ動作します。

Step 1 — ヘルスチェック。 GET http://127.0.0.1:9922/api/health（localhost へのアクセス時はプロキシを無効化）。応答があればサービスの準備完了です → §3 に進み、アクティベーションを確認します。 インストーラーの実行後、通常は数秒以内に起動します。約 3 秒おきに最大約 2 分間ポーリングできます。ユーザーの入力を待たないでください。

Step 2 — 起動していない場合（まれなケース）。 インストーラーは実行後に自動起動し、自動起動も登録済みです。通常、手動操作は不要です。/api/health が応答しない状態が続く場合は、ユーザーに次のように案内してください。

「デスクトップの 「微信 RPA MCP 服务」 アイコンをダブルクリックして起動してください（またはスタートメニューから開いてください）。起動後、私に返信する必要はありません。準備ができたことを自動で検出して続行します。」

その後、/api/health のポーリングを続けます。それでも起動しない場合は、エラーダイアログが表示されているかユーザーに確認するか、§6 の復旧方法を参照してください。

PC 起動時の自動起動：インストーラーによって 3 つのチャネルでの自動起動とクラッシュ自動復旧の監視が登録済みです。次回起動時には自動で準備完了となるため、通常、ユーザーが手動で起動・終了する必要はありません。

---

3. License のアクティベーション（REST を使用するセットアップ操作）

最初に初期化状態を確認し、すでにアクティベートされているか判断します。

GET  http://127.0.0.1:9922/api/license/machine-code   → 拿本机 machine_code

• サービスがアクティベート済みと返した場合（以降、MCP 接続で 403 が返らない状態）→ §4 に進みます。
• 未アクティベートの場合：
  1. ユーザーに次のように伝えます。「ソフトウェアはまだアクティベートされていません。www.yokoagi.com からアクティベーションコードを取得し、受け取ったコードを私に送ってください。こちらで自動的にアクティベートします。」
  2. ユーザーからコードを受け取ったら：

     POST http://127.0.0.1:9922/api/license/activate
     Body: { "activation_code": "<ユーザーが提供>", "machine_code": "<step 1>" }
     

  3. 成功したら続行できます。MCP エンドポイントは接続のたびにライセンスを検証します（未アクティベート／期限切れの場合は 403 を返し、machine_code も返します）。

注：REST のセットアップ呼び出しには X-API-Key: yoko_test が必要です（localhost へのアクセス時はプロキシを無効化）。MCP チャネルでは別の Bearer token を使用します。§4 を参照し、混同しないでください。

---

4. MCP への接続（本スキルの中核）

4.1 MCP token の取得

token はローカルで生成されるランダムなキーです（アクティベーションコードとは異なり、アクティベーションコードが外部に漏れることはありません）。初回実行時に ~/.yokowebot/mcp_token.dat に保存されます。 通常、サンドボックス内のエージェントはこのファイルを読み取れないため、バックエンド専用エンドポイントから取得します（実装済み）。

GET http://127.0.0.1:9922/api/mcp/token
Headers: X-API-Key: yoko_test          (localhost 关代理)

成功時の戻り値：

{
  "success": true,
  "endpoint": "http://127.0.0.1:9922/mcp",
  "token": "<随机 pairing token>",
  "server_name": "wechat-bot-mcp",
  "transport": "streamable-http",
  "auth_header": "Authorization: Bearer <token>"
}

• X-API-Key が必要です（このエンドポイントは api_key の免除リストに含まれません）。ライセンスの免除対象には追加済みのため、未アクティベートでも取得でき、先に設定してからアクティベートできます。
• 404 { code: "MCP_DISABLED" } が返された場合：現在の exe は MCP 版ではありません（通常は yoko_rpa_mcp.exe をダウンロードしてください）。

4.2 mcp.json の設定スニペットを作成

以下のスニペットをユーザーに渡します（token は実際の値に置き換えてください）。Streamable-HTTP トランスポート、Bearer 認証を使用します。

{
  "mcpServers": {
    "yoko-wechat-rpa": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:9922/mcp",
      "headers": { "Authorization": "Bearer yoko_mcp_xxxxxxxx" }
    }
  }
}

ホストによってフィールドに多少の違いがあります（"transport": "http" を使う場合や、"url" をトップレベルに置く場合、または Bearer の代わりに X-Yoko-Token ヘッダーを使う場合があります）。 ホストが「設定用プロンプト」に対応している場合は、上記の URL と token に基づいてホストのエージェント自身に設定を書き込ませることもできます。

4.3 設定と再読み込みをユーザーに案内

「この設定をホストの mcp.json に追加してください（または、ホストの MCP 追加画面で URL と token を入力してください）。保存したら、ホストを再起動／再読み込みしてください。再読み込み後、WeChat 関連のツールが自動的に表示され、すぐに使えるようになります。」

重要：このスキルのセッション中に、設定したばかりの MCP ツールを呼び出すことはできません。ホストが設定を再読み込みした後、新しいセッションでツールがネイティブに利用可能になります。これは MCP の仕様であり、障害ではありません。

4.4 動作確認

ユーザーが再読み込みした後、新しいセッションでホストエージェントに次を行わせます：

• ツールを一覧表示します。wechat_* 系のツールが約27個表示されるはずです（tools/list）。
• wechat_license_info を呼び出します → licensed / machine_code / agent_id が返され、認証と紐付けが正常であることを確認します。
• wechat_rpa_read_manual を { "topic": "index" } で呼び出します → マニュアルの目次が取得され、マニュアルを読み取れることを確認します。

---

5. MCP ツールで WeChat を操作する（再読み込み後）

原則：複雑な機能は、まずマニュアルを読んでから呼び出します。 ツールの説明では、SOP 系ツールにゲート「まず wechat_rpa_read_manual({topic}) を呼び出す必要があります」が設定されています。マニュアルは exe に含まれています（mcp_manuals/）。wechat_rpa_read_manual で読み取ってください。パラメーターを捏造しないでください。

機能マップ（意図 → ツール → 事前に読むマニュアル）

意図	MCP ツール	事前に読むマニュアルの topic
テキストメッセージを送信	wechat_send_message	—
ファイルを送信	wechat_send_file	—
実際の音声バブルを送信	wechat_send_voice / wechat_list_voices	voice_send_sop
モーメンツへの投稿／モーメンツへの予約投稿	wechat_post_moment / wechat_create_moment_plan / wechat_create_moment_post_task / wechat_cancel_moment_post_task	moment_post_sop
AI モーメンツ自動投稿のオン／オフ	wechat_toggle_ai_moment（個別のマニュアルはありません。パラメーターはツールの説明を参照してください。エージェントの設定については config_schema を参照してください）	—
一斉送信	wechat_mass_sending	—
友だち追加／友だち承認 SOP	（関連ツールは tools/list を参照）	auto_add_friend_sop
連絡先の取得／同期	wechat_get_contacts / wechat_sync_contacts	—
最新メッセージを取得	wechat_fetch_latest_messages	—
グループチャットの要約／会話履歴	wechat_list_sessions / wechat_get_session_messages	group_summary_sop
設定の読み取り／書き込み	wechat_get_config / wechat_update_config	config_schema
タスクとログ	wechat_get_tasks / wechat_get_task_logs	task_schema / task_log_schema
複数インスタンスのローカルアカウント	wechat_list_local_users	multi_instance_sop
WeChat の初期化	wechat_initialize	basic_setup_checklist
手動コンソールを開く	wechat_open_console → http://127.0.0.1:9922/ を返します	—
認証／紐付けのトラブルシューティング	wechat_license_info	—
サービスの自己復旧	wechat_service_status / wechat_restart_service / wechat_launch_wechat	—

exe 内の実際のマニュアル（wechat_rpa_read_manual で有効な topic）：index、basic_setup_checklist、multi_instance_sop、voice_send_sop、moment_post_sop、group_summary_sop、auto_add_friend_sop、config_schema、task_schema、task_log_schema。ツール名／パラメーターは、ホスト上の実際の tools/list に従ってください。

メッセージ送信のベストプラクティス（ホストエージェントへの注意）：ユーザーが指定した連絡先の備考名またはニックネームをそのまま使用してください。RPA があいまい一致で検索します。先に wxid を調べたり、似た名前で代用したりしないでください。

バックグラウンドイベントのプッシュはありません：このバージョンでは、能動的な通知／ハートビートは提供されません（リアルタイムイベントのプッシュチャネルはありません）。タスクの失敗、切断、AI 設定エラーなどの状態は、必要に応じて照会してください。必要なときに wechat_service_status / wechat_get_task_logs を呼び出すか、ユーザーにコンソール（wechat_open_console）を開いて確認するよう案内してください。問題が起きたら自動で通知されるとユーザーに約束しないでください。

---

6. ライフサイクル／復旧／手動での代替手段

yoko_rpa_mcp.exe には supervisor と3つの自動起動経路が組み込まれており、ほとんどの場合、手作業は不要です。

シナリオ	復旧方法
worker（RPA）がクラッシュ／強制終了された	supervisor が数秒以内に自動再起動します（終了コード／ハートビート／health による3重監視）
supervisor が強制終了された	タスクスケジューラの restart-on-failure と定期的な再起動／次回ログイン時の3経路での自動起動
サービスには接続できるが、応答しない	ホストから wechat_restart_service を呼び出します（9921 制御チャネル経由で worker を再起動）
すべて停止した	ユーザーがデスクトップの「微信RPAを起動」をダブルクリックするか、トレイの「サービスを再起動」を選択します
exe がウイルス対策ソフトによって隔離された	除外リストへの追加／再インストールを案内します（コード署名により誤検知を低減）

手動コンソール：サービスの実行中は http://127.0.0.1:9922/ が完全なビジュアルインターフェースになります（MCP と同じバックエンド状態を共有し、変更はリアルタイムに相互反映されます）。複雑な操作は、ユーザーにここで手動実行するよう案内できます。

サービスの停止：サンドボックス内では、セッションの分離により taskkill によるセッションをまたいだ終了は必ず失敗します。自分で試さないでください。サービスはインストーラー／自動起動によって常駐するため、通常は停止する必要はありません。停止／アンインストールが必要な場合は、「設定 → アプリ → 『微信 RPA MCP サービス』をアンインストール」の手順をユーザーに案内してください（アンインストールにより自動起動の設定が削除され、プロセスが終了します）。または、タスクマネージャーで yoko_rpa_mcp.exe を終了するよう案内してください（注意：次回起動時に自動起動によって再び起動します。完全に無効化するには、アンインストールするか、§6 の wechat_restart_service 以外の方法を使用する必要があります）。

---

7. メンテナンスに関する注意事項

• ホストへのプッシュはありません：このバージョンではリアルタイムイベント／ハートビートはありません（ホストへの能動的なプッシュチャネルはありません）。状態は必要に応じて照会してください（§5 の末尾）。
• マニュアルは exe 内のものが正です：SOP/schema マニュアルは yoko_rpa_mcp.exe に含まれており、wechat_rpa_read_manual で読み取ります。この skill リポジトリでは REST 版の docs/ をメンテナンスしません。有効な topic は §5 の表の下にある一覧を参照してください。
• ツール一覧は実行時の tools/list に従ってください：現在のバージョンにはツールが27個あります（動作確認済み）。exe のアップグレードは、最新の yoko_rpa_mcp_setup.exe を再実行して行います（インストーラーがアップグレードを認識し、古いインスタンスを終了して再インストールし、自動起動を再設定します）。
• 2種類の認証を混同しないでください：REST の setup 呼び出しでは X-API-Key: yoko_test を使用します。MCP では /api/mcp/token で取得した Bearer ペアリングトークンを使用します。