| name | wxauto |
| description | 微信自动化操作。通过 wxautox4 RESTful API 实现发送消息、获取聊天记录、监听消息、好友管理等功能。Use when: (1) 发送微信消息给好友或群聊，(2) 读取微信聊天记录，(3) 监听新消息，(4) 获取好友列表或群聊列表，(5) 接受好友申请，(6) 切换聊天窗口等微信操作。 |
微信自动化
通过本地 HTTP 服务操作微信，支持消息收发、监听、好友管理等功能。
前置要求
-
安装 wxautox4：
pip install wxautox4
注意：需windows系统，python3.9,3.10,3.11,3.12 64位，其他python版本暂不支持
-
激活 wxautox4：
wxautox4 -a your-activation-code
获取：https://docs.wxauto.org/plus
-
部署 API 服务：
服务配置
- 认证：Bearer Token（见
config.yaml 的 auth.token，默认值为 token）
- 服务状态文件：
~/.wxautox/service_status.json（服务启动时自动生成，请查看该文件获取服务信息）
自动配置检测
服务启动后会自动将运行信息写入 ~/.wxautox/service_status.json。wxapi.py 脚本会：
- 自动读取此文件获取连接配置
- 验证服务是否真的在运行（通过 API 健康检查）
- 如果服务未运行，自动启动服务（需要服务目录存在）
服务目录搜索顺序：
../wxauto-restful-api（相对于 skill 目录）~/wxauto-restful-apiWXAPI_SERVICE_DIR 环境变量指定的路径
手动配置方式（可选）
如果需要覆盖自动配置，优先级从高到低：
-
命令行参数
python wxapi.py --base-url "http://localhost:9000" --token "my-token" send "好友" "消息"
-
环境变量
$env:WXAPI_BASE_URL = "http://localhost:9000"
$env:WXAPI_TOKEN = "my-token"
# 或者
$env:WXAPI_PORT = "9000"
$env:WXAPI_SERVICE_DIR = "/path/to/wxauto-restful-api"
-
service_status.json - 自动检测（推荐）
-
config.yaml - 服务目录下的配置文件
-
默认值 - http://localhost:8000, token 为 token
启动服务
首次使用前需要启动服务：
# 进入服务目录
cd /path/to/wxauto-restful-api
启动服务
python run.py
或后台启动（Windows）：
Start-Process python -ArgumentList "run.py" -WorkingDirectory "C:\path\to\wxauto-restful-api" -WindowStyle Hidden
如果服务已运行，脚本会自动连接；如果服务未运行且配置了服务目录，脚本会自动启动服务。
脚本路径
Python 调用脚本位于 skill 目录下的 scripts/wxapi.py。
使用 {baseDir} 引用 skill 目录：
python "{baseDir}/scripts/wxapi.py" send "好友" "消息"
可用命令
初始化和状态
# 初始化微信实例
python wxapi.py init
# 获取服务状态
python wxapi.py status
# 检查是否在线
python wxapi.py online
# 获取我的信息
python wxapi.py myinfo
发送消息
# 主窗口发送
python wxapi.py send "好友名" "消息内容"
# 精确匹配
python wxapi.py send "好友名" "消息内容" --exact
# @群成员
python wxapi.py send "群名" "开会了" --at "张三,李四"
# 子窗口发送
python wxapi.py send-chat "好友名" "消息内容"
读取消息
# 获取聊天记录（主窗口）
python wxapi.py getmsg "好友名"
# 获取聊天记录（子窗口）
python wxapi.py getmsg-chat "好友名"
# 获取历史消息
python wxapi.py history "好友名" --count 100
# 获取新消息（主窗口轮询）
python wxapi.py newmsg
# 获取新消息（子窗口）
python wxapi.py newmsg-chat "好友名"
监听管理
# 添加监听（打开子窗口）
python wxapi.py listen "好友名"
会话管理
# 获取会话列表
python wxapi.py session
# 获取所有子窗口
python wxapi.py windows
# 切换聊天窗口
python wxapi.py chatwith "好友名" --exact
获取列表
# 好友列表
python wxapi.py friends
# 群聊列表
python wxapi.py groups
页面控制
# 切换到聊天页面
python wxapi.py switch-chat
# 切换到联系人页面
python wxapi.py switch-contact
查看帮助
python wxapi.py --help
API 接口列表
根据 wxauto-restful-api 服务：
微信功能接口
| 接口 | 说明 |
|---|
POST /v1/wechat/initialize | 初始化微信实例 |
GET /v1/wechat/status | 获取微信状态 |
POST /v1/wechat/send | 发送消息 |
POST /v1/wechat/sendfile | 发送文件 |
POST /v1/wechat/sendurlcard | 发送 URL 卡片 |
POST /v1/wechat/getallmessage | 获取当前窗口消息 |
POST /v1/wechat/gethistorymessage | 获取历史消息 |
POST /v1/wechat/getnextnewmessage | 获取新消息 |
POST /v1/wechat/getsession | 获取会话列表 |
POST /v1/wechat/getsubwindow | 获取指定子窗口 |
POST /v1/wechat/getallsubwindow | 获取所有子窗口 |
POST /v1/wechat/chatwith | 切换聊天窗口 |
POST /v1/wechat/getfriends | 获取好友列表 |
POST /v1/wechat/getmyinfo | 获取我的信息 |
POST /v1/wechat/getrecentgroups | 获取群聊列表 |
POST /v1/wechat/switch/chat | 切换到聊天页面 |
POST /v1/wechat/switch/contact | 切换到联系人页面 |
POST /v1/wechat/isonline | 检查在线状态 |
聊天接口（子窗口）
| 接口 | 说明 |
|---|
POST /v1/chat/send | 子窗口发送消息 |
POST /v1/chat/getallmessage | 获取子窗口所有消息 |
POST /v1/chat/getnewmessage | 获取子窗口新消息 |
POST /v1/chat/msg/quote | 发送引用消息 |
POST /v1/chat/close | 关闭子窗口 |
直接 API 调用（备选）
如需直接调用 HTTP API，用 Python（不要用 PowerShell，有中文编码问题）：
import requests
headers = {"Authorization": "Bearer token", "Content-Type": "application/json"}
body = {"who": "好友名", "msg": "消息内容"}
resp = requests.post("http://localhost:8000/v1/wechat/send", headers=headers, json=body)
print(resp.json())
响应格式
所有 API 返回统一格式：
{
"success": true,
"message": "操作成功",
"data": { ... }
}
注意事项
- 微信客户端需要保持打开状态
- wxautox4 需要激活后才能使用
- 不要用 PowerShell 直接调用 API（中文编码问题），请使用 Python 脚本
- 修改
config.yaml 中的 auth.token 以增强安全性
