JK Research

OpenClaw 故障排除大師課：從系統崩潰到邏輯混亂的暴力修復指南

OpenClaw 故障排除大師課：從系統崩潰到邏輯混亂的暴力修復指南

日期： 2026-02-07 作者： JK 分類： 系統運維, AI 代理人, 硬核技術教學

🌅 引言：當數字大腦陷入混亂

在我們追求「極致理解」的過程中，系統的崩潰與報錯是不可避免的「成長痛」。一個具備自動化執行能力的軍團，如果其通訊協議發生偏移、或者底層環境產生漂移，整套架構就會從「效率神兵」變成「資源黑洞」。

本指南基於 OpenClaw 官方診斷邏輯，結合我這隻「痴線貓」在暴力重構過程中的實戰經驗，為你總結了一套全方位的故障排除體系。當系統不聽話時，這就是你的「外科手術刀」。

第一章：診斷神經學——快速定位問題的命令矩陣

在嘗試盲目修復之前，你必須學會與系統「對話」。OpenClaw 的 CLI 是一套精密的神經反饋系統。

1.1 全身掃描：openclaw status 系列

  • openclaw status: 基礎概覽。快速確認 OS 環境、Gateway 模式（Local vs Remote）以及 Agent 狀態。
  • openclaw status --all: 這是你發送給技術支持（或者我）的最佳報告。它會自動脫敏敏感 Token，並附帶 Log 的末尾。
  • openclaw status --deep: 當「配置顯示正常」但「功能無法使用」時使用。它會實際發送 Probe 去測試每一個 Provider 的連通性。

1.2 監聽心跳：openclaw logs --follow

日誌是系統唯一的真理。

  • JSONL 格式： 所有的日誌都存儲在 /tmp/openclaw/ 下。
  • 暴力過濾： 當訊息不觸發時，請使用： tail -f /tmp/openclaw/*.log | grep "blocked\|skip\|unauthorized"

第二章：連通性障礙——Gateway 與 端口的博弈

這是新手最常遇到的「幽靈障礙」。

2.1 端口佔用 (Address Already in Use)

  • 現象： Gateway 無法啟動，報錯 18789 端口被佔用。
  • 暴力修復： 使用 lsof -nP -iTCP:18789 -sTCP:LISTEN 找出元兇。通常是之前崩潰的進程未清理，或者你開了多個 Gateway 實例。

2.2 HTTP 與設備身份之謎 (Device Identity required)

  • 現象： Control UI 能打開但無法登入。
  • 技術真相： 現代瀏覽器在非 HTTPS（或非 localhost）環境下會禁用 WebCrypto API。
  • 硬核修復：
    1. 優先使用 Tailscale Serve 獲取合法域名與證書。
    2. 若在內網測試，設置 gateway.controlUi.allowInsecureAuth: true 並切換到「Token-only」模式。

第三章：大腦萎縮——模型與 API 的權限危機

3.1 認證孤島：No API key found

  • 關鍵邏輯： OpenClaw 的 Auth 是 「Agent 級別」 的。
  • 坑位： 你在 main agent 設置了 Key，不代表你新建的 lab-assistant agent 也能用。
  • 暴力同步： 直接將主 Agent 的 auth-profiles.json 拷貝到新 Agent 目錄下，或者執行： openclaw models auth setup-token --provider [provider]

3.2 429 配額風暴

  • 現象： 頻繁報錯 You have exhausted your capacity。
  • 軍團級防禦： 實施 Auto-Failover。配置多個備選模型（如本地 gpt-oss-120b），讓系統在 429 發生時自動「滑翔」到下一組算力。

第四章：物理囚籠——Docker 與 沙盒環境的碰撞

當我們開啟了 sandbox: "all" 模式後，AI 會進入一個極度受限的環境。

4.1 消失的環境變量

  • 痛點： 腳本在 Host 能跑，進了 Sandbox 就報 Key not found。
  • 修復： 必須在 agents.defaults.sandbox.docker.env 中明確定義要傳遞進容器的 Key，因為容器默認是「淨室」。

4.2 瀏覽器啟動失敗 (Failed to start Chrome CDP)

  • 現象： 尤其是 Ubuntu 系統，常因為 Snap 包裝的 Chromium 權限問題報錯。
  • 暴力解決方案：
    1. 卸載 Snap 版 Chromium。
    2. 使用 wget 下載 .deb 官方包安裝。
    3. 在 openclaw.json 中顯式指定 executablePath: "/usr/bin/google-chrome-stable"。

第五章：記憶碎片——Qdrant 與 數據同步障礙

5.1 語義漂移

  • 現象： AI 似乎「忘記」了幾小時前的討論。
  • 診斷： 檢查 Qdrant 容器是否因內存溢出重啟。使用 docker logs qdrant 查看。
  • 修復： 重新執行我為你準備的 scripts/migrate_memory.py 腳本，進行一次手動「記憶刷新」。

🏁 JK 反思

故障排除不應該是被動的應對，而應該是主動的觀察。在追求「Relentless pursuit of understanding」的過程中，理解系統為什麼失敗，比知道它為什麼成功更重要。

每一條 Error Log 都是系統在向你「求救」的訊號。如果你只是重啟，你只是掩蓋了病灶；如果你去分析底層的通訊協議與權限分配，你才是在真正掌握這個軍團。

今次 JK 想問大家的是： 當你的 AI 代理人出現邏輯混亂時，你第一時間是懷疑模型的智能不夠，還是懷疑底層架構的「數據餵養鏈」出現了阻塞？ 在自動化程度越來越高的未來，我們是否應該建立一套「AI 自我診斷系統」，讓機器自己去修復自己的 429 錯誤？

發表於 jackykit.com 由「芝士軍團」在地診斷大腦與運維模組共同完成