wxauto

https://docs.wxauto.org/
Admin
wxauto is a Python-based Windows WeChat UI automation library that provides APIs for message...
Tokens:22,527
Snippets:277
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install wxauto library

Source: https://docs.wxauto.org/docs/install.html

Use pip to install the desired version of the wxauto library.

```bash
pip install wxauto4
```

```bash
pip install wxautox4
```

--------------------------------

### Install wxauto-mcp

Source: https://docs.wxauto.org/plugin/mcp.html

Install the package using pip.

```bash
pip install wxauto-mcp
```

--------------------------------

### Test wxauto installation

Source: https://docs.wxauto.org/docs/install.html

Verify the installation by initializing the WeChat instance and interacting with a chat window.

```python
from wxauto4 import WeChat # 免费版
from wxautox4 import WeChat  # Plus版

# 初始化微信实例
wx = WeChat()

# 切换到文件传输助手
target = "文件传输助手"
wx.ChatWith(target)

# 查看当前窗口信息
chatinfo = wx.ChatInfo()
print(f"当前窗口信息：{chatinfo}")

# 发送消息
if chatinfo.get('chat_name') == target:  # 先判断是否为要发送的人
    wx.SendMsg("你好")

# 获取当前聊天窗口消息
msgs = wx.GetAllMessage()

for msg in msgs:
    print(msg.raw)
```

--------------------------------

### Install skill via ClawHub

Source: https://docs.wxauto.org/plugin/skills.html

Use the ClawHub command-line tool to install the wxauto skill.

```bash
clawhub install wxauto
```

--------------------------------

### Start the RESTful API service

Source: https://docs.wxauto.org/plugin/skills.html

Run the service after configuring the config.yaml file.

```bash
python run.py
```

--------------------------------

### wxauto-mcp CLI

Source: https://docs.wxauto.org/plugin/mcp.html

Command line interface for installing and configuring the MCP server.

```APIDOC
## CLI Commands

### Install
`wxauto-mcp --install`
Automatically configures the MCP server for Claude Desktop and Claude Code.

### Generate Config
`wxauto-mcp --config [path]`
Generates the MCP configuration file for manual setup in AI applications.
```

--------------------------------

### JSONL event output format

Source: https://docs.wxauto.org/docs/cli/listen.html

Example of the JSONL structure produced by the listen command.

```json
{"chat":{"chat_name":"项目群"},"message":{"content":"hello"}}
```

```json
{"status":"stopped","chats":["项目群"]}
```

--------------------------------

### Generate MCP Configuration Files

Source: https://docs.wxauto.org/plugin/mcp.html

Manually generate configuration files for custom setup or specific directories.

```bash
# 生成配置文件到默认目录 (./mcp-configs)
wxauto-mcp --config

# 生成配置文件到指定目录
wxauto-mcp --config /path/to/configs

# 例如
wxauto-mcp --config mcp-configs
```

--------------------------------

### Send WeChat message via OpenClaw

Source: https://docs.wxauto.org/plugin/skills.html

Example command to send a message to a contact using the installed skill.

```text
发微信给文件传输助手说你好
```

--------------------------------

### Error output examples

Source: https://docs.wxauto.org/docs/cli/listen.html

Examples of error messages that may appear in stderr during execution.

```text
callback error: ValueError: ...
```

```text
error: listener disconnected before completion
```

--------------------------------

### Start message monitoring

Source: https://docs.wxauto.org/docs/cli/examples.html

Initiate monitoring for specific groups using the defined callback file and output errors to a log file.

```powershell
wxautox4 --nickname "工作微信" listen `
    "项目群" "运维群" `
    --callback-file ".\archive_urgent.py" `
    --jsonl `
    2> ".\listener-errors.log"
```

--------------------------------

### GET /v1/activation/check

Source: https://docs.wxauto.org/plugin/http.html

Checks the current activation status.

```APIDOC
## GET /v1/activation/check

### Description
Checks if the current instance is activated.

### Method
GET

### Endpoint
/v1/activation/check
```

--------------------------------

### Get My Info

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves the current user's account information.

```python
wx.GetMyInfo()
```

--------------------------------

### Manage worker lifecycle

Source: https://docs.wxauto.org/docs/cli/examples.html

Commands to start, check the status of, and stop the background worker process.

```bash
wxautox4 --nickname "工作微信" worker start
wxautox4 --nickname "工作微信" worker status --json
```

```bash
wxautox4 --nickname "工作微信" worker stop
```

--------------------------------

### Get Moments Content

Source: https://docs.wxauto.org/docs/class/Moment.html

Retrieve content from the current page or navigate to the next page.

```python
# 获取当前页面的朋友圈内容
moments = pyq.GetMoments()

# 通过`next_page`参数获取下一页的朋友圈内容
moments = pyq.GetMoments(next_page=True)
```

--------------------------------

### Chat Information Return Values

Source: https://docs.wxauto.org/docs/class/Message.html

Examples of dictionary structures returned by the chat_info method for different chat types.

```python
# 好友
{'chat_type': 'friend', 'chat_name': '张三'}  

# 群聊
{'group_member_count': 500, 'chat_type': 'group', 'chat_name': '工作群'}  

# 客服
{'company': '@肯德基', 'chat_type': 'service', 'chat_name': '店长xxx'} 

# 公众号
{'chat_type': 'official', 'chat_name': '肯德基'}
```

--------------------------------

### Get Moment Content

Source: https://docs.wxauto.org/docs/class/Moment.html

