从命令行掌控你的微信数据：wx-cli 完全指南

本文核心问题：作为一名开发者或技术爱好者，你能否像操作数据库一样，用一行命令查询、搜索、导出自己微信里的聊天记录、朋友圈和联系人？答案是肯定的，而 wx-cli 正是为此而生。

一、为什么我们需要命令行工具管理微信数据？

微信承载了我们大量的工作沟通、生活记录和重要信息。但在实际使用中，我们常常遇到这样的场景：需要快速查找三个月前某个群聊里关于”项目排期”的讨论，想批量导出与某位客户的历史记录做备份，或者统计一个活跃群里谁发言最多。微信客户端的搜索功能虽然可用，却难以满足批量处理、自动化脚本和深度分析的需求。

wx-cli 是一个用 Rust 编写的开源命令行工具，它让你无需离开终端就能查询本地微信数据。它的设计理念很直接：数据留在本地，查询交给命令行。工具通过扫描微信进程内存获取数据库密钥，实时解密 SQLCipher 加密的数据库文件，并通过后台守护进程（daemon）缓存解密结果，实现毫秒级响应。

我最初接触这个工具时，最大的顾虑是安全性和复杂度——毕竟涉及到内存扫描和数据库解密。但实际使用后发现，它的设计非常克制：所有操作都在本地完成，不需要上传任何数据到云端；安装过程也是一行命令的事，远比我想象的简洁。

二、wx-cli 的核心优势：快、轻、本地、AI 友好

在深入安装和使用之前，让我们先理解为什么这个工具值得尝试。

核心问题：相比手动导出或第三方 GUI 工具，wx-cli 的独特价值在哪里？

1. 零依赖的单一二进制文件

很多开发者工具最让人头疼的就是依赖地狱。wx-cli 采用 Rust 编译成单一二进制文件，无论你用 macOS、Linux 还是 Windows，安装后只有一个可执行文件，没有运行时依赖。这对于需要在多台机器上快速部署，或者想把它集成到自动化脚本中的用户来说，是极大的便利。

2. 毫秒级查询响应

第一次初始化时，wx-cli 会启动后台 daemon 进程解密数据库。但关键在于：它不会每次查询都重新解密。daemon 会将解密后的数据库和文件的修改时间（mtime）持久化到本地缓存目录。只要微信数据库文件没有被修改，下次启动时直接复用缓存，查询速度达到毫秒级。这种设计兼顾了安全性和性能——实时解密保证数据新鲜度，缓存机制保证查询速度。

3. 默认 YAML 输出，兼顾可读性与机器处理

wx-cli 默认输出 YAML 格式，这在命令行环境中非常易读，同时也比 JSON 更节省 token。如果你需要下游处理，随时可以用 --json 切换，配合 jq 等工具做过滤和转换。这种”人类可读优先，机器处理其次”的设计哲学，在 AI 助手和自动化脚本日益普及的今天，显得尤为贴心。

4. 完全本地运行，隐私零风险

所有数据解密和查询都在你的机器上完成。wx-cli 不需要网络权限（除了安装时从 npm 或 GitHub 下载），不会上传任何聊天记录到服务器。对于处理敏感工作沟通的用户来说，这是不可妥协的底线。

三、安装指南：根据你的平台选择最适合的方式

核心问题：如何在 macOS、Linux 和 Windows 上快速完成 wx-cli 的安装和初始化？

wx-cli 提供了多种安装方式，从最简单的 npm 全局安装到手动下载二进制文件，覆盖了不同用户的需求。

方式一：npm 安装（推荐，全平台通用）

如果你已经安装了 Node.js，这是最省心的方式：

npm install -g @jackwener/wx-cli

这会自动下载适合你平台的预编译二进制文件，并将其加入系统 PATH。安装完成后，直接在终端输入 wx 即可使用。

方式二：macOS / Linux 一键脚本

对于不喜欢用 npm 的用户，可以用 curl 直接执行安装脚本：

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

