1. 为什么 Windows 跑 OpenClaw 总在第一步卡住OpenClaw 是一个可以本地部署、通过对话驱动任务执行的智能体框架能接大模型、跑工具链、开浏览器 UI适合想把 Agent 能力落到自己机器上的开发者。但它在 Windows 上的安装部署和纯 Linux 环境完全是两条路。官方文档默认你熟悉 shell、会用包管理器、路径权限不敏感而 Windows 用户一上来就会撞上三堵墙PowerShell 执行策略拦截脚本、npm 全局路径没进 PATH、以及 Windows 原生文件系统对符号链接和权限的处理和 Linux 不一致。我见过太多人卡在iex : 无法加载文件 npm.ps1因为在此系统上禁止运行脚本这一行就放弃了。其实这不是 OpenClaw 的问题是 PowerShell 默认的 ExecutionPolicy 在保护你。另一批人装完了 CLI敲openclaw却提示「不是内部或外部命令」于是以为装失败了实际只是 npm 全局 bin 目录没写进系统 PATH。所以这篇 Windows 安装部署指南主线走官方最推荐的 WSL2 Node.js 路线同时把 PowerShell 原生安装作为备选方案讲清楚。目标很明确从零开始环境准备、依赖安装、配置校验、启动验证每一步都给可复制的命令和预期输出让你一次跑通而不是在报错里反复试错。适合谁看手上是 Windows 10/11、想本地跑 OpenClaw 做 Agent 实验、对 Linux 命令不算熟但愿意照着敲的开发者。全程不需要你提前装 Node也不需要你懂 WSL 底层原理跟着命令走就行。先说结论如果你只是想在 Windows 上快速看到 OpenClaw 跑起来WSL2 是首选因为它绕开了 Windows 原生路径和权限的绝大多数坑如果你已经有干净的 Node 22 环境、又不想开 WSL那 PowerShell 脚本安装也能用但要额外处理执行策略和 PATH 两个问题。下面按这个思路展开。2. WSL2 环境准备与 Node.js 安装openclaw windows 安装部署 前置依赖这一章是整篇的地基。WSL2 装不好后面 OpenClaw 一定跑不起来。我按「启用功能 → 装发行版 → 配 Node.js」三步走每步都给验证命令。2.1 启用 WSL2 并安装 Ubuntu以管理员身份打开 PowerShell右键开始菜单 → 终端(管理员)执行wsl --install这条命令会自动启用「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两个 Windows 功能下载 WSL2 内核并默认安装 Ubuntu。执行完需要重启电脑。重启后 Ubuntu 会首次启动要求你设置 Linux 用户名和密码这个密码后面sudo会用到记牢。如果你机器上已经装过 WSL 但是 1 代手动切到 2 代wsl --set-default-version 2 wsl --list --verbose--list --verbose会列出所有发行版和它们的 WSL 版本确认 VERSION 列是 2。如果显示 1用wsl --set-version Ubuntu 2转换。验证 WSL2 是否正常进 Ubuntu 后敲uname -r看到类似5.15.x-microsoft-standard-WSL2的内核版本就对了。如果内核版本里没有WSL2字样说明还在 1 代。2.2 在 WSL2 里装 Node.js 22OpenClaw 要求 Node.js 22 及以上。WSL2 的 Ubuntu 自带 Node 版本往往太老别用apt install nodejs那个版本通常停在 18 甚至更低。推荐用 NodeSource 官方源装 22.xcurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node -v npm -v预期输出v22.x.x和对应的 npm 版本。如果node -v还是老版本说明 PATH 里有旧的 node用which node看路径把/usr/bin/node优先。这里有个 WSL2 特有的坑Windows 侧的 Node 和 WSL2 侧的 Node 是两套独立环境。你在 PowerShell 里node -v是 22不代表 WSL2 里也是。OpenClaw 装在 WSL2 里就必须在 WSL2 里验证 Node 版本别混着看。2.3 配置 npm 镜像加速可选但强烈建议国内直连 npm 官方源装 OpenClaw 会慢到怀疑人生。在 WSL2 里设置镜像npm config set registry https://registry.npmmirror.com npm config get registry第二条命令确认输出是https://registry.npmmirror.com/。这一步能把你后面npm install -g openclaw的时间从十几分钟压到一两分钟。到这里WSL2 Node.js 的前置环境就齐了。你可以把这一章理解成「给 OpenClaw 铺好地基」接下来才是真正装 OpenClaw 本体。3. OpenClaw 安装与配置片段可复制的 settings 与启动参数环境好了开始装 OpenClaw。WSL2 里就是标准 Linux 安装流程一条命令搞定 CLInpm install -g openclawlatest装完先别急着跑向导验证 CLI 是否可用openclaw --version能打印版本号说明全局安装成功。如果提示command not found八成是 npm 全局 bin 没进 PATH。在 WSL2 里查npm prefix -g输出通常是/usr/local或/home/你的用户名/.npm-global。确认$(npm prefix -g)/bin在 PATH 里没有就加到~/.bashrcecho export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrc3.1 初始化配置与模型接入OpenClaw 的配置核心是模型接入。它支持多种模型来源这里我用 TaoToken 作为统一接入层好处是一个 Key 能调多家模型Base URL 和 Key 管理集中不用在 OpenClaw 里为每个模型单独配。先拿 Key打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_wsl2utm_campaignrewrite 登录后创建一个 API Key复制保存。这个 Key 就是后面配置里的凭证。OpenClaw 的配置文件默认在~/.openclaw/config.jsonWSL2 路径。你可以手动创建也可以用向导生成。手动配置的 JSON 片段如下路径和字段名按 OpenClaw 实际结构来{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-sonnet-4-5 } }, gateway: { port: 18789, host: 127.0.0.1 }, daemon: { enabled: true } }三个关键字段必须对齐Base URL 填https://taotoken.net/api注意不带 UTMapiKey 填你刚复制的 KeymodelId 填你要用的模型 ID。这三件套Base URL Key Model ID是任何 OpenAI 兼容接入的通用公式OpenClaw、Cline、Codex 都一样。如果你更习惯用向导跑openclaw onboard --install-daemon向导会依次问安装路径、是否装守护进程、模型参数。模型那一步选 OpenAI 兼容Base URL 和 Key 按上面填。守护进程建议选是这样 OpenClaw 能后台常驻不用每次手动起。3.2 环境变量与状态目录OpenClaw 支持用环境变量覆盖默认路径WSL2 里临时设置export OPENCLAW_HOME$HOME/.openclaw export OPENCLAW_STATE_DIR$HOME/.openclaw/state export OPENCLAW_CONFIG_PATH$HOME/.openclaw/config.json想永久生效就写进~/.bashrc。这几个变量在多实例或想隔离数据时特别有用比如你想同时跑两个不同配置的 OpenClaw给它们不同的OPENCLAW_HOME就行。配置写完下一步是验证它到底通不通。4. 启动验证与接口连通性测试openclaw doctor 与 status 实测配置对不对不靠猜靠命令验证。OpenClaw 自带几个诊断命令按顺序跑一遍。4.1 配置体检openclaw doctor这个命令会检查配置文件语法、模型连通性、守护进程状态。预期输出里每一项都是 OK 或绿色通过。如果模型那项报错多半是 Base URL 或 Key 填错回到config.json核对三件套。4.2 网关状态openclaw status输出会显示网关是否在监听、端口是多少、守护进程是否运行。正常情况你能看到gateway: running on 127.0.0.1:18789。如果显示 stopped手动起openclaw gateway start4.3 接口连通性测试最直接的验证是发一个真实请求。用 curl 打 TaoToken 的接口确认 Key 和网络都通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK 两个字母}] }预期返回 JSON 里choices[0].message.content是OK。这一步通了说明从 WSL2 到 TaoToken 的网络、鉴权、模型路由全链路没问题。如果这里就报 401是 Key 问题报连接超时是网络问题报 model not found是 modelId 写错。4.4 打开浏览器 UIopenclaw dashboard它会启动本地 Web UI 并打印访问地址通常是http://127.0.0.1:18789。WSL2 的 localhost 转发到 Windows 是自动的直接在 Windows 浏览器里打开这个地址就能看到 OpenClaw 界面。在对话框里发一条消息能收到模型回复整个部署就算真正跑通了。想验证模型对话效果也可以直接开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_wsl2utm_campaignrewrite 在线试确认同一个 Key 在网页端也能用排除是 OpenClaw 配置问题还是 Key 本身问题。5. 常见报错逐项排查401、local proxy failed、reading choices、OAuth这一章按真实报错来每条给现象、原因、解决。报错一401 Unauthorized现象curl 或 OpenClaw 请求返回 401。原因九成是 Key 错、Key 过期、或 Authorization 头格式不对。检查config.json里 apiKey 是不是完整复制别漏字符、别带空格curl 里Bearer后面有没有空格。TaoToken 的 Key 以sk-开头确认没被截断。报错二local proxy failed / connection refused现象OpenClaw 启动时报本地代理连接失败。这通常是网关端口被占或守护进程没起。查端口占用ss -tlnp | grep 18789有别的进程占着就改config.json里的gateway.port或者杀掉占用进程。守护进程没起就openclaw gateway start。报错三reading choices 相关错误现象请求返回了但解析失败报cannot read property choices of undefined之类。原因是返回体不是标准 OpenAI 格式或者模型 ID 不被支持。先确认 modelId 拼写正确再用第 4.3 的 curl 单独测看原始返回长什么样。如果返回里没有choices字段说明模型路由有问题换一个确认可用的 modelId 再试。报错四OAuth 认证失败现象向导里选 OAuth 登录模型时卡住或报错。OAuth 依赖浏览器回调WSL2 里浏览器回调地址可能不通。解决办法是改用 API Key 方式接入也就是本文第 3 章的配置法绕开 OAuth 回调。TaoToken 的 Key 方式就是为这种场景准备的稳定且不依赖浏览器跳转。报错五openclaw 不是内部或外部命令这是 Windows 原生安装的典型问题WSL2 里少见。如果你在 PowerShell 里装 OpenClaw 遇到说明 npm 全局 bin 没进 PATH。npm prefix -g拿到路径加进系统环境变量 Path重开终端。这也是我推荐 WSL2 的原因之一Linux 侧 PATH 处理更直观。排查顺序建议先 curl 测 Key 和网络再openclaw doctor测配置最后openclaw status测服务。从外到内一层层缩小范围比盲目改配置高效得多。6. 长期跑 Agent 的接入选择与 Coding PlanOpenClaw 跑起来只是开始真正用起来是让它长期执行编码、Agent 任务。这时候模型调用量和稳定性就成了关键。如果你只是偶尔试几个 prompt按量付费的 Key 就够但如果你打算让 OpenClaw 常驻、频繁跑 Agent 循环那按量计费很容易失控尤其是长上下文模型一晚上跑几十块不夸张。这种场景更适合用 Coding Plan 这类包月方案把成本固定下来。TaoToken 的 Coding Plan 就是为长期编码和 Agent 场景设计的接入方式和你现在配的完全一样还是那三件套Base URL 填https://taotoken.net/apiKey 换成 Plan 对应的Model ID 按需选。配置片段不用大改只换 Key 和 modelId 即可。具体开通和接入细节看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_wsl2utm_campaignrewrite 里面有 Plan 的模型覆盖和额度说明。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_wsl2utm_campaignrewrite 遇到字段不确定就翻文档比在群里问快。最后给一个实操建议WSL2 里的 OpenClaw 配置改完后养成先openclaw doctor再openclaw status的习惯两个命令十秒钟能挡掉八成低级错误。守护进程开着机器重启后 OpenClaw 自动恢复不用每次手动起。这样你的 Windows 机器就真正变成了一个随时可用的 Agent 工作站。