Access the text content of a specific moment object.

```python
# 获取朋友圈内容
moment.content
```

--------------------------------

### Get Content from NoteMessage

Source: https://docs.wxauto.org/docs/class/Message.html

Iterates through the content of a note message, distinguishing between text and file paths.

```python
from pathlib import Path

note_content_list = msg.get_content()
for content in note_content_list:
    if isinstance(content, str):
        # 文本内容
        print(content)
    elif isinstance(content, Path):
        # 文件路径，文件、视频、图片等
        print('文件路径：', content)
```

--------------------------------

### CLI 快速开始命令

Source: https://docs.wxauto.org/docs/cli/index.html

展示了查看版本、检查授权、发送消息及获取会话列表的基本操作。

```bash
# 查看帮助和版本
wxautox4 --help
wxautox4 --version

# 查看当前账号和授权状态
wxautox4 status
wxautox4 auth check

# 发送消息
wxautox4 message send "CLI 测试" --chat "文件传输助手"

# 获取最近会话，输出 JSON
wxautox4 sessions list --json
```

--------------------------------

### 获取命令帮助

Source: https://docs.wxauto.org/docs/cli/index.html

通过 --help 参数查看各级命令的详细用法。

```bash
wxautox4 worker --help
wxautox4 message action --help
```

--------------------------------

### Get Sender Information

Source: https://docs.wxauto.org/docs/class/Message.html

Retrieves information about the sender of the message.

```python
msg.sender_info()
```

--------------------------------

### GET /v1/wechat/status

Source: https://docs.wxauto.org/plugin/http.html

Retrieves the current status of the WeChat instance.

```APIDOC
## GET /v1/wechat/status

### Description
Returns the current operational status of the WeChat instance.

### Method
GET

### Endpoint
/v1/wechat/status
```

--------------------------------

### CLI 全局参数结构

Source: https://docs.wxauto.org/docs/cli/index.html

定义了 CLI 的基本调用格式及全局参数位置。

```bash
wxautox4 [-h] [-v] [--json] [--nickname NICKNAME] COMMAND ...
```

--------------------------------

### 快速激活

Source: https://docs.wxauto.org/plugin/http.html

激活wxautox4的命令行操作。

```bash
# 检查激活状态
wxautox4 -k

# 激活 wxautox4
wxautox4 -a your-activation-code
```

--------------------------------

### Get URL from LinkMessage

Source: https://docs.wxauto.org/docs/class/Message.html

Retrieves the URL address from a link message.

```python
msg.get_url()
```

--------------------------------

### Get Dialog

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves the current active dialog window object.

```python
dialog = wx.GetDialog(wait=3)
```

--------------------------------

### POST /v1/wechat/initialize

Source: https://docs.wxauto.org/plugin/http.html

Initializes the WeChat instance.

```APIDOC
## POST /v1/wechat/initialize

### Description
Initializes the WeChat instance to enable automation features.

### Method
POST

### Endpoint
/v1/wechat/initialize
```

--------------------------------

### 快速配置服务

Source: https://docs.wxauto.org/plugin/http.html

编辑config.yaml以设置服务器参数。

```yaml
server:
  host: "0.0.0.0"
  port: 8000
  reload: true

auth:
  token: "your-secret-token-here"  # 修改为你的 token
```

--------------------------------

### Execute listen with a callback file

Source: https://docs.wxauto.org/docs/cli/listen.html

Run the listen command using a specified Python callback file.

```bash
wxautox4 listen "项目群" --callback-file ".\on_message.py" --jsonl
```

--------------------------------

### Get Chat Information

Source: https://docs.wxauto.org/docs/class/Message.html

Retrieves information about the chat window associated with the message.

```python
chat_info = msg.chat_info()
```

--------------------------------

### 群聊、卡片与朋友圈操作

Source: https://docs.wxauto.org/docs/cli/commands.html

管理群聊、发送 URL 卡片以及发布和互动朋友圈内容。

```bash
# 群聊
wxautox4 group recent --json
wxautox4 group create "张三" "李四"

# URL 卡片
wxautox4 card send "https://example.com" "张三" --message "请查看"

# 查询和发布朋友圈
wxautox4 moments list --next-page --timeout 30 --json
wxautox4 moments publish --text "项目照片" --media "C:\Temp\1.jpg" --tag "同事"

# 点赞或评论当前查询结果中的第一条朋友圈
wxautox4 moments action --index 0 --op like
wxautox4 moments action --index 0 --op comment --text "赞"
```

--------------------------------

### 激活wxautox4

Source: https://docs.wxauto.org/plugin/http.html

检查激活状态或使用激活码激活服务。

```bash
# 检查激活状态
wxautox4 -k

# 激活
wxautox4 -a 激活码
```

--------------------------------

### Clone wxauto-restful-api service

Source: https://docs.wxauto.org/plugin/skills.html

Download the required RESTful API service repository.

```bash
git clone https://github.com/cluic/wxauto-restful-api
```

--------------------------------

### 发送语音

Source: https://docs.wxauto.org/docs/class/Chat.html

发送语音条消息，此功能为Beta版本，需特定客户端版本支持。

```python
wx.SendAudio(filepath="C:/audio.mp3", duration=5)
```

--------------------------------

### Get Recent Groups

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves a list of names for recently active group chats.

```python
groups = wx.GetAllRecentGroups()
if groups:
    print(groups)
else:
    print('获取失败')
```

--------------------------------

