AI工具

wx-cli 專案解讀：用命令列查詢本機微信聊天記錄

介紹 jackwener/wx-cli 這個本機微信資料命令列工具：它如何透過 daemon 架構查詢會話、聊天記錄、聯絡人、群成員、朋友圈、公眾號文章、附件和統計，並為 Claude Code、Cursor、Codex 等 Agent 提供可消費的結構化輸出。

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：

1

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 "關鍵詞"

需要注意，朋友圈資料只覆蓋你本機刷到過的內容。微信客戶端按需下載，沒在本機出現過的資料，工具也不會憑空拿到。

公眾號文章則透過獨立命令查詢：

1
2
3
4

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 中給出的結構大致是：

1
2
3
4
5

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 很值得關注。但使用它時也要始終記住一條底線：只處理自己的資料，並且謹慎管理匯出結果。

參考資料

© 2022 - 2026 KnightLi的博客
记录并分享
使用 Hugo 建立
主題 Stack 由 Jimmy 設計