Solución de problemas de OpenClaw en Zeabur

OpenClaw funciona perfectamente en Zeabur, hasta que de repente deja de hacerlo.

Esto no es una situación hipotética. En las últimas tres semanas, hemos gestionado más de 40 tickets de soporte relacionados con OpenClaw. Algunos problemas se pueden resolver por cuenta propia en cinco minutos; otros han dejado a los usuarios atascados durante días.

Este artículo recopila los problemas más comunes junto con soluciones extraídas de casos reales. La próxima vez que te encuentres con uno, no tendrás que esperar a que soporte te responda.

¿Qué estás viendo?

---

Aprende esto primero: Modo de rescate

No importa qué tipo de fallo estés enfrentando, este procedimiento casi siempre puede recuperar las cosas. Memorízalo: lo usarás repetidamente a lo largo de esta guía.

Versiones instaladas después del 2026/2/22 (con página de ayuda)

Cuando el Gateway se cae, al abrir la URL del servicio se mostrará automáticamente una página de ayuda con registros de errores y sugerencias de reparación.

1. Revisa los registros de errores en la página de ayuda (los registros completos están disponibles en la pestaña Registros del Zeabur Dashboard)
2. Ve a la pestaña Archivos del Zeabur Dashboard, busca /home/node/.openclaw/openclaw.json y corrige el problema
3. Haz clic en Reiniciar en el Zeabur Dashboard

Una vez que el servicio se recupere, la página de ayuda desaparecerá automáticamente.

Versiones instaladas antes del 2026/2/22 (sin página de ayuda)

Las versiones antiguas no tienen la página de ayuda, por lo que necesitarás entrar manualmente al contenedor para reparar.

1. Ve al Zeabur Dashboard y busca tu servicio de OpenClaw
2. Ve a la pestaña Registros para revisar los mensajes de error
3. Ve a Configuración > Comando, cambia el comando de inicio a sleep 3600, y luego Reinicia -- esto mantiene el contenedor en ejecución para que puedas entrar y arreglar las cosas
4. Ve a la pestaña Archivos, busca /home/node/.openclaw/openclaw.json y corrige el problema
5. Cambia el comando de inicio de vuelta a /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh, y luego Reinicia el servicio

¿Quieres habilitar la página de ayuda? Simplemente vuelve a desplegar desde la plantilla de OpenClaw.

---

Problema 1: El servicio se cae y se reinicia constantemente después de cambiar la configuración

Este es actualmente el problema más común, representando casi la mitad de todos los tickets de soporte.

Síntoma: El estado del servicio muestra CRASHED o CrashLoopBackOff, y los registros muestran errores como este:

Causa: El archivo de configuración contiene claves que OpenClaw no reconoce. Escenarios comunes: añadir campos inexistentes al editar manualmente, pedirle a OpenClaw que modifique la configuración pero la rompe, o campos de configuración antiguos que fueron descontinuados o renombrados tras una actualización de versión. El archivo de configuración se encuentra en almacenamiento persistente, y si encuentra una clave no reconocida, el servicio simplemente se niega a iniciar.

Solución:

Caso A: El servicio aún puede iniciar (los registros muestran el mensaje de Doctor)

Ve a la pestaña Comando y ejecuta openclaw doctor --fix -- esto eliminará automáticamente las claves no reconocidas.

Caso B: El servicio ya se ha caído y ni siquiera puedes abrir un shell

Este es el escenario más común. Usa el Modo de rescate descrito arriba para entrar al contenedor, abre /home/node/.openclaw/openclaw.json, elimina las claves listadas en los registros (por ejemplo, gateway.cool del ejemplo anterior), y luego reinicia el servicio.

---

Problema 2: El servicio se queda en "Iniciando", la sonda de inicio expira

Síntoma: El servicio sigue mostrando STARTING y nunca pasa a RUNNING. Los registros pueden mostrar:

Causa: OpenClaw requiere un tiempo de inicio relativamente largo (a veces más de 60 segundos), y la sonda de inicio predeterminada puede ser demasiado agresiva. Otra causa común es un archivo de configuración corrupto (igual que el Problema 1).

Solución:

