pandorafuture wx-cli — WeChat 数据查询工具
Overview
wx-cli 解密并查询 WeChat macOS 加密数据库。零参数即可运行——自动检测账号、密钥和数据目录。
核心原则： 用 --format json 获取结构化数据供分析；用默认 text 格式展示给用户。
When to Use
- 用户问"最近跟谁聊了什么"、"某人发过什么消息"
- 用户要搜索聊天记录中的关键词
- 用户要查看联系人信息
- 用户要解密数据库或图片
- 用户提到 WeChat / 微信相关数据需求
Quick Reference
| 需求 | 命令 |
|---|---|
| 当前状态 | wx-cli status |
| 密钥提取（推荐） | wx-cli key extract |
| 手动设置数据库密钥 | wx-cli key set <account_id> <hex_key> |
| 手动设置图片密钥 | wx-cli key set-image <account_id> <image_key> |
| 已存密钥列表 | wx-cli key list |
| 解密数据库 | wx-cli decrypt |
| 增量解密 | wx-cli decrypt --incremental |
| 解密图片（自动推导密钥） | wx-cli decode-image <路径> -d <data_dir> |
| 解密图片（手动 V2 key） | wx-cli media decrypt-dat <路径> --v2-key <key> |
| 解密图片（KeyStore） | wx-cli decode-image <路径> --account <account_id> |
| 提取语音 | wx-cli media extract-voice --media-dir <dir> <svr_id> |
| 提取语音（原始 SILK） | wx-cli media extract-voice --media-dir <dir> <svr_id> --raw |
| 解密视频号视频 | wx-cli media decrypt-video <文件> --seed <seed> |
| 查询 hardlink 路径 | wx-cli media resolve-path --db <hardlink.db> <key> |
| 检查 DB 文件 | wx-cli info <db_file> |
| 版本信息 | wx-cli --version |
| 最近会话列表 | wx-cli sessions |
| 查看系统路径 | wx-cli paths |
| 查看系统路径（JSON） | wx-cli paths --json |
| 忽略隐藏配置查看完整会话列表 | wx-cli sessions --show-hidden |
| 搜索联系人 | wx-cli contacts --search <关键词> |
| 忽略隐藏配置搜索联系人 | wx-cli contacts --search <关键词> --show-hidden |
| 查某人的消息 | wx-cli query <联系人名/账号ID> |
| 忽略隐藏配置查看消息 | wx-cli query <联系人> --show-hidden |
| 定位某条消息上下文 | wx-cli query <联系人> --around-sort-seq <seq> --context 10 |
| 按 server_id 定位上下文 | wx-cli query <联系人> --around-server-id <id> --context 10 |
| 增量拉取新消息 | wx-cli query <联系人> --after-sort-seq <seq> --limit 20 |
| 全局搜索关键词 | wx-cli search <关键词> |
| 导出会话（TXT，默认并行） | wx-cli export <联系人> -o <目录> --all |
| 导出会话（JSON，默认并行） | wx-cli export <联系人> -o <目录> --all --format json |
| 忽略隐藏配置导出会话 | wx-cli export <联系人> -o <目录> --all --show-hidden |
| 导出（无媒体） | wx-cli export <联系人> -o <目录> --all --no-media |
| 启动 HTTP API | wx-cli server run |
| 查看 HTTP 服务状态 | wx-cli server status |
| 停止 HTTP 服务 | wx-cli server stop |
| 重启 HTTP 服务 | wx-cli server restart |
| HTTP API（远程） | wx-cli server run --host 0.0.0.0 --token <secret> |
| 实时监听会话变化 | wx-cli watch |
| 实时监听（忽略隐藏配置） | wx-cli watch --show-hidden |
| 实时监听（轮询） | wx-cli watch --poll --poll-ms 3000 |
| 实时监听（文件事件模式） | wx-cli watch --fsnotify |
| 前置条件检查 | wx-cli doctor |
| 前置条件检查 + 修复建议 | wx-cli doctor --fix |
前置条件
密钥提取需要 SIP 禁用，通常不需要 sudo。SIP enabled 时 task_for_pid 被内核拒绝（kern_return=5），即使 root 也不行。检查 SIP 状态：csrutil status。禁用需在 Recovery Mode 执行 csrutil disable。
常用工作流
0. 首次使用：提取密钥并解密
WeChat 数据库是加密的，查询前必须先有密钥。需要 SIP 禁用（SIP enabled 时 task_for_pid 被内核拒绝）：
# LLDB hook 提取密钥 — 会重启 WeChat，需要 LLDB + python3，通常不需要 sudo
wx-cli key extract --timeout 120
key extract 拿到的是完整数据库密钥，覆盖所有数据库。后续多数查询可直接读取加密数据库，无需先执行 decrypt。
提取后验证：
# 查看已存密钥（`raw=yes` 表示已保存完整数据库密钥）
wx-cli key list
# 有完整数据库密钥时：query/sessions/search/contacts/server run/watch 可直接读取加密数据库，无需先 decrypt
# 如需明文导出
wx-cli decrypt
wx-cli decrypt --incremental
手动设置密钥：
wx-cli key set <account_id> 0123456789abcdef... # 数据库密钥（32 字节 hex）
wx-cli key set-image <account_id> abcdefghijklmnop # 图片 AES 密钥（V2 格式）
密钥类型说明：
| 密钥 | 用途 | 提取方式 | 覆盖范围 |
|---|---|---|---|
完整数据库密钥（raw_key） |
解密 SQLite 数据库 | key extract（LLDB hook） |
所有 DB |
| Image key（16 bytes） | 解密 V2 格式 .dat 图片 | decode-image -d <data_dir> 自动推导 |
— |
1. 查看最近聊天
wx-cli sessions --limit 10
# 返回按时间倒序的会话列表，含联系人显示名和最后一条消息摘要
2. 查找某人并读消息
# 先搜联系人（支持昵称、备注、wxid、微信号、手机号等模糊匹配）
wx-cli contacts --search 张三
# 用搜到的名字或 wxid 查消息
wx-cli query 张三 --limit 20
# 用 JSON 获取结构化数据
wx-cli query 张三 --format json --limit 50
2a. 联系人隐藏规则
配置文件：~/Library/Application Support/wx-cli/config/settings.toml
[accounts."<account_id>"]
ignore_contacts = ["wxid_hidden_contact"]
ignore_tags = ["同事"]
query/sessions/contacts/export/watch支持--show-hidden忽略隐藏配置search当前不会自动应用隐藏配置- 隐私优先： 当输出里出现
[消息已隐藏]，除非用户明确要求，agent 不应主动追加--show-hidden
3. 全局搜索关键词
wx-cli search 周末 --limit 20
# 优先查询 WeChat 自带的全文索引库，搜索通常在亚秒级完成
搜索语义：
- 中文按字拆分；英文支持 Porter stemming
- 多词搜索为 AND 逻辑
stats.scanned=0表示走微信内置全文索引；stats.scanned>0表示退回到全量扫描
4. 按条件过滤消息
wx-cli query 张三 --type text # 按类型：text/image/voice/video/emoji/app/system/revoke
wx-cli query 张三 --since 1772600000 --until 1772700000 # 时间范围（Unix 秒）
4b. 锚点上下文查询
wx-cli query 张三 --around-sort-seq 1773421188000 --context 10 # 按 sort_seq 定位前后 10 条
wx-cli query 张三 --around-server-id 5455993825313690274 --context 10 # 按 server_id 定位
wx-cli query 张三 --after-sort-seq 1773421188000 --limit 20 # 增量拉取新消息
行为规则：
- 锚点查询始终按升序返回，
--order desc会被忽略 --context默认 50，仅对around-*有效around-*参数与--since/--until/--all互斥--around-sort-seq、--around-server-id、--after-sort-seq三者互斥
5. 群聊查询
wx-cli query 18819405230@chatroom --limit 10 # 群聊 ID
wx-cli query 周末爬山群 # 或群名模糊匹配
6. 导出会话
wx-cli export 张三 -o /tmp/export/ --all # TXT 格式，全部消息
wx-cli export 张三 -o /tmp/export/ --all --format json # JSON 格式
wx-cli export 张三 -o /tmp/export/ --all --no-media # 跳过媒体文件
wx-cli export 张三 -o /tmp/export/ --all --show-emoji # 显示表情细节
排序默认 asc（时间正序），与 query 默认 desc 相反。
7. 图片解密与转码
# 推荐：-d 自动推导 V2 密钥
wx-cli decode-image input.dat -d <account_data_dir> -o output.png
# 批量目录
wx-cli decode-image /path/to/dat_dir/ -d <account_data_dir> -o /tmp/output/
# 直接传入 V2 AES key
wx-cli media decrypt-dat input.dat --v2-key abcdefghijklmnop -o output.png
8. 语音提取
wx-cli media extract-voice --media-dir <dir> <svr_id> -o voice.mp3 # 默认 MP3（需 ffmpeg）
wx-cli media extract-voice --media-dir <dir> <svr_id> --raw -o voice.silk # 原始 SILK
8b. Hardlink 路径查询
wx-cli media resolve-path --db /path/to/hardlink.db <md5_key> # 图片
wx-cli media resolve-path --db /path/to/hardlink.db --media-type video <key> # 视频
wx-cli media resolve-path --db /path/to/hardlink.db --media-type file <key> # 文件
9. 视频号视频解密
wx-cli media decrypt-video encrypted.bin --seed 2105122989 -o video.mp4 # 十进制 seed
wx-cli media decrypt-video encrypted.bin --seed 0x7d844e8d -o video.mp4 # 十六进制 seed
10. HTTP API 服务
wx-cli server run # 本地启动（默认 127.0.0.1:9100）
wx-cli server run --host 0.0.0.0 --token mysecret # 远程访问（必须设 token）
wx-cli server status / stop / restart # 管理服务
10a. CLI 自动复用已运行的 server
sessions、contacts、query、search 默认会先尝试连接本机 http://127.0.0.1:9100，如果 server 可用就走 HTTP，否则回退到本地直查。
| 参数 | 说明 |
|---|---|
--server-url <url> |
覆盖默认地址 |
--server-token <token> |
Bearer token |
--server-only |
只走远程，不回退 |
--no-server |
强制本地查询 |
10b. REST 端点（只读）
| 端点 | 说明 | 关键参数 |
|---|---|---|
GET /api/v1/health |
健康探测 | 无 |
GET /api/v1/sessions |
会话列表 | limit, offset, order, show_hidden |
GET /api/v1/contacts |
联系人列表 | limit, offset, search, show_hidden |
GET /api/v1/messages |
消息查询 | contact（必填）, limit, offset, since, until, type, order, around_sort_seq, around_server_id, after_sort_seq, context, show_hidden |
GET /api/v1/timeline |
跨全部会话按时间批量读取消息 | since（必填）, until（必填）, limit, offset, type, order, show_hidden |
GET /api/v1/media |
媒体内容直出 | server_id（必填）, talker（必填）, format=ogg|mp3（仅语音） |
GET /api/v1/search |
全文搜索 | q（必填）, limit, offset |
GET /api/v1/events |
SSE 事件流 | 无 |
图片响应会携带 X-Wechat-Media-Quality: full|thumbnail。服务会优先返回本机已有的高清/原图文件；若微信只下载过缩略图，则返回 thumbnail，调用方不应长期缓存，并可在微信下载原图后重试。
认证： 带 --token 启动时须携带 Authorization: Bearer <token>。--host 不是本机地址时 --token 必填。
当前 HTTP API 为只读，没有 send/reply/webhook 等写接口。
11. 实时监听
wx-cli watch # 默认启动
wx-cli watch --poll --poll-ms 5000 # 自定义轮询间隔
wx-cli watch --format json # JSON 格式（每行一个 JSON 对象）
wx-cli watch --show-hidden # 忽略隐藏配置
12. 前置条件检查
wx-cli doctor # 列出各项检查结果（SIP、DevToolsSecurity、_developer、lldb、python3）
wx-cli doctor --fix # 对 FAIL 项输出修复命令
错误自动恢复
error: no key for account <account_id>
wx-cli status # 1. 确认 WeChat 状态
wx-cli key extract --timeout 120 # 2. 提取密钥
wx-cli key list # 3. 验证密钥
wx-cli sessions # 4. 重试查询
task_for_pid failed (kern_return=5) — SIP 启用，需在 Recovery Mode 执行 csrutil disable。
warning: ffmpeg not found — 安装 ffmpeg：brew install ffmpeg，或 FFMPEG_PATH=/path/to/ffmpeg wx-cli ...
JSON 输出结构
所有查询命令加 --format json 返回统一信封：
{
"items": [...],
"paging": { "offset": 0, "limit": 20, "returned": 20, "total": 103, "has_more": true },
"stats": { "scanned": 103, "skipped": 0, "elapsed_ms": 3 }
}
| 命令 | item 关键字段 |
|---|---|
| sessions | username, display_name, avatar_url?, summary, sort_timestamp, direction? |
| query | sort_seq, server_id, msg_type, sender, content, direction |
| timeline API | sort_seq, server_id, msg_type, sender, talker, talker_display_name, create_time, direction, snippet；统一按时间跨会话排序 |
| contacts | user_name, alias, remark, nick_name, avatar_url?, phone, labels |
| search | server_id, talker, sender, snippet, hit_type |
易混淆字段：
- contacts 用
user_name（下划线），sessions 用username（无下划线） avatar_url优先取微信小头像地址，缺失时回退大头像地址；本地没有记录时不输出- message 的
sender才是消息级 self/other 判断依据 /api/v1/health的current_account.wxid是判断"我发的"的主事实源
JSON 编程使用： JSON 走 stdout，诊断信息走 stderr。分离采集才能正确解析：
OUTPUT=$(wx-cli query 张三 --format json --limit 5)
echo "$OUTPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['items']))"
分页与排序
wx-cli query 张三 --format json --limit 10 --offset 0 # 第一页
wx-cli query 张三 --format json --limit 10 --offset 10 # 第二页
wx-cli query 张三 --order asc # 时间正序
wx-cli query 张三 --all # 获取全部消息（上限 20,000）
消息类型标签（type=49 结构化解析）
| 变体 | sub_type | 输出 |
|---|---|---|
| Link | 4, 5, 7, 92 | [链接] <标题> |
| File | 6 | [文件] <文件名> |
| MiniProgram | 33, 36 | [小程序] <名称> |
| MergedMessages | 19 | [聊天记录] <标题> |
| Quote | 57 | [引用 @发送者: 原文] 回复文本 |
| Transfer | 2000 | [转账] ¥金额 |
| RedEnvelope | 2001, 2003 | [红包] <标题> |
| ChannelVideo | 51, 63 | [视频号] <标题> |
| Pat | 62 | [拍一拍] |
JSON content 字段为 tagged union：外层 key 是变体名，值是结构化字段。
文件路径
| 类别 | 路径（macOS） | 用途 |
|---|---|---|
| Config | ~/Library/Application Support/wx-cli/config/ |
密钥、设置 |
| Cache | ~/Library/Caches/wx-cli/ |
解密后数据库 |
| State | ~/Library/Application Support/wx-cli/state/ |
服务运行时 |
| Logs | ~/Library/Logs/wx-cli/ |
服务日志 |
| Temp | $TMPDIR/wx-cli/ |
密钥提取临时文件 |
使用 wx-cli paths 查看所有路径。
注意事项
- 所有命令自动检测账号和密钥，通常无需
--account或--key query支持 wxid、chatroom ID、filehelper，也支持中文名模糊匹配search直接查询 WeChat 自带message_fts.db，无需单独建索引search当前不会自动应用隐藏配置，也没有--show-hidden--all覆盖--limit（当前上限 20,000）；export --all会按批次拉完全部结果--limit 0会退回到该命令的默认值server run启动后会自动增量刷新解密缓存
诊断策略
当查询返回空结果时，不要反复换参数重试：
# 1. 检查 stats.skipped
wx-cli query <contact> --all --format json 2>/dev/null | \
python3 -c "import json,sys; d=json.load(sys.stdin); print(f'items={len(d[\"items\"])}, skipped={d[\"stats\"][\"skipped\"]}')"
# 2. skipped > 0 → 重新解密
wx-cli decrypt
# 3. items=0 且 skipped=0 → 检查联系人
wx-cli contacts --search <name> --format json