OpenClaw Gateway 連線錯誤：診斷與修復指南

Gateway 連線錯誤是 OpenClaw 第二常見的問題類型。本指南涵蓋你可能遇到的每一種 gateway 連線錯誤以及修復方法。

"Gateway Did Not Become Ready"

這代表 gateway 程序已啟動，但從未完成初始化。

常見原因

1. 連接埠衝突

另一個程序正在使用 gateway 的連接埠：

# 檢查什麼程序佔用了 port 3001
lsof -i :3001

修復方法：

# 終止衝突的程序，或更換連接埠
openclaw config set gateway.port 3002
openclaw restart

2. 缺少設定

Gateway 需要設定 gateway.mode：

openclaw config set gateway.mode local
openclaw restart

3. 啟動緩慢（Docker）

在 Docker 容器中，gateway 需要大約 40 秒才能完全啟動。日誌中出現的 [entrypoint] Starting OpenClaw gateway 不代表已經就緒。請等待以下訊息：

[gateway] listening on :3001

4. 記憶體不足

Gateway 需要至少 256MB 的可用 RAM。檢查方法：

free -h  # Linux
vm_stat  # macOS

診斷步驟

# 檢查 gateway 狀態
openclaw status

# 檢查日誌中的具體錯誤
openclaw logs --tail 50

# 執行診斷工具
openclaw doctor --verbose

"Connection Error" / "Gateway Connect Failed"

Gateway 正在運行，但你的用戶端無法連接到它。

檢查 1：Gateway 是否確實在運行

openclaw status

如果顯示 gateway: stopped，啟動它：

openclaw gateway start

檢查 2：主機和連接埠設定

openclaw config get gateway.host
openclaw config get gateway.port

預設值是 localhost:3001。如果你改過這些設定，請確保你的用戶端設定一致。

檢查 3：防火牆

# Linux — 檢查連接埠是否開放
sudo ufw status

# macOS — 檢查應用程式是否被允許
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

檢查 4：反向代理

如果你在 Caddy、Nginx 或 Traefik 後面運行，代理可能沒有正確轉發請求。請參閱我們的反向代理設定指南。

"Disconnected (4008): Connect Failed"

錯誤碼 4008 特別表示裝置 token 不匹配。裝置儲存的 token 與 gateway 預期的不符。

快速修復：

openclaw doctor --fix
openclaw restart

詳細步驟請參閱我們的裝置 token 不匹配修復指南。

"Send Failed: Error: Gateway Not Connected"

當你嘗試透過 Telegram、API 等傳送訊息，但 gateway 連線已中斷時，就會出現此錯誤。

逐步修復

1. 檢查 gateway 狀態：

   openclaw status
   

2. 如果已停止，重新啟動：

   openclaw restart
   

3. 如果正在運行但仍然失敗，檢查日誌：

   openclaw logs --follow
   

   尋找驗證錯誤、連接埠衝突或崩潰循環。

4. 執行 doctor：

   openclaw doctor --fix
   

Gateway 持續斷線

如果 gateway 可以連線但頻繁斷開：

原因 1：記憶體壓力

當系統記憶體不足時，gateway 程序會被強制終止（Linux 的 OOM killer）。

# 檢查系統記憶體
free -h

# 檢查 OOM killer 是否曾經觸發
dmesg | grep -i "out of memory"

原因 2：程序管理器重啟

如果你使用 PM2、systemd 或 Docker 重啟策略，設定變更可能導致重啟循環。

# 檢查 PM2 日誌
pm2 logs openclaw

# 檢查 systemd 狀態
systemctl status openclaw

原因 3：網路不穩定

對於遠端連線，封包遺失或 DNS 問題可能導致斷線。

# 測試連線
ping your-openclaw-host
curl -v http://localhost:3001/health

通用除錯流程

對於任何無法立即辨識的 gateway 連線錯誤：

# 1. 執行診斷
openclaw doctor --fix --verbose

# 2. 檢查完整日誌
openclaw logs --tail 100

# 3. 驗證設定
openclaw config validate

# 4. 終極手段：完全重啟
openclaw gateway stop
sleep 5
openclaw gateway start

# 5. 監控啟動過程
openclaw logs --follow

在測試連線之前，請等待 [gateway] listening on 出現。

零 Gateway 煩惱

ClawTank 自動管理 gateway 生命週期——啟動、健康檢查、重新連線和 token 管理。你的 OpenClaw 實例無需手動干預就能保持連線。