WeChat RPA Bot Skill

这是一个专为 AI 智能体（如 OpenClaw、YoBot私域龙虾、QClaw 等）设计的、强大且独立的微信 RPA（机器人流程自动化）技能。

该技能允许任何 AI 智能体通过 HTTP REST API 自主安装、配置、启动和控制本地微信桌面端实例。它弥合了大语言模型（LLM）推理与真实世界微信操作之间的鸿沟。

🛡️ 安全与隐私声明 (Security & Privacy Declaration)

🔒 数据完全本地化：本工具处理的所有微信聊天记录、通讯录、朋友圈等信息，全部仅在用户的本地计算机上处理和保存。本工具没有任何数据外发或上报机制。
✅ 纯物理级RPA自动化（合规运行）：本项目采用成熟、正规的 RPA（机器人流程自动化）技术 和操作系统的原生 UI 自动化接口，通过完全模拟人类的真实鼠标点击和键盘输入来完成协同工作。不采用底层技术修改（如内存修改），不会读取微信数据库及私有协议。
🛡️ 绿色的本地协同工具：本工具的设计初衷是帮助用户提高日常工作效率，运行逻辑公开透明。代码库完全开放，无任何隐藏的远控或非法行为。

🌟 核心特性

智能体友好 (Agent-Friendly)：从底层开始专门针对 AI 智能体的轻松安装和调用而构建。
无头后端 (Headless Backend)：在后台静默运行，暴露出丰富的 REST API 接口（http://127.0.0.1:9922）。
自主初始化 (Autonomous Initialization)：智能体可以在无需人工干预的情况下启动服务并自动绑定到微信。
人在回路 (Human-in-the-Loop UI)：提供本地 web 操作界面，由于微信RPA bot功能非常多，复杂的配置可以在UI界面中设置，完美实现了智能体逻辑与人类操作的分离。

📦 安装指南（面向 AI 智能体）

智能体可以通过以下步骤自主安装此技能：

确认微信版本（重要）：
本技能只支持微信桌面版 4.1.7，不支持其他版本（包括更高版本）。
- 版本确认方法：打开微信 → 帮助 → 关于 → 查看版本号是否为 4.1.7
- 如果版本不符，需先卸载当前微信，再安装指定版本：
  👉 下载微信 4.1.7 安装包

克隆代码库：

git clone https://github.com/LeoMusk/wechat-rpa-bot-skill.git
cd wechat-rpa-bot-skill

下载核心服务组件 (service.exe)：
此技能依赖 RPA 后端服务。智能体需要从本仓库的 Releases 页面下载 service.exe（如 wechat rpa bot service-v1.7.0 中的附件），并将其放置在 wechat-rpa-bot-skill 根目录下。

Agent 可以使用类似以下的命令自动下载（注意替换为最新的 release URL）：
```
curl -L -o service.exe https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/download/v1.7.0/service.exe
```
安装 Python 依赖（用于启动脚本）：

pip install psutil requests

无需额外配置认证（Token）：
现在项目采用**激活码 (Activation Code)**方式认证。激活码可在 www.yokoagi.com 获取。智能体只需在服务启动后，引导用户提供激活码，并直接调用自带的激活接口完成绑定，无需用户手动修改环境变量。

� 快速更新指南 (面向普通用户)

由于该 Skill 的能力迭代非常频繁（包含接口升级、新文档、启动逻辑优化等），为了确保您体验到最新的 RPA 功能，建议定期更新代码库。

您无需手动敲命令去拉取代码，只需直接对您的 Agent（如 QClaw、OpenClaw 等）发送以下提示词（Prompt）：

"微信 RPA Skill 更新了，请帮我重新安装/拉取下最新代码：https://github.com/LeoMusk/wechat-rpa-bot-skill.git"

Agent 接收到此指令后，通常会自动检测该本地代码仓库的变更，帮您执行 git pull 拉取最新代码，甚至重新下载依赖和二进制文件，让您的技能一键保持最新状态！

� 使用指南

1. 启动服务

在尝试进行任何微信操作之前，智能体应该先启动 RPA 后端服务。运行提供的启动脚本：

python scripts/start_server.py

此脚本会自动清理旧进程，启动后端服务（service.exe 或 server.py），并等待健康检查完成。

2. 软件激活 (Agent 自动操作)

服务启动后，如果未激活，智能体（如 OpenClaw）可以引导用户提供激活码。
智能体获取到激活码后，可以直接调用自带的 REST API 工具完成设备激活：

调用 GET /api/license/machine-code 获取当前机器码。
调用 POST /api/license/activate 传入 activation_code 和 machine_code 激活。

话术参考："微信RPA服务已启动，请提供您的激活码，我将为您自动完成设备绑定。"

3. 可视化 UI 界面 (Human-in-the-Loop)

该技能自带完整的前端操作界面（位于 webot/ 目录下），服务启动后，该界面会自动挂载在根路由下。
当您的微信实例初始化成功后，您可以随时向 Agent 发送如下提示词来打开界面进行复杂配置或查看日志：

