OpenClaw/龙虾常见启动和配置错误解决方案

摘要：本文档整理了 OpenClaw（龙虾）在本地或云服务器上安装、启动和配置过程中最常见的错误及解决方案，帮助用户快速排查问题。

一、安装和启动常见错误

1.1 `openclaw` 命令未找到

错误现象：

openclaw: command not found
# 或
'openclaw' 不是内部或外部命令，也不是可运行的程序

原因分析：

Node.js 未安装或版本过低（需要 Node 22.16+ 或 Node 24）
npm 全局安装路径未添加到系统 PATH
安装过程中断或失败

解决方案：

macOS/Linux/WSL2：

# 1. 检查 Node.js 版本
node-v
npm-v

# 2. 检查 npm 全局路径
npm prefix -g

# 3. 将全局路径添加到 PATH（~/.zshrc 或 ~/.bashrc）
exportPATH="$(npm prefix -g)/bin:$PATH"

# 4. 重新加载配置
source ~/.zshrc  # 或 source ~/.bashrc

# 5. 重新安装
curl-fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

# 1. 检查 npm 全局路径
npmconfiggetprefix

# 2. 将该路径添加到用户 PATH 环境变量

# 3. 重新打开 PowerShell 后重新安装
iwr-usebhttps://openclaw.ai/install.ps1|iex

1.2 sharp 构建错误

错误现象：

npm error sharp: Please add node-gyp to your dependencies
# 或
npm error sharp: Installation failed due to libvips conflicts

原因分析：

系统全局安装了 libvips（macOS 通过 Homebrew 常见）
缺少构建工具链（node-gyp、Xcode Command Line Tools）

解决方案：

方法一：强制使用预编译二进制（推荐）

SHARP_IGNORE_GLOBAL_LIBVIPS=1npm install -g openclaw@latest

方法二：安装构建工具

# macOS
xcode-select --install
npm install -g node-gyp

# Ubuntu/Debian
sudo apt-get install -y build-essential python3

# Windows
npm install -g windows-build-tools

1.3 Git 未找到错误

错误现象：

npm error spawn git ENOENT
# 或
Windows: "Git for Windows" is required but not installed

原因分析：

某些依赖包需要通过 git 安装
Windows 未安装 Git for Windows

解决方案：

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install -ygit

# Windows
# 访问 https://gitforwindows.org/ 下载安装

1.4 网关服务无法启动

错误现象：

openclaw gateway status
# Runtime: stopped
# 或
Gateway start blocked: set gateway.mode=local

原因分析：

gateway.mode 配置为 remote 但本地未运行服务
端口冲突（默认端口 18789 被占用）
非本地绑定未配置认证

解决方案：

# 1. 检查网关状态
openclaw gateway status
openclaw gateway status --deep

# 2. 查看日志
openclaw logs --follow

# 3. 运行健康检查
openclaw doctor

# 4. 检查端口占用
# macOS/Linux
lsof -i :18789

# Windows
netstat -ano | findstr :18789

# 5. 重新安装服务
openclaw gateway install --force
openclaw gateway restart

配置文件修复（~/.openclaw/openclaw.json）：

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-secure-token"
    }
  }
}

1.5 npm EACCES 权限错误（Linux）

错误现象：

npm error EACCES: permission denied

原因分析：

npm 全局安装路径指向系统目录（需要 root 权限）

解决方案：

# 方法一：使用安装脚本自动修复
curl-fsSL https://openclaw.ai/install.sh | bash

# 方法二：手动配置 npm 前缀
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到 ~/.bashrc 或 ~/.zshrc
exportPATH=~/.npm-global/bin:$PATH

# 重新安装
npm install -g openclaw@latest

二、OpenClaw 错误码详解

2.1 设备配对相关错误

错误码	含义	触发场景
`PAIRING_REQUIRED`	需要设备配对	新设备首次连接网关
`AUTH_TOKEN_MISSING`	缺少认证令牌	客户端未发送共享令牌
`AUTH_TOKEN_MISMATCH`	令牌不匹配	配置的令牌与网关不一致
`AUTH_DEVICE_TOKEN_MISMATCH`	设备令牌过期	设备令牌被撤销或过期
`device identity required`	需要设备身份	非安全上下文或缺少设备认证
`device nonce required`	需要设备随机数	客户端未完成挑战认证
`device signature invalid`	设备签名无效	客户端签名了错误的有效载荷

2.2 节点工具错误

错误码	含义	触发场景
`NODE_BACKGROUND_UNAVAILABLE`	应用在后台	iOS/Android 节点应用在后台运行
`CAMERA_DISABLED`	相机已禁用	节点设置中相机功能被禁用
`CAMERA_PERMISSION_REQUIRED`	需要相机权限	未授予相机权限
`MICROPHONE_PERMISSION_REQUIRED`	需要麦克风权限	未授予麦克风权限
`LOCATION_PERMISSION_REQUIRED`	需要位置权限	未授予位置权限
`LOCATION_DISABLED`	位置服务已关闭	系统位置服务被禁用
`LOCATION_BACKGROUND_UNAVAILABLE`	后台位置不可用	仅有"使用期间"权限但应用在后台
`SYSTEM_RUN_DENIED`	执行被拒绝	exec 命令需要审批或不在允许列表中
`SCREEN_RECORDING_PERMISSION_REQUIRED`	需要录屏权限	未授予屏幕录制权限

