修復「OpenClaw Gateway Did Not Become Ready」錯誤（2026 完整指南）

沒什麼比看著你的 OpenClaw 拒絕啟動更令人沮喪了。你執行 openclaw start，等了半天，然後看到：

FAIL  gateway did not become ready within 60s

這個錯誤代表 gateway 程序已經啟動，但從未完成初始化。這是最常見的 OpenClaw 問題之一，幾乎所有情況都能在五分鐘內解決。本指南會帶你逐一排查每個已知原因，並提供具體的修復步驟。

了解 Gateway 啟動流程

在開始修復之前，先了解 gateway 啟動時實際發生的事情會很有幫助。OpenClaw gateway 會經歷以下幾個初始化階段^[1]：

1. 載入設定 -- 讀取 openclaw.json 並驗證設定鍵
2. 綁定連接埠 -- 嘗試在設定的連接埠上監聽（預設 3001）
3. 初始化資料庫 -- 建立用於記憶和工作階段的本地 SQLite 儲存
4. 載入外掛 -- 初始化已設定的 skills 和 MCP 伺服器
5. 註冊健康檢查 -- 開放 openclaw doctor 使用的健康檢查端點

「did not become ready」錯誤會在步驟 5 未能在逾時時間（預設 60 秒）內完成時觸發。要注意的關鍵日誌行是：

[gateway] listening on :3001

如果你看到 [entrypoint] Starting OpenClaw gateway 但一直沒有看到「listening」那一行，表示 gateway 在前面的某個階段卡住了。

第一步：先看日誌

一切從日誌開始。日誌會準確告訴你 gateway 在哪裡卡住。

# 直接安裝的情況
openclaw logs --tail 50

# Docker 的情況
docker logs <container_name> --tail 50

找出輸出停止前的最後一行。常見模式：

第二步：執行 openclaw doctor

openclaw doctor 指令是專門用來診斷啟動失敗的工具^[2]：

openclaw doctor

它會執行一系列健康檢查，並將結果標記為 OK、WARN 或 FAIL。對於 gateway 就緒性問題，你通常會看到一個或多個 FAIL 項目。

自動修復所有偵測到的問題：

openclaw doctor --fix

--fix 旗標會嘗試安全的、非破壞性的修復：重新生成 token、設定缺少的設定值、清除過期的鎖定檔案。

第三步：針對具體原因進行診斷

原因一：連接埠衝突

最常見的原因。另一個程序——或者前一個沒有正常關閉的 OpenClaw 實例——佔用了 gateway 連接埠。

# 檢查什麼在使用 port 3001
lsof -i :3001

# 在沒有 lsof 的 Linux 上
ss -tlnp | grep 3001

修復：

# 方法 A：終止衝突的程序
kill <PID>

# 方法 B：更換 gateway 連接埠
openclaw config set gateway.port 3002
openclaw restart

原因二：記憶體不足

Gateway 大約需要 256 MB 來啟動。在低記憶體的 VPS（512 MB 或 1 GB），OOM killer 可能在 gateway 完成初始化前就把它終止了。

# 檢查可用記憶體
free -h

# 檢查 OOM killer 是否動手了
dmesg | grep -i "oom\|killed"

修復：

# 如果沒有 swap，新增一個
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 設為開機自動掛載
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

如果是在 Docker 中執行，確保容器至少分配 512 MB：

docker run -d --memory=512m openclaw-stack

原因三：Docker 中啟動緩慢

在容器化環境中，gateway 通常需要 30-40 秒才能完全初始化。預設的 60 秒逾時通常夠用，但在負載較重的主機或較慢的硬體上可能不夠。

修復：

增加 gateway 就緒逾時時間：

openclaw config set gateway.startupTimeout 120
openclaw restart

這會給 gateway 120 秒而不是 60 秒。

原因四：缺少或無效的設定

缺少 gateway.mode 設定會完全阻止啟動。

# 檢查目前的設定
openclaw config get gateway.mode

如果回傳空白或錯誤：

openclaw config set gateway.mode local
openclaw restart

對於在反向代理後面的 Docker 部署，你還需要設定受信任的代理：

openclaw config set gateway.trustedProxies '["127.0.0.1"]'

原因五：過期的鎖定檔案

如果 OpenClaw 崩潰或被強制終止，可能會留下阻止重新啟動的鎖定檔案。

# 檢查鎖定檔案
ls -la ~/.openclaw/*.lock

# 刪除它們
rm ~/.openclaw/*.lock
openclaw restart

原因六：外掛或 Skill 逾時

異常的外掛可能會阻塞整個 gateway 啟動。如果日誌顯示 gateway 卡在外掛載入階段：

# 先停用所有外掛啟動以確認問題
openclaw start --no-plugins

# 如果啟動成功，問題出在外掛
# 逐一重新啟用外掛來找出問題

第四步：終極手段——完全重設

如果以上方法都無效，完全重啟通常可以解決不明的狀態損壞問題：

# 停止所有服務
openclaw stop

# 清除執行時狀態（保留你的設定和記憶）
openclaw reset --keep-config --keep-memory

# 重新啟動
openclaw start

在 Docker 中：

docker stop <container>
docker rm <container>
# 使用相同的環境變數重新建立
docker run -d --name openclaw \
  -e OPENCLAW_GATEWAY_TOKEN=your_token \
  -v openclaw_data:/data \
  openclaw-stack

在 Docker 中設定 OPENCLAW_GATEWAY_TOKEN 環境變數至關重要——沒有它的話，gateway 每次重啟都會重新產生 token，導致裝置配對失效^[3]。

第五步：驗證修復結果

套用任何修復後，確認 gateway 是健康的：

# 檢查狀態
openclaw status

# 執行完整健康檢查
openclaw doctor

# 發送測試訊息
openclaw send "hello"

你應該看到：

OK  gateway is connected
OK  gateway version: x.x.x
OK  all health checks passed

當自架變得心累

如果你發現自己反覆在除錯 gateway 啟動問題——特別是在共享或低資源的 VPS 上——託管服務可以完全消除這些問題。ClawTank 處理容器配置、資源分配、反向代理設定和自動重啟。Gateway 就緒性錯誤根本不會發生，因為基礎設施已經預先配置好並持續監控。

不過自架能給你完全的控制權，對很多使用者來說是正確的選擇。上面的步驟應該能解決絕大多數「did not become ready」錯誤。如果你全部試過還是卡住，OpenClaw 的 GitHub 討論區回覆很快也很有幫助^[4]。

快速檢查清單

• 檢查日誌確認啟動在哪裡卡住
• 執行 openclaw doctor --fix
• 確認 port 3001 沒有連接埠衝突
• 確認至少有 512 MB 可用記憶體
• 如果 Docker 啟動慢，增加 gateway.startupTimeout
• 確保 gateway.mode 設為 local
• 從 ~/.openclaw/ 移除過期的鎖定檔案
• 嘗試 --no-plugins 來排除外掛問題
• 最後手段：openclaw reset --keep-config --keep-memory

References

1. OpenClaw Gateway Architecture Documentation
2. OpenClaw Doctor Command Reference
3. OpenClaw Docker Deployment Guide
4. OpenClaw GitHub Discussions