openclaw-quickfix

name	openclaw-quickfix
description	OpenClaw Gateway 快速診斷與修復工具。當 OpenClaw 無法連線、Gateway 無法啟動、Dashboard 打不開、或出現 ECONNREFUSED 錯誤時使用此技能。涵蓋插件路徑修復、設定檔驗證、daemon 重啟、Node 版本問題等常見問題的自動化修復流程。觸發關鍵字：openclaw、gateway、18789、ECONNREFUSED、daemon、連線失敗、修復、recovery、plugin not found、config invalid。

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)│   │
│  └──────────┘    └──────────┘    └──────────────┘   │
└─────────────────────────────────────────────────────┘

關鍵路徑與設定

項目	路徑 / 值
設定檔	~/.openclaw/openclaw.json
設定備份	~/.openclaw/openclaw.json.bak
Gateway Port	18789 (WebSocket: ws://127.0.0.1:18789)
Dashboard URL	http://127.0.0.1:18789/
Chat URL	http://127.0.0.1:18789/chat?session=agent:main:main
LaunchAgent 名稱	gui/501/ai.openclaw.gateway
錯誤日誌	~/.openclaw/logs/gateway.err.log
標準日誌	~/.openclaw/logs/gateway.log
執行日誌	/tmp/openclaw/openclaw-<date>.log
工作目錄	~/.openclaw/workspace/
插件目錄	~/plugins/ 或 ~/.openclaw/plugins/
Agent 設定	~/.openclaw/agents/main/
Sessions 資料	~/.openclaw/agents/main/sessions/sessions.json
Memory 資料庫	~/.openclaw/memory/lancedb-pro/

環境需求

項目	建議值
作業系統	macOS (arm64 / x86_64)
Node 版本	>= 22
OpenClaw 版本	>= 2026.2.x
安裝方式	npm install -g openclaw

---

二、快速診斷流程（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

狀態輸出	含義	嚴重度	下一步
running (pid XXXX) + reachable XXms	正常運行	-	無需修復
running (pid XXXX) + unreachable	進程在但無法連線	中	→ 故障類型 B（Port 衝突）
stopped (state spawn scheduled)	啟動後立即崩潰	高	→ 第二步（查 error log）
LaunchAgent installed · loaded · stopped	daemon 載入但停止	高	→ 第二步（查 error log）
LaunchAgent not installed	daemon 未安裝	低	→ 故障類型 C（LaunchAgent）

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

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 為例）：

插件名稱	來源	功能
memory-lancedb-pro	GitHub: win4r/memory-lancedb-pro	向量記憶資料庫，支援 hybrid 檢索

插件安裝注意事項

• 安裝路徑建議放在 ~/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 頻道
    }
  }
}

---

八、常用指令速查表

指令	用途
openclaw status	查看完整狀態
openclaw status | grep -i gateway	快速檢查 Gateway
openclaw daemon restart	重啟 Gateway daemon
openclaw daemon install	安裝 LaunchAgent
openclaw doctor	完整診斷
openclaw doctor --fix	自動修復
openclaw gateway probe	測試 Gateway 連通性
openclaw logs --follow	即時查看日誌
openclaw update	更新到最新版本
openclaw security audit --deep	深度安全檢查
tail -30 ~/.openclaw/logs/gateway.err.log	查看錯誤日誌
lsof -i :18789	檢查 port 佔用
launchctl bootout gui/$(id -u)/ai.openclaw.gateway	卸載 LaunchAgent

---

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

問題描述

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

排障時間線

時間	操作	結果
05:45	openclaw status	Gateway: unreachable, stopped (state spawn scheduled)
05:47	openclaw daemon restart	Restarted，但 Gateway 仍然 unreachable
05:48	openclaw gateway probe	Connect failed: ECONNREFUSED 127.0.0.1:18789
05:49	openclaw logs --follow	Gateway not reachable
05:50	openclaw doctor	Gateway not running, 建議 --fix
05:52	openclaw doctor --fix	更新了設定檔，重啟 LaunchAgent
05:55	再次 openclaw doctor --fix	Gateway 仍 not running
05:58	tail -30 ~/.openclaw/logs/gateway.err.log	發現根因：plugins.load.paths: plugin path not found: /plugins/memory-lancedb-pro
06:00	find ~ -maxdepth 5 -name "memory-lancedb-pro"	找到：/Users/<你的用戶名>/plugins/memory-lancedb-pro
06:02	修改設定檔：相對路徑 → 絕對路徑	"plugins/memory-lancedb-pro" → "/Users/<你的用戶名>/plugins/memory-lancedb-pro"
06:05	openclaw daemon restart	Gateway running (pid 11515), reachable 41ms

根因總結

~/.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