wx-cli

wx-cli — WeChat 数据查询工具

Overview

wx-cli 解密并查询 WeChat macOS 加密数据库。零参数即可运行——自动检测账号、密钥和数据目录。

核心原则： 用 --format json 获取结构化数据供分析；用默认 text 格式展示给用户。

When to Use

• 用户问"最近跟谁聊了什么"、"某人发过什么消息"
• 用户要搜索聊天记录中的关键词
• 用户要查看联系人信息
• 用户要解密数据库或图片
• 用户提到 WeChat / 微信相关数据需求

Quick Reference

需求	命令
当前状态	wx-cli status
密钥提取（推荐）	wx-cli key extract
手动设置数据库密钥	wx-cli key set <account_id> <hex_key>
手动设置图片密钥	wx-cli key set-image <account_id> <image_key>
已存密钥列表	wx-cli key list
解密数据库	wx-cli decrypt
增量解密	wx-cli decrypt --incremental
解密图片（自动推导密钥）	wx-cli decode-image <路径> -d <data_dir>
解密图片（手动 V2 key）	wx-cli media decrypt-dat <路径> --v2-key <key>
解密图片（KeyStore）	wx-cli decode-image <路径> --account <account_id>
提取语音	wx-cli media extract-voice --media-dir <dir> <svr_id>
提取语音（原始 SILK）	wx-cli media extract-voice --media-dir <dir> <svr_id> --raw
解密视频号视频	wx-cli media decrypt-video <文件> --seed <seed>
查询 hardlink 路径	wx-cli media resolve-path --db <hardlink.db> <key>
检查 DB 文件	wx-cli info <db_file>
版本信息	wx-cli --version
最近会话列表	wx-cli sessions
查看系统路径	wx-cli paths
查看系统路径（JSON）	wx-cli paths --json
忽略隐藏配置查看完整会话列表	wx-cli sessions --show-hidden
搜索联系人	wx-cli contacts --search <关键词>
忽略隐藏配置搜索联系人	wx-cli contacts --search <关键词> --show-hidden
查某人的消息	wx-cli query <联系人名/账号ID>
忽略隐藏配置查看消息	wx-cli query <联系人> --show-hidden
定位某条消息上下文	wx-cli query <联系人> --around-sort-seq <seq> --context 10
按 server_id 定位上下文	wx-cli query <联系人> --around-server-id <id> --context 10
增量拉取新消息	wx-cli query <联系人> --after-sort-seq <seq> --limit 20
全局搜索关键词	wx-cli search <关键词>
导出会话（TXT，默认并行）	wx-cli export <联系人> -o <目录> --all
导出会话（JSON，默认并行）	wx-cli export <联系人> -o <目录> --all --format json
忽略隐藏配置导出会话	wx-cli export <联系人> -o <目录> --all --show-hidden
导出（无媒体）	wx-cli export <联系人> -o <目录> --all --no-media
启动 HTTP API	wx-cli server run
查看 HTTP 服务状态	wx-cli server status
停止 HTTP 服务	wx-cli server stop
重启 HTTP 服务	wx-cli server restart
HTTP API（远程）	wx-cli server run --host 0.0.0.0 --token <secret>
实时监听会话变化	wx-cli watch
实时监听（忽略隐藏配置）	wx-cli watch --show-hidden
实时监听（轮询）	wx-cli watch --poll --poll-ms 3000
实时监听（文件事件模式）	wx-cli watch --fsnotify
前置条件检查	wx-cli doctor
前置条件检查 + 修复建议	wx-cli doctor --fix

前置条件

密钥提取需要 SIP 禁用，通常不需要 sudo。SIP enabled 时 task_for_pid 被内核拒绝（kern_return=5），即使 root 也不行。检查 SIP 状态：csrutil status。禁用需在 Recovery Mode 执行 csrutil disable。

常用工作流

0. 首次使用：提取密钥并解密

WeChat 数据库是加密的，查询前必须先有密钥。需要 SIP 禁用（SIP enabled 时 task_for_pid 被内核拒绝）：

# LLDB hook 提取密钥 — 会重启 WeChat，需要 LLDB + python3，通常不需要 sudo
wx-cli key extract --timeout 120

