ClawTank
所有文章
修復 OpenClaw 儀表板無法運作：Web UI 與 TUI 疑難排解指南

修復 OpenClaw 儀表板無法運作：Web UI 與 TUI 疑難排解指南

|4 分鐘閱讀

如果你的 OpenClaw 儀表板無法載入、TUI 顯示「gateway disconnected」，或者你看到「Web login provider is not available」的錯誤，本指南涵蓋所有常見原因及修復方式。我們會從最常見的問題開始，依序處理。

「Web Login Provider Is Not Available」

這是最常被回報的儀表板錯誤。它代表 OpenClaw 的 Web 介面無法驗證你的工作階段。

原因 1：Gateway 模式未設為 Local

Gateway 需要在 local 模式下運行，Web UI 才能正常運作。

openclaw config get gateway.mode

如果回傳的不是 local，修正它：

openclaw config set gateway.mode "local"
openclaw restart

原因 2：Gateway 尚未完全啟動

Web UI 依賴 gateway 行程。如果 gateway 尚未啟動完成，登入提供者還不可用。

檢查日誌中的就緒訊號：

openclaw logs --tail 30

找 [gateway] listening on 這行。如果你只看到 [entrypoint] Starting OpenClaw gateway，gateway 還在啟動中——大約需要 40 秒。等一下再試。

原因 3：連接埠衝突

其他行程正在使用 gateway 的連接埠（預設 3001）：

lsof -i :3001

如果有其他東西正在監聽該連接埠，停掉那個行程或更改 OpenClaw 的連接埠：

openclaw config set gateway.port 3002
openclaw restart

然後使用新的連接埠存取儀表板。

TUI 顯示「Gateway Disconnected」

TUI（終端使用者介面）透過本地 socket 連接到 gateway。「Gateway disconnected」代表 TUI 無法連線到 gateway 行程。

修復 1：重新啟動 Gateway

openclaw gateway stop
# 等待 5 秒
openclaw gateway start

然後重新啟動 TUI：

openclaw

修復 2：檢查 Gateway 是否正在運行

openclaw status

如果 gateway 沒有在運行，啟動它：

openclaw gateway start

如果啟動失敗，檢查錯誤：

openclaw logs --tail 50

修復 3：過期的 PID 檔案

有時候 gateway 行程終止了但留下 PID 檔案，阻止乾淨的重新啟動。

openclaw doctor --fix

這會偵測並移除過期的 PID 檔案，然後乾淨地重啟 gateway。

修復 4：Docker 特有的 TUI 問題

如果在 Docker 中運行，TUI 需要連接到容器內部的 gateway：

docker exec -it YOUR_CONTAINER_NAME openclaw

不要嘗試從容器外部運行 TUI——它無法連到 gateway socket。

儀表板載入了但顯示空白頁面

原因 1：JavaScript 錯誤

打開瀏覽器的開發者控制台（F12 或 Cmd+Shift+J）並檢查錯誤。常見問題：

  • CORS 錯誤 — 儀表板 URL 與設定的 gateway URL 不符
  • 混合內容 — 透過 HTTPS 存取但 gateway 使用 HTTP
  • 模組載入錯誤 — 瀏覽器快取過期

修復：清除瀏覽器快取

OpenClaw 更新後，過期的快取是空白儀表板頁面最常見的原因。

  1. 強制重新整理：Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（Mac）
  2. 如果沒用，清除網站資料：
    • Chrome：設定 → 隱私權 → 清除瀏覽資料 → 快取的圖片和檔案
    • Firefox：設定 → 隱私權 → 清除資料 → 快取的網頁內容

原因 2：不完整的更新

如果你更新了 OpenClaw 但儀表板仍顯示舊的資源：

# 在 Docker 中
docker compose pull
docker compose up -d --force-recreate

# 裸機安裝
openclaw update
openclaw restart

儀表板載入了但無法連線到 Gateway

你看到登入頁面或儀表板介面，但它顯示「Connecting...」或「Connection failed」。

原因 1：瀏覽器中的 Gateway URL 錯誤

儀表板嘗試連接到嵌入設定中的 gateway URL。如果你從預期之外的 URL 存取：

openclaw config get gateway.url

確保這與你在瀏覽器中使用的 URL 相符。如果你透過 https://openclaw.mydomain.com 存取 OpenClaw，gateway URL 需要一致。

原因 2：反向代理未轉發 WebSocket

OpenClaw 使用 WebSocket 連線在儀表板和 gateway 之間進行即時通訊。許多反向代理設定預設不會轉發 WebSocket 流量。[1]

Caddy 會自動處理 WebSocket 轉發——不需要額外設定。

Nginx 需要明確設定 WebSocket 標頭：