1. Espera unos minutos para que se complete la inicialización
2. Si sigue fallando, revisa los registros en busca de errores relacionados con la configuración
3. Asegúrate de que la memoria sea de al menos 4GB
4. Si los registros muestran config invalid, usa el Modo de rescate para solucionarlo

---

Problema 3: Conectado a AI Hub pero el bot no responde

Síntoma: Envías un mensaje al bot de Telegram, muestra typing pero nunca responde, o directamente no reacciona.

Causa: Generalmente es un problema de configuración del API Key o un fallo en la conexión del modelo. El error más común que hemos visto es una discrepancia entre el Key y el Provider.

Solución:

1. Asegúrate de que las variables de entorno estén configuradas correctamente:

   • ZEABUR_AI_HUB_API_KEY -- al usar Zeabur AI Hub
   • ANTHROPIC_API_KEY -- al usar Claude directamente
   • OPENAI_API_KEY -- al usar OpenAI (también se usa para Memory Search y TTS)

2. Ve a la Web UI para verificar la configuración del modelo y asegúrate de que el modelo seleccionado coincida con tu API Key

3. Recuerda reiniciar el servicio después de configurar las variables de entorno -- de lo contrario, los cambios no tendrán efecto

Error común: Has configurado el Key de AI Hub pero OpenClaw intenta conectarse a Anthropic por defecto, lo que produce No API key found for provider "anthropic". Asegúrate de que la configuración del Provider coincida con tu Key.

---

Problema 4: Quiero cambiar de modelo pero no sé cómo configurarlo

Síntoma: El modelo predeterminado no es suficientemente bueno y quieres cambiar a Claude Sonnet u otro modelo.

Solución:

1. Abre la Web UI de OpenClaw (busca el enlace Web UI (with token) en la pestaña Instrucciones del Zeabur Dashboard)
2. Ve a la página de Config
3. Selecciona el modelo que desees en la configuración de modelos

Si estás usando Zeabur AI Hub, puedes cambiar entre múltiples modelos con un solo Key:

• claude-sonnet-4-6 -- recomendado, equilibra calidad y velocidad
• claude-haiku-4-5 -- más rápido y económico
• gpt-5-mini -- opción de OpenAI

¿Quieres usar otro Provider? Ve a la pestaña Variables de entorno para añadir el API Key correspondiente, y luego reinicia el servicio para usarlo:

Para más Providers, consulta la documentación oficial de OpenClaw.

---

Problema 5: 502 SERVICE_UNAVAILABLE

Síntoma: Al abrir la URL de OpenClaw aparece un error 502.

Causa: Hay tres causas comunes:

1. El servicio aún no ha terminado de iniciar (el puerto aún no está listo)
2. El puerto en la configuración de red de Zeabur no coincide con el puerto en el que OpenClaw está escuchando realmente (predeterminado 18789)
3. Después de eliminar openclaw.json, OpenClaw vuelve a la configuración predeterminada donde bind está en loopback, haciéndolo inaccesible desde el exterior

Solución:

1. Asegúrate de que el estado del servicio sea RUNNING
2. Confirma que el puerto configurado en la pestaña Red del Zeabur Dashboard sea 18789 (coincidiendo con la variable de entorno OPENCLAW_GATEWAY_PORT)
3. Confirma que la variable de entorno OPENCLAW_GATEWAY_BIND esté configurada como lan (la plantilla de Zeabur la configura por defecto, pero puede desaparecer si la has eliminado o restablecido manualmente)
4. Si has restablecido recientemente el archivo de configuración, también verifica gateway.bind en openclaw.json para asegurarte de que sea lan y no loopback
5. Espera unos minutos para que el enrutamiento surta efecto
6. Si el error 502 persiste, reinicia el servicio

---

Problema 6: La herramienta de navegador no funciona

Síntoma: Le pides a OpenClaw que navegue por la web o controle un navegador, y dice que el navegador no está habilitado o no se puede usar, y luego recurre a Web Fetch.

Causa: En un entorno de contenedor, headless Chrome requiere un servicio sandbox adicional para funcionar. Simplemente desplegar OpenClaw no incluye automáticamente un navegador.

Solución:

Despliega la plantilla OpenClaw Sandbox Browser, que configura automáticamente headless Chrome. Después del despliegue, necesitarás configurar un Profile remote en el Config de OpenClaw que apunte al sandbox.