key extract 拿到的是完整数据库密钥，覆盖所有数据库。后续多数查询可直接读取加密数据库，无需先执行 decrypt。

提取后验证：

# 查看已存密钥（`raw=yes` 表示已保存完整数据库密钥）
wx-cli key list

# 有完整数据库密钥时：query/sessions/search/contacts/server run/watch 可直接读取加密数据库，无需先 decrypt

# 如需明文导出
wx-cli decrypt
wx-cli decrypt --incremental

手动设置密钥：

wx-cli key set <account_id> 0123456789abcdef...       # 数据库密钥（32 字节 hex）
wx-cli key set-image <account_id> abcdefghijklmnop     # 图片 AES 密钥（V2 格式）

密钥类型说明：

密钥	用途	提取方式	覆盖范围
完整数据库密钥（raw_key）	解密 SQLite 数据库	key extract（LLDB hook）	所有 DB
Image key（16 bytes）	解密 V2 格式 .dat 图片	decode-image -d <data_dir> 自动推导	—

1. 查看最近聊天

wx-cli sessions --limit 10
# 返回按时间倒序的会话列表，含联系人显示名和最后一条消息摘要

2. 查找某人并读消息

# 先搜联系人（支持昵称、备注、wxid、微信号、手机号等模糊匹配）
wx-cli contacts --search 张三

# 用搜到的名字或 wxid 查消息
wx-cli query 张三 --limit 20

# 用 JSON 获取结构化数据
wx-cli query 张三 --format json --limit 50

2a. 联系人隐藏规则

配置文件：~/Library/Application Support/wx-cli/config/settings.toml

[accounts."<account_id>"]
ignore_contacts = ["wxid_hidden_contact"]
ignore_tags = ["同事"]

• query / sessions / contacts / export / watch 支持 --show-hidden 忽略隐藏配置
• search 当前不会自动应用隐藏配置
• 隐私优先： 当输出里出现 [消息已隐藏]，除非用户明确要求，agent 不应主动追加 --show-hidden

3. 全局搜索关键词

wx-cli search 周末 --limit 20
# 优先查询 WeChat 自带的全文索引库，搜索通常在亚秒级完成

搜索语义：

• 中文按字拆分；英文支持 Porter stemming
• 多词搜索为 AND 逻辑
• stats.scanned=0 表示走微信内置全文索引；stats.scanned>0 表示退回到全量扫描

4. 按条件过滤消息

wx-cli query 张三 --type text           # 按类型：text/image/voice/video/emoji/app/system/revoke
wx-cli query 张三 --since 1772600000 --until 1772700000   # 时间范围（Unix 秒）

4b. 锚点上下文查询

wx-cli query 张三 --around-sort-seq 1773421188000 --context 10    # 按 sort_seq 定位前后 10 条
wx-cli query 张三 --around-server-id 5455993825313690274 --context 10  # 按 server_id 定位
wx-cli query 张三 --after-sort-seq 1773421188000 --limit 20       # 增量拉取新消息

行为规则：

• 锚点查询始终按升序返回，--order desc 会被忽略
• --context 默认 50，仅对 around-* 有效
• around-* 参数与 --since/--until/--all 互斥
• --around-sort-seq、--around-server-id、--after-sort-seq 三者互斥

5. 群聊查询

wx-cli query 18819405230@chatroom --limit 10   # 群聊 ID
wx-cli query 周末爬山群                          # 或群名模糊匹配

6. 导出会话

wx-cli export 张三 -o /tmp/export/ --all                        # TXT 格式，全部消息
wx-cli export 张三 -o /tmp/export/ --all --format json           # JSON 格式
wx-cli export 张三 -o /tmp/export/ --all --no-media              # 跳过媒体文件
wx-cli export 张三 -o /tmp/export/ --all --show-emoji            # 显示表情细节

排序默认 asc（时间正序），与 query 默认 desc 相反。

7. 图片解密与转码

# 推荐：-d 自动推导 V2 密钥
wx-cli decode-image input.dat -d <account_data_dir> -o output.png

# 批量目录
wx-cli decode-image /path/to/dat_dir/ -d <account_data_dir> -o /tmp/output/

# 直接传入 V2 AES key
wx-cli media decrypt-dat input.dat --v2-key abcdefghijklmnop -o output.png

8. 音声の抽出

