· 开发工具 · HTML
wx-cli 深度解读 - 命令行查询微信本地数据
wx-cli 深度解读:Rust 编写的微信本地数据命令行工具,通过 daemon 架构实现毫秒级查询,完全本地、AI 友好,数据不出本机。
wx-cli: 命令行查询微信本地数据
Rust 编写的零依赖命令行工具。Daemon 架构持久缓存,毫秒级响应。数据完全本地解密,不出本机。支持会话、搜索、朋友圈、公众号、附件提取、统计、导出,以及 AI Agent 集成。
背景与起源
微信 4.x 采用 SQLCipher 4 加密本地数据库 (AES-256-CBC + HMAC-SHA512, PBKDF2 256,000 次迭代)。数据存储在本地但用户难以直接访问。此前社区已有 wechat-decrypt 等研究性项目,但大多需要手动提取密钥、全量解密或依赖 Python 环境。
wx-cli 由 jackwener 开发,在 wechat-decrypt 的研究基础上重新设计,目标是打造零依赖、毫秒级、AI 友好的生产级工具。项目于 2026 年 3 月开源,迅速积累 3.6k Stars,被 SourceForge 镜像收录,并支持通过 skills CLI 一键安装到 Claude Code、Cursor、Codex 等 AI Agent。
解决的问题
数据锁定在加密数据库
微信本地数据使用 SQLCipher 加密,普通用户无法直接查看或导出自己的聊天记录。
现有工具依赖繁重
Python 脚本需要配置环境、手动提取密钥,全量解密耗时长且占用大量磁盘。
AI Agent 难以消费数据
传统输出格式缺乏元信息,Agent 无法判断数据新鲜度和来源可靠性。
隐私与安全顾虑
在线工具需要上传数据,本地全量解密会在磁盘留下明文副本。
架构: CLI + Daemon 双进程
wx-cli 采用双进程架构: CLI 负责用户交互,daemon 负责后台缓存与解密。两者通过 Unix socket 通信,首次解密后将数据库和 mtime 持久化到 ~/.wx-cli/cache/,后续 mtime 未变则直接复用。
CLI 通过 Unix socket 与 daemon 通信 // daemon 从微信进程内存提取密钥并缓存解密数据库
内存扫描原理
微信 4.x 将派生后的 raw key 缓存在进程内存中,格式为 x'<64hex_key><32hex_salt>'。wx-cli 通过平台特定 API 扫描微信进程内存:
mach_vm_region
mach_vm_read
/proc/<pid>/mem
VirtualQueryEx
ReadProcessMemory
功能
会话与消息
history / search / unread / new-messages,支持时间范围和关键词过滤
联系人与群组
contacts / members,群昵称优先,稳定身份三件套 (wxid / 显示名 / 群名片)
朋友圈
sns-notifications / sns-feed / sns-search,点赞评论通知与帖子时间线
公众号文章
查询独立分片,按公众号名称、时间范围、未读状态筛选
附件提取
attachments 列出图片,extract 解密导出原图 (XOR / V1-AES / V2 三档解码)
收藏与统计
favorites 按类型筛选,stats 聊天统计,top_senders 群名片解析
导出
支持 markdown / json 格式,可指定条数和时间范围
AI Agent 集成
返回 meta wrapper,agent 直接消费 freshness / source;支持 skills CLI 一键安装
命令速查
| Command | Description | Example |
|---|---|---|
sessions | 最近 20 个会话 | wx sessions |
history | 聊天记录 | wx history "name" -n 200 |
search | 全库搜索 | wx search "key" --in "group" |
unread | 未读消息 | wx unread --filter private |
new-messages | 增量新消息 | wx new-messages |
sns-feed | 朋友圈时间线 | wx sns-feed --user "name" |
biz-articles | 公众号文章 | wx biz-articles --unread |
attachments | 列出附件 | wx attachments "group" --kind image |
stats | 聊天统计 | wx stats "group" --since 2026-01-01 |
export | 导出记录 | wx export "name" -o chat.md |
工作流
install // init // query // agent consume // export
macOS 初始化
macOS 需要先对微信做 ad-hoc 重签名以扫描内存,重签名后还需清理 TCC 授权记录并重启微信。详见项目 权限指南。
# macOS 初始化完整流程
codesign --force --deep --sign - /Applications/WeChat.app
# 清理 TCC 授权记录
for s in ScreenCapture Camera Microphone ...; do
tccutil reset "$s" com.tencent.xinWeChat
done
killall WeChat && open /Applications/WeChat.app
sudo wx initAI Agent 友好设计
每个主要命令默认返回 {..., meta} wrapper,包含数据新鲜度和来源信息,让 AI Agent 能可靠地判断数据状态:
wx history "name" --json
{
"results": [...],
"meta": {
"status": "ok",
"chat_latest_timestamp": 1719200000,
"chat_latest_db": "message_3.db",
"session_last_timestamp": 1719200100,
"unknown_shards": []
}
}status 字段取值: ok (数据完整) / possibly_stale (可能有更新) / windowed (结果被截断)。Agent 可据此决定是否需要重新查询。
Agent Skill 安装
# Claude Code / Cursor / Codex
npx skills add jackwener/wx-cli
# global
npx skills add jackwener/wx-cli -g安装后 Agent 自动读取 SKILL.md,了解如何调用 wx-cli 完成微信数据相关任务。
使用场景
推荐
- 导出自己的聊天记录做备份或分析
- 让 AI Agent 读取微信数据完成自动化任务
- 搜索历史消息中的关键信息
- 统计群聊活跃度与发言排行
- 提取聊天中的图片附件原图
- 查看公众号文章推送记录
不推荐
- 未经授权访问他人的微信数据
- 用于商业数据分析 (违反微信 ToS)
- 大规模爬取或批量导出 (性能限制)
- 需要实时推送 (非事件驱动架构)
- 微信未运行时查询 (需进程存活)
- Linux 上的 V2 图片解码 (暂不支持)
评分
局限
macOS 重签名副作用
ad-hoc 重签后微信会频繁弹出"想访问其他 App 的数据"提示,这是 macOS TCC 机制的已知行为。
微信需保持运行
初始化时需要微信进程存活以扫描内存提取密钥。Daemon 缓存密钥后日常查询无需微信在前台。
Linux V2 图片不支持
V2 格式图片解密依赖平台特定的密钥派生,Linux 上暂未实现,遇到 V2 .dat 文件会报错。
朋友圈数据有限
只覆盖本地刷到过的帖子 (微信按需下载),不是完整的朋友圈历史。
FAQ
数据安全吗? 会不会上传到服务器?
完全本地。密钥提取和数据库解密都在本机完成,没有任何网络请求。Daemon 缓存的解密数据库存在 ~/.wx-cli/cache/,不会同步到云端。
微信更新后需要重新初始化吗?
如果微信更新导致二进制变化,macOS 上需要重新 ad-hoc 签名并执行 wx init --force。数据库 mtime 未变时 daemon 会复用缓存,无需重复解密。
支持微信 3.x 吗?
wx-cli 针对微信 4.x 的 SQLCipher 4 加密方案设计。微信 3.x 使用不同的加密机制,不在当前支持范围内。
如何与 AI Agent 集成?
通过 npx skills add jackwener/wx-cli 安装为 Skill,Agent 会自动读取 SKILL.md 了解调用方式。也可以直接在脚本中调用 CLI 命令并解析 JSON 输出。