Community研究&データ分析github.com

tzwkb/wechat-decrypt

エージェントスキル — WeChat 4.x チャット履歴の復号・検索(macOS + Windows):MCP 読み取り/検索、エクスポート、音声文字起こし。

wechat-decrypt とは?

このスキルは、WeChat 4.x の暗号化されたチャットデータベースを復号し、エージェント(Claude Code など)から直接読み取り、検索、エクスポートできるようにするツールです。macOS と Windows の両方をサポートし、MCP プロトコルを通じて統合されたツールインターフェース `wechat_list_chats`、`wechat_read_chat`、`wechat_search_messages`、`wechat_recent_messages`、`wechat_chat_summary` を提供します。また、音声メッセージの自動文字起こし(macOS では mlx-whisper、Windows では faster-whisper を使用)や、`export_chat.py` による構造化エクスポート機能も備えています。セットアップ時には、各プラットフォーム固有の手法(macOS では Frida による PBKDF2 フック、Windows では HMAC-SHA512 の race-attach による raw key 抽出)を用いて暗号化キーを抽出し、データベースを復号した後、MCP サーバーが直接平文データベースにアクセスします。ユーザーはエージェントに自然言語で「最近のチャットを見せて」「XXとの会話を検索して」などと指示するだけで、手間のかかる DB 操作を意識せずに結果を得られます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add tzwkb/wechat-decrypt

Installed? Explore more 研究&データ分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

WeChat 4.x チャット履歴の復号と検索(macOS + Windows)

初回ロード時セルフチェック(Agent 必須)

python3 -c "import platform; print(platform.system())"
claude mcp list 2>&1 | grep -q "wechat.*Connected" && echo "MCP_OK" || echo "MCP_MISSING"
test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "KEY_OK" || echo "KEY_MISSING"
状態アクション
MCP_MISSINGmacOS bash setup.sh / Windows powershell -File setup.ps1、その後「Claude Code を再起動」するようユーザーに伝える
KEY_MISSING該当プラットフォームの「鍵抽出」手順を実行(Windows で鍵抽出後、python scripts\windows\decrypt_all.py を実行して全データベースを平文に復号)
すべて OKそのまま MCP ツールを使用

Windows セルフチェック(PowerShell、上記 macOS 3項目に対応):

python -c "import frida, Crypto; print('DEPS_OK')"   # 不足 → pip install frida pycryptodome
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt"   # 不足 → extract_raw_key.py で鍵抽出
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted"         # 不足 → decrypt_all.py で全データベース復号

不足している項目に対応する手順を実行:deps→setup.ps1、key→extract_raw_key.py、平文DB→decrypt_all.py。

セルフチェックをスキップしないこと。

Agent 起動ルール

ユーザーの意図アクション
"WeChat を見せて" "最近のチャット" "誰から連絡があった?" "新しいメッセージは?"MCP: wechat_recent_messages / wechat_chat_summary
"XX とのチャットを検索" "XX って言ってたことある?"MCP: wechat_search_messages
"チャット一覧" "どんなグループがある?"MCP: wechat_list_chats
"XX とのチャットを読んで"MCP: wechat_read_chat
"XX とのチャットをエクスポート" "XX をデスクトップにエクスポート"先に①モデル確認(下記)を行い、次に python3 scripts/common/export_chat.py <contact> [--start/--end/--year] [-o path](日付指定なし=全履歴;モデルがあればデフォルトで文字起こし、--no-transcribe で無効化可能;音声文字起こし結果は voice_cache.json にキャッシュされ、2回目以降のエクスポートは即座に完了)
"XX の音声を文字起こし" "音声をテキストに" "音声をテキストでエクスポート"python3 scripts/common/export_chat.py <contact> --transcribe、または個別に python3 scripts/common/transcribe_db.py <contact> -o map.json
"WeChat がアップデートされた" "再クラックが必要" "鍵が無効になった"該当プラットフォームの「鍵抽出」手順を実行

① エクスポート前——音声文字起こしモデル確認(デフォルトで実行)

音声が含まれる可能性のある会話をエクスポート/文字起こしする前に、モデルが準備されているか確認:

test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING
結果アクション
MODEL_OKエクスポート時はデフォルトで音声文字起こしを有効化(スクリプトがモデルを検出すれば自動的に文字起こし、--transcribe は不要;ユーザーが明確に不要と指定した場合のみ --no-transcribe を追加)
MODEL_MISSINGまずユーザーにインストールするか確認(whisper-large-v3 約3GB、純粋なオフライン、一度だけ)。インストールする場合→--transcribe を追加(初回は自動ダウンロード&文字起こし);しない場合→通常エクスポート、音声は [Audio] のまま

スクリプト側にも同じロジックが組み込まれています(モデルあり→デフォルトで文字起こし、なし→[Audio] を残してヒント表示)。ただし MODEL_MISSING の場合、Agent は自らユーザーに確認を取ること。勝手に3GBをダウンロードしてはいけません。

