wx-cli

wx-cli

トリガー

• WeChat のチャット履歴を調べる
• WeChat のメッセージ履歴
• WeChat の連絡先
• WeChat グループのメンバー
• WeChat グループのニックネーム／グループカード
• WeChat のお気に入り
• wechat history / messages / contacts
• wx-cli
• WeChat の内容を確認して
• WeChat のメッセージを検索

前提条件

• macOS（Apple Silicon／Intel）または Linux
• WeChat デスクトップ版 4.x がインストールされ、ログイン済みであること
• Node.js >= 14（npm インストール方式）または curl（shell インストール方式）
• 初回の wx init には sudo が必要です（メモリスキャンによるキー抽出）

---

インストール

方式一：npm（推奨）

npm install -g @jackwener/wx-cli

方式二：curl

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

インストール後に確認します：

wx --version

---

初期化（初回使用時のみ、一度だけ実行）

macOS（必ず順番に実行してください）

手順 1：WeChat に再署名する（一度だけ実行します。WeChat の更新後は再実行が必要です）

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

signature in use エラーが発生する場合や、dylib の署名が破損している場合は、先に修復してから再署名してください：

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

手順 2：macOS の TCC プライバシーデータベースにある WeChat の古い許可記録を削除する（再署名後に必ず実行してください）

macOS TCC は bundle id + csreq の組み合わせで権限を検証します。csreq はコード署名からエンコードされます。再署名すると古い csreq と新しい署名が一致しなくなり、古い許可記録はサイレントに無効になります（System Settings ではスイッチが「許可済み」と表示されたままですが、実行時には実際に拒否されます）。TCC にある WeChat の古い記録を消去すると、次回 WeChat が権限を要求した際に、macOS が新しい署名に基づいて csreq を再生成します：

tccutil reset ScreenCapture com.tencent.xinWeChat   # 截图 / 屏幕共享
tccutil reset Camera com.tencent.xinWeChat          # 视频通话 / 扫码
tccutil reset Microphone com.tencent.xinWeChat      # 语音消息 / 通话
tccutil reset AppleEvents com.tencent.xinWeChat     # 自动化 / 输入法
tccutil reset AddressBook com.tencent.xinWeChat     # 通讯录
tccutil reset SystemPolicyDocumentsFolder com.tencent.xinWeChat
tccutil reset SystemPolicyDownloadsFolder com.tencent.xinWeChat
tccutil reset SystemPolicyDesktopFolder com.tencent.xinWeChat

tccutil は、許可したことのない service に対して "No such bundle identifier" と表示します。これは no-op であり、ほかの service の reset には影響しません。

手順 3：WeChat を再起動する

killall WeChat && open /Applications/WeChat.app
# 等待微信完全登录后再继续

その後、WeChat が権限を要求したら、GUI の指示に従って再度許可してください。macOS 26 では、WeChat を プライバシーとセキュリティ → 画面収録とシステムオーディオ録音 の上半分に追加してください。下半分の「システムオーディオのみ」にチェックを入れるだけではいけません。後者ではスクリーンショットの権限を許可できません。

手順 4：初期化する

sudo wx init

Linux

sudo wx init

wx init は次の処理を自動で行います：

1. WeChat のデータディレクトリを検出します
2. プロセスメモリをスキャンし、すべてのデータベースキーを抽出します
3. ~/.wx-cli/config.json に書き込みます

初期化が完了すると、以降のすべてのコマンドで sudo は不要です。daemon は初回呼び出し時に自動起動します。

---

コマンド一覧

すべてのコマンドはデフォルトで YAML を出力します。トークンの節約になり、読みやすくなります。--json を指定すると JSON に切り替えられます（jq での処理などに便利です）。

セッションとメッセージ

# 最近 20 个会话
wx sessions

# 有未读消息的会话
wx unread

# 只看真人（私聊 + 群聊）的未读，过滤公众号与折叠入口
wx unread --filter private,group

# 上次检查后的新消息（增量）
wx new-messages
wx new-messages --json          # JSON 输出，适合 agent 解析

# 聊天记录（支持昵称/备注名）
wx history "张三"
wx history "张三" -n 2000
wx history "AI群" --since 2026-04-01 --until 2026-04-15 -n 100

