WeChat CLI — 微信聊天记录读取与分析

本技能通过 wechat-cli 命令行工具，帮助用户读取和分析本地微信的聊天记录、联系人、收藏等数据。支持会话浏览、消息搜索、聊天记录导出、统计分析等功能。

适用场景

• 查看最近会话列表 / 未读消息
• 查看指定联系人或群聊的聊天记录
• 按关键词搜索消息
• 导出聊天记录为 Markdown 或纯文本
• 聊天统计分析（消息数量、活跃度等）
• 查看微信收藏
• 获取增量新消息（断点续传）
• 对聊天记录进行分类总结、重点提取等分析任务

前置条件

系统支持

• Windows（Weixin.exe）
• macOS（WeChat）
• Linux（wechat）

必须满足

1. 使用指定版本的微信 — wechat-cli 仅兼容微信 4.0+ 新版架构，不支持 3.x 旧版。本 skill 附带了指定版本的微信安装包，详见下方"微信安装"
2. 微信客户端已安装并登录 — 工具读取本地微信数据库，微信必须已登录
3. 初始化时微信必须处于运行状态 — 密钥提取需要扫描微信进程内存
4. Python 3.10+ — wechat-cli 是 Python 工具

微信安装（重要）

wechat-cli 仅支持微信 4.0 及以上版本，不支持微信 3.x 旧版。

为什么需要 4.0+：
- 微信 4.0 采用了全新的跨平台架构，进程名从 WeChat.exe 变为 Weixin.exe（Windows），数据目录从 WeChat Files 变为 xwechat_files
- wechat-cli 的密钥提取逻辑针对 4.0 架构设计，无法识别 3.x 版本的进程和数据库

本 skill 附带了以下微信安装包（与 skill 目录同级）：

Windows 安装指引

1. 解压安装包：将 WeChatWin-4.0.1.30.zip 解压到任意目录（如 C:\WeChat）
2. 运行微信：进入解压目录，双击 Weixin.exe 启动微信
3. 扫码登录：用手机微信扫码登录
4. 确认微信已完全启动并登录后，再执行 wechat-cli init

> Windows 版本是免安装绿色版，无需运行安装程序，解压后直接双击 Weixin.exe 即可使用。

macOS 安装指引

第一步：安装微信

1. 打开 DMG 文件：双击 WeChatMac-4.1.8.dmg，系统会挂载一个磁盘镜像
2. 安装微信：在弹出的窗口中，将左侧的 WeChat 图标拖拽到右侧的 Applications（应用程序） 文件夹
3. 弹出 DMG：安装完成后，在 Finder 侧边栏点击 DMG 磁盘旁的弹出按钮，卸载镜像

第二步：重新签名 WeChat（必须）

macOS 默认禁止读取其他进程内存，需要对微信进行 ad-hoc 重签名，wechat-cli 才能提取密钥。

1. 打开终端：在「启动台」搜索「终端」或「Terminal」并打开
2. 提取微信原有权限：

codesign -d --entitlements - --xml /Applications/WeChat.app > ~/wechat_ent.plist

3. 复制 WeChat 到用户目录（推荐，最安全）：

rm -rf ~/Applications/WeChat.app
cp -R /Applications/WeChat.app ~/Applications/

4. 对副本进行签名：

codesign --force --deep --sign - --entitlements ~/wechat_ent.plist ~/Applications/WeChat.app

5. 以后运行这个副本：

open ~/Applications/WeChat.app

第三步：登录并初始化

1. 打开微信：运行上一步签名后的副本（~/Applications/WeChat.app）
2. 处理安全提示：首次打开可能提示"无法验证开发者"或"来自身份不明的开发者"：
   - 点击 取消
   - 进入 系统设置 → 隐私与安全性，找到关于 WeChat 的安全提示，点击 仍要打开
   - 再次打开 WeChat，点击 打开
3. 扫码登录：用手机微信扫码登录
4. 确认微信已完全启动并登录后，执行初始化：

sudo wechat-cli init --force

> 为什么需要重新签名？ macOS 出于安全考虑，禁止进程读取其他进程的内存。wechat-cli 需要扫描微信进程内存来提取数据库解密密钥，因此必须对微信进行 ad-hoc 重签名以放开此限制。
>
> 注意：微信更新后需要重新签名。每次微信自动更新后，重复上述第二步即可。

已安装旧版微信怎么办？

如果电脑上已经安装了旧版微信（3.x），需要先卸载或退出旧版，再安装上述指定版本。Windows 绿色版无需卸载原有微信，但建议退出正在运行的旧版微信后再启动新版。

> 重要：必须使用附带的指定版本微信。其他版本（即使也是 4.0+）可能因架构差异导致密钥提取失败。

安装

pip install wechat-cli

依赖包（自动安装）：click、pycryptodome、zstandard

安装完成后验证：

wechat-cli --version
# 输出: wechat-cli, version 0.2.4

初始化（首次使用必读）

初始化会提取微信数据库的加密密钥并生成配置文件。只需执行一次。

步骤

1. 确保微信正在运行且已登录（这是必须的，密钥从微信进程内存中提取）

2. 执行初始化命令：

