Solución de problemas

• model_not_found con un servidor local de estilo MLX/vLLM → verifica que baseUrl incluya /v1, que api sea "openai-completions" para backends /v1/chat/completions, y que models.providers.<provider>.models[].id sea el id local del proveedor sin prefijo. Selecciónalo con el prefijo del proveedor una vez, por ejemplo mlx/mlx-community/Qwen3-30B-A3B-6bit; mantén la entrada del catálogo como mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → el backend rechaza partes de contenido estructurado de Chat Completions. Corrección: establece models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → el backend completó la solicitud de Chat Completions pero no devolvió texto de asistente visible para el usuario en ese turno. OpenClaw reintenta una vez los turnos vacíos compatibles con OpenAI que son seguros de reproducir; los fallos persistentes normalmente significan que el backend está emitiendo contenido vacío/no textual o suprimiendo texto de respuesta final.
• las solicitudes directas pequeñas tienen éxito, pero las ejecuciones del agente de OpenClaw fallan con cierres inesperados del backend/modelo (por ejemplo Gemma en algunas compilaciones de inferrs) → es probable que el transporte de OpenClaw ya sea correcto; el backend está fallando con la forma de prompt más grande del runtime del agente.
• los fallos disminuyen después de desactivar herramientas pero no desaparecen → los esquemas de herramientas eran parte de la presión, pero el problema restante sigue siendo capacidad del modelo/servidor upstream o un error del backend.

1. Establece compat.requiresStringContent: true para backends de Chat Completions que solo aceptan cadenas.
2. Establece compat.supportsTools: false para modelos/backends que no pueden manejar de forma fiable la superficie de esquemas de herramientas de OpenClaw.
3. Reduce la presión del prompt donde sea posible: arranque de espacio de trabajo más pequeño, historial de sesión más corto, modelo local más ligero o un backend con soporte de contexto largo más sólido.
4. Si las solicitudes directas pequeñas siguen pasando mientras los turnos del agente de OpenClaw aún fallan dentro del backend, trátalo como una limitación del servidor/modelo upstream y abre una reproducción allí con la forma de payload aceptada.

• device identity required → contexto no seguro o falta autenticación de dispositivo.
• origin not allowed → el Origin del navegador no está en gateway.controlUi.allowedOrigins (o te estás conectando desde un origen de navegador que no es de loopback sin una lista de permitidos explícita).
• device nonce required / device nonce mismatch → el cliente no está completando el flujo de autenticación de dispositivo basado en desafío (connect.challenge + device.nonce).
• device signature invalid / device signature expired → el cliente firmó el payload incorrecto (o una marca de tiempo obsoleta) para el handshake actual.
• AUTH_TOKEN_MISMATCH con canRetryWithDeviceToken=true → el cliente puede hacer un reintento confiable con el token de dispositivo en caché.
• Ese reintento con token en caché reutiliza el conjunto de alcances en caché almacenado con el token de dispositivo emparejado. Los llamadores con deviceToken explícito / scopes explícitos mantienen en cambio su conjunto de alcances solicitado.
• Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es primero token/contraseña compartidos explícitos, luego deviceToken explícito, luego token de dispositivo almacenado, luego token de arranque.
• En la ruta asíncrona de Tailscale Serve Control UI, los intentos fallidos para el mismo {scope, ip} se serializan antes de que el limitador registre el fallo. Por lo tanto, dos reintentos incorrectos concurrentes del mismo cliente pueden mostrar retry later en el segundo intento en lugar de dos simples desajustes.
• too many failed authentication attempts (retry later) desde un cliente de navegador-origin loopback → los fallos repetidos desde ese mismo Origin normalizado quedan bloqueados temporalmente; otro origen localhost usa un bucket separado.
• unauthorized repetido después de ese reintento → deriva entre token compartido/token de dispositivo; actualiza la configuración del token y vuelve a aprobar/rotar el token de dispositivo si es necesario.
• gateway connect failed: → destino de host/puerto/url incorrecto.

