wechat-rpa-bot

name	wechat-rpa-bot
description	Onboard and drive the yoko WeChat RPA MCP server. Use this skill to install yoko_rpa_mcp.exe, start it, activate the license, wire its local MCP endpoint into the host (mcp.json), and then use WeChat automation through the MCP tools it exposes.

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.

心智模型（务必先理解）

• 微信自动化能力由 yoko_rpa_mcp.exe 在用户桌面(Session 1)常驻提供，端口 9922，同一进程三门面：
  • /mcp — Streamable-HTTP MCP 端点（本技能的主通道，Bearer token 鉴权）
  • /api/* — REST（本技能只在安装/激活/取 token等 setup 步骤用它）
  • / — 可视化控制台（手动兜底）
• 本技能不直接发微信：它负责把 MCP server 装好、拉起、激活、把 /mcp + token 写进宿主的 mcp.json。 一旦宿主重载配置，~27 个微信工具就原生出现在宿主里，之后由宿主 Agent 直接调用。
• Agent 绝不能自己 spawn 这个 exe：被 spawn 的进程会继承沙箱/会话隔离，看不见微信桌面。exe 必须由 用户在自己的交互会话里启动（首启一次；之后 exe 自注册开机自启，自动复活）。

---

0. 端到端流程总览

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

---

1. 安装（用户运行安装器，Agent 只做引导）

⚠️ 这一步由用户本人完成，不是自动的。 微信能力由一个桌面程序提供，通过官方安装器 yoko_rpa_mcp_setup.exe 安装。 Agent 只负责把步骤讲清楚、给出下载链接；不要替用户静默安装，也不要自己去运行安装器或 exe——原因见 §2（沙箱/会话隔离会让自动拉起的进程操作不了微信）。 请一次性、清楚地告诉用户：「微信自动化需要在您电脑上装一个本地程序，下面我把下载和安装步骤发给您，需要您亲自运行一次安装器（会弹管理员确认）。」

1. 确认环境：Windows + 微信桌面版 ≥ 4.1.7（语音发送需 ≥ 4.1.9）。
   • 版本查看：微信 → 帮助 → 关于；版本不对从官方渠道升级。
2. 下载并运行安装器 yoko_rpa_mcp_setup.exe（Inno Setup 安装包）：
   • 下载地址：https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/latest/download/yoko_rpa_mcp_setup.exe
   • Agent 可代下载到用户的下载目录，再请用户双击运行（Agent 不要自己运行安装器）：

     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；③ 注册三通道开机自启（登录计划任务 + 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/ 下载安装，装后重启电脑。文本/图片/文件等功能不需要。
4. 无需 .env：采用激活码体系，激活码从 www.yokoagi.com 获取。

---

2. 确认服务在运行（安装器已自动启动，通常无需手动）

为什么不能你来 spawn：微信自动化靠在用户可见桌面上模拟真实鼠标键盘。若 Agent（尤其在沙箱内）自己拉起 exe，它落在隔离会话里看不见微信。由设计如此——服务由安装器/自启在用户会话里跑，你只做网络客户端。

Step 1 — 健康检查。 GET http://127.0.0.1:9922/api/health（localhost 关代理）。有响应说明服务就绪 → 跳到 §3 检查激活。 装完安装器后一般会在数秒内起来；可每 ~3s 轮询，最多 ~2 分钟，不要等用户打字。

Step 2 — 若没起来（少数情况）。 安装器装完会自动启动、且已注册开机自启，正常无需手动。若 /api/health 始终无响应，引导用户：

"请双击桌面上的 「微信 RPA MCP 服务」 图标启动它（或从开始菜单打开）。启动后无需回复我，我会自动检测到就绪并继续。"

然后继续轮询 /api/health。仍不行则问用户是否有报错弹窗，或参考 §6 恢复手段。

开机自启：安装器已注册三通道自启 + 崩溃自愈守护，下次开机自动就绪，用户日常无需手动启停。

---

3. 激活 License（走 REST，setup 操作）

先探一次初始化状态以判断是否已激活：

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 端点每次连接会校验 license（未激活/过期 → 403 并回传 machine_code）。

注：REST 的 setup 调用需带 X-API-Key: yoko_test（localhost 关代理）。MCP 通道用的是另一套 Bearer token，见 §4，别混。

---

4. 接入 MCP（本技能核心）

4.1 取 MCP token

token 是本地随机密钥（不等于激活码，激活码不外泄），首次运行落盘 ~/.yokowebot/mcp_token.dat。 沙箱里 agent 通常读不到该文件，因此从后端专用端点取（已实现）：

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 豁免名单内）；未激活也能取（已加入 license 豁免），方便先配好再激活。
• 若返回 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" 顶层 / 或 X-Yoko-Token 头代替 Bearer）。 若宿主支持「配置话术」，可让宿主 Agent 依据上面 URL + token 自行写入。

4.3 指导用户装配并重载

"请把这段配置加入您宿主的 mcp.json（或用宿主的 MCP 添加入口填入 URL 和 token），保存后重启/重载宿主。重载后微信相关工具会自动出现，之后我们就能直接用了。"

重要：本 skill 会话当场无法调用刚配好的 MCP 工具——宿主需重载配置后，工具才在新会话里原生可用。这是 MCP 的固有机制，不是故障。

4.4 验活

用户重载后，在新会话让宿主 Agent：

• 列工具：应能看到 wechat_* 系列 ~27 个工具（tools/list）。
• 调 wechat_license_info → 返回 licensed / machine_code / agent_id，确认授权与归属正常。
• 调 wechat_rpa_read_manual with { "topic": "index" } → 拿到手册目录，确认手册可读。

---

5. 用 MCP 工具驱动微信（重载后）

纪律：复杂能力先读手册再调用。 工具描述里对 SOP 类工具设了 gate「你必须先 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（无独立手册，参数见工具描述；配 agent 参考 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_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 为准。

发消息最佳实践（提醒宿主 Agent）：直接用用户给的联系人备注名/昵称即可，RPA 会模糊匹配，不要先查 wxid，不要用相似名替代。

无后台事件推送：本版不提供主动通知/心跳（不存在实时事件推送通道）。任务失败、掉线、AI 配置错误等状态请按需查询——需要时调 wechat_service_status / wechat_get_task_logs，或引导用户打开控制台（wechat_open_console）查看。不要向用户承诺"出问题会自动提醒"。

---

6. 生命周期 / 恢复 / 手动兜底

yoko_rpa_mcp.exe 内置 supervisor + 三通道自启，多数情况无需人工：

场景	恢复
worker（RPA）崩溃/被杀	supervisor 秒级自动重启（退出码/心跳/health 三重监控）
supervisor 被杀	计划任务 restart-on-failure + 周期复活 / 下次登录三通道自启
服务能连但卡住	宿主调 wechat_restart_service（经 9921 控制通道重启 worker）
全停	用户双击桌面「启动微信RPA」，或托盘「重启服务」
exe 被杀软隔离	引导加白名单/重装（代码签名降误报）

手动控制台：服务在跑时 http://127.0.0.1:9922/ 即完整可视化界面（与 MCP 共享同一后端状态，改动实时互通）。复杂操作可引导用户在此手动完成。

停止服务：沙箱内 taskkill 跨会话必失败（Session 隔离），别自己尝试。服务由安装器/自启常驻，正常不需要停。若确需停止/卸载，引导用户走「设置 → 应用 → 卸载『微信 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 完成（安装器识别升级、关旧实例、重装并复位自启）。
• 鉴权两套别混：REST setup 调用用 X-API-Key: yoko_test；MCP 用 /api/mcp/token 拿的 Bearer pairing token。