wxauto

WeChat Automation

Operate WeChat via the wxautox4 RESTful API, supporting message sending and receiving, monitoring, contact management, and more. The API service must run on Windows devices(wxautox4 only supports Windows), and can be connected to locally or remotely.

Step 0: Platform Detection (Execute First)

Before doing anything else, first detect the current device's operating system：

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

Branch differently based on the result:

---

Non-Windows devices (macOS / Linux)

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

Ask the user directly for the remote service information (using AskUserQuestion or an equivalent tool):

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

After obtaining the address and token:

1. Write the configuration into environment variables or pass it directly as script parameters
2. Call the health check endpoint to verify connectivity:GET /v1/wechat/status
3. If the connection fails, prompt the user to check: whether the network is reachable, whether the service has been started, and whether the token is correct
4. After a successful connection, directly execute the user's operation,no local installation steps are required

---

Windows devices

First check whether the local service is already running (read ~/.wxautox/service_status.json and perform a health check):

• Local service is already running: connect automatically, no user action required
• Local service is not running: ask the user to choose a method (see "Handling When the Service Is Not Running" below)

---

Service Configuration

• Authentication: Bearer Token (see config.yaml in auth.token, default value is token）
• Service status file:~/.wxautox/service_status.json(automatically generated when the service starts; only exists for local Windows deployments)

Configuration Priority (from high to low)

1. Command-line parameters

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

2. Environment variables

   # 通用（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 - auto-detection (only available for local Windows deployments)

4. config.yaml - configuration file in the service directory (only available for local Windows deployments)

5. Default values - http://localhost:8000, token is token

Service Directory Search Order (Windows only)

1. WXAPI_SERVICE_DIR the path specified by the environment variable
2. ~/.wxautox/service_status.json the one recorded in service_dir
3. ../wxauto-restful-api(relative to the skill directory)
4. ~/wxauto-restful-api

Starting the Service (Windows only)

macOS / Linux users do not need to perform this section; simply use the remote service address.

Prerequisites：

1. Install wxautox4:

   pip install wxautox4
   

   Requires Windows, Python 3.9–3.12 64-bit

2. Activate wxautox4:

   wxautox4 -a your-activation-code
   

   Get an activation code:https://docs.wxauto.org/plus

3. Deploy and start the API service:

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

   Or start it in the background:

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

Script Paths

Call scripts using relative paths relative to the skill directory root:

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

View help:

python scripts/wxapi.py --help

Available Commands

Initialization and Status

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

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

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

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

Send Message

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

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

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

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

Read Messages

# 获取聊天记录（主窗口）
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 "好友名"

Monitoring Management

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

Session Management

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

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

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

Get List

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

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

Page Controls

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

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

View Help

python scripts/wxapi.py --help

API Endpoint List

According to the wxauto-restful-api service:

WeChat Feature Endpoints

Endpoint	Description
POST /v1/wechat/initialize	Initialize WeChat instance
GET /v1/wechat/status	Get WeChat status
POST /v1/wechat/send	Send message
POST /v1/wechat/sendfile	Send file
POST /v1/wechat/sendurlcard	Send URL card
POST /v1/wechat/getallmessage	Get current window messages
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 Endpoints (Sub-window)

Endpoint	Description
POST /v1/chat/send	Sub-window send message
POST /v1/chat/getallmessage	Get all sub-window messages
POST /v1/chat/getnewmessage	Get new sub-window messages
POST /v1/chat/msg/quote	Send quoted message
POST /v1/chat/close	Close sub-window

Direct API Call (Alternative)

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

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

Response Format

All APIs return a unified format:

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

Handling When Service Is Not Running

Non-Windows Devices

Unable to start the service locally.Do not report an error directly, use the inquiry 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."

The user needs to provide:

1. Service address(e.g. http://192.168.1.100:8000）
2. Bearer Token(server-side config.yaml in auth.token value, default is token）

After obtaining it, perform a connectivity verification. If successful, continue executing the user's original operation.

---

Windows Devices

When executing a command and finding that the wxauto-restful-api service is not running, wxapi.py will attempt automatic recovery in the following order:

1. Check ~/.wxautox/service_status.json in service_dir to locate the project path
2. Search default paths (see the search order above)
3. After finding the project directory, automatically start the service

If none of the above can locate the project directory,do not report an error directly, use the inquiry tool to ask the user:

Question content: "The wxauto-restful-api service is not running. Please choose how to proceed."

Options:

1. Automatically deploy and start the local service - Clone the project from GitHub, install dependencies, start the service (after startup, the path is automatically recorded to service_status.json）
2. Only start the local service - The service directory already exists, only need to start it (the user needs to provide the path)
3. Connect to remote service - The service is running on another Windows device, the service address and Token need to be provided
4. Skip - Handled by the user

If the user chooses 'Automatically deploy and start the local service', perform the following steps:

# 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

After startup, verify whether the service is running properly (check the health endpoint), then continue with the user's original operation.

Notes

1. The WeChat client needs to remain open on the Windows devicerunning the service
2. wxautox4 needs to be activated before use (only required on Windows)
3. Do not call the API directly with PowerShell(Chinese encoding issues); please use a Python script
4. Modify the config.yaml in the server-side auth.token to enhance security
5. macOS / Linux users: Skip all local installation steps; simply provide the remote service address and Token to use all features