"帮我打开微信 RPA 的配置界面。"

Agent 会尝试自动在您的浏览器中唤起 http://127.0.0.1:9922/，或者直接提供一个可点击的链接供您访问。

4. 常见问题排查与高级说明

沙箱隔离问题 (启动无反应/找不到微信)：
由于 QClaw 等智能体通常运行在隔离的沙箱（Sandbox）中，它们无法直接控制您物理桌面的微信。因此，不要让 Agent 强行在后台启动服务。Agent 会在您的桌面生成一个 启动微信RPA.bat 脚本，请您手动双击该脚本，这样服务就能在您的真实桌面环境中运行，完美识别您的微信。
RPA 服务的退出与残留 (9922端口占用)：
RPA 服务作为独立的后端进程（Headless Daemon）运行。即使您关闭了 Agent (QClaw) 或者关闭了浏览器 UI 界面，RPA 服务依然会在后台继续运行。
Agent 在生成启动脚本时会同时在桌面生成 停止微信RPA.bat，使用完毕后双击即可停止服务。如需手动停止，也可在技能目录执行：
```
python scripts/stop_server.py
```
注意：下次启动时 启动微信RPA.bat 会自动清理残留进程，无需手动操作。
前端 UI 加载与挂载时机：
本项目采用了前后端分离架构。当您启动服务后，虽然 http://127.0.0.1:9922/ 已经可以访问，但在微信实例成功初始化并登录之前，前端界面会提示“微信掉线”或只显示部分组件。
正确流程：让 Agent 帮您启动服务 -> Agent 调用接口完成微信初始化 -> Agent 将前端 UI 链接 (http://127.0.0.1:9922/) 发送给您 -> 您在浏览器中打开，即可进行全功能的可视化配置。

5. API 控制

激活并登录成功后，智能体即可通过 REST API 控制微信。

基础 URL (Base URL)：http://127.0.0.1:9922
认证请求头 (Auth Header)：所有请求必须携带 X-API-Key: yoko_test

示例：发送消息（⚠️ 必须注意中文编码）

重要提示：Windows PowerShell 的 Invoke-RestMethod 默认以 ISO-8859-1 发送字符串，会导致微信发送中文乱码。智能体必须使用 curl.exe 或 Python requests 来调用接口。

# 单微信实例（常见场景）
curl.exe -X POST http://127.0.0.1:9922/api/chat/send_message \
     -H "Content-Type: application/json" \
     -H "X-API-Key: yoko_test" \
     -d "{\"user\": \"文件传输助手\", \"message\": \"你好，这是来自智能体的消息！\"}"

# 多微信实例（通过 account_id 指定发送方账号）
curl.exe -X POST http://127.0.0.1:9922/api/chat/send_message \
     -H "Content-Type: application/json" \
     -H "X-API-Key: yoko_test" \
     -d "{\"user\": \"文件传输助手\", \"message\": \"你好！\", \"account_id\": \"wxid_xxx\"}"

参数说明：user 是接收消息的联系人备注名/昵称；account_id 是发送方微信实例的标识符，仅在同一台机器运行多个微信账号时才需要传入。

5. 支持的 RPA 能力及提示词案例

目前该 Skill 已经全面接入了本地微信 RPA 的各项核心能力，支持 Agent 渐进式读取文档以执行复杂任务。以下是支持的功能列表以及您可以对 Agent 说的提示词（Prompt）案例：

⭕ 朋友圈管理 (Post Moment)
- 能力：自动发布纯文本或带图/视频的朋友圈。
- 提示词案例："帮我发一条朋友圈，内容是'今天天气真好，适合开发新的 AI Agent！'，并附带一张工作台照片（路径：C:\images\workspace.jpg）。"
📩 消息收发 (Messaging)
- 能力：向指定好友或群聊发送文本、图片、文件；获取历史聊天记录。
- 提示词案例："给'文件传输助手'发送一份本月的财务报表，文件路径是 D:\reports\march.xlsx，并留言'这是本月的报表请查收'。"
📢 批量群发 (Mass Sending)
- 能力：根据好友标签（Tags）或指定目标列表（Targets）创建定时或即时的群发任务。
- 提示词案例："帮我创建一个群发任务，给标签为'VIP客户'的好友群发一条早安问候：'祝大家国庆节快乐！'，每批发送10人。"
🤖 AI 自动化功能控制 (AI Features Toggle)
- 能力：动态开启或关闭 RPA 后台的各种 AI 托管功能（如：AI 销售助手、AI 朋友圈自动互动、自动通过新好友请求）。
- 提示词案例："帮我开启微信的'自动通过新好友'功能，并打开'AI朋友圈自动互动'。"
👥 其他辅助能力
- 任务状态查询：获取 RPA 任务执行状态列表（"帮我看看现在的群发任务进度如何"）。
- 通讯录同步：同步最新的微信通讯录和群聊列表。

📚 微信RPA机器人操作文档