1. 为什么在 WSL 里装 OpenClaw 总卡住OpenClaw 是一个跑在终端里的 AI 编码助手能读项目、改文件、执行命令适合习惯命令行、又想让模型帮忙写代码的人。它本身是 Node.js 写的 CLI 工具理论上npm install一条命令就能装好但放到 Windows 的 WSL 环境里事情就没那么顺了。我见过最多的三类翻车现场一是npm install -g openclaw跑到一半终端彻底不动等十分钟也没反应其实是安装脚本在拉编译依赖时卡在网络上二是装完了敲openclaw start或openclaw run直接报unknown command因为新版早就把这两个命令废弃了三是面板起来了Windows 浏览器却打不开127.0.0.1的链接或者打开了却提示 401 认证失败。这篇就按「先装通、再配 Key、最后验证」的顺序走一遍重点放在可复制的settings.json骨架和 TaoToken 统一 Key 的接入上。你不需要懂太多 Node 生态照着命令敲、照着配置改基本能一次跑通。适合刚接触 WSL、想用 OpenClaw 又不想在环境上耗一整晚的新手。2. 前置准备WSL2、Node 20 与 TaoToken Key2.1 确认 WSL 版本和网络互通先在 Windows 的 PowerShell 里执行wsl -l -v输出里VERSION那一列必须是2。如果是1用wsl --set-version Ubuntu 2升级WSL1 的网络映射和端口转发跟 WSL2 差别很大很多「浏览器打不开」的坑根源就在这。WSL2 默认会把子系统里的127.0.0.1端口映射到 Windows 本机所以 OpenClaw 面板监听127.0.0.1:1878时Windows 浏览器直接访问同一个地址就行不用改 IP。这一点先记住后面排障会用到。2.2 Node.js 版本别低于 20进 WSL 终端Ubuntu检查node -v npm -vnode -v要输出v20.x或更高。低于 20 的话OpenClaw 的部分依赖会报语法错误。用 nvm 装最省事curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 202.3 在 TaoToken 拿统一 KeyOpenClaw 支持自定义模型接入点这里用 TaoToken 的统一 Key好处是一个 Key 能对接多个模型不用为每个模型单独申请。操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进控制台在 API Keys 页面创建一个新 Key。创建时建议给它起个能认出来的名字比如openclaw-wsl方便以后在控制台里区分和吊销。拿到 Key 之后先别急着填进 OpenClaw记下两个东西Key 本身通常是一串以特定前缀开头的字符以及接入文档里给的 Base URL。Base URL 是 OpenClaw 请求模型的入口地址填错会直接 404 或 401。注意Key 只在创建时完整显示一次关掉页面就看不到了。建议先复制到临时文本里配完再删。3. 安装 OpenClaw绕开卡死的正确姿势3.1 用国内源加 --ignore-scripts直接npm install -g openclaw在 WSL 里大概率卡在 postinstall 阶段因为默认源在国外拉二进制依赖时容易超时。换成国内镜像并跳过编译脚本npm install -g openclaw \ --registryhttps://registry.npmmirror.com \ --ignore-scripts \ --no-fund三个参数的作用--registry把包下载源指向国内镜像速度明显快--ignore-scripts跳过安装时的编译脚本这是解决「卡死」最关键的一步OpenClaw 运行时不依赖那些脚本产物--no-fund只是关掉赞助提示让输出干净点。如果之前已经卡过一次先CtrlC终止再执行npm cache clean --force清一下缓存然后重跑上面的命令。3.2 验证安装结果openclaw --version正常会输出类似OpenClaw 2026.4.0的版本号具体数字随版本变化能打印出来就说明二进制已经就位。如果提示command not found多半是 npm 全局 bin 目录没进 PATH执行npm config get prefix看路径再把它加到~/.bashrc的 PATH 里。3.3 初始化配置openclaw onboard按提示走安全提示选 Yes模型选择这一步先保持默认后面我们会用settings.json覆盖成 TaoToken 的接入点。API Key 那一步可以先随便填或跳过因为真正的配置我们手写进文件比交互式输入更可控。4. settings.json 骨架TaoToken 统一 Key 接入4.1 配置文件放哪OpenClaw 的配置目录默认在~/.openclaw/主配置文件是settings.json。如果目录不存在就手动建mkdir -p ~/.openclaw touch ~/.openclaw/settings.json4.2 可复制的配置骨架把下面这段写进~/.openclaw/settings.json把YOUR_TAOTOKEN_KEY换成你在控制台创建的那串 Key{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY, model: claude-sonnet-4-20250514 }, runtime: { timeoutMs: 120000, maxRetries: 2 }, dashboard: { host: 127.0.0.1, port: 1878 } }几个字段说明baseUrl用 TaoToken 的 API 地址https://taotoken.net/api注意这里不带任何查询参数apiKey就是统一 Keymodel填你想用的模型标识具体可用值以接入文档为准timeoutMs给到 120 秒避免长任务被过早掐断dashboard.port固定 1878跟后面验证命令对应。提示JSON 不支持注释粘贴时别把说明文字带进去否则启动会报解析错误。4.3 用环境变量兜底可选不想把 Key 明文写进文件的话可以改成读环境变量echo export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc然后把settings.json里的apiKey改成${TAOTOKEN_API_KEY}。OpenClaw 启动时会做变量替换这样配置文件即使被同步或截图也不泄露 Key。5. 验证连通性三条命令跑通5.1 检查配置是否被正确读取openclaw status输出里会显示当前 provider、baseUrl 和模型名。如果 provider 还是默认值说明settings.json没被读到检查文件路径和 JSON 格式可以用python3 -m json.tool ~/.openclaw/settings.json验证语法。5.2 发一条真实请求openclaw chat 用一句话说明什么是递归这条命令会走完整的「读配置 → 请求 TaoToken → 返回结果」链路。能正常打印模型回复就说明 Key、Base URL、模型名三者都对上了。如果报 401是 Key 的问题报 404多半是 Base URL 写错报超时检查 WSL 的出网是否正常。5.3 启动面板并访问openclaw dashboard终端会输出一个带 token 的链接形如Dashboard URL: http://127.0.0.1:1878/#tokenxxxxxxxx复制完整链接在 Windows 浏览器里打开。WSL2 会自动做端口映射不需要改 IP。面板能加载出来、并且能正常对话整个环境就算跑通了。关闭服务按CtrlC。6. 常见报错排查清单6.1 安装阶段卡死不动现象是npm install跑了几行就没反应。先CtrlC清缓存npm cache clean --force再确认命令里带了--ignore-scripts和国内 registry。如果还卡检查 WSL 的 DNScat /etc/resolv.conf必要时在/etc/wsl.conf里关掉自动生成 DNS 再重启 WSL。6.2 unknown command: start / run新版 OpenClaw 已经没有start和run子命令这是正常的。启动服务统一用openclaw dashboard它同时完成启动和打开面板两件事。看到这个报错不用怀疑安装换命令即可。6.3 浏览器打不开面板先确认终端里openclaw dashboard还在前台运行没被CtrlC关掉。然后确认访问的是终端输出的完整链接带#token那段少复制了 token 会停在登录页。如果仍打不开检查settings.json里dashboard.host是不是127.0.0.1改成0.0.0.0有时能解决 WSL 端口映射的个别情况。6.4 401 认证失败九成是 Key 的问题要么复制时带了空格要么 Key 已被吊销要么账户余额不足。重新在控制台创建一个新 Key替换settings.json里的apiKey再跑一次openclaw chat验证。改完配置不需要重启 WSLOpenClaw 每次请求都会重新读配置。6.5 模型名报 not foundmodel字段填的值必须是 TaoToken 接入文档里列出的可用标识写错或写了不存在的模型会返回 not found。对照文档改一下再验证。7. 接下来怎么用按场景选入口环境跑通之后日常使用分几种情况。如果你只是想快速验证某个模型回答得怎么样直接用模型对话页面最省事不用碰命令行https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算把 OpenClaw 长期挂在项目里做编码助手或者接进 Agent 工作流建议看一下 Coding Plan它按长期编码场景做了额度规划比单次调用更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要管理多个 Key、查看调用量或调整额度进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的创建和吊销都在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置字段的含义、可用模型列表、Base URL 的准确写法都以接入文档为准遇到对不上的地方先查文档再改配置https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用的是 Claude Code 这类 Anthropic 系工具接入方式略有差异参考这个页面https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我踩过的坑改完settings.json后如果openclaw status显示的还是旧配置多半是文件里有多余的逗号或中文引号用python3 -m json.tool过一遍就能定位到具体行号。配置这东西格式对了就成功一半。
