wx-cli

wx-cli

从命令行查询本地微信数据

会话 · 聊天记录 · 搜索 · 联系人 · 群成员 · 群昵称 · 收藏 · 统计 · 导出

---

AI Agent Skill

通过 skills CLI 一键安装到 Claude Code、Cursor、Codex 等 agent：

npx skills add botiverse/wx-cli

或全局安装：

npx skills add botiverse/wx-cli -g

安装后 agent 会自动读取 SKILL.md，了解如何安装和调用 wx-cli。

源码与发布仓库：botiverse/wx-cli。

---

特性

• 零依赖安装 — 单一 Rust 二进制，一行命令装完
• 毫秒级响应 — 后台 daemon 持久缓存解密数据库，mtime 不变则复用
• AI 友好 — history / search / sessions / new-messages / stats / attachments 默认返回 {..., meta} wrapper，agent 能直接消费 freshness / source 信息
• 完全本地 — 数据不出本机，实时解密，无需全量预解密

---

安装

当前仓库 botiverse/wx-cli 为 private。
匿名 curl / 公开 npm 旧包（@jackwener/[email protected]）拿不到本仓库最新二进制。
有仓库读权限时，请用下面的 源码构建（推荐）。

从源码构建（推荐）

git clone [email protected]:botiverse/wx-cli.git && cd wx-cli
cargo build --release
# 安装到用户 PATH（覆盖旧版）
mkdir -p ~/.local/bin
cp target/release/wx ~/.local/bin/wx
wx --version   # 应显示当前 Cargo.toml 版本，如 0.6.3

Windows：

git clone [email protected]:botiverse/wx-cli.git
cd wx-cli
cargo build --release
# 将 target\release\wx.exe 放到 PATH 目录

已有 clone 时升级

git pull
cargo build --release
cp target/release/wx ~/.local/bin/wx

GitHub Release 预编译包（仓库 private 时仅协作者可见）

从 Releases 下载：

chmod +x wx-macos-arm64 && mv wx-macos-arm64 ~/.local/bin/wx

一键脚本（raw 链接在 private 仓库下对匿名用户 404；有权限时可用 gh 下载 release asset）

# 需已登录 gh 且对 botiverse/wx-cli 有读权限
gh release download -R botiverse/wx-cli -p 'wx-macos-arm64' -O ~/.local/bin/wx
chmod +x ~/.local/bin/wx

install.sh / install.ps1 仍维护在仓库内，仓库公开或 raw 可访问后可再启用：

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

npm

历史包名 @jackwener/wx-cli 仍存在于 npm，但公开 registry 上的版本可能严重滞后，不要当作当前主安装路径。

---

快速开始

新用户要做什么 / 不要做什么

初始化（只需一次）

保持微信运行并已登录，然后：

macOS

# 必须：本机 GUI Terminal + sudo（系统可能提示授予「开发者工具」权限，请允许）
sudo wx init

# 若提示缺分片密钥 / meta.unknown_shards 非空：加长 hook，等待期间在微信里点开相关聊天
sudo wx key extract --hook-seconds 90

wx init 两阶段取密钥（都不依赖关 SIP）：

1. 进程内存扫描（x'key+salt' + salt 邻接）
2. LLDB hook CCCryptorCreate，补齐尚未加载进内存的 per-DB AES key

说明：

• 官方 Hardened Runtime 包：本机 Terminal + sudo 即可；若失败，到「系统设置 → 隐私与安全性 → 开发者工具」里勾选你的终端。
• 部分官网 4.x 本身已是 ad-hoc：用户态 LLDB 往往也能工作。
• 不要默认对 WeChat 做 ad-hoc 重签：会打乱 TCC 权限、公众号/截图可能异常。仅当 SSH 等无 GUI 场景下 task_for_pid 仍失败时，才考虑有副作用的重签；详见 macOS 权限指南。

Linux

sudo wx init

Windows（以管理员身份运行 PowerShell）

wx init

验证

wx --version
wx doctor          # 密钥 / 分片 / SQLCipher 健康检查
wx sessions

能看到最近会话且 wx doctor 关键项通过即表示正常。daemon 在首次查询时自动启动。

若 doctor 提示关键分片缺密钥，或 meta.unknown_shards 非空：

sudo wx key extract --hook-seconds 90
# 等待期间在微信里打开相关聊天（冷分片可能需触发加载）
wx doctor

---

命令

诊断与密钥

wx doctor                                 # 环境 / 密钥 / 分片检查
wx doctor --fix --json                   # JSON + 修复建议
wx key list                               # 已有密钥与缺失覆盖
wx key extract --hook-seconds 90          # 建议：sudo wx key extract --hook-seconds 90
wx key set message/message_1.db <64hex>   # 手动写入并校验

