wx-cli 项目解读：用命令行查询本地微信聊天记录

Mon, 18 May 2026 21:02:21 +0800

wx-cli 是一个用 Rust 编写的本地微信数据命令行工具，目标是在命令行里查询自己的微信会话、聊天记录、联系人、群成员、收藏、朋友圈、公众号文章、附件和统计信息。

它不是一个云端微信同步服务，也不是聊天机器人。它更像一个本地只读数据检索层：微信仍然在本机运行，数据仍然留在本机，wx-cli 负责按需解密、缓存和查询本地数据库，然后把结果以 YAML 或 JSON 形式输出给人或 Agent 使用。

这个项目有两个值得关注的点：一是它把微信本地数据查询做成了跨平台 CLI；二是它专门考虑了 Claude Code、Cursor、Codex 这类 AI Agent 的使用场景，提供了 SKILL.md 和带 meta 的结构化输出。

wx-cli 能做什么

按项目 README 的描述，wx-cli 覆盖的功能很完整：

查看最近会话和未读会话。
查询某个联系人或群的聊天历史。
全库搜索关键词。
查看新增消息。
查询联系人、群成员和群昵称。
查询收藏。
查询朋友圈通知、朋友圈时间线和朋友圈正文。
查询公众号文章推送。
列出和提取聊天图片附件。
做聊天统计。
导出聊天记录为 Markdown 或 JSON。

这些能力让它不只是“查聊天记录”，而是把微信本地数据变成了可搜索、可统计、可导出的本地资料库。

为什么适合 AI Agent

很多命令行工具只是给人看的，输出是一段文本。wx-cli 则明显考虑了 Agent 读取。

README 提到，history、search、sessions、unread、new-messages、stats、attachments 等命令会附带 meta 信息。meta 里包含结果状态、未知分片、命中数据的最新时间、session 记录的最新时间等信息。

这对 Agent 很有用。因为 AI 不只需要“查到了什么”，还需要知道“结果新不新”“有没有可能漏消息”“是不是需要重新 init”。例如：

status 可以提示结果是否 ok 或 possibly_stale。
unknown_shards 可以提示是否存在 daemon 当前没有 key 的数据库分片。
chat_latest_timestamp 可以告诉 Agent 当前命中数据里的最新消息时间。
session_last_timestamp 可以帮助判断本地 session 记录是否明显领先于查询结果。

这类元信息可以减少 AI 误判，让 Claude Code、Cursor、Codex 这类工具在处理微信数据时更稳。

安装方式

项目推荐通过 npm 全平台安装：

`1`	`npm install -g @jackwener/wx-cli`

也支持 macOS / Linux 的 curl 安装：

`1`	`curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh \| bash`

Windows 可以在管理员 PowerShell 中运行：

`1`	`irm https://raw.githubusercontent.com/jackwener/wx-cli/main/install.ps1 \| iex`

如果要从源码构建，也可以直接用 Rust：

1
2

git clone git@github.com:jackwener/wx-cli.git && cd wx-cli
cargo build --release

构建产物是 target/release/wx，Windows 下是 wx.exe。

和 Agent Skill 的关系

wx-cli 还提供了面向 AI Agent 的 Skill。可以通过 skills CLI 一键安装到 Claude Code、Cursor、Codex 等支持 Skills 的环境：

`1`	`npx skills add jackwener/wx-cli`

全局安装：

`1`	`npx skills add jackwener/wx-cli -g`

安装后，Agent 会读取仓库里的 SKILL.md，知道如何安装、初始化和调用 wx-cli。

这意味着你可以让 Agent 帮你做一些本地信息整理任务，例如：

找某段时间某个群聊里讨论过的关键词。
汇总最近未读消息。
从某个会话里导出最近聊天记录。
搜索公众号文章推送链接。
分析某个群聊里的发言统计。

前提仍然是：这些数据必须是你本机、你自己的微信数据。

基本使用方式

初始化前需要保持微信正在运行。不同平台要求不同。

Linux 上可以执行：

`1`	`sudo wx init`

Windows 上需要用管理员 PowerShell：

wx init

macOS 上更复杂。README 说明，默认路径需要先对 WeChat 做 ad-hoc 签名，才能扫描进程内存；重签名后还要清理旧 TCC 授权记录，否则截图、视频通话、麦克风等权限可能出现“看起来已开启但实际拒绝”的问题。项目文档也提醒，重签名会带来 macOS 频繁弹出访问其他 App 数据提示的副作用。

初始化后，可以用下面的命令验证：

`1`	`wx sessions`

能看到最近会话，说明基本链路已经可用。daemon 会在首次调用时自动启动。

常用命令示例

查看最近会话：

`1`	`wx sessions`

查看未读会话：

`1`	`wx unread`

只看真人未读，过滤公众号和折叠入口：

`1`	`wx unread --filter private,group`

查看某个会话最近聊天记录：

`1`	`wx history "张三"`

拉取更多历史消息：

`1`	`wx history "张三" -n 2000`

按时间范围查询群聊：

`1`	`wx history "AI群" --since 2026-04-01 --until 2026-04-15`

全库搜索：

`1`	`wx search "关键词"`

搜索某个群中的关键词：

`1`	`wx search "会议" --in "工作群" --since 2026-01-01`

