Depuración de OpenClaw

¿Qué hace Depuración de OpenClaw?

El comportamiento difiere entre pruebas locales, modelos en vivo, proveedores, modo código, Tool Search, Crabbox y CI: obtén señal de depuración antes de adivinar.

Leer Primero

• docs/logging.md: archivos de log, openclaw logs, flags de depuración específicos.
• docs/reference/test.md: comandos de prueba local.
• docs/tools/code-mode.md: ejecución/espera del modo código + reglas del catálogo de herramientas.
• $openclaw-testing: elección de carril de prueba.
• $crabbox: prueba amplia, Docker, paquete, Linux, clave en vivo, paridad con CI.

Bucle Predeterminado

1. Identifica la frontera sospechosa: configuración, construcción de herramientas, payload del proveedor, fetch, stream/SSE, repetición de transcripción, worker/runtime, paquete/dist, CI.
2. Agrega/habilita la señal más específica que demuestre la frontera.
3. Reproduce con el mismo proveedor/modelo/configuración. Nunca cambies de modelo al azar a menos que el modelo mismo sea la variable probada.
4. Compara el estado configurado con la activación real de la ejecución.
5. Corrige la causa raíz.
6. Vuelve a ejecutar la sonda exacta que falla; amplía solo si el contrato lo requiere.

Logs de Transporte del Modelo

Forma de la solicitud del modelo/tiempos del stream: usa flags de entorno específicos en lugar de depuración global:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

Flags útiles:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: inicio de solicitud, respuesta de fetch, cabeceras SDK, primer evento SSE, fin de stream, errores de transporte a nivel info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: resumen acotado del payload.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: todos los nombres de herramientas visibles para el modelo.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: payload JSON limitado y censurado. Solo durante depuración; el texto de mensajes/prompts aún puede aparecer.
• OPENCLAW_DEBUG_SSE=events: tiempo del primer evento + finalización del stream.
• OPENCLAW_DEBUG_SSE=peek: primeros cinco eventos SSE censurados.
• OPENCLAW_DEBUG_CODE_MODE=1: diagnóstico de la superficie de herramientas del modo código.

Observa logs:

openclaw logs --follow

Fronteras Comunes

• Configuración vs activación: la configuración habilitada puede coexistir con herramientas de ejecución deshabilitadas, ejecución en bruto, lista blanca vacía, falta de soporte de herramientas del modelo. Verifica las herramientas realmente visibles antes de imponer invariantes del payload del proveedor.
• Superficie de herramientas: inspecciona los nombres de herramientas finales visibles para el modelo, no solo el registro/la configuración. El modo código = exactamente exec + wait solo después de la activación real.
• Payload del proveedor: antes de la llamada al SDK, registra campos, ID del modelo, nivel de servicio, razonamiento, tamaño de entrada, claves de metadatos, presencia de clave de caché de prompt, nombres de herramientas.
• Fetch vs SSE: la respuesta de fetch demuestra que las cabeceras HTTP llegaron; el primer evento SSE demuestra el progreso del cuerpo del proveedor. La brecha aquí indica un problema de stream/cuerpo/proveedor, no de ejecución de herramientas.
• Worker/dist: al tocar workers, importaciones dinámicas, exportaciones de paquetes, límites del runtime perezoso, rutas publicadas → pnpm build.
• Claves en vivo: claves de proveedor faltantes → flujo de trabajo secreto configurado antes de declarar la prueba en vivo bloqueada. Las comprobaciones de entorno solo verifican presencia; nunca imprimas secretos.

Obtención de Sesiones y Transcripciones

Reporte de error de sesión de chat: obtén la transcripción real, atribución del remitente, archivos adjuntos como evidencia.

Primero CLI (necesita instalación configurada; seguro contra el gateway en vivo):

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

Documentación: diseño de almacenamiento docs/reference/database-schemas.md; CLI https://docs.openclaw.ai/cli/sessions.

Almacenamiento sin procesar: cuando la CLI no está disponible (por ejemplo, host remoto por SSH) o se necesita detalle a nivel de evento:

• Plano de datos por agente: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Esquema canónico: src/state/openclaw-agent-schema.sql.
• Estado alojado/systemd: directorio home del usuario de servicio (p. ej., /home/openclaw/.openclaw/...), no el de root. Root puede tener una instalación separada huérfana con diferentes agentes. Si falta el directorio esperado del agente: localiza la BD real con find / -maxdepth 6 -name openclaw-agent.sqlite.
• Fragmento de ID de sesión en URL de chat web: /chat/<agentId>/<slug>-<hex>. Resuelve en session_nodes: session_key LIKE '%<hex>%' → current_session_id, display_name. Forma de la clave: agent:<agentId>:<surface>:<uuid>; las sesiones de subagentes usan la superficie subagent.
• Transcripción: transcript_events (session_id, seq, event_json). event_json.message: role (user/assistant/toolResult) + content (cadena o partes de tipo text/toolCall/image).
• Procedencia del remitente: los mensajes de usuario reales llevan message.__openclaw (senderId, senderName, senderIsOwner); las entradas sintetizadas por el runtime no. Distingue texto escrito por el operador de prompts inyectados con esto.
• Búsqueda de texto completo en transcripciones: session_transcript_fts.
• Archivos adjuntos: URLs media://inbound/<file> → <state-dir>/media/inbound/<file>.
• Las imágenes adjuntas por el usuario no son partes de contenido image. El sobre del mensaje lleva entradas message.__openclaw.media[]: url (media://inbound/<file>), contentType, kind, fileName. El extractor solo de partes pierde todas las imágenes; busca en el event_json sin procesar por media://. Host remoto: copia archivos por scp localmente (una ruta remota por argumento de scp); lee allí.

Hosts sin el binario sqlite3 aún tienen Node: node:sqlite no necesita dependencias.

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <ruta-bd> <id-sesión>

• Siempre abre almacenes en vivo con readOnly: true; nunca escribas en el estado del gateway en ejecución (reglas de validación de AGENTS.md raíz).
• Trabajo con datos realistas: copia la BD en el directorio de estado de desarrollo primero.

Punteros de Código

• Payload del modelo + stream de Responses: src/agents/openai-transport-stream.ts
• Fetch/timing custodiado: src/agents/provider-transport-fetch.ts
• Wrappers de proveedor OpenAI/Codex: src/llm/providers/stream-wrappers/openai.ts
• Construcción de herramientas, Tool Search, activación del modo código: src/agents/embedded-agent-runner/run/attempt.ts
• Runtime del modo código y worker: src/agents/code-mode.ts src/agents/code-mode.worker.ts
• Catálogo de Tool Search: src/agents/tool-search.ts

Elección de Prueba

• Error de helper/payload único: Vitest local dirigido.
• Solo documentación/logs: pnpm check:docs + git diff --check.
• Worker/dist/importación perezosa/superficie de paquete: pruebas dirigidas + pnpm build.
• Comportamiento de modelo/proveedor en vivo: mismo proveedor/modelo, flags de depuración, clave real si está disponible.
• Docker/paquete/Linux/paridad con CI: worker Linux dedicado actual si es capaz; de lo contrario, $crabbox.
• Falla en CI: SHA exacto, solo el trabajo relevante; logs solo después de falla/completado.

Hábito de Salida

Reporta:

• frontera probada
• comando/env exacto, censurado
• señal observada, p. ej., nombres de herramientas o tiempo del primer evento SSE
• ubicación de la corrección
• prueba estrecha + riesgo restante