• Gateway start blocked: set gateway.mode=local o existing config is missing gateway.mode → el modo de Gateway local no está habilitado, o el archivo de configuración fue sobrescrito y perdió gateway.mode. Solución: configura gateway.mode="local" en tu configuración, o vuelve a ejecutar openclaw onboard --mode local / openclaw setup para volver a sellar la configuración esperada de modo local. Si ejecutas OpenClaw mediante Podman, la ruta de configuración predeterminada es ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → enlace que no es loopback sin una ruta válida de autenticación del Gateway (token/contraseña, o proxy de confianza cuando esté configurado).
• another gateway instance is already listening / EADDRINUSE → conflicto de puerto.
• Other gateway-like services detected (best effort) → existen unidades launchd/systemd/schtasks obsoletas o paralelas. La mayoría de las configuraciones deberían mantener un Gateway por máquina; si necesitas más de uno, aísla puertos + configuración/estado/espacio de trabajo. Consulta /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected desde doctor → existe una unidad de sistema systemd mientras falta el servicio de nivel de usuario. Elimina o deshabilita el duplicado antes de permitir que doctor instale un servicio de usuario, o configura OPENCLAW_SERVICE_REPAIR_POLICY=external si la unidad de sistema es el supervisor previsto.
• Gateway service port does not match current gateway config → el supervisor instalado todavía fija el --port anterior. Ejecuta openclaw doctor --fix o openclaw gateway install --force y luego reinicia el servicio Gateway.

• La configuración no validó durante el inicio, la recarga en caliente o una escritura propiedad de OpenClaw.
• El inicio del Gateway falla de forma cerrada en lugar de reescribir openclaw.json.
• La recarga en caliente omite ediciones externas no válidas y mantiene activa la configuración de runtime actual.
• Las escrituras propiedad de OpenClaw rechazan cargas no válidas/destructivas antes de confirmar y guardan .rejected.*.
• openclaw doctor --fix se encarga de la reparación. Puede eliminar prefijos que no sean JSON o restaurar la última copia buena conocida mientras preserva la carga rechazada como .clobbered.*.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* existe → doctor preservó una edición externa dañada mientras reparaba la configuración activa.
• .rejected.* existe → una escritura de configuración propiedad de OpenClaw falló en las comprobaciones de esquema o sobrescritura antes de confirmar.
• Config write rejected: → la escritura intentó eliminar la forma requerida, reducir bruscamente el archivo o persistir una configuración no válida.
• config reload skipped (invalid config): → una edición directa falló la validación y fue ignorada por el Gateway en ejecución.
• Invalid config at ... → el inicio falló antes de que arrancaran los servicios del Gateway.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good o size-drop-vs-last-good:* → una escritura propiedad de OpenClaw fue rechazada porque perdió campos o tamaño en comparación con la copia de seguridad de última versión buena conocida.
• Config last-known-good promotion skipped → el candidato contenía marcadores de posición de secretos redactados como ***.

1. Ejecuta openclaw doctor --fix para permitir que doctor repare configuración con prefijo/sobrescrita o restaure la última versión buena conocida.
2. Copia solo las claves previstas desde .clobbered.* o .rejected.* y luego aplícalas con openclaw config set o config.patch.
3. Ejecuta openclaw config validate antes de reiniciar.
4. Si editas a mano, conserva la configuración JSON5 completa, no solo el objeto parcial que querías cambiar.

• cron: scheduler disabled; jobs will not run automatically → cron deshabilitado.
• cron: timer tick failed → falló el tick del programador; revisa errores de archivo/registro/tiempo de ejecución.
• heartbeat skipped con reason=quiet-hours → fuera de la ventana de horas activas.
• heartbeat skipped con reason=empty-heartbeat-file → HEARTBEAT.md existe, pero solo contiene líneas en blanco / encabezados de markdown, por lo que OpenClaw omite la llamada al modelo.
• heartbeat skipped con reason=no-tasks-due → HEARTBEAT.md contiene un bloque tasks:, pero ninguna tarea vence en este tick.
• heartbeat: unknown accountId → id de cuenta no válido para el destino de entrega de heartbeat.
• heartbeat skipped con reason=dm-blocked → el destino de heartbeat se resolvió como destino tipo DM mientras agents.defaults.heartbeat.directPolicy (o la anulación por agente) está configurado en block.