wx-cli media extract-voice --media-dir <dir> <svr_id> -o voice.mp3    # 默认 MP3（需 ffmpeg）
wx-cli media extract-voice --media-dir <dir> <svr_id> --raw -o voice.silk  # 原始 SILK

8b. ハードリンクのパス検索

wx-cli media resolve-path --db /path/to/hardlink.db <md5_key>                    # 图片
wx-cli media resolve-path --db /path/to/hardlink.db --media-type video <key>     # 视频
wx-cli media resolve-path --db /path/to/hardlink.db --media-type file <key>      # 文件

9. ビデオチャンネル動画の復号

wx-cli media decrypt-video encrypted.bin --seed 2105122989 -o video.mp4      # 十进制 seed
wx-cli media decrypt-video encrypted.bin --seed 0x7d844e8d -o video.mp4      # 十六进制 seed

10. HTTP API サービス

wx-cli server run                                          # 本地启动（默认 127.0.0.1:9100）
wx-cli server run --host 0.0.0.0 --token mysecret          # 远程访问（必须设 token）
wx-cli server status / stop / restart                      # 管理服务

10a. CLI から実行中の server を自動的に再利用

sessions、contacts、query、search は、デフォルトでまずローカルの http://127.0.0.1:9100 への接続を試みます。server が利用可能な場合は HTTP 経由で実行し、利用できない場合はローカルで直接検索します。

パラメーター	説明
--server-url <url>	デフォルトのアドレスを上書きします
--server-token <token>	Bearer token
--server-only	リモートのみを使用し、フォールバックしません
--no-server	ローカル検索を強制します

10b. REST エンドポイント（読み取り専用）

エンドポイント	説明	主なパラメーター
GET /api/v1/health	ヘルスチェック	なし
GET /api/v1/sessions	会話の一覧	limit, offset, order, show_hidden
GET /api/v1/contacts	連絡先の一覧	limit, offset, search, show_hidden
GET /api/v1/messages	メッセージの検索	contact（必須）, limit, offset, since, until, type, order, around_sort_seq, around_server_id, after_sort_seq, context, show_hidden
GET /api/v1/timeline	すべての会話を横断してメッセージを時系列順に一括取得	since（必須）, until（必須）, limit, offset, type, order, show_hidden
GET /api/v1/media	メディアコンテンツを直接返します	server_id（必須）, talker（必須）, format=ogg|mp3（音声のみ）
GET /api/v1/search	全文検索	q（必須）, limit, offset
GET /api/v1/events	SSE イベントストリーム	なし

画像レスポンスには X-Wechat-Media-Quality: full|thumbnail が含まれます。サービスはローカルにある高画質画像／オリジナル画像ファイルを優先して返します。WeChat がサムネイルしかダウンロードしていない場合は thumbnail を返します。この場合、呼び出し元は長期キャッシュを避け、WeChat でオリジナル画像をダウンロードした後に再試行してください。

認証： --token を指定して起動した場合は、Authorization: Bearer <token> を指定する必要があります。--host がローカルアドレスでない場合、--token は必須です。

現在の HTTP API は読み取り専用であり、send/reply/webhook などの書き込み用インターフェースはありません。

11. リアルタイム監視

wx-cli watch                          # 默认启动
wx-cli watch --poll --poll-ms 5000    # 自定义轮询间隔
wx-cli watch --format json            # JSON 格式（每行一个 JSON 对象）
wx-cli watch --show-hidden            # 忽略隐藏配置

12. 前提条件の確認

wx-cli doctor           # 列出各项检查结果（SIP、DevToolsSecurity、_developer、lldb、python3）
wx-cli doctor --fix      # 对 FAIL 项输出修复命令

エラーの自動復旧

error: no key for account <account_id>

wx-cli status                           # 1. 确认 WeChat 状态
wx-cli key extract --timeout 120        # 2. 提取密钥
wx-cli key list                         # 3. 验证密钥
wx-cli sessions                         # 4. 重试查询

task_for_pid failed (kern_return=5) — SIP が有効です。Recovery Mode で csrutil disable を実行してください。

warning: ffmpeg not found — ffmpeg をインストールしてください：brew install ffmpeg。または FFMPEG_PATH=/path/to/ffmpeg wx-cli ...

JSON 出力形式

