OpenClaw 踩坑,5 个必看

OpenClaw 踩坑，5 个必看

Windows 装 OpenClaw 踩了一圈坑，把解决方案整理出来，省得你们再走弯路。

这 5 个问题覆盖了掘金和知乎上 80% 的求助帖。

坑 1：Node.js 版本不对

：

或

：OpenClaw 需要 Node.js 18+，很多人装的还是 14 或 16。

：

# 检查当前版本
node -v
如果低于 18，去 nodejs.org 下最新 LTS
或者用 nvm-windows：
nvm install 20
nvm use 20

注意：别装 Node 22（奇数版本是不稳定版），装 20 LTS 最稳。

坑 2：权限问题导致安装失败

：

或

：Windows 的 C:\Program Files 目录有写入保护。

（三选一）：

1. 用管理员权限打开终端（右键 → "以管理员身份运行"）
2. 把 npm 全局路径改到用户目录：

   npm config set prefix "%USERPROFILE%\.npm-global"
   

1. 直接用 npx 运行，不全局安装

第三种最省事，推荐。

坑 3：模型配置连不上

：

或

：

• 接 Ollama 本地模型：Ollama 没启动，或端口被占
• 接在线 API：Key 过期、或者网络代理拦截了请求

：

# 检查 Ollama 是否在跑
curl http://localhost:11434/api/tags
检查 API Key 是否有效（以 Groq 为例）
curl -H "Authorization: Bearer YOUR_KEY" https://api.groq.com/openai/v1/models

如果用了 Clash 等代理，把 localhost 和 API 域名加到直连规则里。

坑 4：中文路径乱码

：

（路径里有中文）

：Windows 用户名是中文（如

），Node.js 处理路径时会炸。

：

1. 把 OpenClaw 安装到纯英文路径，比如 D:\openclaw\
2. 设置 npm 缓存路径：

   npm config set cache "D:\npm-cache"
   

1. 如果已经装了，创建一个英文目录的符号链接：

   mklink /D "C:\openclaw" "C:\Users\小明\openclaw"
   

坑 5：依赖包安装卡住

：

跑了 10 分钟还没动静，或者报

：npm 默认源在国外，大陆访问慢。

：

# 换淘宝镜像
npm config set registry https://registry.npmmirror.com
然后重新安装
npm install

如果是 playwright 或 puppeteer 的 chromium 下载卡住：

# Windows
set PLAYWRIGHT_BROWSERS_PATH=D:\browsers
npx playwright install chromium

通用排查思路

以上 5 个坑不够用的话，记住这个排查顺序：

1. 看完整报错：别只看第一行，往下翻找 cause 或 reason
2. 检查版本：node -v、npm -v，确认 Node 18+
3. 检查网络：ping api.groq.com，确认能连外网
4. 检查路径：确认没有中文、空格、特殊字符
5. 清缓存重来：npm cache clean --force && rm -rf node_modules && npm install

遇到搞不定的问题，去 GitHub Issues 搜一下关键词，大概率有人踩过。

如果你懒得折腾 API 配置，可以试试 OpenRelay（https://github.com/romgX/openrelay），一键聚合免费模型，省得逐个配 Key。

你在 Windows 上还踩过什么坑？评论区说说，我补充进去。

开源项目 · GitHub: romgX/openrelay