# OpenClaw on Zeabur 疑难排解

> 从真实客服记录整理出来的解法，让你五分钟内自己搞定。

<AIHubShutdownNotice />

OpenClaw 在 Zeabur 上跑得好好的，直到它突然不动了。

这不是假设情境。过去三周，我们处理了超过 40 张 OpenClaw 相关的支持单。有些问题五分钟就能自己解决，有些却让人卡了好几天。

这篇文章把最常见的问题整理出来，附上从真实案例中提炼的解法。下次遇到的时候，不用等客服回复。

## 你看到什么？

| 症状 | 查看 |
|---|---|
| 服务显示 CRASHED，一直重启 | [问题一](#p1) |
| 服务卡在 STARTING，从来没变 RUNNING | [问题二](#p2) |
| Telegram bot 显示 typing 但不回复 | [问题三](#p3) |
| 想换模型但不知道怎么设置 | [问题四](#p4) |
| 打开网址看到 502 错误 | [问题五](#p5) |
| 浏览器工具说没启动 | [问题六](#p6) |
| 安装套件显示权限错误 | [问题七](#p7) |
| `openclaw gateway restart` 出错 | [问题八](#p8) |
| 不知道配置文件在哪 | [问题九](#p9) |
| 手动改设置后崩溃 | [问题十](#p10) |
| 想升级 OpenClaw | [问题十一](#p11) |
| 升级后出问题 | [问题十一](#p11) |
| 想备份或还原数据 | [问题十二](#p12) |
| 升级 2026.2.17 后 Telegram 连不上 | [问题十三](#p13) |
| Telegram 日志出现 `409: Conflict` | [问题十四](#p14) |
| 升级 2026.2.23 后 Web UI 打不开 | [问题十五](#p15) |
| 日志出现 `Unrecognized key` | [问题一](#p1) + [救援模式](#rescue) |
| `No API key found for provider` | [问题三](#p3) |
| `connection refused on port 18789` | [问题二](#p2) |
| `systemctl ENOENT` | [问题八](#p8) |

---

<div id="rescue" />

## 先学会这个：救援模式

不管你遇到什么崩溃问题，这套流程几乎都能救回来。先记住，后面会反复用到。

### 2026/2/22 之后安装的版本（有辅助页面）

Gateway 崩溃时，打开服务网址会自动显示**辅助页面**，里面有错误记录和修复提示。

1. 查看辅助页面上的**错误记录**（完整记录到 Zeabur Dashboard 的**日志**页签查看）
2. 到 Zeabur Dashboard 的**文件**页签，找到 `/home/node/.openclaw/openclaw.json` 并修正问题
3. 在 Zeabur Dashboard 点击**重新启动**

服务恢复后，辅助页面会自动消失。

### 2026/2/22 之前安装的版本（无辅助页面）

旧版没有辅助页面，需要手动进入容器修复。

1. 到 Zeabur Dashboard，找到你的 OpenClaw 服务
2. 到**日志**页签查看错误信息
3. 到**设置** → **命令**，把启动命令改为 `sleep 3600`，然后**重新启动** — 这样容器会持续运行，让你有机会进去修东西
4. 到**文件**页签，找到 `/home/node/.openclaw/openclaw.json` 并修正问题
5. 把启动命令改回 `/opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh`，然后**重启服务**

> 想启用辅助页面？从 [OpenClaw 模板](https://zeabur.com/zh-CN/templates/VTZ4FX)重新部署即可。

---

<div id="p1" />

## 问题一：改完设置后服务崩溃，一直重启

这是目前最常见的问题，占了将近一半的支持单。

**症状：** 服务状态显示 CRASHED 或 CrashLoopBackOff，日志出现类似这样的错误：

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

**原因：** 配置文件里有 OpenClaw 不认识的 key。常见情境：手动编辑时加了不存在的字段、叫 OpenClaw 改设置但它改坏了、升级版本后旧的设置字段被弃用或改名。配置文件存在持久化存储里，读到不认识的 key 就直接拒绝启动。

**解法：**

**情况 A：服务还能启动（日志有显示 Doctor 提示）**

进入**命令**页签执行 `openclaw doctor --fix`，它会自动移除不认识的 key。

**情况 B：服务已经崩溃，连 shell 都进不去**

这是最常见的情况。用上面的[**救援模式**](#rescue)进入容器，打开 `/home/node/.openclaw/openclaw.json`，对照日志里列出的 key（例如上面的 `gateway.cool`）把它删掉，然后重启服务。

---

<div id="p2" />

## 问题二：服务卡在「启用中」，启动探针超时

**症状：** 服务一直显示 STARTING，从来没有变成 RUNNING。日志可能显示：

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

**原因：** OpenClaw 需要比较长的启动时间（有时超过 60 秒），默认的启动探针可能太急了。另一个常见原因是配置文件损坏（跟问题一一样）。

**解法：**

1. 先等几分钟让它完成初始化
2. 如果持续失败，检查日志里有没有 config 相关的错误
3. 确认内存至少 4GB
4. 如果日志显示 config invalid，用**救援模式**处理

---

<div id="p3" />

## 问题三：接上 AI Hub 但 bot 没有回应

**症状：** Telegram 发消息给 bot，它显示 typing 但永远不回复，或直接没反应。

**原因：** 通常是 API Key 设置问题，或是模型连接失败。我们看过最常见的错误是 Key 和 Provider 不匹配。

**解法：**

1. 确认环境变量设置正确：
   - `ZEABUR_AI_HUB_API_KEY` — 使用 Zeabur AI Hub 时
   - `ANTHROPIC_API_KEY` — 直接使用 Claude 时
   - `OPENAI_API_KEY` — 使用 OpenAI 时（也用于 Memory Search 和 TTS）

2. 到 Web UI 检查模型设置，确认选择的模型跟你的 API Key 匹配

3. **设置环境变量后记得重启服务**，不然不会生效

**常见错误：** 设置了 AI Hub Key 但 OpenClaw 默认尝试连 Anthropic，导致 `No API key found for provider "anthropic"`。确保 Provider 设置跟你的 Key 一致。

---

<div id="p4" />

## 问题四：想换模型，不知道怎么设置

**症状：** 默认模型不够好用，想换成 Claude Sonnet 或其他模型。

**解法：**

1. 进入 OpenClaw Web UI（从 Zeabur Dashboard 的**使用说明**分页找到 **Web UI (with token)** 链接）
2. 到 Config 页面
3. 在模型设置中选择你要的模型

如果使用 Zeabur AI Hub，可以在一把 Key 下切换多种模型：
- `claude-sonnet-4-6` — 推荐，平衡品质与速度
- `claude-haiku-4-5` — 更快、更便宜
- `gpt-5-mini` — OpenAI 选项

**想用其他 Provider？** 到**环境变量**页签加入对应的 API Key，**重启服务**后即可使用：

| Provider | 环境变量 |
|---|---|
| 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` |

更多 Provider 请参考 [OpenClaw 官方文档](https://docs.openclaw.ai/providers)。

---

<div id="p5" />

## 问题五：502 SERVICE_UNAVAILABLE

**症状：** 打开 OpenClaw 的网址，看到 502 错误。

**原因：** 常见原因有三个：

1. 服务还没启动完成（port 还没 ready）
2. Zeabur 网络设置的 port 不是 OpenClaw 实际监听的 port（默认 `18789`）
3. 删除 `openclaw.json` 后，OpenClaw 回退到默认设置，`bind` 变成 loopback，外部无法连线

**解法：**

1. 确认服务状态是 RUNNING
2. 确认 Zeabur Dashboard **网络**页签中设置的 port 是 `18789`（跟环境变量 `OPENCLAW_GATEWAY_PORT` 一致）
3. 确认环境变量 `OPENCLAW_GATEWAY_BIND` 的值是 `lan`（Zeabur 模板默认会设好，但如果手动删除或重置过可能会不见）
4. 如果是刚重置过配置文件，也检查 `openclaw.json` 里的 `gateway.bind`，确保是 `lan` 而不是 `loopback`
5. 等待几分钟让路由生效
6. 如果持续 502，重启服务

---

<div id="p6" />

## 问题六：浏览器工具不能用

**症状：** 叫 OpenClaw 上网查资料或控制浏览器，它说浏览器没启动或无法使用，然后改用 Web Fetch。

**原因：** 在容器环境中，headless Chrome 需要额外的 sandbox 服务才能运作。单纯部署 OpenClaw 不会自动带浏览器。

**解法：**

部署 OpenClaw Sandbox Browser 模板，它会自动配好 headless Chrome。部署后需要在 OpenClaw 的 Config 里设置 `remote` Profile 指向 sandbox。

<TemplateCTA
  code="H8L4G1"
  title="部署 Sandbox Browser"
  description="为 OpenClaw 加上浏览器控制能力。"
  buttonText="一键部署"
/>

对于单纯读取网页内容（例如摘要文章），Web Fetch 通常就够用了，不一定需要完整的浏览器控制。

---

<div id="p7" />

## 问题七：权限不足，无法安装套件

**症状：** 想让 bot 安装 pip、Homebrew 或其他工具，但显示权限错误。

**原因：** Zeabur 的 Docker 容器以非 root 用户（`node`）运行，无法直接安装系统级套件。Homebrew 在容器环境中也不可用。

**解法：** 这是设计上的取舍——容器隔离保护了你的数据安全。替代方案：

- 用 OpenClaw 的 **skill 系统**，很多功能已经有现成的 skill（超过 50 个）
- 如果需要完整的开发环境（pip、apt 等），可以部署 Zeabur Devbox 作为 OpenClaw 的 sandbox，让它在里面执行命令

<TemplateCTA
  code="ZBVZNH"
  title="部署 Devbox"
  description="为 OpenClaw 加上完整的开发环境。"
  buttonText="一键部署"
/>

---

<div id="p8" />

## 问题八：Gateway restart 失败

**症状：** 执行 `openclaw gateway restart` 出现：

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

**原因：** 容器环境没有 systemd。

**解法：** 在 Zeabur 上不需要用 `openclaw gateway restart`。直接到 Dashboard **重启整个服务**即可。

---

<div id="p9" />

## 问题九：找不到 openclaw.json 配置文件

**症状：** 想手动编辑设置，但不知道文件在哪。

**解法：** 配置文件位于容器内的：

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

你可以通过 Zeabur Dashboard 的**文件**或**命令**页签进去查看和编辑。

但建议优先使用 Web UI 的 Config 页面来修改设置，比较不容易打坏 JSON 格式。手动改坏 JSON 是造成问题一（崩溃）的常见原因之一。

---

<div id="p10" />

## 问题十：修改设置的正确方式

**方法一：Web UI（推荐）**

使用 Web UI 的 **Settings → Config** 页面修改设置。它会帮你做格式验证，比较不容易打坏 JSON。

**方法二：叫 OpenClaw 帮你改**

直接在对话中告诉 OpenClaw 你想改什么设置，它可以帮你修改 `openclaw.json`。但要注意两件事：
- **提供足够的上下文** — 说清楚你要改什么、改成什么，不要只说「帮我改设置」
- **使用能力足够的模型** — 简单的模型可能会改错格式或加入不存在的字段，建议用 `claude-sonnet-4-6` 或 `gpt-5` 以上的模型来操作设置

**方法三：手动编辑**

1. 到 Zeabur Dashboard 的**文件**或**命令**页签
2. 编辑 `/home/node/.openclaw/openclaw.json`
3. 改完后**重启服务**

**注意：** 不管用哪种方式，都不要加 OpenClaw 不认识的 key，否则会触发问题一的崩溃。

---

<div id="p11" />

## 问题十一：升级 OpenClaw 的正确方式

**正确做法：**

1. 到 Zeabur Dashboard，点进 OpenClaw 服务
2. 在服务设置中，修改 Docker image 的**标签**（tag）
3. 例如从 `2026.2.19` 改为 `2026.2.23`
4. 保存后服务会自动重启并使用新版本

**升级前建议：** 先到 Web UI 的 Config 页面把现有设置导出备份，以防新版本弃用了某些设置字段。

**升级后注意：** 新版本可能会变更或弃用某些设置字段，导致启动时出现 `Unrecognized key` 错误而崩溃。如果升级后服务起不来，参考[问题一](#p1)和[救援模式](#rescue)的处理方式。

**不要做的事：**
- 不要把镜像改成非 `ghcr.io/openclaw/openclaw` 的东西
- 不要在容器内执行 `openclaw update` 或 `npm i -g openclaw`——这些是本地安装的升级方式，在 Zeabur 上改 image tag 就好
- **不推荐使用 `latest` 标签**——服务重启时会自动拉取最新版本，可能在你不知情的情况下升级并出现问题。建议固定版本号（如 `2026.2.23`），需要升级时再手动更改

---

<div id="p12" />

## 问题十二：备份与还原

Zeabur 有内建的[备份功能](https://zeabur.com/docs/data-management/backup)，可以定期自动备份，建议先设置好。以下是手动备份的方式。

**手动备份：**

到 Zeabur Dashboard 的**命令**页签执行：

```
backup
```

备份文件会产生在 `/home/node/`（例如 `backup-1430.tar.gz`），到**文件**页签找到文件，点右边的**下载**按钮存到电脑。

旧版没有 `backup` 命令的话：

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

**还原：**

1. 到**文件**页签，进入 `/home/node/`，点右上角**上传**按钮上传备份文件
2. 到**命令**页签执行：

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

3. **重启服务**

如果是从 Zeabur Backup Service 产生的备份文件，加 `--strip 2`：

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

**什么时候该备份：** 初始设置完成后、升级前、改大幅设置前。

---

<div id="p13" />

## 问题十三：升级 2026.2.17 后 Telegram 连不上

**症状：** 升级到 `2026.2.17` 或更新版本后，Telegram bot 无法连线或不回应。

**原因：** `2026.2.17` 版修改了网络连线的默认行为，在某些容器环境下会导致 Telegram API 连线失败。

**解法：**

到 Zeabur Dashboard 的**环境变量**页签，新增：

```
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true
```

**重启服务**即可。

---

<div id="p14" />

## 问题十四：Telegram 日志一直出现 409 Conflict

**症状：** 日志不断出现以下错误，Telegram bot 完全没反应：

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

**原因：** Telegram Bot API 有两种接收消息的方式：**Polling**（主动轮询）和 **Webhook**（Telegram 推送）。两者互斥，不能同时使用。

这个 409 错误代表这个 bot 之前被设置过 webhook，但现在 OpenClaw 尝试用 polling 方式接收消息，Telegram 拒绝了。常见原因：

- 之前有其他服务或环境对这个 bot 设过 webhook
- bot 切回 polling 模式前没有清除 webhook

**解法：**

到 Zeabur Dashboard 的**命令**页签，执行以下命令清除 webhook（把 `<TOKEN>` 换成你的 bot token）：

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

看到 `{"ok":true,"result":true}` 就代表清除成功。**重启服务**后 bot 就能正常接收消息了。

---

<div id="p15" />

## 问题十五：升级 2026.2.23 后 Web UI 打不开

**症状：** 升级到 `2026.2.23` 后，打开 Web UI 出现空白页面或 CORS 错误，无法正常加载。

**原因：** `2026.2.23` 开始强制检查 Control UI 的 `allowedOrigins`。在 Zeabur 上，用户的 domain 是动态生成的，Gateway 无法自动判断合法的 origin，导致请求被拒绝。

**解法：**

到 Zeabur Dashboard 的**文件**分页，编辑 `/home/node/.openclaw/openclaw.json`，在 `gateway.controlUi` 区块加入：

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

**重启服务**即可。

如果服务已经崩溃进不去，用[**救援模式**](#rescue)编辑设置文件。

---

## 还是解决不了？

如果以上都试过了还是不行：

1. 到日志页面截图错误信息
2. 到 [Zeabur Forum](https://zeabur.com/forum) 开一张支持单，附上截图

---

如果这篇文章的内容有错误或过时，也欢迎到 [Zeabur Forum](https://zeabur.com/forum) 回报。