故障排除15 分鐘閱讀

OpenClaw 常見錯誤及解決方法

全面指南：診斷和修復 OpenClaw 常見錯誤，包括安裝問題、API錯誤、頻道問題和效能問題。

OpenClaw Guides

Tutorial Authors

2025-02-04

快速診斷

在深入具體錯誤之前，執行這些診斷命令：

bash

# 檢查整體狀態
openclaw status

# 驗證設定
openclaw config validate

# 查看最近的錯誤日誌
openclaw logs --tail 50 --level error

# 執行健康檢查
openclaw doctor

安裝錯誤

錯誤："Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

解決方法：

bash

# 使用 nvm（推薦）
nvm install 22
nvm use 22
nvm alias default 22

# 或使用 Homebrew（macOS）
brew install node@22

# 驗證
node --version  # 應顯示 v22.x.x

錯誤："EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

解決方法： 不要使用 sudo。改為修復 npm 權限：

bash

# 選項1：使用 nvm（推薦）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 選項2：更改 npm 預設目錄
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然後重新安裝
npm install -g openclaw@latest

錯誤："Cannot find module"

Error: Cannot find module '@openclaw/core'

解決方法：

bash

# 清除 npm 快取並重新安裝
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# 或使用安裝腳本
curl -fsSL https://openclaw.ai/install.sh | bash

錯誤："gyp ERR! build error"（原生模組）

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

解決方法： 安裝建置工具：

bash

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API 和認證錯誤

錯誤："401 Unauthorized"

Error: API request failed with status 401: Invalid API key

解決方法：

bash

# 驗證 API 金鑰是否已設定
openclaw config get api-key

# 如果為空或錯誤，重新設定
openclaw config set api-key

# 檢查金鑰格式（Anthropic 金鑰以 sk-ant- 開頭）
# 確保沒有多餘的空格或引號

錯誤："429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

解決方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

對於持續的速率限制，考慮升級 API 等級或使用不同的模型：

bash

openclaw config set default-model claude-3-5-haiku

錯誤："402 Payment Required"

Error: API request failed: Insufficient credits

解決方法：

檢查 API 提供商餘額
為帳戶加值
或設定使用限制：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

錯誤："Connection Refused" to API

Error: connect ECONNREFUSED api.anthropic.com:443

解決方法：

bash

# 檢查網路連線
ping api.anthropic.com

# 檢查是否在代理後面
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 如需要設定代理
openclaw config set proxy http://your-proxy:8080

# 或檢查防火牆/VPN設定

閘道錯誤

錯誤："EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

解決方法：

bash

# 查找使用該連接埠的程序
lsof -i :18789

# 終止程序
kill -9 <PID>

# 或使用不同連接埠
openclaw gateway start --port 18790

# 更新設定使用新連接埠
openclaw config set gateway-port 18790

錯誤："Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

解決方法：

bash

# 驗證設定檔語法
openclaw config validate

# 如果損壞，重設為預設值
openclaw config reset --confirm

# 然後重新設定
openclaw onboard

錯誤："Gateway not responding"

bash

# 檢查閘道是否執行
openclaw status

# 如果停止，檢查原因
openclaw logs --tail 100

# 嘗試重啟
openclaw gateway restart

# 如果仍然失敗，檢查系統資源
free -h  # 記憶體
df -h    # 磁碟空間

頻道特定錯誤

WhatsApp："Session expired"

Error: WhatsApp session invalid or expired

解決方法：

bash

# 重新認證
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# 掃描新的 QR code

WhatsApp："QR code not generating"

bash

# 檢查是否有其他工作階段活動
pkill -f "openclaw.*whatsapp"

# 清除舊工作階段資料
rm -rf ~/.openclaw/whatsapp-session

# 重試
openclaw channel connect whatsapp

Telegram："Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

另一個實例正在使用相同的機器人權杖。

解決方法：

bash

# 停止所有 OpenClaw 實例
pkill -f openclaw

# 檢查其他執行中的實例
ps aux | grep openclaw

# 重新啟動
openclaw gateway start

Discord："Invalid token"

Error: An invalid token was provided

解決方法：

bash

