# 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-TW/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) 回報。