OpenClaw 安装踩坑指南！5个最常见问题一次解决 🦞

## 正文

💻 **装完了找不到命令？**

输入 `openclaw` 提示 command not found？

✅ 原因：npm 全局目录没加到 PATH
✅ 解决：
• Windows：添加 `C:\Users\用户名\AppData\Roaming\npm` 到 PATH
• Mac/Linux：添加 `~/.npm-global/bin` 到 PATH
• 验证：`openclaw --version` 显示版本号就对了

---

🔒 **安装时权限不足？**

遇到 EACCES: permission denied 错误？

❌ 别用 sudo！会导致后续权限混乱

✅ 正确做法：
```bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
```

Windows 用户：以管理员身份运行 PowerShell

---

🚀 **Gateway 启动失败？**

提示"未设置运行模式"或端口被占用？

✅ 三步解决：
1. 运行引导：`openclaw onboard --install-daemon`
2. 检查端口：`lsof -i :18789`（Mac/Linux）
3. 查看状态：`openclaw gateway status`

---

🔑 **API Key 配置错误？**

提示"凭证验证失败"？

常见原因：
• 复制不完整（有空格或换行）
• 账户余额不足
• Provider 设置和 Key 来源不匹配

✅ 解决：
• 重新运行：`openclaw onboard`
• 仔细粘贴完整 API Key
• 确认 Provider 设置正确

---

🪟 **Windows 特有问题？**

安装报错：Git 未安装、C++ 工具链缺失、CMake 下载失败？

✅ 三步搞定：
1. 安装 Git：`winget install Git`
2. 安装 Visual Studio Build Tools（含 C++ 工作负载）
3. 万能诊断：`openclaw doctor --fix`（自动修复 80% 问题）

---

🛠️ **通用排查工具**

• `openclaw doctor` - 诊断问题
• `openclaw doctor --fix` - 自动修复
• `openclaw status` - 查看系统状态
• `openclaw logs --follow` - 实时查看日志

---

💡 **最佳实践**

✓ 分步配置：先配置一个模型，确保能用再添加其他
✓ 保持更新：定期运行 `openclaw update`
✓ 备份配置：修改前先备份 `openclaw.json`
✓ 独立环境：建议在干净的虚拟机或云服务器上运行

#OpenClaw #ai编程