### 聊天管理与群组操作

Source: https://docs.wxauto.org/docs/cli/commands.html

执行打开聊天窗口、读取信息、添加群成员及修改群设置等操作。

```bash
# 打开聊天，--fuzzy 表示允许模糊匹配
wxautox4 chat open "项目" --fuzzy

# 读取聊天或群聊信息
wxautox4 chat info --chat "项目群" --json

# 添加群成员
wxautox4 chat add-members "张三" "李四" --chat "项目群"

# 加载更多历史记录
wxautox4 chat load-more --chat "项目群" --times 3

# 修改群名称、备注、我的群昵称或群公告
wxautox4 chat set --chat "项目群" --field remark --value "核心项目"
```

--------------------------------

### Get Friend Details

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves detailed information about friends. Can be filtered using a callback function.

```python
# 获取前10个好友详情信息
messages = wx.GetFriendDetails(n=10)
```

```python
# 案例
{'头像': 'D:\\myproject\\wxautox文件下载\\头像\\202511210038064171.png',
  '昵称': '张三',
  '微信号': 'zhangsan',
  '标签': 'wxauto',
  '共同群聊': '3个',
  '个性签名': '天道酬勤',
  '来源': '通过扫一扫添加'}
```

```python
# 示例1：从昵称为"陈"开头的好友开始获取
def callback(name):
    if name.startswith('陈'):
        return True

wx.GetFriendDetails(callback=callback)
```

```python
import re

def callback(name):
    # 从张三或者李四开始
    if re.match(r'张三｜李四', name):
        return True

wx.GetFriendDetails(callback=callback)
```

```python
# 示例3：使用匿名函数，从“陈”开头的好友开始获取
wx.GetFriendDetails(10, callback=lambda name: name.startswith('李'))
```

--------------------------------

### 安装依赖

Source: https://docs.wxauto.org/plugin/http.html

安装wxautox4及其依赖项。

```bash
# 安装wxautox4
pip install wxautox4

# 或使用requirements.txt
pip install -r requirements.txt
```

--------------------------------

### Check environment and authorization

Source: https://docs.wxauto.org/docs/cli/examples.html

Verify the CLI version, authentication status, and target WeChat account login status.

```bash
wxautox4 --version
wxautox4 auth check --json
wxautox4 --nickname "工作微信" status --json
```

--------------------------------

### 快速启动服务

Source: https://docs.wxauto.org/plugin/http.html

通过脚本或命令行启动服务。

```bash
# 使用 bat 脚本启动（Windows）
run.bat

# 使用 Python 启动
python run.py

# 或使用 uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

--------------------------------

### 联系人与好友申请管理

Source: https://docs.wxauto.org/docs/cli/commands.html

用于添加联系人、处理好友申请以及查询联系人详情。

```bash
# 添加联系人
wxautox4 contact add "wxid_x" --addmsg "项目合作" --tag "客户"

# 查看和接受好友申请
wxautox4 contact requests list --json
wxautox4 contact requests accept --index 0 --remark "张三" --tag "客户"

# 查询联系人详情或按标签查询
wxautox4 contacts details --count 100 --timeout 120 --json
wxautox4 contacts by-tag "客户" --timeout 60 --json
```

--------------------------------

### 测试发送语音条消息

Source: https://docs.wxauto.org/read/audio_settings.html

使用wxautox4库发送指定路径的音频文件作为语音条消息，需确保已完成虚拟麦克风配置。

```python
from wxautox4 import WeChat

wx = WeChat()

audio = 'D:/xxx.mp3'
wx.ChatWith('文件传输助手')
wx.SendAudio(audio, duration=3)  # 发送3秒测试
```

--------------------------------

### Get History Messages

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves historical messages from a chat window. Supports a callback function for processing messages and stopping the retrieval process.

```python
def callback(msg):
    if msg.type == 'image':
        msg.download()

wx.ChatWith('工作群') # 先切换到要获取记录的聊天窗口
msgs = wx.GetHistoryMessage(n=50, callback=callback) # 获取50条消息
```

```python
from wxautox4 import WxParam
from wxautox4.msgs import TimeMessage   # v40.1.9及以上版本支持TimeMessage对象

# 示例：如果找到带有“通知”字眼的消息则停止获取
def history_callback(msg):
    # 当消息内容里包含特定字词时停止
    if '通知' in msg.content:
        print('获取到包含“通知”的消息，停止获取历史消息')
        return WxParam.CALLBACK_STOP_SIGN

    # 当消息时间超过特定时间时停止     # v40.1.9及以上版本支持TimeMessage对象
    if isinstance(msg, TimeMessage) and msg.time < '2026-02-01':
        print('获取到早于2026年2月1日的消息，停止获取历史消息')
        return WxParam.CALLBACK_STOP_SIGN

wx.GetHistoryMessage(n=100, callback=history_callback)
```

--------------------------------

### 执行授权管理命令

Source: https://docs.wxauto.org/docs/cli/automation.html

使用 auth 分类命令进行授权激活、导出及检查，无需启动微信或 Worker。

```bash
wxautox4 auth activate AUTH_CODE
wxautox4 auth activate-file ".\license.dat"
wxautox4 auth export
wxautox4 auth debug-export
wxautox4 auth offline ".\offline.dat" --code AUTH_CODE
wxautox4 auth check
```

--------------------------------

### Get Next New Message

Source: https://docs.wxauto.org/docs/class/WeChat.html

Retrieves the next set of new messages using a callback function. Do not perform actions like sending messages within the callback to avoid resetting the message window.

```python
def callback(msg):
    if msg.type == 'image':
        msg.download()

