wx-cli 解説：コマンドラインでローカルの WeChat チャット履歴を検索する

Mon, 18 May 2026 21:02:21 +0800

wx-cli は Rust で書かれたローカル WeChat データ向けのコマンドラインツールです。自分の WeChat セッション、チャット履歴、連絡先、グループメンバー、お気に入り、Moments、公式アカウント記事、添付ファイル、統計情報をターミナルから検索できるようにすることを目的としています。

これはクラウド型の WeChat 同期サービスでも、チャットボットでもありません。むしろローカルの読み取り専用データ検索レイヤーに近いものです。WeChat は引き続き手元のマシンで動作し、データも手元に残ります。wx-cli は必要に応じてローカルデータベースを復号、キャッシュ、検索し、その結果を YAML または JSON として人間や Agent に返します。

このプロジェクトで注目したい点は二つあります。一つは、WeChat のローカルデータ検索をクロスプラットフォーム CLI としてまとめていること。もう一つは、Claude Code、Cursor、Codex のような AI Agent の利用シーンを明確に意識し、SKILL.md と meta 付きの構造化出力を提供していることです。

wx-cli でできること

プロジェクト README によると、wx-cli はかなり広い機能をカバーしています。

最近のセッションと未読セッションを表示する。
特定の連絡先またはグループのチャット履歴を検索する。
ローカルデータベース全体からキーワード検索する。
新着メッセージを表示する。
連絡先、グループメンバー、グループ内ニックネームを検索する。
お気に入りを検索する。
Moments の通知、タイムライン、本文を検索する。
公式アカウントの記事配信を検索する。
チャット内の画像添付を一覧表示し、抽出する。
チャット統計を作成する。
チャット履歴を Markdown または JSON としてエクスポートする。

これらの機能により、単なる「チャット履歴検索」ではなく、WeChat のローカルデータを検索、集計、エクスポートできるローカル資料庫として扱えるようになります。

AI Agent に向いている理由

多くの CLI ツールは人間向けで、出力も単なるテキストになりがちです。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 のようなツールが WeChat データを扱うときの安定性を高めます。

インストール方法

プロジェクトは 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 に次のようなローカル情報整理を依頼できます。

特定期間に特定のグループチャットで話題になったキーワードを探す。
最近の未読メッセージを要約する。
特定セッションから最近のチャット履歴をエクスポートする。
公式アカウント記事のリンクを検索する。
グループチャット内の発言統計を分析する。

前提は変わりません。対象データは、あなた自身のマシン上にある、あなた自身の WeChat データである必要があります。

基本的な使い方

初期化前には WeChat を起動しておく必要があります。要件はプラットフォームごとに異なります。

Linux では次を実行できます。

`1`	`sudo wx init`

Windows では管理者 PowerShell を使います。

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 と組み合わせると扱いやすくなります。

Moments と公式アカウント記事

wx-cli はチャットだけを検索するわけではありません。

Moments 関連のコマンドは通知と投稿に分かれています。

1
2
3

wx sns-notifications
wx sns-feed
wx sns-search "关键词"

注意点として、Moments データはローカルで表示されたことのある内容に限られます。WeChat クライアントは必要に応じてデータをダウンロードするため、ローカルに存在したことのないデータをツールが突然取得することはできません。

公式アカウント記事は独立したコマンドで検索します。

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、概要、カバー画像、時刻などのフィールドが返ります。資料整理、記事収集、ローカル知識ベースづくりをしている人には実用的な機能です。

添付ファイルの抽出

WeChat チャット内の画像添付は、通常そのまま読める一般的な画像ファイルではなく、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 が示す構成はおおむね次のようなものです。

wx (CLI) ──Unix socket──▶ wx-daemon (バックグラウンドプロセス)
                              │
                    ┌─────────┴──────────┐
               DBCache               連絡先キャッシュ
           (mtime を見て再利用)

daemon は初回復号後、データベースと mtime 情報を ~/.wx-cli/cache/ に永続化します。データベースファイルの mtime が変わっていなければ、以後の呼び出しではキャッシュを再利用でき、毎回復号する必要がありません。

