1. OpenClaw 接入免费大模型时最容易卡在哪settings 改完不生效的排查思路OpenClaw 是一个本地优先的 AI 编码助手网关它把模型调用统一收拢到~/.openclaw/openclaw.json这份 settings 里再通过 gateway 进程对外提供接口。很多人第一次给它接免费大模型卡点不在“找不到免费额度”而在 settings 改完之后/model切过去没反应、请求报 401、或者日志里出现local proxy failed。这篇就围绕 OpenClaw 配置免费大模型这条主线把 settings 里 Base URL 和 API Key 的可复制改法讲清楚并附一次真实对话请求验证连通。先说清楚适合谁你本地已经装好 OpenClaw能跑openclaw gateway restart想用一个统一 Key 调用多家模型而不是每换一个模型就重装一遍环境。OpenClaw 本身不生产模型它只负责把请求转发到你配置的 provider所以“免费”这件事取决于你接的后端。把多家后端统一到同一个入口好处是切换模型只改一行 alias不用动业务代码。我试过最省事的做法是让所有 provider 都走 OpenAI 兼容协议。OpenClaw 的 settings 里每个 provider 都有api字段填openai-completions就能复用同一套请求格式。这样你接 A 家还是 B 家差别只在baseUrl、apiKey和models列表。理解这一点后面所有配置都是同一个模板换参数。需要提前说明的是本文不涉及任何网络访问工具只讨论在合规网络环境下如何填写 settings。如果你所在环境访问某些域名不稳定优先选择国内可直连的模型服务这也是后面配置里会给出的组合建议。真正动手前先确认三件事OpenClaw 版本支持models.providers结构你有可用的 API Key你知道 settings 文件的绝对路径。用下面命令确认路径和版本openclaw --version ls -la ~/.openclaw/openclaw.json如果openclaw.json不存在说明 gateway 还没初始化过先跑一次openclaw gateway start让它生成默认配置再回来改。改之前务必备份这是踩过坑之后养成的习惯cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak备份的意义在于settings 是 JSON少一个逗号整个 gateway 就起不来有备份能秒回滚。下面进入正题先讲统一入口的准备再给可复制配置。2. TaoToken 作为统一入口的前置准备一个 Key 打通多家模型TaoToken 在这里扮演的角色是统一入口你用一份 Key就能在 OpenClaw 里调用多家模型不用为每个后端单独维护一套鉴权。对 OpenClaw 这种把 provider 写进 settings 的工具来说统一入口能显著减少配置量——原来要维护三份apiKey现在只需要在 provider 里填同一个 Key模型 ID 按需切换。前置准备分两步。第一步是拿到 Key进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后复制那串以sk-开头的字符串先存到本地临时文件别直接贴进聊天窗口。第二步是确认你要用的模型 ID。不同后端的模型命名不一样OpenClaw 的models[].id必须和后端实际接受的 ID 一致写错了会报model not found。可以在模型对话页先手动发一条消息确认这个模型 ID 能正常返回https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite在对话页选好模型、发一句“你好”能收到回复就说明这个 ID 可用。把返回正常的模型 ID 记下来后面填进 settings。这里有个容易忽略的点OpenClaw 的 provider 配置里baseUrl要填到版本路径通常以/v1结尾而models[].id只填模型名不要把/v1拼进 ID。两者拼错位置是最常见的 404 来源。关于 Key 的安全给三条实操建议不要把 Key 提交到 Gitsettings 文件加进.gitignore不要在公开聊天里贴 Key定期在控制台检查使用情况不用的 Key 及时删除。这些不是形式主义Key 泄露后别人消耗的是你的额度。准备好 Key 和模型 ID 之后就可以进入配置环节。下面给的 JSON 片段可以直接复制路径和字段名与 OpenClaw 的 settings 结构保持一致你只需要替换 Key 和模型 ID 两处。3. 可复制配置把 settings 里的 Base URL 与 API Key 改到 TaoToken这一节是全文核心给出可直接复制的 JSON 片段。OpenClaw 的 settings 结构是models.providers.providerName每个 provider 下有baseUrl、apiKey、api、models四个关键字段。我们用 Python 脚本读取、修改、写回避免手改 JSON 出错。先看单 provider 的最小可用配置。把下面脚本里的sk-你的Key和模型 ID 换成你自己的import json path /home/你的用户名/.openclaw/openclaw.json with open(path) as f: config json.load(f) config[models][providers][taotoken] { baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的Key, api: openai-completions, models: [ { id: 你的模型ID, name: 统一入口模型, reasoning: False, input: [text], cost: {input: 0, output: 0, cacheRead: 0, cacheWrite: 0}, contextWindow: 131072, maxTokens: 8192 } ] } config[agents][defaults][models][taotoken/你的模型ID] { alias: free } with open(path, w) as f: json.dump(config, f, indent2, ensure_asciiFalse) print(配置写入成功)几个字段逐个说明。baseUrl填https://taotoken.net/api/v1注意结尾的/v1这是 OpenAI 兼容协议的版本路径。apiKey填你创建的那串 Key。api固定openai-completions表示走 OpenAI 兼容格式。models[].id填你在对话页验证过的模型 ID。contextWindow和maxTokens按模型实际能力填填大了后端会截断填小了浪费上下文。agents.defaults.models里的 key 是providerName/modelId的组合value 里的alias是你在对话里用/model free调用的短名。alias 建议用有意义的名字比如按用途叫chat、code别用a、b这种过两天自己都忘了的。如果你要接多家模型就在models数组里加多个对象每个对象一个idalias 分别起名config[models][providers][taotoken][models] [ {id: 模型A, name: 日常对话, reasoning: False, input: [text], cost: {input: 0, output: 0, cacheRead: 0, cacheWrite: 0}, contextWindow: 131072, maxTokens: 8192}, {id: 模型B, name: 代码补全, reasoning: False, input: [text], cost: {input: 0, output: 0, cacheRead: 0, cacheWrite: 0}, contextWindow: 128000, maxTokens: 4096} ] config[agents][defaults][models][taotoken/模型A] {alias: chat} config[agents][defaults][models][taotoken/模型B] {alias: code}写回之后重启 gateway 让配置生效openclaw gateway restart重启后看状态确认进程正常openclaw gateway status如果状态是 running说明 settings 语法没问题。如果起不来八成是 JSON 格式错误用下面命令校验python3 -m json.tool ~/.openclaw/openclaw.json /dev/null echo JSON 合法到这里配置部分完成。下一节用一次真实请求验证连通确认模型返回正常而不是只看进程状态。4. 验证请求与成功结果一次对话确认模型返回正常配置写完不代表能用必须发一次真实请求。OpenClaw 提供命令行对话入口也可以直接调 gateway 的 HTTP 接口。先用最直观的方式启动对话并切换模型openclaw chat进入交互后输入/model free如果 alias 配置正确会提示已切换到对应模型。然后发一句测试用一句话说明你是什么模型正常返回会是一段自然语言说明请求链路通了。如果返回报错先别急着改配置看具体错误码下一节会逐条对照。除了交互式也可以直接用 curl 打 gateway 接口这种方式更适合脚本化验证。先确认 gateway 监听端口默认在 settings 的gateway段里通常是 3000 或 8080grep -A3 gateway ~/.openclaw/openclaw.json假设端口是 3000发一条 OpenAI 兼容格式的请求curl -s http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的本地网关Token \ -d { model: taotoken/你的模型ID, messages: [{role: user, content: 你好请回复 OK}] }成功返回的 JSON 里会有choices数组第一项的message.content就是模型回复。看到这个结构说明从 OpenClaw 到后端整条链路都通了。如果返回里choices为空或者报reading choices相关错误说明后端返回格式和预期不符检查api字段是否填了openai-completions。验证时建议同时看 gateway 日志能定位问题出在哪一层journalctl --user -u openclaw-gateway -n 50 --no-pager日志里如果出现local proxy failed通常是 gateway 到后端的连接问题出现401是 Key 或鉴权头问题出现model not found是模型 ID 写错。这三种是最高频的下一节展开。一次成功的验证应该满足三个条件进程 running、对话能切换模型、请求返回带choices。三个都过才算真正配置完成。只满足前两个不算因为进程起来但请求失败的情况很常见。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 逐条对照这一节按真实报错逐条给排查路径。每个错误都给出触发原因和验证命令照着做基本能定位。401 Unauthorized。最常见原因是 Key 填错或带了多余空格。检查 settings 里的apiKey字段python3 -c import json;print(repr(json.load(open(/home/你的用户名/.openclaw/openclaw.json))[models][providers][taotoken][apiKey]))用repr打印能看出有没有隐藏空格或换行。如果 Key 正确还报 401确认baseUrl没有多写或少写/v1路径不对会被后端当成未授权。local proxy failed。这个错误说明 gateway 尝试转发请求但连接失败。先确认baseUrl域名能解析curl -sI https://taotoken.net/api/v1能返回 HTTP 状态码说明网络可达。如果这里就失败检查本机 DNS 和网络配置。注意不要使用任何非合规的网络访问方式优先确认基础网络是否正常。reading choices 相关错误。典型报错是cannot read property choices of undefined或reading choices。这说明后端返回的不是 OpenAI 兼容格式而 OpenClaw 按兼容格式去解析。检查 provider 的api字段是否为openai-completions以及baseUrl是否指向兼容接口。有些后端有原生接口和兼容接口两个地址填错就会出这个错。OAuth 相关报错。如果你之前配过需要 OAuth 的 providersettings 里可能残留了oauth字段和新的apiKey冲突。检查 provider 段里有没有多余的鉴权字段python3 -c import json;print(json.load(open(/home/你的用户名/.openclaw/openclaw.json))[models][providers][taotoken].keys())正常应该只有baseUrl、apiKey、api、models。多出来的字段删掉再重启。配置不生效。改完 settings 没重启 gateway或者重启了但进程读的是旧配置。确认重启命令执行成功并看进程启动时间openclaw gateway restart sleep 2 openclaw gateway status如果状态显示 running 但行为没变检查是不是有多个 gateway 实例在跑旧实例占着端口。模型切换后无响应。alias 配了但/model切不过去检查agents.defaults.models的 key 是否和 provider 名、模型 ID 完全一致大小写敏感。用下面命令列出所有已注册 aliaspython3 -c import json;print(json.load(open(/home/你的用户名/.openclaw/openclaw.json))[agents][defaults][models])对照输出确认 alias 存在且拼写正确。排查完记得每次改完 settings 都重启并验证一次不要攒着一起改否则出问题不知道是哪次改动引入的。6. 长期使用建议与接入文档入口配置跑通之后日常使用还有几个能省事的点。alias 按用途命名比如chat给日常对话、code给代码补全切换时不用记模型 ID。settings 定期备份改之前先cp一份出问题能秒回滚。Key 定期在控制台检查使用情况不用的及时删。如果你要把这套配置用到长期编码或 Agent 场景建议把常用模型固定成默认 alias减少每次手动切换。接入过程中遇到鉴权或路径问题优先查接入文档里面按 provider 给了字段说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite需要新建或轮换 Key 时走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite验证新模型是否可用用模型对话页先手动发一条确认返回正常再写进 settings能省掉很多排查时间https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite最后提醒一句settings 里的baseUrl和apiKey是整条链路的关键改完一定用第 4 节的 curl 验证一次看到choices才算真的通了。