Resolución de problemas del gateway de OpenClaw

Cuando la página de triaje rápido no basta, la documentación te envía al runbook detallado del gateway. Es un índice más que un muro de soluciones: una escalera de comandos, las señales que muestra un gateway en buen estado y seis páginas por área de síntoma con anclajes estables. Su sección más útil es la breve lista de cosas que se rompen justo después de una actualización. Este es el mapa.

La escalera y las seis páginas

• Ejecuta, en este orden, los comandos status, gateway status, de seguimiento de logs, doctor y de sonda de canales; en buen estado significa que gateway status muestra un runtime en ejecución, una sonda de conectividad en ok y una línea de capacidades, que doctor no informa de ningún problema bloqueante de configuración ni de servicio, y que la sonda muestra el estado del transporte en vivo por cuenta, con un marcador works o audit ok donde es compatible.
• Actualizaciones y reversiones cubre un gateway que queda caído o desajustado tras una actualización, una bajada de versión o una instalación split-brain: después de una actualización, el tiempo de espera de publicación del runtime de modelo preparado, la protección contra configuraciones más recientes, corregir la ruta de búsqueda, reinstalar el servicio, eliminar wrappers obsoletos y una discrepancia de protocolo tras una reversión. Skills y proveedores de modelos cubre una raíz de skills omitida, el error de límite de tasa para contexto largo con sus soluciones de ventana estándar, credencial apta y modelo de respaldo, las respuestas bloqueadas en origen y un backend local compatible con OpenAI que supera las sondas pero falla en las ejecuciones del agente.
• Respuestas del agente e interfaz de control cubre una ejecución que falla con un error de almacenamiento, respuestas que no llegan, la conectividad del panel, las firmas de conexión y autenticación con un mapa rápido de los códigos de detalle de autenticación, y los pasos del desafío de conexión, la firma del payload y el nonce del dispositivo. Servicio y proceso del gateway cubre un servicio que no arranca o no se mantiene en marcha, un gateway de macOS que se detiene en silencio hasta que se toca el panel, un bucle del supervisor con launch agents duplicados y una salida por uso elevado de memoria.
• Validación de configuración y sondas cubre una configuración no válida rechazada, qué ocurrió, inspeccionar y reparar, sus firmas habituales y opciones de solución, y los avisos de la sonda del gateway. Entrega de canales y herramientas cubre un canal conectado por el que no fluyen los mensajes, la entrega programada y de heartbeat, un nodo emparejado cuya herramienta falla, los fallos de la herramienta de navegador, las firmas de plugins y ejecutables, las firmas de sesión del navegador y las de elementos, capturas de pantalla y subidas; todos los anclajes antiguos de la página única siguen resolviendo a su nueva ubicación.

La mayoría de las roturas tras una actualización son desviaciones de configuración o valores predeterminados más estrictos que ahora se aplican.

Si actualizaste y algo se rompió

El índice mantiene tres comprobaciones en la propia página. Primero, el comportamiento de la autenticación y de las sobrescrituras de URL: lee el modo del gateway, la URL remota y el modo de autenticación, porque con el modo en remote la línea de comandos puede estar apuntando a un gateway remoto mientras el servicio local funciona bien, y las llamadas con URL explícita no recurren a las credenciales guardadas; una firma connect-failed significa un destino de URL equivocado, y una firma unauthorized significa que el endpoint es accesible, pero con la autenticación equivocada. Segundo, las protecciones de enlace y autenticación son más estrictas: los enlaces fuera de loopback necesitan una vía de autenticación válida, un token o contraseña compartidos o un proxy de confianza fuera de loopback correctamente configurado, y la antigua clave de token no sustituye a la clave actual del token de autenticación; las firmas son la negativa a enlazar sin autenticación y una sonda de conectividad fallida con el runtime en ejecución. Tercero, el estado del emparejamiento y de la identidad del dispositivo: lista los dispositivos y los emparejamientos de canal y busca aprobaciones de dispositivo pendientes para el panel o los nodos, y aprobaciones pendientes tras un cambio de política o de identidad; las firmas son device identity required y pairing required. Si la configuración del servicio y el runtime siguen sin coincidir, reinstala los metadatos del servicio desde el mismo perfil y directorio de estado y reinicia.

Leer las señales

• Un runtime en ejecución con una sonda de conectividad fallida es la combinación más reveladora: el proceso está vivo, pero la línea de comandos no puede alcanzarlo con su URL y su autenticación actuales, así que la solución está en el modo, la URL o el token, no en el servicio.
• Una firma device identity required después de una actualización no es un error del cliente; la autenticación de dispositivos ahora se aplica y el panel o el nodo necesita su aprobación pendiente, que muestran las listas de dispositivos y de emparejamiento.
• La sonda es por cuenta: un canal con dos cuentas puede mostrar un transporte que funciona y otro que falla, algo que la línea de estado por sí sola no revela.

La resolución de problemas de canales de OpenClaw es la guía complementaria a nivel de canal para el caso en que el transporte se conecta pero el comportamiento es incorrecto, y OpenClaw doctor explica el comando de reparación en el que se apoya la escalera.

Por qué un índice

Dividir el runbook por áreas de síntoma mantiene cada página lo bastante corta como para leerla mientras algo está caído, y los anclajes conservados hacen que los enlaces de hilos e incidencias antiguos sigan llevando a la sección correcta. El orden de la escalera también es deliberado: va de la señal más amplia a la más concreta, y doctor va antes de la sonda porque repara las configuraciones erróneas que, de lo contrario, la sonda notificaría como fallos. El emparejamiento en OpenClaw cubre las aprobaciones que busca la tercera comprobación y la configuración de OpenClaw, las claves que leen las dos primeras.

En Diali

En Diali, la configuración del runtime se genera desde el panel y se reemplaza en cada versión, lo que elimina la mayor parte de la desviación que describe la sección sobre las actualizaciones, y la misma escalera funciona en el runtime alojado. OpenClaw alojado en Diali describe el asistente alojado y la seguridad en Diali, el límite que lo rodea.

• Cinco comandos en orden; runtime en ejecución más sonda en ok es buen estado.
• Seis páginas de síntomas; todos los anclajes antiguos siguen resolviendo.
• Tras una actualización: modo y URL, enlace y autenticación, estado del emparejamiento.