すべての検索コマンドに --format json を指定すると、統一されたエンベロープが返されます。

{
  "items": [...],
  "paging": { "offset": 0, "limit": 20, "returned": 20, "total": 103, "has_more": true },
  "stats": { "scanned": 103, "skipped": 0, "elapsed_ms": 3 }
}

コマンド	item の主なフィールド
sessions	username, display_name, avatar_url?, summary, sort_timestamp, direction?
query	sort_seq, server_id, msg_type, sender, content, direction
timeline API	sort_seq, server_id, msg_type, sender, talker, talker_display_name, create_time, direction, snippet。すべての会話を横断して時系列順に統一されます
contacts	user_name, alias, remark, nick_name, avatar_url?, phone, labels
search	server_id, talker, sender, snippet, hit_type

混同しやすいフィールド：

• contacts では user_name（アンダースコアあり）、sessions では username（アンダースコアなし）を使用します
• avatar_url は WeChat の小さいアバター画像の URL を優先し、ない場合は大きいアバター画像の URL を使用します。ローカルに記録がない場合は出力されません
• メッセージの sender が、メッセージ単位で self/other を判断する基準です
• /api/v1/health の current_account.wxid が、「自分が送信した」ことを判断するための主要な情報源です

プログラムからの JSON 利用： JSON は stdout に、診断情報は stderr に出力されます。正しく解析するには、出力を分けて取得してください：

OUTPUT=$(wx-cli query 张三 --format json --limit 5)
echo "$OUTPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['items']))"

ページネーションと並べ替え

wx-cli query 张三 --format json --limit 10 --offset 0    # 第一页
wx-cli query 张三 --format json --limit 10 --offset 10   # 第二页
wx-cli query 张三 --order asc                             # 时间正序
wx-cli query 张三 --all                                   # 获取全部消息（上限 20,000）

メッセージタイプのラベル（type=49 の構造化解析）

バリエーション	sub_type	出力
Link	4, 5, 7, 92	[リンク] <タイトル>
File	6	[ファイル] <ファイル名>
MiniProgram	33, 36	[ミニプログラム] <名前>
MergedMessages	19	[チャット履歴] <タイトル>
Quote	57	[引用 @送信者: 元のテキスト] 返信テキスト
Transfer	2000	[送金] ¥金額
RedEnvelope	2001, 2003	[お年玉] <タイトル>
ChannelVideo	51, 63	[ビデオチャンネル] <タイトル>
Pat	62	[タップ]

JSON の content フィールドは tagged union です。外側の key はバリエーション名で、値は構造化フィールドです。

ファイルパス

カテゴリ	パス（macOS）	用途
Config	~/Library/Application Support/wx-cli/config/	キー、設定
Cache	~/Library/Caches/wx-cli/	復号済みデータベース
State	~/Library/Application Support/wx-cli/state/	サービスの実行時データ
Logs	~/Library/Logs/wx-cli/	サービスログ
Temp	$TMPDIR/wx-cli/	キー抽出用の一時ファイル

すべてのパスを確認するには wx-cli paths を使用してください。

注意事項

• すべてのコマンドでアカウントとキーが自動検出されるため、通常は --account や --key は不要です
• query は wxid、chatroom ID、filehelper に対応し、中国語名のあいまい検索にも対応しています
• search は WeChat に付属する message_fts.db を直接検索するため、個別にインデックスを作成する必要はありません
• search は現在、非表示設定を自動適用せず、--show-hidden もありません
• --all は --limit を上書きします（現在の上限は 20,000）。export --all はすべての結果をバッチ単位で取得します
• --limit 0 を指定すると、そのコマンドのデフォルト値に戻ります
• server run の起動後、復号キャッシュは自動的に差分更新されます

診断方針

検索結果が空の場合、パラメーターを何度も変えて再試行しないでください：

# 1. 检查 stats.skipped
wx-cli query <contact> --all --format json 2>/dev/null | \
  python3 -c "import json,sys; d=json.load(sys.stdin); print(f'items={len(d[\"items\"])}, skipped={d[\"stats\"][\"skipped\"]}')"

# 2. skipped > 0 → 重新解密
wx-cli decrypt

# 3. items=0 且 skipped=0 → 检查联系人
wx-cli contacts --search <name> --format json