1. Windows 上 openclaw 安装前必须搞清楚的几件事openclaw 是一个跑在本地的 AI 网关工具你可以把它理解成一个「模型路由器」它本身不生产模型能力而是把各家大模型的 API 统一收拢到一个本地地址上再通过浏览器界面或命令行去调用。对 Windows 新手来说它最大的价值是——不用折腾复杂的容器和编译环境一条 npm 命令就能装好然后用openclaw gateway把服务跑起来浏览器打开http://127.0.0.1:18789就能用。这篇教程面向的是完全没接触过 Node.js 生态的 Windows 用户。我会从 PowerShell 的打开方式讲起一路走到 gateway 启动成功、模型接入、报错排查。整个过程你只需要复制粘贴命令遇到问题对照第 5 节的报错表处理即可。先说清楚适合谁如果你手上是 Windows 10 或 Windows 11能正常联网愿意花 20 分钟跟着敲命令那这篇就是为你写的。如果你连「终端」是什么都没概念也没关系第一步我会告诉你右键点哪里。需要提前知道的两个概念后面会反复出现npm是 Node.js 的包管理器相当于 Windows 上的「应用商店命令行版」。npm install -g openclaw的意思就是「全局安装 openclaw 这个包」装完之后你在任何目录下都能直接敲openclaw命令。gateway是 openclaw 的核心服务进程。安装只是把程序文件放到硬盘上gateway 才是真正跑起来、监听端口、等待你访问的那个东西。很多人装完发现浏览器打不开十有八九是 gateway 没启动或者启动失败了。还有一个容易被忽略的点openclaw 默认监听127.0.0.1:18789这个地址只在本机可访问不会暴露到局域网所以不用担心安全问题。但反过来说如果你在另一台电脑上访问这个地址是打不开的这是正常的。我实测下来整个流程最容易卡住的地方有三个一是 PowerShell 权限不够导致 npm 全局安装失败二是 Node.js 版本太旧openclaw 装上了但跑不起来三是 gateway 启动了但端口被占用。这三个问题在第 5 节都有对应的排查方法。最后提醒一句安装过程中如果遇到需要登录授权的环节按提示操作即可。模型供应商的选择可以放到 gateway 跑通之后再做先把服务启动起来看到界面心里就有底了。2. 前置准备PowerShell 环境与 Node.js 检查在敲npm install之前得先确认你的 PowerShell 能正常工作并且 Node.js 和 npm 已经装好。这一步看起来简单但很多新手就是在这里埋了坑。2.1 用管理员身份打开 PowerShell右键点击屏幕左下角的 Windows 图标或者按Win X在弹出的菜单里选择「Windows PowerShell管理员」或者「终端管理员」。如果菜单里只有「终端」点进去之后默认就是 PowerShell 标签页。为什么要用管理员身份因为npm install -g是全局安装会往系统目录写文件。普通权限的 PowerShell 可能会在安装到一半时报EACCES或EPERM错误。用管理员身份能避开绝大部分权限问题。打开之后窗口标题栏应该显示「管理员」字样。你可以先敲一条命令确认一下当前身份whoami如果输出里包含administrator或者你的用户名说明没问题。接着确认 PowerShell 的执行策略不会拦截脚本。openclaw 的安装脚本是.ps1文件默认策略可能会阻止运行Get-ExecutionPolicy如果返回Restricted需要改成RemoteSignedSet-ExecutionPolicy RemoteSigned -Scope CurrentUser执行后会问你是否确认输入Y回车。这个设置只影响当前用户不会动系统全局策略相对安全。2.2 检查 Node.js 和 npm 版本openclaw 对 Node.js 版本有要求太旧的版本会在安装后运行时报语法错误。先查一下node -v npm -v理想情况下node -v应该返回v18.x或更高版本npm -v返回9.x或更高。如果提示「不是内部或外部命令」说明 Node.js 根本没装去 Node.js 官网下载 LTS 版本安装包一路下一步即可。安装完成后必须关掉当前 PowerShell 窗口重新打开否则环境变量不生效。如果 node 版本低于 18建议直接卸载重装最新 LTS。用旧版本硬撑后面 gateway 启动时可能报SyntaxError: Unexpected token之类的错排查起来很费时间。确认版本没问题后顺手把 npm 自身升级一下避免旧版 npm 的依赖解析 bugnpm install -g npmlatest这条命令跑完npm 就是最新版了。整个过程可能需要一两分钟取决于网络速度。如果卡住不动按Ctrl C中断然后检查网络或者换个时间段再试。2.3 配置 npm 的国内镜像可选但推荐如果你在国内网络环境下npm 默认源下载速度可能很慢甚至超时。可以临时切换到国内镜像加速npm config set registry https://registry.npmmirror.com设置完之后可以用npm config get registry确认。如果之后想换回官方源npm config set registry https://registry.npmjs.org这一步不是必须的但如果你在npm install阶段卡了很久没动静八成是网络问题换镜像能明显改善。2.4 确认没有旧版本残留如果你之前装过 openclaw 的旧版本建议先卸载干净再装新版避免版本冲突npm uninstall -g openclaw这条命令即使没装过也不会报错放心执行。卸载完成后可以再跑一次npm list -g --depth0看看全局包里还有没有 openclaw 的痕迹。到这里前置环境就准备好了。总结一下你现在应该具备的状态管理员 PowerShell 已打开、Node.js 18 和 npm 9 已就位、执行策略已放开、网络通畅。接下来进入正式安装环节。3. 可复制配置npm 安装 openclaw 与 gateway 启动这一节是整篇教程的核心所有命令都可以直接复制粘贴。我会按顺序给出安装、初始化、启动三步每一步都说明预期结果方便你对照。3.1 全局安装 openclaw在管理员 PowerShell 里执行npm install -g openclawlatest这条命令会从 npm 源拉取 openclaw 的最新版本并全局安装。安装过程中你会看到类似added 120 packages in 30s的输出包的数量和耗时因版本而异。只要最后没有红色的ERR字样就算成功。安装完成后验证一下openclaw --version如果返回一个版本号比如1.x.x说明命令已经可用。如果提示「无法将 openclaw 项识别为 cmdlet」说明全局安装路径没有加到 PATH 里。可以手动查一下 npm 的全局路径npm config get prefix把返回的路径通常是C:\Users\你的用户名\AppData\Roaming\npm加到系统环境变量 Path 里然后重开 PowerShell。3.2 运行新手引导向导openclaw 提供了一个交互式向导帮你完成初始配置openclaw onboard执行后会进入一个问答流程按下面的选择走第一步选择「QuickStart快速入门」。这个模式会用最简配置把服务跑起来适合第一次安装。第二步选择供应商。这里如果你还没有任何模型 API Key可以先选「Skip for now」等 gateway 跑通之后再回来配置。向导会提示你稍后可以用/model命令切换。第三步如果选了供应商会要求你填入 API Key 和 Base URL。以智谱为例Base URL 填https://open.bigmodel.cn/api/paas/v4Key 填你在开放平台生成的密钥。模型 ID 填glm-4.5-air或你资源包里可用的型号。第四步「跳过机器人配置」第五步「跳过 skill 配置」第六步指定特定事件时直接回车用默认值。最后确认完成安装。整个向导走完openclaw 的配置文件就生成好了。Windows 下配置文件通常位于C:\Users\你的用户名\.openclaw\目录里面会有config.json或settings.json。你可以用记事本打开看看确认里面的 Base URL 和模型 ID 写对了。如果你在向导里跳过了模型配置也可以手动编辑配置文件。一个典型的配置片段长这样{ provider: { baseUrl: https://open.bigmodel.cn/api/paas/v4, apiKey: 你的APIKey, model: glm-4.5-air }, gateway: { host: 127.0.0.1, port: 18789 } }注意baseUrl结尾不要多加斜杠model字段必须和供应商文档里的模型 ID 完全一致大小写敏感。写错的话 gateway 能启动但发请求时会报model not found。3.3 启动 gateway 服务配置完成后启动网关openclaw gateway如果一切正常你会看到类似下面的输出Gateway listening on http://127.0.0.1:18789 Press CtrlC to stop这时候不要关掉这个 PowerShell 窗口gateway 是前台进程关窗口就等于停服务。打开浏览器访问http://127.0.0.1:18789应该能看到 openclaw 的聊天界面。如果你想让 gateway 在后台运行可以用openclaw gateway start对应的停止命令是openclaw gateway stop重启是openclaw gateway restart。后台模式适合你不想一直开着终端窗口的场景。3.4 接入 TaoToken 作为统一入口可选如果你手上有多个供应商的 Key一个个配置比较麻烦。TaoToken 提供了一个统一的 API 入口可以把不同模型的调用收敛到一个 Base URL 上。配置方式是在 openclaw 的配置文件里把baseUrl改成https://taotoken.net/apiAPI Key 填你在 TaoToken 控制台生成的密钥。模型 ID 按你实际要用的填比如glm-4.5-air或qwen3.5-plus。这样切换模型时只需要改model字段不用动 Base URL。需要说明的是TaoToken 在这里扮演的是 API 聚合入口的角色openclaw 本身仍然是跑在你本地的网关两者不冲突。配置完成后同样用openclaw gateway restart让改动生效。4. 验证请求确认 gateway 真的跑通了gateway 启动成功不等于模型能正常调用。这一节教你从三个层面验证端口是否监听、界面是否可访问、模型是否真的能返回结果。4.1 检查端口监听状态在 PowerShell 里执行netstat -ano | findstr 18789如果返回类似TCP 127.0.0.1:18789 0.0.0.0:0 LISTENING的行说明端口已经在监听。最后一列是进程 ID可以用tasklist | findstr 进程ID确认是不是 node 进程。如果这条命令没有任何输出说明 gateway 没起来或者监听了别的端口。回到第 3 节重新启动并留意启动日志里有没有报错。4.2 用浏览器访问聊天界面打开浏览器地址栏输入http://127.0.0.1:18789正常情况下会加载出 openclaw 的 Web 界面。如果页面一直转圈或者显示「无法访问此网站」先确认 gateway 窗口还在运行然后试试http://127.0.0.1:18789/chat这个路径。界面加载出来后在输入框里发一条测试消息比如「你好请回复 OK」。如果模型配置正确几秒内会返回响应。如果返回的是错误信息记下错误内容对照第 5 节排查。4.3 用命令行直接测试 API除了浏览器也可以用 PowerShell 直接发请求验证 gateway 的 API 是否工作curl.exe -X POST http://127.0.0.1:18789/v1/chat/completions -H Content-Type: application/json -d {\model\:\glm-4.5-air\,\messages\:[{\role\:\user\,\content\:\回复OK\}]}注意 Windows PowerShell 里curl是Invoke-WebRequest的别名所以要用curl.exe调用真正的 curl。反引号是 PowerShell 的换行符整条命令可以一次性粘贴。如果返回的 JSON 里有choices字段和内容说明整条链路通了。如果返回401是 API Key 问题返回404是模型 ID 或路径问题返回connection refused是 gateway 没启动。4.4 切换模型的正确姿势在 openclaw 聊天框里输入/model glm-4.5-air就可以切换到指定模型。前提是这个模型 ID 在你的配置文件或供应商那边是有效的。切换成功后会提示当前使用的模型名称。如果你用的是 TaoToken 统一入口切换模型同样用/model命令只要 TaoToken 那边支持这个模型 ID 即可。这样你可以在同一个 gateway 里灵活切换不同供应商的模型不用反复改配置重启。验证环节的核心思路是先确认端口活着再确认界面能开最后确认模型能回话。三层都过了才算真正装好。5. 本篇常见报错排查401、local proxy failed、reading choices这一节收集了 Windows 上安装 openclaw 最高频的几类报错每条都给出原因和解决方法。遇到问题先在这里对照大部分情况不用重装。5.1 401 Unauthorized现象浏览器界面能打开但发消息后返回401或Unauthorized。原因API Key 无效、过期、或者填错了位置。也有可能是 Key 对应的账号没有实名认证供应商拒绝服务。排查步骤先确认配置文件里的apiKey字段没有多余空格。用记事本打开C:\Users\你的用户名\.openclaw\config.json检查 Key 是不是完整的一串。然后登录供应商控制台确认这个 Key 还在有效期内并且账号已完成实名认证。如果用的是 TaoToken去控制台确认 Key 的额度是否充足、是否绑定了正确的模型权限。改完配置后执行openclaw gateway restart重启后再试。如果还是 401换一个 Key 测试排除是 Key 本身的问题。5.2 local proxy failed / connection refused现象启动 gateway 时报local proxy failed或者浏览器访问时提示ERR_CONNECTION_REFUSED。原因gateway 进程没起来、端口被占用、或者配置文件里的 host/port 写错了。排查步骤先看 gateway 窗口有没有报错信息。如果窗口已经关了重新执行openclaw gateway观察输出。如果提示端口被占用netstat -ano | findstr 18789找到占用端口的进程 ID用taskkill /PID 进程ID /F结束它。或者改配置文件里的port字段换一个没被占用的端口比如18790然后重启 gateway。如果报错里提到proxy检查系统环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个不可用的地址。有的话临时清掉$env:HTTP_PROXY $env:HTTPS_PROXY然后重新启动 gateway。5.3 reading choices 报错现象发消息后返回Cannot read properties of undefined (reading choices)。原因gateway 收到了响应但响应格式不符合预期。通常是 Base URL 写错导致请求打到了错误的端点返回了非标准 JSON。排查步骤确认baseUrl结尾的路径正确。比如智谱是https://open.bigmodel.cn/api/paas/v4通义千问是https://dashscope.aliyuncs.com/compatible-mode/v1。少写或多写/v1、/v4都会导致这个问题。另外确认模型 ID 拼写正确。glm-4.5-air和glm-4.5-air末尾有空格是两个不同的字符串后者会报模型不存在。改完配置后openclaw gateway restart再发一条测试消息。5.4 OAuth 授权失败现象向导里选择供应商后跳转授权页面回调时报OAuth failed或一直卡在授权页。原因浏览器回调地址和本地服务不匹配或者授权超时。排查步骤先确认 gateway 正在运行因为 OAuth 回调需要本地服务接收。然后重新走一遍openclaw onboard在授权环节用默认浏览器打开链接不要用无痕模式。如果还是失败改用 API Key 方式手动配置跳过 OAuth 流程。5.5 报错速查表报错关键词最可能原因快速处理401 UnauthorizedKey 无效或未实名检查 Key、重启 gatewaylocal proxy failed端口占用或代理干扰换端口、清代理变量reading choicesBase URL 或模型 ID 错核对端点路径和模型名OAuth failed回调失败或超时改用 API Key 手动配置command not foundPATH 未配置把 npm 全局路径加入 Path排查的核心原则是先看报错原文再对照表格定位改完配置必须重启 gateway。不要改一处试一次就放弃很多问题是多个配置项叠加导致的。6. 装好之后怎么用模型接入与日常维护gateway 跑通只是起点接下来你要把真正要用的模型接进来并且知道日常怎么维护这个服务。6.1 用 TaoToken 统一管理多个模型如果你同时用智谱、通义、硅基流动等多家模型逐个配置 Base URL 很繁琐。TaoToken 的 API 入口可以把这些收敛成一个地址https://taotoken.net/api在 openclaw 配置文件里把baseUrl指向它apiKey填 TaoToken 控制台生成的密钥model字段填你要用的模型 ID。这样切换模型只需要改model一行不用动其他配置。TaoToken 的控制台地址是https://taotoken.net/consoleAPI Key 在https://taotoken.net/api-keys生成。如果你需要查看完整的接入文档在https://taotoken.net/doc有详细说明。配置改完后执行openclaw gateway restart然后在聊天框里用/model 模型ID切换验证新模型是否可用。6.2 电脑重启后如何恢复服务openclaw 的 gateway 不会自动开机启动每次电脑重启后需要手动拉起。最直接的方式是openclaw gateway start如果你希望它开机自启可以把这条命令写进 Windows 任务计划程序触发条件设为「登录时」。不过对大多数用户来说手动启动更可控也方便排查问题。如果访问http://127.0.0.1:18789/chat没显示聊天框先试openclaw gateway restart重启能解决大部分「昨天还好好的今天打不开」的情况。6.3 长期编码场景的配置建议如果你打算把 openclaw 当作日常编码的模型入口频繁切换模型、跑长对话建议关注 TaoToken 的 Coding Plan 方案。它在https://taotoken.net/coding-plan有说明适合需要稳定调用多个模型、对额度和响应速度有要求的场景。对于只是偶尔用用的用户按量付费的 API Key 就够了不用上套餐。先跑通再根据实际用量决定要不要升级。6.4 日常维护清单保持 gateway 稳定运行记住这几条定期用openclaw --version检查版本有新版本时npm install -g openclawlatest升级。升级后重启 gateway。配置文件改动后必须openclaw gateway restart否则改动不生效。如果长时间不用用openclaw gateway stop停掉服务释放端口和内存。遇到报错先看 gateway 窗口的输出那里有最原始的线索。浏览器上的错误提示往往是二次包装过的不如终端日志直接。需要快速验证模型是否可用时用https://taotoken.net/chat的模型对话功能测一下能排除是 gateway 问题还是模型端问题。装 openclaw 这件事难点不在命令本身而在环境准备和报错定位。把第 2 节的前置检查做扎实第 5 节的报错表存好后面就是复制粘贴的功夫。gateway 跑起来之后你会发现本地有一个统一的模型入口比在多个网页之间来回切换省事得多。