# Solución de problemas de OpenClaw en Zeabur

> Soluciones extraídas de tickets de soporte reales para que lo resuelvas tú mismo en cinco minutos.

<AIHubShutdownNotice />

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?

| Síntoma | Ver |
|---|---|
| El servicio muestra CRASHED y se reinicia constantemente | [Problema 1](#p1) |
| El servicio se queda en STARTING y nunca pasa a RUNNING | [Problema 2](#p2) |
| El bot de Telegram muestra typing pero nunca responde | [Problema 3](#p3) |
| Quiero cambiar de modelo pero no sé cómo configurarlo | [Problema 4](#p4) |
| Al abrir la URL aparece un error 502 | [Problema 5](#p5) |
| La herramienta de navegador dice que no está habilitada | [Problema 6](#p6) |
| La instalación de paquetes muestra errores de permisos | [Problema 7](#p7) |
| `openclaw gateway restart` da error | [Problema 8](#p8) |
| No sé dónde está el archivo de configuración | [Problema 9](#p9) |
| El servicio se cae tras editar la configuración manualmente | [Problema 10](#p10) |
| Quiero actualizar OpenClaw | [Problema 11](#p11) |
| Problemas después de actualizar | [Problema 11](#p11) |
| Quiero hacer una copia de seguridad o restaurar datos | [Problema 12](#p12) |
| Telegram no conecta después de actualizar a 2026.2.17 | [Problema 13](#p13) |
| Los registros de Telegram muestran `409: Conflict` | [Problema 14](#p14) |
| Web UI no carga después de actualizar a 2026.2.23 | [Problema 15](#p15) |
| Los registros muestran `Unrecognized key` | [Problema 1](#p1) + [Modo de rescate](#rescue) |
| `No API key found for provider` | [Problema 3](#p3) |
| `connection refused on port 18789` | [Problema 2](#p2) |
| `systemctl ENOENT` | [Problema 8](#p8) |

---

<div id="rescue" />

## 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](https://zeabur.com/es-ES/templates/VTZ4FX).

---

<div id="p1" />

## 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:

```
Invalid config at /home/node/.openclaw/openclaw.json:
- gateway: Unrecognized key: "cool"

◇  Unknown config keys ─╮
│                       │
│  - gateway.cool       │
│                       │
├───────────────────────╯

◇  Doctor ────────────────────────────────────────────╮
│                                                     │
│  Run "openclaw doctor --fix" to remove these keys.  │
│                                                     │
├─────────────────────────────────────────────────────╯
Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - gateway: Unrecognized key: "cool"

Run: openclaw doctor --fix
```

**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**](#rescue) 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.

---

<div id="p2" />

## 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:

```
Startup probe failed: dial tcp 10.0.5.87:18789: connect: connection refused
```

**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

---

<div id="p3" />

## 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.

---

<div id="p4" />

## 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:

| Provider | Variable de entorno |
|---|---|
| Zeabur AI Hub | `ZEABUR_AI_HUB_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GEMINI_API_KEY` |
| xAI (Grok) | `XAI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Moonshot (Kimi) | `MOONSHOT_API_KEY` |
| Z.AI (GLM) | `ZAI_API_KEY` |

Para más Providers, consulta la [documentación oficial de OpenClaw](https://docs.openclaw.ai/providers).

---

<div id="p5" />

## 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

---

<div id="p6" />

## 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.

<TemplateCTA
  code="H8L4G1"
  title="Desplegar Sandbox Browser"
  description="Añade capacidades de control de navegador a OpenClaw."
  buttonText="Desplegar ahora"
/>

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.

---

<div id="p7" />

## 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í

<TemplateCTA
  code="ZBVZNH"
  title="Desplegar Devbox"
  description="Añade un entorno de desarrollo completo a OpenClaw."
  buttonText="Desplegar ahora"
/>

---

<div id="p8" />

## Problema 8: Fallo al reiniciar el Gateway

**Síntoma:** Al ejecutar `openclaw gateway restart` aparece:

```
Gateway service check failed: Error: systemctl --user unavailable: spawn systemctl ENOENT
```

**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**.

---

<div id="p9" />

## 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:

```
/home/node/.openclaw/openclaw.json
```

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).

---

<div id="p10" />

## 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.

---

<div id="p11" />

## 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](#p1) y el [Modo de rescate](#rescue).

**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

---

<div id="p12" />

## Problema 12: Copia de seguridad y restauración

Zeabur tiene una [función de copia de seguridad](https://zeabur.com/docs/data-management/backup) 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:

```
backup
```

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`:

```
cd /home/node && tar -czvf backup.tar.gz .openclaw
```

**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:

```
restore backup-1430.tar.gz
```

3. **Reinicia el servicio**

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

```
restore backup-xxxxx.tar.gz --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.

---

<div id="p13" />

## 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:

```
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true
```

**Reinicia el servicio** y listo.

---

<div id="p14" />

## 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:

```
[telegram] getUpdates conflict: Call to 'getUpdates' failed! (409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running)
```

**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):

```
curl https://api.telegram.org/bot<TOKEN>/deleteWebhook
```

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

---

<div id="p15" />

## 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`:

```json
{
  "gateway": {
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    }
  }
}
```

**Reinicia el servicio** y debería funcionar.

Si el servicio ya se ha caído y no puedes acceder, usa el [**Modo de rescate**](#rescue) 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](https://zeabur.com/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](https://zeabur.com/forum).