tzwkb/wechat-decrypt

Skill para agente — Descifrado y consulta de chats de WeChat 4.x (macOS + Windows): lectura/búsqueda MCP, exportación y transcripción de voz.

¿Qué es wechat-decrypt?

Este skill permite a un agente de IA (como Claude Code o Cursor) descifrar, consultar, exportar y transcribir mensajes de voz de WeChat 4.x en macOS y Windows. Utiliza técnicas como Frida para extraer la clave de cifrado directamente de la memoria del proceso de WeChat (hookeando PBKDF2-HMAC-SHA512 o CCKeyDerivationPBKDF), y luego descifra la base de datos SQLCipher del chat. Una vez descifrada, expone herramientas MCP (como `wechat_recent_messages`, `wechat_search_messages`, `wechat_list_chats`) para que el agente pueda leer y buscar mensajes de forma estructurada. Además, es capaz de transcribir mensajes de voz (codificados en SILK v3) a texto mediante modelos whisper (mlx-whisper en Apple Silicon, faster-whisper en Windows), todo de forma offline y automática. Es útil para desarrolladores, analistas o usuarios que necesiten acceder a su historial de WeChat desde la línea de comandos o desde un asistente de IA.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add tzwkb/wechat-decrypt

Installed? Explore more Investigación y análisis de datos skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Descifrado y consulta de chats de WeChat 4.x (macOS + Windows)

Autocomprobación inicial (el agente debe ejecutarla)

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"
EstadoAcción
MCP_MISSINGmacOS: bash setup.sh / Windows: powershell -File setup.ps1, luego informa "reinicia Claude Code"
KEY_MISSINGEjecuta el flujo de "extracción de clave" correspondiente a la plataforma (en Windows, tras extraer la clave, ejecuta python scripts\windows\decrypt_all.py para descifrar toda la base de datos a texto plano)
Todo OKUsa las herramientas MCP directamente

Autocomprobación en Windows (PowerShell, equivalente a las tres comprobaciones de macOS):

python -c "import frida, Crypto; print('DEPS_OK')"   # Si falta → pip install frida pycryptodome
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt"   # Si falta → extract_raw_key.py para extraer clave
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted"         # Si falta → decrypt_all.py para descifrar toda la base

El paso que falte se ejecuta con su comando correspondiente: deps→setup.ps1, clave→extract_raw_key.py, base descifrada→decrypt_all.py.

No omitas la autocomprobación.

Reglas de activación del agente

Intención del usuarioAcción
"Mira mi WeChat" "Chats recientes" "Quién me buscó" "Hay mensajes"MCP: wechat_recent_messages / wechat_chat_summary
"Busca la conversación con X" "Menciona algo sobre"MCP: wechat_search_messages
"Lista las conversaciones" "Qué grupos hay"MCP: wechat_list_chats
"Lee la conversación con X"MCP: wechat_read_chat
"Exporta la conversación con X" "Exporta X al escritorio"Primero haz la ① comprobación del modelo (ver abajo), luego python3 scripts/common/export_chat.py <contacto> [--start/--end/--year] [-o ruta] (sin fecha = todo el historial; si el modelo está, la transcripción se activa por defecto, --no-transcribe la desactiva; los resultados de transcripción de voz se cachean en voice_cache.json, la segunda exportación es instantánea)
"Transcribe el audio de X" "Voz a texto" "Convierte el audio a texto"python3 scripts/common/export_chat.py <contacto> --transcribe, o por separado python3 scripts/common/transcribe_db.py <contacto> -o map.json
"WeChat se actualizó" "Re-hackear" "Clave no funciona"Ejecuta el flujo de "extracción de clave" correspondiente a la plataforma más abajo

① Comprobación previa a la exportación: modelo de transcripción de voz (se ejecuta por defecto)

Antes de exportar/transcribir cualquier conversación que pueda contener audio, comprueba si el modelo está presente:

test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING
ResultadoAcción
MODEL_OKLa exportación activa la transcripción de voz por defecto (el script detecta el modelo y transcribe automáticamente, sin necesidad de --transcribe; solo si el usuario dice explícitamente que no, añade --no-transcribe)
MODEL_MISSINGPregunta primero al usuario si quiere instalar (whisper-large-v3 ~3GB, descarga única offline). Si acepta, añade --transcribe (descarga automática en la primera ejecución y transcribe); si no, exportación normal, los audios se muestran como [Audio]

El script ya tiene esta lógica integrada (modelo presente → transcribe por defecto, no presente → muestra [Audio] y avisa). Pero cuando MODEL_MISSING, el agente debe preguntar activamente, no descargar 3GB sin permiso.

Herramientas MCP (registradas como wechat)

