所有 OpenClaw Gateway 錯誤 — 完整修復指南 [2026]

本指南涵蓋你在 OpenClaw 中會遇到的所有 gateway 錯誤。每個章節都是獨立的：找到你的錯誤訊息、複製修復指令、搞定收工。如果你需要某個錯誤的更深入說明，可以點擊連結前往專門的指南。

目錄

• Gateway Start Blocked
• Gateway Did Not Become Ready
• Device Token Mismatch
• Connect Failed
• Send Failed: Gateway Not Connected
• Disconnected (4008)
• Access Not Configured
• Pairing Required
• Docker Gateway 疑難排解
• 終極手段：完全重置
• 預防檢查清單
• 直接跳過 Gateway 設定

Gateway Start Blocked

最常見的 OpenClaw gateway 錯誤。Gateway 因為 gateway.mode 未設定而拒絕啟動。

錯誤訊息

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 config set gateway.mode local
openclaw restart

對大多數人來說，這就是全部的修復步驟。Gateway 現在可以啟動了。

什麼是 gateway.mode？

這個設定控制 gateway 監聽哪些網路介面。OpenClaw 拒絕自動選擇預設值，因為每種模式有不同的安全影響。

除非你有特定理由選擇其他選項，否則選 local。即使在反向代理後面，local 也是正確的，因為代理是透過 localhost 連線。

Docker 使用者

透過環境變數設定模式：

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

或在 docker-compose.yml 中：

environment:
  - OPENCLAW_GATEWAY_MODE=local

完整深入說明請參閱我們的專門指南：修復 OpenClaw 的 "Gateway Start Blocked"。

Gateway Did Not Become Ready

Gateway 程序已啟動，但從未完成初始化。

錯誤訊息

gateway did not become ready

Error: gateway did not become ready within 60s

gateway startup timeout — did not become ready

[entrypoint] gateway did not become ready in time

timeout waiting for gateway: did not become ready

FAIL: gateway health check failed — not ready

原因 1：Port 衝突

另一個程序正在使用 gateway 的 port（預設 3001）。

診斷：

lsof -i :3001

修復：

# 終止衝突的程序，或切換 port
openclaw config set gateway.port 3002
openclaw restart

原因 2：權限問題

OpenClaw 的資料目錄或設定檔無法寫入。

診斷：

ls -la ~/.openclaw/

修復：

sudo chown -R $(whoami) ~/.openclaw/
openclaw restart

原因 3：設定檔損壞

損壞的 openclaw.json 或 config.yaml 導致無法初始化。

修復：

openclaw config validate

如果驗證失敗：

openclaw doctor --fix
openclaw restart

如果 doctor --fix 無法修復設定：

openclaw config reset
openclaw setup

原因 4：啟動緩慢（Docker）

在 Docker 容器中，gateway 大約需要 40 秒才能完全初始化。日誌中出現 [entrypoint] Starting OpenClaw gateway 不代表 gateway 已就緒。你必須等到出現這一行：

[gateway] listening on :3001

只有在這行出現後，gateway 才會開始接受連線。如果你在撰寫腳本或做輪詢，請等到這個字串出現後再發送請求。

檢查啟動進度：

openclaw logs --follow

原因 5：記憶體不足

Gateway 至少需要 256MB 的可用 RAM。

檢查：

free -h       # Linux
vm_stat       # macOS

如果系統記憶體不足，請停止其他程序或增加 VM/容器的記憶體限制。

原因 6：殘留的 PID 檔案

之前的崩潰留下了 PID 檔案，阻礙了正常啟動。

修復：

rm ~/.openclaw/gateway.pid
openclaw restart

Device Token Mismatch

你的裝置（瀏覽器、Telegram bot、手機 app）上儲存的 token 與 gateway 預期的不再一致。

錯誤訊息

device token mismatch

connect failed: device token mismatch

disconnected (4008): connect failed — device token mismatch

openclaw gateway device token mismatch

Error: device token mismatch — please re-pair this device

WebSocket connection failed: device token mismatch

connect failed (4008): device identity rejected

快速修復

openclaw doctor --fix && openclaw restart

這會重新產生匹配的 token 並重啟 gateway。大多數情況下都能解決問題。

手動修復：移除並重新核准

如果 doctor --fix 無法解決：

# 列出所有裝置
openclaw devices list

# 移除有問題的裝置
openclaw devices remove DEVICE_ID

# 重啟 gateway
openclaw restart

然後從你的瀏覽器或 Telegram 重新連線。會出現新的配對請求：

openclaw devices approve NEW_DEVICE_ID

預防：固定你的 Gateway Token

OpenClaw 在每次重啟時都會重新產生 gateway token，除非你將它固定。固定一次，token mismatch 就不會再發生：

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

或透過環境變數（Docker 建議使用此方式）：

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

完整步驟（包含 Docker Compose 設定）請參閱：修復 OpenClaw 的 "Device Token Mismatch"。

Connect Failed

你的用戶端可以看到 gateway 位址，但無法建立連線。

錯誤訊息

connection error

gateway connect failed

Error: connect ECONNREFUSED 127.0.0.1:3001

connect failed: connection refused

WebSocket connection to 'ws://localhost:3001' failed

openclaw connection error: gateway unreachable

failed to connect to gateway at localhost:3001

修復 1：Gateway 未執行

openclaw status

如果顯示 gateway: stopped：

openclaw gateway start

或直接：

openclaw restart

修復 2：Host 或 Port 錯誤

確認你的設定與 gateway 實際監聽的位址一致：

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

預設為 localhost:3001。如果你修改過這些值，請確保你的用戶端、反向代理或 Telegram webhook URL 也對應更新。

修復 3：防火牆阻擋

Linux：

sudo ufw status
# 如果 port 3001 未允許：
sudo ufw allow 3001

macOS：

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

修復 4：反向代理設定錯誤

如果你使用 Caddy、Nginx 或 Traefik，代理可能沒有正確轉發。最常見的錯誤是忘記設定 trustedProxies：

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

完整的反向代理設定請參閱我們的反向代理與 trusted proxies 指南。

Send Failed: Gateway Not Connected

你嘗試發送訊息（透過 Telegram、API、瀏覽器），但發送時 gateway 連線已斷開。

錯誤訊息

send failed: gateway not connected

Error: send failed — gateway not connected

send failed: Error: gateway not connected

message delivery failed: gateway not connected

[telegram] send failed: gateway not connected

Error: cannot send — no active gateway connection

原因 1：Gateway 在工作階段中途崩潰

Gateway 在你連線時正在執行，但之後崩潰了。

修復：

openclaw restart

檢查崩潰原因：

openclaw logs --tail 100

在輸出中尋找 panic、fatal、OOM 或 killed。

原因 2：網路中斷

你的用戶端與 gateway 之間的連線中斷。這在不穩定的網路環境或伺服器 IP 變更時很常見。

修復：

# 確認 gateway 可連線
curl -v http://localhost:3001/health

# 如果無法連線，重啟
openclaw restart

原因 3：Gateway 被程序管理器停止

PM2、systemd 或 Docker 的重啟策略可能已停止了 gateway。

# PM2
pm2 status

# systemd
systemctl status openclaw

# Docker
docker ps -a | grep openclaw

透過你的程序管理器重啟並監控日誌：

openclaw logs --follow

等到出現 [gateway] listening on 後再重試發送訊息。

Disconnected (4008)

WebSocket 錯誤碼 4008 代表協定層級的斷線。通常與 device token mismatch 或連線逾時有關。

錯誤訊息

disconnected (4008): connect failed

disconnected (4008): connect failed — device token mismatch

disconnected (4008): device identity rejected

WebSocket closed with code 4008

connection closed: 4008

與 Token 有關的情況

這是 device token mismatch。請跳到上面的 Device Token Mismatch 章節。

與逾時有關的情況

WebSocket 連線因閒置或網路問題而逾時。

修復：

# 檢查網路連線
ping your-openclaw-host
curl -v http://localhost:3001/health

# 重啟 gateway
openclaw restart

如果頻繁斷線，檢查以下情況：

• 網路不穩定——用戶端與伺服器之間的連線品質
• 防火牆或代理逾時——中斷閒置的 WebSocket 連線（許多代理會在 60 秒後關閉閒置連線）
• 記憶體壓力——OOM killer 終止了 gateway 程序

針對會關閉閒置連線的代理，請在代理中設定 WebSocket ping/pong keep-alive：

# Caddy 範例
reverse_proxy localhost:3001 {
    transport http {
        keepalive 30s
    }
}

Access Not Configured

Gateway 未設定為接受 web 或 API 連線。

錯誤訊息

OpenClaw: access not configured.

Error: web login provider is not available.

Device identity required.

TUI gateway disconnected — closed idle.

快速修復

openclaw config set gateway.mode local
openclaw restart

如果你從其他機器存取：

openclaw config set gateway.mode remote
openclaw config set gateway.host "0.0.0.0"
openclaw restart

"Web Login Provider Is Not Available"

這表示 web 身份驗證已停用。設定 gateway 模式：

openclaw config set gateway.mode local
openclaw restart

"TUI Gateway Disconnected — Closed Idle"

終端 UI 連線逾時。重啟並重新開啟：

openclaw restart
openclaw tui

完整的存取設定指南請參閱：OpenClaw "Access Not Configured" 修復。

Pairing Required

每個連線到 OpenClaw 的新瀏覽器或裝置都需要核准。這是安全功能，不是錯誤。

錯誤訊息

pairing required

device not paired — approve this device to connect

Error: device identity required

new device detected — waiting for approval

[gateway] pairing request from device DEVICE_ID

Telegram pairing required — approve code XXXXXX

修復：核准裝置

瀏覽器或 API 用戶端：

openclaw devices list
openclaw devices approve DEVICE_ID

Telegram bot：

openclaw pairing approve telegram CODE

你可以在 Telegram 對話或 gateway 日誌中看到配對碼：

openclaw logs --tail 20

查看所有裝置

openclaw devices list

這會顯示所有已配對的裝置、其狀態（connected、pending、disconnected）和 ID。

