wxauto（wxauto 自动化）

微信自动化

通过 wxautox4 RESTful API 操作微信，支持消息收发、监听、好友管理等功能。API 服务必须运行在 Windows 设备上（wxautox4 仅支持 Windows），可通过本地或远程方式连接。

步骤 0：平台检测（最优先执行）

在做任何其他操作之前，先检测当前设备的操作系统：

import platform
print(platform.system())  # 返回 'Windows' / 'Darwin' / 'Linux'

根据结果走不同分支：

非 Windows 设备（macOS / Linux）

wxautox4 服务只能运行在 Windows 上，不要尝试在当前设备安装或启动服务。

直接询问用户远程服务信息（使用 AskUserQuestion 或等效工具）：

问题1：请提供 wxauto-restful-api 服务地址（例如 http://192.168.1.100:8000）
问题2：请提供服务的 Bearer Token（见服务端 config.yaml 的 auth.token，默认为 token）

获取到地址和 token 后：

1. 将配置写入环境变量或直接传入脚本参数
2. 调用健康检查接口验证连通性：GET /v1/wechat/status
3. 如果连接失败，提示用户检查：网络是否可达、服务是否已启动、token 是否正确
4. 连接成功后直接执行用户操作，不需要任何本地安装步骤

Windows 设备

先检查本地服务是否已运行（读取 ~/.wxautox/service_status.json 并做健康检查）：

• 本地服务已运行：自动连接，无需用户操作
• 本地服务未运行：询问用户选择方式（见下方「服务未运行时的处理」）

服务配置

• 认证：Bearer Token（见 config.yaml 的 auth.token，默认值为 token）
• 服务状态文件：~/.wxautox/service_status.json（服务启动时自动生成，仅 Windows 本地部署时存在）

配置优先级（从高到低）

1. 命令行参数 python scripts/wxapi.py --base-url "http://192.168.1.100:8000" --token "my-token" send "好友" "消息"
2. 环境变量 # 通用（macOS/Linux/Windows） export WXAPI_BASE_URL="http://192.168.1.100:8000" export WXAPI_TOKEN="my-token" # Windows PowerShell $env:WXAPI_BASE_URL = "http://192.168.1.100:8000" $env:WXAPI_TOKEN = "my-token"
3. service_status.json - 自动检测（仅 Windows 本地部署时可用）
4. config.yaml - 服务目录下的配置文件（仅 Windows 本地部署时可用）
5. 默认值 - http://localhost:8000, token 为 token

服务目录搜索顺序（仅 Windows）

1. WXAPI_SERVICE_DIR 环境变量指定的路径
2. ~/.wxautox/service_status.json 中记录的 service_dir
3. ../wxauto-restful-api（相对于 skill 目录）
4. ~/wxauto-restful-api

启动服务（仅 Windows）

macOS / Linux 用户无需执行此节，直接使用远程服务地址即可。

前置要求：

1. 安装 wxautox4： pip install wxautox4 需 Windows 系统，Python 3.9–3.12 64 位
2. 激活 wxautox4： wxautox4 -a your-activation-code 获取激活码：https://docs.wxauto.org/plus
3. 部署并启动 API 服务： # 进入服务目录 cd C:\path\to\wxauto-restful-api # 启动服务 python run.py 或后台启动： Start-Process python -ArgumentList "run.py" -WorkingDirectory "C:\path\to\wxauto-restful-api" -WindowStyle Hidden

脚本路径

调用脚本使用相对于 skill 目录根的相对路径：

python scripts/wxapi.py send "好友" "消息"

查看帮助：

python scripts/wxapi.py --help

可用命令

初始化和状态

# 初始化微信实例
python scripts/wxapi.py init

# 获取服务状态
python scripts/wxapi.py status

# 检查是否在线
python scripts/wxapi.py online

# 获取我的信息
python scripts/wxapi.py myinfo

发送消息

# 主窗口发送
python scripts/wxapi.py send "好友名" "消息内容"

# 精确匹配
python scripts/wxapi.py send "好友名" "消息内容" --exact

# @群成员
python scripts/wxapi.py send "群名" "开会了" --at "张三,李四"

# 子窗口发送
python scripts/wxapi.py send-chat "好友名" "消息内容"

读取消息

# 获取聊天记录（主窗口）
python scripts/wxapi.py getmsg "好友名"

# 获取聊天记录（子窗口）
python scripts/wxapi.py getmsg-chat "好友名"

# 获取历史消息
python scripts/wxapi.py history "好友名" --count 100

# 获取新消息（主窗口轮询）
python scripts/wxapi.py newmsg

# 获取新消息（子窗口）
python scripts/wxapi.py newmsg-chat "好友名"

监听管理

# 添加监听（打开子窗口）
python scripts/wxapi.py listen "好友名"

会话管理

# 获取会话列表
python scripts/wxapi.py session

# 获取所有子窗口
python scripts/wxapi.py windows

# 切换聊天窗口
python scripts/wxapi.py chatwith "好友名" --exact

获取列表

# 好友列表
python scripts/wxapi.py friends

# 群聊列表
python scripts/wxapi.py groups

页面控制

# 切换到聊天页面
python scripts/wxapi.py switch-chat

# 切换到联系人页面
python scripts/wxapi.py switch-contact

查看帮助

python scripts/wxapi.py --help

API 接口列表

根据 wxauto-restful-api 服务：

微信功能接口

聊天接口（子窗口）

直接 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": { ... }
}

服务未运行时的处理

非 Windows 设备

无法在本地启动服务。不要直接报错，使用询问工具询问用户：

提问内容：「当前设备（macOS/Linux）无法运行 wxautox4 服务，请提供运行在 Windows 设备上的远程服务信息」

需要用户提供：

1. 服务地址（如 http://192.168.1.100:8000）
2. Bearer Token（服务端 config.yaml 中 auth.token 的值，默认为 token）

获取后做连通性验证，成功则继续执行用户原本的操作。

Windows 设备

当执行命令发现 wxauto-restful-api 服务未运行时，wxapi.py 会按以下顺序尝试自动恢复：

1. 检查 ~/.wxautox/service_status.json 中的 service_dir 定位项目路径
2. 搜索默认路径（见上方搜索顺序）
3. 找到项目目录后自动启动服务

如果以上都无法定位到项目目录，不要直接报错，使用询问工具询问用户：

提问内容：「wxauto-restful-api 服务未运行，请选择处理方式」

选项：

1. 自动部署并启动本地服务 - 从 GitHub 克隆项目，安装依赖，启动服务（启动后路径自动记录到 service_status.json）
2. 仅启动本地服务 - 服务目录已存在，只需启动（需用户提供路径）
3. 连接远程服务 - 服务运行在其他 Windows 设备上，需提供服务地址和 Token
4. 跳过 - 用户自行处理

如果用户选择「自动部署并启动本地服务」，执行以下步骤：

# 1. 克隆项目到用户目录
cd ~
git clone https://github.com/cluic/wxauto-restful-api.git

# 2. 创建虚拟环境
cd wxauto-restful-api
python -m venv .venv

# 3. 激活虚拟环境并安装依赖
.venv\Scripts\activate
pip install -r requirements.txt

# 4. 后台启动服务
python run.py

启动后验证服务是否正常运行（检查健康接口），然后继续执行用户原本的操作。

注意事项

1. 微信客户端需要在运行服务的 Windows 设备上保持打开状态
2. wxautox4 需要激活后才能使用（仅 Windows 端需要）
3. 不要用 PowerShell 直接调用 API（中文编码问题），请使用 Python 脚本
4. 修改服务端 config.yaml 中的 auth.token 以增强安全性
5. macOS / Linux 用户：跳过所有本地安装步骤，仅需提供远程服务地址和 Token 即可使用全部功能