wxauto

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

微信自动化

WeChat Automation

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

Operate WeChat through the wxautox4 RESTful API, supporting functions such as message sending/receiving, monitoring, and friend management. The API service must run on Windows devices (wxautox4 only supports Windows) and can be connected locally or remotely.

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

Step 0: Platform Detection (Highest Priority)

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

python

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

根据结果走不同分支：

Before performing any other operations, first detect the operating system of the current device:

python

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

Follow different branches based on the result:

非 Windows 设备（macOS / Linux）

Non-Windows Devices (macOS / Linux)

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

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

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

获取到地址和 token 后：

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

The wxautox4 service can only run on Windows, do not attempt to install or start the service on the current device.

Directly ask the user for remote service information (use AskUserQuestion or equivalent tools):

Question 1: Please provide the wxauto-restful-api service address (e.g. http://192.168.1.100:8000)
Question 2: Please provide the service's Bearer Token (see auth.token in the server-side config.yaml, default value is token)

After obtaining the address and token:

Write the configuration into environment variables or pass it directly as script parameters
Call the health check interface to verify connectivity:
```
GET /v1/wechat/status
```
If the connection fails, prompt the user to check: network reachability, whether the service is started, whether the token is correct
After the connection is successful, directly execute the user's operation, no local installation steps are required

Windows 设备

Windows Devices

先检查本地服务是否已运行（读取

~/.wxautox/service_status.json

并做健康检查）：

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

First check if the local service is running (read

~/.wxautox/service_status.json

and perform health check):

Local service is running: Automatically connect, no user operation required
Local service is not running: Ask the user to select a method (see "Handling when the service is not running" below)

服务配置

Service Configuration

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

Authentication: Bearer Token (see
```
auth.token
```
in
```
config.yaml
```
, default value is
```
token
```
)
Service status file:
```
~/.wxautox/service_status.json
```
(automatically generated when the service starts, only exists when deployed locally on Windows)

配置优先级（从高到低）

Configuration Priority (From High to Low)

命令行参数

bash

python scripts/wxapi.py --base-url "http://192.168.1.100:8000" --token "my-token" send "好友" "消息"

环境变量

bash

# 通用（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"

service_status.json - 自动检测（仅 Windows 本地部署时可用）
config.yaml - 服务目录下的配置文件（仅 Windows 本地部署时可用）
默认值 -
```
http://localhost:8000
```
, token 为
```
token
```

Command Line Parameters

bash

python scripts/wxapi.py --base-url "http://192.168.1.100:8000" --token "my-token" send "Friend" "Message"

Environment Variables

bash

# General (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"

service_status.json - Automatic detection (only available when deployed locally on Windows)
config.yaml - Configuration file under the service directory (only available when deployed locally on Windows)
Default Value -
```
http://localhost:8000
```
, token is
```
token
```

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

Service Directory Search Order (Windows Only)

```
WXAPI_SERVICE_DIR
```
环境变量指定的路径

~/.wxautox/service_status.json

中记录的

service_dir

```
../wxauto-restful-api
```
（相对于 skill 目录）
```
~/wxauto-restful-api
```

Path specified by the
```
WXAPI_SERVICE_DIR
```
environment variable

service_dir

recorded in

~/.wxautox/service_status.json

```
../wxauto-restful-api
```
(relative to the skill directory)
```
~/wxauto-restful-api
```

启动服务（仅 Windows）

Start the Service (Windows Only)

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

前置要求：

安装 wxautox4：
powershell
```
pip install wxautox4
```
需 Windows 系统，Python 3.9–3.12 64 位
激活 wxautox4：
powershell
```
wxautox4 -a your-activation-code
```
获取激活码：https://docs.wxauto.org/plus

部署并启动 API 服务：

powershell

# 进入服务目录
cd C:\path\to\wxauto-restful-api
# 启动服务
python run.py

或后台启动：

powershell

Start-Process python -ArgumentList "run.py" -WorkingDirectory "C:\path\to\wxauto-restful-api" -WindowStyle Hidden

macOS / Linux users do not need to perform this section, just use the remote service address directly.

Prerequisites:

Install wxautox4:
powershell
```
pip install wxautox4
```
Requires Windows system, Python 3.9–3.12 64-bit
Activate wxautox4:
powershell
```
wxautox4 -a your-activation-code
```
Get activation code: https://docs.wxauto.org/plus

Deploy and start the API service:

powershell

# Enter the service directory
cd C:\path\to\wxauto-restful-api
# Start the service
python run.py

Or start in the background:

powershell

Start-Process python -ArgumentList "run.py" -WorkingDirectory "C:\path\to\wxauto-restful-api" -WindowStyle Hidden

脚本路径

Script Path

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

bash

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

查看帮助：

bash

python scripts/wxapi.py --help

Call the script using a relative path relative to the root of the skill directory:

bash

python scripts/wxapi.py send "Friend" "Message"

View help:

bash

python scripts/wxapi.py --help

可用命令

Available Commands

初始化和状态

Initialization and Status

powershell

undefined

powershell

undefined

初始化微信实例

Initialize WeChat instance

python scripts/wxapi.py init

获取服务状态

Get service status

python scripts/wxapi.py status

检查是否在线

Check if online

python scripts/wxapi.py online

获取我的信息

Get my information

python scripts/wxapi.py myinfo

undefined

python scripts/wxapi.py myinfo

undefined

发送消息

Send Messages

powershell

undefined

powershell

undefined

主窗口发送

Send from main window

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

python scripts/wxapi.py send "Friend Name" "Message Content"

精确匹配

Exact match

python scripts/wxapi.py send "好友名" "消息内容" --exact

python scripts/wxapi.py send "Friend Name" "Message Content" --exact

@群成员

@Group members

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

python scripts/wxapi.py send "Group Name" "Meeting starts" --at "Zhang San,Li Si"

子窗口发送

Send from sub-window

python scripts/wxapi.py send-chat "好友名" "消息内容"

undefined

python scripts/wxapi.py send-chat "Friend Name" "Message Content"

undefined

读取消息

Read Messages

powershell

undefined

powershell

undefined

获取聊天记录（主窗口）

Get chat records (main window)

python scripts/wxapi.py getmsg "好友名"

python scripts/wxapi.py getmsg "Friend Name"

获取聊天记录（子窗口）

Get chat records (sub-window)

python scripts/wxapi.py getmsg-chat "好友名"

python scripts/wxapi.py getmsg-chat "Friend Name"

获取历史消息

Get historical messages

python scripts/wxapi.py history "好友名" --count 100

python scripts/wxapi.py history "Friend Name" --count 100

获取新消息（主窗口轮询）

Get new messages (main window polling)

python scripts/wxapi.py newmsg

获取新消息（子窗口）

Get new messages (sub-window)

python scripts/wxapi.py newmsg-chat "好友名"

undefined

python scripts/wxapi.py newmsg-chat "Friend Name"

undefined

监听管理

Monitoring Management

powershell

undefined

powershell

undefined

添加监听（打开子窗口）

Add monitoring (open sub-window)

python scripts/wxapi.py listen "好友名"

undefined

python scripts/wxapi.py listen "Friend Name"

undefined

会话管理

Session Management

powershell

undefined

powershell

undefined

获取会话列表

Get session list

python scripts/wxapi.py session

获取所有子窗口

Get all sub-windows

python scripts/wxapi.py windows

切换聊天窗口

Switch chat window

python scripts/wxapi.py chatwith "好友名" --exact

undefined

python scripts/wxapi.py chatwith "Friend Name" --exact

undefined

获取列表

Get Lists

powershell

undefined

powershell

undefined

好友列表

Friend list

python scripts/wxapi.py friends

群聊列表

Group chat list

python scripts/wxapi.py groups

undefined

python scripts/wxapi.py groups

undefined

页面控制

Page Control

powershell

undefined

powershell

undefined

切换到聊天页面

Switch to chat page

python scripts/wxapi.py switch-chat

切换到联系人页面

Switch to contacts page

python scripts/wxapi.py switch-contact

undefined

python scripts/wxapi.py switch-contact

undefined

查看帮助

View Help

powershell

python scripts/wxapi.py --help

powershell

python scripts/wxapi.py --help

API 接口列表

API Interface List

根据 wxauto-restful-api 服务：

According to the wxauto-restful-api service:

微信功能接口

WeChat Function Interfaces

接口	说明
`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`	检查在线状态

Interface	Description
`POST /v1/wechat/initialize`	Initialize WeChat instance
`GET /v1/wechat/status`	Get WeChat status
`POST /v1/wechat/send`	Send messages
`POST /v1/wechat/sendfile`	Send files
`POST /v1/wechat/sendurlcard`	Send URL cards
`POST /v1/wechat/getallmessage`	Get messages from current window
`POST /v1/wechat/gethistorymessage`	Get historical messages
`POST /v1/wechat/getnextnewmessage`	Get new messages
`POST /v1/wechat/getsession`	Get session list
`POST /v1/wechat/getsubwindow`	Get specified sub-window
`POST /v1/wechat/getallsubwindow`	Get all sub-windows
`POST /v1/wechat/chatwith`	Switch chat window
`POST /v1/wechat/getfriends`	Get friend list
`POST /v1/wechat/getmyinfo`	Get my information
`POST /v1/wechat/getrecentgroups`	Get group chat list
`POST /v1/wechat/switch/chat`	Switch to chat page
`POST /v1/wechat/switch/contact`	Switch to contacts page
`POST /v1/wechat/isonline`	Check online status

聊天接口（子窗口）

Chat Interfaces (Sub-window)

接口	说明
`POST /v1/chat/send`	子窗口发送消息
`POST /v1/chat/getallmessage`	获取子窗口所有消息
`POST /v1/chat/getnewmessage`	获取子窗口新消息
`POST /v1/chat/msg/quote`	发送引用消息
`POST /v1/chat/close`	关闭子窗口

Interface	Description
`POST /v1/chat/send`	Send messages from sub-window
`POST /v1/chat/getallmessage`	Get all messages from sub-window
`POST /v1/chat/getnewmessage`	Get new messages from sub-window
`POST /v1/chat/msg/quote`	Send quoted messages
`POST /v1/chat/close`	Close sub-window

直接 API 调用（备选）

Direct API Call (Alternative)

如需直接调用 HTTP API，用 Python（不要用 PowerShell，有中文编码问题）：

python

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())

