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_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite创建后复制那串以sk-开头的字符串，先存到本地临时文件，别直接贴进聊天窗口。第二步是确认你要用的模型 ID。不同后端的模型命名不一样，OpenClaw 的models[].id必须和后端实际接受的 ID 一致，写错了会报model not found。可以在模型对话页先手动发一条消息，确认这个模型 ID 能正常返回：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite在对话页选好模型、发一句“你好”，能收到回复就说明这个 ID 可用。把返回正常的模型 ID 记下来，后面填进 settings。
这里有个容易忽略的点：OpenClaw 的 provider 配置里，baseUrl要填到版本路径，通常以/v1结尾，而models[].id只填模型名，不要把/v1拼进 ID。两者拼错位置是最常见的 404 来源。
关于 Key 的安全，给三条实操建议：不要把 Key 提交到 Git，settings 文件加进.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, indent=2, ensure_ascii=False) 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数组里加多个对象，每个对象一个id，alias 分别起名：
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 或 8080：
grep -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 的 provider，settings 里可能残留了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 完全一致，大小写敏感。用下面命令列出所有已注册 alias：
python3 -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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite需要新建或轮换 Key 时走 API Keys 页面：
https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite验证新模型是否可用，用模型对话页先手动发一条，确认返回正常再写进 settings，能省掉很多排查时间：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite最后提醒一句，settings 里的baseUrl和apiKey是整条链路的关键，改完一定用第 4 节的 curl 验证一次，看到choices才算真的通了。