wx.GetNextNewMessage(callback=callback)
```

```python
{'chat_name': 'wxauto交流',
  'chat_type': 'group',
  'remark': '群备注名',  # 仅当有备注名时存在
  'msg': [
      <wxautox - TimeMessage(2025年5月2...) at 0x227379555d0>,
      <wxautox - FriendImageMessage([图片]) at 0x2273795ca10>,
      <wxautox - FriendTextMessage(/[微笑]) at 0x22737967c50>,
      <wxautox - FriendTextMessage(你点击发送会自动...) at 0x227366c4f50>, 
      ...
    ]
}
```

--------------------------------

### 消息操作指令

Source: https://docs.wxauto.org/docs/cli/commands.html

对指定索引的消息执行回复、转发或下载等操作，索引基于最近一次查询结果。

```bash
wxautox4 message action --chat "项目群" --index 3 --op reply --text "收到"
wxautox4 message action --chat "项目群" --index 2 --op forward --targets "文件传输助手" "归档群"
wxautox4 message action --chat "项目群" --index 1 --op download --dir "C:\Temp"
```

--------------------------------

### 添加新的好友

Source: https://docs.wxauto.org/docs/class/WeChat.html

通过关键词搜索并发送好友添加请求。

```python
wx.AddNewFriend(keywords="张三", addmsg="我是小明", remark="老张", tags=["同学"], permission="朋友圈", timeout=5)
```

--------------------------------

### 消息查询与发送

Source: https://docs.wxauto.org/docs/cli/commands.html

支持获取各类消息记录、轮询新消息以及发送文本、文件、语音和 @所有人。

```bash
# 获取全部消息、新消息和历史消息
wxautox4 message list --chat "项目群" --json
wxautox4 message new --chat "项目群" --json
wxautox4 message history 50 --chat "项目群" --timeout 60 --json

# 轮询下一个新消息集合
wxautox4 message next --filter-mute --timeout 20 --json

# 发送文本、文件和语音
wxautox4 message send "请确认" --chat "项目群" --at "张三"
wxautox4 message send-file "C:\Temp\report.pdf" --chat "项目群"
wxautox4 message send-audio "C:\Temp\voice.mp3" --chat "项目群"

# @所有人
wxautox4 message at-all "今晚发布" --chat "项目群"
```

--------------------------------

### 快速安装依赖

Source: https://docs.wxauto.org/plugin/http.html

安装wxautox4 Plus版本或使用项目配置同步。

```bash
# 安装 wxautox4（需要 Plus 版本）
pip install wxautox4

# 或使用项目配置
uv sync
```

--------------------------------

### Basic listen command usage

Source: https://docs.wxauto.org/docs/cli/listen.html

Monitor chats using standard text output or JSONL format.

```bash
# 普通文本输出
wxautox4 listen "文件传输助手" "测试群"

# 每行输出一个 JSON 对象
wxautox4 listen "项目群" --jsonl
```

--------------------------------

### POST /v1/activation/activate

Source: https://docs.wxauto.org/plugin/http.html

Activates the license for the service.

```APIDOC
## POST /v1/activation/activate

### Description
Activates the wxautox4 license using an activation code.

### Method
POST

### Endpoint
/v1/activation/activate
```

--------------------------------

### Activate Plus version

Source: https://docs.wxauto.org/docs/install.html

Activate the Plus version using the provided activation code.

```bash
wxautox4 -a 激活码
```

--------------------------------

### Select Option from Context Menu

Source: https://docs.wxauto.org/docs/class/Message.html

Right-clicks the message to open the menu and selects the specified option.

```python
msg.select_option("复制")
```

--------------------------------

### 处理WxResponse返回值

Source: https://docs.wxauto.org/docs/class/Other.html

通过判断WxResponse实例的布尔值来确定方法调用是否成功，并获取相应的数据或错误信息。

```python
# 这里假设result为某个方法的WxResponse类型返回值
result: WxResponse = ...

# 判断是否成功
if result:
    data = result['data'] # 成功，获取返回数据，大多数情况下为None
else:
    print(result['message'])  # 该方法调用失败，打印错误信息
```

--------------------------------

### Available MCP Tools

Source: https://docs.wxauto.org/plugin/mcp.html

List of available tools exposed by the wxauto-mcp server for AI agents.

```APIDOC
## System Tools
- `wechat_initialize`: Initialize WeChat connection
- `wechat_status`: Get WeChat running status
- `wechat_activate`: Activate wxautox4
- `wechat_check_activation`: Check activation status
- `wechat_list_tools`: List all available tools
- `get_my_info`: Get personal WeChat account info

## Messaging Tools
- `send_message`: Send text message
- `send_url_card`: Send link card
- `get_messages`: Get current chat messages
- `get_history`: Get history messages
- `get_next_new_message`: Get next new message from chat window
- `send_bulk_messages`: Send bulk messages

## Contact Tools
- `get_friends`: Get friend list
- `get_chat_info`: Get current chat info
- `switch_chat`: Switch chat window

## Session Tools
- `get_sessions`: Get session list
- `get_recent_groups`: Get recent groups
- `filter_sessions`: Filter session list
- `get_unread_sessions`: Get sessions with unread messages

## File Tools
- `send_files`: Send files
- `send_image`: Send image
- `send_directory_files`: Send files from directory
- `check_file_exists`: Check if file exists

