wechat-rpa-bot

WeChat RPA Bot Skill (MCP edition)

This skill turns any MCP-capable host (OpenClaw / QClaw / WorkBuddy …) into a WeChat assistant by onboarding the local yoko WeChat RPA MCP server and then driving WeChat through its MCP tools.

Mental model (must understand first)

WeChat automation capability is provided by yoko_rpa_mcp.exe resident on the user's desktop (Session 1), port 9922, same process, three interfaces:
- /mcp — Streamable-HTTP MCP endpoint(the main channel of this skill, Bearer token authentication)
- /api/* — REST (this skill only uses it forinstall/activate/get tokenand other setup steps)
- / — Visual console (manual fallback)
This skill does not send WeChat messages directly: it is responsible for installing the MCP server, starting it, activating it, and writing the /mcp + token into the host's mcp.json. Once the host reloads the configuration, ~27 WeChat tools willnativelyappear in the host, and thereafter be called directly by the host Agent.
Agent Never spawn this exe yourself: a spawned process will inherit the sandbox/session isolation and cannot see the WeChat desktop. The exe must be started by the user in their own interactive session (once on first launch; afterward the exe self-registers for startup on boot and automatically revives).

0. End-to-end flow overview

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

1. Installation (the user runs the installer; the Agent only guides)

⚠️ This step is completed by the user themselves, it is not automatic. The WeChat capability is provided by a desktop program, installed via the official installer yoko_rpa_mcp_setup.exe . The Agent is only responsible for explaining the steps clearly and giving the download link;do notsilently install on the user's behalf, and alsodo notrun the installer or exe yourself—for the reason see §2 (sandbox/session isolation will prevent automatically launched processes from operating WeChat). Please tell the user clearly and in one go: "WeChat automation requires installing a local program on your computer. Below I will send you the download and installation steps. You need to run the installer yourself once (it will prompt for administrator confirmation)."

Confirm the environment:Windows + WeChat desktop version ≥ 4.1.7(voice sending requires ≥ 4.1.9）。
- Version check: WeChat → Help → About; if the version is wrong, upgrade from the official channel.
Download and run the installer yoko_rpa_mcp_setup.exe(Inno Setup installer package):
- Download address:https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/latest/download/yoko_rpa_mcp_setup.exe
- The Agent may download it to the user's Downloads directory on their behalf, then ask the user to double-click to run it (the Agent must not run the installer itself):
```
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
```
- The user double-clicks to run → UAC pops up, need to click "Yes" to grant administrator privileges(installs to C:\Program Files\yoko_rpa_mcp\, ASCII path avoids Chinese path loading issues).
- The installer will automatically: ① install the program to Program Files; ② as a normal user(non-administrator, landing in the user interactive session Session 1) immediately start the service --supervisor --no-ui; ③ registerthree-channel startup on boot(logon scheduled task + HKCU Run key + Startup folder); ④ create desktop/Start menu icon "WeChat RPA MCP Service"。
- It is already running after installation, no need to start it manually again. The exe itself is at C:\Program Files\yoko_rpa_mcp\yoko_rpa_mcp.exe(the skill itself no longer bundles the exe).
VB-Cable virtual audio driver(only needed for "voice message sending"): from https://vb-audio.com/Cable/ download and install,Restart the computer after installation. Functions such as text/image/file are not needed.
No need for .env: uses anactivation codesystem; the activation code is obtained from www.yokoagi.com .

2. Confirm the service is running (the installer has already started it automatically; usually no manual action is needed)

Why can't you spawn it yourself: WeChat automation relies on simulating real mouse and keyboard on the user'svisible desktop. If the Agent (especially inside a sandbox) launches the exe itself, it lands in an isolated session where it cannot see WeChat.This is by design— the service runs in the user session via the installer/autostart, and you only act as a network client.

Step 1 — Health check. GET http://127.0.0.1:9922/api/health(localhost, proxy disabled). A response means the service is ready → skip to §3 to check activation. After the installer finishes, it usually comes up within a few seconds; you can poll every ~3s for up to ~2 minutes,do not wait for the user to type。

Step 2 — If it hasn't come up (rare case). The installer starts it automatically after installation and has already registered autostart on boot, so normally no manual action is needed. If /api/health never responds, guide the user:

"Please double-click the "WeChat RPA MCP Service" icon on the desktop to start it (or open it from the Start menu). After starting,no need to reply to me; I will automatically detect readiness and continue."

Then continue polling /api/health. If it still doesn't work, ask the user whether there is an error popup, or refer to §6 for recovery methods.

Autostart on boot: The installer has registered three-channel autostart + a crash self-healing daemon,so it will be ready automatically on the next boot, and users do not need to manually start or stop it in daily use.

3. Activate License (via REST, setup operation)

First probe the initialization state once to determine whether it is already activated:

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

If the service returnsactivated(subsequent MCP connections do not return 403) → skip to §4.
Ifnot activated：
1. tell the user: "The software is not yet activated. Please go to www.yokoagi.com to obtain an activation code, and send it to me once you have it; I will activate it automatically."
2. After the user provides the code:
```
POST http://127.0.0.1:9922/api/license/activate
Body: { "activation_code": "<用户提供>", "machine_code": "<step 1>" }
```
3. Success means you can continue. Each MCP endpoint connection verifies the license (not activated/expired → 403 and returns machine_code).

Note: REST setup calls must include X-API-Key: yoko_test(localhost, proxy disabled). The MCP channel uses a different Bearer token, see §4; do not mix them up.

4. Connect to MCP (the core of this skill)

4.1 Get the MCP token

The token is a local random key (not equal to the activation code, and the activation code is not exposed), written to disk on first run at ~/.yokowebot/mcp_token.dat. In a sandbox, the agent usually cannot read this file, so obtain it from the dedicated backend endpoint (already implemented):

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

On success, returns:

{
  "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>"
}

Must include X-API-Key(this endpoint is not in the api_key exemption list); it can also be obtained when not activated (it has been added to the license exemption), making it convenient to configure first and activate later.
If it returns 404 { code: "MCP_DISABLED" }: this means the current exe is not the MCP version (normally you should download yoko_rpa_mcp.exe）。

4.2 Generate the mcp.json snippet

Give the following snippet to the user (replace token with the actual value). Streamable-HTTP transport, Bearer authentication:

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

Different hosts have slightly different fields (some use "transport": "http" / "url" top-level / or X-Yoko-Token header instead of Bearer). If the host supports "configuration phrasing", you can have the host Agent write it in itself based on the URL + token above.

4.3 Guide the user to assemble and reload

"Please add this configuration to your host's mcp.json(or use the host's MCP add entry to fill in the URL and token), save it, thenrestart/reload the host. After reloading, the WeChat-related tools will appear automatically, and we can use them directly thereafter."

Important: This skill sessioncannot on the spotcall the just-configured MCP tools—the host must reload the configuration before the tools become natively available ina new session. This is an inherent mechanism of MCP, not a fault.

4.4 Liveness check

After the user reloads, in a new session have the host Agent:

List tools: it should see the wechat_* series of ~27 tools (tools/list）。
Call wechat_license_info → returns licensed / machine_code / agent_id, confirming authorization and ownership are normal.
Call wechat_rpa_read_manual with { "topic": "index" } → get the manual directory, confirming the manual is readable.

5. Drive WeChat with MCP tools (after reload)

Discipline: for complex capabilities, read the manual first, then call. The tool descriptions set a gate for SOP-type tools: "You must first wechat_rpa_read_manual({topic})". The manual has been embedded into the exe (mcp_manuals/), read via wechat_rpa_read_manual ,do not invent parameters。

Capability map (intent → tool → read manual first)

Intent	MCP tool	Read manual topic first
Send text message	`wechat_send_message`	—
Send file	`wechat_send_file`	—
Sendreal voice bubble	`wechat_send_voice` / `wechat_list_voices`	`voice_send_sop`
Post Moments / scheduled Moments	`wechat_post_moment` / `wechat_create_moment_plan` / `wechat_create_moment_post_task` / `wechat_cancel_moment_post_task`	`moment_post_sop`
AI auto Moments toggle	`wechat_toggle_ai_moment`(no standalone manual; see tool description for parameters; for config agent refer to `config_schema`）	—
Mass send	`wechat_mass_sending`	—
Add friend / pass friend SOP	(related tools, see tools/list)	`auto_add_friend_sop`
Read contacts / sync contacts	`wechat_get_contacts` / `wechat_sync_contacts`	—
Fetch latest messages	`wechat_fetch_latest_messages`	—
Group chat summary / conversation history	`wechat_list_sessions` / `wechat_get_session_messages`	`group_summary_sop`
Config read/write	`wechat_get_config` / `wechat_update_config`	`config_schema`
Tasks and logs	`wechat_get_tasks` / `wechat_get_task_logs`	`task_schema` / `task_log_schema`
Multi-instance local accounts	`wechat_list_local_users`	`multi_instance_sop`
Initialize WeChat	`wechat_initialize`	`basic_setup_checklist`
Open manual console	`wechat_open_console` → returns `http://127.0.0.1:9922/`	—
Authorization/ownership troubleshooting	`wechat_license_info`	—
Service self-healing	`wechat_service_status` / `wechat_restart_service` / `wechat_launch_wechat`	—

The actual manual inside the exe (wechat_rpa_read_manual legal topics):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. Tool names/parameters are subject to the host's actual tools/list .

Messaging best practices (remind the host Agent): Just use the contact remark name/nickname the user provided directly; RPA will fuzzy match,do notlook up the wxid first, and do not substitute a similar name.

No background event push: This version does not provide proactive notifications/heartbeats (there is no real-time event push channel). For statuses such as task failure, disconnection, AI configuration errors, pleasequery on demand—when needed call wechat_service_status / wechat_get_task_logs, or guide the user to open the console (wechat_open_console) to check.Do notpromise users that "problems will be automatically alerted."

6. Lifecycle / Recovery / Manual Fallback

yoko_rpa_mcp.exe Built-in supervisor + three-channel auto-start; in most cases no manual intervention is needed:

Scenario	Recovery
worker (RPA) crashes/is killed	supervisor automatically restarts within seconds (triple monitoring via exit code/heartbeat/health)
supervisor is killed	Scheduled task restart-on-failure + periodic revival / three-channel auto-start on next login
Service can connect but is stuck	Host calls `wechat_restart_service`(restarts worker via the 9921 control channel)
All stopped	User double-clicks the desktop "Start WeChat RPA", or the tray "Restart Service"
exe is quarantined by antivirus	Guide adding to whitelist/reinstall (code signing reduces false positives)

Manual console: while the service is running, http://127.0.0.1:9922/ is the full visual interface (shares the same backend state with MCP; changes sync in real time). For complex operations, guide the user to complete them manually here.

Stop service: inside the sandbox, taskkill will always fail across sessions (Session isolation); do not try it yourself. The service runs persistently via the installer/auto-start and normally does not need to be stopped. If it truly needs to be stopped/uninstalled, guide the user to "Settings → Apps → Uninstall 'WeChat RPA MCP Service'" (uninstalling will clean up auto-start and kill the process), or have the user end yoko_rpa_mcp.exein Task Manager (note that auto-start on boot will launch it again; to fully disable it, uninstall or use the means in §6 other than wechat_restart_service ).

7. Maintenance Notes

No host push: this version does not do real-time events/heartbeats (there is no active push channel to the host). Query status on demand (end of §5).
The manual is authoritative as inside the exe: the SOP/schema manual is packed into yoko_rpa_mcp.exe, read via wechat_rpa_read_manual ; this skill repository no longer maintains the REST version docs/. For valid topics, see the list under the §5 table.
The tool list is authoritative as the runtime tools/list : the current version has 27 tools (already tested). exe upgrades are completed by rerunning the latest(the installer recognizes upgrades, closes the old instance, reinstalls, and resets auto-start). yoko_rpa_mcp_setup.exe Completed (installer detects upgrade, closes old instance, reinstalls and resets autostart).
Do not mix the two authentication sets: REST setup calls use X-API-Key: yoko_test; MCP uses the Bearer pairing token obtained by /api/mcp/token .