修復 OpenClaw「Gateway Start Blocked」錯誤 — gateway.mode=local

如果你的 OpenClaw gateway 無法啟動並出現「gateway start blocked」錯誤，你需要設定 gateway.mode。本指南涵蓋此錯誤的所有變體、一行指令的修復方法，以及如何防止它再次發生。

所有「Gateway Start Blocked」錯誤訊息

OpenClaw 會根據你的版本和設定狀態輸出略有不同的訊息。如果你是因為以下任何一種錯誤訊息來到這裡，那你來對地方了：

gateway start blocked: set gateway.mode=local (current: unset)
  or pass --allow-unconfigured

gateway start blocked: set gateway.mode=local --allow-unconfigured

Missing config. Run `openclaw setup` or set gateway.mode=local
  (or pass --allow-unconfigured).

gateway.mode unset — gateway start will be blocked

gateway.mode is unset

ERROR: gateway.mode not configured. Run openclaw setup or set
  gateway.mode=local to start in local-only mode.

missing config: run openclaw setup or set gateway.mode=local

gateway start blocked: gateway.mode is unset — expected local, remote, or hybrid

[gateway] start blocked — config key gateway.mode has no value

這些訊息全都代表同一件事：OpenClaw 在你明確選擇模式之前不會啟動 gateway。這是刻意的安全措施，不是 bug。

30 秒修復

執行一行指令：

openclaw config set gateway.mode local

然後重新啟動：

openclaw restart

完成。你的 gateway 將正常啟動。

如果你正在 openclaw setup 設定精靈中遇到此錯誤，在提示選擇 gateway 模式時輸入 local，精靈會處理剩下的事。

什麼是 gateway.mode？

gateway.mode 設定告訴 OpenClaw gateway 應該監聽哪些網路介面。OpenClaw 不會自動幫你選擇預設值，因為每種模式都有不同的安全影響。

除非你有特定理由，否則請選擇 local。 即使你透過 Caddy 或 Nginx 等反向代理存取 OpenClaw，local 也是正確的，因為代理與 OpenClaw 在同一台機器上，透過 localhost 連線。

設定模式：

# 僅限本地（建議）
openclaw config set gateway.mode local

# 遠端存取
openclaw config set gateway.mode remote

# 兩者皆可
openclaw config set gateway.mode hybrid

你可以隨時驗證目前的設定：

openclaw config get gateway.mode

--allow-unconfigured 是什麼？

錯誤訊息建議使用 --allow-unconfigured 作為替代方案。此旗標會在不儲存任何設定的情況下啟動 gateway 一次：

openclaw gateway start --allow-unconfigured

這在一次性測試或快速除錯時很有用。但下次重新啟動 OpenClaw 時，你會再次看到同樣的「gateway start blocked」錯誤，因為沒有任何設定被儲存。

請改用 openclaw config set gateway.mode local。 這是永久性的設定，你將不會再看到此錯誤。

傳入 --allow-unconfigured 時，gateway 會在該次工作階段預設為僅限本地模式，不會開啟遠端存取。

Docker 使用者

如果你在 Docker 中執行 OpenClaw，請透過環境變數而非設定指令來設定模式：

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

或在 docker-compose.yml 中：

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_MODE=local

對於在反向代理後方的 Docker 容器，還需要設定受信任的代理，讓 gateway 接受轉發的連線：

environment:
  - OPENCLAW_GATEWAY_MODE=local
  - OPENCLAW_GATEWAY_TRUSTED_PROXIES=127.0.0.1

如果你要 exec 進入正在執行的容器，仍然可以使用 CLI：

docker exec -it <container> openclaw config set gateway.mode local
docker exec -it <container> openclaw restart

仍然無法啟動？其他原因

如果你已經設定了 gateway.mode，但 gateway 仍然無法啟動，問題出在其他地方。執行診斷：

openclaw doctor

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

openclaw doctor --fix

除了 gateway.mode 以外的常見原因：

連接埠衝突

另一個程序正在使用 gateway 的連接埠（預設 3001）。檢查並更換：

# 查看哪個程序佔用了該連接埠
lsof -i :3001

# 切換到其他連接埠
openclaw config set gateway.port 3002
openclaw restart

設定檔損壞

損壞的設定檔即使已設定 gateway.mode 也可能阻止啟動：

# 驗證設定
openclaw config validate

# 如果驗證失敗，重設設定並重新配置
openclaw config reset
openclaw setup

權限問題

設定目錄或資料檔案無法被目前使用者寫入：

ls -la ~/.openclaw/

# 如有需要，修復擁有權
sudo chown -R $(whoami) ~/.openclaw/

殘留的 PID 檔案

先前的異常結束留下了 PID 檔案，導致無法正常啟動：

rm ~/.openclaw/gateway.pid
openclaw restart

驗證是否正常運作

套用修復後，確認 gateway 正在執行：

openclaw status

你應該在輸出中看到 gateway: running。如需更多細節，查看日誌：

openclaw logs --tail 20

看到 [gateway] listening on 這行就表示 gateway 已完全啟動並正在接受連線。如果你看到這行，修復就成功了。

常見問題

為什麼 OpenClaw 不直接預設為 local 模式？

OpenClaw 將 gateway 模式視為安全關鍵設定。如果在不通知的情況下默認選擇，可能會讓 gateway 暴露在非預期的網路介面上。透過強制要求明確選擇，OpenClaw 確保你清楚知道你的實例可以從何處被存取。

我設定了 gateway.mode 但重新開機後仍然出現錯誤

請確認你使用的是 openclaw config set gateway.mode local（而非只是在 shell 中設定環境變數）。config 指令會寫入 ~/.openclaw/config.yaml，此檔案在重新開機後仍會保留。執行 openclaw config get gateway.mode 確認設定已被儲存。

gateway.mode=local 可以搭配 Cloudflare Tunnel / ngrok 使用嗎？

可以。Cloudflare Tunnel 和 ngrok 都是透過 localhost 連線到你的 gateway，所以 local 模式是正確的。你不需要為隧道服務使用 remote 模式。

可以不重新啟動就更改 gateway.mode 嗎？

不行。Gateway 在啟動時讀取模式設定。更改設定後，請執行 openclaw restart 來套用。

openclaw setup 和 openclaw config set 有什麼差別？

openclaw setup 是一個互動式設定精靈，會引導你完成所有設定選項，包括 gateway 模式、API 金鑰和整合服務。openclaw config set gateway.mode local 則是直接只更改 gateway 模式。兩者最終都會寫入同一個設定檔。

我在 CI/CD 流水線中遇到「gateway start blocked」

在 CI 中傳入 --allow-unconfigured，因為沒有持久化的設定。或者在你的流水線定義中設定 OPENCLAW_GATEWAY_MODE=local 環境變數。任一方法都可以避免互動式設定。

厭倦了除錯 gateway 設定？ClawTank 提供完整配置好的 OpenClaw 實例——不到一分鐘即可部署，無需終端機操作。