wechat-cli init

工具会自动：
- 检测微信数据目录
- 扫描微信进程内存提取数据库密钥
- 在 ~/.wechat-cli/ 下生成 config.json 和 all_keys.json

3. 如果自动检测失败，手动指定数据目录：

wechat-cli init --db-dir "C:\path\to\db_storage"

微信数据目录位置参考

> 提示：<wxid> 是你的微信内部 ID，类似 wxid_xxxxxxxxxxxxx。

重新初始化

如果密钥过期（如微信更新后），强制重新提取：

wechat-cli init --force

配置文件说明

初始化后，配置保存在 ~/.wechat-cli/ 目录：

快速入门

1. 查看最近会话

wechat-cli sessions

2. 查看某人的聊天记录

wechat-cli history "张三" --limit 20

3. 搜索消息

wechat-cli search "关键词"

4. 查看未读会话

wechat-cli unread

5. 导出聊天记录

wechat-cli export "张三" --format markdown --output chat.md

命令总览

> 完整命令参数详见 references/commands.md

输出格式

大多数命令支持 --format 参数：
- json（默认）— 结构化 JSON，适合程序处理
- text — 纯文本，适合人类阅读

时间格式：YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS

消息类型过滤（--type）：text、image、voice、video、sticker、location、link、file、call、system

重要注意事项

• 默认限制：history 默认返回 50 条，search 最大 500 条，sessions 默认 20 个。导出大量数据时用 --limit 100000
• 系统占位会话：brandsessionholder、@placeholder_foldgroup 是系统占位符，导出时会失败，属正常现象
• 隐私安全：所有数据仅在本地处理，不会上传任何信息
• 微信需运行：虽然查询操作不需要微信运行，但初始化（密钥提取）必须微信在线

分析工作流

当用户需要分析聊天记录时，推荐工作流详见 references/analysis-guide.md。

典型流程：
1. sessions — 浏览会话列表，确定分析对象
2. history — 读取目标聊天的消息记录
3. 对消息内容进行分类、总结、提取重点
4. 如需深度分析，用 stats 获取统计数据辅助

故障排查

常见问题及解决方案详见 references/troubleshooting.md。

微信 4.1.12+ 密钥提取（重要适配，2026-08-10 实测）

> 背景：微信 4.1+ 不再在进程内存缓存明文密钥（x'...' 格式），wechat-cli init 的内存扫描在 4.1+ 上 0 命中属正常。wx_key（DLL 注入工具）已被 DMCA 下架，GitHub release 全删。实测发现：4.1.12 的 com.Tencent.WCDB.Config.Cipher 对象里存的是每个数据库的（派生后密钥 32B + salt 16B）十六进制对，密钥可直接用于解密，无需 PBKDF2。

前提

• 微信 4.1.12+ 正在运行且已登录
• 必须确认当前登录账号与目标 db_storage 目录一致（多开/多账号环境：内存里的密钥属于当前登录账号！用 check_account 逻辑扫描内存中 wxid_xxx 出现次数确认）
• Python 环境（本机：C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe）

步骤

1. 扫描并 dump Config.Cipher blob（脚本内改 DB_DIR 为目标账号目录）：
   python scripts/dump_config_blobs.py
   产出 C:/Users/Administrator/AppData/Local/Temp/config_dump/blob_*.bin
2. 提取密钥并生成配置（脚本内改 DB_DIR）：
   python scripts/gen_keys.py
   自动对 blob 中所有 64~192 hex 串取 32B 窗口，用 HMAC 校验匹配数据库 salt，生成 ~/.wechat-cli/all_keys.json + config.json
3. 验证：
   wechat-cli sessions --limit 5 --format text

已知限制

• 实测 16/18 库成功；message\weclaw.db、solitaire\solitaire.db 未提取到（非核心库，不影响聊天记录查询）
• 微信重启/更新后密钥可能变化，需重新执行上述步骤
• 若 Config.Cipher 扫描 nodes=0：微信版本过新或进程选择错误，先确认登录账号
• 密钥对是 (key+salt)，直接当加密密钥用，不要做 PBKDF2 派生（那是 4.1.x 早期版本的 passphrase 路线）

本机环境速查

• wechat-cli 可执行文件：C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/wechat-cli.exe
• Python：C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe
• 配置目录：~/.wechat-cli/（all_keys.json / config.json）
• 多账号：数据在 E:\微信\xwechat_files\<wxid>\db_storage（账号1 wxid_32ebc6ww7zh122_5d5c、账号2 wxid_hgsqppf2wc0022_4ddd、账号3 wxid_r5y285z5zj5d22_1952）
• 双账号配置：账号1/2 密钥均已提取（各 16/18 库），备份为 ~/.wechat-cli/all_keys_account{1,2}.json
• 切换账号：python scripts/switch_account.py 1|2（复制对应密钥 + 更新 config.json），切换后无需重启微信（查询只读数据库）
• 提取新账号密钥：确认微信登录该账号后，python scripts/extract_keys.py --db-dir <db_storage> --out ~/.wechat-cli/all_keys_accountN.json

参考文档

• 完整命令参考
• 消息分析工作流指南
• 常见问题排查