# 全库搜索
wx search "关键词"
wx search "关键词" -n 500
wx search "会议" --in "工作群" --since 2026-01-01

history／search／export はすべて、返す件数を指定する -n／--limit に対応しています。デフォルト値は一度に出力される量を抑えるためのもので、厳密な上限ではありません。

sessions／unread／history／new-messages／stats の出力には、エージェントが振り分けに使える chat_type フィールドが含まれます：

値	意味	username の特徴
private	個人とのチャット	wxid_* またはカスタムの短い ID
group	グループチャット	*@chatroom
official_account	公式アカウント／購読アカウント／サービスアカウント／システム通知	gh_*、biz_*、mphelper、qqsafe、@opencustomerservicemsg
folded	折りたたみエントリー（購読アカウントの折りたたみ、折りたたまれたグループチャットの集約項目）	brandsessionholder、@placeholder_foldgroup

wx unread --filter は private／group／official／folded／all に対応しており、カンマ区切りで複数選択できます。デフォルトは all です。

グループチャットのメッセージに含まれる last_sender、sender、stats.top_senders には、優先してグループのニックネーム（グループカード）が表示されます。ローカルデータベースにグループのニックネームがない場合は、連絡先のメモ、WeChat のニックネーム、username の順に使用します。

グループのコンテキストでは、history／search／new-messages／attachments と stats.top_senders に、安定した識別情報の 3 フィールドが同時に出力されます：sender_username（同じ名前のメンバーを区別するための安定した wxid）／sender_contact_display（メモ > ニックネーム > wxid の順で使用）／sender_group_nickname（グループカード。sender の表示元と同じで、文字列の再解析が不要です）。wxid を解決できない場合、下流のフィルターに空文字列が混入するのを避けるため、これらのフィールドは出力されません。

sessions／unread／history／search／new-messages／stats／attachments の標準出力は、現在すべて次のラッパー形式です：

{
  "messages": [...],
  "meta": {
    "status": "ok",
    "unknown_shards": [],
    "chat_latest_timestamp": 1715750400,
    "chat_latest_db": "message/message_2.db",
    "session_last_timestamp": 1715760000
  }
}

内容：

• status = possibly_stale_unknown_shards：ディスク上に daemon が認識していない新しい message_N.db が見つかった場合は、まず wx init --force を実行してください
• status = possibly_stale：session.db に記録された最新時刻が、今回取得した最新メッセージより明らかに新しいため、メッセージが漏れている可能性があります
• status = windowed：今回のクエリはもともとウィンドウ化／フィルター適用後の部分的なビューです。「最新の全状態」として扱わないでください
• --with-meta：per_shard_latest／cache_mode_per_shard を追加で返します
• --debug-source：--with-meta に加えて、実際の shard_paths も表示します

引用メッセージ（appmsg type=57）は、history／search／new-messages の出力で 2 行に展開されます。1 行目は現在の返信、2 行目は ↳ で始まり、引用元の本文が表示されます。例：

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

--type link／--type file は、WeChat appmsg のリンク、ファイル、統合チャット履歴、引用メッセージなどのバリエーションを対象にします。search --type link は、展開および整形された引用元の本文にも一致します。

連絡先とグループ

# 联系人列表 / 搜索
wx contacts
wx contacts --query "李"

# 群成员列表
wx members "AI交流群"

wx members --json の各メンバーには、次の内容が含まれます：

• username：WeChat 内部の username
• display：推奨される表示名。グループのニックネームを優先します
• contact_display：連絡先のメモまたは WeChat のニックネーム
• group_nickname：グループのニックネーム。記録がない場合は空文字列です
• is_owner：グループオーナーかどうか

エージェントがグループメンバーを表示する場合は、display を優先してください。グループのニックネームと連絡先名を区別する必要がある場合は、group_nickname と contact_display を読み取ってください。

モーメンツ（SNS）

3 つのコマンドがあり、それぞれ役割が異なります：

# 1) 互动通知（点赞 / 评论，默认仅未读）
wx sns-notifications
wx sns-notifications --include-read --since 2026-04-01 -n 100

