夜雨聆风不绑定任何一家
前十二篇里，我们每次提到模型调用都用了"配置的模型"这个措辞，刻意避免说"Claude"或"GPT"。这不是写作习惯，而是在暗示 OpenClaw 的一个核心设计立场：不绑定任何一家模型厂商。
Claude、GPT、Gemini、DeepSeek、本地 Ollama 模型、通过 OpenRouter 接入的数百个第三方模型——从 OpenClaw 的视角看，它们都是可以互换的执行后端。今天用 Claude Sonnet 处理日常对话，明天某个 API 出现故障，自动切到 GPT 继续工作，用户感知到的只是轻微的延迟，而不是助手停摆。
实现这个"任意模型、无缝切换"能力的，是 OpenClaw 的两层 Failover 架构：认证 Profile 轮换（Provider 内部，API Key 之间的切换）和模型降级链（跨 Provider，不同模型之间的切换）。
这两层叠加在一起，构成了一个在生产环境能真正可靠运行的多模型路由系统。
模型引用格式：provider/model-id
OpenClaw 用一套统一的引用格式标识所有模型，格式是 provider/model-id，比如 anthropic/claude-sonnet-4-5、openai/gpt-5.4、openrouter/moonshotai/kimi-k2。
解析规则很简单：按第一个 / 分割，左边是 Provider 标识，右边是模型 ID。有一个例外：OpenRouter 的模型 ID 本身包含 /（比如 moonshotai/kimi-k2），所以使用 OpenRouter 时必须带上前缀 openrouter/，否则 OpenClaw 无法正确区分 Provider 和模型 ID。
模型引用在加载时会被规范化为小写，Provider 别名也会被展开：z.ai/* 自动规范化为 zai/*，方便你在配置里用简短的别名书写，系统内部统一处理。
双层配置系统：openclaw.json 与 models.json
OpenClaw 对模型的配置采用两层结构，这个设计初看有点绕，但有其合理性。
第一层是用户可见的 openclaw.json，里面的 agents.defaults.model 和 agents.defaults.imageModel 字段是你直接编辑的配置。
第二层是 Agent 运行时使用的 models.json，位于每个 Agent 的状态目录里：
~/.openclaw/agents/<agentId>/agent/models.json这个文件由 src/agents/models-config.ts 里的 ensureOpenClawModelsJson() 函数自动生成和维护，用户通常不需要直接编辑它。它把你在 openclaw.json 里的显式配置、系统内置的 Provider 定义、以及自动发现的本地服务（比如正在运行的 Ollama 实例）三部分合并起来，形成 Agent 运行时能直接消费的完整模型清单。
合并时有一条优先级规则值得注意：如果 models.json 里某个 Provider 已经有非空的 baseUrl，它比 openclaw.json 里的设置优先级高，不会被覆盖。这是为了保护用户手动调整过的本地 Provider 端点，避免每次配置重载都把它重置掉。
Ollama 的本地模型发现在每次 Gateway 启动时自动触发：models-config.providers.ts 里的代码向 http://localhost:11434/api/tags 发一个探针请求，如果 Ollama 正在运行，把返回的模型列表全部注册进来。你不需要手动配置每一个本地模型，只管在 Ollama 里 pull 就行，Gateway 下次启动会自动发现。
五层模型选择优先级
运行时选择"这次用哪个模型"，经过五层优先级覆盖，从高到低依次是：
第一层：/model 指令覆盖。用户在对话里发送 /model openai/gpt-5.4，这个选择被存入 Session 状态，在整个 Session 存续期间固定使用这个模型，不受其他覆盖影响。/model default 清除覆盖，恢复到配置默认值。
第二层：Hooks 覆盖。workspace/hooks/ 目录下的 Hook 脚本可以在 Agent 执行开始前动态修改模型选择，比如"如果消息包含代码块，切换到更强的 Sonnet 模型"。
第三层：Bindings 路由。bindings 配置把特定的通道/群组对话绑定到特定的 Agent 配置，而每个 Agent 配置有自己的 model 设置。比如把 Discord 某个服务器的消息路由到 work Agent，work Agent 使用不同于默认 Agent 的模型。
第四层：per-agent 配置。agents.list[].model.primary 覆盖全局 agents.defaults.model.primary，用于给特定 Agent 配置不同的默认模型。
第五层：全局默认。agents.defaults.model.primary 是所有 Agent 的基准模型。
这五层最终会给每次执行确定一个目标模型，然后进入认证 Profile 选择和 Failover 流程。
认证 Profile：密钥的身份容器
每个 Provider 的认证凭证存在 auth-profiles.json 里，位于 Agent 状态目录：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json一个 Profile 是一条认证凭证的完整描述，支持两种类型。
API Key 类型的 Profile 格式是 provider:default（单个 Key）或 provider:backup（多个 Key 时命名区分），内容直接存 API Key 字符串，或者用 SecretRef 格式引用环境变量和文件。
OAuth 类型的 Profile 格式是 provider:<email>，比如 openai-codex:[email protected]，内容是 {provider, access, refresh, expires, email} 结构。OAuth Token 有过期时间，resolveApiKeyForProfile() 在每次使用前检查有效期，快到期时自动用 refresh token 刷新，整个过程对上层透明。
同一个 Provider 可以有多个 Profile，比如你同时持有 Anthropic API Key 和 Anthropic OAuth（通过 claude setup-token 得到的订阅令牌），这两个可以并列存在，OpenClaw 在其中一个失败时自动切换到另一个。
openclaw.json 里的 auth.profiles 和 auth.order 字段是元数据和路由声明，不存储密钥本身，密钥只在 auth-profiles.json 里。这个分离确保配置文件可以安全版本管理，而密钥文件通过 .gitignore 隔离。
Profile 轮换：第一层 Failover
当一次模型调用失败，OpenClaw 首先尝试在同一个 Provider 内部轮换 Profile，而不是立刻跳到备用模型。
轮换顺序不是随机的，而是按两个维度排序的结果。主键是 Profile 类型：OAuth 类型的 Profile 排在 API Key 之前，因为 OAuth 订阅通常有独立的速率限制配额，和 API Key 的配额互相隔离。次键是上次使用时间：usageStats.lastUsed 最旧的 Profile 排在前面，实现负载均衡式的分散使用。
冷却期内或被禁用的 Profile 移到列表末尾，按冷却到期时间排序，最早恢复的排在最前。这意味着即便所有 Profile 都在冷却，系统也不会无限等待，而是选择最快恢复的那一个尝试。
触发轮换的失败类型分为两类，处理方式不同。速率限制和超时是短期故障，对应 Profile 进入短期冷却（默认 1 分钟），冷却期结束后恢复正常。计费失败（"insufficient credits"、"credit balance too low"）是持续性故障，对应 Profile 被标记为 disabled，触发更长的退避时间：第一次失败 5 小时，每次翻倍，上限 24 小时，24 小时无失败后计数器重置。
Session 粘性是一个重要的性能优化：一旦某次执行成功确定了使用的 Profile，这个 Profile 会被固定（pinned）到当前 Session，后续请求都优先使用它。原因是部分 Provider（尤其是 Anthropic）对 System Prompt 的缓存和 KV 缓存是按 API Key 维度维护的，每次切换 Key 都会导致缓存冷启动，带来额外的延迟和成本。Session 粘性让缓存尽可能保持热状态。
粘性 Profile 失败时行为取决于它是如何被固定的：用户手动通过 /model ...@<profileId> 固定的 Profile 失败后，直接跳到模型降级链，不再尝试同一 Provider 的其他 Profile；系统自动固定的 Profile 失败后，先尝试同一 Provider 的其他 Profile，全部失败再触发模型降级。
模型降级链：第二层 Failover
当某个 Provider 的所有 Profile 都耗尽后，OpenClaw 启动第二层 Failover，按顺序尝试 agents.defaults.model.fallbacks 列表里的备用模型。
配置看起来很直观：
{agents: {defaults: {model: {primary: "anthropic/claude-sonnet-4-5",fallbacks: ["anthropic/claude-opus-4-6", // 同 Provider，更强的模型"openai/gpt-5.2", // 跨 Provider"openrouter/google/gemini-2.5-pro", // 通过 OpenRouter],},},},}
降级链里的每个模型都会走一遍 Profile 选择和轮换逻辑。如果 openai/gpt-5.2 的所有 API Key 也都在冷却，继续往下试 gemini-2.5-pro，以此类推。
降级事件会通过 Gateway 的事件系统广播给所有连接的客户端，Web UI 和 TUI 会展示一条提示："已从 claude-sonnet-4-5 降级到 gpt-5.2（原因：速率限制）"，让用户知道当前用的是哪个模型，不是默默地换掉。
降级链有一个重要的终点设计：即便执行开始时已经有了一个通过 Hook 或 Binding 注入的模型覆盖，降级链走完之后，最终兜底的永远是 agents.defaults.model.primary，而不是降级链的最后一个模型。这防止了一次临时的模型覆盖在 Failover 后意外把 Agent 的默认模型永久改变。
图像模型与图像生成模型的独立配置
OpenClaw 把三类模型分开配置，各自有独立的 primary 和 fallbacks：
agents.defaults.model 是主对话模型，处理所有普通的文字交互。
agents.defaults.imageModel 是图像理解模型，专门用于处理包含图片的消息。当主对话模型本身支持视觉输入时，imageModel 不会被单独调用；只有当主模型不支持视觉，但消息里包含图片时，才切换到 imageModel 处理图像内容，结果作为文字描述注入主对话流程。
agents.defaults.imageGenerationModel 是图像生成模型，被 image_generate 工具（如果安装了对应插件）使用。这三条配置线互相独立，你可以用 Claude 对话、用 GPT-4o 理解图片、用 DALL-E 生成图片，三个 Provider 并行工作。
/model 指令：对话中的即时切换
用户在任何对话里都可以用 /model 指令操作当前 Session 的模型选择。
/model list # 展示所有可用模型，带编号/model 3 # 按编号选择第三个/model anthropic/claude-opus-4-6 # 按完整引用选择/model Opus # 按别名选择（需要在 agents.defaults.models 里配置别名）/model default # 恢复到配置里的默认模型/model status # 展示当前模型选择和认证状态/model ...@backup # 固定使用名为 backup 的认证 Profile
如果配置了 agents.defaults.models 白名单，/model list 只展示白名单里的模型，/model 切换到白名单外的模型会被拒绝并返回"Model is not allowed"错误。白名单模式适合多用户部署场景，防止某些用户把 Agent 切换到成本更高的模型。
/model status 是调试认证问题的最有用命令：它展示当前 Session 固定的 Profile、该 Profile 的冷却状态、同一 Provider 下还有哪些可用 Profile，以及配置的降级链里每个模型的当前认证状态。当你遇到"不知道为什么在用备用模型"时，这是第一个查看的地方。
openclaw models scan：发现 OpenRouter 的免费模型
openclaw models scan 是一个非常实用的工具，它通过 OpenRouter API 扫描当前可用的免费和低成本模型目录，可选地对每个候选模型做探针测试（发一次真实的工具调用请求），检测它是否实际支持工具调用和图像输入——因为模型 API 文档里声称支持的能力，和真实调用时能不能正常运转，并不总是一致的。
扫描结果按四个维度排序：工具调用支持、图像支持、上下文窗口大小、上次性能测试得分。在终端交互模式下，你可以直接从扫描结果里选择降级链里的备用模型，确认后自动写入配置。
探针测试需要 OpenRouter API Key，无 Key 时可以加 --no-probe 只列出候选不做测试。并发测试数量和超时时间都可以配置，避免一次扫描消耗太多 API 配额。
自定义 Provider：把本地 LLM 服务接入路由
models.providers 配置允许把任何兼容 OpenAI API 的服务接入 OpenClaw 的模型路由系统：
{models: {providers: {"local-llm": {baseUrl: "http://127.0.0.1:1234/v1",apiKey: "lmstudio",api: "openai-responses", // 或 "openai-chat"},"vllm": {baseUrl: "http://gpu-server:8000/v1",apiKey: { env: "VLLM_API_KEY" },api: "openai-chat",},},},}
这条配置被写入 models.json 后，你就可以在 agents.defaults.model.primary 里用 local-llm/llama-3.3-70b 这样的格式引用它，它会进入完整的 Profile 轮换和降级链体系，与云端模型在同一套路由逻辑下工作。
api 字段区分两种 API 格式：openai-chat 对应旧的 /v1/chat/completions 接口，openai-responses 对应较新的 /v1/responses 接口（更好地支持工具调用结果的引用追踪）。如果不确定，优先选 openai-chat，兼容性更广。
本地模型的一个关键限制是工具调用支持：并非所有本地模型都能可靠地输出符合格式要求的工具调用 JSON。建议先用 openclaw models scan --probe 验证，再把它放入降级链。
openclaw models status --check：自动化监控
openclaw models status --check 以非零退出码报告认证状态，适合集成进监控脚本和 CI/CD 流水线：
退出码 0：所有已配置的 Provider 都有有效的认证 退出码 1：有 Provider 认证缺失或已过期 退出码 2：有 OAuth Token 即将过期（默认提前 24 小时警告）
把这条命令加进 cron 任务，OAuth Token 快到期时会提前告警，避免某天 Token 过期后助手悄悄切到备用模型运行好几天你才发现：
0 9 * * * openclaw models status --check || \openclaw message send --channel telegram \"⚠️ 模型认证即将过期，请检查 /model status"
小结
OpenClaw 的模型路由系统是一个两层嵌套的 Failover 架构。第一层在 Provider 内部，按 OAuth 优先、最久未用优先的顺序轮换 API Key，配合速率限制的短期冷却和计费失败的长期退避；第二层跨 Provider，按配置顺序逐一尝试备用模型，每个备用模型又独立走一遍第一层。Session 粘性在保持 Provider 缓存热状态的同时，不牺牲跨 Profile 的容错能力。
这套架构的核心价值是：让"模型不可用"从一个让助手停摆的灾难，变成一个用户几乎感知不到的瞬间自愈事件。
下一篇，我们进入扩展系统——插件是如何被发现、加载，以及如何向 Gateway 注入新能力的。
源码参考：src/agents/models-config.ts · src/agents/auth-profiles.ts · src/agents/model-selection.ts · src/auto-reply/fallback-state.ts · docs/concepts/model-failover.md基于 commit bf6ec64f 版本