# 在 Discord Developer Portal 重新產生權杖
# Bot → Reset Token

# 更新 OpenClaw
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord："Missing intents"

Error: Disallowed intents specified

解決方法：

進入 Discord Developer Portal
選擇您的應用程式 → Bot
在"Privileged Gateway Intents"下啟用所需的 intents
儲存並重啟 OpenClaw

記憶體和效能錯誤

錯誤："JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

解決方法：

bash

# 增加 Node.js 記憶體限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 新增到 shell 設定檔以持久化
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# 重啟 OpenClaw
openclaw gateway restart

錯誤："Too many open files"

Error: EMFILE: too many open files

解決方法：

bash

# 檢查目前限制
ulimit -n

# 增加限制（暫時）
ulimit -n 65535

# 增加限制（永久 - Linux）
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

回應時間慢

診斷：

bash

# 檢查模型延遲
openclaw benchmark

# 檢查系統資源
openclaw stats

解決方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

設定錯誤

錯誤："Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

解決方法：

bash

# 驗證 YAML
openclaw config validate

# 常見問題：
# - 使用 Tab 而非空格（使用2個空格）
# - 鍵後缺少冒號
# - 未引用的特殊字元

# 修復或重設
openclaw config edit
# 或
openclaw config reset --confirm

錯誤："Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

解決方法：

bash

# 檢查可用選項
openclaw config list

# 移除未知鍵
openclaw config edit

錯誤："Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

解決方法：

bash

# 新增到 .env 檔案
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# 或在 shell 中匯出
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 新增到 shell 設定檔以持久化
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

資料庫和儲存錯誤

錯誤："Database locked"

Error: SQLITE_BUSY: database is locked

解決方法：

bash

# 停止 OpenClaw
openclaw gateway stop

# 檢查鎖定檔案
ls -la ~/.openclaw/*.lock

# 移除陳舊的鎖定
rm ~/.openclaw/*.lock

# 重啟
openclaw gateway start

錯誤："Disk quota exceeded"

Error: ENOSPC: no space left on device

解決方法：

bash

# 檢查磁碟使用
df -h

# 清除 OpenClaw 日誌和快取
openclaw cache clear
openclaw logs clear --older-than 7d

# 清除舊工作階段
rm -rf ~/.openclaw/sessions/*.old

取得更多幫助

啟用除錯日誌

bash

# 設定除錯模式
export OPENCLAW_DEBUG=true
openclaw gateway start

# 或在設定中設定
openclaw config set logLevel debug

產生診斷報告

bash

openclaw doctor --report > diagnostic-report.txt

社群支援

Discord: discord.gg/openclaw
GitHub Issues: github.com/openclaw/openclaw/issues
文件: docs.openclaw.ai

提交 Bug 報告

報告問題時，請包含：

bash

# 系統資訊
openclaw --version
node --version
uname -a

# 設定（隱藏敏感資料）
openclaw config show --redact

# 最近的日誌
openclaw logs --tail 100

快速診斷

安裝錯誤

錯誤："Node.js version too old"

錯誤："EACCES permission denied"

錯誤："Cannot find module"

錯誤："gyp ERR! build error"（原生模組）

API 和認證錯誤

錯誤："401 Unauthorized"

錯誤："429 Rate Limited"

錯誤："402 Payment Required"

錯誤："Connection Refused" to API

閘道錯誤

錯誤："EADDRINUSE: Port already in use"

錯誤："Gateway failed to start"

錯誤："Gateway not responding"

頻道特定錯誤

WhatsApp："Session expired"

WhatsApp："QR code not generating"

Telegram："Conflict: terminated by other getUpdates"

Discord："Invalid token"

Discord："Missing intents"

記憶體和效能錯誤

錯誤："JavaScript heap out of memory"

錯誤："Too many open files"

回應時間慢

設定錯誤

錯誤："Invalid YAML syntax"

錯誤："Unknown configuration key"

錯誤："Environment variable not set"

資料庫和儲存錯誤

錯誤："Database locked"

錯誤："Disk quota exceeded"

取得更多幫助

啟用除錯日誌

產生診斷報告

社群支援

提交 Bug 報告

後續步驟