OpenClaw 安装踩坑全记录：10 个常见问题解决

过来人的血泪经验，帮你少走弯路

问题 1：npm install 失败

症状：

npm ERR! network timeout

解决：

# 换淘宝源
npm config set registry https://registry.npmmirror.com

# 或用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g openclaw

问题 2：Python 版本不兼容

症状：

Error: Python 3.7+ required

解决：

# macOS 用 Homebrew
brew install python@3.11

# 创建软链接
ln -s /opt/homebrew/bin/python3.11 /usr/local/bin/python3

问题 3：权限问题

症状：

EACCES: permission denied

解决：

# 方案 1：用 sudo（不推荐）
sudo npm install -g openclaw

# 方案 2：修改 npm 目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

问题 4：API Key 无效

症状：

Error: Invalid API key

排查：

1. 检查 Key 是否正确复制（没有多余空格）
2. 检查 Key 是否过期
3. 检查账户余额

解决：

# 测试 API Key
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

问题 5：端口被占用

症状：

Error: Port 3000 already in use

解决：

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

# 杀掉进程
kill -9 <PID>

# 或换端口
openclaw start --port 3001

问题 6：配置文件找不到

症状：

Config file not found

解决：

# 初始化配置
openclaw init

# 或指定配置文件
openclaw start --config /path/to/config.yaml

问题 7：Telegram Bot 不响应

症状：发了消息没反应

排查：

1. Bot Token 是否正确
2. 是否已经 /start
3. 网络是否能访问 Telegram

解决：

# 测试 Bot
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

# 检查 Webhook
curl https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo

问题 8：心跳任务不执行

症状：配置了心跳但不运行

解决：

# 确保配置正确
heartbeat:
  enabled: true
  interval: 5m  # 至少 1m

# 检查日志
openclaw logs --tail 100

问题 9：内存占用过高

症状：OpenClaw 占用几个 G 内存

解决：

# 限制历史记录
memory:
  max_turns: 20  # 默认 50

# 禁用不需要的功能
features:
  embedding: false  # 不需要向量搜索时禁用

问题 10：升级后配置失效

症状：升级后不工作

解决：

# 备份配置
cp ~/.openclaw/config.yaml ~/config.yaml.bak

# 重新初始化
openclaw init

# 对比新旧配置，合并差异
diff ~/.openclaw/config.yaml ~/config.yaml.bak

快速诊断命令

# 检查状态
openclaw status

# 检查配置
openclaw config check

# 检查日志
openclaw logs --tail 50

# 测试连接
openclaw test --model deepseek-chat

还有问题？

1. 官方文档：docs.openclaw.ai
2. Discord 社区：discord.com/invite/claw…
3. 中文支持：微信 yang1002378395

---

💡 你遇到过什么坑？评论区分享，帮更多人避雷！