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