新手常见问题汇总：安装/配置/使用排错

整理了新手在使用 OpenClaw 过程中最常遇到的问题和解决方案。

---

安装相关

Q: npm install 权限错误

错误： EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'

解决方案：

# 方法一：使用 sudo（简单直接）
sudo npm install -g openclaw --unsafe-perm

# 方法二：修改 npm 全局目录权限（推荐，避免每次 sudo）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw

---

Q: Node.js 版本太低

错误： error: openclaw requires Node.js version >= 18

解决方案：

升级 Node.js，推荐使用 nvm：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc

# 安装 Node.js 20
nvm install 20
nvm alias default 20

# 验证
node --version  # 应该显示 v20.x+

---

Q: 网络慢安装失败

错误： 下载超时，网络错误

解决方案： 使用淘宝 npm 镜像：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw

---

配置相关

Q: API Key 不正确

错误： 401 Unauthorized 或 Invalid API Key

解决方案：

1. 检查 API Key 是否正确复制
2. 检查 API Key 是否有空格，去掉前后空格
3. 确认账户有可用额度

---

Q: 模型调用超时

错误： 请求超时，长时间没有响应

解决方案：

1. 检查网络连接是否正常
2. 如果使用境外模型，确认代理配置正确
3. 有些大模型响应慢，可以耐心等待一会儿
4. 尝试切换到其他模型测试是否可用

---

Q: 忘记 API Key 放哪里了

OpenClaw 配置文件在：~/.openclaw/openclaw.json，你可以编辑这个文件修改 API Key。

---

启动相关

Q: 端口被占用

错误： listen EADDRINUSE: address already in use :::18789

解决方案：

# 查找占用端口的进程
lsof -i :18789

# 杀掉占用进程
kill <PID>

# 或者修改 OpenClaw 配置，换一个端口
# 编辑 ~/.openclaw/openclaw.json 修改 gateway.port

---

Q: 启动后无法访问 Web UI

检查清单：

1. 确认防火墙是否开放了 18789 端口
2. 如果是远程服务器，确认绑定地址不是 127.0.0.1
3. 检查 OpenClaw 是否真的在运行：ps aux | grep openclaw

---

使用相关

Q: AI 不调用工具，只会聊天

可能原因：

1. 模型不支持工具调用 – 换一个支持工具调用的模型
2. 提示不够清晰 – 明确告诉 AI “使用工具帮我完成这个任务”
3. 上下文太长 – 清理一下旧会话

解决方案： 使用 volcengine-plan/ark-code-latest 或 modelstudio/qwen3.5-plus，这两个都对工具调用支持很好。

---

Q: 工具调用出错了怎么办？

直接把错误信息贴给 AI，它一般能自己修复问题。OpenClaw 设计就是让 AI 自己发现并修正错误。

---

Q: 会话上下文太长了怎么办？

OpenClaw 会自动处理上下文压缩，如果感觉变慢了，可以：

1. 开始一个新会话
2. 删除一些旧的不需要的会话

---

Q: 如何更新 OpenClaw 到最新版本？

npm update -g openclaw
# 如果需要 sudo
sudo npm update -g openclaw

然后重启 OpenClaw 生效。

---

还有问题？

如果你遇到了这里没列出的问题，可以：

1. 查看 OpenClaw GitHub Issues
2. 在 OpenClaw 社区提问
3. 给我留言，我会尽力帮你解决

---

本文会持续更新，欢迎收藏。