脚本会自动检测你的平台和架构，下载对应的二进制文件并安装到合适的位置。

方式三：Windows PowerShell 安装

在 Windows 上，以管理员身份打开 PowerShell，执行：

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

方式四：手动下载二进制文件

如果你需要特定版本，或者想完全控制安装位置，可以从项目的 Releases 页面手动下载：

平台	文件
macOS Apple Silicon	`wx-macos-arm64`
macOS Intel	`wx-macos-x86_64`
Linux x86_64	`wx-linux-x86_64`
Linux arm64	`wx-linux-arm64`
Windows x86_64	`wx-windows-x86_64.exe`

下载后，macOS 和 Linux 用户需要赋予执行权限并移动到 PATH 目录：

chmod +x wx-macos-arm64
sudo mv wx-macos-arm64 /usr/local/bin/wx

方式五：从源码构建

如果你希望审查代码或做二次开发，可以用 Rust 从源码编译：

git clone git@github.com:jackwener/wx-cli.git && cd wx-cli
cargo build --release
# 编译产物位于 target/release/wx（Windows 为 wx.exe）

我的建议：普通用户直接用 npm 安装即可，简单且易于更新。只有当你需要离线环境安装或修改源码时，才考虑手动下载或源码构建。

四、初始化配置：macOS 需要额外一步

核心问题：为什么 macOS 用户需要先对微信进行代码签名，而 Linux 和 Windows 用户可以直接初始化？

wx-cli 的工作原理需要读取微信进程的内存，这在 macOS 上受到系统安全机制的严格限制。因此，macOS 用户在首次使用前必须完成一个额外的准备步骤。

macOS 初始化流程

第一步：对微信进行 Ad-hoc 签名

macOS 的系统完整性保护（SIP）和代码签名机制会阻止未授权进程读取其他应用的内存。你需要先给微信应用重新签名：

codesign --force --deep --sign - /Applications/WeChat.app

如果执行时遇到 signature in use 错误，说明微信的某些内部组件已有签名，需要先移除再重新签名：

codesign --remove-signature "/Applications/WeChat.app/Contents/Frameworks/vlc_plugins/librtp_mpeg4_plugin.dylib"
codesign --force --deep --sign - /Applications/WeChat.app

第二步：重置 TCC 隐私授权记录

这一步极其重要，却很容易被忽略。当你重新签名微信后，macOS 会将其视为一个”新应用”，之前授予的屏幕录制、摄像头、麦克风、通讯录等权限虽然在设置界面看起来仍然开启，但实际上可能已经静默失效。如果不重置 TCC 记录，你可能会遇到微信截图黑屏、视频通话无画面等问题。

执行以下命令重置微信的所有隐私授权：

for s in ScreenCapture Camera Microphone AppleEvents AddressBook \
         SystemPolicyDocumentsFolder SystemPolicyDownloadsFolder SystemPolicyDesktopFolder; do
  tccutil reset "$s" com.tencent.xinWeChat
done

第三步：重启微信并完全登录

killall WeChat && open /Applications/WeChat.app

等待微信完全登录，确保所有数据已加载。

第四步：执行 wx-cli 初始化

sudo wx init

需要使用 sudo 是因为读取其他进程内存需要管理员权限。

Linux 初始化

Linux 用户的过程简单很多，只需确保微信正在运行，然后执行：

sudo wx init

Windows 初始化

以管理员身份打开 PowerShell，确保微信在后台运行，然后执行：

wx init

验证安装

无论哪个平台，初始化完成后，执行以下命令验证是否正常工作：

wx sessions

如果看到最近 20 个会话的列表，说明一切就绪。此时后台 daemon 已经自动启动并缓存了数据库。

反思：macOS 的额外步骤确实增加了使用门槛，但这恰恰体现了现代操作系统在安全性和功能性之间的权衡。wx-cli 的设计者在这里做了很好的文档补充，把 TCC 重置这个”坑”明确指了出来。作为用户，我们既要享受技术带来的便利，也要理解这些安全机制背后的逻辑，而不是盲目地关闭 SIP 或赋予过多权限。

