OpenClaw Gateway 錯誤：完整故障排除流程圖 [2026]

OpenClaw gateway 的錯誤看起來都很類似，但根本原因各不相同。這份流程圖幫助你精確辨識你遇到的錯誤，並直接跳到解決方案。在下表中找到你的錯誤訊息，然後點選連結前往對應的段落。

找到你的錯誤

診斷流程圖

在深入個別錯誤之前，先試試通用的急救指令：

openclaw doctor --fix && openclaw restart

這能自動解決大約 70% 的 gateway 問題。如果沒有修復你的問題，在下方找到你的特定錯誤。

1. Gateway Start Blocked

你會看到的錯誤訊息：

gateway start blocked: set gateway.mode=local (current: unset)

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

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

原因： OpenClaw 要求你在 gateway 啟動之前明確設定 gateway.mode。這是一項安全措施——gateway 拒絕猜測它應該監聽哪些網路介面。

快速修復：

openclaw config set gateway.mode local
openclaw restart

Docker 部署的話，透過環境變數設定：

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

大部分情況選擇 local，包括在反向代理後方的設定。只有當區域網路上的裝置需要直接存取時，才選擇 remote。

完整細節請參閱 修復 OpenClaw 的「Gateway Start Blocked」。

2. Gateway Not Connected / Send Failed

你會看到的錯誤訊息：

send failed: error: gateway not connected

[telegram] send failed: gateway not connected

Error: connect ECONNREFUSED 127.0.0.1:3001

原因： Gateway 行程已崩潰、被作業系統終止（OOM kill），或正在執行但因為連接埠或防火牆問題而無法連線。

快速修復：

# 檢查 gateway 是否正在執行
openclaw status

# 重新啟動
openclaw restart

# 驗證是否已恢復
curl -s http://localhost:3001/health

如果 gateway 持續崩潰，檢查日誌找出根本原因：

openclaw logs --tail 100

常見的日誌模式：Killed（OOM）、EADDRINUSE（連接埠衝突）、或 SQLITE_CANTOPEN（磁碟/權限問題）。

完整細節請參閱 修復「Send Failed: Gateway Not Connected」。

3. Gateway Did Not Become Ready

你會看到的錯誤訊息：

gateway did not become ready within 60s

[entrypoint] gateway did not become ready in time

FAIL: gateway health check failed — not ready

原因： Gateway 行程已啟動但未能完成初始化。通常是因為連接埠衝突、記憶體不足、設定檔損壞，或 Docker 環境中啟動速度較慢。

快速修復：

# 檢查連接埠衝突
lsof -i :3001

# 如果有衝突，變更連接埠
openclaw config set gateway.port 3002

