WeChat Automation

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.

Step 0: Platform Detection (Highest Priority)

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:

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.

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 Devices

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

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)

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
```

Service Directory Search Order (Windows Only)

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
```

Start the Service (Windows Only)

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

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

# 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

Send Messages

powershell

# Send from main window
python scripts/wxapi.py send "Friend Name" "Message Content"

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

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

# Send from sub-window
python scripts/wxapi.py send-chat "Friend Name" "Message Content"

Read Messages

powershell

# Get chat records (main window)
python scripts/wxapi.py getmsg "Friend Name"

# Get chat records (sub-window)
python scripts/wxapi.py getmsg-chat "Friend Name"

# Get historical messages
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 "Friend Name"

Monitoring Management

powershell

# Add monitoring (open sub-window)
python scripts/wxapi.py listen "Friend Name"

Session Management

powershell

# 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 "Friend Name" --exact

Get Lists

powershell

# Friend list
python scripts/wxapi.py friends

# Group chat list
python scripts/wxapi.py groups

Page Control

powershell

# Switch to chat page
python scripts/wxapi.py switch-chat

# Switch to contacts page
python scripts/wxapi.py switch-contact

View Help

powershell

python scripts/wxapi.py --help

API Interface List

According to the wxauto-restful-api service:

WeChat Function Interfaces

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)

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

Direct API Call (Alternative)

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

All APIs return a unified format:

json

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

Handling when the Service is Not Running

Non-Windows Devices

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 Devices

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

# 1. Clone the project to the user directory
cd ~
git clone https://github.com/cluic/wxauto-restful-api.git

# 2. Create virtual environment
cd wxauto-restful-api
python -m venv .venv

# 3. Activate virtual environment and install dependencies
.venv\Scripts\activate
pip install -r requirements.txt

# 4. Start service in background
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

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

wxauto

NPX Install

Tags

SKILL.md Content (Chinese)

WeChat Automation

Step 0: Platform Detection (Highest Priority)

Non-Windows Devices (macOS / Linux)

Windows Devices

Service Configuration

Configuration Priority (From High to Low)

Service Directory Search Order (Windows Only)

Start the Service (Windows Only)

Script Path

Available Commands

Initialization and Status

Send Messages

Read Messages

Monitoring Management

Session Management

Get Lists

Page Control

View Help

API Interface List

WeChat Function Interfaces

Chat Interfaces (Sub-window)

Direct API Call (Alternative)

Response Format

Handling when the Service is Not Running

Non-Windows Devices

Windows Devices

Notes