Para simplemente leer contenido de páginas web (por ejemplo, resumir artículos), Web Fetch generalmente es suficiente y no necesitas necesariamente el control completo del navegador.

---

Problema 7: Permisos insuficientes, no se pueden instalar paquetes

Síntoma: Quieres que el bot instale pip, Homebrew u otras herramientas, pero muestra errores de permisos.

Causa: Los contenedores Docker de Zeabur se ejecutan como un usuario no root (node), por lo que no puedes instalar directamente paquetes a nivel de sistema. Homebrew tampoco está disponible en el entorno de contenedor.

Solución: Esto es una decisión de diseño deliberada: el aislamiento del contenedor protege la seguridad de tus datos. Alternativas:

• Usa el sistema de skills de OpenClaw: muchas funciones ya tienen skills predefinidos (más de 50)
• Si necesitas un entorno de desarrollo completo (pip, apt, etc.), despliega un Zeabur Devbox como sandbox de OpenClaw y deja que ejecute comandos allí

---

Problema 8: Fallo al reiniciar el Gateway

Síntoma: Al ejecutar openclaw gateway restart aparece:

Causa: El entorno de contenedor no tiene systemd.

Solución: No necesitas usar openclaw gateway restart en Zeabur. Simplemente ve al Dashboard y reinicia el servicio completo.

---

Problema 9: No encuentro el archivo de configuración openclaw.json

Síntoma: Quieres editar la configuración manualmente pero no sabes dónde está el archivo.

Solución: El archivo de configuración se encuentra dentro del contenedor en:

Puedes verlo y editarlo a través de la pestaña Archivos o Comando del Zeabur Dashboard.

Sin embargo, se recomienda usar la página de Config en la Web UI para modificar la configuración, ya que es menos probable que rompas el formato JSON. Romper manualmente el JSON es una de las causas comunes del Problema 1 (caídas del servicio).

---

Problema 10: La forma correcta de modificar la configuración

Método 1: Web UI (recomendado)

Usa la página Settings > Config en la Web UI para modificar la configuración. Valida el formato por ti, lo que reduce la probabilidad de romper el JSON.

Método 2: Pedir a OpenClaw que lo haga por ti

Dile directamente a OpenClaw en la conversación qué configuración quieres cambiar, y puede modificar openclaw.json por ti. Pero ten en cuenta dos cosas:

• Proporciona suficiente contexto -- indica claramente qué quieres cambiar y a qué valor; no digas simplemente "ayúdame a cambiar la configuración"
• Usa un modelo con suficiente capacidad -- modelos más simples pueden romper el formato o añadir campos inexistentes; se recomienda usar claude-sonnet-4-6 o gpt-5 o superior para operaciones de configuración

Método 3: Edición manual

1. Ve a la pestaña Archivos o Comando del Zeabur Dashboard
2. Edita /home/node/.openclaw/openclaw.json
3. Reinicia el servicio después de hacer los cambios

Nota: Independientemente del método que uses, no añadas claves que OpenClaw no reconozca, o se producirá la caída descrita en el Problema 1.

---

Problema 11: La forma correcta de actualizar OpenClaw

Procedimiento correcto:

1. Ve al Zeabur Dashboard y entra en el servicio de OpenClaw
2. En la configuración del servicio, cambia la etiqueta (tag) de la imagen Docker
3. Por ejemplo, cambia de 2026.2.19 a 2026.2.23
4. Después de guardar, el servicio se reiniciará automáticamente y usará la nueva versión

Antes de actualizar: Se recomienda exportar y hacer una copia de seguridad de tu configuración actual desde la página Config de la Web UI, en caso de que la nueva versión descontinúe algunos campos de configuración.

Después de actualizar: Las nuevas versiones pueden cambiar o descontinuar ciertos campos de configuración, causando un error Unrecognized key al iniciar que hace que el servicio falle. Si el servicio no arranca después de actualizar, consulta el Problema 1 y el Modo de rescate.

Cosas que no debes hacer:

• No cambies la imagen a algo que no sea ghcr.io/openclaw/openclaw
• No ejecutes openclaw update ni npm i -g openclaw dentro del contenedor -- esos son métodos de actualización para instalaciones locales; en Zeabur, simplemente cambia el tag de la imagen
• No uses la etiqueta latest — el servicio descarga la versión más reciente en cada reinicio, lo que puede actualizar sin tu conocimiento y causar problemas. Fija un número de versión específico (ej. 2026.2.23) y actualiza manualmente cuando sea necesario

