wx-cli explicado: consultar el historial local de WeChat desde la línea de comandos

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

wx-cli es una herramienta de línea de comandos escrita en Rust para datos locales de WeChat. Su objetivo es permitirte consultar desde la terminal tus propias sesiones de WeChat, historial de chats, contactos, miembros de grupos, favoritos, Moments, artículos de cuentas oficiales, adjuntos y estadísticas.

No es un servicio de sincronización de WeChat en la nube, ni un chatbot. Se parece más a una capa local de recuperación de datos en modo solo lectura: WeChat sigue ejecutándose en tu máquina, los datos siguen quedándose en tu máquina, y wx-cli se encarga de descifrar, cachear y consultar las bases de datos locales bajo demanda, para después devolver resultados en YAML o JSON a una persona o a un Agent.

Hay dos puntos que hacen interesante este proyecto. Primero, convierte la consulta de datos locales de WeChat en una CLI multiplataforma. Segundo, tiene en cuenta de forma explícita los escenarios de AI Agent con herramientas como Claude Code, Cursor y Codex, ofreciendo un archivo SKILL.md y salida estructurada con campos meta.

Qué puede hacer wx-cli

Según el README del proyecto, wx-cli cubre un conjunto de funciones bastante completo:

Ver sesiones recientes y sesiones no leídas.
Consultar el historial de chat de un contacto o grupo.
Buscar palabras clave en toda la base de datos local.
Ver mensajes nuevos.
Consultar contactos, miembros de grupos y apodos dentro de grupos.
Consultar favoritos.
Consultar notificaciones, línea de tiempo y contenido de Moments.
Consultar artículos enviados por cuentas oficiales.
Listar y extraer adjuntos de imágenes en chats.
Generar estadísticas de chat.
Exportar historiales de chat como Markdown o JSON.

Estas capacidades hacen que no sea solo una herramienta para “buscar chats”, sino una forma de convertir los datos locales de WeChat en una base de información local que se puede buscar, analizar y exportar.

Por qué encaja con AI Agents

Muchas herramientas CLI están pensadas solo para personas, y su salida es un bloque de texto. wx-cli, en cambio, claramente considera la lectura por parte de agentes.

El README menciona que comandos como history, search, sessions, unread, new-messages, stats y attachments incluyen información meta. Esa metadata contiene estado del resultado, shards desconocidos, la hora más reciente de los datos encontrados, la hora más reciente registrada en la session y otros campos similares.

Esto es útil para un Agent. La IA no solo necesita saber “qué se encontró”; también necesita saber si el resultado está actualizado, si puede faltar algún mensaje y si conviene ejecutar init de nuevo. Por ejemplo:

status puede indicar si el resultado es ok o possibly_stale.
unknown_shards puede indicar si existen shards de base de datos para los que el daemon aún no tiene key.
chat_latest_timestamp le dice al Agent cuál es la hora del mensaje más reciente en los datos encontrados.
session_last_timestamp ayuda a determinar si el registro local de la session está claramente por delante del resultado de la consulta.

Este tipo de metadata reduce errores de juicio de la IA y hace que herramientas como Claude Code, Cursor y Codex sean más fiables al trabajar con datos de WeChat.

Instalación

El proyecto recomienda la instalación multiplataforma mediante npm:

`1`	`npm install -g @jackwener/wx-cli`

También admite instalación con curl en macOS / Linux:

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

En Windows, ejecútalo en PowerShell como administrador:

`1`	`irm https://raw.githubusercontent.com/jackwener/wx-cli/main/install.ps1 \| iex`

Si quieres compilar desde el código fuente, también puedes usar Rust directamente:

1
2

git clone git@github.com:jackwener/wx-cli.git && cd wx-cli
cargo build --release

El artefacto generado es target/release/wx; en Windows, wx.exe.

Relación con Agent Skills

wx-cli también ofrece una Skill orientada a AI Agents. Se puede instalar con un solo comando en Claude Code, Cursor, Codex y otros entornos compatibles con Skills mediante la skills CLI:

`1`	`npx skills add jackwener/wx-cli`

Instalación global:

`1`	`npx skills add jackwener/wx-cli -g`

Después de instalarla, el Agent lee el SKILL.md del repositorio y entiende cómo instalar, inicializar y llamar a wx-cli.

Esto significa que puedes pedir a un Agent que te ayude con tareas locales de organización de información, por ejemplo:

Encontrar palabras clave comentadas en un grupo durante un periodo determinado.
Resumir mensajes recientes no leídos.
Exportar el historial reciente de una sesión concreta.
Buscar enlaces de artículos de cuentas oficiales.
Analizar estadísticas de participación en un grupo.

La condición sigue siendo la misma: esos datos deben ser tus propios datos de WeChat, en tu propia máquina.

Uso básico

Antes de inicializar, mantén WeChat en ejecución. Los requisitos varían según la plataforma.

En Linux:

`1`	`sudo wx init`

En Windows, usa PowerShell como administrador:

wx init

En macOS es más complejo. El README explica que, con la ruta predeterminada, primero hay que aplicar una firma ad-hoc a WeChat para poder escanear la memoria del proceso. Después de volver a firmar, también hay que limpiar registros antiguos de autorización TCC; de lo contrario, permisos como captura de pantalla, videollamadas o micrófono pueden parecer activados pero estar realmente denegados. La documentación del proyecto también advierte que volver a firmar puede hacer que macOS muestre con frecuencia avisos para acceder a datos de otras apps.

Después de inicializar, puedes verificarlo con:

`1`	`wx sessions`

Si ves las sesiones recientes, la ruta básica ya funciona. El daemon se inicia automáticamente en la primera llamada.

Ejemplos de comandos comunes

Ver sesiones recientes:

`1`	`wx sessions`

Ver sesiones no leídas:

`1`	`wx unread`

Mostrar solo no leídos de personas y grupos, filtrando cuentas oficiales y entradas plegadas:

`1`	`wx unread --filter private,group`

Ver el historial reciente de una sesión:

`1`	`wx history "张三"`

Obtener más historial:

`1`	`wx history "张三" -n 2000`

Consultar un grupo por rango de fechas:

`1`	`wx history "AI群" --since 2026-04-01 --until 2026-04-15`

Buscar en toda la base:

`1`	`wx search "关键词"`

Buscar una palabra clave dentro de un grupo:

`1`	`wx search "会议" --in "工作群" --since 2026-01-01`

Exportar historial de chat:

1
2

wx export "张三" --format markdown -o chat.md
wx export "AI群" --since 2026-01-01 --format json

Estos comandos encajan bien con scripts o Agents, sobre todo cuando se combinan con --json.

Moments y artículos de cuentas oficiales

wx-cli no se limita a consultar chats.

Los comandos relacionados con Moments se dividen en notificaciones y publicaciones:

1
2
3

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

Conviene tener presente que los datos de Moments solo cubren contenido que haya aparecido localmente. El cliente de WeChat descarga datos bajo demanda; si algo nunca apareció en tu entorno local, la herramienta no puede obtenerlo de la nada.

Los artículos de cuentas oficiales se consultan mediante comandos independientes:

wx biz-articles
wx biz-articles --account "返朴"
wx biz-articles --since 2026-05-01 --until 2026-05-10
wx biz-articles --json | jq '.[].url'

Devuelve campos como nombre de la cuenta oficial, título, URL, resumen, portada y hora. Para quienes organizan referencias, recopilan artículos o construyen una base de conocimiento local, esta función resulta muy práctica.

Extracción de adjuntos

Los adjuntos de imagen en chats de WeChat normalmente no son archivos de imagen corrientes que se puedan leer directamente. Suelen existir como archivos .dat bajo xwechat_files/<wxid>/msg/attach/....

wx-cli ofrece un flujo de dos pasos:

1
2

wx attachments "张三"
wx attachments "AI群" --kind image -n 100

Primero obtienes el attachment_id; después lo extraes:

`1`	`wx extract <attachment_id> -o ~/Desktop/photo.jpg`

El informe de salida incluye campos como md5, dat_path, dat_size, output, format y decoder. El README indica que admite modos de decodificación como legacy XOR, V1 fixed-AES y V2 AES + XOR, y que la extracción de image key varía según la plataforma.

Esta parte es potente, pero también requiere más cautela: procesa solo tus propios datos y no la uses para acceder a datos sin autorización.

Por qué importa la arquitectura daemon

El punto de rendimiento de wx-cli está en su daemon.

La estructura descrita en el README es aproximadamente esta:

wx (CLI) ──Unix socket──▶ wx-daemon (proceso en segundo plano)
                              │
                    ┌─────────┴──────────┐
               DBCache               caché de contactos
           (reutilización sensible a mtime)