MCP ツール(登録名 wechat)

ツールパラメータ用途
wechat_list_chatsなしすべての会話(グループ名・備考は解析済み)
wechat_read_chatcontact, limit(50), days(7)特定の会話を読む
wechat_search_messageskeyword, days(30), limit(50)全文検索
wechat_recent_messagesdays(3), limit(100)最近の動き
wechat_chat_summarydays(3)構造化された要約+ToDo

[私] = ユーザーが送信、[相手] = 連絡先が送信。

音声文字起こし(完全自動)

音声メッセージ(local_type=34)のオーディオは SILK v3 形式で media_0.db の VoiceInfo.voice_data に保存され、svr_id == server_id で紐付けられます。パイプライン:VoiceInfo から直接取得 → pilk で SILK→wav デコード → whisper large-v3 で文字起こし → server_id 単位で書き戻し。完全自動、バッチ処理、完全オフライン、BlackHole/再生/再起動は不要。デフォルト動作:モデルがキャッシュされていれば自動文字起こし;--transcribe で強制(初回は ~3GB のモデルをダウンロードし、~/.cache/huggingface/ にキャッシュ);--no-transcribe で無効化。 バックエンドはプラットフォームに応じて自動切り替え:macOS = mlx-whisper(Apple Silicon)、Windows = faster-whisper(CPU int8、必要に応じてダウンロード);旧来の BlackHole+Swift 方式は langlobal 開発リポジトリにあります。

コマンドライン entry(ロジックコア;MCP はオプションの薄い窓口)

ロジックコアは scripts/common/query.py(コマンドライン)にあり、server.py の MCP ツールはそれを経由するだけです。Agent からの呼び出しは --json を推奨(構造化出力で解析が容易、テキスト整形の影響を受けない);人間がデバッグするときは --json なしでテキスト表示。

SKILL_DIR=~/.claude/skills/wechat-decrypt
python3 "$SKILL_DIR/scripts/common/query.py" list
python3 "$SKILL_DIR/scripts/common/query.py" recent -d 3 --json      # Agent は --json を使う
python3 "$SKILL_DIR/scripts/common/query.py" search キーワード --json
# サブコマンド: list / read <contact> / search <kw> / recent / summary / stats / media / openfile

鍵体系(両プラットフォーム共通)

  • Raw Key: 64 桁の hex、デバイスごとに独立(WeChat 4.0:同一アカウントでも macOS と Windows の raw key は異なり、相互利用不可);WeChat がアップデートされなければ有効
  • 派生式: PBKDF2-HMAC-SHA512(raw_key, db_file_salt, 256000) → 32 bytes
  • SQLCipher パラメータ: PRAGMA key = "x'<derived>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;

データベースパス

プラットフォームパス
macOS~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/
Windows~/Documents/xwechat_files/{wxid}/db_storage/

鍵抽出

macOS

Agent 実行手順

  1. 再署名の確認:codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"
    • NEED_RESIGN → ユーザーに sudo codesign --force --deep --sign - /Applications/WeChat.app の実行を依頼
  2. bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh を実行
  3. スクリプトが WeChat を起動 → ユーザーにQRコードログインを依頼 → ログイン後、鍵が自動で key.txt に書き込まれる
  4. 確認:test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK"
  5. 抽出後はユーザーに署名の復元を依頼:adhoc 再署名は破壊的な一方向操作で、Tencent の元の署名を上書きします。その結果、WeChat のスクリーンショットやデータアクセスで権限ダイアログが繰り返し表示されるようになります。codesign でサードパーティ署名を元に戻すことはできないため、WeChat の再インストールでのみ復元可能です。チャット履歴は独立したコンテナディレクトリ(~/Library/Containers/com.tencent.xinWeChat/)に保存されるため、/Applications/WeChat.app の再インストールには影響しません。鍵抽出後の日常的なメッセージ確認は DB の読み取りのみで、再署名は不要です。

重要な認識

  • 再署名は「鍵抽出」の瞬間にのみ必要であり、抽出が完了したら WeChat を再インストールして署名を復元する必要があります。
  • 権限ダイアログが繰り返し表示される = WeChat の署名が adhoc 状態である症状であり、Claude Code/MCP が原因ではありません。
  • 鍵はデバイスごとに独立(同一アカウントでも各端末の鍵は異なり、相互利用不可)、WeChat がアップデートされなければ有効であり、再抽出は不要です。

原理

WeChat 4.x macOS 版は sqlite3_key を呼び出しません(Apple システム SQLite のこの関数は空のシェルです)。代わりに WCDB 統合暗号化レイヤーを介して CCKeyDerivationPBKDF(CommonCrypto)を呼び出します。Frida は Module.findGlobalExportByName(Frida 17.x+ の API)を使用してこの関数をフックし、passwordLen=32, rounds>1000, dkLen=32 の条件でパスワードパラメータ(raw key)をキャプチャします。

