1. Windows 11 部署 OpenClaw 到底卡在哪OpenClaw 是一个可以在本地跑起来的 AI 智能体网关它能对接多种大模型把对话、工具调用、文件操作这些能力统一到一个 Web 界面里。适合谁适合想在 Windows 11 上本地跑一个可操控的 AI Agent、又不想折腾 Linux 双系统的开发者。但问题来了——很多人第一次在 Win11 上装 OpenClaw卡的不是 OpenClaw 本身而是它依赖的三件套Node.js、git、npm。我见过太多人在这三步翻车Node.js 版本太低导致openclaw命令直接报错git 没装导致 npm 拉取依赖时code 128npm 全局路径没配好装完了却找不到命令。这三个问题单独看都不难但凑在一起新手很容易在第一步就放弃。这篇内容聚焦一件事在 Windows 11 下从零把 Node.js、git、npm 环境一次跑通然后完成 OpenClaw 的安装、配置、启动和端到端验证。每一步都给可复制的命令和参数遇到报错也知道去哪查。你跟着做最后应该能在浏览器里打开http://127.0.0.1:18789/overview看到 WebChat 界面。先说清楚版本要求Node.js 需要 22 或更高实测用 v24.14.0 没问题git 用 2.53.0.windows.1 验证通过。低于这个版本后面大概率会出问题。2. 装 OpenClaw 前先把 Node.js、git、npm 三件套配好2.1 Node.js 安装与路径选择Node.js 是 OpenClaw 的运行底座npm 是它的包管理器git 用来拉取部分依赖。三者缺一不可。去 Node.js 官网下载 Windows 安装包选 LTS 版本即可。安装时有一个关键点尽量用默认路径也就是C:\Program Files\nodejs\。为什么因为 OpenClaw 在调用 node 程序时如果路径里有空格或中文某些子进程调用会失败。默认路径最稳。安装完成后打开 PowerShell不是 CMD后面命令都用 PowerShell验证node -v npm -v正常输出类似v24.14.0 11.6.0如果node -v报「不是内部或外部命令」说明 PATH 没生效。关掉 PowerShell 重新开一个或者手动把C:\Program Files\nodejs\加到系统环境变量 Path 里。2.2 git 安装与版本校验git 官网下载 Windows 版一路默认下一步即可。安装完验证git --version输出git version 2.53.0.windows.1就对了。git 在这里的作用不是让你提交代码而是 npm 在拉取某些 GitHub 上的依赖时会调用 git 协议。如果没装 gitnpm 会报code 128这个错误后面会专门讲。2.3 npm 全局路径与环境变量npm 随 Node.js 一起装好了但全局安装的包默认放在C:\Users\你的用户名\AppData\Roaming\npm。这个路径通常已经在 PATH 里但如果你改过 npm 配置可能就丢了。检查一下npm config get prefix如果输出的路径不在系统 PATH 里手动加进去。或者直接重设npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm改完记得重启 PowerShell。这一步不做后面npm install -g openclaw装完了会提示「openclaw 不是内部或外部命令」。三件套验证命令汇总你可以一次性跑node -v; npm -v; git --version三个都有版本号输出前置环境就算通了。3. 安装 OpenClaw 并生成可复制的 config.toml 骨架3.1 全局安装 OpenClaw环境通了之后一条命令装 OpenClawnpm install -g openclawlatest等它跑完验证openclaw --version有版本号输出就说明装好了。如果报错先回头看第 2 节的 npm 全局路径。3.2 初始化配置与 onboardOpenClaw 提供了一个引导命令帮你生成初始配置openclaw onboard --install-daemon执行后会有一系列交互提示。模型选择那一步如果你有 GitHub 账号可以直接在弹出页面里登录验证也可以选千问等其他模型。其他选项第一次可以先跳过后面在配置文件里改。这一步会在C:\Users\你的用户名\.openclaw\下生成配置文件主要是openclaw.json。3.3 config.toml 骨架与关键字段OpenClaw 的配置核心在.openclaw目录下。虽然主配置是openclaw.json但很多场景会用到 TOML 格式的配置骨架。下面是一个可复制的基础骨架你可以按需改成config.toml[gateway] port 18789 host 127.0.0.1 [model] provider qwen api_key 你的API Key base_url https://taotoken.net/api [tools] profile full [log] level info几个关键点说明gateway.port默认 18789和后面启动命令保持一致。model.base_url指向模型服务的 API 地址如果你用 TaoToken 这类聚合服务填https://taotoken.net/api即可。tools.profile是权限策略默认是minimal或messaging会导致文件操作、命令执行等工具被禁用改成full才能解锁全部工具。注意tools.profile改成full意味着 OpenClaw 可以执行文件操作和命令本地跑没问题但不要把它暴露到公网。4. 启动 Gateway 并做一次端到端验证4.1 启动命令与参数配置就绪后启动 Gatewayopenclaw gateway --port 18789 --verbose--verbose会打印详细日志方便定位问题。启动成功后日志里会出现监听127.0.0.1:18789的信息。如果之前已经启动过改了配置需要重启openclaw gateway restart openclaw gateway --port 18789 --verbose4.2 打开 WebChat 并填入 token浏览器访问http://127.0.0.1:18789/overview第一次打开可能显示不正常或者 WebChat 页面弹出告警。这是因为还没填入访问 token。打开C:\Users\你的用户名\.openclaw\openclaw.json找到token字段把它的值复制到 WebChat 页面的输入框里再点连接。刷新后就能看到正常的 WebChat 界面了。4.3 一次成功的请求验证在 WebChat 里发一条测试消息比如「你好帮我列一下当前目录的文件」。如果tools.profile已经改成full它应该能调用文件工具并返回结果。如果返回的是权限被禁用的提示说明 profile 还没生效回去检查配置并重启 Gateway。这一步跑通说明从 Node.js 环境到 OpenClaw 网关再到模型调用的整条链路都通了。5. 本篇常见报错排查5.1 npm error code 128这是最常见的报错原因是 npm 拉取 GitHub 依赖时 git 认证失败。排查顺序先确认 git 装了git --version。然后检查 SSH 密钥配置。如果你没有 GitHub SSH keynpm 走 https 拉取也可能因为网络或认证问题报 128。最快的验证方式是手动 clone 一个仓库试试git clone https://github.com/openclaw/openclaw.git如果这一步就失败说明 git 本身有问题重装 git 或配置 SSH key。如果 clone 成功但 npm 还报 128清一下 npm 缓存再装npm cache clean --force npm install -g openclawlatest5.2 openclaw 不是内部或外部命令装完了但命令找不到99% 是 npm 全局路径没在 PATH 里。回到 2.3 节用npm config get prefix确认路径然后加到系统环境变量。改完必须重启 PowerShell旧窗口不会自动刷新 PATH。5.3 Tools 工具权限被禁用WebChat 里让 OpenClaw 操作文件或执行命令返回权限不足。原因是默认的minimal或messagingprofile 禁用了敏感工具。打开openclaw.json在tools部分把profile改成full保存后重启 Gatewayopenclaw gateway restart openclaw gateway --port 18789 --verbose5.4 网页显示不正常或 WebChat 告警先确认 Gateway 在跑端口没被占用。然后检查 token 是否填对。如果页面样式错乱强制刷新CtrlF5清一下缓存。还不行就看--verbose日志里有没有报错。5.5 Node.js 版本过低openclaw启动时报语法错误或模块找不到先查node -v。低于 22 就升级。升级后 npm 全局包可能需要重装npm install -g openclawlatest6. 环境跑通之后Key 和文档去哪找环境跑通只是第一步接下来你要接模型、调工具、写 Agent 逻辑。这时候需要两样东西API Key 和接入文档。API Key 在控制台里生成地址是 https://taotoken.net/api-keys 生成后填到config.toml的model.api_key字段或者openclaw.json对应位置。接入文档在 https://taotoken.net/doc 里面有各模型的 base_url、参数说明和调用示例对着改配置就行。如果你只是想先验证模型能不能通可以直接用模型对话页面发一条消息试试https://taotoken.net/chat 。确认模型侧没问题再回来调 OpenClaw 的配置。长期跑编码任务或者 Agent 工作流的话Coding Plan 更划算地址是 https://taotoken.net/coding-plan 适合需要持续调用、频繁调试的场景。配置改完记得重启 Gateway然后回 WebChat 发一条真实请求验证。整条链路通了你就可以开始往 OpenClaw 里加自己的工具和逻辑了。