location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Upgrade 和 Connection 標頭至關重要。缺少它們，WebSocket 連線會靜默失敗，儀表板看起來載入了但永遠連不上。

原因 3：Trusted Proxies 未設定

如果 OpenClaw 在反向代理（Caddy、Nginx、Traefik）後方，它需要知道這點[2]：

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

缺少這個設定，安全稽核會標記 trusted_proxies_missing，某些功能（包括 Web 用戶端偵測）可能無法正確透過代理運作。

需要裝置批准

從新瀏覽器連線時，OpenClaw 需要裝置批准。如果儀表板載入了但顯示「Device identity required」：

# 列出待批准的裝置
openclaw devices list

# 批准裝置
openclaw devices approve DEVICE_ID

在 Docker 中：

docker exec -it YOUR_CONTAINER_NAME openclaw devices approve DEVICE_ID

批准後，重新整理瀏覽器頁面。

瀏覽器相容性

OpenClaw 的 Web 儀表板需要現代瀏覽器。已知問題：

瀏覽器 狀態
Chrome 100+ 完整支援
Firefox 100+ 完整支援
Safari 16+ 完整支援
Edge 100+ 完整支援
Safari < 16 WebSocket 問題
Internet Explorer 不支援
Brave（嚴格防護模式） 可能阻擋 WebSocket；請允許該網域

隱私/無痕模式

儀表板可以在隱私瀏覽模式下使用，但每次都需要重新進行裝置批准，因為 Cookie 不會在工作階段之間保留。

會干擾的瀏覽器擴充功能

某些擴充功能可能會破壞儀表板的運作：

  • 廣告阻擋器 — 可能阻擋 WebSocket 連線。將儀表板網域加入允許清單。
  • 隱私保護擴充功能（uBlock Origin、Privacy Badger）— 可能阻擋與 gateway 的連線。將網域加入白名單。
  • VPN 擴充功能 — 可能導致憑證不符。在儀表板網域上停用。

HTTPS / SSL 問題

「Your Connection Is Not Private」

如果你看到憑證警告：

  1. 自簽憑證 — 你的反向代理沒有使用有效的 TLS 憑證。用 Caddy 來自動取得 Let's Encrypt 憑證。
  2. 憑證過期 — 檢查你的憑證續期。Caddy 自動續期；Certbot 可能需要 cron 排程。
  3. 網域不符 — 憑證是給不同網域的，不是你正在存取的那個。

混合內容錯誤

如果儀表板在 HTTPS 上載入但嘗試透過 HTTP 連接 gateway：

openclaw config set gateway.url "https://your-domain.com"
openclaw restart

所有連線必須使用相同的協定。你無法在 HTTPS 上載入儀表板然後透過 HTTP 連接 gateway。

最後手段：完整重置

如果其他方法都無效，你需要一個乾淨的起點：

# 先備份你的資料
cp -r /app/data /app/data-backup

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

# 如果還是壞的，恢復原廠設定（保留記憶）
openclaw factory-reset --keep-memories

# 重新啟動
openclaw restart

請參閱我們的恢復原廠設定指南了解完整流程，以及它會保留和不保留什麼。

快速診斷清單

儀表板無法運作時，依照這個清單排查：

  1. OpenClaw 是否在運行？→ openclaw status
  2. Gateway 是否就緒？→ 檢查日誌中的 [gateway] listening on
  3. 連接埠是否可存取？→ curl http://localhost:3001/health
  4. 反向代理是否正確轉發？→ curl -I https://your-domain.com
  5. Trusted proxies 是否已設定？→ openclaw config get gateway.trustedProxies
  6. 裝置是否已批准？→ openclaw devices list
  7. 瀏覽器快取是否過期？→ 強制重新整理（Ctrl+Shift+R）
  8. 瀏覽器擴充功能是否干擾？→ 在無痕模式下測試

跳過基礎設施煩惱

大多數儀表板問題來自反向代理設定錯誤、連接埠衝突或 TLS 設定問題——這些都是基礎設施的問題，與實際使用 OpenClaw 無關。

ClawTank 自動處理反向代理、TLS、連接埠分配和裝置管理。你的 OpenClaw 實例從建立的那一刻起就可以透過穩定的 HTTPS URL 存取。不需要代理設定、不需要連接埠除錯、不需要憑證管理。

References

  1. MDN Web Docs — WebSocket API
  2. OpenClaw 反向代理與 Trusted Proxies 指南
  3. OpenClaw Doctor 指令參考
  4. OpenClaw 恢復原廠設定指南
  5. Caddy — Reverse Proxy Documentation

準備好部署 OpenClaw 了嗎？

不需要 Docker、SSH、DevOps。不到 1 分鐘即可部署。

免費開始使用