五、核心命令详解：查询聊天记录与联系人

核心问题：安装完成后，如何用 wx-cli 高效地查询会话、搜索历史消息、导出聊天记录？

wx-cli 的命令设计遵循”简单查询用默认参数，复杂需求用选项扩展”的原则。下面按实际使用场景介绍核心命令。

5.1 会话管理：快速浏览和筛选

查看最近活跃的会话：

wx sessions

这会返回最近 20 个会话，包含会话名称、最后一条消息预览、时间戳和 chat_type 字段。chat_type 的取值包括：

private：私聊
group：群聊
official_account：公众号、订阅号、服务号及系统通知
folded：订阅号折叠和折叠群聊

查看有未读消息的会话：

wx unread

如果只想看真人的未读消息，过滤掉公众号和折叠入口：

wx unread --filter private,group

查看上次检查后的新消息（增量查询）：

wx new-messages

场景示例：每天早上到工位后，我先执行 wx unread --filter private,group，快速浏览哪些客户或同事发了新消息，而不被公众号推送干扰。这比打开微信客户端逐个查看红点高效得多。

5.2 历史记录查询：精准定位对话内容

查看某个联系人的最近聊天记录：

wx history "张三"

默认返回最近 50 条。如果需要更多历史，用 -n 指定：

wx history "张三" -n 2000

按时间范围筛选：

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

场景示例：上个月客户在微信上确认了需求变更，但我记不清具体细节。执行 wx history "客户A" --since 2026-04-01 --until 2026-04-30，配合 grep 或直接用肉眼扫描，几分钟内就能定位到那条关键消息，而不用在微信客户端里无限上滑加载。

5.3 全局搜索：在海量记录中找关键词

全库搜索包含特定关键词的消息：

wx search "关键词"

放宽结果数量限制：

wx search "关键词" -n 500

在特定群聊中搜索，并限定时间范围：

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

场景示例：团队里经常讨论”接口文档”的更新，但分散在多个群聊和私聊中。我用 wx search "接口文档" -n 200 一次性找出所有相关讨论，然后按时间排序，就能还原出文档的完整迭代过程。

5.4 消息类型过滤

搜索链接、文件、合并聊天记录和引用消息：

wx search "项目计划" --type link
wx search "合同" --type file

--type link 会匹配微信 appmsg 里的链接、文件、合并聊天记录和引用消息等变体。搜索时也会匹配解压后可见的引用原文，这意味着即使消息本身没有你要的关键词，只要它引用的内容包含，也会被命中。

5.5 引用消息的展示

在 history、search 和 new-messages 的输出中，引用消息会以下面这种格式清晰展示：

[引用] 当前回复内容
  ↳ 发送者: 被引用的原文内容

这种层级缩进让对话上下文一目了然，比微信客户端里的引用气泡更利于文本处理。

六、朋友圈数据：查询互动通知与时间线

核心问题：能否用命令行查看朋友圈的点赞评论通知，以及按作者或时间筛选朋友圈内容？

wx-cli 将朋友圈功能拆分为三个独立命令，区分”通知”和”帖子”两种数据类型。

6.1 互动通知：谁赞了我、评论了我

查看未读的点赞和评论通知：

wx sns-notifications

包含已读通知，并限制数量：

wx sns-notifications --include-read -n 100

返回的字段包括：

type：like（点赞）或 comment（评论）
from_nickname：互动者昵称
content：评论正文（如果是评论）
feed_preview 和 feed_author：对应的原帖预览和作者

场景示例：朋友圈发了一张项目上线截图，收到几十条点赞和评论。用 wx sns-notifications --include-read -n 50 可以快速生成一个互动清单，用于后续感谢或统计，而不用在微信里逐个查看。

6.2 朋友圈时间线：按作者和时间筛选

查看最近 20 条朋友圈：

wx sns-feed

限定特定作者：

wx sns-feed --user "张三"

按时间范围查看，并增加数量：

