1. 从一次本地调用失败说起OpenClaw 多模型链路到底卡在哪如果你正在读 OpenClaw 的源码大概率会经历这样一个瞬间Gateway 起来了通道也连上了消息能进来但模型就是不回。日志里翻来覆去只有一句local proxy failed或者401 Unauthorized你盯着src/agents/model-selection.ts和src/gateway/server-methods.ts来回看却找不到 Key 是在哪一层被塞进请求头的。这不是你代码读得不够细而是 OpenClaw 的模型调用链路本身是分层的通道层只负责收消息Gateway 负责鉴权和路由真正把请求发到模型服务商的是 Agent Runtime 里的 Model Layer。这三层之间靠配置对象OpenClawConfig串起来而 Key 的注入点藏在secrets和models.providers两个字段里。很多人第一次读源码时会默认「配了 apiKey 就能用」实际上还要过prepareSecretsRuntimeSnapshot这一关。这篇笔记聚焦的就是这条链路从消息进入 Gateway到 Agent 选中模型再到请求带着鉴权信息发出去最后响应回到会话。我会用 TaoToken 的统一 Key 通道作为参照物因为它的接入方式和 OpenClaw 的 provider 抽象刚好能对上——一个 Base URL 加一个 Key就能覆盖多个模型。这样你在读源码时能有一个具体的、可验证的配置对象去对照。适合谁看已经跑通过 OpenClaw 基础流程、想搞清楚模型调用内部实现的开发者或者正在给自己的 Agent 项目做多模型路由、想参考一套成熟鉴权设计的人。下面所有配置片段都可以直接复制到你的openclaw.json5里改掉 Key 就能跑。2. TaoToken 统一 Key 通道在 OpenClaw 里它对应哪一层先把概念对齐。OpenClaw 源码里没有「统一 Key 通道」这个类名它对应的是models.providers这个配置结构加上secrets运行时快照。你可以把 TaoToken 理解成一个兼容多模型协议的入口对外只暴露一个 Base URL 和一个 Key内部帮你路由到具体模型。在 OpenClaw 的抽象里这正好就是一个自定义 provider。我试过在src/config/types.ts里追ModelProviderConfig的定义它大概长这样baseUrl、apiKey、models三个核心字段外加可选的headers和timeout。这意味着任何兼容 OpenAI 或 Anthropic 协议的服务都能作为一个 provider 挂进去。TaoToken 的 API 地址是https://taotoken.net/api这个地址就是填在baseUrl里的值。关键点在于鉴权注入的时机。OpenClaw 启动时会调用prepareSecretsRuntimeSnapshot把配置里的明文 Key 替换成运行时引用避免 Key 在日志和内存快照里裸奔。所以你在源码里搜apiKey会发现两处一处是配置解析一处是运行时快照激活。真正发请求时Model Layer 从快照里取 Key拼成Authorization: Bearer key头。如果你只改了配置文件但没触发快照重载请求就会带着旧 Key 出去这就是401的常见来源。再往下看路由。src/agents/model-selection.ts里的resolveModelSelection会按优先级选模型先看会话级覆盖再看agents.profiles最后落到agent.model默认值。模型 ID 的格式是provider/model比如taotoken/claude-sonnet-4-6。这里的taotoken就是你在models.providers里定义的 key 名不是固定值你可以叫任何名字只要前后一致。所以整条链路是配置里定义 provider含 Base URL 和 Key→ 启动时激活密钥快照 → 会话选中provider/model→ Model Layer 从快照取 Key 拼请求头 → 发到 Base URL。TaoToken 在这个链路里扮演的是「被请求方」OpenClaw 扮演的是「请求组装方」。理解了这个分工后面配错时你就能快速定位是哪一环断了。3. 可复制配置openclaw.json5 里的 provider 与密钥片段这一节给你能直接用的配置。OpenClaw 的配置文件默认在~/.openclaw/openclaw.json5Windows 下是C:\Users\你\.openclaw\openclaw.json5格式是 JSON5允许注释和尾逗号。下面这段是完整可跑的 provider 配置路径和字段名都和源码里的OpenClawConfig类型对齐。{ // Agent 默认模型格式为 provider/model agent: { model: taotoken/claude-sonnet-4-6, thinking: medium, timeout: 120 }, // 模型提供商配置这里是统一 Key 通道的接入点 models: { providers: { taotoken: { // TaoToken 的 API 入口注意不要带末尾斜杠 baseUrl: https://taotoken.net/api, // 你的统一 Key建议用环境变量注入见下方说明 apiKey: ${TAOTOKEN_API_KEY}, // 声明这个 provider 下可用的模型 ID models: [ claude-sonnet-4-6, gpt-4o, deepseek-chat ], headers: { Content-Type: application/json }, timeout: 120 } }, // 模型别名方便在会话里用短名字切换 aliases: { sonnet: taotoken/claude-sonnet-4-6, gpt4o: taotoken/gpt-4o } }, // 密钥配置声明运行时快照的来源 secrets: { defaults: { // 从环境变量读取避免明文写进配置文件 source: env, prefix: OPENCLAW_ } }, gateway: { port: 18789, bind: loopback, auth: { mode: token, token: your-gateway-token } } }几个必须注意的点。第一apiKey我用了${TAOTOKEN_API_KEY}这种占位写法OpenClaw 的配置解析器支持环境变量插值但更稳妥的做法是配合secrets.defaults.source: env让运行时快照直接从环境变量取。你需要在启动 Gateway 前导出这个变量# macOS / Linux export TAOTOKEN_API_KEY你的统一Key # Windows PowerShell $env:TAOTOKEN_API_KEY你的统一Key第二baseUrl千万别写成https://taotoken.net/api/末尾斜杠会导致拼接出//v1/chat/completions这种路径部分服务端会返回 404。第三models数组里的 ID 要和你实际调用的模型名一致写错了会在resolveModelSelection阶段就报「model not found」而不是等到发请求才失败。如果你用的是 Claude Code 这类需要单独配置的工具思路一样Base URL 填https://taotoken.net/apiKey 填统一 KeyModel ID 填claude-sonnet-4-6。三件套齐了才能通。OpenClaw 这边则是把这三件套拆进了models.providers和agent.model两个地方。配置改完后别急着重启先跑一次配置校验openclaw doctor这个命令会检查配置结构、密钥快照是否能激活、provider 的 baseUrl 是否可达。如果这一步就报错说明配置本身有问题不用往下走。4. 验证请求一次本地调用看完整链路配置就绪后用最小动作验证链路是否打通。我建议不要一上来就连通道先用 OpenClaw 自带的 CLI 直接触发一次 Agent 运行这样能把通道层的干扰排除掉。第一步确认 Gateway 在跑openclaw gateway --port 18789另开一个终端执行一次单轮对话openclaw agent run \ --session test-link \ --message 只回复两个字通了 \ --model taotoken/claude-sonnet-4-6如果链路正常你会看到类似这样的输出[session:test-link] modeltaotoken/claude-sonnet-4-6 [provider:taotoken] baseUrlhttps://taotoken.net/api [secrets] snapshot activated, key sourceenv [response] 通了这几行日志对应源码里的几个关键节点model来自resolveModelSelectionbaseUrl来自 provider 配置snapshot activated来自prepareSecretsRuntimeSnapshotresponse来自 Model Layer 拿到结果后的回调。你能看到这四行说明从配置到请求到响应的整条链路是通的。如果想更细地看请求头可以临时把日志级别调到 debugOPENCLAW_LOG_LEVELdebug openclaw agent run \ --session test-link \ --message ping \ --model taotoken/claude-sonnet-4-6debug 日志里会打印出实际发出的请求头你能看到Authorization: Bearer ****Key 会被脱敏和Content-Type: application/json。这一步能帮你确认 Key 到底有没有被正确注入。如果这里显示的是Authorization: Bearer undefined那问题一定在密钥快照没激活回去检查secrets配置和环境变量。还有一个验证角度是看会话数据。OpenClaw 会把每次调用的 token 统计写进SessionData你可以用openclaw sessions list openclaw sessions show test-link输出里会有inputTokens、outputTokens、totalTokens和estimatedCostUsd。这些数字来自模型响应里的 usage 字段能对上就说明响应被正确解析了。如果 token 数一直是 0可能是响应格式和 OpenClaw 的解析器不匹配这时候要检查 provider 的协议类型是不是被正确识别。实测下来最容易出问题的不是配置本身而是环境变量没导出到 Gateway 进程里。比如你在 shell 里export了但 Gateway 是用 systemd 或别的用户启动的就读不到。这种情况openclaw doctor会提示「secret source env not found」看到这个提示就回去检查进程环境。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来对。你在 OpenClaw 里调模型大概率会撞上下面几类错误每一类对应的源码位置和修法都不一样。401 Unauthorized。这是最常见的。日志里通常长这样[provider:taotoken] request failed: 401 Unauthorized [secrets] key resolved: false看到key resolved: false基本可以确定是密钥快照没拿到 Key。排查顺序先确认环境变量在当前 shell 里echo $TAOTOKEN_API_KEY有值再确认openclaw.json5里secrets.defaults.source是env最后确认 Gateway 进程和你的 shell 是同一个环境。如果 Key 确实有值但还是 401检查 Key 有没有多余空格或者是不是复制时带了换行。local proxy failed。这个报错来自 Gateway 的网络层通常伴随[gateway] local proxy failed: connect ECONNREFUSED它说明请求根本没发出去卡在了本地。常见原因是baseUrl写错或者本机网络策略拦截了出站请求。先curl一下你的 Base URLcurl -I https://taotoken.net/api如果 curl 也连不上那就是网络层问题和 OpenClaw 无关。如果 curl 通但 OpenClaw 报这个错检查gateway.bind是不是设成了loopback之外的値有时候绑定地址和出站代理配置会冲突。reading choices。这个报错长这样TypeError: Cannot read properties of undefined (reading choices)它发生在响应解析阶段说明 Model Layer 拿到了响应但结构里没有choices字段。OpenClaw 默认按 OpenAI 协议解析如果你的 provider 返回的是 Anthropic 原生格式顶层是content数组就会读不到choices。解决办法是在 provider 配置里显式声明协议类型或者在models.providers.taotoken下加protocol: openai让 TaoToken 侧按 OpenAI 格式返回。这也是统一 Key 通道的好处协议转换在服务端做掉客户端只认一种格式。OAuth 相关报错。如果你在配置里用了 OAuth 模式的 provider可能会看到[oauth] token refresh failed: invalid_grant这类错误和 API Key 模式是两套逻辑。OAuth 的 token 有过期时间刷新失败通常是 refresh token 失效或时钟偏移。排查时先确认系统时间准确再检查 OAuth 配置里的clientId和clientSecret。如果你只是想快速跑通建议先用 API Key 模式把 OAuth 留到后面再调。Codex auth.json 相关。如果你同时用 Codex 类工具它的auth.json和 OpenClaw 的密钥快照是独立的。常见坑是两边 Key 不一致导致一个通一个不通。检查~/.codex/auth.json里的 Key 和 OpenClaw 环境变量里的 Key 是不是同一个。三件套Base URL、Key、Model ID在两边都要对齐。排查时有个通用技巧把OPENCLAW_LOG_LEVEL设成debug然后按日志顺序看。日志会按「配置加载 → 密钥快照 → 模型选择 → 请求组装 → 响应解析」的顺序打点哪一步断了日志就停在哪一步。这比盲猜快得多。6. 把统一通道接进你的工作流读源码的最终目的是能改、能扩。OpenClaw 的 provider 抽象给了你一个很干净的扩展点只要实现ModelProviderConfig对应的字段任何兼容协议的服务都能接进来。TaoToken 的统一 Key 通道在这里的价值是你不需要为每个模型单独配一套 Key 和 Base URL一个 provider 条目就能覆盖多个模型切换时只改agent.model里的模型 ID。如果你要长期跑编码类任务或 Agent 工作流建议把模型选择做成会话级可覆盖的。OpenClaw 的agents.profiles支持按 profile 定义不同的模型和参数你可以给「快速问答」和「深度编码」各配一个 profile用的时候切 profile 而不是改全局配置。这样多模型调用的链路你只维护一份 provider 配置切换成本降到最低。最后留一个实操建议每次改完 provider 配置先跑openclaw doctor再跑一次openclaw agent run的最小验证确认链路通了再连通道。这个习惯能帮你把「配置问题」和「通道问题」分开排查时少走很多弯路。源码里的handleGatewayRequest有完整的鉴权和限流逻辑读的时候可以对照你的实际请求日志看每一层做了什么、在哪一层被拦下都会很清楚。