Después del primer descifrado, el daemon persiste información de base de datos y mtime en ~/.wx-cli/cache/. Si el mtime del archivo de base de datos no cambió, las llamadas posteriores pueden reutilizar la caché sin volver a descifrarlo todo.

Esto es clave para consultas de línea de comandos y bucles de Agent. Un Agent puede consultar varias sesiones seguidas, buscar múltiples palabras clave y luego generar estadísticas o exportaciones. Si cada llamada tuviera que escanear y descifrar todo de nuevo, la experiencia sería mala. La caché del daemon lo acerca más a un servicio local de consultas.

Principio básico

El README del proyecto explica el principio de forma directa: WeChat 4.x cifra las bases de datos locales con SQLCipher 4, y WCDB cachea la raw key derivada en la memoria del proceso.

wx-cli usa métodos diferentes según la plataforma para escanear la memoria del proceso de WeChat, encontrar patrones de key y extraer la clave. Luego el daemon descifra y cachea las bases de datos bajo demanda.

El mecanismo de bajo nivel varía por plataforma:

macOS usa Mach VM API.
Linux usa /proc/<pid>/mem.
Windows usa VirtualQueryEx y ReadProcessMemory.

Estas capacidades explican por qué la inicialización suele requerir permisos elevados, y por qué en macOS intervienen firma y autorización de privacidad.

Límites y riesgos de uso

Con herramientas de este tipo, primero hay que hablar de límites.

El descargo de responsabilidad del README de wx-cli es claro: la herramienta es solo para aprendizaje e investigación, para descifrar tus propios datos de WeChat, y exige cumplir las leyes y regulaciones aplicables. No debe usarse para acceder a datos sin autorización.

En la práctica, también conviene tener en cuenta lo siguiente:

Úsala solo en tu propio ordenador y con tu propia cuenta de WeChat.
No subas sin pensar historiales de chat exportados a modelos en la nube.
Si usas un Agent para analizar chats, confirma primero el proveedor de API y los riesgos de transferencia de datos.
Después de exportar Markdown / JSON, cuida los permisos del archivo y la ubicación de las copias de seguridad.
En equipos de empresa o compartidos, confirma antes la autorización y el cumplimiento normativo.

Una herramienta local no significa que no haya riesgo de privacidad. Reduce la ruta predeterminada por la que los datos salen de tu máquina, pero si entregas la salida a un modelo en la nube, un disco en la nube o un script de terceros, el riesgo vuelve.

Para quién es

wx-cli encaja en estos escenarios:

Quieres buscar rápidamente tu propio historial de mensajes de WeChat de forma local.
Necesitas exportar una sesión como Markdown o JSON.
Quieres analizar la actividad de mensajes de un grupo durante un periodo.
Quieres que Claude Code, Cursor, Codex u otros Agents organicen material local de WeChat.
Quieres incorporar enlaces de artículos de cuentas oficiales a una base de conocimiento local.
Quieres estudiar la estructura local de bases de datos de WeChat y su flujo de descifrado.

No encaja tan bien en estos casos:

Quieres sincronización de WeChat en la nube.
Quieres saltarte permisos de dispositivos o cuentas de otras personas.
Quieres operar solo con una interfaz gráfica y no tocar la línea de comandos.
No quieres lidiar con permisos de macOS, derechos de administrador en Windows o sudo en Linux.

Resumen

El valor de wx-cli no es simplemente “buscar historiales de chat de WeChat desde la línea de comandos”. De forma más precisa, convierte los datos locales de WeChat en una fuente local que se puede consultar, exportar y consumir desde Agents.

Su arquitectura daemon resuelve los problemas de descifrado repetido y rendimiento de consulta; el wrapper meta ayuda a los AI Agents a determinar si los resultados están actualizados; y SKILL.md permite que herramientas como Claude Code, Cursor y Codex entiendan cómo instalarlo y usarlo.

Si a menudo necesitas encontrar información en WeChat, organizar chats de grupos, exportar registros o construir una base de conocimiento personal, wx-cli merece atención. Pero al usarlo conviene recordar siempre una regla básica: procesa solo tus propios datos y gestiona con cuidado los resultados exportados.

Referencias

Repositorio GitHub de jackwener/wx-cli

Wx-Cli on KnightLi Blog