1. 为什么环境准备阶段最容易卡住Windows WSL OpenClaw 这套组合真正让人卡住的往往不是 OpenClaw 本身而是它脚下那层地基WSL 的网络模式、端口转发、Node.js 版本、系统依赖库还有模型通道的 Key 配置。我见过太多人在npm install阶段报一堆sharp相关错误或者在浏览器里死活打不开localhost:18789最后发现是 WSL 的 IP 变了、端口映射没更新。这篇是系列第三篇专门讲环境准备。目标很明确让你在装 OpenClaw 之前把 WSL 网络、端口转发、系统依赖、Node.js 24、以及 TaoToken 的配置骨架全部铺好。配置骨架我会给出可直接复制的settings.json和config.toml并演示怎么通过统一 Key/API 通道接入 TaoToken最后附上验证连通性的命令和常见报错排查。适合谁看第一次在 Windows 上部署 OpenClaw 的开发者或者之前装过但被网络和依赖问题劝退的人。你不需要很懂 Linux但需要愿意打开 PowerShell 敲几条命令。先说结论环境准备的核心就三件事——让 Windows 能访问 WSL 里的服务、让 WSL 能装齐 OpenClaw 需要的依赖、让 OpenClaw 能通过一个稳定的 API 通道拿到模型能力。前两件是系统层第三件是配置层下面逐个拆。2. TaoToken 前置统一 Key 与 API 通道OpenClaw 这类工具在跑起来之后需要调用大模型来完成对话、代码生成、Agent 任务。如果你每个模型都单独配一个 Key、单独记一个 Base URL配置会变得很碎换模型时还要改代码。TaoToken 在这里扮演的角色就是一个统一的 API 通道你拿一个 Key配一个 Base URL就能在 OpenClaw 里切换不同模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加任何 UTM 参数配置里直接写这个就行。你需要提前做两件事第一注册并拿到 API Key。登录后进控制台在 API Keys 页面创建一个新 Key。这个 Key 就是后面settings.json和config.toml里要填的东西。创建入口在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二确认你要用的模型名。OpenClaw 的配置里需要指定模型标识比如claude-sonnet-4-20250514这类。你可以在模型对话页面先试一下确认通道通不通入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。提示Key 只创建一次就够不要每个模型建一个。TaoToken 的设计就是一把 Key 走通所有模型配置里换的是模型名不是 Key。如果你后面要长期跑编码类 Agent 任务可以关注 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时对照文档最稳。3. WSL 网络模式与端口转发配置3.1 NAT 模式为什么是默认选择WSL2 默认走 NAT 模式WSL 有自己独立的虚拟网卡和 IP和 Windows 不在同一网段。这意味着 Windows 上的浏览器不能直接通过localhost访问 WSL 里的服务除非你显式做端口转发。另一种模式是镜像模式WSL 共享 Windows 网络栈localhost直接通。但镜像模式对 Windows 版本有要求部分环境不支持而且网络隔离性差WSL 里的服务可能意外暴露到局域网。OpenClaw 的 Gateway 默认监听 18789 端口用 NAT 加显式端口转发你能清楚知道哪些端口对外开放安全性更可控。配置文件在C:\Users\你的用户名\.wslconfig内容如下[wsl2] networkingModeNAT localhostForwardingtruenetworkingModeNAT启用 NAT 模式localhostForwardingtrue允许 Windows 通过 localhost 访问 WSL 端口但这个转发有局限实际还是建议手动配 portproxy。改完执行wsl --shutdown让配置生效等几秒再启动。3.2 端口转发脚本WSL 的 IP 每次重启都可能变所以端口转发不能只配一次。下面这段 PowerShell 脚本会先取当前 WSL IP再删旧规则、加新规则# 获取 WSL IP $wslIp wsl -d Ubuntu-24.04 -e bash -c hostname -I | awk {print $1} $wslIp $wslIp.Trim() Write-Host WSL IP: $wslIp # 删除旧规则 netsh interface portproxy delete v4tov4 listenport18789 listenaddress127.0.0.1 2$null # 添加新规则 netsh interface portproxy add v4tov4 listenport18789 listenaddress127.0.0.1 connectport18789 connectaddress$wslIp # 验证 netsh interface portproxy show all预期输出里应该能看到一行127.0.0.1 18789 wslIp 18789。如果connectaddress是空的说明 WSL IP 没取到检查发行版名字对不对。3.3 防火墙放行Windows 防火墙默认可能拦掉入站连接加一条规则放行 18789New-NetFirewallRule -DisplayName OpenClaw-Gateway -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow -Profile Any这条命令需要管理员权限的 PowerShell。执行完可以用Get-NetFirewallRule -DisplayName OpenClaw-Gateway确认规则存在。3.4 持久化处理WSL IP 会变所以每次开机后端口转发可能失效。最省事的做法是把上面的脚本存成fix-wsl-port.ps1然后创建一个计划任务在用户登录时自动跑一次。或者你每次重启后手动跑一遍也就几秒钟的事。4. 系统依赖与 Node.js 24 安装4.1 基础依赖进 WSL 后先更新源再装基础工具sudo apt-get update sudo apt-get install -y \ curl \ wget \ python3 \ python3-pip \ build-essential4.2 sharp 依赖必须装OpenClaw 依赖sharp做图片处理而sharp需要libvips。不装的话npm install阶段会报spawn sh ENOENT或者sharp相关的编译错误sudo apt-get install -y libvips-dev libvips-tools这个坑很常见报错信息里会提到node_modules/sharp看到就回来装libvips-dev。4.3 apt 太慢换镜像如果apt-get update卡住或超时换阿里云镜像sudo cp /etc/apt/sources.list.d/ubuntu.sources \ /etc/apt/sources.list.d/ubuntu.sources.bak sudo sed -i s|http://archive.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g \ /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g \ /etc/apt/sources.list.d/ubuntu.sources sudo apt-get update4.4 手动装 Node.js 24Ubuntu 24.04 默认源里的 Node.js 版本偏旧OpenClaw 需要 24。手动装cd /tmp NODE_VERSIONv24.0.0 NODE_TARnode-${NODE_VERSION}-linux-x64.tar.xz curl -fsSL https://nodejs.org/dist/${NODE_VERSION}/${NODE_TAR} -o node.tar.xz sudo tar -xf node.tar.xz sudo rm -rf /usr/local/node 2/dev/null sudo mv node-${NODE_VERSION}-linux-x64 /usr/local/node sudo ln -sf /usr/local/node/bin/node /usr/local/bin/node sudo ln -sf /usr/local/node/bin/npm /usr/local/bin/npm node -v npm -vnode -v应该输出v24.x.x。如果输出的是旧版本检查/usr/local/bin/node软链是否指对了。4.5 npm 换国内镜像npm config set registry https://registry.npmmirror.com npm config get registry第二条命令应该返回https://registry.npmmirror.com。5. TaoToken 配置骨架settings.json 与 config.toml5.1 settings.json 骨架OpenClaw 的settings.json通常放在项目根目录或用户配置目录。下面是一个可直接复制的骨架重点是apiBase和apiKey两个字段{ gateway: { host: 0.0.0.0, port: 18789 }, model: { provider: openai-compatible, apiBase: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelName: claude-sonnet-4-20250514, maxTokens: 8192, temperature: 0.7 }, logging: { level: info } }apiBase写https://taotoken.net/api不要带 UTM 参数。apiKey换成你在控制台创建的那把。modelName按你实际要用的模型填。5.2 config.toml 骨架有些 OpenClaw 版本或插件用 TOML 配置骨架如下[gateway] host 0.0.0.0 port 18789 [model] provider openai-compatible api_base https://taotoken.net/api api_key sk-你的TaoTokenKey model_name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.7 [logging] level info两个文件里的 Key 和模型名保持一致避免一个改了另一个忘了。5.3 环境变量方式如果你不想把 Key 写进文件可以用环境变量export TAOTOKEN_API_KEYsk-你的TaoTokenKey export TAOTOKEN_API_BASEhttps://taotoken.net/api然后在配置里引用${TAOTOKEN_API_KEY}。这样 Key 不会进版本库适合团队协作。6. 验证连通性与常见报错排查6.1 验证 API 通道在 WSL 里用 curl 直接打 TaoToken 的 API确认 Key 和网络都通curl -s -o /dev/null -w %{http_code} \ -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 10 }返回200说明通道通。返回401是 Key 不对404是路径或模型名不对000是网络不通。6.2 验证 Gateway 端口在 Windows PowerShell 里测端口转发Test-NetConnection -ComputerName 127.0.0.1 -Port 18789TcpTestSucceeded为True说明转发生效。为False就回去检查 portproxy 规则和 WSL IP。6.3 常见报错对照报错原因处理spawn sh ENOENT缺 libvipssudo apt-get install -y libvips-devECONNREFUSED 127.0.0.1:18789端口转发失效重跑 portproxy 脚本401 UnauthorizedKey 错误检查 settings.json 里的 apiKey404 model not found模型名不对对照文档确认模型标识node: command not foundNode 软链没建重跑软链命令apt-get update超时源太慢换阿里云镜像6.4 一个容易忽略的点WSL 重启后 IP 变了但 Windows 的 portproxy 规则还指向旧 IP这时候浏览器访问localhost:18789会超时。养成习惯每次重启 WSL 后跑一遍fix-wsl-port.ps1。如果你用的是自动化安装脚本它通常会在安装时处理一次但后续重启还是得手动或计划任务兜底。7. 下一步接入与长期使用环境铺好之后OpenClaw 的安装本身反而简单。配置骨架里的 Key 和 API 地址填对Gateway 起来后浏览器能打开模型能回话就算通了。如果你在验证阶段想先确认模型通道没问题可以直接用模型对话页面试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。要管理或新建 Key去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。配置字段拿不准时接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期跑编码和 Agent 任务的话Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定额度和统一通道的场景。最后留一个实操建议把fix-wsl-port.ps1和check-environment.ps1放在同一个目录每次重启后先跑检查脚本看到端口和 WSL 状态都正常再启动 OpenClaw。这个习惯能省掉大量“为什么昨天还好今天就不通”的排查时间。
