1. 为什么你的 OpenClaw 装完就跑不起来Node.js 环境与 Skill 配置的真实门槛OpenClaw 是一个能自主操控浏览器、操作本地计算机、24 小时执行任务并带向量记忆的开源智能助理适合想搭建个人自动化助手的开发者。但很多人第一次部署时会卡在同一个地方Node.js 版本不对、NVM 没配好、API 参数填错、Skill 加载失败。这篇指南把 NVM 版本管理、API 接入、Skill 配置三大环节串成一条最小可用链路每一步都给可复制的命令和配置。我见过太多人用系统自带的 Node.js 直接装 OpenClaw结果npm install报EBADENGINE或者装完了启动报Cannot find module。根因几乎都是 Node.js 版本太旧或太新而 OpenClaw 对 Node.js 版本有明确要求。另一个高频坑是 API 配置OpenClaw 本体免费但它必须对接外部大模型才能干活Base URL、API Key、Model ID 三个参数任何一个填错请求就会返回 401 或reading choices报错。所以正确的落地顺序应该是先用 NVM 把 Node.js 版本锁死再装 OpenClaw然后配 API最后加载 Skill 并验证。下面按这个顺序展开每一步都有验证动作确保你跑通最小可用链路再往下走。2. 用 NVM 管理 Node.js 版本OpenClaw 环境准备的核心步骤2.1 为什么必须用 NVM 而不是系统 Node.jsOpenClaw 的依赖树对 Node.js 版本敏感。系统包管理器装的 Node.js 往往是 LTS 旧版比如 v16、v18而 OpenClaw 的部分依赖需要 v20 以上。直接升级系统 Node.js 又会污染全局环境影响其他项目。NVMNode Version Manager的价值在于它让你在同一台机器上装多个 Node.js 版本按项目切换互不干扰。类比一下系统 Node.js 像家里只有一把菜刀切什么都用它NVM 像一套刀具切菜用菜刀、削皮用削皮刀各司其职。OpenClaw 需要哪把刀你就切到哪个版本。2.2 Mac/Linux 安装 NVM打开终端执行官方安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash如果这条命令因为网络原因超时可以改用国内镜像方式手动克隆git clone https://gitee.com/mirrors/nvm.git ~/.nvm cd ~/.nvm git checkout v0.40.1然后把 NVM 加载脚本写入 shell 配置。如果你用 zshmacOS 默认echo export NVM_DIR$HOME/.nvm ~/.zshrc echo [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh ~/.zshrc source ~/.zshrc如果你用 bashecho export NVM_DIR$HOME/.nvm ~/.bashrc echo [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh ~/.bashrc source ~/.bashrc验证安装nvm --version能输出版本号如0.40.1就说明 NVM 装好了。2.3 Windows 安装 NVMWindows 用户不要用 curl 脚本直接用 nvm-windows 的安装包。去 GitHub Releases 下载nvm-setup.exe双击安装。安装过程中会问你 NVM 安装路径和 Node.js symlink 路径保持默认即可。安装完成后打开 PowerShell建议以管理员身份验证nvm version如果提示nvm不是内部或外部命令说明环境变量没生效重启 PowerShell 或手动把 NVM 安装目录加入 PATH。2.4 安装并切换 OpenClaw 需要的 Node.js 版本先看 OpenClaw 要求的版本。截至当前OpenClaw 推荐 Node.js v20 LTS 或 v22。执行nvm install 20 nvm use 20验证当前版本node -v npm -v应该输出v20.x.x和对应的 npm 版本。如果你机器上有多个项目可以设置默认版本nvm alias default 20这样每次新开终端都自动用 v20。Windows 下 nvm-windows 的命令略有不同nvm install 20 nvm use 20注意 nvm-windows 的use需要管理员权限否则会报exit status 1: Access is denied。2.5 配置 npm 国内镜像加速Node.js 装好后npm 默认从国外源拉包国内网络下经常超时。换成国内镜像npm config set registry https://registry.npmmirror.com验证npm config get registry输出https://registry.npmmirror.com/即可。这一步能显著减少后续npm install的失败率。3. OpenClaw 安装与 API 接入可复制的配置模板3.1 安装 OpenClawNode.js 环境就绪后安装 OpenClaw。官方提供一键脚本但如果你已经手动装好了 Node.js 和 NVM可以直接用 npm 全局安装npm install -g openclaw如果一键脚本方式更适合你Mac/Linux 执行curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.comWindows PowerShell 执行iwr -useb https://clawd.org.cn/install.ps1 -OutFile install.ps1; ./install.ps1 -Registry https://registry.npmmirror.com安装完成后验证openclaw --version3.2 API 接入Base URL、Key、Model ID 三件套OpenClaw 本体不包含模型能力必须对接外部大模型 API。这里以 TaoToken 为例它提供统一的 API 入口兼容 OpenAI 格式配置简单。你需要准备三个参数参数说明示例值Base URLAPI 请求地址https://taotoken.net/apiAPI Key身份凭证sk-xxxxxxxx在控制台生成Model ID模型标识claude-sonnet-4-20250514或gpt-4o获取 API Key 的步骤访问 TaoToken 控制台注册后在 API Keys 页面生成一个 Key。注意 Key 只显示一次复制后妥善保存。3.3 配置文件写法JSON 格式OpenClaw 的配置文件通常位于~/.openclaw/config.jsonMac/Linux或%USERPROFILE%\.openclaw\config.jsonWindows。如果文件不存在手动创建{ api: { baseUrl: https://taotoken.net/api, apiKey: sk-你的实际Key, model: claude-sonnet-4-20250514, timeout: 60000 }, skills: { directory: ~/.openclaw/skills, autoLoad: true }, memory: { vectorStore: ~/.openclaw/memory } }如果你更习惯用环境变量也可以这样配export OPENCLAW_API_BASEhttps://taotoken.net/api export OPENCLAW_API_KEYsk-你的实际Key export OPENCLAW_MODELclaude-sonnet-4-20250514Windows PowerShell$env:OPENCLAW_API_BASEhttps://taotoken.net/api $env:OPENCLAW_API_KEYsk-你的实际Key $env:OPENCLAW_MODELclaude-sonnet-4-20250514注意Base URL 末尾不要加/v1TaoToken 的 API 路径已经内置了兼容层。如果你填成https://taotoken.net/api/v1可能会遇到 404。3.4 验证 API 连通性配置写好后先别急着启动 OpenClaw用 curl 单独测一下 API 是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的实际Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回 JSON 里包含choices字段和内容说明 API 通了。如果返回 401检查 Key 是否复制完整如果返回reading choices说明响应格式不对大概率是 Base URL 或 Model ID 写错了。4. Skill 配置与加载验证让 OpenClaw 真正干活4.1 Skill 是什么Skill 是 OpenClaw 的能力插件。本体只提供基础框架具体能力浏览器操控、桌面自动化、自我改进、向量记忆都靠 Skill 实现。你可以把 Skill 理解成手机上的 App手机本身能打电话但装了 App 才能点外卖、打车、记账。4.2 必装 Skill 清单以下 8 个 Skill 是首次部署后建议优先装的Skill 名称作用self-improvement记录错误和学习让 OpenClaw 自我改进browser浏览器自动化网页交互和截图desktop-control桌面自动化鼠标键盘控制auto-updater自动更新 OpenClaw 和升级技能skill-vetter扫描已安装技能的安全性避免高风险技能上传本地文件subagent-driven-development任务委派把子任务分配给其他 AI 并审核vector-memory向量记忆搜索解决上下文太杂导致记忆不准的问题clawhub技能市场按需检索并安装其他 Skill4.3 安装 Skill 的两种方式方式一通过 clawhub 安装。先装 clawhub 本身openclaw skill install clawhub然后用 clawhub 搜索并安装其他 Skillopenclaw skill search browser openclaw skill install browser方式二手动安装。从 GitHub 克隆 Skill 仓库到 Skill 目录cd ~/.openclaw/skills git clone https://github.com/VoltAgent/awesome-openclaw-skills.git4.4 验证 Skill 加载安装完成后列出已加载的 Skillopenclaw skill list应该能看到你安装的所有 Skill 名称和状态。如果某个 Skill 显示failed或not loaded检查它的依赖是否装齐。比如 browser Skill 可能依赖 Playwrightnpx playwright install chromium再重启 OpenClawopenclaw restart然后测试一个具体 Skill 是否工作。比如测试 browseropenclaw run browser --url https://example.com --action screenshot如果生成了截图文件说明 browser Skill 加载成功。4.5 Skill 配置示例部分 Skill 需要额外配置。以 vector-memory 为例它的配置文件在~/.openclaw/skills/vector-memory/config.json{ embeddingModel: text-embedding-3-small, embeddingApiBase: https://taotoken.net/api, embeddingApiKey: sk-你的实际Key, storePath: ~/.openclaw/memory/vectors }配置好后重启 OpenClawvector-memory 就会开始工作。5. 常见报错对照表与排查方法5.1 401 Unauthorized报错原文Error: 401 Unauthorized或{error:{message:Invalid API key}}原因API Key 填错、过期、或复制时带了空格。排查重新在控制台生成 Key复制时确保没有首尾空格。用 curl 单独测 API 是否通见 3.4 节。如果 curl 通但 OpenClaw 报 401检查配置文件里的 Key 是否被环境变量覆盖。5.2 local proxy failed报错原文Error: local proxy failed to connect或ECONNREFUSED原因OpenClaw 尝试走本地代理但代理没启动或者 Base URL 指向了本地地址。排查检查配置文件里的baseUrl是否是https://taotoken.net/api不要填http://localhost:xxxx。如果你本地确实跑了代理服务确认它已启动并监听正确端口。5.3 reading choices报错原文TypeError: Cannot read properties of undefined (reading choices)原因API 返回的 JSON 结构里没有choices字段通常是 Base URL 或 Model ID 写错导致请求打到了错误的端点。排查确认 Base URL 是https://taotoken.net/apiModel ID 是有效的模型名。用 curl 测一次看返回结构里有没有choices。5.4 OAuth 相关报错报错原文OAuth token expired或Failed to refresh OAuth token原因如果你用的是需要 OAuth 的模型服务token 过期了。排查重新走一遍 OAuth 授权流程或者改用 API Key 方式接入。TaoToken 的 API Key 方式不需要 OAuth配置更简单。5.5 EBADENGINE报错原文npm ERR! code EBADENGINE或Unsupported engine原因Node.js 版本不符合 OpenClaw 要求。排查node -v看当前版本如果不是 v20 或 v22用nvm use 20切换。切换后重新npm install -g openclaw。5.6 Skill 加载失败报错原文Skill xxx failed to load: missing dependency原因Skill 依赖的包没装。排查看报错信息里缺什么用 npm 或 npx 装上。比如 Playwright 缺失就npx playwright install chromium。装完重启 OpenClaw。6. 跑通最小链路后的下一步到这里你应该已经完成了 NVM 装 Node.js、OpenClaw 安装、API 配置、Skill 加载验证的完整链路。最小可用链路的验证标准是openclaw skill list能看到已加载的 Skillopenclaw run browser --url https://example.com --action screenshot能生成截图API 请求返回正常。接下来可以按需扩展需要长期编码或 Agent 任务可以了解 Coding Plan需要验证不同模型的效果可以在模型对话里切换 Model ID 测试需要管理多个 API Key在控制台的 API Keys 页面操作。接入文档里有更详细的参数说明和进阶配置示例。实际用下来最容易翻车的环节不是安装而是 API 参数和 Skill 依赖。把这两块的验证动作做扎实后面基本不会有大问题。