1. OpenClaw 接入免费 AI 大模型为什么 settings 改不对就一直报错OpenClaw 是一个本地优先的 AI Agent 运行框架它能通过provider/model的引用格式调用不同来源的大模型适合已经在本地跑着 Ollama、LM Studio、vLLM 或任意 OpenAI 兼容服务的开发者。很多人第一次配 OpenClaw 的免费 AI 大模型时卡点并不在“有没有模型”而在“settings 里到底该改哪一层”。OpenClaw 的模型配置分散在agents.defaults.model、models.providers和models.mode三个位置改错一个字段表现就是openclaw models list看不到模型或者对话请求直接 401。我见过最常见的误区是把 Ollama 的http://127.0.0.1:11434直接填进baseUrl漏掉/v1后缀。OpenClaw 走的是 OpenAI 兼容协议api字段声明为openai-completions时请求路径会拼成{baseUrl}/chat/completions所以 baseUrl 必须以/v1结尾。另一个高频坑是models.mode没设成merge导致自定义 provider 把内置 provider 列表整个覆盖掉Gemini、Groq 这些内置项全消失。这篇教程面向的场景很具体你本地已经有 Ollama 或一个 OpenAI 兼容服务想通过改openclaw.json里的 settings 完成模型切换不改任何业务代码。我会给出可直接复制的 JSON 片段、一次真实的对话请求验证以及 401、429、reading choices这类报错的对照排查。如果你手上还没有可用的 API KeyTaoToken 的 API Keys 页面可以先生成一个用于验证链路接入文档里有完整的 Base URL 说明。需要先明确一个概念OpenClaw 里的“免费模型”分两种。一种是真免费模型跑在你自己机器上只花电费和显存Ollama、LM Studio、llama.cpp 都属于这类另一种是托管服务的免费额度有速率限制和配额波动。两种的 settings 写法不同混着配就会出现“昨天能用今天 429”的情况。下面按本地优先、托管兜底的顺序展开。2. TaoToken 与 OpenClaw 的前置准备Base URL、Key 和 Model ID 三件套在动 settings 之前先把三件套凑齐Base URL、API Key、Model ID。这三样在 OpenClaw 里分别对应models.providers.name.baseUrl、apiKey和models[].id。任何接入问题先回头确认这三样是否自洽能省掉一半排查时间。本地 Ollama 的三件套是Base URL 为http://127.0.0.1:11434/v1API Key 随便填一个非空字符串Ollama 默认不校验但 OpenClaw 的 provider 结构要求该字段存在Model ID 用ollama list输出的名字比如llama3.3。注意 Model ID 不要带ollama/前缀前缀只在agents.defaults.model.primary里出现。如果你用的是托管服务做兜底TaoToken 的接入方式与 OpenAI 兼容协议一致。Base URL 填https://taotoken.net/apiAPI Key 在控制台的 API Keys 页面生成Model ID 填服务端支持的模型标识。这里要提醒一句Base URL 不要带 UTM 参数OpenClaw 会把它当作路径的一部分拼进请求导致 404。官网地址带?utm_source...那是给浏览器看的配置里必须用干净的 API 域名。环境变量的管理方式直接影响 Key 的安全性。推荐把 Key 写进 shell 的环境变量文件settings 里用${VAR_NAME}引用。OpenClaw 支持这种占位符展开这样openclaw.json可以进 gitKey 不会泄露。systemd 用户服务的话用EnvironmentFile指向一个chmod 600的文件。# ~/.config/openclaw/env 权限设为 600 export TAOTOKEN_API_KEYsk-你的key export OLLAMA_API_KEYollama-localchmod 600 ~/.config/openclaw/env前置检查还有一步容易被跳过确认本地服务真的在监听。Ollama 用curl http://127.0.0.1:11434/v1/models应该返回模型列表 JSON如果返回 connection refused说明服务没起settings 改得再对也没用。LM Studio 默认端口是 1234vLLM 常见是 8000端口填错是最低级的错误但发生频率不低。关于 provider 命名OpenClaw 允许你自定义比如叫taotoken、local-ollama、lmstudio。命名只影响provider/model引用里的前缀不影响实际请求。建议用能一眼看出用途的名字别用provider1这种后面配 fallback 时会后悔。3. 可复制配置把 settings 改到 TaoToken 的完整 JSON 片段OpenClaw 的主配置文件默认在~/.config/openclaw/openclaw.json也可以用OPENCLAW_CONFIG环境变量指定路径。下面这份配置同时挂了本地 Ollama 和 TaoToken 两个 provider主模型走本地fallback 走 TaoTokenmodels.mode设为merge保证内置 provider 不被覆盖。{ agents: { defaults: { model: { primary: local-ollama/llama3.3, fallbacks: [ taotoken/gpt-4o-mini ] }, models: { local-ollama/llama3.3: { alias: LocalLlama }, taotoken/gpt-4o-mini: { alias: TaoMini } } } }, models: { mode: merge, providers: { local-ollama: { baseUrl: http://127.0.0.1:11434/v1, apiKey: ${OLLAMA_API_KEY}, api: openai-completions, models: [ { id: llama3.3, name: Llama 3.3 Local, contextWindow: 131072, maxTokens: 8192, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } } ] }, taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, api: openai-completions, models: [ { id: gpt-4o-mini, name: TaoToken GPT-4o mini, contextWindow: 128000, maxTokens: 16384, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } } ] } } } }几个字段值得单独说。models.mode必须是merge它的作用是让自定义 provider 与内置 provider 合并而不是替换如果你写replace或者不写内置的 Gemini、Groq 会消失openclaw models list里只剩你手写的两个。api字段固定为openai-completions这是 OpenClaw 对 OpenAI 兼容协议的路由标识Ollama、LM Studio、vLLM、TaoToken 都用这个值。cost字段全填 0 是本地模型的惯例写法它不影响请求但能让 OpenClaw 的成本统计面板显示为零避免误报。托管 provider 如果也想让统计归零同样可以填 0但真实计费以服务端为准这里只是本地展示。agents.defaults.models这个映射表是白名单。只有列在这里的provider/model才允许被选中这能防止不同环境下的模型选择漂移。如果你不写这个映射OpenClaw 会放开所有已注册模型团队协作时容易出现“我这边跑的是 A 模型你那边跑的是 B 模型”的诡异现象。改完配置后用openclaw models list确认两个 provider 都出现。如果只看到一个检查 JSON 是否合法jq . ~/.config/openclaw/openclaw.json能快速定位语法错误。JSON 不支持尾逗号这是手写配置最常见的失败原因。4. 验证请求一次对话确认 OpenClaw 与 TaoToken 连通配置写完不等于接通必须发一次真实请求。OpenClaw 提供了命令行入口最直接的方式是用openclaw models set切换默认模型然后跑一次对话。openclaw models list openclaw models set taotoken/gpt-4o-mini openclaw chat 用一句话说明什么是 OpenAI 兼容接口openclaw models list的输出应该包含local-ollama/llama3.3和taotoken/gpt-4o-mini两行。如果 TaoToken 那行缺失说明 provider 块没被解析回到上一节检查models.providers的层级。openclaw models set会写入当前默认模型不需要手动改 JSON。openclaw chat发出请求后正常返回是一段模型生成的文本。如果返回里出现reading choices这类报错说明响应体不是标准的 OpenAI 格式通常是 baseUrl 少了/v1或者服务端返回了 HTML 错误页。用 curl 直接打一次同样的端点能快速区分是 OpenClaw 的问题还是服务端的问题。curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], max_tokens: 16 } | jq .choices[0].message.contentcurl 能返回内容而 OpenClaw 不能问题就在 settingscurl 也失败问题在 Key 或网络。这个二分法能省掉大量猜测。本地 Ollama 同理把 URL 换成http://127.0.0.1:11434/v1/chat/completionsKey 换成任意非空值即可。验证 fallback 是否生效可以临时把主模型的 baseUrl 改成一个不存在的端口再发一次请求。OpenClaw 会在主模型连接失败后自动切到fallbacks列表里的下一个模型。日志里会打印 provider 切换记录openclaw chat --verbose能看到细节。这个测试做完记得把 baseUrl 改回来。流式输出是另一个验证点。部分 Ollama 构建版本在流式模式下会泄露工具标记表现为输出里混入tool_call之类的原始字符串。如果遇到把该 provider 的流式关掉OpenClaw 会退化为一次性返回。流式是可选优化不是连通性的必要条件。5. 常见报错排查401、429、local proxy failed 与 OAuth 失效401 和 403 是接入阶段最高频的错误。OpenClaw 的报错信息通常只写unauthorized不告诉你哪个 provider 挂了。排查顺序是先确认apiKey占位符展开后非空echo ${TAOTOKEN_API_KEY}应该有值再确认 Key 没有多余空格或换行从控制台复制时容易带上尾部空白最后确认 Key 对应的服务端确实启用了该模型。多个 auth profile 轮换时一个失效的 profile 会污染整个 provider检查 auth profile 的顺序和冷却状态。429 是免费额度的常态不是 bug。OpenClaw 的处理策略是先在同一个 provider 内轮换 auth profile再按fallbacks列表切换模型。要让这个机制真正生效fallbacks里至少放一个不同 provider 的模型。长文档摘要这类高并发工作流把并发数降下来比加 fallback 更有效。免费套餐的速率限制是设计约束不是可以绕过的障碍。local proxy failed通常出现在本地服务没起、端口被占或防火墙拦截时。先curl本地端点确认服务活着再检查 OpenClaw 进程是否有权限访问该端口。容器里跑 OpenClaw 的话127.0.0.1指向容器自身而不是宿主机需要换成host.docker.internal或宿主机的实际 IP。这个坑在 Docker 环境里非常常见。reading choices是响应结构不匹配。除了 baseUrl 缺/v1还有一种情况是服务端返回了 200 但 body 是空或 HTML。加--verbose看原始响应或者用上面的 curl 命令对比。如果 curl 返回正常而 OpenClaw 报这个错检查api字段是否写成了openai而不是openai-completions后者才是 OpenClaw 识别的路由标识。OAuth 类 provider 的“登录消失”问题根源在 auth profile 轮换。OpenClaw 为缓存友好性会给每个会话固定一个 profile多个 profile 存在时按配置顺序或轮询规则切换。如果你希望行为可预测把 profile 顺序固定下来别依赖轮询。Qwen 这类走 OAuth 设备码流程的 providertoken 过期后需要重新openclaw models auth login不会自动续期。报错最可能原因快速验证401 unauthorizedKey 为空/错误/多空格echo ${TAOTOKEN_API_KEY}429 rate limit免费额度触顶看服务端配额页加 fallbacklocal proxy failed本地服务未起/端口错curl本地端点reading choicesbaseUrl 缺 /v1 或 api 字段错curl 对比原始响应OAuth 登录消失auth profile 轮换固定 profile 顺序排查时保持一个习惯每次只改一个字段改完立刻openclaw models list加一次openclaw chat。批量改配置再一起测出错时无法定位是哪个字段的问题。6. 不改业务代码完成模型切换Coding Plan 与长期接入建议OpenClaw 的模型切换之所以能做到不改业务代码核心在于provider/model这层引用是配置驱动的。业务侧只认agents.defaults.model.primary具体指向哪个 provider 由 settings 决定。这意味着你可以今天用本地 Ollama 跑日常任务明天把 primary 换成 TaoToken 的托管模型处理复杂推理业务代码一行不动。长期跑 Agent 类工作负载建议把 Coding Plan 纳入考虑。它的定位是给持续编码和 Agent 场景提供稳定的模型调用额度比按次计费的免费额度更适合高频调用。配置方式与本文的 TaoToken provider 完全一致只是 Model ID 换成 Coding Plan 支持的模型标识。切换时只改models.providers.taotoken.models[].id和agents.defaults.model.primary两处。本地优先加托管兜底的组合实测下来成本最可控。本地模型处理高频、低复杂度的调用托管模型只在本地繁忙或任务超纲时介入。fallbacks列表就是这个策略的落地方式。要注意 fallback 不是无限重试OpenClaw 会跟踪冷却时间连续失败的 provider 会被暂时跳过避免雪崩。安全设置上几条底线不能破Key 永远走环境变量不进 git网关不要裸暴露公网用 token 或反向代理挡一层工具权限按最小必要授予免费模型一样能触发危险工具调用。这些和模型是否收费无关是 Agent 框架的通用要求。如果你在验证阶段想先跑通链路再决定长期方案模型对话页面可以直接试一次请求确认 Base URL 和 Key 可用后再写进 settings。接入文档里有各语言的调用示例对照着改openclaw.json的 provider 块即可。整套流程走下来从改 settings 到openclaw chat返回内容熟练后十分钟内能完成。