これはコマンドライン検索と Agent のループ処理の両方で重要です。Agent は複数のセッションを連続で検索し、複数のキーワードを調べ、その後に統計やエクスポートを行うことがあります。毎回スキャンと復号をやり直すと体験は悪くなります。daemon キャッシュにより、ローカル検索サービスに近い感覚で使えます。

原理の簡単な説明

プロジェクト README は原理を直接説明しています。WeChat 4.x は SQLCipher 4 でローカルデータベースを暗号化し、WCDB は派生後の raw key をプロセスメモリ内にキャッシュします。

wx-cli はプラットフォームに応じた方法で WeChat プロセスメモリをスキャンし、key パターンに一致するものを見つけて鍵を抽出します。その後 daemon が必要に応じてデータベースを復号し、キャッシュします。

低レベルの仕組みはプラットフォームごとに異なります。

macOS は Mach VM API を使います。
Linux は /proc/<pid>/mem を使います。
Windows は VirtualQueryEx と ReadProcessMemory を使います。

これらの仕組みは、初期化に高い権限が必要になりがちな理由、そして macOS で署名やプライバシー権限が関係する理由を説明しています。

利用上の境界とリスク

この種のツールでは、まず境界を明確にする必要があります。

wx-cli README の免責事項は明確です。このツールは学習と研究目的に限られ、自分の WeChat データを復号するためのものであり、関連する法令を遵守する必要があります。無許可のデータアクセスに使ってはいけません。

実際に使うときは、次の点にも注意するのがよいでしょう。

自分のコンピューター、自分の WeChat アカウントでのみ使う。
エクスポートしたチャット履歴を安易にクラウドモデルへアップロードしない。
Agent でチャット履歴を分析する場合、API 事業者とデータ越境リスクを先に確認する。
Markdown / JSON としてエクスポートした後は、ファイル権限とバックアップ先に注意する。
会社端末や共有端末で使う前に、コンプライアンスと権限を確認する。

ローカルツールだからといってプライバシーリスクがないわけではありません。データが最初から外へ出る経路は減りますが、出力をクラウドモデル、クラウドストレージ、第三者スクリプトに渡せば、リスクは戻ってきます。

向いているユーザー

wx-cli は次のような場面に向いています。

自分の WeChat 過去メッセージをローカルで素早く検索したい。
特定セッションを Markdown または JSON としてエクスポートしたい。
一定期間のグループチャット発言状況を集計したい。
Claude Code、Cursor、Codex などの Agent にローカル WeChat 資料を整理させたい。
公式アカウント記事の配信リンクをローカル知識ベースに整理したい。
WeChat のローカルデータベース構造や復号フローを研究したい。

一方で、次のような用途にはあまり向いていません。

クラウド型の WeChat 同期をしたい。
他人の端末やアカウント権限を回避したい。
GUI だけで操作したく、コマンドラインに触れたくない。
macOS の権限、Windows の管理者権限、Linux の sudo を扱いたくない。

まとめ

wx-cli の価値は、単に「コマンドラインで WeChat チャット履歴を検索できる」ことだけではありません。より正確には、WeChat のローカルデータを、検索でき、エクスポートでき、Agent が消費できるローカルデータソースへ変える点にあります。

daemon アーキテクチャは繰り返し復号と検索性能の問題を解決します。meta wrapper は AI Agent が結果の鮮度を判断しやすくします。SKILL.md は Claude Code、Cursor、Codex のようなツールにインストールと利用方法を理解させます。

WeChat から情報を探す、グループチャットを整理する、記録をエクスポートする、個人資料庫を構築するといった作業が多いなら、wx-cli は注目に値します。ただし使うときは、常に一つの前提を忘れないことが重要です。処理するのは自分のデータだけにし、エクスポートした結果は慎重に管理してください。

参考資料

jackwener/wx-cli GitHub リポジトリ

CLIツール on KnightLiブログ