wx sns-feed --since 2026-04-01 -n 100

返回的字段包括：author（作者）、content（正文）、media（媒体文件信息）、media_count（媒体数量）、location（位置）、timestamp（时间戳）。

其中 media 字段包含每张图片的 url、thumb、key、token、md5、enc_idx 和 size，这些信息供下游做图片代理或离线渲染使用。media_count 按 DOM 解析的合法 <media> 子节点计数，如果 XML 格式异常则返回 0。

场景示例：想整理某位摄影爱好者朋友过去一年发的朋友圈图片。执行 wx sns-feed --user "李四" --since 2025-05-01 -n 500，从返回的 JSON 中提取 media 里的 URL，就能批量下载图片集。

6.3 朋友圈全文搜索

搜索朋友圈正文内容：

wx sns-search "关键词"

结合作者和时间筛选：

wx sns-search "婚礼" --user "李四" --since 2023-01-01

重要限制：朋友圈数据只覆盖你本地刷到过的帖子。微信客户端是按需下载朋友圈内容的，如果你没有刷到某条朋友圈，本地数据库中就不会存在，wx-cli 自然也无法查询到。这不是工具的缺陷，而是微信本身的数据同步机制决定的。

反思：这个限制让我意识到，很多我们以为”已经获取”的数据，实际上只是客户端的缓存视图。wx-cli 在这里做了诚实的说明，没有夸大能力。作为用户，理解这种边界很重要——命令行工具再强大，也无法获取服务器上没有同步到本地的数据。

七、公众号文章与联系人管理

核心问题：如何单独查询公众号文章推送，以及快速获取群成员列表和联系人信息？

7.1 公众号文章查询

公众号文章推送存储在独立的 biz_message_0.db 数据库中，wx-cli 提供了专门的 biz-articles 命令：

查看最近 50 篇：

wx biz-articles

获取更多历史：

wx biz-articles -n 200

限定特定公众号（名称模糊匹配）：

wx biz-articles --account "返朴"

按时间范围筛选：

wx biz-articles --since 2026-05-01 --until 2026-05-10

只看有未读文章的公众号，每个号取最新 1 篇：

wx biz-articles --unread

提取所有文章 URL 供下游处理：

wx biz-articles --json | jq '.[].url'

返回的字段包括：account（公众号名称）、account_username（公众号 ID）、title（标题）、url（链接）、digest（摘要）、cover_url（封面图）、time（可读时间）、timestamp（时间戳）、recv_time_str（接收时间）。多图文推送会展开成多行，每行一篇文章。

场景示例：我关注了几个技术公众号，想每周自动整理未读文章列表。用 wx biz-articles --unread --json | jq '.[] | {title, url, account}' 就能生成一个简洁的待读清单，配合脚本可以自动发送到邮件或备忘录。

7.2 联系人列表

查看所有联系人：

wx contacts

按名字搜索：

wx contacts --query "李"

7.3 群成员列表

查看特定群的成员：

wx members "AI交流群"

用 --json 输出可以获取更详细的字段：

username：微信内部 username
display：用于展示的名称，优先使用群昵称
contact_display：联系人备注或微信昵称
group_nickname：群昵称；本地没有记录时为空字符串
is_owner：是否群主

场景示例：作为群管理员，我需要定期导出群成员列表做备份。wx members "工作群" --json | jq '.[] | {display, is_owner}' 能快速生成一个包含身份标识的成员表，比手动截图或复制粘贴高效得多。

八、收藏、统计与导出：深度数据利用

核心问题：如何查询微信收藏内容，统计群聊活跃度，以及将聊天记录导出为 Markdown 或 JSON？

8.1 收藏查询

查看全部收藏：

wx favorites

按类型筛选（支持 text、image、article、card、video）：

wx favorites --type image

搜索收藏内容：

wx favorites --query "关键词"

场景示例：我习惯把重要的工作资料、灵感截图收藏到微信。用 wx favorites --type image --query "原型" 可以快速找到之前收藏的所有设计原型图，而不用在微信收藏夹里翻页。