HerramientaParámetrosPropósito
wechat_list_chatsNingunoTodas las conversaciones (nombres de grupos y alias ya resueltos)
wechat_read_chatcontact, limit(50), days(7)Conversación específica
wechat_search_messageskeyword, days(30), limit(50)Búsqueda de texto completo
wechat_recent_messagesdays(3), limit(100)Actividad reciente
wechat_chat_summarydays(3)Resumen estructurado + pendientes

[yo] = mensajes del usuario, [otro] = mensajes del contacto.

Transcripción de voz (totalmente automática)

Los mensajes de voz (local_type=34) se almacenan como audio SILK v3 en la tabla VoiceInfo.voice_data de media_0.db, alineados por svr_id == server_id. Flujo: lectura directa de VoiceInfo → decodificación SILK→wav con pilk → transcripción con whisper large-v3 → rellenado por server_id. Totalmente automático, por lotes, offline, sin necesidad de BlackHole/reproducción/reinicio. Comportamiento por defecto: si el modelo está en caché, transcribe automáticamente; --transcribe lo fuerza (incluye descarga única ~3GB del modelo, cacheado en ~/.cache/huggingface/); --no-transcribe lo desactiva. El backend se selecciona automáticamente según la plataforma: macOS = mlx-whisper (Apple Silicon), Windows = faster-whisper (CPU int8, descarga bajo demanda); la solución anterior con BlackHole+Swift está en el repositorio de desarrollo langlobal.

Entrada de línea de comandos (núcleo lógico; MCP es una fachada opcional)

El núcleo lógico está en scripts/common/query.py (línea de comandos), las herramientas MCP de server.py solo redirigen a él. Para llamadas de agente se recomienda usar --json para obtener salida estructurada (más fiable, independiente del formato del texto); para depuración humana, sin --json, se ve texto plano.

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      # para el agente, usar --json
python3 "$SKILL_DIR/scripts/common/query.py" search 关键词 --json
# Subcomandos: list / read <contacto> / search <palabra> / recent / summary / stats / media / openfile

Sistema de claves (común a ambas plataformas)

  • Clave bruta (Raw Key): 64 hexadecimales, única por dispositivo (WeChat 4.0: la clave bruta de la misma cuenta en macOS y Windows es diferente, no intercambiable); mientras WeChat no se actualice, sigue siendo válida.
  • Fórmula de derivación: PBKDF2-HMAC-SHA512(clave_bruta, salt_archivo_db, 256000) → 32 bytes
  • Parámetros SQLCipher: PRAGMA key = "x'<derivada>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;

Rutas de bases de datos

PlataformaRuta
macOS~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/
Windows~/Documents/xwechat_files/{wxid}/db_storage/

Extracción de clave

macOS

Flujo de ejecución del agente

  1. Comprueba la re-firma: codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"
    • NEED_RESIGN → informa al usuario que ejecute sudo codesign --force --deep --sign - /Applications/WeChat.app
  2. Ejecuta bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh
  3. El script iniciará WeChat → informa al usuario que inicie sesión escaneando el código QR → tras el inicio de sesión, la clave se escribe automáticamente en key.txt
  4. Verifica: test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK"
  5. Después de la extracción, debes informar al usuario que restaure la firma: la re-firma adhoc es una operación destructiva unidireccional que sobrescribe la firma original de Tencent, provocando que las capturas de pantalla de WeChat y el acceso a datos soliciten permisos repetidamente. codesign no puede restaurar firmas de terceros; solo se puede reinstalar WeChat para recuperar la firma original. Los registros de chat se encuentran en un directorio de contenedor independiente (~/Library/Containers/com.tencent.xinWeChat/); reinstalar /Applications/WeChat.app no los afecta. Después de extraer la clave, las consultas diarias de mensajes solo usan la base de datos de solo lectura y ya no es necesaria la re-firma.

Información clave

  • La re-firma solo es necesaria en el momento de "extraer la clave"; una vez extraída, se debe reinstalar WeChat para restaurar la firma.
  • Los cuadros de diálogo de permisos repetitivos son un síntoma de que la firma de WeChat está en estado adhoc, no causados por Claude Code/MCP.
  • La clave es única por dispositivo (la clave de la misma cuenta en diferentes dispositivos es diferente, no intercambiable); mientras WeChat no se actualice, la clave sigue siendo válida y no es necesario extraerla repetidamente.

Principio

La versión 4.x de WeChat para macOS no utiliza sqlite3_key (esa función de SQLite del sistema de Apple es un cascarón vacío), sino que a través de la capa de cifrado unificada WCDB llama a CCKeyDerivationPBKDF (CommonCrypto). Frida usa Module.findGlobalExportByName (API de Frida 17.x+) para enganchar (hook) esa función y capturar el parámetro de contraseña cuando passwordLen=32, rounds>1000, dkLen=32 (la clave bruta).