补密钥统一用 sudo wx key extract --hook-seconds 90（不要用裸的 wx init --force 当主路径）。
取钥不需要关闭 SIP；需本机 GUI Terminal +（Hardened Runtime 包）sudo。

消息

wx sessions                                      # 最近 20 个会话
wx unread                                        # 有未读消息的会话
wx unread --filter private,group                 # 只看真人未读（过滤公众号/折叠入口）
wx new-messages                                  # 上次检查后的新消息（增量）
wx history "张三"                                # 最近 50 条记录
wx history "张三" -n 2000                        # 拉更多历史消息
wx history "AI群" --since 2026-04-01 --until 2026-04-15
wx search "关键词"                               # 全库搜索
wx search "关键词" -n 500                        # 放宽搜索结果条数
wx search "会议" --in "工作群" --since 2026-01-01

history / search / export 都支持 -n / --limit 指定条数。默认值只是为了避免一次性输出过多消息，不是硬上限。

会话/消息输出里都带 chat_type 字段，取值为 private / group / official_account / folded。official_account 涵盖公众号、订阅号、服务号及 mphelper / qqsafe 等系统通知；folded 对应微信里的"订阅号折叠"和"折叠群聊"两个聚合入口。

群聊里的 last_sender、sender 和 stats 的 top_senders 会优先使用群昵称（群名片）。如果本地数据库里没有对应群昵称，则回退到联系人备注、微信昵称或 username。

history / search / new-messages / attachments 以及 stats.top_senders，在群聊上下文里还会附带稳定身份三件套：

• sender_username：稳定 wxid，用来区分两个昵称同名的成员
• sender_contact_display：通讯录里的显示名（备注 > 昵称 > wxid 兜底）
• sender_group_nickname：群名片本身（同 sender 的来源，方便机器读取时不必再解析）

解析不到 wxid 时（id2u 没命中且老格式 wxid_xxx:\n... 前缀也不存在）这三字段不会输出，避免伪造空字段污染下游过滤。

history / search / sessions / unread / new-messages / stats / attachments 现在都会附带 meta：

• status: ok / possibly_stale / possibly_stale_unknown_shards / windowed
• unknown_shards: 磁盘上存在、但 daemon 当前没有 key 的 message_N.db 分片；非空时应先跑 sudo wx key extract --hook-seconds 90
• chat_latest_timestamp / chat_latest_db: 当前命中数据里最新一条消息的时间和分片来源
• session_last_timestamp: session.db 里 WeChat 自己记录的最新时间；如果明显领先于 chat_latest_timestamp，说明结果可能漏了消息

默认情况下，人类用户会在 stderr 看到可执行的 warning；agent / 脚本可直接读 stdout 里的 meta。传 --with-meta 会额外返回 per_shard_latest / cache_mode_per_shard，传隐藏 flag --debug-source 还会带真实 shard_paths。

引用消息会在 history / search / new-messages 输出中显示当前回复和被引用原文：

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

--type link / --type file 会包含微信 appmsg 里的链接、文件、合并聊天记录和引用消息等变体；搜索时也会匹配解压后可见的引用原文。

朋友圈（SNS）

三个独立命令，区分"通知"和"帖子"：

wx sns-notifications                             # 点赞/评论通知（默认仅未读）
wx sns-notifications --include-read -n 100       # 含已读

wx sns-feed                                      # 近 20 条朋友圈（时间线）
wx sns-feed --user "张三"                        # 限定作者
wx sns-feed --since 2026-04-01 -n 100            # 按时间

wx sns-search "关键词"                           # 全文搜索朋友圈正文
wx sns-search "婚礼" --user "李四" --since 2023-01-01

• sns-notifications 返回互动通知：type（like/comment）、from_nickname、content（评论正文）、feed_preview + feed_author（对应原帖）
• sns-feed / sns-search 返回朋友圈帖子：author、content（正文）、media、media_count、location、timestamp；media 字段含每张图的 url/thumb/key/token/md5/enc_idx/size，供下游做图片代理或离线渲染。media_count = media.len()，按 DOM 解析的合法 <media> 子节点计数（malformed XML 返回 0）

朋友圈数据只覆盖你本地刷到过的帖子（微信 app 按需下载）。

公众号文章

公众号文章推送存在独立的 biz_message_*.db 分片，用 biz-articles 单独查：

wx biz-articles                                   # 最近 50 篇
wx biz-articles -n 200                            # 更多
wx biz-articles --account "返朴"                  # 限定公众号（名称模糊匹配）
wx biz-articles --since 2026-05-01 --until 2026-05-10
wx biz-articles --unread                          # 仅有未读的公众号，每号取最新 1 篇
wx biz-articles --json | jq '.[].url'             # 下游消费 URL

每条返回：account / account_username / title / url / digest / cover_url / time / `times