shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

通过 wechat-cli 读取和分析微信聊天记录

通过 wechat-cli 读取和分析微信聊天记录。当用户想查看、搜索、导出或分析微信消息、联系人、收藏时调用此技能。

person作者: user_814dbe54hubcommunity
download下载资源包

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 | WeChatWin-4.0.1.30.zip | 4.0.1.30 | 免安装绿色版，解压即用 | | macOS | WeChatMac-4.1.8.dmg | 4.1.8 | DMG 安装镜像 |

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
  1. 复制 WeChat 到用户目录（推荐，最安全）：
rm -rf ~/Applications/WeChat.app
cp -R /Applications/WeChat.app ~/Applications/
  1. 对副本进行签名：
codesign --force --deep --sign - --entitlements ~/wechat_ent.plist ~/Applications/WeChat.app
  1. 以后运行这个副本：
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
  1. 如果自动检测失败，手动指定数据目录：
wechat-cli init --db-dir "C:\path\to\db_storage"

微信数据目录位置参考

| 系统 | 默认路径 | |------|----------| | Windows | %APPDATA%\Tencent\xwechat\config\*.ini 指向的目录下 xwechat_files\<wxid>\db_storage | | macOS | ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage | | Linux | ~/Documents/xwechat_files/<wxid>/db_storage |

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

重新初始化

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

wechat-cli init --force

配置文件说明

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

| 文件 | 说明 | |------|------| | config.json | 主配置，记录 db_dir（数据库路径） | | all_keys.json | 数据库解密密钥 | | last_check.json | new-messages 命令的状态文件（记录上次读取位置） |

快速入门

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

命令总览

| 命令 | 说明 | 常用参数 | |------|------|----------| | init | 初始化（提取密钥） | --db-dir, --force | | sessions | 最近会话列表 | --limit, --format | | history | 指定聊天的消息记录 | --limit, --offset, --start-time, --end-time, --type, --media | | search | 搜索消息内容 | --chat, --start-time, --end-time, --limit, --type | | contacts | 搜索/列出联系人 | --query, --detail, --limit | | export | 导出聊天记录 | --format, --output, --start-time, --end-time, --limit | | members | 群聊成员列表 | --format | | stats | 聊天统计分析 | --start-time, --end-time, --format | | unread | 未读会话 | --limit, --format | | new-messages | 增量新消息 | --format | | favorites | 微信收藏 | --type, --query, --limit, --format |

完整命令参数详见 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

参考文档