Saltar al contenido principal

​
Solución de problemas del Gateway

Esta página es el runbook en profundidad. Comience en /help/troubleshooting si primero desea el flujo de triaje rápido.

​
Escalera de comandos

Ejecute estos primero, en este orden: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Señales esperadas de estado saludable:
  • openclaw gateway status muestra Runtime: running y RPC probe: ok.
  • openclaw doctor informa que no hay problemas de configuración/servicio que bloqueen.
  • openclaw channels status --probe muestra canales conectados/listos.

​
Sin respuestas

Si los canales están activos pero nada responde, verifique el enrutamiento y la política antes de reconectar nada. 
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow
Busque:
  • Emparejamiento pendiente para los remitentes DM.
  • Restricción de menciones en grupos (requireMention, mentionPatterns).
  • Desajustes en la lista de permitidos de canal/grupo.
Firmas comunes:
  • drop guild message (mention required → mensaje de grupo ignorado hasta que haya una mención.
  • pairing request → el remitente necesita aprobación.
  • blocked / allowlist → el remitente/canal fue filtrado por la política.
Relacionado:

​
Conectividad de la UI de control del panel

Cuando el panel o la UI de control no se conectan, valide la URL, el modo de autenticación y los supuestos de contexto seguro. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
Busque:
  • URL de sonda y URL del panel correctas.
  • Desajuste de modo/token de autenticación entre el cliente y el gateway.
  • Uso de HTTP donde se requiere identidad del dispositivo.
Firmas comunes:
  • device identity required → contexto no seguro o falta autenticación del dispositivo.
  • unauthorized / bucle de reconexión → desajuste de token/contraseña.
  • gateway connect failed: → destino de host/puerto/url incorrecto.
Relacionado:

​
El servicio del Gateway no se está ejecutando

Use 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
Busque:
  • Runtime: stopped con pistas de salida.
  • Desajuste de configuración del servicio (Config (cli) vs Config (service)).
  • Conflictos de puertos/escuchas.
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 mediante Podman usando el usuario dedicado openclaw, la configuración se encuentra en ~openclaw/.openclaw/openclaw.json.
  • refusing to bind gateway ... without auth → enlace no loopback sin token/contraseña.
  • another gateway instance is already listening / EADDRINUSE → conflicto de puertos.
Relacionado:

​
Canal conectado pero los mensajes no fluyen

Si el estado del canal es conectado pero el flujo de mensajes está inactivo, concéntrese en la política, los permisos y las reglas de entrega específicas del canal. 
openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels
Busque:
  • Política de mensajes directos (pairing, allowlist, open, disabled).
  • Lista de permitidos de grupos y requisitos de mención.
  • Permisos/alcances de API del canal faltantes.
Firmas comunes:
  • mention required → mensaje ignorado por la política de mención de 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 cron o heartbeat no se ejecutaron o no entregaron, verifique primero el estado del programador y 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
Busque:
  • Cron habilitado y próxima activación presente.
  • Estado del historial de ejecución de trabajos (ok, skipped, error).
  • Razones de omisión de heartbeat (quiet-hours, requests-in-flight, alerts-disabled).
Firmas comunes:
  • cron: scheduler disabled; jobs will not run automatically → cron deshabilitado.
  • cron: timer tick failed → fallo del tick del programador; revise 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 de heartbeat.
Relacionado:

​
Falla la herramienta de un nodo emparejado

Si un nodo está emparejado pero las herramientas fallan, aísle el estado de primer plano, permisos y aprobación. 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
Busque:
  • Nodo en línea con las capacidades esperadas.
  • Concesiones de permisos del SO para cámara/micrófono/ubicación/pantalla.
  • Aprobaciones de exec y estado de la lista de permitidos.
Firmas comunes:
  • NODE_BACKGROUND_UNAVAILABLE → la app del nodo debe estar en primer plano.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → falta permiso del SO.
  • SYSTEM_RUN_DENIED: approval required → aprobación de exec pendiente.
  • SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado por la lista de permitidos.
Relacionado:

​
Falla la herramienta de navegador

Use esto cuando las acciones de la herramienta de navegador fallan aunque el gateway en sí esté saludable. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
Busque:
  • Ruta válida del ejecutable del navegador.
  • Alcanzabilidad del perfil CDP.
  • Adjunción de la pestaña de retransmisión de la extensión para profile="chrome".
Firmas comunes:
  • Failed to start Chrome CDP on port → el proceso del navegador no se pudo iniciar.
  • browser.executablePath not found → la ruta configurada es inválida.
  • Chrome extension relay is running, but no tab is connected → la retransmisión de la extensión no está adjunta.
  • Browser attachOnly is enabled ... not reachable → el perfil de solo adjuntar no tiene un destino alcanzable.
Relacionado:

​
Si actualizó y algo se rompió de repente

La mayoría de las fallas posteriores a una actualización son deriva de configuración o valores predeterminados más estrictos que ahora se están aplicando.

​
1. Cambió el comportamiento de autenticación y anulación de URL

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 pueden estar apuntando a remoto mientras su servicio local está bien.
  • Las llamadas explícitas --url no recurren a credenciales almacenadas.
Firmas comunes:
  • gateway connect failed: → destino de URL incorrecto.
  • unauthorized → endpoint alcanzable pero autenticación incorrecta.

​
2. Los guardarraíles de enlace y autenticación son más estrictos

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
Qué verificar:
  • Enlaces no loopback (lan, tailnet, custom) requieren autenticación configurada.
  • Claves antiguas como gateway.token no reemplazan gateway.auth.token.
Firmas comunes:
  • refusing to bind gateway ... without auth → desajuste entre enlace y autenticación.
  • RPC probe: failed mientras el runtime está en ejecución → gateway activo pero inaccesible con la autenticación/url actual.

​
3. Cambió el estado de emparejamiento e identidad del dispositivo

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor
Qué verificar:
  • Aprobaciones de dispositivos pendientes para el panel/nodos.
  • Aprobaciones de emparejamiento de mensajes directos pendientes después de cambios de política o identidad.
Firmas comunes:
  • device identity required → la autenticación del dispositivo no está satisfecha.
  • pairing required → el remitente/dispositivo debe ser aprobado.
Si la configuración del servicio y el runtime aún discrepan después de las verificaciones, reinstale los metadatos del servicio desde el mismo directorio de perfil/estado: 
openclaw gateway install --force
openclaw gateway restart
Relacionado: