1. Windows 下 OpenClaw 2026.x 部署到底难在哪OpenClaw 2026.x 是一个跑在本地、通过浏览器交互的 Agent 网关程序它把模型调用、工具执行、浏览器控制拆成几个独立进程再用一个 Gateway 统一收口。适合谁适合想在 Windows 主力机上做本地 Agent 实验、又不想把整台机器重装成 Linux 的开发者。它的核心检索词就是 OpenClaw 2026.x Windows WSL2 部署而这条链路最容易卡住的地方恰恰不是 OpenClaw 本身而是 Windows 与 Linux 之间的那层边界。我见过太多人卡在三个位置第一Node.js 版本不对OpenClaw 2026.x 要求 Node 18 以上推荐 20 或 22用系统自带的旧版本会在pnpm install阶段报原生模块编译失败第二WSL2 没设成默认版本装完 Ubuntu 发现还是 WSL1网络回环和端口转发行为完全不同Gateway 起来了浏览器却连不上第三认证文件写错位置把 API Key 塞进openclaw.json而不是auth-profiles.json启动日志里只会给你一句ignored invalid auth profile entries不告诉你错在哪。这篇就按真实操作顺序走一遍先在 Windows 侧把 WSL2 和 Ubuntu 装好再进 Ubuntu 装 Node.js 和依赖然后拉源码、首次启动、配置认证、验证请求最后把常见报错逐条对照。全程命令可复制路径与 2026.x 的 schema 保持一致。你不需要提前理解 Gateway、Agent、Profile 这些概念跟着敲完浏览器里能收到模型回复就说明整条链路通了。需要说明的是本文所有模型调用都通过合规的 API 网关完成不涉及任何网络加速工具。你只需要一个可用的 API Key 和一个能访问的 Base URL后面配置章节会给出具体写法。2. WSL2 与 Ubuntu 环境准备从 PowerShell 到首次登录这一节的目标是把 Windows 主机变成「Windows Ubuntu 双环境」并且确保 Ubuntu 跑在 WSL2 上。整个过程在 PowerShell 里完成不需要手动下载镜像。先确认系统版本。按Win R输入winver弹窗里看版本号。Windows 10 需要 21H2 及以上Windows 11 任意版本都可以。低于这个版本wsl --install这条命令可能不存在得先更新系统。确认没问题后以管理员身份打开 PowerShell。注意是管理员模式普通模式装 WSL 会提示权限不足。执行wsl --install这条命令会自动启用「虚拟机平台」和「适用于 Linux 的 Windows 子系统」两个 Windows 功能然后下载并安装默认的 Ubuntu 发行版。执行完必须重启电脑别跳过功能启用需要重启才生效。重启后如果 Ubuntu 没有自动装上手动指定版本wsl --set-default-version 2 wsl --install -d Ubuntu-22.04第一行把默认 WSL 版本锁成 2这一步很关键。很多人装完发现是 WSL1原因是系统默认版本还是 1。WSL1 和 WSL2 在网络模型上差异很大WSL2 有独立的虚拟网卡端口转发规则不一样OpenClaw 的 Gateway 监听127.0.0.1时浏览器能不能访问取决于这个版本设置。装完后用下面这条确认wsl -l -v输出里VERSION那一列应该是2。如果是1执行wsl --set-version Ubuntu-22.04 2转换转换过程会花几分钟。首次启动 Ubuntu可以直接在开始菜单点 Ubuntu 图标或者在 PowerShell 里输入wsl。第一次进入会让你设置用户名和密码。用户名用小写字母别用中文和空格密码输入时不显示字符正常现象输完回车即可。这个账号是普通用户后面所有sudo操作都用它。进入 Ubuntu 后先更新软件源sudo apt update sudo apt upgrade -yapt update刷新包索引apt upgrade升级已安装的包。第一次跑可能要几分钟取决于镜像源速度。如果卡在下载可以换成国内镜像源但这一步不是必须的先跑通再说。到这里Windows 侧的环境就绪了。你可以把 Ubuntu 终端当成一台独立的 Linux 机器来用文件系统在\\wsl$\Ubuntu-22.04\home\你的用户名下Windows 资源管理器能直接访问。但注意OpenClaw 的源码和配置都放在 Ubuntu 的 home 目录里不要放在/mnt/c/下跨文件系统读写会拖慢pnpm install的速度也容易出权限问题。3. Node.js 与 OpenClaw 依赖安装可复制的配置片段Ubuntu 就绪后先装 Node.js。OpenClaw 2026.x 要求 Node 18 以上推荐 20 或 22。Ubuntu 22.04 自带的 Node 版本偏旧直接用 NodeSource 的源装 22.xcurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs装完验证node -v npm -v应该输出v22.x.x和对应的 npm 版本。如果node -v还是旧版本说明 PATH 里有其他 Node用which node看一下路径正常应该是/usr/bin/node。接着装 Git 和 pnpm。pnpm 是 OpenClaw 用的包管理器比 npm 快且省磁盘sudo apt install -y git sudo npm install -g pnpm git --version pnpm -v然后拉源码。进 home 目录克隆仓库cd ~ git clone https://github.com/openclaw/openclaw.git openclaw-src cd openclaw-src pnpm installpnpm install会下载所有依赖第一次跑时间较长。如果中途报原生模块编译错误八成是 Node 版本不对回到上面确认node -v。依赖装完后先别急着配 API Key直接首次启动让 OpenClaw 生成默认配置文件node openclaw.mjs gateway --allow-unconfigured--allow-unconfigured表示允许在未配置认证的情况下启动方便你先看到 Gateway 是否正常监听。成功的话终端会打印类似[gateway] listening on ws://127.0.0.1:18789 [browser/server] Browser control listening on http://127.0.0.1:18791看到这两行说明 Gateway 进程和浏览器控制服务都起来了。此时按Ctrl C停掉因为接下来要写配置文件。配置文件在~/.openclaw/下。首次启动后这个目录会自动生成里面有openclaw.json。认证信息单独放在~/.openclaw/agents/main/agent/auth-profiles.json这是 2026.x 的 schema 要求别写错位置。先建目录mkdir -p ~/.openclaw/agents/main/agent然后写入认证文件。这里用 TaoToken 的 API 作为模型入口Base URL 填https://taotoken.net/apiKey 换成你自己的{ profiles: { default: { providers: { openai: { key: sk-你的TaoToken密钥, baseURL: https://taotoken.net/api } } } }, activeProfile: default }保存到~/.openclaw/agents/main/agent/auth-profiles.json。写完后用 Python 校验 JSON 格式python3 -m json.tool ~/.openclaw/agents/main/agent/auth-profiles.json能正常打印说明格式没问题。如果报JSON5 parse failed就是括号或逗号写错了重新检查。接着设置默认模型和并发。模型先用一个轻量的测试并发降到 1 防止限流python3 - PY import json, pathlib p pathlib.Path.home().joinpath(.openclaw/openclaw.json) cfg json.loads(p.read_text()) d cfg.setdefault(agents, {}).setdefault(defaults, {}) d[model] openai/gpt-4o-mini d[maxConcurrent] 1 d.setdefault(subagents, {})[maxConcurrent] 1 p.write_text(json.dumps(cfg, indent2)) print(Model and concurrency updated) PY这段脚本做了三件事把默认模型设为openai/gpt-4o-mini把主 Agent 并发设为 1把子 Agent 并发也设为 1。并发设 1 是为了避免刚接入就被限流跑通后再按需调高。到这里配置三件套就齐了Base URL 是https://taotoken.net/apiKey 在auth-profiles.json里Model ID 是openai/gpt-4o-mini。这三个值后面验证请求时会用到。4. 启动 Gateway 并验证端到端请求配置写完后重新启动 Gatewaycd ~/openclaw-src node openclaw.mjs gateway --allow-unconfigured这次启动会读取auth-profiles.json如果格式正确日志里不会再出现ignored invalid auth profile entries。Gateway 监听ws://127.0.0.1:18789浏览器控制服务监听http://127.0.0.1:18791。先拿 Gateway Token。这个 Token 是浏览器连接 Gateway 用的和 API Key 是两回事。用 Python 读出来python3 - PY import json, pathlib cfg json.loads(pathlib.Path.home().joinpath(.openclaw/openclaw.json).read_text()) print(cfg[gateway][auth][token]) PY打印出来的字符串就是 Gateway Token。然后在 Windows 的浏览器里访问http://localhost:18791/?token刚才打印的token注意localhost在 WSL2 下能直接映射到 Windows 浏览器这是 WSL2 的特性不需要额外配置端口转发。如果打不开先确认 Gateway 进程还在跑再确认 WSL2 版本是 2。进入 Dashboard 后找到 Chat 输入框输入hello。如果配置正确几秒内会返回模型回复。这一步就是端到端验证浏览器 → Gateway18789→ Agent → auth-profiles.json 里的 Base URL → 模型返回。如果返回的是错误而不是回复看终端日志。常见的有No API key found说明auth-profiles.json结构不对必须是profiles.default.providers.openai.key这个层级。还有API rate limit reached说明并发还是太高或者额度用尽把maxConcurrent保持 1换个轻量模型再试。验证通过后可以把启动命令固化下来。在~/openclaw-src下建一个启动脚本cat start.sh EOF #!/bin/bash cd ~/openclaw-src node openclaw.mjs gateway --allow-unconfigured EOF chmod x start.sh以后每次启动就./start.sh。注意这里没有把 API Key 写进环境变量因为 2026.x 推荐用auth-profiles.json管理认证环境变量方式在新版本里优先级较低容易和配置文件冲突。如果你想在浏览器里直接测试模型对话也可以访问 TaoToken 的模型对话页面用同一个 Key 验证额度是否正常https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat 。这一步是可选的自检确认 Key 本身可用排除是 OpenClaw 配置问题还是 Key 问题。5. 常见报错逐条排查401、JSON5、token missing这一节把实际部署中最容易撞上的报错列出来每条给出触发原因和修复动作。你遇到问题时直接对照。报错一401 Unauthorized或invalid api key触发在 Chat 发消息后终端日志显示模型调用被拒。原因通常是 Key 写错、Key 过期或者 Base URL 没配对。检查auth-profiles.json里的key和baseURL两个字段确认 Key 没有多余空格Base URL 是https://taotoken.net/api。改完必须重启 Gateway配置不会热加载。报错二JSON5 parse failed启动时直接崩提示解析失败。原因是手动编辑openclaw.json时破坏了 JSON 格式比如多了逗号、少了引号。最省事的修复是删掉配置目录重新生成rm -rf ~/.openclaw node openclaw.mjs gateway --allow-unconfigured这会重置所有配置包括认证文件所以重置后要重新写auth-profiles.json。建议改配置前先备份。报错三gateway token missing浏览器打开 Dashboard 后提示缺 Token。原因是访问 URL 没带?tokenxxx参数。Gateway 默认要求 Token 认证直接访问http://localhost:18791会被拒。用第 4 节的 Python 命令重新打印 Token拼到 URL 后面。报错四ignored invalid auth profile entries启动日志里出现这行说明auth-profiles.json的结构不符合 2026.x schema。必须是profiles.default.providers.openai.key这个嵌套层级少一层或者字段名拼错都会被忽略。用python3 -m json.tool校验格式再对照第 3 节的 JSON 片段逐字段核对。报错五local proxy failed或连接超时模型调用时提示本地代理失败。检查 Base URL 是否可达在 Ubuntu 里执行curl -I https://taotoken.net/api能返回 HTTP 头说明网络通。如果超时检查 WSL2 的 DNS 配置/etc/resolv.conf里的 nameserver 是否正常。WSL2 偶尔会有 DNS 解析问题重启 WSL 可以解决在 PowerShell 里wsl --shutdown再重新进入。报错六reading choices相关错误日志里出现reading choices或类似字段读取失败通常是模型返回结构异常根源还是认证或 Base URL 问题。先确认 Key 有效再确认模型 ID 写的是openai/gpt-4o-mini这种带 provider 前缀的格式。模型 ID 不带前缀OpenClaw 可能路由不到正确的 provider。报错七OAuth相关提示如果日志里出现 OAuth 字样说明配置里混入了 OAuth 认证方式。2026.x 的auth-profiles.json用 API Key 方式即可不需要 OAuth。检查文件里有没有多余的oauth字段删掉。排查顺序建议固定先看终端日志的第一条错误再对照本节。大部分问题集中在认证文件结构和 Base URL 两处把这两处确认对剩下的基本是并发和模型 ID 的小问题。6. 长期跑 OpenClaw 的接入建议与 CTA跑通一次之后接下来要考虑的是怎么稳定用下去。几个实操建议。第一把启动脚本和配置分离。start.sh只负责启动认证信息留在auth-profiles.json模型和并发留在openclaw.json。这样换 Key 不用动启动命令调模型不用重写认证。第二并发不要一上来就拉满。maxConcurrent设 1 是保守值跑稳定后可以逐步调到 2 或 3观察有没有限流。子 Agent 的并发单独控制subagents.maxConcurrent和主 Agent 分开设避免子任务把额度吃光。第三模型选择上日常测试用轻量模型复杂任务再切到能力更强的。OpenClaw 支持在openclaw.json里改默认模型也可以按 Agent 单独指定。切换模型不需要改认证文件只改模型 ID 即可。第四WSL2 的资源限制。默认 WSL2 会占用较多内存可以在 Windows 用户目录下建.wslconfig限制[wsl2] memory8GB processors4改完wsl --shutdown重启生效。OpenClaw 跑起来后内存占用主要来自 Node 进程和浏览器控制服务8GB 一般够用。如果你打算把 OpenClaw 接到自己的编码工作流里比如让它调用工具、跑长任务可以了解 Coding Plan 的接入方式它更适合长期编码和 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan 。API Key 的管理在控制台里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 需要新建或轮换 Key 时在这里操作。完整的接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 里面有各语言的调用示例和参数说明。最后提醒一个容易忽略的点OpenClaw 的 Gateway Token 和 API Key 是两套认证前者管浏览器连 Gateway后者管 Gateway 调模型。排障时先分清是哪一层出问题再看对应日志。把这两层认证理清楚OpenClaw 在 Windows WSL2 下的部署就算真正跑通了。