Solución de problemas del Gateway

Esta página es la guía avanzada de solución de problemas. Comienza en /help/troubleshooting si prefieres el flujo de triaje rápido primero.

Escalera de comandos

Ejecuta estos primero, en este orden:

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

Señales de salud esperadas:

openclaw gateway status muestra Runtime: running y RPC probe: ok.
openclaw doctor no reporta problemas bloqueantes de configuración/servicio.
openclaw channels status --probe muestra canales conectados/listos.

Anthropic 429 se requiere uso adicional para contexto largo

Usa esto cuando los logs/errores incluyen: 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:

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

Opciones de solución:

Deshabilita context1m para ese modelo para recurrir a la ventana de contexto normal.
Usa una clave API de Anthropic con facturación, o habilita Anthropic Extra Usage en la cuenta de suscripción.
Configura modelos de respaldo para que las ejecuciones continúen cuando las solicitudes de contexto largo de Anthropic sean rechazadas.

Relacionado:

Sin respuestas

Si los canales están arriba 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:

Emparejamiento pendiente para remitentes de DM.
Control de menciones en grupos (requireMention, mentionPatterns).
Discrepancias en listas de permitidos de canal/grupo.

Firmas comunes:

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

Relacionado:

Conectividad del dashboard / UI de control

Cuando el dashboard/UI de control no se conecta, valida URL, modo de autenticación y suposiciones de contexto seguro.

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

Busca:

URL correcta de probe y dashboard.
Discrepancia de modo/token de autenticación entre cliente y gateway.
Uso de HTTP donde se requiere identidad de dispositivo.

Firmas comunes:

device identity required -> contexto no seguro o autenticación de dispositivo faltante.
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 marca de tiempo obsoleta) para el handshake actual.
AUTH_TOKEN_MISMATCH con canRetryWithDeviceToken=true -> el cliente puede hacer un reintento de confianza con token de dispositivo en caché.
unauthorized repetido después de ese reintento -> desfase de token compartido/token de dispositivo; actualiza la configuración del token y re-aprueba/rota el token de dispositivo si es necesario.
gateway connect failed: -> host/puerto/url de destino incorrecto.

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

Usa error.details.code de la respuesta fallida de connect 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 reintenta. Para rutas de dashboard: `openclaw config get gateway.auth.token` luego pega en los ajustes de la UI de control.
`AUTH_TOKEN_MISMATCH`	El token compartido no coincidió con el token de autenticación del gateway.	Si `canRetryWithDeviceToken=true`, permite un reintento de confianza. Si sigue fallando, ejecuta la lista de verificación de recuperación de desfase de token.
`AUTH_DEVICE_TOKEN_MISMATCH`	El token de dispositivo en caché está obsoleto o revocado.	Rota/re-aprueba el token de dispositivo usando CLI de devices, luego reconecta.
`PAIRING_REQUIRED`	La identidad del dispositivo es conocida pero no aprobada para este rol.	Aprueba la solicitud pendiente: `openclaw devices list` luego `openclaw devices approve <requestId>`.

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

openclaw --version
openclaw doctor
openclaw gateway status

Si los logs muestran errores de nonce/firma, actualiza el cliente que se conecta y verifica que:

espera connect.challenge
firma el payload vinculado al desafío
envía connect.params.device.nonce con el mismo nonce del desafío

Relacionado:

El servicio del Gateway no se ejecuta

Usa esto cuando el servicio está instalado pero el proceso no se mantiene activo.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

Busca:

Runtime: stopped con indicaciones de salida.
Discrepancia en la configuración del servicio (Config (cli) vs Config (service)).
Conflictos de puerto/listener.

Firmas comunes:

Gateway start blocked: set gateway.mode=local -> el modo de gateway local no está habilitado. Solución: establece gateway.mode="local" en tu configuración (o ejecuta openclaw configure). Si estás ejecutando OpenClaw vía Podman usando el usuario dedicado openclaw, la configuración está en ~openclaw/.openclaw/openclaw.json.
refusing to bind gateway ... without auth -> enlace no-loopback sin token/password.
another gateway instance is already listening / EADDRINUSE -> conflicto de puerto.

Relacionado:

Canal conectado pero los mensajes no fluyen

