1. openclaw 接入第三方 API 时 models 字段到底该怎么写openclaw 是一个本地优先的 Agent 运行框架它把「模型提供方」和「Agent 使用哪个模型」拆成了两层配置。很多人装完之后卡在同一个地方聊天框里 agent 菜单看不到自己接的模型或者选上了却报 401。根因几乎都在~/.openclaw/openclaw.json的models字段没写对以及agents.defaults.model.primary的引用路径和 provider 名字对不上。这篇记录解决的就是这件事把 openclaw.json 里的 models 从默认状态改到 TaoToken 统一 Key/API 通道让 main agent 能正常列出并调用第三方模型。适合已经装好 openclaw、手里有一个可用 API Key、但被 JSON 嵌套结构绕晕的人。读完你能拿到一份可直接复制的配置片段知道每个字段为什么这么填并且能用一条命令验证模型列表真的返回了。先说清楚 openclaw 的模型解析逻辑不然后面改配置就是盲改。openclaw 读模型分三个层次第一层是models.providers这里定义「有哪些提供方、每个提供方的 baseUrl 和 apiKey 是什么、这个提供方下有哪些模型 id」。它相当于一张通讯录只负责「怎么连」。第二层是agents.defaults.models这里给模型起别名比如把myapi/claude-3-7-sonnet-20250219映射成显示名Claude。它负责「怎么显示」。第三层是agents.list[].model和agents.defaults.model.primary这里决定某个 agent 实际用哪个模型。它负责「用哪个」。三层里任何一层的 provider 名字不一致就会出现「菜单里看不到」或者「选了报错」。excerpt 里反复强调「几个 myapi 的地方名字要一样」说的就是这件事。我建议你统一用一个短名字比如taotoken全文所有引用都用它避免 myapi 这种占位名改漏。TaoToken 在这一层里的角色是它提供一个 OpenAI 兼容的 endpoint你不需要为每个模型单独配一套鉴权一个 Key 走通所有模型。baseUrl 填https://taotoken.net/apiapiKey 填你在控制台生成的 Keyapi 字段填openai-completions。注意 excerpt 里踩过的坑填openai-compatible不行必须是openai-completions这是 openclaw 内部识别的协议标识不是随便写的描述。模型 id 怎么填TaoToken 的模型列表里每个模型都有对应的 id你直接抄过来。比如claude-3-7-sonnet-20250219、gpt-5.1-codex这类。id 和 name 建议保持一致name 是显示用的id 是请求时真正发出去的写错 id 会返回 model not found。contextWindow 和 maxTokens 按模型实际能力填。Claude 3.7 Sonnet 这类填 200000 和 8192 是安全的。填大了不一定报错但可能触发上游截断填小了会提前 compaction影响长对话体验。还有一个容易忽略的点agents.defaults.models这个别名表里key 必须写成provider名/模型id的完整路径不能只写模型 id。excerpt 里写的是myapi/claude-3-7-sonnet-20250219这个斜杠前面的部分就是 provider 名。如果你 provider 叫 taotoken这里就得写taotoken/claude-3-7-sonnet-20250219两处必须字面一致。搞懂这三层后面改配置就是填空题。下一节先把 TaoToken 这边的准备工作做完拿到 baseUrl 和 Key再动 openclaw.json。2. TaoToken 前置准备拿到 baseUrl 与统一 Key在改 openclaw.json 之前先把 TaoToken 这边的两样东西准备好API 地址和 Key。这一步不做后面配置填什么都是空的。TaoToken 的 API 地址是固定的https://taotoken.net/api。注意这个地址不带任何路径后缀openclaw 会自己在后面拼/v1/chat/completions这类路径。如果你手贱加了/v1请求路径就会变成/v1/v1/chat/completions直接 404。这是我在别的工具上踩过的坑openclaw 同理。Key 的获取路径是控制台里的 API Keys 页面。登录后进控制台找到 API Keys新建一个。生成后立刻复制页面刷新就看不到了。Key 的格式一般是sk-开头的一长串。这个 Key 就是 openclaw.json 里apiKey字段要填的值。拿到 Key 之后先别急着改 openclaw用 curl 验证一下这个 Key 和地址是通的。这一步能帮你把「Key 本身有问题」和「openclaw 配置有问题」分开省得后面排障时两头猜。curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key正常返回是一个 JSON里面有data数组每个元素有id字段。你从这个列表里挑一个要用的模型 id抄下来等下填进 openclaw.json 的models[].id。如果这条 curl 返回 401说明 Key 错了或者没带上返回 404说明地址拼错了返回超时检查网络能不能到 taotoken.net。这一步过了再动 openclaw 配置问题范围就缩小到 openclaw 本身。关于模型选择TaoToken 的模型列表里既有 Claude 系列也有 GPT 系列还有 codex 这类偏编码的。openclaw 的 main agent 默认适合用通用对话能力强的模型Claude 3.7 Sonnet 是个稳妥选择。如果你主要拿 openclaw 做代码任务可以选 codex 类。选哪个不影响配置结构只影响id和name填什么。还有一点TaoToken 是统一 Key 通道意味着你不需要为 Claude 和 GPT 分别配两套 provider。一个 provider、一个 baseUrl、一个 apiKey下面挂多个模型 id 就行。这正好对应 openclaw 的models.providers.taotoken.models数组你可以在里面放多个模型然后在agents.defaults.models里给它们分别起别名。准备清单baseUrlhttps://taotoken.net/apiapiKey控制台生成的sk-开头字符串模型 id从/v1/models返回里挑比如claude-3-7-sonnet-20250219协议标识openai-completions不是 openai-compatible这四样齐了下一节直接改 openclaw.json。如果你还没生成 Key先去控制台建一个再回来。3. 可复制配置openclaw.json 的 models 字段完整写法这一节是核心。下面这份~/.openclaw/openclaw.json是完整可复制的你只需要替换三处apiKey、模型 id、以及如果你改了 provider 名的话全局替换taotoken。先看完整片段再逐项拆解。{ meta: { lastTouchedVersion: 2026.2.17, lastTouchedAt: 2026-02-19T07:16:21.127Z }, wizard: { lastRunAt: 2026-02-19T07:00:40.233Z, lastRunVersion: 2026.2.17, lastRunCommand: doctor, lastRunMode: local }, models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, api: openai-completions, models: [ { id: claude-3-7-sonnet-20250219, name: claude-3-7-sonnet-20250219, contextWindow: 200000, maxTokens: 8192 } ] } } }, agents: { defaults: { model: { primary: taotoken/claude-3-7-sonnet-20250219, fallbacks: [] }, models: { openai/gpt-5.1-codex: { alias: GPT }, taotoken/claude-3-7-sonnet-20250219: { alias: Claude } }, workspace: ~/.openclaw/workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } }, list: [ { id: main, name: main, workspace: ~/.openclaw/workspace, agentDir: ~/.openclaw/agents/main/agent, model: taotoken/claude-3-7-sonnet-20250219 } ] }, messages: { ackReactionScope: group-mentions }, commands: { native: auto, nativeSkills: auto }, hooks: { internal: { enabled: true, entries: { command-logger: { enabled: true }, session-memory: { enabled: true } } } }, gateway: { port: 18789, mode: local, bind: loopback, auth: { mode: token, token: XXXXXXXXX }, tailscale: { mode: off, resetOnExit: false }, nodes: { denyCommands: [ camera.snap, camera.clip, screen.record, calendar.add, contacts.add, reminders.add ] } } }逐项说明关键字段。models.providers.taotoken.baseUrl填https://taotoken.net/api不要加/v1不要加尾斜杠。openclaw 会自己拼路径。models.providers.taotoken.apiKey填你的sk-Key。这个字段是明文存储注意文件权限别提交到 git。models.providers.taotoken.api必须是openai-completions。这是 openclaw 内部协议枚举值填openai-compatible会解析失败表现为模型列表为空或请求直接报错。models.providers.taotoken.models[].id从 TaoToken/v1/models返回里抄的模型 id必须一字不差。models.providers.taotoken.models[].name显示名建议和 id 一致方便对照。contextWindow和maxTokens按模型能力填。Claude 3.7 Sonnet 填 200000 / 8192。agents.defaults.model.primary格式是provider名/模型id这里必须写taotoken/claude-3-7-sonnet-20250219。斜杠前是 provider 名斜杠后是模型 id两处都要和上面定义的一致。agents.defaults.models别名表。key 同样是provider名/模型id完整路径value 里的alias是聊天框里显示的名字。注意这里还保留了一个openai/gpt-5.1-codex的别名那是 openclaw 默认自带的你可以留着也可以删掉不影响 taotoken 的接入。agents.list[].modelmain agent 实际使用的模型同样写完整路径。这一处和agents.defaults.model.primary要一致否则会出现「默认模型是 A但 main agent 用 B」的错位。关于~/.openclaw/agents/main/agent/models.json和auth-profiles.jsonexcerpt 里提到第二步「不需要」第三步填鉴权信息。实测下来只要openclaw.json里的models.providers写对了agent 目录下的这两个文件不是必须的。openclaw 会从主配置读取 provider 信息。如果你之前在这两个文件里写过旧配置建议清空或删掉避免旧 provider 名残留导致冲突。这一步很多人忽略结果改了主配置还是不生效就是因为 agent 目录下有同名 provider 的旧定义。改完保存先别重启用下一节的命令验证 JSON 语法没问题再重启 openclaw。4. 验证请求确认模型列表与调用都正常返回配置改完先做语法校验再重启最后验证。顺序错了会浪费很多时间。第一步校验 JSON 语法。openclaw.json 是纯 JSON不能有注释不能有尾逗号。excerpt 里那些//注释是给人看的实际文件里不能有。python3 -m json.tool ~/.openclaw/openclaw.json /dev/null echo JSON OK输出JSON OK说明语法没问题。如果报错它会告诉你第几行有问题回去改。第二步重启 openclaw。重启方式取决于你的启动方式如果是前台运行CtrlC 再起如果是后台服务用对应的 restart 命令。openclaw restart或者直接杀掉进程重新起。重启后 openclaw 会重新读openclaw.json。第三步验证模型列表。openclaw 有没有正确加载 provider最直接的信号是看日志或者用 CLI 查。openclaw models list正常输出里应该能看到taotoken/claude-3-7-sonnet-20250219别名显示为Claude。如果列表里没有说明models.providers没被读到回去检查 JSON 层级。第四步发一次真实请求。这是最终验证确认 endpoint、Key、模型 id 三者都对。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-3-7-sonnet-20250219, messages: [{role: user, content: reply with ok}], max_tokens: 16 }返回里choices[0].message.content有内容说明通道通了。这一步和 openclaw 无关是验证 TaoToken 侧。如果这步就失败问题在 Key 或地址不在 openclaw 配置。第五步在 openclaw 聊天框里验证。打开 openclaw 的聊天界面找到 agent 菜单选 main看模型下拉里有没有Claude。选上发一句「你好」能正常回复就说明整条链路通了。如果聊天框里模型下拉是空的但openclaw models list有输出通常是前端缓存问题重启一次 openclaw 或者刷新界面。如果下拉里有但发消息报错看报错内容对照下一节的排查表。验证通过后你可以把agents.defaults.models里加上更多模型别名比如再挂一个 codex这样聊天框里可以随时切换。切换只改agents.list[].model或者用界面选择不用改 provider。一个实用技巧把agents.defaults.model.fallbacks填上一个备用模型路径比如[taotoken/gpt-5.1-codex]。主模型超时或限流时openclaw 会自动降级到备用模型长任务不容易断。这个字段 excerpt 里是空数组你可以按需填。5. 本篇常见报错排查401、local proxy failed、reading choices配置过程中会遇到的报错就那么几个对照着查能省很多时间。下面按报错原文分类。401 Unauthorized最常见。三种可能apiKey 填错、Key 前后有空格、Key 已失效。先检查openclaw.json里apiKey字段有没有多余空格或换行。然后用第 2 节的 curl 单独验证 Key。如果 curl 也 401去 TaoToken 控制台重新生成一个 Key。注意 Key 只在生成时显示一次复制时别漏字符。还有一种隐蔽情况agents/main/agent/auth-profiles.json里有旧的 apiKey覆盖了主配置。检查这个文件如果有models.providers字段删掉或清空让主配置生效。local proxy failed / connection refusedopenclaw 报这个通常是 baseUrl 写错。检查是不是写成了https://taotoken.net/api/v1多了/v1。或者写成了http://而不是https://。还有一种是把 baseUrl 写成了完整的 chat completions 路径openclaw 会再拼一次导致路径重复。# 正确 baseUrl: https://taotoken.net/api # 错误多了 /v1 baseUrl: https://taotoken.net/api/v1 # 错误写成了完整路径 baseUrl: https://taotoken.net/api/v1/chat/completionsreading choices / cannot read property choices of undefined这个报错说明请求发出去了但返回体不是预期的 OpenAI 格式。两种原因一是api字段填错填了openai-compatible而不是openai-completionsopenclaw 用错误的解析器去读响应。二是模型 id 不存在上游返回了错误 JSON没有choices字段。先确认api字段是openai-completions。再用 curl 单独请求那个模型 id看返回体里有没有choices。如果 curl 返回的是{error: ...}说明模型 id 错了回 TaoToken 模型列表核对。模型列表为空 / agent 菜单看不到模型三层引用不一致。检查models.providers的 key比如taotoken、agents.defaults.model.primary的前缀、agents.defaults.models的 key、agents.list[].model的前缀这四处必须字面完全一致。差一个字符就断链。另外检查agents.list[].id是不是main如果你改成了别的 id聊天框里对应的 agent 名字也变了。OAuth / token 相关报错openclaw 的 gateway 有自己的 auth token和模型 API Key 是两回事。gateway.auth.token是本地网关的鉴权models.providers.taotoken.apiKey是模型通道的鉴权。别把这两个搞混。如果报的是 gateway 相关检查gateway.auth.mode和token如果报的是模型相关检查 provider 的 apiKey。改了配置不生效两个原因没重启或者 agent 目录下有旧配置覆盖。先重启。还不行就检查~/.openclaw/agents/main/agent/models.json和auth-profiles.json把里面和 provider 相关的旧定义清掉。openclaw 的配置优先级是 agent 目录 主配置旧文件不清会一直覆盖。排查顺序建议先 curl 验证 TaoToken 通道再openclaw models list验证加载最后聊天框验证调用。每一步过了再走下一步问题定位会快很多。6. 把 openclaw 的模型通道固定下来配置改通之后建议做两件收尾的事。第一把openclaw.json备份一份改坏了能快速回滚。这个文件里存了明文 Key备份时注意别放到公开仓库。cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak第二如果你要在多台机器上用同一套模型通道把 provider 配置抽出来做成模板只替换 apiKey。TaoToken 的统一 Key 通道在这里的优势是一个 baseUrl 加一个 Key所有模型都能走不用为每个模型维护一套鉴权。后续要加新模型只需要在models.providers.taotoken.models数组里追加一项再在agents.defaults.models里加个别名重启即可。不用动 baseUrl 和 apiKey。如果你想把 openclaw 接到更多模型或者做长期编码任务可以看 TaoToken 的 Coding Plan它针对 Agent 类长任务做了通道优化。模型对话入口可以用来快速验证某个模型 id 是否可用接入文档里有各协议的 endpoint 说明。API Keys 页面用来管理你的 Key控制台里能看到调用情况。配置这件事改对一次之后就是复制粘贴。关键是记住三层引用必须一致以及api字段是openai-completions不是openai-compatible。这两个点踩过去后面就顺了。
openclaw配置第三方api记录：把openclaw.json的models改到TaoToken
1. openclaw 接入第三方 API 时 models 字段到底该怎么写openclaw 是一个本地优先的 Agent 运行框架它把「模型提供方」和「Agent 使用哪个模型」拆成了两层配置。很多人装完之后卡在同一个地方聊天框里 agent 菜单看不到自己接的模型或者选上了却报 401。根因几乎都在~/.openclaw/openclaw.json的models字段没写对以及agents.defaults.model.primary的引用路径和 provider 名字对不上。这篇记录解决的就是这件事把 openclaw.json 里的 models 从默认状态改到 TaoToken 统一 Key/API 通道让 main agent 能正常列出并调用第三方模型。适合已经装好 openclaw、手里有一个可用 API Key、但被 JSON 嵌套结构绕晕的人。读完你能拿到一份可直接复制的配置片段知道每个字段为什么这么填并且能用一条命令验证模型列表真的返回了。先说清楚 openclaw 的模型解析逻辑不然后面改配置就是盲改。openclaw 读模型分三个层次第一层是models.providers这里定义「有哪些提供方、每个提供方的 baseUrl 和 apiKey 是什么、这个提供方下有哪些模型 id」。它相当于一张通讯录只负责「怎么连」。第二层是agents.defaults.models这里给模型起别名比如把myapi/claude-3-7-sonnet-20250219映射成显示名Claude。它负责「怎么显示」。第三层是agents.list[].model和agents.defaults.model.primary这里决定某个 agent 实际用哪个模型。它负责「用哪个」。三层里任何一层的 provider 名字不一致就会出现「菜单里看不到」或者「选了报错」。excerpt 里反复强调「几个 myapi 的地方名字要一样」说的就是这件事。我建议你统一用一个短名字比如taotoken全文所有引用都用它避免 myapi 这种占位名改漏。TaoToken 在这一层里的角色是它提供一个 OpenAI 兼容的 endpoint你不需要为每个模型单独配一套鉴权一个 Key 走通所有模型。baseUrl 填https://taotoken.net/apiapiKey 填你在控制台生成的 Keyapi 字段填openai-completions。注意 excerpt 里踩过的坑填openai-compatible不行必须是openai-completions这是 openclaw 内部识别的协议标识不是随便写的描述。模型 id 怎么填TaoToken 的模型列表里每个模型都有对应的 id你直接抄过来。比如claude-3-7-sonnet-20250219、gpt-5.1-codex这类。id 和 name 建议保持一致name 是显示用的id 是请求时真正发出去的写错 id 会返回 model not found。contextWindow 和 maxTokens 按模型实际能力填。Claude 3.7 Sonnet 这类填 200000 和 8192 是安全的。填大了不一定报错但可能触发上游截断填小了会提前 compaction影响长对话体验。还有一个容易忽略的点agents.defaults.models这个别名表里key 必须写成provider名/模型id的完整路径不能只写模型 id。excerpt 里写的是myapi/claude-3-7-sonnet-20250219这个斜杠前面的部分就是 provider 名。如果你 provider 叫 taotoken这里就得写taotoken/claude-3-7-sonnet-20250219两处必须字面一致。搞懂这三层后面改配置就是填空题。下一节先把 TaoToken 这边的准备工作做完拿到 baseUrl 和 Key再动 openclaw.json。2. TaoToken 前置准备拿到 baseUrl 与统一 Key在改 openclaw.json 之前先把 TaoToken 这边的两样东西准备好API 地址和 Key。这一步不做后面配置填什么都是空的。TaoToken 的 API 地址是固定的https://taotoken.net/api。注意这个地址不带任何路径后缀openclaw 会自己在后面拼/v1/chat/completions这类路径。如果你手贱加了/v1请求路径就会变成/v1/v1/chat/completions直接 404。这是我在别的工具上踩过的坑openclaw 同理。Key 的获取路径是控制台里的 API Keys 页面。登录后进控制台找到 API Keys新建一个。生成后立刻复制页面刷新就看不到了。Key 的格式一般是sk-开头的一长串。这个 Key 就是 openclaw.json 里apiKey字段要填的值。拿到 Key 之后先别急着改 openclaw用 curl 验证一下这个 Key 和地址是通的。这一步能帮你把「Key 本身有问题」和「openclaw 配置有问题」分开省得后面排障时两头猜。curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key正常返回是一个 JSON里面有data数组每个元素有id字段。你从这个列表里挑一个要用的模型 id抄下来等下填进 openclaw.json 的models[].id。如果这条 curl 返回 401说明 Key 错了或者没带上返回 404说明地址拼错了返回超时检查网络能不能到 taotoken.net。这一步过了再动 openclaw 配置问题范围就缩小到 openclaw 本身。关于模型选择TaoToken 的模型列表里既有 Claude 系列也有 GPT 系列还有 codex 这类偏编码的。openclaw 的 main agent 默认适合用通用对话能力强的模型Claude 3.7 Sonnet 是个稳妥选择。如果你主要拿 openclaw 做代码任务可以选 codex 类。选哪个不影响配置结构只影响id和name填什么。还有一点TaoToken 是统一 Key 通道意味着你不需要为 Claude 和 GPT 分别配两套 provider。一个 provider、一个 baseUrl、一个 apiKey下面挂多个模型 id 就行。这正好对应 openclaw 的models.providers.taotoken.models数组你可以在里面放多个模型然后在agents.defaults.models里给它们分别起别名。准备清单baseUrlhttps://taotoken.net/apiapiKey控制台生成的sk-开头字符串模型 id从/v1/models返回里挑比如claude-3-7-sonnet-20250219协议标识openai-completions不是 openai-compatible这四样齐了下一节直接改 openclaw.json。如果你还没生成 Key先去控制台建一个再回来。3. 可复制配置openclaw.json 的 models 字段完整写法这一节是核心。下面这份~/.openclaw/openclaw.json是完整可复制的你只需要替换三处apiKey、模型 id、以及如果你改了 provider 名的话全局替换taotoken。先看完整片段再逐项拆解。{ meta: { lastTouchedVersion: 2026.2.17, lastTouchedAt: 2026-02-19T07:16:21.127Z }, wizard: { lastRunAt: 2026-02-19T07:00:40.233Z, lastRunVersion: 2026.2.17, lastRunCommand: doctor, lastRunMode: local }, models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, api: openai-completions, models: [ { id: claude-3-7-sonnet-20250219, name: claude-3-7-sonnet-20250219, contextWindow: 200000, maxTokens: 8192 } ] } } }, agents: { defaults: { model: { primary: taotoken/claude-3-7-sonnet-20250219, fallbacks: [] }, models: { openai/gpt-5.1-codex: { alias: GPT }, taotoken/claude-3-7-sonnet-20250219: { alias: Claude } }, workspace: ~/.openclaw/workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } }, list: [ { id: main, name: main, workspace: ~/.openclaw/workspace, agentDir: ~/.openclaw/agents/main/agent, model: taotoken/claude-3-7-sonnet-20250219 } ] }, messages: { ackReactionScope: group-mentions }, commands: { native: auto, nativeSkills: auto }, hooks: { internal: { enabled: true, entries: { command-logger: { enabled: true }, session-memory: { enabled: true } } } }, gateway: { port: 18789, mode: local, bind: loopback, auth: { mode: token, token: XXXXXXXXX }, tailscale: { mode: off, resetOnExit: false }, nodes: { denyCommands: [ camera.snap, camera.clip, screen.record, calendar.add, contacts.add, reminders.add ] } } }逐项说明关键字段。models.providers.taotoken.baseUrl填https://taotoken.net/api不要加/v1不要加尾斜杠。openclaw 会自己拼路径。models.providers.taotoken.apiKey填你的sk-Key。这个字段是明文存储注意文件权限别提交到 git。models.providers.taotoken.api必须是openai-completions。这是 openclaw 内部协议枚举值填openai-compatible会解析失败表现为模型列表为空或请求直接报错。models.providers.taotoken.models[].id从 TaoToken/v1/models返回里抄的模型 id必须一字不差。models.providers.taotoken.models[].name显示名建议和 id 一致方便对照。contextWindow和maxTokens按模型能力填。Claude 3.7 Sonnet 填 200000 / 8192。agents.defaults.model.primary格式是provider名/模型id这里必须写taotoken/claude-3-7-sonnet-20250219。斜杠前是 provider 名斜杠后是模型 id两处都要和上面定义的一致。agents.defaults.models别名表。key 同样是provider名/模型id完整路径value 里的alias是聊天框里显示的名字。注意这里还保留了一个openai/gpt-5.1-codex的别名那是 openclaw 默认自带的你可以留着也可以删掉不影响 taotoken 的接入。agents.list[].modelmain agent 实际使用的模型同样写完整路径。这一处和agents.defaults.model.primary要一致否则会出现「默认模型是 A但 main agent 用 B」的错位。关于~/.openclaw/agents/main/agent/models.json和auth-profiles.jsonexcerpt 里提到第二步「不需要」第三步填鉴权信息。实测下来只要openclaw.json里的models.providers写对了agent 目录下的这两个文件不是必须的。openclaw 会从主配置读取 provider 信息。如果你之前在这两个文件里写过旧配置建议清空或删掉避免旧 provider 名残留导致冲突。这一步很多人忽略结果改了主配置还是不生效就是因为 agent 目录下有同名 provider 的旧定义。改完保存先别重启用下一节的命令验证 JSON 语法没问题再重启 openclaw。4. 验证请求确认模型列表与调用都正常返回配置改完先做语法校验再重启最后验证。顺序错了会浪费很多时间。第一步校验 JSON 语法。openclaw.json 是纯 JSON不能有注释不能有尾逗号。excerpt 里那些//注释是给人看的实际文件里不能有。python3 -m json.tool ~/.openclaw/openclaw.json /dev/null echo JSON OK输出JSON OK说明语法没问题。如果报错它会告诉你第几行有问题回去改。第二步重启 openclaw。重启方式取决于你的启动方式如果是前台运行CtrlC 再起如果是后台服务用对应的 restart 命令。openclaw restart或者直接杀掉进程重新起。重启后 openclaw 会重新读openclaw.json。第三步验证模型列表。openclaw 有没有正确加载 provider最直接的信号是看日志或者用 CLI 查。openclaw models list正常输出里应该能看到taotoken/claude-3-7-sonnet-20250219别名显示为Claude。如果列表里没有说明models.providers没被读到回去检查 JSON 层级。第四步发一次真实请求。这是最终验证确认 endpoint、Key、模型 id 三者都对。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-3-7-sonnet-20250219, messages: [{role: user, content: reply with ok}], max_tokens: 16 }返回里choices[0].message.content有内容说明通道通了。这一步和 openclaw 无关是验证 TaoToken 侧。如果这步就失败问题在 Key 或地址不在 openclaw 配置。第五步在 openclaw 聊天框里验证。打开 openclaw 的聊天界面找到 agent 菜单选 main看模型下拉里有没有Claude。选上发一句「你好」能正常回复就说明整条链路通了。如果聊天框里模型下拉是空的但openclaw models list有输出通常是前端缓存问题重启一次 openclaw 或者刷新界面。如果下拉里有但发消息报错看报错内容对照下一节的排查表。验证通过后你可以把agents.defaults.models里加上更多模型别名比如再挂一个 codex这样聊天框里可以随时切换。切换只改agents.list[].model或者用界面选择不用改 provider。一个实用技巧把agents.defaults.model.fallbacks填上一个备用模型路径比如[taotoken/gpt-5.1-codex]。主模型超时或限流时openclaw 会自动降级到备用模型长任务不容易断。这个字段 excerpt 里是空数组你可以按需填。5. 本篇常见报错排查401、local proxy failed、reading choices配置过程中会遇到的报错就那么几个对照着查能省很多时间。下面按报错原文分类。401 Unauthorized最常见。三种可能apiKey 填错、Key 前后有空格、Key 已失效。先检查openclaw.json里apiKey字段有没有多余空格或换行。然后用第 2 节的 curl 单独验证 Key。如果 curl 也 401去 TaoToken 控制台重新生成一个 Key。注意 Key 只在生成时显示一次复制时别漏字符。还有一种隐蔽情况agents/main/agent/auth-profiles.json里有旧的 apiKey覆盖了主配置。检查这个文件如果有models.providers字段删掉或清空让主配置生效。local proxy failed / connection refusedopenclaw 报这个通常是 baseUrl 写错。检查是不是写成了https://taotoken.net/api/v1多了/v1。或者写成了http://而不是https://。还有一种是把 baseUrl 写成了完整的 chat completions 路径openclaw 会再拼一次导致路径重复。# 正确 baseUrl: https://taotoken.net/api # 错误多了 /v1 baseUrl: https://taotoken.net/api/v1 # 错误写成了完整路径 baseUrl: https://taotoken.net/api/v1/chat/completionsreading choices / cannot read property choices of undefined这个报错说明请求发出去了但返回体不是预期的 OpenAI 格式。两种原因一是api字段填错填了openai-compatible而不是openai-completionsopenclaw 用错误的解析器去读响应。二是模型 id 不存在上游返回了错误 JSON没有choices字段。先确认api字段是openai-completions。再用 curl 单独请求那个模型 id看返回体里有没有choices。如果 curl 返回的是{error: ...}说明模型 id 错了回 TaoToken 模型列表核对。模型列表为空 / agent 菜单看不到模型三层引用不一致。检查models.providers的 key比如taotoken、agents.defaults.model.primary的前缀、agents.defaults.models的 key、agents.list[].model的前缀这四处必须字面完全一致。差一个字符就断链。另外检查agents.list[].id是不是main如果你改成了别的 id聊天框里对应的 agent 名字也变了。OAuth / token 相关报错openclaw 的 gateway 有自己的 auth token和模型 API Key 是两回事。gateway.auth.token是本地网关的鉴权models.providers.taotoken.apiKey是模型通道的鉴权。别把这两个搞混。如果报的是 gateway 相关检查gateway.auth.mode和token如果报的是模型相关检查 provider 的 apiKey。改了配置不生效两个原因没重启或者 agent 目录下有旧配置覆盖。先重启。还不行就检查~/.openclaw/agents/main/agent/models.json和auth-profiles.json把里面和 provider 相关的旧定义清掉。openclaw 的配置优先级是 agent 目录 主配置旧文件不清会一直覆盖。排查顺序建议先 curl 验证 TaoToken 通道再openclaw models list验证加载最后聊天框验证调用。每一步过了再走下一步问题定位会快很多。6. 把 openclaw 的模型通道固定下来配置改通之后建议做两件收尾的事。第一把openclaw.json备份一份改坏了能快速回滚。这个文件里存了明文 Key备份时注意别放到公开仓库。cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak第二如果你要在多台机器上用同一套模型通道把 provider 配置抽出来做成模板只替换 apiKey。TaoToken 的统一 Key 通道在这里的优势是一个 baseUrl 加一个 Key所有模型都能走不用为每个模型维护一套鉴权。后续要加新模型只需要在models.providers.taotoken.models数组里追加一项再在agents.defaults.models里加个别名重启即可。不用动 baseUrl 和 apiKey。如果你想把 openclaw 接到更多模型或者做长期编码任务可以看 TaoToken 的 Coding Plan它针对 Agent 类长任务做了通道优化。模型对话入口可以用来快速验证某个模型 id 是否可用接入文档里有各协议的 endpoint 说明。API Keys 页面用来管理你的 Key控制台里能看到调用情况。配置这件事改对一次之后就是复制粘贴。关键是记住三层引用必须一致以及api字段是openai-completions不是openai-compatible。这两个点踩过去后面就顺了。