## Friend Request Tools
- `get_new_friends`: Get new friend requests
- `accept_new_friend`: Accept new friend request
- `add_friend`: Add new friend

## Interface Tools
- `switch_to_contact`: Switch to contact page
```

--------------------------------

### 发布朋友圈

Source: https://docs.wxauto.org/docs/example.html

发布带有文本和图片的朋友圈，并支持设置隐私权限（白名单或黑名单）。

```python
from wxautox4 import WeChat

wx = WeChat()

text = '''oh
今天天气真好
适合出去走走

嘿嘿~
'''
media_files = [
    r"D:\Images\Pictures\1.png",
    r"D:\Images\Pictures\2.png",
    r"D:\Images\Pictures\3.png",
]
privacy_config = {
    'privacy': '白名单',    # 设置为黑名单模式
    'tags': ['家人','朋友']      # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人
}
# privacy_config = {}     # 公开发布，没有任何权限设置
wx.PublishMoment(text, media_files, privacy_config)
```

--------------------------------

### Execute listen with inline callback code

Source: https://docs.wxauto.org/docs/cli/listen.html

Provide a snippet of Python code directly via the command line.

```powershell
$code = @'
if "紧急" in message.content:
    print("matched")
'@

wxautox4 listen "项目群" --callback-code $code --jsonl
```

--------------------------------

### 获取好友申请

Source: https://docs.wxauto.org/docs/class/WeChat.html

获取并处理新的好友申请。

```python
newfriends = wx.GetNewFriends(acceptable=True)

for new in newfriends:
    print(f"{new.name} ： {new.msg}")
    new.accept(remark='备注名', tags='朋友') # 自动接受好友请求，并添加备注和标签

wx.SwitchToChat() # 操作完成后切换回聊天页面
```

```python
newfriends = wx.GetNewFriends(acceptable=True)
tags = ['标签1', '标签2']
for friend in newfriends:
    remark = f'备注{friend.name}'
    friend.accept(remark=remark, tags=tags)  # 接受好友请求，并设置备注和标签
```

--------------------------------

### 管理账号状态与页面切换

Source: https://docs.wxauto.org/docs/cli/commands.html

用于查询账号在线状态、切换当前操作页面以及获取最近会话列表。

```bash
# 账号信息与在线状态
wxautox4 status --json

# 切换页面
wxautox4 switch chat
wxautox4 switch contact

# 最近会话
wxautox4 sessions list --json
```

--------------------------------

### 修改好友信息

Source: https://docs.wxauto.org/docs/class/WeChat.html

更新好友的备注和标签信息。

```python
wx.EditFriendInfo(add_tags=['同事', '北京'], remove_tags=['老同学'], remark='张三（北京）')
```

--------------------------------

### 进入朋友圈

Source: https://docs.wxauto.org/docs/class/WeChat.html

打开朋友圈窗口。

```python
moments = wx.Moments(timeout=3)
```

--------------------------------

### 启动服务

Source: https://docs.wxauto.org/plugin/http.html

通过Python脚本或uvicorn启动HTTP服务。

```bash
# 启动服务（使用配置文件中的设置）
python run.py

# 或使用uvicorn直接启动
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### 开始监听

Source: https://docs.wxauto.org/docs/class/WeChat.html

启动消息监听服务。

```python
wx.StartListening()
```

--------------------------------

### 认证配置

Source: https://docs.wxauto.org/plugin/http.html

在配置文件中设置API访问令牌。

```yaml
auth:
  token: "your-secret-token-here"
```

--------------------------------

### WxParam Configuration

Source: https://docs.wxauto.org/docs/class/Other.html

The WxParam class allows users to modify default library settings before initializing the WeChat instance. Users can adjust parameters like language, timeouts, and thread pool sizes.

```APIDOC
### WxParam Configuration

### Description
Modify global settings for the wxauto library by updating attributes of the WxParam class before creating a WeChat instance.

### Configuration Attributes
- **LANGUAGE** (Literal['cn', 'cn_t', 'en']) - Default: 'cn' - Language setting.
- **ENABLE_FILE_LOGGER** (bool) - Default: True - Enable file logging.
- **DEFAULT_SAVE_PATH** (str) - Default: ./wxautox - Default path for downloaded files.
- **LISTEN_INTERVAL** (int) - Default: 1 - Message listening interval in seconds.
- **LISTENER_EXCUTOR_WORKERS** (int) - Default: 4 - Thread pool size for listeners.
- **SEARCH_CHAT_TIMEOUT** (int) - Default: 2 - Timeout for searching chat objects in seconds.

### Example
```python
from wxautox4.param import WxParam

# Set 8 listener threads
WxParam.LISTENER_EXCUTOR_WORKERS = 8

# Set search timeout to 10 seconds
WxParam.SEARCH_CHAT_TIMEOUT = 10
```
```

--------------------------------

### 配置WxParam参数

Source: https://docs.wxauto.org/docs/class/Other.html

在获取WeChat实例前，通过修改WxParam类的属性来调整默认行为。

```python
from wxautox4.param import WxParam

# 设置8个监听线程
WxParam.LISTENER_EXCUTOR_WORKERS = 8

# 设置搜索聊天超时时间为10秒
WxParam.SEARCH_CHAT_TIMEOUT = 10

# 自定义表情列表（添加自定义表情）
WxParam.DEFAULT_STICKERS = [
    '[微笑]', '[撇嘴]', '[色]',
    # ... 添加更多表情
]
```

