1. 为什么 Windows 装 OpenClaw 总在第一步卡住OpenClaw小龙虾是一个能真正动手执行任务的 AI 智能体可以读写本地文件、跑脚本、调浏览器、接各种大模型适合想把日常重复操作交给 AI 的 Windows 用户和开发者。但很多人第一次装它卡住的不是模型配置而是环境本身官方那条iwr -useb ... | iex一键脚本在 Windows 上经常直接报错退出。我实测下来报错基本集中在四类。第一类是 PowerShell 执行策略默认 Restricted 会直接拒绝运行远程脚本第二类是网络原因脚本下载超时或半途断流第三类是脚本自动探测 Node.js 环境失败明明装了却识别不到第四类是权限不足部分组件写入被拦。这四类问题互相叠加排查起来非常耗时间。更稳的思路是绕开一键脚本改用 npm 全局安装。步骤清晰、每一步都可控、出错能定位成功率也高得多。这篇就按「环境准备 → npm 安装 → TaoToken 统一 Key 接入 → PowerShell 验证连通」的顺序走一遍把 Node.js 版本、PowerShell 权限、路径空格这几个高频坑一次说清。你跟着做基本能一次装通。2. 装之前先把 TaoToken 的 Key 准备好OpenClaw 本身只是执行框架真正干活的是背后接的大模型。如果你要同时用多个模型比如日常对话用一款、写代码用另一款一个个去各平台申请 Key、分别填配置管理起来很乱。TaoToken 的作用就是把这些模型收敛到一个统一入口你只维护一个 KeyOpenClaw 里也只配一处。具体做法打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里生成 API Key。这个 Key 就是后面要填进 OpenClaw 配置里的那一串。接口地址统一用 https://taotoken.net/api 注意这个地址后面不要加任何查询参数直接填就行。注意Key 属于敏感凭证别贴到聊天记录、截图或公开仓库里。配置时写进本地配置文件即可泄露了就去控制台重置。如果你后面打算长期跑编码类任务或 Agent 工作流可以顺带看下 Coding Plan 页面按用量选更划算的方案只是先跑通验证的话用按量计费的 Key 就够了。生成 Key 的入口在控制台的 API Keys 页面接入细节可以对照接入文档两边配合着看不会迷路。3. 环境准备Node.js、npm 与 PowerShell 权限3.1 Node.js 版本必须 ≥ 22OpenClaw 对 Node.js 有硬性版本要求低于 22 会在安装时抛EBADENGINE报错。这是 90% 安装失败的根源先解决它。去 Node.js 官网下载 LTS 版本选 22.x 或更高Windows 64 位安装包。安装过程中务必勾选 “Add to PATH”否则命令行里找不到 node。装完开一个新的 PowerShell 窗口验证node -v # 期望输出 v22.x.x 或更高 npm -v # 期望输出 npm 版本号例如 10.x.x如果node -v显示的还是旧版本说明系统里存在多个 Node。可以用 nvm for Windows 管理多版本切换后再验证一次。这里有个容易忽略的点装完 Node 一定要重开 PowerShell旧窗口的环境变量不会自动刷新。3.2 处理 PowerShell 执行策略与权限npm 全局安装本身不依赖脚本执行策略但 OpenClaw 后续有些钩子脚本会用到。为了避免中途被拦建议以管理员身份打开 PowerShell先看一眼当前策略Get-ExecutionPolicy如果返回Restricted改成对当前用户生效的RemoteSignedSet-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是本地脚本可跑、远程脚本需签名比直接设Unrestricted安全。改完可以用Get-ExecutionPolicy -Scope CurrentUser确认。3.3 路径空格这个隐形坑Windows 用户名里带空格比如C:\Users\Zhang San时npm 全局目录也会带空格某些脚本拼接路径时不加引号就会断掉表现为「命令找不到」或「模块加载失败」。先查一下全局路径npm prefix -g如果输出里含空格最省事的办法是改 npm 全局目录到一个无空格路径比如D:\npm-globalnpm config set prefix D:\npm-global然后把D:\npm-global加进系统环境变量 Path。改完重开 PowerShell再跑一次npm prefix -g确认。4. 用 npm 安装 OpenClaw 并接入统一 Key4.1 全局安装以管理员身份打开 PowerShell执行npm i -g openclaw装完验证命令是否可用openclaw --version如果提示openclaw: command not found说明 npm 全局 bin 目录不在 PATH 里。回到 3.3 查到的npm prefix -g路径把它加进系统变量 Path保存后重启 PowerShell 再试。4.2 初始化配置向导openclaw onboard向导里依次会问是否本机本人使用选 yes、快速安装还是手动配置选 QuickStart、接哪个大模型、填 API Key、聊天载体、插件。这里的关键一步是模型和 Key模型按需选Key 填你在 TaoToken 控制台生成的那一串接口地址填https://taotoken.net/api。聊天载体建议先选 tui终端交互方便快速测试Skills 先跳过后续按需加。4.3 settings.json / config.toml 骨架向导跑完后配置会落到本地文件。如果你想手动核对或补写可以参考下面两个骨架。JSON 版settings.json{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: 你的模型名 }, gateway: { host: 127.0.0.1, port: 18789 }, controlUi: { dangerouslyAllowHostHeaderOriginFallback: true, dangerouslyDisableDeviceAuth: true, allowInsecureAuth: true } }TOML 版config.toml[model] provider openai-compatible base_url https://taotoken.net/api api_key 你的_TaoToken_Key model 你的模型名 [gateway] host 127.0.0.1 port 18789 [control_ui] dangerously_allow_host_header_origin_fallback true dangerously_disable_device_auth true allow_insecure_auth true注意controlUi里那几项是为了本地调试时避免网关因 Host 校验或设备鉴权打不开仅限本机127.0.0.1场景使用。别把网关暴露到公网否则等于把执行权限开放出去。4.4 网关配置与启动如果 ws 网关打不开重新跑一次配置openclaw config依次选 local、Gateway、端口默认、lan、密码登录、关闭 off、设置密码、configure。然后按 4.3 补上controlUi那几行重启网关openclaw gateway start openclaw gateway status状态正常后浏览器打开控制台http://127.0.0.1:18789/就能看到界面。5. 用 PowerShell 验证连通性与常见报错排查5.1 验证请求是否打通网关起来后先用 PowerShell 直接打一次接口确认 Key 和地址没问题$headers { Authorization Bearer 你的_TaoToken_Key Content-Type application/json } $body { model 你的模型名 messages ({ role user; content ping }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/v1/chat/completions -Method Post -Headers $headers -Body $body返回里带choices字段就说明链路通了。如果报 401是 Key 不对或没带Bearer报 404检查地址是不是写成了带多余路径的形式超时则先确认本机网络能正常访问该域名。再验证本地网关Invoke-RestMethod -Uri http://127.0.0.1:18789/health -Method Get5.2 常见报错对照表报错现象大概率原因处理方式EBADENGINENode.js 版本低于 22升级到 22.x 或更高重开终端openclaw: command not foundnpm 全局 bin 不在 PATH把npm prefix -g路径加进 Path模块加载失败 / 路径截断用户名或全局路径含空格改 npm prefix 到无空格目录脚本被拒绝执行执行策略为 Restricted设为RemoteSigned当前用户网关页面打不开Host 校验或设备鉴权拦截补controlUi三项后重启接口 401Key 错误或格式不对核对 Key确认带Bearer接口超时网络或地址写错确认地址为https://taotoken.net/api5.3 诊断与日志遇到说不清的问题先跑诊断openclaw doctor它会自动检查常见配置问题并尝试修复。要看实时日志openclaw logs --follow日志里通常会直接指出是模型调用失败、网关端口占用还是配置字段缺失比盲猜快得多。常用命令再列一遍备用openclaw gateway start # 启动网关 openclaw gateway status # 查看状态 openclaw dashboard # 打开控制面板6. 装通之后把 Key 和排障入口固定下来整套流程走下来真正卡人的其实就三处Node.js 版本、PATH 里的全局路径、以及网关的 Host 校验。把这三处一次性配好后面基本不会再返工。我的习惯是把npm prefix -g的输出和 TaoToken 的 Key 管理页都存进浏览器书签出问题时先跑openclaw doctor再对着日志定位很少需要重装。如果你还在接入阶段反复报错直接去 API Keys 页面重新生成一个 Key并对照接入文档核对地址和请求格式多数 401/404 都能当场解决。想先确认模型本身能不能正常回话用模型对话页面发一条测试消息最快。打算长期跑编码或 Agent 任务的话Coding Plan 里按用量选方案会比按量计费更省心。把 Key 管好、把网关锁在本地这只小龙虾就能安稳地替你干活了。