# 2) 时间线：浏览本地缓存的朋友圈帖子
wx sns-feed                                    # 近 20 条
wx sns-feed --user "张三"                      # 只看某人
wx sns-feed --since 2026-04-01 --until 2026-04-18 -n 100

# 3) 全文搜索：在正文里找关键词
wx sns-search "关键词"
wx sns-search "婚礼" --user "李四" --since 2023-01-01 -n 50

フィールドの違い：

• 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> 子ノードを数えます（XML が不正な場合は 0）

ローカルで閲覧したモーメンツのみ保存されています（WeChat アプリは必要に応じてダウンロードします）。閲覧したことのない投稿はローカルにないため、どのコマンドでも取得できません。

公式アカウントの記事

公式アカウントの記事配信は、通常の message_0.db とは別の biz_message_*.db シャードに保存されます：

# 最近 50 篇（默认）
wx biz-articles

# 更多
wx biz-articles -n 200

# 限定公众号（名称模糊匹配 display name / username）
wx biz-articles --account "返朴"

# 时间范围（YYYY-MM-DD，发布时间，非接收时间）
wx biz-articles --since 2026-05-01 --until 2026-05-10

# 仅有未读消息的公众号，每号取最新 1 篇（适合"今天有什么新推送"扫描）
wx biz-articles --unread
wx biz-articles --unread --account "Datawhale"   # 与 --account 取交集

# 下游消费：拿 URL 做内容抓取
wx biz-articles --since 2026-05-10 --json | jq '.[].url'

各項目に返されるフィールド：account／account_username（gh_*）／title／url（mp.weixin.qq.com のリンク）／digest／cover_url／time + timestamp（記事の公開時刻）／recv_time_str + recv_time（WeChat が配信を受信した時刻）。複数記事を含む配信は複数行に展開されます。

附件提取（图片）

聊天里的图片本体在 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 把单个资源解密写到指定路径
wx extract <attachment_id> -o ~/Desktop/photo.jpg
wx extract <attachment_id> -o /tmp/x.jpg --overwrite

attachments 输出每条带：attachment_id / kind（当前固定 image）/ type / local_id / timestamp / time，群聊里另带 sender 和稳定身份三件套（同上文）。命令名保留成 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 / Windows 自动；Linux 暂不支持）：

• macOS：kvcomm cache（key_<uin>_*.statistic 文件名取 uin → md5(str(uin) + wxid)[:16]）+ brute-force fallback；xor_key = uin & 0xff
• Windows：扫 Weixin.exe 内存匹配 [A-Za-z0-9]{32|16} 候选，按 V2 template ciphertext-block 反验

收藏与统计

# 全部收藏
wx favorites

# 按类型筛选：text / image / article / card / video
wx favorites --type image

# 搜索收藏内容
wx favorites --query "关键词"

# 聊天统计（发言人、消息类型、活跃时段）
wx stats "AI群"
wx stats "AI群" --since 2026-01-01

导出

# 导出为 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 -o chat.json

Daemon 管理

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

---

Agent 使用建议

查询结果需要程序处理时，统一加 --json：

wx sessions --json
wx new-messages --json
wx search "关键词" --json | jq '.results[0]'
wx history "张三" --json -n 50 | jq '.messages[0]'
wx history "张三" --json | jq '.meta'
wx history "张三" --json --with-meta | jq '.meta.cache_mode_per_shard'

CHAT 参数支持昵称、备注名、微信 ID，模糊匹配。不确定准确名称时，先用 wx contacts --query 搜索。

---

数据文件位置

~/.wx-cli/
├── config.json       # 配置
├── all_keys.json     # 数据库密钥（敏感，勿分享）
├── daemon.sock       # Unix socket
├── daemon.pid / .log
└── cache/            # 解密后的数据库缓存

---

常见问题

微信重启后密钥失效：重新运行 sudo wx init --force（微信必须正在运行）。

daemon 无响应：wx daemon stop 后重新调用任意命令自动重启。

找不到聊天：用 wx contacts --query 确认昵称/备注名，或用微信 ID 直接查询。

为什么只能获取 500 条消息？：这是默认输出条数，不是硬限制。显式传 -n 即可，例如 wx history "张三" -n 2000 或 wx export "张三" -n 2000 -o chat.md。