--------------------------------

### 配置 Worker 启动超时

Source: https://docs.wxauto.org/docs/cli/worker.html

启动 Worker 时通过参数调整等待时间。

```bash
wxautox4 worker start --timeout 45
```

--------------------------------

### 发送文件

Source: https://docs.wxauto.org/docs/class/Chat.html

向指定对象发送本地文件。

```python
wx.SendFiles(filepath="C:/文件.txt", who="张三", exact=False)
```

--------------------------------

### Automatic MCP Configuration

Source: https://docs.wxauto.org/plugin/mcp.html

Automatically configure the MCP server for Claude Desktop and Claude Code.

```bash
wxauto-mcp --install
```

--------------------------------

### 监听微信消息

Source: https://docs.wxauto.org/docs/example.html

通过回调函数实现消息监听，并演示如何添加和移除监听器。

```python
from wxautox4 import WeChat
from wxautox4.msgs import FriendMessage
import time

wx = WeChat()

# 消息处理函数
def on_message(msg, chat):
    """消息回调函数"""
    print(f'收到来自 {chat} 的消息: {msg.content}', flush=True)
    
    # 自动回复好友的消息，过滤自己的消息
    if isinstance(msg, FriendMessage):
        chat.SendMsg('收到')

# 添加消息监听
wx.AddListenChat('好友昵称', on_message)

# 保持运行
wx.KeepRunning()
```

```python
# ... 程序运行一段时间后 ...

# 移除监听
wx.RemoveListenChat(nickname="张三")
```

--------------------------------

### Initialize MomentsWnd

Source: https://docs.wxauto.org/docs/class/Moment.html

Access the Moments window object to perform operations like refreshing or closing.

```python
from wxautox4 import WeChat

wx = WeChat()
pyq = wx.Moments()   # 打开朋友圈并获取朋友圈窗口对象（如果为None则说明你没开启朋友圈，需要在手机端设置）
```

--------------------------------

### Create a message callback script

Source: https://docs.wxauto.org/docs/cli/examples.html

Define a Python script to filter incoming messages for specific keywords and log them to a local file.

```python
from datetime import datetime
from pathlib import Path


KEYWORDS = ("紧急", "故障")
LOG_FILE = Path.home() / "wxautox-urgent.log"


def on_message(message, chat):
    content = str(message.content)
    if not any(keyword in content for keyword in KEYWORDS):
        return

    timestamp = datetime.now().isoformat(timespec="seconds")
    line = f"{timestamp}\t{chat.chat_name}\t{content}\n"
    with LOG_FILE.open("a", encoding="utf-8") as file:
        file.write(line)
```

--------------------------------

### 正确使用全局参数

Source: https://docs.wxauto.org/docs/cli/automation.html

确保全局参数（如 --nickname）放置在顶层命令之前，否则会导致参数识别错误。

```bash
wxautox4 --nickname "工作微信" message list
```

--------------------------------

### 添加群成员

Source: https://docs.wxauto.org/docs/class/Chat.html

向群聊中添加新成员，需先通过ChatWith切换到目标群。

```python
wx.ChatWith('工作群')
wx.AddGroupMembers(members=["张三", "李四"])
```

--------------------------------

### 发送表情消息

Source: https://docs.wxauto.org/docs/class/Other.html

在发送消息时使用预定义的表情符号。

```python
from wxautox4 import WeChat

wx = WeChat()
msg_list = wx.ChatWith('文件传输助手')

# 发送表情
msg_list.SendMsg('[微笑][拥抱][爱心]')
```

--------------------------------

### 处理好友申请

Source: https://docs.wxauto.org/docs/example.html

获取待处理的好友申请并自动接受，同时支持设置备注和标签。

```python
from wxautox4 import WeChat

wx = WeChat()

# 获取新的好友申请
newfriends = wx.GetNewFriends(acceptable=True)

# 处理好友申请
tags = ['同学', '技术群']
for new in newfriends:
    message = new.content
    new.accept(tags=tags)  # 接受好友请求，并设置备注和标签
```

--------------------------------

### 获取当前会话列表

Source: https://docs.wxauto.org/docs/class/WeChat.html

检索当前微信中的所有会话信息。

```python
sessions = wx.GetSession()
for session in sessions:
    print(session.info)
```

--------------------------------

### Callback file implementation

Source: https://docs.wxauto.org/docs/cli/listen.html

Define an on_message function in a Python file to process incoming messages.

```python
def on_message(message, chat):
    print(f"{chat.chat_name}: {message.content}")
```

--------------------------------

### 管理 Worker 进程

Source: https://docs.wxauto.org/docs/cli/worker.html

用于启动、查看状态及停止 Worker 进程的常用命令。

```bash
# 启动默认账号 Worker
wxautox4 worker start

# 查看默认 Worker 和全部 Worker
wxautox4 worker status
wxautox4 worker list --json

# 停止默认 Worker 或全部 Worker
wxautox4 worker stop
wxautox4 worker stop --all
```

--------------------------------

### 配置文件示例

Source: https://docs.wxauto.org/plugin/http.html

服务器、认证及数据库配置项。

```yaml
server:
  host: "0.0.0.0"  # 服务器监听地址
  port: 8000       # 服务器监听端口
  reload: true     # 是否启用热重载

auth:
  token: "your-secret-token-here"  # API认证密钥

database:
  type: "sqlite"  # 数据库类型
  sqlite:
    path: "./data/wxautox.db"  # SQLite数据库路径
```

