wx-cli

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

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

---

AI Agent Skill

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

npx skills add jackwener/wx-cli

或全局安装：

npx skills add jackwener/wx-cli -g

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

---

特性

• 零依赖安装 — 单一 Rust 二进制，一行命令装完
• 毫秒级响应 — 后台 daemon 持久缓存解密数据库，mtime 不变则复用
• AI 友好 — 默认 YAML 输出，更省 token & 易读；--json 可切换为 JSON（方便 jq 处理等）
• 完全本地 — 数据不出本机，实时解密，无需全量预解密

---

安装

npm（推荐，全平台）

npm install -g @jackwener/wx-cli

macOS / Linux（curl）

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

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：chmod +x wx && sudo mv wx /usr/local/bin/

从源码构建

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

---

快速开始

保持微信运行，然后初始化（只需一次）：

macOS（需要先对微信做 ad-hoc 签名，才能扫描其内存）

# 1. 签名（只需做一次，WeChat 更新后重做）
codesign --force --deep --sign - /Applications/WeChat.app

# 2. 清理旧 TCC 授权记录（重签名后必做，否则微信截图/通话权限可能 silent 失效）
for s in ScreenCapture Camera Microphone AppleEvents AddressBook \
         SystemPolicyDocumentsFolder SystemPolicyDownloadsFolder SystemPolicyDesktopFolder; do
  tccutil reset "$s" com.tencent.xinWeChat
done

# 3. 重启微信，等待完全登录
killall WeChat && open /Applications/WeChat.app

# 4. 初始化
sudo wx init

如果 codesign 报 signature in use，先执行：

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

重签名后 macOS 的 TCC 隐私授权按新 code signature 重新校验，旧记录会失效。如果跳过 tccutil reset，微信截图/视频通话/麦克风等权限可能"看起来已开启但实际拒绝"。详见 macOS 权限与签名指南。

Linux

sudo wx init

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

wx init

验证安装：

wx sessions

能看到最近会话即表示一切正常。daemon 在首次调用时自动启动。

---

命令

消息

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 输出中显示当前回复和被引用原文：

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

--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_0.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 / timestamp / recv_time_str。多图文推送会展开成多行。

附件提取（图片）

聊天里的附件本体存在 xwechat_files/<wxid>/msg/attach/... 下的 .dat 文件，需要按消息所在 message_resource.db 的 md5 + 平台相关 image key 解码才能拿到原图。

# 1) 列出会话里的图片附件，先拿到不透明的 attachment_id
wx attachments "张三"
wx attachments "AI群" --kind image -n 100
wx attachments "AI群" --since 2026-04-01 --until 2026-04-15

# 2) 把单个 attachment_id 解密写出去（扩展名建议保留 .jpg / .mp4 等）
wx extract <attachment_id> -o ~/Desktop/photo.jpg
wx extract <attachment_id> -o /tmp/x.jpg --overwrite

attachments 输出每条带：attachment_id / kind / type / local_id / timestamp / time，群聊里还有 sender。当前 kind 固定为 image；命令名保留成 attachments 是为了后续扩到其他附件类型时不 break CLI。

extract 输出报告里带：md5 / dat_path / dat_size / output / output_size / format（实际识别出的图片格式：jpg / png / gif / webp / hevc 等）/ decoder（实际选用的解码器：legacy_xor / v1_aes / v2）。

支持的解码档位：

• legacy XOR：早期单字节 XOR，无 magic（按文件首字节探测格式自动反推）
• V1 fixed-AES（07 08 V1 08 07）：AES-128-ECB + 固定 key cfcd208495d565ef
• V2 AES + XOR（07 08 V2 08 07）：AES-128-ECB + raw + XOR；AES key 平台派生

V2 image key 提取：

• macOS：kvcomm cache（key_<uin>_*.statistic 文件名取 uin → md5(str(uin) + wxid)[:16]）+ brute-force fallback（md5(str(uin))[:4] == wxid_suffix 枚举 2^24）；xor_key = uin & 0xff，不是硬编码 0x88
• Windows：扫 Weixin.exe 内存匹配 [A-Za-z0-9]{32|16} 候选，按 V2 template ciphertext-block 反验
• Linux：上游空白，遇到 V2 .dat 会报 unsupported

联系人 & 群组

wx contacts                  # 联系人列表
wx contacts --query "李"     # 按名字搜索
wx members "AI交流群"        # 群成员列表

wx members --json 返回的成员字段包括：

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

收藏 & 统计

wx favorites                          # 全部收藏
wx favorites --type image             # 按类型筛选（text/image/article/card/video）
wx favorites --query "关键词"         # 搜索收藏内容
wx stats "AI群"                       # 聊天统计
wx stats "AI群" --since 2026-01-01   # 指定时间范围

导出

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

输出格式

默认输出 YAML，更省 token & 易读；--json 可切换为 JSON（方便 jq 处理等）：

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

Daemon 管理

wx daemon status
wx daemon stop
wx daemon logs --follow

---

架构

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

daemon 首次解密后将数据库和 mtime 持久化到 ~/.wx-cli/cache/。重启后 mtime 未变则直接复用，无需重解密。

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

---

原理

微信 4.x 使用 SQLCipher 4 加密本地数据库（AES-256-CBC + HMAC-SHA512，PBKDF2 256,000 次迭代）。WCDB 在进程内存中缓存派生后的 raw key，格式为 x'<64hex_key><32hex_salt>'。

wx-cli 通过 macOS Mach VM API（mach_vm_region + mach_vm_read）、Linux /proc/<pid>/mem 或 Windows VirtualQueryEx + ReadProcessMemory（需要 PROCESS_VM_READ | PROCESS_QUERY_INFORMATION 权限）扫描微信进程内存，匹配该模式提取密钥，daemon 按需解密并缓存。

---

致谢

本项目受 ylytdeng/wechat-decrypt 启发，在其基础上进行了重新设计与实现。感谢原作者的研究与探索。

---

免责声明

本工具仅用于学习和研究目的，用于解密自己的微信数据。请遵守相关法律法规，不得用于未经授权的数据访问。