OpenClaw Windows 最详细安装指南：从环境准备到 TaoToken 通道配置

1. 为什么 Windows 上装 OpenClaw 总卡在环境这一步

OpenClaw 是一个本地优先的开源 AI 智能体，它和普通聊天机器人的区别在于：能读写本地文件、执行命令行、操控浏览器、跑定时任务，还能通过飞书、钉钉、Telegram 这类通道接收指令。适合谁？适合想把 AI 从「网页对话框」搬进自己电脑、让它真正动手干活的开发者。而 Windows 首次部署 OpenClaw，最容易翻车的不是 OpenClaw 本身，而是环境：Node 版本不对、PATH 没配、PowerShell 执行策略拦截脚本、WSL2 没开虚拟化。这篇就把从环境检查到 TaoToken 通道配置的完整链路拆开，每一步都给可复制的命令。

先说清楚一个概念，OpenClaw 的运行结构分三层：最底下是 Node.js 运行时，中间是 Gateway（网关进程，负责调度和 RPC 通信），最上面是你接入的模型通道和消息通道。很多人装完openclaw命令却启动不了，本质是 Gateway 没跑起来，或者模型 endpoint 没配对。所以安装指南不能只写「装完就行」，得把「装完怎么验证通道真的通了」写进去。

我试过在一台 Windows 11、16GB 内存的机器上从零走一遍，全程大概 20 分钟，其中一半时间花在等 WSL2 和依赖下载。下面按顺序来，你可以边看边操作。核心检索词先记住：OpenClaw Windows 安装、Gateway 启动、auth.json 配置、TaoToken 通道。这几个词贯穿全文，遇到报错也围绕它们排查。

环境准备阶段有个原则：先验证，再安装。不要一上来就iwr | iex，先确认 Node、Git、pnpm 三个基础件版本达标，否则后面报错你根本分不清是 OpenClaw 的问题还是环境的问题。Node 必须 v22 及以上，这是硬门槛，v20 会在启动 Gateway 时报语法错误。Git 用于拉取技能和源码，pnpm 是官方推荐的包管理器，比 npm 快且对 monorepo 友好。

另外提醒一句，Windows 原生跑和 WSL2 里跑是两条路。原生胜在路径直观、和 Windows 文件系统无缝；WSL2 胜在 Linux 兼容性好，官方也更推荐。如果你只是想让 OpenClaw 管管本地文档、跑跑浏览器自动化，原生够用；如果要装大量依赖编译的技能，WSL2 更省心。本文两条路都给，你按需选。

2. 环境检查与 OpenClaw 安装前置：Node、Git、pnpm 三件套

这一节把「装之前必须确认的东西」一次性列清楚。打开 PowerShell（普通权限即可，安装 OpenClaw 那一步才需要管理员），逐条跑下面的命令。

先查 Node：

node --version npm --version

期望输出v22.x.x或更高。如果显示v20或命令找不到，去 Node 官网下 LTS 版，安装时务必勾选 Add to PATH，这是 90% 「openclaw 不是内部或外部命令」的根因。装完关掉当前 PowerShell 重开，PATH 才会刷新。

再查 Git：

git --version

没有的话去 git-scm.com 下 Windows 版，安装时默认编辑器选 VS Code 或你顺手的，其余保持默认即可。

装 pnpm：

npm install -g pnpm pnpm --version

pnpm 装完如果提示pnpm 无法加载文件，因为在此系统上禁止运行脚本，这是 PowerShell 执行策略问题，用管理员 PowerShell 跑一次：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

输入 Y 确认。这条只影响当前用户，安全可控。

接下来是可选的 WSL2。如果你决定走 WSL2 路线：

wsl --install

它会自动装 Ubuntu，重启后设置用户名密码。验证：

wsl -l -v

看到 Ubuntu 且 STATE 为 Running 就对了。如果报「虚拟化未启用」，重启进 BIOS 打开 Intel VT-x 或 AMD-V。这一步卡住的人不少，但和 OpenClaw 无关，是主板设置。

系统要求对照表，装之前扫一眼：

三件套齐了，再进安装。安装方式三选一：官方脚本最快，npm 全局最稳，源码编译适合要改代码的。官方脚本那条命令是：

iwr -useb https://openclaw.ai/install.ps1 | iex

跑之前建议临时关掉杀毒软件的实时防护，脚本下载二进制时容易被拦。npm 方式：

npm install -g openclaw@latest

源码方式：

git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build

装完统一验证：

openclaw --version

能打印版本号，说明命令已进 PATH。到这里只是「装上了」，还没「跑起来」，下一节进初始化。

3. 初始化 Gateway 与 TaoToken 通道配置（含 auth.json 片段）

装完 OpenClaw 后第一件事是跑初始化向导：

openclaw onboard --install-daemon

--install-daemon会把 Gateway 注册成后台服务，开机自启。向导会问你工作目录、默认模型等，一路回车用默认值也行，后面能改。

然后启动 Gateway：

openclaw gateway start openclaw status openclaw doctor

status期望看到 Gateway 状态 running，doctor期望看到 RPC probe ok。如果 status 显示 unknown，先openclaw gateway restart再查。

重点来了：把模型通道指到 TaoToken。OpenClaw 的模型配置在openclaw.json，认证信息在auth.json。Windows 下默认路径是：

C:\Users\<你的用户名>\.openclaw\openclaw.json C:\Users\<你的用户名>\.openclaw\auth.json

先配openclaw.json里的模型 endpoint。用编辑器打开，找到 models 段，加一个自定义 provider：