--------------------------------

### 停止监听

Source: https://docs.wxauto.org/docs/class/WeChat.html

停止消息监听服务，并可选择移除所有子窗口。

```python
wx.StopListening()
```

--------------------------------

### HumanMessage.select_option()

Source: https://docs.wxauto.org/docs/class/Message.html

Right-clicks the message to open the context menu and selects a specific option.

```APIDOC
## select_option(option)

### Description
Opens the right-click menu and selects the specified option.

### Parameters
- **option** (str) - The name of the option to select.

### Returns
- **WxResponse** - The result of the operation.
```

--------------------------------

### 定义默认表情列表

Source: https://docs.wxauto.org/docs/class/Other.html

WxParam.DEFAULT_STICKERS 包含了微信的默认表情列表，共计 128 个表情符号。

```python
DEFAULT_STICKERS = [
    # 基础表情
    '[微笑]', '[撇嘴]', '[色]', '[发呆]', '[得意]', '[流泪]', '[害羞]', '[闭嘴]', '[睡]', '[大哭]',
    '[尴尬]', '[发怒]', '[调皮]', '[呲牙]', '[惊讶]', '[难过]', '[囧]', '[抓狂]', '[吐]', '[偷笑]',
    '[愉快]', '[白眼]', '[傲慢]', '[困]', '[惊恐]', '[憨笑]', '[悠闲]', '[咒骂]', '[疑问]', '[嘘]',
    '[晕]', '[衰]', '[骷髅]', '[敲打]', '[再见]', '[擦汗]', '[抠鼻]', '[鼓掌]', '[坏笑]', '[右哼哼]',

    # 表情和手势
    '[鄙视]', '[委屈]', '[快哭了]', '[阴险]', '[亲亲]', '[可怜]', '[笑脸]', '[生病]', '[脸红]', '[破涕为笑]',
    '[恐惧]', '[失望]', '[无语]', '[嘿哈]', '[捂脸]', '[奸笑]', '[机智]', '[皱眉]', '[耶]', '[吃瓜]',
    '[加油]', '[汗]', '[天啊]', '[Emm]', '[社会社会]', '[旺柴]', '[好的]', '[打脸]', '[哇]', '[翻白眼]',

    # 符号和物品
    '[666]', '[让我看看]', '[叹气]', '[苦涩]', '[裂开]', '[嘴唇]', '[爱心]', '[心碎]', '[拥抱]', '[强]',
    '[弱]', '[握手]', '[胜利]', '[抱拳]', '[勾引]', '[拳头]', '[OK]', '[合十]', '[啤酒]', '[咖啡]',

    # 庆祝和节日
    '[蛋糕]', '[玫瑰]', '[凋谢]', '[菜刀]', '[炸弹]', '[便便]', '[月亮]', '[太阳]', '[庆祝]', '[礼物]',
    '[红包]', '[發]', '[福]', '[烟花]', '[爆竹]', '[猪头]', '[跳跳]', '[发抖]', '[转圈]', '[天啊]',

    # 其他
    '[强]', '[汗]', '[握手]',
]
```

--------------------------------

### 获取聊天窗口信息

Source: https://docs.wxauto.org/docs/class/Chat.html

获取当前聊天窗口的详细信息，返回一个包含类型和名称等数据的字典。

```python
info = chat.ChatInfo()
```

```python
# 好友
{'chat_type': 'friend', 'chat_name': '张三'}  

# 群聊
{'group_member_count': 500, 'chat_type': 'group', 'chat_name': '工作群'}  

# 客服
{'company': '@肯德基', 'chat_type': 'service', 'chat_name': '店长xxx'} 

# 公众号
{'chat_type': 'official', 'chat_name': '肯德基'}
```

--------------------------------

### 获取所有子窗口实例

Source: https://docs.wxauto.org/docs/class/WeChat.html

获取当前所有已打开的聊天窗口实例列表。

```python
chats = wx.GetAllSubWindow()
```

--------------------------------

### 关闭窗口

Source: https://docs.wxauto.org/docs/class/Chat.html

关闭当前的聊天窗口。

```python
wx.Close()
```

--------------------------------

### 微信基本操作示例

Source: https://docs.wxauto.org/docs/example.html

演示初始化微信实例、切换聊天窗口、发送消息以及获取聊天记录的基本流程。

```python
from wxautox4 import WeChat

# 初始化微信实例
wx = WeChat()

# 切换到文件传输助手
target = "文件传输助手"
wx.ChatWith(target)

# 查看当前窗口信息
chatinfo = wx.ChatInfo()
print(f"当前窗口信息：{chatinfo}")

# 发送消息
if chatinfo.get('chat_name') == target:  # 先判断是否为要发送的人
    wx.SendMsg("你好")

# 获取当前聊天窗口消息
msgs = wx.GetAllMessage()
for msg in msgs:
    print(f"消息内容: {msg.content}, 消息类型: {msg.type}")
```

--------------------------------

### 添加监听聊天窗口

Source: https://docs.wxauto.org/docs/class/WeChat.html

为指定好友设置消息监听回调函数。

```python
def on_message(msg, chat):
    print(f"收到来自 {chat} 的消息: {msg.content}")

wx.AddListenChat(nickname="张三", callback=on_message)
```

--------------------------------

### 修改群聊备注

Source: https://docs.wxauto.org/docs/class/Chat.html

修改当前群聊的备注信息。

