1. WSL 里跑 OpenClaw为什么 settings.json 和 Key 配置总让人绕晕OpenClaw 在 Windows 上的官方推荐路径是 WSL2这件事本身不难理解CLI 和 Gateway 都跑在 Linux 侧工具链一致、依赖冲突少比硬扛原生 Windows 省心得多。但真正上手之后很多人会卡在同一个地方——settings.json到底该写在哪、模型 Key 该配在哪一层、为什么 Gateway 起来了 Control UI 也能打开可一发消息就报认证失败或者模型无响应。这个问题的根源在于 OpenClaw 是分层系统。Gateway 是总机负责接入、路由、会话和健康检查Channel 是线路把 Telegram、Discord、Slack 这些平台接进来Agent 是干活的人Model 是底层推理引擎而 Auth profile 则是模型侧的凭据档案管理 API key、OAuth、token 这些认证信息。你在 WSL 里敲的openclaw gateway或openclaw onboard --install-daemon生效范围都在 WSL 的 Ubuntu 里浏览器只是从 Windows 侧访问127.0.0.1:18789的 Control UI它连的还是 WSL 里的 Gateway。所以当模型调用失败时问题往往不在 Gateway 本身而在 Auth profile 这一层——也就是你的模型 Key 有没有正确落到 OpenClaw 能读到的地方。这篇就围绕 WSL 场景把settings.json的骨架和 TaoToken 统一 Key 的接入步骤讲清楚让你启动 OpenClaw 后能确认请求确实经统一通道发出、配置真正生效。适合已经在 WSL2 里装好 OpenClaw、但模型侧还没跑通的开发者。2. 前置准备WSL 环境检查与 TaoToken 统一 Key 获取在动settings.json之前先把 WSL 侧的基础条件确认一遍。OpenClaw 的 Gateway service install 依赖 systemd如果你的 WSL 还没启用先处理这个。2.1 确认 WSL2 与 systemd 状态打开 WSL 终端执行wsl --version在 Windows PowerShell 里能看到 WSL 版本号即可。接着进 WSL 内部确认 systemdsystemctl is-system-running如果返回running或degraded说明 systemd 已启用。若报错说 systemd 未运行需要在/etc/wsl.conf里加上[boot] systemdtrue然后回到 PowerShell 执行wsl --shutdown再重新进入。这一步不做后面openclaw onboard --install-daemon会直接失败。2.2 获取 TaoToken 统一 KeyTaoToken 的作用是把模型侧的认证收敛到一个统一通道你不需要在 OpenClaw 里为每个模型单独维护一套凭据。获取 Key 的入口在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewrite登录后在 API Keys 页面创建一个新 Key复制出来备用。这个 Key 就是后面要写进 OpenClaw Auth profile 的凭据。API 通道的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base URL 使用。如果你后续要接 Claude Code 这类工具Anthropic 兼容端点也走同一个通道具体路径在接入文档里有说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewriteKey 拿到后先别急着写配置下面先把settings.json的结构理清楚。3. 可复制配置settings.json 骨架与 TaoToken 接入OpenClaw 的配置文件在 WSL 里的位置通常是~/.config/openclaw/settings.json具体路径可以用openclaw config path确认。下面给一份可直接改用的骨架重点看auth和models两段。3.1 settings.json 完整骨架{ gateway: { host: 127.0.0.1, port: 18789, logLevel: info }, auth: { profiles: { taotoken-unified: { type: api_key, provider: openai-compatible, apiKey: sk-你的TaoTokenKey, baseUrl: https://taotoken.net/api } }, defaultProfile: taotoken-unified }, models: { default: gpt-4o-mini, fallback: [claude-3-5-sonnet], provider: taotoken-unified }, channels: { telegram: { enabled: false } } }几个关键点说明一下。auth.profiles里定义了一个名为taotoken-unified的凭据档案type是api_keyprovider用openai-compatible是因为 TaoToken 的 API 通道兼容 OpenAI 的请求格式。baseUrl填https://taotoken.net/api不要带尾部斜杠。models.provider指向这个 profile 名字这样模型调用就会走统一通道。3.2 用环境变量替代明文 Key把 Key 明文写在settings.json里不太安全尤其是 WSL 和 Windows 之间有文件共享时。更稳妥的做法是用环境变量在~/.bashrc或~/.zshrc里加export TAOTOKEN_API_KEYsk-你的TaoTokenKey然后settings.json里改成引用{ auth: { profiles: { taotoken-unified: { type: api_key, provider: openai-compatible, apiKeyEnv: TAOTOKEN_API_KEY, baseUrl: https://taotoken.net/api } }, defaultProfile: taotoken-unified } }改完执行source ~/.bashrc让变量生效。OpenClaw 启动时会读取这个环境变量Key 就不会出现在配置文件里。3.3 参数对照表字段作用建议值gateway.hostGateway 绑定地址127.0.0.1仅本机访问gateway.portControl UI 端口18789与官方默认一致auth.profiles.*.type凭据类型api_keyauth.profiles.*.provider请求协议openai-compatibleauth.profiles.*.baseUrlAPI 通道地址https://taotoken.net/apiauth.defaultProfile默认凭据档案与 profiles 里的键名一致models.provider模型走哪个档案同上配置写完后先别急着启动 Gateway用下面的命令做一次配置校验。4. 验证请求确认 OpenClaw 经统一通道发出配置生效与否不能只看 Gateway 有没有起来。网页能打开只说明 Gateway 大概率在线、HTTP/WebSocket 能访问但模型调用走没走统一通道是另一回事。下面分三步验证。4.1 配置语法与档案加载检查openclaw config validate如果返回配置合法再查 Auth profile 是否被正确加载openclaw auth list正常输出里应该能看到taotoken-unified这个档案并且标记为 default。如果这里看不到说明settings.json路径不对或者 JSON 语法有误回头检查openclaw config path指向的文件。4.2 发一条测试请求用 OpenClaw 自带的测试命令直接打模型openclaw model test --prompt reply with ok这条命令会走models.provider指定的档案也就是taotoken-unified。如果返回ok或类似响应说明请求已经经 TaoToken 统一通道发出并成功返回。如果报 401多半是 Key 无效或环境变量没生效报 404 则检查baseUrl是否写成了带路径的形式。4.3 从日志确认通道地址想更确定请求确实走了统一通道可以看 Gateway 日志openclaw gateway logs --follow在另一个终端再发一次openclaw model test日志里会出现请求的目标地址。确认它指向taotoken.net/api而不是其他默认端点就说明配置真正生效了。这一步做完模型侧的最小闭环就算跑通了。5. 本篇常见错排查WSL 下 OpenClaw 配置的坑即使按上面步骤走WSL 场景还是有几个高频问题。下面按现象列出来方便对照。5.1 Gateway 起了但模型调用失败这是最典型的。Gateway 在线只代表总机开机不代表模型线路接通。先跑openclaw auth list确认档案加载再跑openclaw model test看具体报错。如果档案在但测试失败重点查 Key 和环境变量。WSL 里export的变量在非交互式 shell 里可能读不到建议写进~/.profile而不是只写~/.bashrc。5.2 远程访问时地址写成 127.0.0.1如果你想让别的机器或远程节点访问 WSL 里的 Gateway不能继续用127.0.0.1因为那指向的是对方自己。需要改成 WSL 可达的地址必要时在 Windows 侧做端口转发。官方 WSL 文档里有 portproxy 的配置示例核心思路是把 Windows 主机的某个端口转发到 WSL 的18789。这一步不做远程客户端连不上是必然的。5.3 Channel 不工作与模型配置无关Telegram、Discord 这些 channel 的接入是独立一层涉及各自的 token、bot 权限和平台连接状态。Gateway 正常启动不依赖任何 channel所以「网页能打开但 channel 不工作」不代表模型配置有问题。排查 channel 要看 health-monitor 日志里有没有 stuck 或 disconnected 的重连记录以及对应平台的 bot 权限是否配全。5.4 配置文件路径混淆WSL 里 OpenClaw 读的是 Linux 侧路径不是 Windows 的C:\Users\...。如果你在 Windows 编辑器里改了配置但没同步到 WSL 文件系统OpenClaw 读到的还是旧文件。用openclaw config path确认实际路径直接在 WSL 里用nano或vim改最稳妥。6. 统一 Key 之后模型对话与长期编码的接入选择模型侧跑通之后接下来看你的使用场景。如果只是想验证模型是否正常、偶尔对话测试可以直接用模型对话入口https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewrite如果你打算在 WSL 里长期跑编码任务或 Agent 工作流Coding Plan 更适合它针对持续调用做了额度优化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewrite需要管理多个 Key 或查看调用量回控制台的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewrite接入细节和兼容端点说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentwsl_openclaw_settingsutm_campaignrewriteWSL 场景下 OpenClaw 的配置核心就一句话Gateway 在 Linux 侧模型凭据走 Auth profile统一 Key 落到settings.json的auth.profiles里用openclaw model test验证请求确实经统一通道发出。把这几层分清楚后面 channel 和 Agent 的排错就不会再和模型配置混在一起。