Windows (ya resuelto: extraer clave → descifrar → leer, con capacidades equivalentes a macOS)

Estado actual (2026-06-06 probado en UTM): extraer clave → descifrar toda la base → MCP/exportación/transcripción de voz, mismas capacidades que macOS. message_0 descifrado: 99 conversaciones/1384 mensajes. Flujo completo en docs/2026-06-06-windows-raw-key-journey.md.

Flujo de ejecución del agente

  1. Inicia sesión en WeChat
  2. Extraer clave: python scripts\windows\extract_raw_key.py → sigue las instrucciones y reinicia WeChat manualmente desde el escritorio (es obligatorio; iniciar con schtasks/SSH crea un proceso vacío que no lee la base de datos) → el script se adjunta automáticamente (race-attach), engancha sha512 para capturar la clave bruta, la verifica y la escribe en key_windows.txt
  3. Descifrar toda la base: python scripts\windows\decrypt_all.py → usa la clave bruta para descifrar todas las bases de datos de db_storage en decrypted\{wxid}_<device>\db_storage\ (texto plano)
  4. Reinicia Claude Code → Las herramientas MCP, la exportación y la transcripción de voz son exactamente igual que en macOS (server/export/transcribe usan DB_BACKEND="sqlite3" para leer la base descifrada; la voz usa faster-whisper)

Para verificar/ depurar una sola base usa scripts\windows\decrypt_read.py <clave_bruta> (solo descifra message_0 para comprobar).

Principio de extracción de clave (hook de entrada de sha512 + HMAC ipad)

Núcleo: la clave bruta/K1 está protegida en memoria con triple capa (claves de ronda AES-NI/borrado después de usar/secure mem, la brute force en memoria falla), pero la clave derivada de SQLCipher pasa por PBKDF2-HMAC-SHA512. En el momento de construir el bloque ipad de HMAC, la clave está en texto plano clave XOR 0x36 (los últimos 96 bytes son siempre 0x36), lo que permite obtenerla sorteando toda la protección. extract_raw_key.py es autocontenido: localiza automáticamente la entrada de sha512 (busca la constante K 0x428a2f98d728ae22 → xref → desensamblado, sin direcciones fijas, funciona incluso si cambia la versión de WeChat) + se adjunta en una carrera (race-attach) antes de abrir la base de datos + engancha la entrada (rdx = bloque de entrada) + detecta ipad + verifica automáticamente (PBKDF2→AES page1 da la clave bruta general / AES directo da K1 de una sola base). Al iniciar, PBKDF2(raw, salt) expone la clave bruta; en tiempo de ejecución, la MAC de página solo expone mac_key (inútil) → es necesario ganar la carrera al inicio. Frida puede enganchar funciones x64 internas de WeChat bajo emulación ARM (traducción xtajit) (verificado con 11.27 millones de comprobaciones); como spawn no es compatible, se usa race-attach.

  • Ruta de datos: C:\Users\<usuario>\Documents\xwechat_files\{wxid}_<device>\db_storage\. wechat-dump-rs fue bloqueado por DMCA, este método lo reemplaza.
  • Todos los scripts de desarrollo (localización/brute/registro de fallos) están en el repositorio de desarrollo langlobal; para ejecutar solo se necesitan extract_raw_key.py + decrypt_all.py.

Distribución e instalación

Copia todo el directorio del skill. El receptor ejecuta:

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

key.txt, contacts.json, all_keys.json, voice_cache.json son datos personales; elimínalos antes de distribuir (ya están en .gitignore).

Lista de archivos

~/.claude/skills/wechat-decrypt/          # Unidad de ejecución; el desarrollo completo (tests/docs/scripts de ataque/legacy) está en el repositorio de desarrollo langlobal
├── server.py config.py crypto.py db.py contacts.py message.py   ← Núcleo de ejecución MCP (6), db.py con doble backend
├── scripts/
│   ├── common/    ← Multiplataforma: export_chat(exportación+transcripción) 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(autocontenido, extrae clave) decrypt_all.py(descifra toda la base→texto plano) decrypt_read.py(verifica una sola base)
├── setup.sh / setup.ps1   ← Instalación por plataforma
├── SKILL.md README.md LICENSE
├── key.txt key_windows.txt   ← .gitignore
└── contacts.json             ← .gitignore

Dependencias: macOS python global (mcp/frida/cryptography/pilk/mlx-whisper/zstd); Windows (mcp/frida/pycryptodome/pilk/faster-whisper/zstandard). Caché del modelo de voz en ~/.cache/huggingface/.

Skills relacionados