1. Windows 11 WSL2 Ubuntu 部署 Openclaw 到底卡在哪
Openclaw 是一个跑在本地、能接管终端与文件系统的 AI Agent 框架，适合想让模型直接操作命令行、读写工程目录、串联多步任务的开发者。它在 Windows 上的官方推荐路径就是 WSL2 + Ubuntu，因为纯 Windows 环境缺少完整的 Linux 进程与权限模型，很多 skill 会直接报错。但真正劝退新手的不是安装本身，而是装完之后模型接不进去：默认配置指向的是国际通道，国内直连经常超时，或者 Key 填错位置导致请求 401。
我自己在 Windows 11 上从零走了一遍，把 settings 里的 endpoint 和 Key 统一改到 TaoToken 通道，中间踩了几个典型坑，比如openclaw: command not found、gateway token 对不上、baseUrl 写成127.0.0.1结果 WSL2 里根本连不到宿主机。这篇就把完整流程拆开，每一步都给可复制命令，最后用一次真实对话请求验证连通。
先说清楚适用人群：你有一台 Windows 11 机器，想本地跑 Agent，不想折腾双系统，能接受命令行操作。整个过程大概 30 到 40 分钟，主要时间花在 WSL 内核更新和 Node 依赖安装上。核心检索词就是 Windows WSL2 Ubuntu 部署 Openclaw，下面所有步骤都围绕它展开。
需要提前确认两件事：一是 BIOS 里虚拟化（VT-x / AMD-V）已开启，二是 Windows 版本不低于 21H2。这两项不满足，后面wsl --install会直接失败。确认方式很简单，任务管理器 → 性能 → CPU，右下角能看到「虚拟化：已启用」。
2. TaoToken 前置准备与 Openclaw 模型通道选择
在动 WSL 之前，先把模型通道的事情定下来，否则装完 Openclaw 还要回头改配置，容易乱。Openclaw 的模型配置写在~/.openclaw/openclaw.json里，结构是models.providers下面挂不同 provider，每个 provider 有baseUrl、apiKey、api和models数组。默认模板给的是国际地址，国内网络下请求经常卡住或返回超时。
TaoToken 的作用就是提供一个统一的 OpenAI 兼容通道，把baseUrl指向它，apiKey换成你在控制台生成的 Key，就能在 Openclaw 里正常调用模型。它的接口地址是https://taotoken.net/api，兼容openai-completions协议，所以 Openclaw 里api字段保持openai-completions不用改。
你需要先去控制台创建一个 API Key。打开https://taotoken.net/console，登录后在 API Keys 页面新建一个，复制出来保存好，后面配置里要填。注意 Key 只显示一次，丢了就重新生成。如果你还没决定用哪个模型，可以先在模型对话页面试一下，确认通道能正常返回再写进配置。
这里有个关键点：Openclaw 的 provider 名字可以自定义，比如叫taotoken，但models数组里的id必须和通道支持的模型 ID 一致。比如你想用某个通用对话模型，就填对应的 ID。baseUrl要写成https://taotoken.net/api，注意结尾不要多加/v1，因为 Openclaw 内部会按openai-completions协议拼接路径，多写一层会导致 404。
另外提醒一句，不要把 Key 直接提交到 Git 仓库。Openclaw 的配置文件在用户目录下，一般不会进版本控制，但如果你手动备份到别处，注意脱敏。配置改完后建议chmod 600 ~/.openclaw/openclaw.json，避免其他用户读到。
如果你后续要长期跑编码类 Agent 任务，可以了解下 Coding Plan，它针对高频调用场景做了额度优化，比按量计费更适合天天用的开发者。这个不是必须的，先跑通基础配置再说。
3. WSL2 安装 Ubuntu 与 Openclaw 可复制配置
这一节是全文技术核心，命令都可以直接复制。先以管理员身份打开 PowerShell，执行 WSL 功能启用：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启电脑。重启后继续在 PowerShell 里设置默认版本并安装 Ubuntu：
wsl --set-default-version 2 wsl --install -d Ubuntu-24.04如果wsl --install报「无法解析服务器的名称或地址」，先执行wsl --update --web-download强制拉取内核更新。如果wsl --update卡在 0%，依次执行：
net stop wuauserv net start wuauserv wsl --update安装完 Ubuntu 首次启动会提示设置用户名和密码，输入密码时屏幕不显示任何字符，直接输完回车即可。如果报WslRegisterDistribution failed with error: 0x8007019e，说明 WSL 功能没启用，回到上面第一条命令重新执行并重启。
进入 Ubuntu 终端后，先更新系统并装基础工具：
sudo apt update && sudo apt upgrade -y sudo apt install -y curl git wget build-essential接着装 Node.js 22+，Openclaw 要求 Node 版本不低于 22：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v确认node -v输出 v22 以上。然后一键安装 Openclaw：
curl -fsSL https://openclaw.ai/install.sh | bash安装过程会进入 Onboarding，模型配置那一步先选Skip for now，因为我们要手动改到 TaoToken。Default model 随便选一个占位，channel 也 Skip。装完后如果提示openclaw: command not found，执行：
mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc现在改配置文件。先备份：
cd ~/.openclaw mv openclaw.json openclaw.json.bak nano openclaw.json把models.providers部分替换成下面这段，注意把apiKey换成你自己的 Key，workspace里的用户名换成你 Ubuntu 的用户名：
{ "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "api": "openai-completions", "models": [ { "id": "gpt-4o-mini", "name": "TaoToken Chat", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0 }, "contextWindow": 128000, "maxTokens": 4096 } ] } } } }同时把agents.defaults.model.primary改成taotoken/gpt-4o-mini，和上面 provider 名加模型 id 对应。gateway.auth.token保持安装时生成的那串，不要动。保存退出后执行chmod 600 ~/.openclaw/openclaw.json。
启动 gateway：
openclaw gateway start浏览器打开http://127.0.0.1:18789/#token=你的token，能看到面板就说明服务起来了。
4. 验证请求：一次对话确认 TaoToken 通道连通
配置改完必须验证，否则你可能以为通了，实际请求还在走旧地址。最直接的方式是在 Openclaw 里发一条对话。打开 gateway 面板，找到对话入口，输入「用一句话说明你现在用的是哪个模型通道」，发送。
如果返回正常文本，说明baseUrl和 Key 都生效了。如果返回 401，说明 Key 填错或没生效；如果返回超时，说明baseUrl写错或网络不通。也可以直接在 Ubuntu 终端用 curl 验证通道本身：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'返回 JSON 里choices[0].message.content有内容，就证明通道和 Key 都没问题。这一步能快速区分是 Openclaw 配置问题还是通道问题。如果 curl 通了但 Openclaw 不通，那就是openclaw.json里 provider 名或模型 id 对不上。
验证通过后，回到 Openclaw 面板再发一条稍微复杂的指令，比如「列出当前工作目录下的文件」，确认 Agent 能正常调用工具。这一步能验证 gateway 和 workspace 权限是否正常。如果报权限错误，检查workspace路径是否存在，以及当前用户是否有读写权限。
实测下来，从改配置到验证通过大概 5 分钟。关键是别跳过 curl 这一步，它能帮你快速定位问题层。很多人直接改完配置就发对话，报错了不知道是 Key 问题还是配置结构问题，来回折腾很久。
5. 本篇常见报错排查：401、local proxy failed、reading choices
部署过程中最容易遇到这几类报错，逐个说清楚。
401 Unauthorized：Key 错误或没带上。检查openclaw.json里apiKey是否完整复制，有没有多余空格。TaoToken 的 Key 以sk-开头，复制时注意别漏字符。如果 Key 确认没错，检查baseUrl是否是https://taotoken.net/api，多写/v1会导致路径拼接错误，有些情况下会返回 401 而不是 404。
local proxy failed / connection refused：通常是 gateway 没启动，或者端口被占用。执行openclaw gateway status看状态，如果没跑就openclaw gateway start。端口 18789 被占用的话，改openclaw.json里gateway.port换一个，然后重启。
reading choices 报错 / 返回结构解析失败：说明通道返回的 JSON 结构和 Openclaw 预期不一致。检查api字段是否是openai-completions，以及models数组里的id是否是通道支持的模型 ID。如果模型 ID 写错，通道可能返回错误结构，Openclaw 解析choices时就报错。
OAuth 相关报错：如果你之前配过其他 provider 的 OAuth，残留配置可能干扰。检查openclaw.json里有没有多余的 provider 段，清理掉不用的。Openclaw 会按primary指定的 provider 走，但残留配置有时会导致初始化异常。
WSL2 里连不到宿主机服务：如果你在 WSL2 里跑 Ollama 或其他本地服务，注意127.0.0.1在 WSL2 里指向的是 WSL 自己，不是 Windows 宿主机。用ip route show | grep default | awk '{print $3}'查真实网关 IP，把baseUrl里的127.0.0.1换成这个 IP。不过用 TaoToken 通道就不存在这个问题，因为它是公网地址。
排查顺序建议：先 curl 验证通道 → 再检查openclaw.json结构 → 最后看 gateway 日志。日志在~/.openclaw/logs/下，报错信息比面板提示详细得多。
6. 长期使用建议与接入文档
跑通之后，如果你打算天天用 Openclaw 做编码或自动化任务，建议把 gateway 设置成开机自启。在 Windows 任务计划程序里创建一个基本任务，程序填explorer.exe，参数填shell:AppsFolder\你的Ubuntu AUMID，触发条件选「计算机启动时」。AUMID 可以用Get-StartApps | Where-Object { $_.Name -like "*Ubuntu*" }查到。
配置文件建议定期备份，但备份前把 Key 替换成占位符。如果多人共用一台机器，chmod 600是必须的。模型 ID 如果后续要换，只改openclaw.json里models数组的id和agents.defaults.model.primary两处，保持一致即可。
接入过程中如果遇到通道层面的问题，比如 Key 管理、模型列表、额度查询，可以看接入文档，里面有各语言的调用示例和错误码说明。需要新建或轮换 Key 就去 API Keys 页面。想先试试通道返回效果，模型对话页面可以直接发消息验证。长期高频编码任务的话，Coding Plan 的额度模型更适合，具体可以对比一下自己的调用量再决定。
最后提醒一点：Openclaw 的 skill 权限比较大，能读写文件、执行命令，配置gateway.nodes.denyCommands时把不需要的敏感操作禁掉，比如摄像头、通讯录、日历这些。默认模板已经禁了一部分，按自己需求调整。跑通之后先从只读任务开始试，确认行为符合预期再放开更多权限。