# 清除過期狀態並重啟
rm -f ~/.openclaw/gateway.pid ~/.openclaw/*.lock
openclaw restart

在 Docker 中，gateway 大約需要 40 秒才能初始化完成。在日誌顯示 [gateway] listening on :3001 之前不要傳送請求。如果預設的 60 秒逾時不夠，可以增加：

openclaw config set gateway.startupTimeout 120

完整細節請參閱 修復「Gateway Did Not Become Ready」。

4. Gateway Restart Timed Out

你會看到的錯誤訊息：

gateway restart timed out

Error: restart timed out — gateway did not stop within 30s

restart failed: old gateway process still running

原因： openclaw restart 指令向正在執行的 gateway 發送關閉信號並等待它停止。如果 gateway 卡住（死鎖、正在處理長時間執行的請求，或無回應），它不會在逾時時間內關閉。

快速修復：

# 強制停止 gateway 行程
openclaw gateway stop --force

# 如果 PID 檔仍然存在，移除它
rm -f ~/.openclaw/gateway.pid

# 重新啟動
openclaw gateway start

如果 gateway 卡在 Docker 容器中：

docker restart YOUR_CONTAINER --time 10

--time 10 參數給容器 10 秒的時間進行優雅關閉，之後 Docker 會發送 SIGKILL^[1]。

預防： 重啟逾時通常表示有記憶體或資源問題。用 free -h 和 df -h 檢查系統資源。如果你在記憶體有限的 VPS 上執行，新增 swap 空間可以防止大部分的 gateway 凍結：

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. Missing Config

你會看到的錯誤訊息：

Missing config. Run `openclaw setup` or set gateway.mode=local

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

ERROR: gateway.mode not configured

原因： 這在功能上與「gateway start blocked」錯誤相同。Gateway 找不到必要的設定值——最常見的是 gateway.mode。

快速修復：

openclaw config set gateway.mode local
openclaw restart

如果設定 gateway.mode 後錯誤仍然存在，執行互動式設定來填入所有必要欄位：

openclaw setup

或執行完整診斷和自動修復：

openclaw doctor --fix
openclaw restart

完整細節請參閱 修復 OpenClaw 的「Gateway Start Blocked」。

6. Gateway Disconnected (4008)

你會看到的錯誤訊息：

disconnected (4008): connect failed — device token mismatch

disconnected (4008): device identity rejected

WebSocket closed with code 4008

原因： WebSocket 關閉代碼 4008 表示 gateway 拒絕了連線裝置的 token。這發生在 gateway 重新產生了 token（通常在沒有固定 token 的情況下重啟後），而客戶端仍持有舊的 token。Docker 使用者在重建容器但沒有持久化 token 時經常遇到這個問題。

快速修復：

openclaw doctor --fix && openclaw restart

如果錯誤持續，移除過期的裝置並重新配對：

openclaw devices list
openclaw devices remove DEVICE_ID
openclaw restart

然後從瀏覽器或 Telegram 重新連線並核准新裝置。

預防： 固定 gateway token 讓它在重啟後持續有效：

openclaw config set gateway.token "your-stable-token-here"

或透過 Docker 環境變數：

docker run -e OPENCLAW_GATEWAY_TOKEN=your-stable-token openclaw-stack

完整細節請參閱 修復 OpenClaw 的「Device Token Mismatch」。

7. GatewayRequestError: Web Login Provider

你會看到的錯誤訊息：

GatewayRequestError: Web Login Provider is not available

Error: web login provider is not available

GatewayRequestError: login provider unavailable for this platform

原因： 當客戶端（通常是 WhatsApp Web 或瀏覽器）嘗試透過 gateway 在目前模式下不支援的登入方式進行驗證時，就會出現這個錯誤。最常見的情境是在 gateway 以無頭模式或在沒有顯示伺服器的 Docker 容器中執行時，嘗試 WhatsApp Web 配對。

WhatsApp Web 驗證需要在瀏覽器環境中掃描 QR 碼。無頭環境（SSH、Docker、CI）無法呈現 QR 碼，所以登入提供者被標記為不可用。

快速修復：

如果你需要在無頭環境中使用 WhatsApp 整合，改用 Telegram 或 API 整合。WhatsApp Web 需要圖形化的瀏覽器工作階段進行初始 QR 配對。

如果你在桌面環境中仍看到此錯誤，確認 gateway 模式已設定：

openclaw config set gateway.mode local
openclaw restart

然後在瀏覽器中開啟 OpenClaw 網頁介面，從那裡嘗試 WhatsApp 配對。

8. GatewayRequestError: Invalid Config

你會看到的錯誤訊息：

GatewayRequestError: Invalid Config

GatewayRequestError: config validation failed

WARN  unknown config key: "model"

原因： Gateway 嘗試處理請求時發現設定檔包含無效、無法辨識或已棄用的鍵值。這通常發生在升級 OpenClaw 到重新命名了設定鍵的新版本後，或是按照過時的設定指南操作時。

快速修復：

openclaw config validate
openclaw doctor --fix
openclaw restart

config validate 指令會列出每個有問題的鍵值。doctor --fix 指令會自動遷移已知的已棄用鍵值（例如 model 改為 ai.model、port 改為 gateway.port）。

完整細節請參閱 修復 OpenClaw 的「Config Validation Failed」。

當什麼方法都沒用的時候

如果你已經嘗試了特定錯誤的修復方式但 gateway 仍然不配合，執行以下通用診斷流程：

# 1. 含詳細輸出的完整診斷
openclaw doctor --fix --verbose

# 2. 檢查日誌找出真正的錯誤
openclaw logs --tail 100

# 3. 驗證系統資源
free -h && df -h

# 4. 檢查殭屍行程
ps aux | grep openclaw

# 5. 最後手段：乾淨重啟
openclaw gateway stop --force
rm -f ~/.openclaw/gateway.pid ~/.openclaw/*.lock
openclaw gateway start

# 6. 監控啟動過程以確認
openclaw logs --follow

等待 [gateway] listening on :3001 出現後再測試連線。如果在清除狀態後乾淨重啟 gateway 仍無法啟動，問題幾乎肯定是系統層級的資源限制（磁碟已滿、記憶體不足，或行程管理器衝突）。

跳過故障排除

本指南中的每個錯誤都源自同一個根本問題：gateway 管理是手動工作。你要設定模式、固定 token、對應連接埠、核准裝置、監控崩潰，還要出問題時進行除錯。

ClawTank 幫你處理這一切。Gateway 啟動、健康監控、token 持久化、裝置配對、TLS 和自動重啟都是開箱即用的。不到一分鐘部署一個 OpenClaw 實例，完全跳過這份流程圖。

參考資料

1. Docker stop reference -- graceful shutdown and SIGKILL
2. OpenClaw GitHub issues -- gateway error reports
3. Node.js process signal handling
4. Docker container networking overview