wechat_msg_clicker/README.md

WeChat 消息自动点击器

自动点击微信桌面端未读消息中的图片和文件，触发原始文件下载到本地目录。

背景

微信桌面端不会自动下载图片/文件的原始数据，需要用户手动点击预览后才会触发下载。本工具通过 macOS 辅助功能 API 自动完成这个操作，配合信息收集系统实现群聊数据的自动化入库。

系统要求

• macOS Sonoma 14+
• Python 3.11+
• 微信桌面端 v4.1.9+（已登录）

安装

1. 安装 Python 依赖

cd wechat_msg_clicker
pip install -r requirements.txt

依赖包：

• pyobjc-framework-Quartz — macOS 图形框架绑定
• pyobjc-framework-ApplicationServices — 辅助功能 API 绑定
• pyobjc-framework-Cocoa — macOS 应用框架绑定
• PyYAML — 配置文件解析

2. 授权辅助功能权限

脚本需要 macOS 辅助功能权限才能操作微信 UI 元素：

1. 打开 系统设置 > 隐私与安全性 > 辅助功能
2. 点击左下角 + 号
3. 添加你使用的终端应用（如 Terminal.app 或 iTerm2）
4. 如果通过 Python 直接运行，还需要添加 Python 解释器路径（如 /Users/你的用户名/miniconda3/bin/python3）
5. 确保添加后开关为 开启 状态

首次运行时如果未授权，脚本会弹出系统提示框引导你授权。

3. 准备配置文件

cp config.example.yaml config.yaml

按需编辑 config.yaml，主要配置项：

配置项	默认值	说明
scan.interval_seconds	30	扫描间隔（秒）
scan.max_chats_per_scan	5	每次最多处理几个聊天
schedule.start_hour	8	工作开始时间
schedule.end_hour	23	工作结束时间
filter.mode	all	过滤模式：all / whitelist / blacklist
filter.blacklist	微信系统号	排除的聊天名称
media.click_images	true	是否点击图片
media.click_files	true	是否点击文件
media.click_videos	false	是否点击视频（默认关闭）
media.max_media_per_chat	20	每个聊天最多点击几个媒体

4. 确保微信就绪

• 微信桌面端已启动并登录
• 微信窗口保持可见（不能最小化到 Dock）
• 建议在专用电脑上运行，脚本运行时会操作微信前台窗口

验证流程

建议按以下顺序逐步验证，确认每步正常后再进入下一步：

Step 1：验证 UI 访问

python main.py --dump-ui

预期输出：微信的 UI 元素树，包括窗口、按钮、聊天列表等信息。

如果报错：

• 辅助功能权限未授予 → 检查系统设置中的辅助功能授权
• 微信未运行 → 确保微信桌面端已启动
• 未找到微信主窗口 → 确保微信已登录，窗口未最小化

Step 2：试运行扫描

python main.py --dry-run --once --debug

预期输出：扫描聊天列表，显示有未读消息的聊天和媒体数量，但不会实际点击。

检查日志确认：

• 能正确识别未读聊天
• 聊天名称解析正确
• 未读数量解析正确

Step 3：单次完整执行

python main.py --once --debug

这会执行一次完整的循环：扫描 → 点击聊天 → 点击图片/文件 → 关闭预览 → 关闭会话。

观察过程中：

• 微信窗口是否正常被操作
• 图片预览是否正常打开和关闭
• 是否能正确返回聊天列表

Step 4：正式运行

python main.py

脚本会持续运行，按配置的间隔和工作时间自动处理新消息。

后台运行建议使用 nohup 或 tmux：

# 方式一：nohup
nohup python main.py > /dev/null 2>&1 &

# 方式二：tmux（推荐，方便查看日志）
tmux new -s wechat
python main.py
# Ctrl+B D 分离会话
# tmux attach -t wechat 重新连接

命令参考

命令	说明
python main.py	持续运行
python main.py --once	单次扫描后退出
python main.py --dry-run	只扫描不点击
python main.py --dump-ui	输出微信 UI 元素树
python main.py --debug	开启 DEBUG 级别日志
python main.py --config path/to/config.yaml	指定配置文件

参数可组合使用，如 python main.py --dry-run --once --debug。

日志

日志同时输出到控制台和文件 wechat_clicker.log（可在配置中修改）。

日志文件自动轮转，默认最大 10MB，保留 5 个备份。

注意事项

• 封号风险：工具内置了多种拟人策略（随机延迟、长休息、工作时间限制），但自动化操作始终存在被检测的可能，请自行评估风险
• 微信更新：微信版本更新可能改变 UI 结构，导致脚本失效。如遇到问题，先用 --dump-ui 检查 UI 变化
• 前台占用：脚本运行时会操作微信窗口，不建议同时手动使用微信