Si el estado del canal es conectado pero el flujo de mensajes está muerto, enfócate en la política, permisos y reglas de entrega específicas del canal.

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

Busca:

Política de DM (pairing, allowlist, open, disabled).
Lista de permitidos de grupo y requisitos de mención.
Permisos/alcances faltantes en la API del canal.

Firmas comunes:

mention required -> mensaje ignorado por la política de mención del grupo.
pairing / trazas de aprobación pendiente -> el remitente no está aprobado.
missing_scope, not_in_channel, Forbidden, 401/403 -> problema de autenticación/permisos del canal.

Relacionado:

Entrega de cron y heartbeat

Si el cron o heartbeat no se ejecutó o no entregó, verifica primero el estado del programador, luego el destino de entrega.

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

Busca:

Cron habilitado y siguiente despertar presente.
Historial de ejecución del job (ok, skipped, error).
Razones de omisión del heartbeat (quiet-hours, requests-in-flight, alerts-disabled).

Firmas comunes:

cron: scheduler disabled; jobs will not run automatically -> cron deshabilitado.
cron: timer tick failed -> tick del programador falló; verifica errores de archivo/log/runtime.
heartbeat skipped con reason=quiet-hours -> fuera de la ventana de horas activas.
heartbeat: unknown accountId -> id de cuenta inválido para el destino de entrega del heartbeat.
heartbeat skipped con reason=dm-blocked -> el destino del heartbeat se resolvió a un destino tipo DM mientras agents.defaults.heartbeat.directPolicy (o sobrescritura por agente) está establecido en block.

Relacionado:

Herramienta de nodo emparejado falla

Si un nodo está emparejado pero las herramientas fallan, aísla el estado de foreground, permisos y aprobaciones.

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

Busca:

Nodo online con las capacidades esperadas.
Permisos del SO concedidos para cámara/micrófono/ubicación/pantalla.
Estado de aprobaciones de ejecución y lista de permitidos.

Firmas comunes:

NODE_BACKGROUND_UNAVAILABLE -> la app del nodo debe estar en foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED -> permiso del SO faltante.
SYSTEM_RUN_DENIED: approval required -> aprobación de ejecución pendiente.
SYSTEM_RUN_DENIED: allowlist miss -> comando bloqueado por la lista de permitidos.

Relacionado:

Herramienta de navegador falla

Usa esto cuando las acciones de la herramienta de navegador fallan aunque el gateway esté saludable.

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

Busca:

Ruta válida del ejecutable del navegador.
Alcanzabilidad del perfil CDP.
Conexión de la pestaña del relay de extensión para profile="chrome".

Firmas comunes:

Failed to start Chrome CDP on port -> el proceso del navegador falló al iniciarse.
browser.executablePath not found -> la ruta configurada es inválida.
Chrome extension relay is running, but no tab is connected -> relay de extensión no conectado.
Browser attachOnly is enabled ... not reachable -> el perfil attach-only no tiene un objetivo alcanzable.

Relacionado:

Si actualizaste y algo se rompió repentinamente

La mayoría de las roturas post-actualización son desfase de configuración o valores por defecto más estrictos que ahora se aplican.

1) El comportamiento de autenticación y sobrescritura 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 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: -> URL de destino incorrecta.
unauthorized -> endpoint alcanzable 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.token
openclaw gateway status
openclaw logs --follow

Qué verificar:

Los enlaces no-loopback (lan, tailnet, custom) necesitan autenticación configurada.
Las claves antiguas como gateway.token no reemplazan a gateway.auth.token.

Firmas comunes:

refusing to bind gateway ... without auth -> discrepancia de enlace+autenticación.
RPC probe: failed mientras el runtime está ejecutándose -> gateway activo pero inaccesible con la autenticación/url actual.

3) El estado de emparejamiento e identidad de dispositivo cambió

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

Qué verificar:

Aprobaciones de dispositivos pendientes para dashboard/nodos.
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 -> remitente/dispositivo debe ser aprobado.

Si la configuración del servicio y el runtime siguen en desacuerdo después de las verificaciones, reinstala los metadatos del servicio desde el mismo perfil/directorio de estado:

openclaw gateway install --force
openclaw gateway restart

Relacionado: