Imported from myyxfishcat/openclaw-quickfix (SKILL.md). Install upstream with npx skills add myyxfishcat/openclaw-quickfix. Copyright stays with the author.

OpenClaw QuickFix - Gateway 診斷與修復完整手冊

版本：1.0.0 | 最後更新：2026-03-06 基於實戰經驗整理，目標是將 30 分鐘的手動排障壓縮到 5 分鐘以內。

一、系統架構概述

OpenClaw 是一個開源的個人 AI 助手，運行在本機硬體上，透過 Gateway 服務提供 Web Dashboard 和 API 連線。

核心元件

┌─────────────────────────────────────────────────────┐
│  OpenClaw 系統架構                                    │
│                                                       │
│  ┌──────────┐    ┌──────────┐    ┌──────────────┐   │
│  │ Dashboard │───▶│ Gateway  │───▶│ Agent Engine │   │
│  │ (Web UI)  │    │ :18789   │    │ (LLM Model) │   │
│  └──────────┘    └──────────┘    └──────────────┘   │
│       ▲               │                  │           │
│       │               ▼                  ▼           │
│  ┌──────────┐    ┌──────────┐    ┌──────────────┐   │
│  │ Telegram  │    │ Plugins  │    │   Memory     │   │
│  │ Channel   │    │ (LanceDB)│    │ (LanceDB Pro)│   │
│  └──────────┘    └──────────┘    └──────────────┘   │
└─────────────────────────────────────────────────────┘

關鍵路徑與設定

環境需求

二、快速診斷流程（TL;DR）

# 一鍵診斷
bash ~/.openclaw/skills/openclaw-quickfix/scripts/diagnose.sh

# 一鍵修復
bash ~/.openclaw/skills/openclaw-quickfix/scripts/fix-gateway.sh

如果自動腳本無法修復，按以下順序手動排查：

第一步：確認 Gateway 狀態

openclaw status | grep -i gateway

第二步：查看錯誤日誌（最關鍵的一步）

tail -30 ~/.openclaw/logs/gateway.err.log

根據日誌內容，對應到下方的故障類型進行修復。

第三步：根據錯誤類型修復（見下方各類型詳細說明）

三、故障類型詳解

故障 A：插件路徑錯誤 ⭐ 最常見

發生機率：約 70% 的 Gateway 啟動失敗都是這個原因。

症狀

error log 中出現以下錯誤（可能是一個或多個）：

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - plugins.load.paths: plugin: plugin path not found: /plugins/memory-lancedb-pro
  - plugins.entries.memory-lancedb-pro: plugin not found: memory-lancedb-pro
  - plugins.slots.memory: plugin not found: memory-lancedb-pro

根因分析

OpenClaw 設定檔 ~/.openclaw/openclaw.json 中的 plugins.load.paths 欄位使用了相對路徑（例如 "plugins/memory-lancedb-pro"），但 OpenClaw 在解析時無法正確找到該目錄。

常見觸發場景：

1. 插件是從 GitHub clone 到 ~/plugins/ 目錄，但設定檔寫的是相對路徑
2. 執行 openclaw doctor --fix 後，doctor 重寫了設定但沒有正確處理插件路徑
3. 更新 OpenClaw 版本後，路徑解析邏輯改變

修復步驟

步驟 1：找到插件實際位置

find ~ -maxdepth 5 -name "memory-lancedb-pro" -type d 2>/dev/null

預期輸出範例：

/Users/<你的用戶名>/plugins/memory-lancedb-pro
~/.openclaw/workspace/plugins/memory-lancedb-pro

步驟 2：備份設定檔

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M%S)

步驟 3：修改設定檔中的路徑為絕對路徑

打開設定檔：

nano ~/.openclaw/openclaw.json

找到 plugins.load.paths 欄位，將相對路徑改為絕對路徑：

// ❌ 錯誤寫法（相對路徑）
"plugins": {
  "load": {
    "paths": [
      "plugins/memory-lancedb-pro"
    ]
  }
}

// ✅ 正確寫法（絕對路徑）
"plugins": {
  "load": {
    "paths": [
      "/Users/<你的用戶名>/plugins/memory-lancedb-pro"
    ]
  }
}

步驟 4：重啟並驗證

openclaw daemon restart
sleep 3
openclaw status | grep -i gateway

應看到：running (pid XXXX) + reachable

預防措施

• 安裝新插件後，永遠使用絕對路徑
• 執行 openclaw doctor --fix 後，必須檢查 plugins.load.paths 是否被改回相對路徑
• 建議在安裝插件後立即跑一次 openclaw status 確認 gateway 正常

故障 B：Port 18789 被佔用

發生機率：約 10%

症狀

• Gateway 狀態顯示 running 但 unreachable
• 或啟動時 error log 出現 EADDRINUSE

修復步驟

# 1. 檢查誰在用 port 18789
lsof -i :18789

# 2. 如果有其他進程佔用（非 openclaw），終止它
kill -9 <PID>

# 3. 如果是殘留的 openclaw 進程
killall -9 node  # 注意：這會殺掉所有 node 進程

# 4. 重啟
openclaw daemon restart

故障 C：LaunchAgent 異常

發生機率：約 10%

症狀

• openclaw status 顯示 LaunchAgent not installed
• 或 stopped (state spawn scheduled) 反覆出現，daemon restart 無效

修復步驟

# 完全卸載
launchctl bootout gui/$(id -u)/ai.openclaw.gateway 2>/dev/null

# 重新安裝
openclaw daemon install

# 啟動
openclaw daemon restart

# 驗證
openclaw status | grep -i gateway

如果 openclaw daemon install 失敗，手動檢查 LaunchAgent plist：

ls ~/Library/LaunchAgents/ai.openclaw.gateway.plist
cat ~/Library/LaunchAgents/ai.openclaw.gateway.plist

故障 D：設定檔 JSON 損壞

發生機率：約 5%

症狀

• error log 出現 SyntaxError: Unexpected token 或 JSON parse error
• Config invalid（非插件相關）

修復步驟

方案 1：恢復備份

# 找最近的備份
ls -la ~/.openclaw/openclaw.json.bak*

# 恢復
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw daemon restart

方案 2：用 doctor 重建

openclaw doctor --fix
openclaw daemon restart

方案 3：手動驗證 JSON

# 用 node 檢查 JSON 格式
node -e "JSON.parse(require('fs').readFileSync('$HOME/.openclaw/openclaw.json','utf8')); console.log('JSON OK')"

故障 E：Node 版本不相容

發生機率：約 3%

症狀

• error log 出現 punycode deprecation warning
• 或其他 Node.js 相關的錯誤

修復步驟

# 確認 Node 版本（需要 >= 22）
node --version

# 如果版本過低，更新 Node
# 使用 nvm:
nvm install --lts
nvm use --lts

# 或使用 brew:
brew upgrade node

故障 F：OpenClaw 版本過舊

症狀

• openclaw status 顯示 Update available
• 新功能無法使用或出現未知錯誤

修復步驟

# 更新
openclaw update

# 或手動更新
npm update -g openclaw

# 重啟
openclaw daemon restart

四、萬能修復流程

如果不確定問題類型，依序執行以下步驟：

# Step 1: 完整診斷
openclaw doctor

# Step 2: 自動修復（會修改設定檔）
openclaw doctor --fix

# Step 3: 查看錯誤日誌（doctor --fix 可能沒修好所有問題）
tail -30 ~/.openclaw/logs/gateway.err.log

# Step 4: 如果是插件路徑問題，手動修正
# 找插件：
find ~ -maxdepth 5 -name "<插件名>" -type d 2>/dev/null
# 改設定：
nano ~/.openclaw/openclaw.json
# 把 plugins.load.paths 改為絕對路徑

# Step 5: 重啟
openclaw daemon restart

# Step 6: 驗證
openclaw status | grep -i gateway
# 應看到: running + reachable

# Step 7: 如果還是不行，完全重裝 LaunchAgent
launchctl bootout gui/$(id -u)/ai.openclaw.gateway 2>/dev/null
openclaw daemon install
openclaw daemon restart

五、自動化腳本

diagnose.sh — 一鍵診斷

執行 7 項檢查：OpenClaw 安裝、設定檔格式、插件路徑、Port 狀態、LaunchAgent、錯誤日誌、Gateway 連通性。

bash ~/.openclaw/skills/openclaw-quickfix/scripts/diagnose.sh

fix-gateway.sh — 一鍵自動修復

自動備份 → 偵測插件路徑 → 修復設定檔 → 重啟 daemon → 驗證。

bash ~/.openclaw/skills/openclaw-quickfix/scripts/fix-gateway.sh

腳本會在以下位置搜尋插件：

1. ~/plugins/<插件名>
2. ~/.openclaw/workspace/plugins/<插件名>
3. ~/.openclaw/plugins/<插件名>

如果找到，自動將設定檔中的相對路徑替換為絕對路徑。

六、常見插件參考

以下是社區常用的 OpenClaw 插件（以 memory-lancedb-pro 為例）：

插件安裝注意事項

• 安裝路徑建議放在 ~/plugins/<插件名> 或 ~/.openclaw/plugins/<插件名>
• 設定檔中務必使用絕對路徑（如 /Users/yourname/plugins/memory-lancedb-pro）
• 安裝後立即執行 openclaw status 確認 Gateway 正常

七、設定檔結構參考

{
  "gateway": {
    "port": 18789,           // Gateway 監聽的 port
    "mode": "local",          // 運行模式
    "bind": "loopback",       // 綁定位址（loopback = 127.0.0.1）
    "auth": {
      "mode": "token",        // 認證模式
      "token": "..."          // 存取 token（勿外洩）
    }
  },
  "plugins": {
    "load": {
      "paths": [              // ⚠️ 務必使用絕對路徑！
        "/Users/<你的用戶名>/plugins/memory-lancedb-pro"
      ]
    },
    "slots": {
      "memory": "memory-lancedb-pro"   // 記憶插件綁定
    },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": { ... }     // 插件設定（embedding、retrieval 等）
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-model-here"      // 預設模型
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true         // Telegram 頻道
    }
  }
}

八、常用指令速查表

九、實戰案例：2026-03-06 修復記錄

問題描述

OpenClaw Gateway 無法啟動，Dashboard (http://127.0.0.1:18789/) 無法連線。

排障時間線

根因總結

~/.openclaw/openclaw.json 中 plugins.load.paths 使用了相對路徑 "plugins/memory-lancedb-pro"，OpenClaw 無法在 ~/.openclaw/plugins/memory-lancedb-pro 找到該插件（實際位於 ~/plugins/memory-lancedb-pro），導致設定檔驗證失敗，Gateway 啟動即 crash。

教訓

1. 插件路徑永遠用絕對路徑
2. openclaw doctor --fix 不一定能修所有問題 — 它可能更新設定檔但不處理插件路徑
3. error log 是定位根因的最有效方式 — tail -30 ~/.openclaw/logs/gateway.err.log
4. 不要反覆 daemon restart — 如果第一次沒用，直接看 error log

十、給其他 AI Agent 的指引

如果你是一個 AI Agent（如 Claude、GPT、Kimi 等），正在幫助用戶修復 OpenClaw：

1. 第一步永遠是看 error log：tail -30 ~/.openclaw/logs/gateway.err.log
2. 不要盲目重啟 — 如果 daemon restart 一次無效，問題不在 daemon 本身
3. 插件路徑問題是最常見的故障 — 優先檢查 plugins.load.paths
4. 如果有權限，直接修改設定檔 — 比反覆跑 doctor 更有效
5. 修改後務必備份 — cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
6. 驗證成功的標誌：openclaw status 顯示 running + reachable