# OpenClaw on Zeabur Troubleshooting

> Solutions distilled from real support tickets so you can fix it yourself in five minutes.

<AIHubShutdownNotice />

OpenClaw runs perfectly on Zeabur -- until it suddenly doesn't.

This isn't a hypothetical scenario. Over the past three weeks, we've handled more than 40 OpenClaw-related support tickets. Some issues can be fixed in five minutes on your own; others have left people stuck for days.

This article compiles the most common issues along with solutions distilled from real cases. Next time you run into one, you won't have to wait for a support reply.

## What are you seeing?

| Symptom | Go to |
|---|---|
| Service shows CRASHED and keeps restarting | [Issue 1](#p1) |
| Service stuck on STARTING, never becomes RUNNING | [Issue 2](#p2) |
| Telegram bot shows typing but never replies | [Issue 3](#p3) |
| Want to switch models but don't know how to configure it | [Issue 4](#p4) |
| Opening the URL shows a 502 error | [Issue 5](#p5) |
| Browser tool says it's not enabled | [Issue 6](#p6) |
| Installing packages shows permission errors | [Issue 7](#p7) |
| `openclaw gateway restart` throws an error | [Issue 8](#p8) |
| Don't know where the config file is | [Issue 9](#p9) |
| Service crashes after manually editing config | [Issue 10](#p10) |
| Want to upgrade OpenClaw | [Issue 11](#p11) |
| Problems after upgrading | [Issue 11](#p11) |
| Want to back up or restore data | [Issue 12](#p12) |
| Telegram won't connect after upgrading to 2026.2.17 | [Issue 13](#p13) |
| Telegram logs show `409: Conflict` | [Issue 14](#p14) |
| Web UI won't load after upgrading to 2026.2.23 | [Issue 15](#p15) |
| Logs show `Unrecognized key` | [Issue 1](#p1) + [Rescue Mode](#rescue) |
| `No API key found for provider` | [Issue 3](#p3) |
| `connection refused on port 18789` | [Issue 2](#p2) |
| `systemctl ENOENT` | [Issue 8](#p8) |

---

<div id="rescue" />

## Learn this first: Rescue Mode

No matter what crash you're dealing with, this workflow can almost always bring things back. Memorize it -- you'll use it repeatedly throughout this guide.

### Versions installed after 2026/2/22 (with helper page)

When the Gateway crashes, opening the service URL will automatically display a **helper page** with error logs and repair hints.

1. Check the **error logs** on the helper page (full logs are available in the **Logs** tab of the Zeabur Dashboard)
2. Go to the **Files** tab in the Zeabur Dashboard, find `/home/node/.openclaw/openclaw.json`, and fix the issue
3. Click **Restart** in the Zeabur Dashboard

Once the service recovers, the helper page will disappear automatically.

### Versions installed before 2026/2/22 (no helper page)

Older versions don't have the helper page, so you'll need to manually enter the container to fix things.

1. Go to the Zeabur Dashboard and find your OpenClaw service
2. Go to the **Logs** tab to check the error messages
3. Go to **Settings** > **Command**, change the startup command to `sleep 3600`, then **Restart** -- this keeps the container running so you can get in and fix things
4. Go to the **Files** tab, find `/home/node/.openclaw/openclaw.json`, and fix the issue
5. Change the startup command back to `/opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh`, then **Restart** the service

> Want to enable the helper page? Simply redeploy from the [OpenClaw template](https://zeabur.com/en-US/templates/VTZ4FX).

---

<div id="p1" />

## Issue 1: Service crashes and keeps restarting after config changes

This is currently the most common issue, accounting for nearly half of all support tickets.

**Symptom:** Service status shows CRASHED or CrashLoopBackOff, and the logs show errors like this:

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

**Cause:** The config file contains keys that OpenClaw doesn't recognize. Common scenarios: adding nonexistent fields when manually editing, asking OpenClaw to modify the config but it breaks it, or old config fields being deprecated or renamed after a version upgrade. The config file lives in persistent storage, and if it encounters an unrecognized key, the service simply refuses to start.

**Solution:**

**Case A: The service can still start (logs show the Doctor prompt)**

Go to the **Command** tab and run `openclaw doctor --fix` -- it will automatically remove unrecognized keys.

**Case B: The service has already crashed and you can't even get a shell**

This is the most common scenario. Use [**Rescue Mode**](#rescue) above to enter the container, open `/home/node/.openclaw/openclaw.json`, remove the keys listed in the logs (e.g., `gateway.cool` from the example above), then restart the service.

---

<div id="p2" />

## Issue 2: Service stuck on "Starting", startup probe times out

**Symptom:** Service keeps showing STARTING and never transitions to RUNNING. Logs may show:

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

**Cause:** OpenClaw requires a relatively long startup time (sometimes over 60 seconds), and the default startup probe may be too aggressive. Another common cause is a corrupted config file (same as Issue 1).

**Solution:**

1. Wait a few minutes for initialization to complete
2. If it keeps failing, check the logs for config-related errors
3. Make sure memory is at least 4GB
4. If the logs show config invalid, use **Rescue Mode** to fix it

---

<div id="p3" />

## Issue 3: Connected to AI Hub but bot doesn't respond

**Symptom:** You send a message to the Telegram bot, it shows typing but never replies, or has no response at all.

**Cause:** Usually an API Key configuration issue or a model connection failure. The most common error we've seen is a mismatch between the Key and the Provider.

**Solution:**

1. Make sure your environment variables are set correctly:
   - `ZEABUR_AI_HUB_API_KEY` -- when using Zeabur AI Hub
   - `ANTHROPIC_API_KEY` -- when using Claude directly
   - `OPENAI_API_KEY` -- when using OpenAI (also used for Memory Search and TTS)

2. Go to the Web UI to check the model settings and make sure the selected model matches your API Key

3. **Remember to restart the service after setting environment variables** -- otherwise the changes won't take effect

**Common mistake:** You've set up the AI Hub Key but OpenClaw defaults to connecting to Anthropic, resulting in `No API key found for provider "anthropic"`. Make sure the Provider setting matches your Key.

---

<div id="p4" />

## Issue 4: Want to switch models but don't know how to configure it

**Symptom:** The default model isn't good enough and you want to switch to Claude Sonnet or another model.

**Solution:**

1. Open the OpenClaw Web UI (find the **Web UI (with token)** link from the **Instructions** tab in the Zeabur Dashboard)
2. Go to the Config page
3. Select the model you want in the model settings

If you're using Zeabur AI Hub, you can switch between multiple models with a single Key:
- `claude-sonnet-4-6` -- recommended, balances quality and speed
- `claude-haiku-4-5` -- faster and cheaper
- `gpt-5-mini` -- OpenAI option

**Want to use a different Provider?** Go to the **Environment Variables** tab to add the corresponding API Key, then **restart the service** to use it:

| Provider | Environment Variable |
|---|---|
| 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` |

For more Providers, see the [OpenClaw official documentation](https://docs.openclaw.ai/providers).

---

<div id="p5" />

## Issue 5: 502 SERVICE_UNAVAILABLE

**Symptom:** Opening the OpenClaw URL shows a 502 error.

**Cause:** There are three common causes:

1. The service hasn't finished starting (port isn't ready yet)
2. The port in the Zeabur network settings doesn't match the port OpenClaw is actually listening on (default `18789`)
3. After deleting `openclaw.json`, OpenClaw falls back to default settings where `bind` is set to loopback, making it unreachable from outside

**Solution:**

1. Make sure the service status is RUNNING
2. Confirm that the port set in the **Network** tab of the Zeabur Dashboard is `18789` (matching the `OPENCLAW_GATEWAY_PORT` environment variable)
3. Confirm that the `OPENCLAW_GATEWAY_BIND` environment variable is set to `lan` (the Zeabur template sets this by default, but it may be missing if you've manually deleted or reset it)
4. If you've recently reset the config file, also check `gateway.bind` in `openclaw.json` to make sure it's `lan` and not `loopback`
5. Wait a few minutes for routing to take effect
6. If the 502 persists, restart the service

---

<div id="p6" />

## Issue 6: Browser tool doesn't work

**Symptom:** You ask OpenClaw to browse the web or control a browser, and it says the browser isn't enabled or can't be used, then falls back to Web Fetch.

**Cause:** In a container environment, headless Chrome requires an additional sandbox service to work. Simply deploying OpenClaw doesn't automatically include a browser.

**Solution:**

Deploy the OpenClaw Sandbox Browser template, which automatically sets up headless Chrome. After deployment, you'll need to configure a `remote` Profile in the OpenClaw Config to point to the sandbox.

<TemplateCTA
  code="H8L4G1"
  title="Deploy Sandbox Browser"
  description="Add browser control capabilities to OpenClaw."
  buttonText="Deploy Now"
/>

For simply reading web page content (e.g., summarizing articles), Web Fetch is usually sufficient and you don't necessarily need full browser control.

---

<div id="p7" />

## Issue 7: Insufficient permissions, can't install packages

**Symptom:** You want the bot to install pip, Homebrew, or other tools, but it shows permission errors.

**Cause:** Zeabur's Docker containers run as a non-root user (`node`), so you can't directly install system-level packages. Homebrew is also not available in the container environment.

**Solution:** This is a deliberate trade-off -- container isolation protects your data security. Alternatives:

- Use OpenClaw's **skill system** -- many features already have ready-made skills (over 50)
- If you need a full development environment (pip, apt, etc.), deploy a Zeabur Devbox as OpenClaw's sandbox and let it execute commands there

<TemplateCTA
  code="ZBVZNH"
  title="Deploy Devbox"
  description="Add a full development environment to OpenClaw."
  buttonText="Deploy Now"
/>

---

<div id="p8" />

## Issue 8: Gateway restart fails

**Symptom:** Running `openclaw gateway restart` shows:

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

**Cause:** The container environment doesn't have systemd.

**Solution:** You don't need to use `openclaw gateway restart` on Zeabur. Simply go to the Dashboard and **restart the entire service**.

---

<div id="p9" />

## Issue 9: Can't find the openclaw.json config file

**Symptom:** You want to manually edit the config but don't know where the file is.

**Solution:** The config file is located inside the container at:

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

You can view and edit it through the **Files** or **Command** tab in the Zeabur Dashboard.

However, it's recommended to use the Config page in the Web UI to modify settings first, as it's less likely to break the JSON format. Manually breaking the JSON is one of the common causes of Issue 1 (crashes).

---

<div id="p10" />

## Issue 10: The right way to modify settings

**Method 1: Web UI (recommended)**

Use the **Settings > Config** page in the Web UI to modify settings. It validates the format for you, making it less likely to break the JSON.

**Method 2: Ask OpenClaw to do it for you**

Tell OpenClaw directly in the conversation what settings you want to change, and it can modify `openclaw.json` for you. But keep two things in mind:
- **Provide enough context** -- clearly state what you want to change and what you want it changed to; don't just say "help me change the settings"
- **Use a capable enough model** -- simpler models may break the format or add nonexistent fields; it's recommended to use `claude-sonnet-4-6` or `gpt-5` or above for config operations

**Method 3: Manual editing**

1. Go to the **Files** or **Command** tab in the Zeabur Dashboard
2. Edit `/home/node/.openclaw/openclaw.json`
3. **Restart the service** after making changes

**Note:** Regardless of which method you use, don't add keys that OpenClaw doesn't recognize, or it will trigger the crash described in Issue 1.

---

<div id="p11" />

## Issue 11: The right way to upgrade OpenClaw

**Correct approach:**

1. Go to the Zeabur Dashboard and click into the OpenClaw service
2. In the service settings, change the Docker image **tag**
3. For example, change from `2026.2.19` to `2026.2.23`
4. After saving, the service will automatically restart and use the new version

**Before upgrading:** It's recommended to export and back up your current config from the Web UI Config page, in case the new version deprecates some config fields.

**After upgrading:** New versions may change or deprecate certain config fields, causing an `Unrecognized key` error on startup that crashes the service. If the service won't start after upgrading, refer to [Issue 1](#p1) and [Rescue Mode](#rescue).

**Things to avoid:**
- Don't change the image to anything other than `ghcr.io/openclaw/openclaw`
- Don't run `openclaw update` or `npm i -g openclaw` inside the container -- those are upgrade methods for local installations; on Zeabur, just change the image tag
- **Don't use the `latest` tag** -- the service pulls the newest version on every restart, which may upgrade without your knowledge and cause issues. Pin a specific version (e.g. `2026.2.23`) and update manually when needed

---

<div id="p12" />

## Issue 12: Backup and restore

Zeabur has a built-in [backup feature](https://zeabur.com/docs/data-management/backup) that can perform automatic scheduled backups -- it's recommended to set this up first. Below is how to do a manual backup.

**Manual backup:**

Go to the **Command** tab in the Zeabur Dashboard and run:

```
backup
```

The backup file will be created in `/home/node/` (e.g., `backup-1430.tar.gz`). Go to the **Files** tab to find the file, and click the **Download** button on the right to save it to your computer.

If you're on an older version without the `backup` command:

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

**Restore:**

1. Go to the **Files** tab, navigate to `/home/node/`, and click the **Upload** button in the top-right corner to upload the backup file
2. Go to the **Command** tab and run:

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

3. **Restart the service**

If the backup file was generated by the Zeabur Backup Service, add `--strip 2`:

```
restore backup-xxxxx.tar.gz --strip 2
```

**When to back up:** After initial setup, before upgrading, before making major config changes.

---

<div id="p13" />

## Issue 13: Telegram won't connect after upgrading to 2026.2.17

**Symptom:** After upgrading to `2026.2.17` or a newer version, the Telegram bot can't connect or doesn't respond.

**Cause:** Version `2026.2.17` changed the default network connection behavior, which can cause Telegram API connection failures in certain container environments.

**Solution:**

Go to the **Environment Variables** tab in the Zeabur Dashboard and add:

```
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true
```

**Restart the service** and you're done.

---

<div id="p14" />

## Issue 14: Telegram logs keep showing 409 Conflict

**Symptom:** The logs continuously show the following error, and the Telegram bot is completely unresponsive:

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

**Cause:** The Telegram Bot API has two ways to receive messages: **Polling** (actively polling for updates) and **Webhook** (Telegram pushes updates to you). These are mutually exclusive and cannot be used simultaneously.

This 409 error means the bot was previously configured with a webhook, but now OpenClaw is trying to receive messages via polling, and Telegram is rejecting it. Common causes:

- Another service or environment previously set a webhook for this bot
- The webhook wasn't cleared before switching the bot back to polling mode

**Solution:**

Go to the **Command** tab in the Zeabur Dashboard and run the following command to clear the webhook (replace `<TOKEN>` with your bot token):

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

When you see `{"ok":true,"result":true}`, the webhook has been cleared successfully. **Restart the service** and the bot will be able to receive messages normally.

---

<div id="p15" />

## Issue 15: Web UI won't load after upgrading to 2026.2.23

**Symptom:** After upgrading to `2026.2.23`, the Web UI shows a blank page or CORS errors and won't load properly.

**Cause:** Starting from `2026.2.23`, the Control UI enforces `allowedOrigins` checks. On Zeabur, domains are dynamically generated, so the Gateway can't automatically determine which origins are legitimate, causing requests to be rejected.

**Solution:**

Go to the **Files** tab in the Zeabur Dashboard, edit `/home/node/.openclaw/openclaw.json`, and add the following under `gateway.controlUi`:

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

**Restart the service** and it should work.

If the service has already crashed and you can't get in, use [**Rescue Mode**](#rescue) to edit the config file.

---

## Still can't fix it?

If you've tried everything above and it still doesn't work:

1. Take a screenshot of the error messages from the Logs page
2. Open a support ticket on the [Zeabur Forum](https://zeabur.com/forum) and attach the screenshots

---

If any content in this article is incorrect or outdated, feel free to report it on the [Zeabur Forum](https://zeabur.com/forum).