2.3 通道和消息错误

错误码	含义	触发场景
`mention required`	需要提及	群组消息未@机器人
`pairing`	需要配对	发送者未通过配对审批
`blocked`	已阻止	发送者在阻止列表中
`allowlist miss`	不在允许列表	发送者不在 allowFrom 列表中
`missing_scope`	缺少权限范围	通道 API 权限不足
`not_in_channel`	不在通道中	机器人未加入群组
`Forbidden`	禁止访问	API 权限被拒绝（403）
`401/403`	认证/授权失败	通道认证配置错误

2.4 浏览器工具错误

错误码	含义	触发场景
`Failed to start Chrome CDP`	无法启动 Chrome CDP	浏览器进程启动失败
`browser.executablePath not found`	浏览器路径无效	配置的浏览器路径不存在
`Chrome extension relay is running, but no tab is connected`	扩展未连接标签页	用户未点击扩展图标连接
`Browser attachOnly is enabled ... not reachable`	附加模式不可达	附加模式下目标不可访问

2.5 模型和 API 错误

错误码	含义	触发场景
`HTTP 429: rate_limit_error`	请求频率限制	API 调用超限
`Extra usage is required for long context`	需要额外用量	长上下文请求需要额外配额
`AUTH_TOKEN_EXPIRED`	认证令牌过期	OAuth 令牌已过期
`model not in allowlist`	模型不在允许列表	使用的模型未配置在 models 中

2.6 配置验证错误

错误码	含义	触发场景
`config validation failed`	配置验证失败	配置文件不符合 schema
`unknown key`	未知配置键	配置中包含未定义的键
`invalid type`	类型无效	配置值类型错误
`required field missing`	缺少必填字段	必填配置项缺失

2.7 沙箱和 Docker 错误

错误码	含义	触发场景
`sandbox image missing`	沙箱镜像缺失	未运行 sandbox-setup.sh
`Docker not running`	Docker 未运行	Docker 守护进程未启动
`container start failed`	容器启动失败	沙箱容器无法启动

2.8 Cron 和心跳错误

错误码	含义	触发场景
`cron: scheduler disabled`	调度器已禁用	cron.enabled 为 false
`cron: timer tick failed`	定时器失败	调度器时钟失败
`heartbeat skipped: quiet-hours`	静默时间跳过	当前时间在静默时间段内
`heartbeat skipped: dm-blocked`	DM 被阻止	heartbeat.directPolicy 为 block

三、错误解决方案

3.1 通用诊断流程

第一步：运行诊断命令

# 按顺序执行以下命令
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

第二步：检查预期输出

openclaw gateway status 应显示 Runtime: running 和 RPC probe: ok
openclaw doctor 应报告无阻塞配置/服务问题
openclaw channels status --probe 应显示已连接/就绪的通道

3.2 设备配对问题解决方案

症状： 新设备无法连接，显示配对请求

解决方案：

# 1. 查看待审批设备
openclaw devices list

# 2. 审批设备
openclaw devices approve <requestId>

# 3. 查看通道配对状态
openclaw pairing list --channel <channel>

# 4. 如果是令牌不匹配
openclaw config get gateway.auth.token
# 将令牌粘贴到客户端设置中

预防措施：

首次连接时确保网关和客户端使用相同认证模式
保存设备令牌以便后续连接

3.3 节点工具失败解决方案

症状： 节点已连接但相机/画布/屏幕工具失败

解决方案：

# 1. 检查节点状态
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

# 2. 检查执行审批
openclaw approvals get--node <idOrNameOrIp>

# 3. 添加命令到允许列表
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

iOS/Android 特定：

确保节点应用在前台运行
检查系统权限设置（相机、麦克风、位置、录屏）
重新授予 OS 权限

3.4 通道消息不流通解决方案

症状： 通道显示已连接但消息不流动

解决方案：

检查 DM 策略：

openclaw config get channels
openclaw pairing list --channel <channel>

修复配置：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"]
    }
  }
}

群组提及配置：

{
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"]
      }
    }]
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } }
    }
  }
}

3.5 模型 API 错误解决方案

症状： HTTP 429 错误或长上下文请求失败

解决方案：

# 1. 查看日志
openclaw logs --follow

# 2. 检查模型状态
openclaw models status

# 3. 检查配置的模型
openclaw config get agents.defaults.models

修复选项：

禁用长上下文：

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: false }
        }
      }
    }
  }
}

配置备用模型：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  }
}

更新 Anthropic API 密钥：

claude setup-token
# 或粘贴新的 setup-token

3.6 配置验证失败解决方案

症状： 网关拒绝启动，显示配置验证错误

解决方案：