导出聊天记录：

1
2

wx export "张三" --format markdown -o chat.md
wx export "AI群" --since 2026-01-01 --format json

这些命令都比较适合被脚本或 Agent 调用，尤其是加上 --json 后。

朋友圈和公众号文章

wx-cli 不只查聊天。

朋友圈相关命令分成通知和帖子：

1
2
3

wx sns-notifications
wx sns-feed
wx sns-search "关键词"

需要注意，朋友圈数据只覆盖你本地刷到过的内容。微信客户端按需下载，没在本地出现过的数据，工具也不会凭空拿到。

公众号文章则通过独立命令查询：

wx biz-articles
wx biz-articles --account "返朴"
wx biz-articles --since 2026-05-01 --until 2026-05-10
wx biz-articles --json | jq '.[].url'

它会返回公众号名称、标题、URL、摘要、封面、时间等字段。对做资料整理、文章收集和本地知识库的人来说，这个功能很实用。

附件提取

微信聊天里的图片附件通常不是直接可读的普通图片文件，而是存在 xwechat_files/<wxid>/msg/attach/... 下的 .dat 文件。

wx-cli 提供了两步流程：

1
2

wx attachments "张三"
wx attachments "AI群" --kind image -n 100

先拿到 attachment_id 后，再提取：

`1`	`wx extract <attachment_id> -o ~/Desktop/photo.jpg`

输出报告里会带 md5、dat_path、dat_size、output、format、decoder 等信息。README 中说明它支持 legacy XOR、V1 fixed-AES、V2 AES + XOR 等解码档位，不同平台的 image key 提取方式也不同。

这部分能力很强，但也更需要谨慎使用：只处理自己的数据，不要把它用于未经授权的数据访问。

daemon 架构为什么重要

wx-cli 的性能点在 daemon。

README 中给出的结构大致是：

wx (CLI) ──Unix socket──▶ wx-daemon (后台进程)
                              │
                    ┌─────────┴──────────┐
               DBCache               联系人缓存
           (mtime 感知复用)

daemon 首次解密后，会把数据库和 mtime 信息持久化到 ~/.wx-cli/cache/。如果数据库文件 mtime 没变，后续调用就可以复用缓存，不需要每次重新解密。

这对命令行查询和 Agent 循环都很关键。Agent 可能会连续查询多个会话、搜索多个关键词、再做统计和导出。如果每次都重新扫描和解密，体验会很差；daemon 缓存让它更接近一个本地查询服务。

原理简述

项目 README 对原理有直接说明：微信 4.x 使用 SQLCipher 4 加密本地数据库，WCDB 会在进程内存中缓存派生后的 raw key。

wx-cli 会根据平台使用不同方式扫描微信进程内存，匹配 key 模式后提取密钥，再由 daemon 按需解密和缓存数据库。

不同平台的底层机制不同：

macOS 使用 Mach VM API。
Linux 使用 /proc/<pid>/mem。
Windows 使用 VirtualQueryEx 和 ReadProcessMemory。

这些能力解释了为什么初始化通常需要较高权限，也解释了为什么 macOS 上会涉及签名和隐私授权。

使用边界和风险

这类工具必须先讲边界。

wx-cli README 的免责声明写得很明确：工具仅用于学习和研究目的，用于解密自己的微信数据，并要求遵守相关法律法规，不得用于未经授权的数据访问。

实际使用时也建议注意：

只在自己的电脑、自己的微信账号上使用。
不要把导出的聊天记录随意上传到云端模型。
用 Agent 分析聊天记录时，先确认 API 供应商和数据出境风险。
导出 Markdown / JSON 后要注意文件权限和备份位置。
公司或多人设备上使用前，先确认合规和授权。

本地工具不等于没有隐私风险。它减少了数据离开本机的默认路径，但如果你把输出交给云端模型、网盘或第三方脚本，风险又会回来。

适合谁使用

wx-cli 适合这些场景：

想在本地快速搜索自己的微信历史消息。
需要把某个会话导出为 Markdown 或 JSON。
想统计某个群聊在一段时间内的发言情况。
想让 Claude Code、Cursor、Codex 等 Agent 帮忙整理本地微信资料。
想把公众号文章推送链接整理进本地知识库。
想研究微信本地数据库结构和解密流程。

不太适合这些场景：

想做云端微信同步。
想绕过他人设备或账号权限。
想无脑图形界面操作，不接触命令行。
不愿意处理 macOS 权限、Windows 管理员权限或 Linux sudo 的用户。

小结

wx-cli 的价值，不只是“命令行查微信聊天记录”。更准确地说，它把本地微信数据变成了一个可查询、可导出、可被 Agent 消费的本地数据源。

它的 daemon 架构解决了反复解密和查询性能问题；meta wrapper 让 AI Agent 更容易判断结果是否新鲜；SKILL.md 则把安装和使用方式交给 Claude Code、Cursor、Codex 这类工具理解。

如果你经常需要从微信里找信息、整理群聊、导出记录或构建个人资料库，wx-cli 很值得关注。但使用它时也要始终记住一条底线：只处理自己的数据，并且谨慎管理导出结果。

参考资料

jackwener/wx-cli GitHub 仓库

Wx-Cli on KnightLi的博客