8.2 聊天统计：谁是最活跃的发言者？

统计特定群的聊天数据：

wx stats "AI群"

限定时间范围：

wx stats "AI群" --since 2026-01-01

返回的统计信息包括消息总数、每人发言数量、活跃时间段分布等。群聊中的 last_sender、sender 和 stats 的 top_senders 会优先使用群昵称（群名片），如果没有记录则回退到联系人备注、微信昵称或 username。

场景示例：运营一个 200 人的技术交流群，想分析过去一个月的活跃度和核心贡献者。wx stats "技术交流群" --since 2026-04-01 能直接给出数据支撑，用于感谢活跃成员或调整运营策略。

8.3 数据导出：备份与迁移

将聊天记录导出为 Markdown：

wx export "张三" --format markdown -o chat.md

导出更多历史：

wx export "张三" -n 2000 --format markdown -o chat.md

导出为 JSON 格式，方便程序处理：

wx export "AI群" --since 2026-01-01 --format json

场景示例：项目结束后，需要将与客户的全部沟通记录归档。wx export "客户A" -n 5000 --format markdown -o project_a_chat.md 生成一个完整的 Markdown 文件，包含时间戳和发言者，可以直接放入项目文档库。

九、输出格式与后台管理

核心问题：如何根据使用场景切换输出格式，以及如何管理后台 daemon 进程？

9.1 YAML 与 JSON 输出切换

wx-cli 默认输出 YAML，在终端阅读时更节省空间，也更省 token。需要程序化处理时，随时切换为 JSON：

wx sessions --json
wx search "关键词" --json | jq '.[0].content'
wx new-messages --json

9.2 Daemon 管理

查看 daemon 状态：

wx daemon status

停止 daemon：

wx daemon stop

查看实时日志：

wx daemon logs --follow

场景示例：发现查询速度突然变慢，可能是 daemon 出了问题。执行 wx daemon logs --follow 查看实时日志，或用 wx daemon stop 强制重启，通常能解决问题。

十、技术原理：wx-cli 如何安全地读取微信数据？

核心问题：wx-cli 是如何在不预解密整个数据库的情况下，实时读取加密数据的？

理解原理有助于我们信任这个工具，并排查可能出现的问题。

微信 4.x 使用 SQLCipher 4 加密本地数据库，加密方案包括：

算法：AES-256-CBC + HMAC-SHA512
密钥派生：PBKDF2，256,000 次迭代

WCDB（微信的数据库框架）在进程内存中缓存了派生后的 raw key，格式为 x'<64hex_key><32hex_salt>'。

wx-cli 的核心任务就是找到这个 raw key。它通过以下平台特定 API 扫描微信进程内存：

macOS：使用 Mach VM API（mach_vm_region + mach_vm_read）
Linux：读取 /proc/<pid>/mem
Windows：使用 VirtualQueryEx + ReadProcessMemory，需要 PROCESS_VM_READ | PROCESS_QUERY_INFORMATION 权限

扫描过程中，wx-cli 会匹配上述 raw key 的模式，提取密钥后由 daemon 按需解密数据库并缓存。

架构流程：

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

daemon 首次解密后将数据库和 mtime 持久化到 ~/.wx-cli/cache/。目录结构如下：

~/.wx-cli/
├── config.json       # 配置
├── all_keys.json     # 数据库密钥
├── daemon.sock       # Unix socket
├── daemon.pid / .log
└── cache/
    ├── _mtimes.json  # mtime 索引
    └── *.db          # 解密后的数据库

重启后如果 mtime 未变，直接复用缓存，无需重解密。这种设计既保证了数据实时性（微信数据库更新后会重新解密），又避免了每次查询的重复开销。

反思：这个技术方案非常精巧——它利用了”微信已经在内存中解密了数据库”这一事实，而不是尝试暴力破解或绕过加密。这既合法（你正在运行自己的微信进程），又高效（不需要处理 PBKDF2 的 25.6 万次迭代）。作为开发者，我很欣赏这种”站在巨人肩膀上”的设计思路：不重复造轮子，而是利用现有系统的状态。