Windows(解決済み:鍵抽出→復号→読み取り、macOS と同等の機能)

現状(2026-06-06 UTM 実機テスト完了):鍵抽出→全データベース復号→MCP/エクスポート/音声文字起こしが macOS と同様に動作。message_0 から 99 セッション/1384 メッセージを解読。詳細な手順は docs/2026-06-06-windows-raw-key-journey.md を参照。

Agent 実行手順

  1. WeChat にログイン
  2. 鍵抽出:python scripts\windows\extract_raw_key.py → 指示に従ってデスクトップ上で手動で WeChat を再起動(必須;schtasks/SSH から起動したものは空のシェルで、DB を読みません)→ スクリプトが自動的に race-attach + hook sha512 で raw key を取得・検証し、key_windows.txt に書き込み
  3. 全データベース復号:python scripts\windows\decrypt_all.py → raw key を使用して db_storage 内のすべてのデータベースを decrypted\{wxid}_<device>\db_storage\ に復号(平文)
  4. Claude Code を再起動 → MCP ツール、エクスポート、音声文字起こしは macOS と完全に同一(server/export/transcribe は DB_BACKEND="sqlite3" で平文データベースを読み取り;音声は faster-whisper を使用)

単一データベースの検証/デバッグには scripts\windows\decrypt_read.py <raw_key> を使用(message_0 のみ復号して確認)。

鍵抽出の原理(sha512 エントリポイント hook + HMAC ipad)

核心:raw key/K1 はメモリ上で三重に保護されています(AES-NI ラウンドキー/使用後消去/secure mem。メモリ bruteforce はすべて失敗)。しかし SQLCipher の派生鍵は PBKDF2-HMAC-SHA512 を使用しており、HMAC が ipad block を構築する瞬間、鍵の平文 key XOR 0x36(後続 96 バイトは常に 0x36)が現れます——これによりすべての保護を回避して直接取得できます。 extract_raw_key.py は自己完結型:自動的に sha512 のエントリポイントを特定(K 定数 0x428a2f98d728ae22 を検索→xref→逆アセンブル。アドレスをハードコードしないため、WeChat のバージョンが変わっても動作)+ race-attach(DB オープン前に割り込む)+ エントリポイントをフック(rdx=input block)+ 検出 ipad + 自動検証(PBKDF2→AES page1 が先頭 = raw key 汎用 / 直接 AES が先頭 = K1 単一DB)。PBKDF2(raw,salt) の起動により raw key が露出します。実行時の page-MAC は mac_key のみを露出し、役に立ちません→起動時に race で割り込む必要があります。 frida は ARM エミュレーション(xtajit による x64 変換)下でも WeChat 内部の x64 関数をフック可能(1127万回の検証済み);spawn が非互換のため race-attach を使用。

  • データパス:C:\Users\<ユーザー>\Documents\xwechat_files\{wxid}_<device>\db_storage\。wechat-dump-rs は DMCA で封鎖されましたが、本手法が代替となります。
  • 開発期間中の全攻略スクリプト(位置特定/brute/失敗記録)は langlobal 開発リポジトリにあり、実行に必要なのは extract_raw_key.py + decrypt_all.py のみです。

配布とインストール

skill ディレクトリ全体をコピー。受け取り側で実行:

macOS: bash setup.sh Windows: powershell -File setup.ps1

key.txt、contacts.json、all_keys.json、voice_cache.json は個人データのため、配布前に削除すること(.gitignore で除外済み)。

ファイル一覧

~/.claude/skills/wechat-decrypt/          # 実行ユニット;開発一式(tests/docs/攻略スクリプト/legacy)は langlobal 開発リポジトリ
├── server.py config.py crypto.py db.py contacts.py message.py   ← MCP 実行コア(6)、db.py はデュアルバックエンド
├── scripts/
│   ├── common/    ← クロスプラットフォーム:export_chat(エクスポート+文字起こし) transcribe_db voice_decode sqlcipher_decrypt read_doc export_media verify_key
│   ├── macos/     ← extract_key.sh + hook_pbkdf.js (CCKeyDerivationPBKDF)
│   └── windows/   ← extract_raw_key.py(自己完結型鍵抽出) decrypt_all.py(全DB復号→平文) decrypt_read.py(単一DB検証)
├── setup.sh / setup.ps1   ← プラットフォームインストーラ
├── SKILL.md README.md LICENSE
├── key.txt key_windows.txt   ← .gitignore
└── contacts.json             ← .gitignore

依存関係:macOS グローバル python(mcp/frida/cryptography/pilk/mlx-whisper/zstd);Windows(mcp/frida/pycryptodome/pilk/faster-whisper/zstandard)。音声モデルキャッシュ ~/.cache/huggingface/。

関連スキル