1. Windows 上跑 OpenClaw 到底卡在哪WSL2 环境搭建与 Ubuntu 依赖配置全流程OpenClaw 是一个开源的个人 AI 助手平台能通过自然语言指令帮你管理文件、整理目录、执行脚本、读写文档甚至对接聊天软件做多通道交互。它适合想在本地掌控数据、又希望有个能主动干活的“数字管家”的开发者。问题在于OpenClaw 的原生运行环境是 LinuxWindows 用户直接装会遇到一堆路径、权限和依赖问题。我试过在纯 Windows 下折腾npm 全局包、Node 版本管理、系统调用各种报错最后老老实实回到 WSL2 Ubuntu 这条路。这篇教程就是给 Windows 用户的完整落地流程从 WSL2 发行版安装、Ubuntu 依赖清单、Node 环境配置到 OpenClaw 启动验证最后把 API 通道统一到 TaoToken 完成连通性测试。全程命令可复制报错有对照。你不需要提前懂 Linux跟着敲就行。核心检索词先明确Windows 安装 OpenClaw、WSL2 Ubuntu 环境搭建、OpenClaw 接入 TaoToken。这三个词贯穿全文每一步都围绕它们展开。先说清楚为什么必须用 WSL2。OpenClaw 依赖 Linux 的文件系统语义和进程管理WSL2 提供的是完整 Linux 内核不是模拟层兼容性最好。WSL1 虽然轻量但系统调用翻译层会导致 OpenClaw 的部分脚本执行异常所以直接上 WSL2。Ubuntu 选 22.04 LTS 或 24.04 LTS 都行我下面以 22.04 为例24.04 命令基本一致。整个流程分六块原问题与场景、TaoToken 前置准备、可复制配置、验证请求、常见错排查、CTA 分流。你可以按顺序走也可以直接跳到卡住的那一步。2. TaoToken 前置准备API 通道统一与 Key 获取在装 OpenClaw 之前先把 API 通道的事情理清楚。OpenClaw 本身是执行框架它需要调用大模型来完成理解和决策。默认情况下你可能要分别配置多个模型供应商的 Key管理起来很乱。TaoToken 的作用是把这些 API 通道统一到一个入口你只需要一个 Base URL 和一个 Key就能在 OpenClaw 里切换不同模型。TaoToken 是什么它是一个 API 聚合与转发服务兼容 OpenAI 风格的接口协议。对 OpenClaw 来说你只要把 Base URL 指向 TaoToken 的 API 地址填上申请的 Key再指定 Model ID就能跑通。适合谁想在一个地方管理多个模型、不想每个供应商单独注册配置的开发者。前置准备分三步。第一步注册并登录 TaoToken 控制台。打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册。登录后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步创建 API Key。在控制台里找到 API Keys 页面路径是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。点创建复制生成的 Key格式通常是 sk- 开头的一串字符。这个 Key 只显示一次先存到安全的地方。第三步确认 Base URL 和 Model ID。TaoToken 的 API 基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于程序配置。Model ID 根据你要用的模型填比如 claude-sonnet-4-20250514、gpt-4o 这类具体以控制台模型列表为准。如果你不确定选哪个可以先在模型对话页面测试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这里有个关键点OpenClaw 的配置文件里需要同时填 Base URL、Key、Model ID 三件套。少一个都连不上。我见过有人只填了 Key 没改 Base URL结果请求发到默认地址一直 401。所以下面配置环节我会把三件套写全。另外如果你打算长期跑编码类 Agent 任务可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它针对高频编码场景做了额度优化比按量计费更划算。这个不是必须的先跑通基础接入再说。3. 可复制配置WSL2 安装、Ubuntu 依赖与 OpenClaw 启动这一节是全文核心所有命令都可以直接复制。我按顺序拆成 WSL2 安装、Ubuntu 初始化、Node 环境、OpenClaw 安装、配置文件写入五步。3.1 WSL2 安装与 Ubuntu 发行版以管理员身份打开 PowerShell执行wsl --install -d Ubuntu-22.04这条命令会自动启用 WSL2 所需组件、下载 Ubuntu 22.04 镜像并安装。装完后重启电脑。重启后 Ubuntu 会自动启动让你设置用户名和密码。用户名建议用小写字母比如 dev密码记牢后面 sudo 要用。如果你已经装过 WSL 但版本是 1先升级wsl --set-default-version 2 wsl --update验证 WSL2 是否生效wsl -l -v输出里 VERSION 列应该是 2。如果是 1执行wsl --set-version Ubuntu-22.04 2转换。进入 Ubuntu 终端后先更新软件源sudo apt update sudo apt upgrade -y3.2 Ubuntu 依赖清单OpenClaw 运行需要这些基础依赖一次性装齐sudo apt install -y curl git build-essential libssl-dev libffi-dev python3 python3-pip python3-venv逐个说明curl 用于下载安装脚本git 用于拉取仓库build-essential 提供编译工具链libssl-dev 和 libffi-dev 是 Node 原生模块编译所需python3 系列是部分脚本依赖。缺任何一个都可能在 npm install 阶段报 node-gyp 错误。3.3 Node 环境nvm Node 22不要用 apt 装 Node版本太旧。用 nvm 管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash source ~/.bashrc然后安装 Node 22nvm install 22 nvm use 22 nvm alias default 22验证node -v npm -v应该输出 v22.x.x 和对应的 npm 版本。如果nvm命令找不到检查 ~/.bashrc 里是否有 nvm 的加载脚本没有就手动加export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh3.4 安装 OpenClawnpm install -g openclaw如果卡在下载或报网络错误换 npm 镜像npm config set registry https://registry.npmmirror.com npm install -g openclaw装完验证openclaw --version3.5 配置文件写入三件套OpenClaw 的配置目录通常在~/.openclaw/。创建配置文件mkdir -p ~/.openclaw cat ~/.openclaw/config.json EOF { api: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key粘贴在这里, model: claude-sonnet-4-20250514 }, agent: { name: my-claw, workspace: /home/dev/openclaw-workspace } } EOF把sk-你的Key粘贴在这里替换成你在 TaoToken 控制台创建的真实 Keymodel换成你要用的 Model ID。workspace 目录提前建好mkdir -p ~/openclaw-workspace如果你用的是 TOML 格式配置部分版本支持对应写法[api] baseUrl https://taotoken.net/api apiKey sk-你的Key粘贴在这里 model claude-sonnet-4-20250514 [agent] name my-claw workspace /home/dev/openclaw-workspace保存为~/.openclaw/config.toml。两种格式选一种即可JSON 兼容性更广。3.6 启动 OpenClawopenclaw onboard这个命令会引导你完成初始化包括确认配置、创建工作区、测试 API 连通性。按提示走遇到询问 API 配置时确认 Base URL 是https://taotoken.net/apiKey 和 Model 正确。启动成功后你会看到类似OpenClaw agent is running的输出。此时可以开一个新终端测试openclaw status应该显示 agent 运行状态和当前模型信息。4. 验证请求连通性测试与成功结果配置写完不代表通了必须做一次真实请求验证。OpenClaw 提供了内置的测试命令openclaw test --prompt 你好请回复当前模型名称如果返回了模型回复说明 API 通道打通。返回内容里应该包含你配置的 Model ID 对应信息。更直接的验证方式是用 curl 测 TaoToken 接口curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 10 }成功返回的 JSON 里会有choices数组包含模型回复。如果返回 401说明 Key 不对返回 404说明 Base URL 或路径不对返回 model not found说明 Model ID 写错。OpenClaw 侧再跑一次完整任务验证openclaw run --task 在当前目录创建一个 test.txt 文件写入 hello openclaw执行后检查文件是否生成cat ~/openclaw-workspace/test.txt看到hello openclaw就说明从指令解析到文件操作全链路通了。这一步同时验证了模型调用和本地执行能力。实测下来最容易出问题的是 Base URL 末尾的斜杠。TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/部分 HTTP 客户端会把双斜杠当路径处理导致 404。另外 Key 前后不要有空格复制时容易带上。如果你在 OpenClaw 里配置了多个模型可以用openclaw models list查看当前可用列表用openclaw models use model-id切换。切换后重新跑一次 test 命令确认。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。你遇到问题时直接搜报错关键词。5.1 401 Unauthorized报错原文Error: 401 Unauthorized或invalid api key。原因通常是 Key 错误或没带上。排查步骤第一确认~/.openclaw/config.json里的 apiKey 是完整的 sk- 开头字符串没有多余空格或换行。第二确认 Key 没有过期或被删除去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 检查。第三用上面的 curl 命令单独测 Key排除 OpenClaw 配置问题。如果 curl 也 401就是 Key 本身的问题重新创建一个。5.2 local proxy failed报错原文local proxy failed或connect ECONNREFUSED 127.0.0.1:xxxx。这个通常出现在 WSL2 网络配置异常时。WSL2 有自己的虚拟网卡如果 Windows 侧有网络策略干扰WSL2 里的请求可能被拦。排查第一在 Ubuntu 里测基础网络curl -I https://taotoken.net/api看能否通。第二如果基础网络不通重启 WSL在 PowerShell 执行wsl --shutdown然后重新进入 Ubuntu。第三检查/etc/resolv.conf里的 DNS 配置WSL2 自动生成的通常没问题如果被手动改过恢复默认sudo rm /etc/resolv.conf sudo bash -c echo nameserver 8.8.8.8 /etc/resolv.conf注意这里只是解决 DNS 解析不涉及任何网络代理工具。WSL2 直连外网即可。5.3 reading choices 报错报错原文Cannot read properties of undefined (reading choices)。这是 OpenClaw 解析 API 返回时没拿到预期结构。原因一般是 Base URL 指向了错误的路径或者返回的不是 OpenAI 兼容格式。排查第一确认 Base URL 是https://taotoken.net/api不是https://taotoken.net。第二确认请求路径拼接正确OpenClaw 会自动在 Base URL 后加/v1/chat/completions所以最终是https://taotoken.net/api/v1/chat/completions。第三用 curl 直接测这个完整路径看返回 JSON 里有没有choices字段。如果没有检查 Model ID 是否在 TaoToken 支持列表里。5.4 OAuth 相关报错报错原文OAuth token expired或authentication failed。OpenClaw 某些版本会尝试 OAuth 流程做设备授权。如果你用的是 API Key 模式不需要 OAuth。排查第一确认配置文件里用的是 apiKey 字段而不是 oauth 字段。第二如果 OpenClaw 启动时强制走 OAuth检查版本升级到最新npm update -g openclaw。第三在配置里显式关闭 OAuth{ auth: { mode: apikey } }合并到主配置里即可。5.5 其他高频问题node-gyp编译失败缺 build-essential 或 python3回到 3.2 节补装。nvm: command not found~/.bashrc 没加载手动 source 或检查安装脚本是否执行成功。openclaw: command not foundnpm 全局 bin 目录不在 PATH执行npm config get prefix看路径把它加到 PATH。EACCES permission denied不要用 sudo 装 npm 全局包用 nvm 管理的 Node 不需要 sudo。如果之前用 sudo 装过先卸载再重装。6. 接入文档与后续操作入口跑通之后你可能会想深入配置 OpenClaw 的更多能力比如接入聊天软件、自定义工作流、多模型切换。这些在 TaoToken 的接入文档里有对应说明地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。文档里覆盖了 API 参数、错误码、模型列表和调用示例。如果你主要用 OpenClaw 做编码类任务比如自动写代码、重构、跑测试可以看下 Coding Plan 的额度方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它针对高频调用做了优化比按量计费更适合长期跑 Agent。需要管理多个 Key 或查看调用量去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。新建 Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先测试模型效果再决定用哪个模型对话页面可以直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一个实操细节WSL2 的 Ubuntu 文件系统和 Windows 是隔离的OpenClaw 的工作区在 Ubuntu 里如果你想在 Windows 资源管理器里访问路径是\\wsl$\Ubuntu-22.04\home\dev\openclaw-workspace。但不要直接在 Windows 侧修改这些文件权限会乱。所有操作都在 Ubuntu 终端里做。配置改完后重启 OpenClaw 让新配置生效openclaw restart然后重新跑一次openclaw test确认。整个流程走下来从零到跑通大概 20 分钟主要时间花在 WSL2 首次安装和依赖下载上。装完之后日常使用就是openclaw run --task 你的指令剩下的交给它执行。