移除裝置

如果某個裝置不應再有存取權限：

openclaw devices remove DEVICE_ID

Docker Gateway 疑難排解

Docker 在你的用戶端和 gateway 之間增加了一層。以下是最常見的 Docker 特定問題。

Gateway 啟動了但從容器外部無法連線

Gateway 綁定到容器內的 127.0.0.1，從 host 無法存取。

修復：

docker exec -it YOUR_CONTAINER openclaw config set gateway.bind "0.0.0.0"
docker restart YOUR_CONTAINER

Port 未映射

容器的 port 未暴露給 host。

檢查：

docker port YOUR_CONTAINER

修復： 使用正確的 port 映射重新執行：

docker run -p 3001:3001 openclaw-stack

或在 docker-compose.yml 中：

ports:
  - "3001:3001"

容器重啟會重新產生 Gateway Token

每次 Docker 容器重啟時，gateway 都會產生新的 token。這會使所有已配對的裝置失效。

修復： 透過環境變數固定 token：

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-stable-token-here
    volumes:
      - openclaw-data:/app/data

volumes:
  openclaw-data:

資料在重建後未保留

沒有掛載 volume 的話，重建容器會清除所有設定、裝置配對和記憶。

修復： 掛載資料目錄：

volumes:
  - openclaw-data:/app/data

在 Docker 中執行 openclaw doctor

docker exec -it YOUR_CONTAINER bash
openclaw doctor --fix
exit
docker restart YOUR_CONTAINER

Docker 中啟動緩慢

Gateway 在 Docker 中大約需要 40 秒才能就緒。在日誌中看到以下這行之前，不要發送請求：

[gateway] listening on :3001

監控啟動進度：

docker logs -f YOUR_CONTAINER

終極手段：完全重置

當 openclaw doctor --fix 沒有用、移除裝置沒有用、修改設定也沒有用，而你需要完全從頭開始。

警告： 這會移除你的設定、已配對裝置、記憶和儲存的資料。你需要重新輸入 API key、重新配對裝置，以及重新設定整合。

原生安裝

# 1. 停止所有程序
openclaw gateway stop
pkill -f openclaw

# 2. 備份重要資料（選用）
cp ~/.openclaw/openclaw.json ~/openclaw-backup.json
cp -r ~/.openclaw/memory ~/openclaw-memory-backup

# 3. 移除資料目錄
rm -rf ~/.openclaw

# 4. 從頭開始設定
openclaw setup

Docker

# 1. 停止並移除容器
docker stop YOUR_CONTAINER
docker rm YOUR_CONTAINER

# 2. 移除資料 volume（警告：會銷毀所有資料）
docker volume rm openclaw-data

# 3. 重新啟動
docker run -d \
  -p 3001:3001 \
  -e OPENCLAW_GATEWAY_MODE=local \
  -e OPENCLAW_GATEWAY_TOKEN=your-stable-token \
  -v openclaw-data:/app/data \
  openclaw-stack

重置後，執行 openclaw setup 或透過環境變數設定你的設定，然後重新核准你的裝置。

完整步驟請參閱：OpenClaw 完全重置指南。

預防檢查清單

在 gateway 錯誤發生之前就阻止它們。

• 固定你的 gateway token。 將 OPENCLAW_GATEWAY_TOKEN 設為環境變數，或執行 openclaw config set gateway.token "your-stable-token"。這可以防止重啟時 token 被重新產生，消除 device token mismatch 錯誤。

• 明確設定 gateway.mode。 執行一次 openclaw config set gateway.mode local，你就再也不會看到 "gateway start blocked" 了。

• 持久化你的資料目錄。 對 Docker 來說，在 /app/data 掛載一個 volume。沒有這個的話，每次容器重建都會清除設定、配對和記憶。

• 更新後執行 openclaw doctor。 主要版本升級可能會改變設定格式或 token 結構。openclaw doctor --fix 會自動偵測並修復這些問題。

• 使用 openclaw status 監控。 將 openclaw status 加入你的健康檢查腳本或 Docker HEALTHCHECK 指令。在使用者回報問題之前就發現問題。

• 每台機器只執行一個實例。 在同一台機器上使用相同的資料目錄執行多個 OpenClaw 實例會導致 token 衝突和間歇性錯誤。

• 設定 WebSocket keep-alive。 如果你使用反向代理，設定 keep-alive 間隔以防止閒置連線逾時導致 disconnected (4008) 錯誤。

• 重大變更後清除瀏覽器快取。 如果你更改了 gateway URL、域名或 token，請清除每個連線到 OpenClaw 的瀏覽器的網站資料。

直接跳過 Gateway 設定

本指南中的每個錯誤歸根結底都是同一件事：管理 gateway 是手動工作。你需要設定模式、固定 token、映射 port、核准裝置、修復 mismatch，然後在出問題時重啟。

ClawTank 會自動處理這一切。Gateway 啟動、健康檢查、token 管理、裝置配對、TLS 和重新連線都由系統為你管理。在一分鐘內部署一個 OpenClaw 實例，從任何裝置連線，完全不需要碰終端機。