OpenClaw on Zeabur Troubleshooting

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?

---

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.

---

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:

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

---

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

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

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

---

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.

---

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:

For more Providers, see the OpenClaw official documentation.

---

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

---

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.

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

---

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

---

Issue 8: Gateway restart fails

Symptom: Running openclaw gateway restart shows:

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.

---

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:

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

---

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.

---

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 and Rescue Mode.

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

---

Issue 12: Backup and restore

Zeabur has a built-in backup feature 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:

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:

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:

3. Restart the service

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

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

---

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:

Restart the service and you're done.

---

Issue 14: Telegram logs keep showing 409 Conflict

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

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

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.

---

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:

Restart the service and it should work.

If the service has already crashed and you can't get in, use Rescue Mode 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 and attach the screenshots

---

If any content in this article is incorrect or outdated, feel free to report it on the Zeabur Forum.