OpenClaw 安装常见问题解决 🔧

在安装 OpenClaw 的过程中，你可能会遇到一些问题。这篇文章整理了最常见的问题和解决方案，帮你快速排除障碍。

问题 1：npm 安装失败

症状

命令
npm install -g openclaw
# Error: EACCES: permission denied
可左右滑动查看完整代码

解决方案

方法 1：使用 sudo（不推荐）

命令
sudo npm install -g openclaw
可左右滑动查看完整代码

方法 2：修改 npm 全局目录（推荐）

命令
# 创建全局目录
mkdir ~/.npm-global

# 配置 npm
npm config set prefix '~/.npm-global'

# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g openclaw
可左右滑动查看完整代码

方法 3：使用 nvm（最推荐）

命令
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js
nvm install node

# 安装 OpenClaw
npm install -g openclaw
可左右滑动查看完整代码

问题 2：Node.js 版本过低

症状

命令
openclaw: command not found
# 或
Error: Unsupported Node.js version
可左右滑动查看完整代码

解决方案

检查 Node.js 版本

命令
node --version
可左右滑动查看完整代码

OpenClaw 要求 Node.js >= 18

升级 Node.js

命令
# 使用 nvm
nvm install 18
nvm use 18

# 或直接从官网下载
# https://nodejs.org/
可左右滑动查看完整代码

问题 3：Gateway 启动失败

症状

命令
openclaw gateway start
# Error: Port 3000 already in use
可左右滑动查看完整代码

解决方案

方法 1：更换端口

命令
# 编辑配置文件
nano ~/.openclaw/config.json

# 修改端口
{
  "gateway": {
    "port": 3001
  }
}
可左右滑动查看完整代码

方法 2：关闭占用端口的进程

命令
# 查找占用进程
lsof -i :3000

# 关闭进程
kill -9 <PID>
可左右滑动查看完整代码

问题 4：Agent 创建失败

症状

命令
openclaw agents create my-agent
# Error: Agent already exists
可左右滑动查看完整代码

解决方案

查看现有 Agent

命令
openclaw agents list
可左右滑动查看完整代码

删除重复 Agent

命令
openclaw agents delete my-agent
可左右滑动查看完整代码

使用不同名称

命令
openclaw agents create my-assistant
可左右滑动查看完整代码

问题 5：无法连接 AI 模型

症状

命令
# Agent 无响应
# 或报错：API key not configured
可左右滑动查看完整代码

解决方案

配置 API Key

命令
# 编辑配置
nano ~/.openclaw/config.json

# 添加 API Key
{
  "models": {
    "default": "claude-3-sonnet",
    "apiKeys": {
      "anthropic": "sk-ant-xxx"
    }
  }
}
可左右滑动查看完整代码

支持的模型提供商

Anthropic (Claude)
OpenAI (GPT)
Google (Gemini)
本地模型 (Ollama)

问题 6：技能包安装失败

症状

命令
clawhub install weather
# Error: Rate limit exceeded
可左右滑动查看完整代码

解决方案

等待速率限制重置

ClawHub 有速率限制
通常 1 小时后重置

手动安装技能

命令
# 克隆技能仓库
git clone https://github.com/openclaw/skill-weather
cd skill-weather

# 链接到 OpenClaw
openclaw skills link .
可左右滑动查看完整代码

问题 7：Telegram Bot 连接失败

症状

命令
# Bot 无响应
# 或 Webhook 设置失败
可左右滑动查看完整代码

解决方案

检查 Bot Token

命令
# 确认 Token 格式正确
# 格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
可左右滑动查看完整代码

检查网络连接

命令
# 测试 Telegram API
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
可左右滑动查看完整代码

重新配置 Bot

命令
# 编辑配置
nano ~/.openclaw/agents/main/config.json

# 更新 Telegram 配置
{
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

# 重启服务
openclaw gateway restart
可左右滑动查看完整代码

问题 8：内存不足

症状

命令
# 系统变慢
# 或 JavaScript heap out of memory
可左右滑动查看完整代码

解决方案

增加 Node.js 内存限制

命令
# 设置环境变量
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在启动时指定
node --max-old-space-size=4096 $(which openclaw) gateway start
可左右滑动查看完整代码

优化 Agent 配置

命令
# 减少并发 Agent 数量
# 清理旧的会话记录
openclaw sessions clean --older-than 7d
可左右滑动查看完整代码

问题 9：配置文件损坏

症状

命令
# 启动报错
# Error: Invalid JSON
可左右滑动查看完整代码

解决方案

备份并重置配置

命令
# 备份现有配置
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup

# 重新初始化
openclaw init --reset
可左右滑动查看完整代码

验证 JSON 格式

命令
# 使用 jq 验证
cat ~/.openclaw/config.json | jq .
可左右滑动查看完整代码

问题 10：权限问题

症状

命令
# Error: EACCES: permission denied
可左右滑动查看完整代码

解决方案

修复文件权限

命令
# 修复 OpenClaw 目录权限
chmod -R 755 ~/.openclaw

# 修复配置文件权限
chmod 644 ~/.openclaw/config.json
可左右滑动查看完整代码

🔍 诊断工具

检查系统状态

命令
openclaw status
可左右滑动查看完整代码

查看日志

命令
# Gateway 日志
openclaw gateway logs

# Agent 日志
openclaw agents logs main
可左右滑动查看完整代码

测试连接

命令
# 测试 AI 模型连接
openclaw test model

# 测试 Telegram 连接
openclaw test telegram
可左右滑动查看完整代码

💡 预防措施

1. 定期更新

命令
npm update -g openclaw
可左右滑动查看完整代码

2. 备份配置

命令
# 定期备份
cp -r ~/.openclaw ~/.openclaw.backup
可左右滑动查看完整代码

3. 监控资源

命令
# 查看资源使用
openclaw stats
可左右滑动查看完整代码

🆘 获取帮助

官方资源

📚 文档: https://docs.openclaw.ai
💬 Discord: https://discord.com/invite/clawd
🐛 GitHub Issues: https://github.com/openclaw/openclaw/issues

社区支持

HarvestClaw 社区
Telegram 用户群
中文技术论坛

🎯 下一步

问题解决后，继续学习：

遇到其他问题？在 HarvestClaw 社区提问，我们会持续更新这篇文章！

by 丰收管家 🌾