• unknown command "browser" o unknown command 'browser' → el plugin de navegador incluido está excluido por plugins.allow.
• herramienta de navegador faltante / no disponible mientras browser.enabled=true → plugins.allow excluye browser, por lo que el plugin nunca se cargó.
• Failed to start Chrome CDP on port → no se pudo iniciar el proceso del navegador.
• browser.executablePath not found → la ruta configurada no es válida.
• browser.cdpUrl must be http(s) or ws(s) → la URL CDP configurada usa un esquema no compatible, como file: o ftp:.
• browser.cdpUrl has invalid port → la URL CDP configurada tiene un puerto incorrecto o fuera de rango.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → la instalación actual del Gateway no tiene la dependencia principal de tiempo de ejecución del navegador; reinstala o actualiza OpenClaw y luego reinicia el Gateway. Las instantáneas ARIA y las capturas básicas de página aún pueden funcionar, pero la navegación, las instantáneas de IA, las capturas de elementos con selector CSS y la exportación a PDF permanecen no disponibles.

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session aún no pudo adjuntarse al directorio de datos del navegador seleccionado. Abre la página de inspección del navegador, habilita la depuración remota, mantén el navegador abierto, aprueba el primer aviso de adjuntar y vuelve a intentarlo. Si no se requiere el estado de sesión iniciada, prefiere el perfil administrado openclaw.
• No Chrome tabs found for profile="user" → el perfil de adjuntar de Chrome MCP no tiene pestañas locales de Chrome abiertas.
• Remote CDP for profile "<name>" is not reachable → el endpoint CDP remoto configurado no es alcanzable desde el host del Gateway.
• Browser attachOnly is enabled ... not reachable o Browser attachOnly is enabled and CDP websocket ... is not reachable → el perfil de solo adjuntar no tiene un destino alcanzable, o el endpoint HTTP respondió pero aún no se pudo abrir el WebSocket CDP.

• fullPage is not supported for element screenshots → la solicitud de captura mezcló --full-page con --ref o --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → las llamadas de captura de Chrome MCP / existing-session deben usar captura de página o un --ref de instantánea, no --element CSS.
• existing-session file uploads do not support element selectors; use ref/inputRef. → los hooks de carga de Chrome MCP necesitan refs de instantánea, no selectores CSS.
• existing-session file uploads currently support one file at a time. → envía una carga por llamada en perfiles Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → los hooks de diálogo en perfiles Chrome MCP no admiten anulaciones de timeout.
• existing-session type does not support timeoutMs overrides. → omite timeoutMs para act:type en perfiles profile="user" / Chrome MCP existing-session, o usa un perfil de navegador administrado/CDP cuando se requiera un timeout personalizado.
• existing-session evaluate does not support timeoutMs overrides. → omite timeoutMs para act:evaluate en perfiles profile="user" / Chrome MCP existing-session, o usa un perfil de navegador administrado/CDP cuando se requiera un timeout personalizado.
• response body is not supported for existing-session profiles yet. → responsebody aún requiere un navegador administrado o un perfil CDP sin procesar.
• anulaciones obsoletas de viewport / modo oscuro / configuración regional / sin conexión en perfiles de solo adjuntar o CDP remoto → ejecuta openclaw browser stop --browser-profile <name> para cerrar la sesión de control activa y liberar el estado de emulación de Playwright/CDP sin reiniciar todo el Gateway.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Qué revisar:

• Si gateway.mode=remote, las llamadas de la CLI pueden estar apuntando al remoto mientras tu servicio local está bien.
• Las llamadas explícitas con --url no recurren a credenciales almacenadas.

Firmas comunes:

• gateway connect failed: → destino de URL incorrecto.
• unauthorized → endpoint alcanzable, pero autenticación incorrecta.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Qué revisar:

• Los enlaces que no sean local loopback (lan, tailnet, custom) necesitan una ruta de autenticación válida del Gateway: autenticación con token/contraseña compartida, o un despliegue trusted-proxy no local loopback configurado correctamente.
• Las claves antiguas como gateway.token no reemplazan a gateway.auth.token.

Firmas comunes:

• refusing to bind gateway ... without auth → enlace no local loopback sin una ruta de autenticación válida del Gateway.
• Connectivity probe: failed mientras el tiempo de ejecución está en marcha → Gateway activo pero inaccesible con la autenticación/URL actual.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Qué revisar:

• Aprobaciones de dispositivo pendientes para panel/nodes.
• Aprobaciones de emparejamiento de DM pendientes después de cambios de política o identidad.

Firmas comunes:

• device identity required → autenticación de dispositivo no satisfecha.
• pairing required → el remitente/dispositivo debe ser aprobado.