{ "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "api": "openai-completions", "models": [ { "id": "claude-sonnet-4-5", "name": "Claude Sonnet via TaoToken" } ] } } } }

再配auth.json，把 Key 写进去：

{ "taotoken": { "type": "api_key", "key": "sk-你的TaoToken密钥" } }

Key 从 TaoToken 控制台的 API Keys 页面拿，地址是 https://taotoken.net/api-keys 。注意baseUrl结尾不要带/v1，OpenClaw 会自己拼路径，多写一层会 404。

三件套对照，别漏：

改完配置重启 Gateway 让配置生效：

openclaw gateway restart openclaw model list

model list里能看到 taotoken 下的模型，说明配置被正确加载。如果看不到，检查 JSON 有没有多余逗号——JSON 不允许尾逗号，这是最常见的低级错误。

如果你用的是 Cline 或 Claude Code 这类外部工具接 OpenClaw 的 Gateway，配置逻辑一样：Base URL 填https://taotoken.net/api，Key 填 auth.json 里那把，Model ID 填上面配的 id。三者必须一致，缺一个就连不通。

4. 最小对话验证：确认 TaoToken 通道真的连通

配置写完不代表通了，得发一次真实请求。OpenClaw 自带 dashboard，先打开：

openclaw dashboard

浏览器访问http://127.0.0.1:18789/。在对话输入框里发一句最简单的：

你好，请回复"通道正常"四个字

如果几秒内返回内容，说明 Gateway → TaoToken → 模型这条链路全通。如果转圈或报错，看下一节排查。

命令行方式也能验证，适合脚本化：

openclaw chat --model taotoken/claude-sonnet-4-5 --message "ping"

期望返回一段模型输出。这里taotoken/claude-sonnet-4-5的写法是provider/modelId，provider 就是你在 openclaw.json 里定义的键名。

再补一个更贴近真实使用的验证：让它读一个本地文件。在 dashboard 里发：

读取 C:\Users\你的用户名\.openclaw\openclaw.json 并告诉我里面配了几个 provider

如果它能正确读出 provider 数量，说明工具调用（文件读取）也通了，不只是纯文本对话。这一步很关键，因为 OpenClaw 的价值就在「能动手」，纯聊天通不代表工具通。

验证通过后，建议把这次成功的配置备份一份：

copy C:\Users\你的用户名\.openclaw\openclaw.json C:\Users\你的用户名\.openclaw\openclaw.json.bak copy C:\Users\你的用户名\.openclaw\auth.json C:\Users\你的用户名\.openclaw\auth.json.bak

后面折腾技能或换模型搞崩了，直接还原这两个文件就行，比重装快得多。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错对照，遇到哪个查哪个。

401 Unauthorized：Key 错了或没生效。检查 auth.json 里 key 是否完整（sk- 开头那串别漏字符），确认没有多余空格。改完必须openclaw gateway restart，不重启配置不加载。还有一种情况是 Key 被禁用或额度耗尽，去 TaoToken 控制台确认状态。

local proxy failed / Connection error：网络层问题。先确认能访问https://taotoken.net/api，在 PowerShell 里跑：

curl https://taotoken.net/api

有响应说明网络通。如果企业内网有证书拦截，会报 SSL 错误，这时才考虑在 gateway 启动脚本里临时加set "NODE_TLS_REJECT_UNAUTHORIZED=0"，但这是降低安全性的做法，仅限内网调试，公网环境别用。

reading choices / Cannot read properties of undefined (reading 'choices')：这是响应结构不符合预期。常见原因是 baseUrl 多写了/v1，导致请求打到错误路径返回了非标准 JSON。把 baseUrl 改回https://taotoken.net/api即可。另一个原因是 Model ID 写错，模型不存在时返回体里没有 choices 字段。

OAuth 相关报错：如果你在配 Claude Code 或某些需要 OAuth 的工具，报 token 过期或 redirect 失败，说明走的是 OAuth 流程而非 API Key。OpenClaw 接 TaoToken 用 API Key 模式即可，不需要 OAuth，把认证类型改成api_key就绕开了。

Message ordering conflict：会话冲突，刷新 dashboard 或开新会话。Rate limit exceeded：等一会儿重试，或去控制台看额度。

openclaw 不是内部或外部命令：Node 没进 PATH。重装 Node 勾选 Add to PATH，或手动把 npm 全局目录加进环境变量，然后重开终端。

Web UI 打不开：先openclaw gateway status看网关活没活，没活就openclaw gateway restart。端口被占用的话，改 dashboard 端口或杀掉占用进程。

排查通用套路：openclaw logs --follow看实时日志，报错原文都在里面，比猜快得多。

6. 把通道跑通之后：技能安装与长期使用建议

通道验证通过后，OpenClaw 才算真正可用。接下来可以装技能扩展能力：

npx clawhub search <关键词> npx clawhub install <技能名> --dir C:\Users\你的用户名\.openclaw\workspace\skills

技能目录别写错，写错会装了但加载不到。装完openclaw gateway restart让技能生效。

如果你打算长期跑编码类、Agent 类任务，建议把模型通道固定下来，别频繁换。TaoToken 的 Coding Plan 适合这种持续调用的场景，地址是 https://taotoken.net/coding-plan ，比按次调用更省心。日常调试想快速验证某个模型，用模型对话页面就行：https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc ，配置细节对不上时以文档为准。

最后给个实用习惯：每次改完 openclaw.json 或 auth.json，先openclaw doctor再openclaw gateway restart，两步都过再发请求。这样能把「配置错误」和「运行时错误」分开，排查效率高很多。Windows 上装 OpenClaw 的坑基本都在环境和配置这两层，跑通一次之后，后面就是装技能、接通道的重复劳动了。