Depuración en OpenClaw

Cuando algo se rompe, necesitas ver qué está pasando realmente, no lo que crees que debería pasar. Es frustrante trabajar a ciegas cuando el modelo devuelve resultados inesperados o el flujo se detiene sin explicación.

Estas herramientas te permiten inspeccionar la salida en bruto del modelo, ejecutar ciclos de iteración rápidos y separar tu entorno de desarrollo del de producción para evitar errores costosos.

Requisitos previos

• Tener commands.debug: true habilitado en tu configuración.
• Acceso a la terminal con pnpm instalado.
• Un entorno de OpenClaw funcional.

Inicio rápido

Sigue estos pasos para empezar a depurar en menos de 5 minutos:

1. Activa el modo observación: Ejecuta pnpm gateway:watch --force para que el Gateway se reinicie al guardar cambios.
2. Usa el perfil de desarrollo: Lanza el Gateway con pnpm gateway:dev para usar un estado aislado en ~/.openclaw-dev.
3. Inspecciona el stream: Ejecuta el Gateway con el flag --raw-stream para ver la salida exacta del modelo en un archivo JSONL.
4. Prueba cambios en vivo: Usa el comando /debug set en el chat para cambiar la configuración sin reiniciar ni editar archivos.

Runtime Debug Overrides

Usa /debug en el chat para ajustar la configuración sin editar archivos físicos. Estos cambios solo viven en la memoria y no se guardan permanentemente:

/debug show                                    # Ver overrides actuales
/debug set messages.responsePrefix="[test]"    # Establecer un valor
/debug unset messages.responsePrefix           # Eliminar un override
/debug reset                                   # Limpiar todos los overrides

Gateway Watch Mode

Para iterar rápido, ejecuta el Gateway con detección de cambios en archivos:

pnpm gateway:watch --force

Esto reinicia el Gateway automáticamente cada vez que guardas un archivo. Es el equivalente a ejecutar:

tsx watch src/entry.ts gateway --force

Perfil Dev (Estado aislado)

Usa un perfil de desarrollo para que tus pruebas no ensucien el estado de producción:

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Qué hace el perfil dev:

• Usa el directorio de estado: ~/.openclaw-dev.
• Usa el puerto del Gateway: 19001.
• Omite el archivo BOOTSTRAP.md.
• Crea una configuración por defecto mínima.
• Usa la identidad: C3-PO (protocol droid).
• Omite los proveedores de canales (channel providers).

Si necesitas empezar de cero, usa este comando para borrar la configuración de desarrollo, credenciales y sesiones:

pnpm gateway:dev:reset

Logs de Stream en bruto

Para ver exactamente qué devuelve el modelo antes de cualquier filtrado, activa el registro del stream:

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

Por defecto, los logs se guardan en ~/.openclaw/logs/raw-stream.jsonl. Si necesitas una ruta personalizada, usa:

pnpm gateway:watch --force --raw-stream --raw-stream-path /tu/ruta.jsonl

También puedes usar variables de entorno:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

Esta es la mejor forma de detectar si el contenido de razonamiento (reasoning) se está filtrando en la salida de texto normal.

Solución de problemas

• Los comandos /debug no funcionan: Asegúrate de tener commands.debug: true en tu archivo de configuración.
• Los cambios de /debug desaparecen: Estos comandos son “memory-only”, lo que significa que se pierden al reiniciar el proceso.
• El estado de desarrollo está corrupto: Ejecuta pnpm gateway:dev:reset para limpiar el entorno (usa trash en lugar de rm por seguridad).
• No ves los logs de OpenAI: Si usas pi-mono, asegúrate de configurar PI_RAW_STREAM=1 para capturar los chunks compatibles con OpenAI antes del parseo.

Notas de seguridad

• Los logs de stream en bruto pueden contener prompts, salidas de herramientas (tools) y datos de usuario.
• Mantén los logs de forma local y bórralos tras terminar la depuración.
• Limpia secretos y datos PII antes de compartir cualquier log.

¿Sigues con problemas? Nuestro AI Setup Assistant puede ayudarte a depurar tu configuración.

Próximos pasos

• Logging → — Logs de archivos y salida de consola.
• Testing → — Suites de pruebas y tests en vivo.
• Gateway Configuration → — Referencia completa de configuración.
• Variables de Entorno → — Consulta la tabla de variables disponibles.