---

Problema 12: Copia de seguridad y restauración

Zeabur tiene una función de copia de seguridad integrada que puede realizar copias de seguridad automáticas programadas -- se recomienda configurar esto primero. A continuación se explica cómo hacer una copia de seguridad manual.

Copia de seguridad manual:

Ve a la pestaña Comando del Zeabur Dashboard y ejecuta:

El archivo de copia de seguridad se creará en /home/node/ (por ejemplo, backup-1430.tar.gz). Ve a la pestaña Archivos para encontrar el archivo y haz clic en el botón Descargar a la derecha para guardarlo en tu ordenador.

Si tienes una versión antigua sin el comando backup:

Restauración:

1. Ve a la pestaña Archivos, navega a /home/node/, y haz clic en el botón Subir en la esquina superior derecha para subir el archivo de copia de seguridad
2. Ve a la pestaña Comando y ejecuta:

3. Reinicia el servicio

Si el archivo de copia de seguridad fue generado por el Zeabur Backup Service, añade --strip 2:

Cuándo hacer copia de seguridad: Después de la configuración inicial, antes de actualizar, antes de hacer cambios importantes en la configuración.

---

Problema 13: Telegram no conecta después de actualizar a 2026.2.17

Síntoma: Después de actualizar a 2026.2.17 o una versión más reciente, el bot de Telegram no puede conectarse o no responde.

Causa: La versión 2026.2.17 cambió el comportamiento predeterminado de la conexión de red, lo que puede causar fallos en la conexión con la API de Telegram en ciertos entornos de contenedor.

Solución:

Ve a la pestaña Variables de entorno del Zeabur Dashboard y añade:

Reinicia el servicio y listo.

---

Problema 14: Los registros de Telegram muestran constantemente 409 Conflict

Síntoma: Los registros muestran continuamente el siguiente error, y el bot de Telegram no responde en absoluto:

Causa: La API de Telegram Bot tiene dos formas de recibir mensajes: Polling (consulta activa de actualizaciones) y Webhook (Telegram envía las actualizaciones). Son mutuamente excluyentes y no pueden usarse simultáneamente.

Este error 409 significa que el bot fue configurado previamente con un webhook, pero ahora OpenClaw está intentando recibir mensajes mediante polling, y Telegram lo rechaza. Causas comunes:

• Otro servicio o entorno configuró previamente un webhook para este bot
• El webhook no fue eliminado antes de cambiar el bot al modo polling

Solución:

Ve a la pestaña Comando del Zeabur Dashboard y ejecuta el siguiente comando para eliminar el webhook (reemplaza <TOKEN> con el token de tu bot):

Cuando veas {"ok":true,"result":true}, el webhook se ha eliminado correctamente. Reinicia el servicio y el bot podrá recibir mensajes normalmente.

---

Problema 15: Web UI no carga después de actualizar a 2026.2.23

Síntoma: Después de actualizar a 2026.2.23, la Web UI muestra una página en blanco o errores CORS y no carga correctamente.

Causa: A partir de 2026.2.23, el Control UI aplica verificaciones de allowedOrigins. En Zeabur, los dominios de los usuarios se generan dinámicamente, por lo que el Gateway no puede determinar automáticamente qué origins son legítimos, rechazando las solicitudes.

Solución:

Ve a la pestaña Archivos del Zeabur Dashboard, edita /home/node/.openclaw/openclaw.json y añade lo siguiente en gateway.controlUi:

Reinicia el servicio y debería funcionar.

Si el servicio ya se ha caído y no puedes acceder, usa el Modo de rescate para editar el archivo de configuración.

---

¿Aún no puedes resolverlo?

Si has probado todo lo anterior y sigue sin funcionar:

1. Toma una captura de pantalla de los mensajes de error en la página de Registros
2. Abre un ticket de soporte en el Zeabur Forum y adjunta las capturas de pantalla

---

Si algún contenido de este artículo es incorrecto o está desactualizado, no dudes en reportarlo en el Zeabur Forum.