If you need to call the HTTP API directly, use Python (do not use PowerShell, which has Chinese encoding issues):

python

import requests

headers = {"Authorization": "Bearer token", "Content-Type": "application/json"}
body = {"who": "Friend Name", "msg": "Message Content"}
resp = requests.post("http://localhost:8000/v1/wechat/send", headers=headers, json=body)
print(resp.json())

响应格式

Response Format

所有 API 返回统一格式：

json

{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}

All APIs return a unified format:

json

{
  "success": true,
  "message": "Operation succeeded",
  "data": { ... }
}

服务未运行时的处理

Handling when the Service is Not Running

非 Windows 设备

Non-Windows Devices

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

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

需要用户提供：

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

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

Cannot start the service locally. Do not report an error directly, use the query tool to ask the user:

Question content: "The current device (macOS/Linux) cannot run the wxautox4 service, please provide the remote service information running on a Windows device"

Required user input:

Service address (e.g.
```
http://192.168.1.100:8000
```
)
Bearer Token (the value of
```
auth.token
```
in the server-side
```
config.yaml
```
, default is
```
token
```
)

After obtaining, perform connectivity verification, and continue to execute the user's original operation if successful.

Windows 设备

Windows Devices

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

检查

~/.wxautox/service_status.json

中的

service_dir

定位项目路径

搜索默认路径（见上方搜索顺序）
找到项目目录后自动启动服务

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

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

选项：

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

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

powershell

undefined

When executing a command and finding that the wxauto-restful-api service is not running, wxapi.py will try to automatically recover in the following order:

Check

service_dir

~/.wxautox/service_status.json

to locate the project path

Search default paths (see the search order above)
Automatically start the service after finding the project directory

If the project directory cannot be located by the above methods, do not report an error directly, use the query tool to ask the user:

Question content: "The wxauto-restful-api service is not running, please select a processing method"

Options:

Automatically deploy and start local service - Clone the project from GitHub, install dependencies, start the service (the path will be automatically recorded in
```
service_status.json
```
after startup)
Only start local service - The service directory already exists, just start it (user needs to provide the path)
Connect to remote service - The service runs on another Windows device, need to provide service address and Token
Skip - User handles it by themselves

If the user selects "Automatically deploy and start local service", perform the following steps:

powershell

undefined

1. 克隆项目到用户目录

1. Clone the project to the user directory

cd ~ git clone https://github.com/cluic/wxauto-restful-api.git

2. 创建虚拟环境

2. Create virtual environment

cd wxauto-restful-api python -m venv .venv

3. 激活虚拟环境并安装依赖

3. Activate virtual environment and install dependencies

.venv\Scripts\activate pip install -r requirements.txt

4. 后台启动服务

4. Start service in background

python run.py


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

python run.py


After startup, verify whether the service is running normally (check the health interface), then continue to execute the user's original operation.

注意事项

Notes

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

The WeChat client needs to be kept open on the Windows device running the service
wxautox4 needs to be activated before use (only required for Windows side)
Do not call the API directly with PowerShell (Chinese encoding problem), please use Python scripts
Modify
```
auth.token
```
in the server-side
```
config.yaml
```
to enhance security
macOS / Linux users: Skip all local installation steps, only need to provide the remote service address and Token to use all functions