Solución de problemas del Gateway en OpenClaw

Solución de problemas del Gateway

Esta página es el manual de operaciones detallado. Comienza en /help/troubleshooting si prefieres seguir el flujo de triaje rápido primero.

Escalera de comandos

Ejecuta estos comandos primero, en este orden, para verificar el estado de tu OpenClaw Gateway:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Señales de un sistema saludable:

openclaw gateway status muestra Runtime: running, Connectivity probe: ok y una línea de Capability: ....
openclaw doctor no reporta problemas de configuración o de servicio que bloqueen el funcionamiento.
openclaw channels status --probe muestra el estado de transporte en vivo por cuenta y, donde sea compatible, resultados de pruebas o auditorías como works o audit ok.

Anthropic 429: uso adicional requerido para contexto largo

Utiliza este procedimiento cuando los logs o errores incluyan: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

Busca lo siguiente:

El modelo Anthropic Opus/Sonnet seleccionado tiene params.context1m: true.
La credencial actual de Anthropic no es elegible para el uso de contexto largo.
Las solicitudes fallan solo en sesiones largas o ejecuciones de modelos que necesitan la ruta beta de 1M.

Opciones de solución:

Desactiva context1m para ese modelo y así volver a la ventana de contexto normal.
Usa una credencial de Anthropic que sea elegible para solicitudes de contexto largo, o cambia a una API key de Anthropic.
Configura modelos de respaldo para que las ejecuciones continúen cuando las solicitudes de contexto largo de Anthropic sean rechazadas.

Relacionado:

El backend local compatible con OpenAI pasa las pruebas directas pero las ejecuciones del agente fallan

Usa este diagnóstico cuando las llamadas simples funcionan pero las tareas complejas de OpenClaw no:

curl ... /v1/models funciona.
Las llamadas directas pequeñas a /v1/chat/completions funcionan.
Las ejecuciones de modelos de OpenClaw fallan solo en turnos normales del agente.

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

Busca lo siguiente:

Las llamadas directas pequeñas tienen éxito, pero las ejecuciones de OpenClaw fallan solo con prompts más grandes.
Errores del backend sobre messages[].content esperando una cadena (string).
Fallos del backend que aparecen solo con conteos de tokens de prompt más grandes o prompts completos de tiempo de ejecución del agente.

Firmas comunes:

messages[...].content: invalid type: sequence, expected a string → El backend rechaza partes de contenido estructurado de Chat Completions. Solución: establece models.providers.<provider>.models[].compat.requiresStringContent: true.
Las solicitudes directas pequeñas tienen éxito, pero las ejecuciones del agente de OpenClaw fallan con bloqueos del backend/modelo (por ejemplo, Gemma en algunas compilaciones de inferrs) → El transporte de OpenClaw probablemente es correcto; el backend está fallando con la forma del prompt de tiempo de ejecución del agente más grande.
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 la capacidad del modelo/servidor upstream o un error del backend.

Opciones de solución:

Establece compat.requiresStringContent: true para backends de Chat Completions que solo aceptan cadenas.
Establece compat.supportsTools: false para modelos/backends que no pueden manejar la superficie del esquema de herramientas de OpenClaw de manera confiable.
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 mejor soporte de contexto largo.
Si las solicitudes directas pequeñas siguen pasando mientras los turnos del agente de OpenClaw siguen fallando dentro del backend, trátalo como una limitación del servidor/modelo upstream y presenta un reporte allí con la forma de carga útil aceptada.

Relacionado:

Sin respuestas

Si los canales están activos pero nada responde, verifica el enrutamiento y la política antes de reconectar cualquier cosa.

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

Busca lo siguiente:

Emparejamiento pendiente para remitentes de mensajes directos (DM).
Restricción de menciones en grupos (requireMention, mentionPatterns).
Desajustes en la lista de permitidos (allowlist) de canales/grupos.

Firmas comunes:

drop guild message (mention required → mensaje de grupo ignorado hasta que se mencione.
pairing request → el remitente necesita aprobación.
blocked / allowlist → el remitente/canal fue filtrado por política.

Relacionado:

AI Setup Assistant

Conectividad de la interfaz de control del Dashboard

Cuando la interfaz de control del Dashboard no logra conectarse, debes validar la URL, el modo de autenticación y las suposiciones sobre el contexto seguro.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Busca lo siguiente:

La URL de sondeo y la URL del Dashboard correctas.
Desajustes en el modo de autenticación o token entre el cliente y el Gateway.
Uso de HTTP cuando se requiere la identidad del dispositivo.

Firmas comunes:

device identity required → contexto no seguro o falta de autenticación del 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 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íos (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 realizar un reintento confiable con el token de dispositivo en caché.
Ese reintento con token en caché reutiliza el conjunto de alcances almacenado con el token de dispositivo vinculado. Las llamadas explícitas con deviceToken o scopes mantienen su conjunto de alcances solicitado.
Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es primero el token compartido/contraseña explícita, luego el deviceToken explícito, después el token de dispositivo almacenado y finalmente el token de arranque.
En la ruta asíncrona de la interfaz de control de Tailscale Serve, los intentos fallidos para el mismo {scope, ip} se serializan antes de que el limitador registre el fallo. Por lo tanto, dos reintentos concurrentes erróneos desde el mismo cliente pueden mostrar retry later en el segundo intento en lugar de dos errores de coincidencia simples.
too many failed authentication attempts (retry later) desde un cliente loopback de origen de navegador → los fallos repetidos desde el mismo Origin normalizado se bloquean temporalmente; otro origen localhost utiliza un bucket separado.
unauthorized repetido después de ese reintento → desviación del token compartido/token de dispositivo; actualiza la configuración del token y vuelve a aprobar o rotar el token de dispositivo si es necesario.
gateway connect failed: → objetivo de host/puerto/URL incorrecto.

Mapa rápido de códigos de detalle de autenticación

Usa error.details.code de la respuesta de connect fallida para elegir la siguiente acción:

Código de detalle	Significado	Acción recomendada
`AUTH_TOKEN_MISSING`	El cliente no envió un token compartido requerido.	Pega/configura el token en el cliente y vuelve a intentar. Para rutas de Dashboard: usa `openclaw config get gateway.auth.token` y luego pégalo en la configuración de la interfaz de control.
`AUTH_TOKEN_MISMATCH`	El token compartido no coincidió con el token de autenticación del Gateway.	Si `canRetryWithDeviceToken=true`, permite un reintento confiable. Los reintentos con token en caché reutilizan los alcances aprobados almacenados; las llamadas con `deviceToken` / `scopes` explícitos mantienen los alcances solicitados. Si sigue fallando, ejecuta la lista de verificación de recuperación de desviación de token.
`AUTH_DEVICE_TOKEN_MISMATCH`	El token por dispositivo en caché está obsoleto o revocado.	Rota/vuelve a aprobar el token de dispositivo usando la CLI de dispositivos, luego reconecta.
`PAIRING_REQUIRED`	La identidad del dispositivo necesita aprobación. Verifica `error.details.reason` para `not-paired`, `scope-upgrade`, `role-upgrade` o `metadata-upgrade`, y usa `requestId` / `remediationHint` cuando estén presentes.	Aprueba la solicitud pendiente: usa `openclaw devices list` y luego `openclaw devices approve <requestId>`. Las actualizaciones de alcance/rol usan el mismo flujo después de que revises el acceso solicitado.

Verificación de migración de autenticación de dispositivo v2:

openclaw --version
openclaw doctor
openclaw gateway status

Si los registros muestran errores de nonce/firma, actualiza el cliente que se está conectando y verifícalo:

Espera por connect.challenge
Firma el payload vinculado al desafío
Envía connect.params.device.nonce con el mismo nonce de desafío

Si openclaw devices rotate / revoke / remove es denegado inesperadamente:

Las sesiones de token de dispositivo vinculado solo pueden gestionar su propio dispositivo a menos que el llamador también tenga operator.admin.
openclaw devices rotate --scope ... solo puede solicitar alcances de operador que la sesión del llamador ya posea.

Relacionado:

/web/control-ui
/gateway/configuration (modos de autenticación del Gateway)
/gateway/trusted-proxy-auth
/gateway/remote
/cli/devices

El servicio Gateway no se está ejecutando

Utiliza esta sección cuando el servicio esté instalado pero el proceso no se mantenga activo.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

Busca lo siguiente:

Runtime: stopped con sugerencias de salida.
Desajuste en la configuración del servicio (Config (cli) vs Config (service)).
Conflictos de puerto/escucha.
Instalaciones adicionales de launchd/systemd/schtasks cuando se usa --deep.
Sugerencias de limpieza de Other gateway-like services detected (best effort).

Firmas comunes:

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: establece gateway.mode="local" en tu configuración, o vuelve a ejecutar openclaw onboard --mode local / openclaw setup para restablecer la configuración esperada del 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 de autenticación de Gateway válida (token/contraseña, o proxy confiable donde esté configurado).
another gateway instance is already listening / EADDRINUSE → conflicto de puerto.
Other gateway-like services detected (best effort) → existen unidades de launchd/systemd/schtasks obsoletas o paralelas. La mayoría de las configuraciones deben mantener un Gateway por máquina; si necesitas más de uno, aísla los puertos + configuración/estado/espacio de trabajo. Consulta /gateway#multiple-gateways-same-host.

Relacionado:

AI Setup Assistant

Gateway restauró la configuración válida anterior

Utiliza esta sección cuando el Gateway inicie, pero los registros indiquen que restauró el archivo openclaw.json.

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

Busca lo siguiente:

Config auto-restored from last-known-good
gateway: invalid config was restored from last-known-good backup
config reload restored last-known-good config after invalid-config
Un archivo openclaw.json.clobbered.* con marca de tiempo junto a la configuración activa
Un evento del sistema main-agent que comience con Config recovery warning

Lo que sucedió:

La configuración rechazada no pasó la validación durante el inicio o la recarga en caliente.
OpenClaw preservó el payload rechazado como .clobbered.*.
La configuración activa se restauró desde la última copia validada conocida como buena.
El siguiente turno del main-agent tiene una advertencia para no sobrescribir a ciegas la configuración rechazada.

Inspecciona y repara:

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

Firmas comunes:

.clobbered.* existe → se restauró una edición directa externa o una lectura de inicio.
.rejected.* existe → una escritura de configuración propiedad de OpenClaw falló en el esquema o en las comprobaciones de sobrescritura antes de confirmarse.
Config write rejected: → la escritura intentó eliminar una forma requerida, reducir el archivo drásticamente o persistir una configuración no válida.
Config last-known-good promotion skipped → el candidato contenía marcadores de posición de secretos redactados como ***.

Opciones de solución:

Mantén la configuración activa restaurada si es correcta.
Copia solo las claves deseadas desde .clobbered.* o .rejected.*, luego aplícalas con openclaw config set o config.patch.
Ejecuta openclaw config validate antes de reiniciar.
Si editas manualmente, mantén la configuración completa en formato JSON5, no solo el objeto parcial que querías cambiar.

Relacionado:

Advertencias de sonda del Gateway

Utiliza esta sección cuando openclaw gateway probe alcance un destino, pero aún así imprima un bloque de advertencia.

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

Busca lo siguiente:

warnings[].code y primaryTargetId en la salida JSON.
Si la advertencia trata sobre el respaldo SSH, múltiples Gateways, falta de alcances (scopes) o referencias de autenticación no resueltas.

Firmas comunes:

SSH tunnel failed to start; falling back to direct probes. → la configuración SSH falló, pero el comando aún intentó realizar pruebas directas a los destinos configurados o de loopback.
multiple reachable gateways detected → más de un destino respondió. Por lo general, esto significa una configuración intencional de múltiples Gateways o listeners obsoletos/duplicados.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la conexión funcionó, pero el RPC detallado está limitado por el alcance; vincula la identidad del dispositivo o usa credenciales con operator.read.
Capability: pairing-pending o gateway closed (1008): pairing required → el Gateway respondió, pero este cliente aún necesita vinculación/aprobación antes del acceso normal del operador.
Texto de advertencia de gateway.auth.* / gateway.remote.* SecretRef no resuelto → el material de autenticación no estaba disponible en esta ruta de comando para el destino fallido.

Relacionado:

Los mensajes de canales conectados no se envían

Si el estado del canal aparece como conectado pero el flujo de mensajes no funciona, céntrate en revisar las políticas, los permisos y las reglas de entrega específicas de cada canal. OpenClaw gestiona el flujo de mensajes de forma estricta, por lo que cualquier discrepancia en la configuración impedirá la comunicación.

Ejecuta los siguientes comandos para diagnosticar el estado de tu conexión:

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Revisa los siguientes puntos críticos en tu configuración:

Política de DM (pairing, allowlist, open, disabled).
Lista de permitidos para grupos y requisitos de mención.
Permisos o scopes de la API del canal que puedan faltar.

Identifica los errores comunes según estas firmas:

mention required → el mensaje es ignorado por la política de menciones del grupo.
pairing / rastros de aprobación pendiente → el remitente no está aprobado.
missing_scope, not_in_channel, Forbidden, 401/403 → problema de autenticación o permisos en el canal.

Relacionado:

Entrega de cron y heartbeat

Si el cron o el heartbeat no se ejecutaron o no se entregaron correctamente, verifica primero el estado del programador y luego el destino de la entrega. Es fundamental asegurar que el entorno de Node.js tenga acceso a los recursos programados.

Utiliza estos comandos para verificar el estado del sistema:

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Analiza los siguientes estados en tu configuración:

Cron habilitado y presencia del próximo ciclo de ejecución.
Historial de ejecución del trabajo (ok, skipped, error).
Razones por las que se omitió el heartbeat (quiet-hours, requests-in-flight, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Identifica las firmas comunes de error:

cron: scheduler disabled; jobs will not run automatically → el cron está desactivado.
cron: timer tick failed → el tick del programador falló; revisa errores de archivo, registro o tiempo de ejecución.
heartbeat skipped con reason=quiet-hours → fuera de la ventana de horas activas.
heartbeat skipped con reason=empty-heartbeat-file → el archivo HEARTBEAT.md existe pero solo contiene líneas en blanco o encabezados de JSON o 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 debe ejecutarse en este tick.
heartbeat: unknown accountId → id de cuenta no válido para el destino de entrega del heartbeat.
heartbeat skipped con reason=dm-blocked → el destino del heartbeat se resolvió como un destino tipo DM mientras que agents.defaults.heartbeat.directPolicy (o una anulación por agente) está configurado en block.

Relacionado:

AI Setup Assistant

El nodo emparejado falla al ejecutar herramientas

Si un nodo está emparejado pero las herramientas fallan, debes aislar el estado del primer plano, los permisos y la aprobación de ejecución.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Verifica lo siguiente:

El nodo está en línea con las capacidades esperadas.
Los permisos del sistema operativo para cámara, micrófono, ubicación o pantalla están concedidos.
El estado de las aprobaciones de ejecución y la lista de permitidos (allowlist).

Firmas de error comunes:

NODE_BACKGROUND_UNAVAILABLE → la aplicación del nodo debe estar en primer plano.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → falta un permiso del sistema operativo.
SYSTEM_RUN_DENIED: approval required → la aprobación de ejecución está pendiente.
SYSTEM_RUN_DENIED: allowlist miss → el comando está bloqueado por la lista de permitidos.

Relacionado:

La herramienta de navegador falla

Utiliza estos pasos cuando las acciones de la herramienta de navegador fallen, incluso si el Gateway funciona correctamente.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Verifica lo siguiente:

Si plugins.allow está configurado e incluye browser.
La ruta válida del ejecutable del navegador.
La accesibilidad del perfil CDP.
La disponibilidad de Chrome local para perfiles de tipo existing-session o user.

Firmas de error comunes:

unknown command "browser" o unknown command 'browser' → el plugin de navegador incluido está excluido por plugins.allow.
La herramienta de navegador falta o no está disponible mientras browser.enabled=true → plugins.allow excluye browser, por lo que el plugin nunca se cargó.
Failed to start Chrome CDP on port → el proceso del navegador no pudo iniciarse.
browser.executablePath not found → la ruta configurada no es válida.
browser.cdpUrl must be http(s) or ws(s) → la URL de CDP configurada usa un esquema no soportado como file: o ftp:.
browser.cdpUrl has invalid port → la URL de CDP configurada tiene un puerto incorrecto o fuera de rango.
No Chrome tabs found for profile="user" → el perfil de conexión de Chrome MCP no tiene pestañas de Chrome locales abiertas.
Remote CDP for profile "<name>" is not reachable → el endpoint de CDP remoto configurado no es accesible 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 conexión no tiene un objetivo accesible, o el endpoint HTTP respondió pero el WebSocket de CDP no pudo abrirse.
Playwright is not available in this gateway build; '<feature>' is unsupported. → la instalación actual del Gateway carece del paquete completo de Playwright; las instantáneas ARIA y las capturas de pantalla básicas de página pueden funcionar, pero la navegación, las instantáneas de IA, las capturas de elementos por selector CSS y la exportación a PDF no estarán disponibles.
fullPage is not supported for element screenshots → la solicitud de captura de pantalla 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 pantalla de Chrome MCP / existing-session deben usar captura de página o una --ref de instantánea, no un --element CSS.
existing-session file uploads do not support element selectors; use ref/inputRef. → los hooks de carga de archivos de Chrome MCP necesitan referencias de instantáneas, no selectores CSS.
existing-session file uploads currently support one file at a time. → envía una carga por llamada en perfiles de Chrome MCP.
existing-session dialog handling does not support timeoutMs. → los hooks de diálogo en perfiles de Chrome MCP no soportan anulaciones de tiempo de espera.
response body is not supported for existing-session profiles yet. → responsebody todavía requiere un navegador gestionado o un perfil CDP sin procesar.
Anulaciones obsoletas de viewport / modo oscuro / configuración regional / sin conexión en perfiles de solo conexión 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.

Relacionado:

Si actualizaste y algo dejó de funcionar repentinamente

La mayoría de los fallos tras una actualización se deben a una desviación en la configuración o a valores predeterminados más estrictos que ahora se aplican.

1) El comportamiento de autenticación y anulación de URL cambió

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

Qué verificar:

Si gateway.mode=remote, las llamadas de la CLI podrían estar dirigiéndose a un destino remoto mientras tu servicio local está bien.
Las llamadas explícitas con --url no recurren a las credenciales almacenadas.

Firmas de error comunes:

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

2) Las protecciones de enlace y autenticación son más estrictas

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

Qué verificar:

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

Firmas de error comunes:

refusing to bind gateway ... without auth → enlace que no es de loopback sin una ruta de autenticación de Gateway válida.
Connectivity probe: failed mientras el entorno de ejecución está activo → el Gateway está vivo pero inaccesible con la autenticación/URL actual.

3) El estado de emparejamiento y la identidad del dispositivo cambiaron

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

Qué verificar:

Aprobaciones de dispositivos pendientes para el panel de control o nodos.
Aprobaciones de emparejamiento de DM pendientes después de cambios en la política o la identidad.

Firmas de error comunes:

device identity required → la autenticación del dispositivo no se ha satisfecho.
pairing required → el remitente/dispositivo debe ser aprobado.

Si la configuración del servicio y el entorno de ejecución siguen sin coincidir después de las comprobaciones, reinstala los metadatos del servicio desde el mismo perfil o directorio de estado:

openclaw gateway install --force
openclaw gateway restart

Relacionado:

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.