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"
| Status | Ação |
|---|---|
MCP_MISSING | macOS bash setup.sh / Windows powershell -File setup.ps1, informar "Reinicie o Claude Code" |
KEY_MISSING | Executar o fluxo de "extração de chave" da plataforma correspondente (no Windows, após extrair a chave, também executar python scripts\windows\decrypt_all.py para descriptografar todo o banco) |
| Tudo OK | Usar diretamente as ferramentas MCP |
Autoverificação no Windows (PowerShell, alinhado com os três itens do macOS acima):
python -c "import frida, Crypto; print('DEPS_OK')" # Se falhar → pip install frida pycryptodome Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt" # Se não existir → extrair chave com extract_raw_key.py Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted" # Se não existir → descriptografar todo o banco com decrypt_all.pySe algum item estiver faltando, execute a etapa correspondente: deps→
setup.ps1, chave→extract_raw_key.py, banco em texto claro→decrypt_all.py.
Não pule a autoverificação.
Regras de acionamento do agente
| Intenção do usuário | Ação |
|---|---|
| "Ver meu WeChat", "conversas recentes", "quem me procurou", "tem mensagens?" | MCP: wechat_recent_messages / wechat_chat_summary |
| "Pesquisar conversa com XX", "mencionado por XX" | MCP: wechat_search_messages |
| "Listar conversas", "quais grupos" | MCP: wechat_list_chats |
| "Ler conversa com XX" | MCP: wechat_read_chat |
| "Exportar conversa com XX", "exportar XX para a área de trabalho" | Primeiro executar ① verificação de modelo (veja abaixo), depois python3 scripts/common/export_chat.py <contato> [--start/--end/--year] [-o caminho] (sem data = histórico completo; se o modelo estiver presente, a transcrição será feita por padrão, --no-transcribe para desligar; resultado da transcrição de voz é armazenado em cache persistente em voice_cache.json, segunda exportação instantânea) |
| "Transcrever áudio de XX", "áudio para texto", "converter áudio em texto" | python3 scripts/common/export_chat.py <contato> --transcribe, ou separadamente python3 scripts/common/transcribe_db.py <contato> -o map.json |
| "WeChat atualizou", "re-crackear", "chave expirou" | Executar o fluxo de "extração de chave" da plataforma correspondente abaixo |
① Pré-requisito de exportação — Verificação do modelo de transcrição de voz (executado por padrão)
Antes de exportar/transcrever qualquer conversa que possa conter áudio, verifique se o modelo está presente:
test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING
| Resultado | Ação |
|---|---|
MODEL_OK | A exportação ativa a transcrição de voz por padrão (o script detecta o modelo e transcreve automaticamente, sem precisar de --transcribe; só desligar se o usuário pedir explicitamente, com --no-transcribe) |
MODEL_MISSING | Pergunte primeiro ao usuário se deseja instalar (whisper-large-v3 ~3GB, offline único). Se sim → adicionar --transcribe (primeira vez baixa e transcreve automaticamente); se não → exportação normal, áudio mantido como [Audio] |
O script já tem essa lógica embutida (modelo presente → transcrição padrão, ausente → mantém [Audio] e avisa). Mas quando MODEL_MISSING, o agente deve perguntar ativamente; não baixe 3GB por conta própria.
Ferramentas MCP (registradas como wechat)
| Ferramenta | Parâmetros | Uso |
|---|---|---|
wechat_list_chats | Nenhum | Listar todas as conversas (nomes de grupos e apelidos já resolvidos) |
wechat_read_chat | contact, limit(50), days(7) | Ler uma conversa específica |
wechat_search_messages | keyword, days(30), limit(50) | Pesquisa em texto completo |
wechat_recent_messages | days(3), limit(100) | Mensagens recentes |
wechat_chat_summary | days(3) | Resumo estruturado + tarefas pendentes |
[Eu] = mensagens enviadas pelo usuário, [Outro] = mensagens enviadas pelo contato.
Transcrição de voz (totalmente automática)
Mensagens de voz (local_type=34) têm seu áudio armazenado como SILK v3 no banco media_0.db, campo VoiceInfo.voice_data, alinhado por svr_id == server_id. Fluxo: leitura direta de VoiceInfo → decodificação SILK→wav com pilk → transcrição com whisper large-v3 → realimentação por server_id. Totalmente automático, em lote, offline, sem necessidade de BlackHole/reprodução/reinicialização. Comportamento padrão: se o modelo estiver em cache, a transcrição é automática; --transcribe força (incluindo download inicial do modelo ~3GB, cache em ~/.cache/huggingface/); --no-transcribe desliga. O backend muda automaticamente conforme a plataforma: macOS = mlx-whisper (Apple Silicon), Windows = faster-whisper (CPU int8, download sob demanda); a abordagem antiga com BlackHole+Swift está no repositório de desenvolvimento langlobal.
Entry point de linha de comando (núcleo da lógica; MCP é uma fachada opcional)
O núcleo da lógica está em scripts/common/query.py (linha de comando); as ferramentas MCP em server.py são apenas encaminhamentos para ele. Para chamadas do agente, recomenda-se usar --json para saída estruturada (mais confiável para parsing, não afetada pela formatação do texto); para depuração humana, não usar --json, ver texto legível.
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 # agente usar --json
python3 "$SKILL_DIR/scripts/common/query.py" search 关键词 --json
# Subcomandos: list / read <contato> / search <palavra-chave> / recent / summary / stats / media / openfile
Sistema de chaves (comum a ambas as plataformas)
- Chave bruta (Raw Key): 64 hex, independente por dispositivo (WeChat 4.0: mesma conta, chaves brutas do macOS e Windows são diferentes, não intercambiáveis); enquanto o WeChat não for atualizado, a chave permanece válida.
- Fórmula de derivação:
PBKDF2-HMAC-SHA512(chave_bruta, salt_do_arquivo_db, 256000) → 32 bytes - Parâmetros SQLCipher:
PRAGMA key = "x'<derivada>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;
Caminhos dos bancos de dados
| Plataforma | Caminho |
|---|---|
| macOS | ~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/ |
| Windows | ~/Documents/xwechat_files/{wxid}/db_storage/ |
Extração de chave
macOS
Fluxo de execução do agente
- Verificar re-assinatura:
codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"NEED_RESIGN→ Informar o usuário para executarsudo codesign --force --deep --sign - /Applications/WeChat.app
- Executar
bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh - O script iniciará o WeChat → Informar o usuário para escanear o QR code e fazer login → Após o login, a chave será gravada automaticamente em
key.txt - Verificar:
test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK" - Após a extração, o agente deve informar o usuário para restaurar a assinatura: a re-assinatura adhoc é uma operação destrutiva unidirecional; ela sobrescreve a assinatura original da Tencent, fazendo com que o WeChat exiba repetidamente caixas de diálogo de permissão para capturas de tela/acesso a dados. O
codesignnão pode restaurar assinaturas de terceiros; a única maneira é reinstalar o WeChat. O histórico de conversas está em um diretório de contêiner independente (~/Library/Containers/com.tencent.xinWeChat/); reinstalar/Applications/WeChat.appnão o afeta. Após a extração da chave, a consulta diária de mensagens é somente leitura do banco de dados, não precisando mais de re-assinatura.
Pontos-chave
- A re-assinatura é necessária apenas no momento da extração da chave; após a extração, reinstale o WeChat para restaurar a assinatura.
- Caixas de diálogo de permissão repetidas = sintoma de que a assinatura do WeChat está em estado adhoc, não causado pelo Claude Code/MCP.
- A chave é independente por dispositivo (cada conta em cada dispositivo tem chave diferente, não intercambiável); enquanto o WeChat não for atualizado, ela permanece válida, não sendo necessário extrair repetidamente.
Princípio
A versão macOS do WeChat 4.x não chama sqlite3_key (essa função do SQLite do sistema Apple é um shell vazio), mas sim usa a camada de criptografia unificada WCDB para chamar CCKeyDerivationPBKDF (CommonCrypto). O Frida usa Module.findGlobalExportByName (API Frida 17.x+) para fazer hook dessa função e capturar o parâmetro da senha quando passwordLen=32, rounds>1000, dkLen=32 (chave bruta).
Windows (já resolvido: extrair chave→descriptografar→ler, capacidade equivalente ao macOS)
Status atual (testado via UTM em 06/06/2026): extrair chave→descriptografar todo o banco→MCP/exportação/transcrição de voz, mesma capacidade do macOS. message_0 decifrado com 99 conversas/1384 mensagens. Fluxo completo em docs/2026-06-06-windows-raw-key-journey.md.
Fluxo de execução do agente
- Fazer login no WeChat
- Extrair chave:
python scripts\windows\extract_raw_key.py→ Seguir as instruções e reiniciar o WeChat manualmente na área de trabalho (obrigatório; iniciar via schtasks/SSH cria um processo vazio que não lê o banco) → O script faz race-attach automaticamente + hook sha512 para capturar a chave bruta + verificar, gravando emkey_windows.txt - Descriptografar todo o banco:
python scripts\windows\decrypt_all.py→ Usa a chave bruta para descriptografar todos os bancos emdb_storagepara o diretóriodecrypted\{wxid}_<device>\db_storage\(texto claro) - Reiniciar o Claude Code → Ferramentas MCP, exportação e transcrição de voz idênticas ao macOS (server/export/transcribe usam
DB_BACKEND="sqlite3"para ler o banco em texto claro; voz usa faster-whisper)
Para verificar/ depurar um único banco, use scripts\windows\decrypt_read.py <chave_bruta> (apenas descriptografa message_0 para teste).
Princípio da extração de chave (hook da entrada sha512 + ipad HMAC)
Núcleo: A chave bruta/K1 na memória tem proteção tripla (chave de rodada AES-NI / limpeza pós-uso / memória segura, todas as tentativas de brute force na memória falham), mas a chave derivada do SQLCipher passa por PBKDF2-HMAC-SHA512. No momento da construção do bloco ipad do HMAC, a chave está em texto claro chave XOR 0x36 (os últimos 96 bytes são sempre 0x36) — contornando todas as proteções.
extract_raw_key.py é autocontido: localiza automaticamente a entrada do sha512 (procura pela constante K 0x428a2f98d728ae22 → xref → desmontagem, sem endereços fixos, funciona mesmo se a versão do WeChat mudar) + race-attach (antes de abrir o banco) + hook na entrada (rdx = bloco de entrada) + detecção de ipad + verificação automática (PBKDF2→AES page1 resulta em chave bruta geral / AES direto resulta em K1 de banco único). Iniciar PBKDF2(raw,salt) expõe a chave bruta; em execução, page-MAC expõe apenas mac_key (inútil) → é obrigatório fazer race-attach na inicialização.
O Frida sob emulação ARM (xtajit traduzindo x64) consegue fazer hook em funções x64 internas do WeChat (verificado 11,27 milhões de vezes); como spawn não é compatível, usa-se race-attach.
- Caminho dos dados:
C:\Users\<usuário>\Documents\xwechat_files\{wxid}_<device>\db_storage\. Owechat-dump-rsfoi bloqueado por DMCA; este método o substitui. - O conjunto completo de scripts de desenvolvimento (localização/brute/registro de falhas) está no repositório de desenvolvimento langlobal; para executar, bastam
extract_raw_key.py+decrypt_all.py.
Distribuição e instalação
Copie todo o diretório do skill. O destinatário executa:
macOS: bash setup.sh
Windows: powershell -File setup.ps1
key.txt, contacts.json, all_keys.json, voice_cache.json são dados pessoais; remova-os antes de distribuir (já estão em .gitignore).
Lista de arquivos
~/.claude/skills/wechat-decrypt/ # Unidade de execução; desenvolvimento completo (testes/docs/scripts de pesquisa/legado) no repositório langlobal
├── server.py config.py crypto.py db.py contacts.py message.py ← Núcleo MCP (6), db.py com backend duplo
├── scripts/
│ ├── common/ ← Multiplataforma: export_chat(exportação+transcrição) 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(autocontido para extrair chave) decrypt_all.py(descriptografa todo o banco→texto claro) decrypt_read.py(verificação de banco único)
├── setup.sh / setup.ps1 ← Instalação por plataforma
├── SKILL.md README.md LICENSE
├── key.txt key_windows.txt ← .gitignore
└── contacts.json ← .gitignore
Dependências: macOS Python global (mcp/frida/cryptography/pilk/mlx-whisper/zstd); Windows (mcp/frida/pycryptodome/pilk/faster-whisper/zstandard). Cache do modelo de voz em ~/.cache/huggingface/.