# 1. 运行 doctor 检查
openclaw doctor

# 2. 查看配置文件
cat ~/.openclaw/openclaw.json

# 3. 自动修复（谨慎使用）
openclaw doctor --repair

# 4. 或手动修复后重启
openclaw gateway restart

常见修复：

移除未知配置键
修正类型错误（字符串加引号，数字不加）
添加必填字段
使用 JSON5 语法（支持注释和尾随逗号）

3.7 沙箱问题解决方案

症状： 沙箱模式启用但容器无法启动

解决方案：

# 1. 检查 Docker 状态
docker ps

# 2. 构建沙箱镜像
cd ~/.openclaw
./scripts/sandbox-setup.sh

# 3. 检查配置
openclaw config get agents.defaults.sandbox

# 4. 修复配置
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent"     // session | agent | shared
      }
    }
  }
}

3.8 浏览器工具问题解决方案

症状： browser 工具调用失败

解决方案：

# 1. 检查浏览器状态
openclaw browser status

# 2. 启动浏览器
openclaw browser start--browser-profile openclaw

# 3. 查看可用配置
openclaw browser profiles

# 4. 检查日志
openclaw logs --follow

Chrome 扩展中继模式：

确保安装 OpenClaw Browser Relay 扩展
点击扩展图标连接到目标标签页
使用 profile="chrome-relay" 时确保标签页已附加

3.9 Cron 和心跳问题解决方案

症状： 定时任务或心跳未执行

解决方案：

# 1. 检查 Cron 状态
openclaw cron status
openclaw cron list

# 2. 查看执行历史
openclaw cron runs --id <jobId> --limit20

# 3. 检查心跳状态
openclaw system heartbeat last

# 4. 查看日志
openclaw logs --follow

修复配置：

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  },
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        directPolicy: "allow"  // 允许 DM 风格目标
      }
    }
  }
}

3.10 升级后问题解决方案

症状： 升级后某些功能突然失效

检查清单：

# 1. 检查认证和 URL 覆盖
openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

# 2. 检查绑定和认证
openclaw config get gateway.bind
openclaw config get gateway.auth.token

# 3. 检查配对和设备状态
openclaw devices list
openclaw pairing list --channel <channel>

# 4. 运行深度检查
openclaw doctor --deep

常见问题：

认证模式变更： 显式 --url 调用不回退到存储的凭据
绑定更严格： 非本地绑定需要配置认证
配对状态变更： 策略或身份变更后需要重新审批

四、预防性维护建议

4.1 定期运行健康检查

# 每周运行一次 openclaw doctor  # 每天检查状态 openclaw status openclaw gateway status

4.2 备份配置和状态

# 备份配置 cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup  # 使用 Git 管理工作区 cd ~/.openclaw/workspace git init git add . git commit -m "Initial backup"

4.3 保持更新

# 检查更新 openclaw --version  # 更新 OpenClaw npm update -g openclaw  # 或重新运行安装脚本 curl -fsSL https://openclaw.ai/install.sh | bash

4.4 监控日志

# 持续监控 openclaw logs --follow  # 查看最近错误 openclaw logs --grep "error" --limit 100

五、获取帮助

官方资源

文档：https://docs.openclaw.ai
本地文档：~/.openclaw/node_modules/openclaw/docs
GitHub：https://github.com/openclaw/openclaw
Discord 社区：https://discord.com/invite/clawd
技能市场：https://clawhub.com

常用命令速查

# 状态检查 openclaw status openclaw gateway status openclaw nodes status openclaw channels status --probe  # 诊断修复 openclaw doctor openclaw doctor --repair openclaw doctor --deep  # 日志查看 openclaw logs --follow openclaw logs --grep "error"  # 配置管理 openclaw config get <key> openclaw config set <key> <value> openclaw configure  # 设备管理 openclaw devices list openclaw devices approve <id> openclaw pairing list --channel <channel>

一、安装和启动常见错误

1.1 openclaw 命令未找到

1.2 sharp 构建错误

1.3 Git 未找到错误

1.4 网关服务无法启动

1.5 npm EACCES 权限错误（Linux）

二、OpenClaw 错误码详解

2.1 设备配对相关错误

2.2 节点工具错误

2.3 通道和消息错误

2.4 浏览器工具错误

2.5 模型和 API 错误

2.6 配置验证错误

2.7 沙箱和 Docker 错误

2.8 Cron 和心跳错误

三、错误解决方案

3.1 通用诊断流程

3.2 设备配对问题解决方案

3.3 节点工具失败解决方案

3.4 通道消息不流通解决方案

3.5 模型 API 错误解决方案

3.6 配置验证失败解决方案

3.7 沙箱问题解决方案

3.8 浏览器工具问题解决方案

3.9 Cron 和心跳问题解决方案

3.10 升级后问题解决方案

四、预防性维护建议

4.1 定期运行健康检查

4.2 备份配置和状态

4.3 保持更新

4.4 监控日志

五、获取帮助

官方资源

常用命令速查

1.1 `openclaw` 命令未找到