OpenClaw 常見錯誤排除手冊：新手活過第一天的急救包
OpenClaw 常見錯誤排除手冊：新手活過第一天的急救包
你剛裝好 OpenClaw，結果什麼都動不了？這篇是你的急診室。每個問題都是「症狀 → 原因 → 解法」，指令直接複製貼上。
1. 安裝失敗篇
1.1 macOS 權限問題
症狀：npm install -g openclaw 噴 EACCES: permission denied
原因：系統 Node.js 的全域安裝路徑需要 root 權限。
解法（二擇一）：
# 方法 A：用 sudo 強裝（不推薦，但能救急）
sudo npm install -g openclaw
# 方法 B：用 nvm 管理 Node.js（推薦，一勞永逸）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
npm install -g openclaw
1.2 SHARP 圖片庫編譯失敗
症狀：安裝過程噴 sharp 或 SHARP_IGNORE_GLOBAL_LIBVIPS 相關錯誤。
原因：sharp 是原生圖片處理庫，需要預編譯二進位檔。某些系統架構或 Node 版本抓不到對應的 prebuilt binary。
解法：
# 設定環境變數跳過全域 libvips 檢查
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw
# 如果還是失敗，手動安裝編譯工具
# macOS
xcode-select --install
# Ubuntu/Debian
sudo apt-get install -y build-essential libvips-dev
1.3 Node.js 版本不對
症狀：安裝或啟動時噴 SyntaxError: Unexpected token 或 engine 不相容警告。
原因：OpenClaw 需要 Node.js 22+。
解法：
# 檢查目前版本
node -v
# 如果低於 v22，升級
nvm install 22
nvm alias default 22
node -v # 確認是 v22.x.x
1.4 Windows 用戶：必須用 WSL2
症狀：各種奇怪的路徑錯誤、原生模組編譯失敗、spawn UNKNOWN 錯誤。
原因：OpenClaw 不支援原生 Windows，必須跑在 WSL2 裡面。
解法：
# 在 PowerShell（管理員）安裝 WSL2
wsl --install -d Ubuntu-22.04
# 進入 WSL2 後，安裝 Node.js 再裝 OpenClaw
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
npm install -g openclaw
⚠️ 不要在 Windows 的 cmd 或 PowerShell 裡直接跑
openclaw。永遠在 WSL2 的終端機裡操作。
1.5 npm Registry 連線失敗
症狀：npm ERR! network、ETIMEDOUT、ECONNRESET。
原因：網路環境無法連上 npm 官方 registry。
解法：
# 換用淘寶鏡像（中國大陸用戶）
npm config set registry https://registry.npmmirror.com
npm install -g openclaw
# 或設定代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm install -g openclaw
# 裝完記得改回來
npm config delete proxy
npm config delete https-proxy
1.6 從 Clawdbot / Moltbot 升級失敗
症狀：裝完 OpenClaw 後指令衝突、設定檔不相容、奇怪的模組找不到錯誤。
原因：舊版套件的全域安裝殘留。
解法：
# 先清掉舊版
npm uninstall -g clawdbot moltbot
# 清除舊設定（可選，先備份）
mv ~/.clawdbot ~/.clawdbot.bak
mv ~/.moltbot ~/.moltbot.bak
# 重新安裝
npm install -g openclaw
openclaw setup
2. API Key 設定篇
2.1 Anthropic API Key 設定陷阱
症狀：拿到 API key 但呼叫一直回 401 或 insufficient_quota。
原因：Anthropic 帳號必須先預充值至少 $5 美金才能啟用 API 呼叫。光註冊拿 key 是不夠的。
解法：
- 登入 console.anthropic.com
- 到 Billing → Add funds，至少充值 $5
- 等幾分鐘讓額度生效
- 重新測試
2.2 setup-token vs API key
症狀：搞不清楚 openclaw setup 要填什麼。
原因：OpenClaw 支援兩種認證方式，用途不同。
| API Key | Setup Token | |
|---|---|---|
| 格式 | sk-ant-api03-... |
透過 OAuth 取得 |
| 計費 | API 用量計費 | 綁定 Claude Max 訂閱 |
| 適合 | 按量付費用戶 | Claude Max 訂閱用戶（最划算） |
解法：
# 用 API Key
openclaw setup
# 選擇 "API Key"，貼上你的 sk-ant-... key
# 用 Claude Max 的 Setup Token（推薦訂閱用戶）
openclaw setup --token
# 按照 OAuth 流程登入
2.3 OpenRouter API Key 改不了
症狀：在 openclaw config 選單中想修改 OpenRouter key，但選單直接跳過輸入步驟。
原因：已知 bug（GitHub Issue #8983），設定選單對已存在的 key 會跳過。
解法：直接編輯設定檔。
# 開啟設定檔
nano ~/.openclaw/openclaw.json
# 找到 openrouter 區塊，手動修改 apiKey 值
# {
# "providers": {
# "openrouter": {
# "apiKey": "sk-or-v1-你的新key"
# }
# }
# }
2.4 API Key 格式錯誤
症狀：Invalid API key format 或認證持續失敗。
原因：複製貼上時帶入了多餘的空格、換行、或搞混了不同平台的 key。
各平台 key 格式：
| 平台 | 前綴 | 範例 |
|---|---|---|
| Anthropic | sk-ant-api03- |
sk-ant-api03-xxxxxxxx... |
| OpenAI | sk- |
sk-proj-xxxxxxxx... |
| OpenRouter | sk-or-v1- |
sk-or-v1-xxxxxxxx... |
解法：
# 檢查目前設定的 key
openclaw config list
# 重新設定（注意前後不要有空格）
openclaw config set providers.anthropic.apiKey "sk-ant-api03-你的完整key"
3. Gateway 啟動失敗篇
3.1 端口衝突
症狀：Error: listen EADDRINUSE :::18789
原因：預設端口 18789 已經被其他程式占用。
解法：
# 找出誰占了端口
lsof -i :18789
# 殺掉占用的程式（用上面查到的 PID）
kill -9 <PID>
# 或者改用其他端口
openclaw config set gateway.port 18790
openclaw gateway start
3.2 gateway.mode 未設定
症狀：Gateway start blocked: set gateway.mode=local
原因：安全機制，首次啟動需要明確指定 Gateway 模式。
解法：
openclaw config set gateway.mode local
openclaw gateway start
3.3 非 loopback 綁定需要認證
症狀：refusing to bind gateway on 0.0.0.0 without auth
原因：當你把 Gateway 綁定到非 127.0.0.1 的地址時（例如讓外部存取），OpenClaw 強制要求設定認證 token，防止裸奔。
解法：
# 產生一個隨機 token
TOKEN=$(openssl rand -hex 32)
# 設定認證
openclaw config set gateway.auth.token "$TOKEN"
# 設定綁定地址（如果需要外部存取）
openclaw config set gateway.host 0.0.0.0
# 重啟 Gateway
openclaw gateway restart
⚠️ 如果只是本機使用，保持預設的
127.0.0.1就好，不需要設定 auth token。
4. 通道連線篇
4.1 Telegram Bot 沒回應
症狀：發訊息給你的 Telegram Bot，已讀但沒回覆。
原因：Telegram 通道需要經過配對流程，Bot 不會自動回覆未配對的用戶。
解法：
# 步驟 1：對 Bot 發送任意訊息，會收到一個配對碼（例如 ABC123）
# 步驟 2：在終端機批准配對
openclaw pairing approve telegram ABC123
# 步驟 3：確認通道狀態
openclaw channels status --probe
群組模式額外設定：
# 設定 Bot 只在被 @ 時回覆（避免群組洗版）
openclaw config set channels.telegram.mentionOnly true
4.2 Control UI 404
症狀：打開 http://localhost:18789 看到 404 Not Found。
原因：已知 bug（GitHub Issue #24465），npm install -g 升級後 UI 靜態檔案可能沒有正確部署。
解法：
# 方法 A：重啟 Gateway
openclaw gateway restart
# 方法 B：如果重啟沒用，完全重裝
npm uninstall -g openclaw
npm install -g openclaw
openclaw gateway restart
# 確認 UI 可存取
curl -s http://localhost:18789/health
5. AI 不執行工具篇
5.1 tools.profile 設定問題
症狀：叫 AI 執行指令、讀檔案、寫程式，它只會用文字回覆，不會真的去做。
原因：tools.profile 預設可能是 messaging（純聊天模式），不具備工具執行能力。
解法：
# 查看目前設定
openclaw config get agents.defaults.tools.profile
# 改成可以執行工具的模式
# messaging — 純聊天（預設）
# coding — 可讀寫檔案、執行程式碼
# full — 完整系統指令存取
openclaw config set agents.defaults.tools.profile full
5.2 Sandbox 太嚴格
症狀：AI 嘗試讀寫檔案但噴 Permission denied 或 sandbox violation。
原因：Sandbox 預設限制了工作區以外的檔案存取。
解法：
# 查看目前 sandbox 設定
openclaw config get sandbox
# 允許存取工作區
openclaw config set sandbox.workspaceAccess readwrite
# 如果需要存取工作區以外的路徑（謹慎使用）
openclaw config set sandbox.allowPaths "/home/user/data,/tmp"
⚠️ 不要把 sandbox 完全關掉。只開放你確實需要的路徑。
6. 成本爆炸篇
6.1 Token 消耗異常快
症狀：帳單飆升，API 額度幾小時就用完。
常見原因：
- Heartbeat 設太頻繁：預設的定期檢查如果設成 5 分鐘一次，每天就是 288 次 API 呼叫。
- Cron job 失敗重試不停：排程任務失敗後會自動重試，每次重試都消耗 token。
解法：
# 檢查 heartbeat 間隔（建議 30 分鐘以上）
openclaw config get agents.defaults.heartbeat
openclaw config set agents.defaults.heartbeat.interval 1800
# 檢查 cron job 狀態
openclaw cron list
openclaw cron runs
# 暫停有問題的 cron job
openclaw cron disable <job-id>
# 查看 token 使用統計
openclaw usage --period today
💡 詳細的成本控制策略請參考成本控制專篇。
7. 急救指令速查表
遇到問題，先跑這些指令再來查文件：
| 症狀 | 第一步 | 指令 |
|---|---|---|
| 什麼都不動了 | 跑自動診斷 | openclaw doctor |
| 不確定哪裡壞了 | 檢查整體狀態 | openclaw status |
| Gateway 連不上 | 檢查 Gateway 狀態 | openclaw gateway status |
| Bot 沒回應 | 檢查通道狀態 | openclaw channels status --probe |
| 看不懂錯誤訊息 | 即時查看日誌 | openclaw logs --follow |
| Gateway 行為異常 | 重啟 Gateway | openclaw gateway restart |
| 設定好像不對 | 列出所有設定 | openclaw config list |
| API 一直 401 | 驗證 API key | openclaw config get providers |
| Token 燒太快 | 檢查排程任務 | openclaw cron list && openclaw cron runs |
| 安裝後指令找不到 | 檢查 PATH | which openclaw && node -v |
黃金三連：通用排錯起手式
# 第一步：自動診斷
openclaw doctor
# 第二步：看狀態
openclaw status
# 第三步：看日誌
openclaw logs --follow
90% 的問題跑完這三步就能找到方向。
參考資料
作者：Chi