十一、实用摘要与一页速览

操作清单：从安装到日常使用

安装：npm install -g @jackwener/wx-cli
macOS 额外步骤：codesign 签名微信 → 重置 TCC 授权 → 重启微信
初始化：sudo wx init（macOS/Linux）或管理员身份 wx init（Windows）
验证：wx sessions 查看最近会话
日常查询：
- 未读消息：wx unread --filter private,group
- 搜索历史：wx search "关键词" --in "群名"
- 导出记录：wx export "联系人" --format markdown -o backup.md
故障排查：wx daemon logs --follow 查看日志

一页速览：常用命令表

需求	命令
最近会话	`wx sessions`
未读消息	`wx unread`
新消息（增量）	`wx new-messages`
查看历史	`wx history "名称"`
全局搜索	`wx search "关键词"`
朋友圈通知	`wx sns-notifications`
朋友圈时间线	`wx sns-feed`
朋友圈搜索	`wx sns-search "关键词"`
公众号文章	`wx biz-articles`
联系人列表	`wx contacts`
群成员	`wx members "群名"`
收藏	`wx favorites`
聊天统计	`wx stats "群名"`
导出记录	`wx export "名称" --format markdown`
JSON 输出	任意命令加 `--json`
Daemon 状态	`wx daemon status`

十二、常见问题（FAQ）

Q1: wx-cli 会泄露我的聊天记录吗？
不会。所有数据解密和查询都在本地完成，wx-cli 不会上传任何数据到远程服务器。它只需要本地网络（Unix socket）用于 CLI 与 daemon 通信。

Q2: 为什么 macOS 需要重新签名微信？
macOS 的系统安全机制会阻止未授权进程读取其他应用内存。重新签名后，wx-cli 才能合法地扫描微信进程获取数据库密钥。这是系统层面的安全要求，不是 wx-cli 的过度设计。

Q3: 重签名微信后，截图和视频通话功能失效了怎么办？
这是 TCC 授权缓存导致的。执行文档中提供的 tccutil reset 命令重置微信的隐私授权，然后重新在系统设置中开启权限即可。

Q4: 查询结果能覆盖多久的历史？
聊天记录理论上覆盖本地数据库中的所有历史（通常从首次登录该设备开始）。朋友圈和公众号文章只覆盖你本地刷到过的内容，微信不会自动同步全部历史。

Q5: 微信更新后需要重新初始化吗？
微信更新后可能需要重新执行 macOS 的签名步骤（如果微信二进制文件有变化），然后重新运行 wx init。daemon 会自动检测数据库变化并更新缓存。

Q6: 可以查询已经被删除的聊天记录吗？
不可以。wx-cli 只读取微信本地数据库中现存的数据，无法恢复已删除的记录。

Q7: 输出中的 official_account 和 folded 有什么区别？
official_account 包括公众号、订阅号、服务号以及 mphelper、qqsafe 等系统通知账号。folded 对应微信的”订阅号折叠”和”折叠群聊”两个聚合入口。

Q8: 群聊中为什么有些成员显示的是 username 而不是昵称？
wx-cli 会优先显示群昵称，其次是联系人备注或微信昵称。如果以上都没有本地记录，则回退到微信内部 username。这取决于你在微信中是否查看过该成员的资料。

结语：wx-cli 把微信这个”黑盒”应用变成了一个可以用标准 Unix 哲学操作的数据源。它不会替代微信客户端进行日常聊天，但在数据查询、备份、分析和自动化方面，它填补了官方客户端的空白。对于习惯命令行工作流的开发者和技术从业者来说，这是一个值得加入工具箱的实用程序。数据所有权应当属于用户自己，而 wx-cli 给了我们一个行使这种所有权的趁手工具。

开发者必看：用wx-cli在命令行里一键查询你的微信聊天记录、朋友圈和联系人