Depuración en OpenClaw: Cómo ver lo que ocurre bajo el capó

Seguro te ha pasado: estás probando un nuevo modelo y el streaming se vuelve loco. Los bloques de razonamiento se mezclan con el texto normal y es imposible entender qué está fallando exactamente en la salida del proveedor.

Intentar arreglar esto editando archivos de configuración cada dos minutos es agotador. Necesitas visibilidad directa de los datos crudos y un entorno seguro para hacer pruebas sin romper tu configuración principal.

Requisitos previos

• Instalación activa de OpenClaw.
• Gestor de paquetes pnpm.

Inicio rápido

1. Activa los comandos de depuración en tu openclaw.json con commands.debug: true.
2. Ejecuta el Gateway en modo watch para recarga rápida: pnpm gateway:watch --force.
3. Usa el comando /debug show directamente en el chat para ver la configuración en memoria.
4. Lanza un entorno aislado con pnpm gateway:dev para pruebas destructivas.

Runtime debug overrides

Puedes usar el comando /debug en el chat para cambiar configuraciones que solo vivirán en la memoria (no se guardan en el disco). Esto es ideal para probar ajustes sin editar openclaw.json. Recuerda que esto viene desactivado por defecto.

Ejemplos de uso:

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset

El comando /debug reset borra todos los cambios temporales y vuelve a lo que tengas definido en tu archivo de configuración.

Gateway watch mode

Si estás iterando rápido, ejecuta el Gateway con el file watcher. Esto reiniciará el proceso automáticamente cada vez que detecte cambios:

pnpm gateway:watch --force

Este comando ejecuta internamente tsx watch src/entry.ts gateway --force. Si necesitas pasar flags adicionales al Gateway, puedes añadirlas después de gateway:watch.

Perfil dev y dev gateway (—dev)

Para no ensuciar tu configuración principal, usa el perfil de desarrollo. Existen dos flags --dev que funcionan de forma distinta:

• Global --dev (perfil): Aísla el estado en ~/.openclaw-dev y cambia el puerto del Gateway al 19001.
• gateway --dev: Ordena al Gateway crear una configuración y espacio de trabajo por defecto si no existen, saltándose el archivo BOOTSTRAP.md.

El flujo que te recomiendo para depurar es:

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Esto configura automáticamente una identidad de C3‑PO, usa un espacio de trabajo de desarrollo y desactiva los proveedores de canales para evitar ruido. Si necesitas empezar de cero totalmente, usa:

pnpm gateway:dev:reset

Raw stream logging (OpenClaw)

Esta es la mejor forma de ver si el razonamiento del modelo llega como texto plano o en bloques separados. OpenClaw puede registrar el stream crudo del asistente antes de cualquier filtrado.

Actívalo desde la CLI:

pnpm gateway:watch --force --raw-stream

Si quieres guardar los logs en una ruta específica:

pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Por defecto, los logs se guardan en ~/.openclaw/logs/raw-stream.jsonl.

Raw chunk logging (pi-mono)

Si el problema está en los chunks de compatibilidad con OpenAI antes de ser procesados, pi-mono tiene su propio logger. Solo tienes que configurar esta variable de entorno:

PI_RAW_STREAM=1

La ruta por defecto será ~/.pi-mono/logs/raw-openai-completions.jsonl. Ten en cuenta que esto solo funciona si usas el proveedor openai-completions de pi-mono.

Seguridad

• Los logs de stream crudo contienen prompts completos, datos de herramientas y mensajes del usuario.
• Borra los logs después de terminar la depuración.
• Si vas a compartir un log para pedir ayuda, asegúrate de borrar credenciales y datos personales.

Solución de problemas

• El Gateway no arranca porque ya hay un proceso activo: Detén cualquier instancia previa con openclaw gateway stop antes de iniciar el modo dev.
• El flag --dev no se reconoce: Algunos runners pueden ignorar el flag. En ese caso, usa la variable de entorno: OPENCLAW_PROFILE=dev openclaw gateway --dev --reset.

AI Setup Assistant

Próximos pasos

• Configuración de proveedores
• Gestión de workspaces