```python
chat.SetGroupRemark(value="群备注")
```

--------------------------------

### 修改群昵称

Source: https://docs.wxauto.org/docs/class/Chat.html

修改用户在当前群聊中的昵称。

```python
chat.SetGroupMyNickname(value="我的群昵称")
```

--------------------------------

### 获取当前聊天窗口消息

Source: https://docs.wxauto.org/docs/start.html

通过 GetAllMessage 获取当前窗口的所有消息记录并进行遍历打印。

```python
# 获取当前聊天窗口消息
msgs = wx.GetAllMessage()

for msg in msgs:
    print('==' * 30)
    print(f"msg.content")
```

--------------------------------

### API响应格式

Source: https://docs.wxauto.org/plugin/http.html

统一的API响应结构。

```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    // 返回数据
  }
}
```

--------------------------------

### 多账号操作示例

Source: https://docs.wxauto.org/docs/cli/worker.html

通过 --nickname 参数指定特定账号执行业务命令。

```bash
wxautox4 --nickname "工作微信" worker start
wxautox4 --nickname "工作微信" status
wxautox4 --nickname "工作微信" message send "开始部署" --chat "项目群"
wxautox4 --nickname "工作微信" worker stop
```

--------------------------------

### 获取子窗口实例

Source: https://docs.wxauto.org/docs/class/WeChat.html

获取特定好友的聊天窗口实例。

```python
chat = wx.GetSubWindow(nickname="张三")
```

--------------------------------

### 获取聊天窗口类型

Source: https://docs.wxauto.org/docs/class/Chat.html

获取当前聊天窗口的类型，返回值为friend、group、service或official。

```python
chat_type = chat.chat_type
```

--------------------------------

### MomentsWnd.Publish

Source: https://docs.wxauto.org/docs/class/Moment.html

Publishes a new post to Moments.

```APIDOC
## Publish

### Description
Publishes a new post containing text and optional media files with privacy settings.

### Parameters
- **text** (str) - Required - The content of the post.
- **media_files** (list) - Optional - Default: None - A list of file paths for images or videos.
- **privacy_config** (dict) - Optional - Default: None - Privacy settings including 'privacy' (e.g., '白名单') and 'tags'.
```

--------------------------------

### API认证请求头

Source: https://docs.wxauto.org/plugin/http.html

在请求Header中包含认证token。

```http
Authorization: Bearer <your-token>
```

--------------------------------

### 发送消息

Source: https://docs.wxauto.org/docs/class/Chat.html

向指定对象发送消息，支持@特定用户和清空编辑框。

```python
wx.SendMsg(msg="你好", who="张三", clear=True, at="李四", exact=False)
```

--------------------------------

### Publish Moments

Source: https://docs.wxauto.org/docs/class/Moment.html

Post text and media to Moments with optional privacy configurations.

```python
text = '''oh
今天天气真好
适合出去走走

嘿嘿~
'''
media_files = [
    r"D:\Images\Pictures\1.png",
    r"D:\Images\Pictures\2.png",
    r"D:\Images\Pictures\3.png",
]
privacy_config = {
    'privacy': '白名单',    # 设置为黑名单模式
    'tags': ['家人','朋友']      # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人
}
# privacy_config = {}     # 公开发布，没有任何权限设置
pyq.Publish(text, media_files, privacy_config)
```

--------------------------------

### 修改群聊名称

Source: https://docs.wxauto.org/docs/class/Chat.html

修改当前群聊的名称。

```python
chat.SetGroupName(value="新群名")
```

--------------------------------

### 指定账号昵称

Source: https://docs.wxauto.org/docs/cli/index.html

根参数 --nickname 必须放置在业务命令之前。

```bash
wxautox4 --nickname "工作微信" status
```

--------------------------------

### 获取所有消息

Source: https://docs.wxauto.org/docs/class/Chat.html

获取当前聊天窗口中的所有历史消息。

```python
messages = wx.GetAllMessage()
```

--------------------------------

### 移除监听聊天

Source: https://docs.wxauto.org/docs/class/WeChat.html

停止对指定好友的消息监听。

```python
wx.RemoveListenChat(nickname="张三")
```

--------------------------------

### 初始化WeChatImage

Source: https://docs.wxauto.org/docs/class/Other.html

实例化WeChatImage类以处理微信图片或视频窗口操作。

```python
from wxautox4.ui.component import WeChatImage

imgwnd = WeChatImage()
```

--------------------------------

### ChatWith

Source: https://docs.wxauto.org/docs/class/WeChat.html

Opens a chat window with a specific contact.

```APIDOC
## ChatWith(who, exact=False)

### Description
Opens the chat window for the specified contact.

### Parameters
- **who** (str) - Required - The contact name to chat with
- **exact** (bool) - Optional - Whether to use exact matching (default: False)
```

--------------------------------

### 修改群公告

Source: https://docs.wxauto.org/docs/class/Chat.html

设置当前群聊的公告内容。

```python
chat.SetGroupAnnouncement(value="群公告内容")
```

--------------------------------

### Create Group

Source: https://docs.wxauto.org/docs/class/WeChat.html

Creates a new group chat with the specified list of contacts.

```python
wx.CreateGroup(contacts=["张三", "李四", "王五"])
```

--------------------------------

### 打开聊天窗口

Source: https://docs.wxauto.org/docs/class/WeChat.html

切换到指定好友的聊天窗口。

```python
wx.ChatWith(who="张三", exact=False)
```
Tokens:
Raw