OpenClaw 如何配置模型回退 Model failover让主模型失败时自动切换【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw如果你的 OpenClaw 主模型在限流、计费中断或供应商故障时直接报错这篇文章说明如何通过agents.defaults.model.fallbacks配置模型回退model failover让失败时自动切换到备用模型并给出验证配置是否生效的方法。回退发生在 OpenClaw 运行回复的过程中不需要在会话里做任何额外操作。回退发生前 OpenClaw 会先做什么OpenClaw 处理失败分两阶段先在当前 provider 内做auth profile 轮换再切到agents.defaults.model.fallbacks中的下一个模型。在轮换或切模型之前runner 会先做有界的同模型恢复bounded same-model recovery限流最多10 次总尝试其他瞬态故障保留 8 次重试、90 秒重试窗口等待采用抖动指数退避上限 30 秒provider 的retry-after/retry-after-ms提示仍作为最小等待。恢复过程延续现有 transcript保留已完成的输出不需要额外配置。详见 重试策略。两条决定“会不会回退”的规则在配置前值得先明确回退执行是 turn-local 的回退模型只对当前这一轮生效下一轮从你选择的主模型重新开始。OpenClaw 每 5 分钟探测一次原先的主模型来源恢复后清除 auto 回退状态/new、/reset、sessions.reset会立即清除。选择来源决定严格性配置默认值agents.defaults.model.primary和 cron 任务的payload.model/--model使用配置的回退链但用户通过/model、模型选择器、session_status(model...)、sessions.patch在会话内选定的模型是精确严格的——失败前没有产生回复时OpenClaw 直接报告失败不会用不相关的备用模型回答。代理级agents.entries.*.model同样是严格的除非该 agent 的模型对象里自带fallbacksfallbacks: []显式声明严格非空列表则启用回退。配置回退链回退链管理的是全局默认值有两条等效路径。用 CLI 管理回退链fallbacks子命令直接维护agents.defaults.model.fallbacks顺序即尝试顺序openclaw models fallbacks add minimax/MiniMax-M2.7 openclaw models fallbacks list openclaw models fallbacks remove minimax/MiniMax-M2.7 openclaw models fallbacks clearadd/remove接受provider/model或已配置的别名。openclaw models image-fallbacks list|add|remove|clear是并行的agents.defaults.imageModel.fallbacks列表子命令形态相同用于视觉模型场景。provider/model必须能解析省略 provider 时 OpenClaw 按别名、唯一已配置 provider 匹配、配置默认 provider 的顺序解析建议始终写全前缀。模型的确切写法可以用只读命令确认openclaw models list --provider providerId主模型本身通过openclaw models set写入agents.defaults.model.primary。该命令要求 provider 已由已安装插件声明或配置在models.providers下未知 provider 会以非零退出且不改动配置。直接编辑配置配置是~/.openclaw/openclaw.jsonJSON5。文档给出的对象形式示例文档示例// ~/.openclaw/openclaw.json { agents: { defaults: { model: { primary: anthropic/claude-opus-4-6, fallbacks: [minimax/MiniMax-M2.7], }, }, }, }model接受字符串只设主模型或{ primary, fallbacks }对象主模型 有序回退列表。Gateway 监视该文件并自动应用变更无需手动重启。完整键位参考 Gateway configuration。验证回退配置是否生效CLI 侧。openclaw models fallbacks list应列出你添加的备用模型openclaw models status显示解析出的默认模型、回退链和各路由的认证概览处于冷却中的 profile 会出现在Unavailable auth profiles段并附带原因和恢复动作。openclaw models fallbacks list openclaw models status会话内。/status显示选中的模型当回退状态与选中模型不同时还会显示当前生效的回退模型和原因。/model status则是更详细的视图每个 provider 的认证候选、如有provider 端点baseUrl与api模式。注意models status不检查具体聊天会话的模型覆盖会话内状态要在该会话里查。运行中的提示。限流重试期间Control UI 会显示一条瞬态Retrying… n/10指示。在非群组/非频道的会话里回合切到自动选定的回退模型时会收到操作通知文档示例↪️ Model Fallback: fallback (selected primary; reason)主模型恢复、回合重新落回选中主模型时↪️ Model Fallback cleared: primary (was fallback)这两条是操作消息而非助手内容每次状态变化只发一次连续同对的回合不会重复发送群组和频道会话保留相同的回退状态但不发这些通知。回退不生效的常见边界会话内选定的模型如上文所述是精确严格的回退链对它不生效失败会直接报出来。上下文溢出不触发回退request_too_large、input token count exceeds the maximum number of input tokens、input too long for the model、ollama error: context length exceeded这类错误留在压缩/重试逻辑内不会前进到下一个候选。计费失败走更长的禁用窗口“insufficient credits” 类失败会把该凭据标记为禁用 10 分钟并轮换到下一个可用 profile临时性的用量窗口限制如weekly usage limit exhausted则归为rate_limit走短冷却路径。冷却是递增的普通非计费、非 auth-permanent冷却随近期错误次数升级——第 1 次失败 30 秒、第 2 次 1 分钟、第 3 次起 5 分钟封顶计数器在失败窗口过后重置。格式类错误通常不轮换invalid-request 错误重试同样负载仍会失败OpenClaw 会直接上报而不是轮换 auth profile。可选跳过近期失败的备用模型默认情况下每个新回合都会重试所有配置的回退候选包括刚以auth或auth_permanent失败的备用模型。启用以下环境变量可抑制重复的认证类失败文档示例值OPENCLAW_FALLBACK_SKIP_TTL_MS60000启用后非主回退候选发生认证类失败会记录一个进程内、会话级的跳过标记0或未设置表示禁用该缓存正值被限制在 1 秒到 10 分钟之间。主候选永远不会被跳过显式用户选定的模型仍会暴露真实的认证错误缓存随 Gateway 重启清除。可选同一 provider 内先轮换账号再切模型如果同一个 provider 配了多个 auth profile例如 OpenAI 的 Codex 订阅 API-key 备份失败时 OpenClaw 会先在 provider 内轮换 profile而不是立刻切到下一个模型。对外暴露的轮换顺序用auth.order配置文档示例openai:userexample.com需替换为你自己的 profile id{ auth: { order: { openai: [openai:userexample.com, openai:api-key-backup], }, }, }订阅触发 Codex 用量上限时OpenClaw 会记录 Codex 给出的确切重置时间尝试下一个有序 profile并保持在 Codex harness 内运行重置时间过后订阅 profile 重新可用。轮换顺序、冷却细节和 profile 健康状态见 Model failover、Models CLI 与 Model selection。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/9 19:07:57 · 阅读 1.2k OpenClaw 如何配置模型回退 Model failover，让主模型失败时自动切换？
OpenClaw 如何配置模型回退 Model failover让主模型失败时自动切换【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw如果你的 OpenClaw 主模型在限流、计费中断或供应商故障时直接报错这篇文章说明如何通过agents.defaults.model.fallbacks配置模型回退model failover让失败时自动切换到备用模型并给出验证配置是否生效的方法。回退发生在 OpenClaw 运行回复的过程中不需要在会话里做任何额外操作。回退发生前 OpenClaw 会先做什么OpenClaw 处理失败分两阶段先在当前 provider 内做auth profile 轮换再切到agents.defaults.model.fallbacks中的下一个模型。在轮换或切模型之前runner 会先做有界的同模型恢复bounded same-model recovery限流最多10 次总尝试其他瞬态故障保留 8 次重试、90 秒重试窗口等待采用抖动指数退避上限 30 秒provider 的retry-after/retry-after-ms提示仍作为最小等待。恢复过程延续现有 transcript保留已完成的输出不需要额外配置。详见 重试策略。两条决定“会不会回退”的规则在配置前值得先明确回退执行是 turn-local 的回退模型只对当前这一轮生效下一轮从你选择的主模型重新开始。OpenClaw 每 5 分钟探测一次原先的主模型来源恢复后清除 auto 回退状态/new、/reset、sessions.reset会立即清除。选择来源决定严格性配置默认值agents.defaults.model.primary和 cron 任务的payload.model/--model使用配置的回退链但用户通过/model、模型选择器、session_status(model...)、sessions.patch在会话内选定的模型是精确严格的——失败前没有产生回复时OpenClaw 直接报告失败不会用不相关的备用模型回答。代理级agents.entries.*.model同样是严格的除非该 agent 的模型对象里自带fallbacksfallbacks: []显式声明严格非空列表则启用回退。配置回退链回退链管理的是全局默认值有两条等效路径。用 CLI 管理回退链fallbacks子命令直接维护agents.defaults.model.fallbacks顺序即尝试顺序openclaw models fallbacks add minimax/MiniMax-M2.7 openclaw models fallbacks list openclaw models fallbacks remove minimax/MiniMax-M2.7 openclaw models fallbacks clearadd/remove接受provider/model或已配置的别名。openclaw models image-fallbacks list|add|remove|clear是并行的agents.defaults.imageModel.fallbacks列表子命令形态相同用于视觉模型场景。provider/model必须能解析省略 provider 时 OpenClaw 按别名、唯一已配置 provider 匹配、配置默认 provider 的顺序解析建议始终写全前缀。模型的确切写法可以用只读命令确认openclaw models list --provider providerId主模型本身通过openclaw models set写入agents.defaults.model.primary。该命令要求 provider 已由已安装插件声明或配置在models.providers下未知 provider 会以非零退出且不改动配置。直接编辑配置配置是~/.openclaw/openclaw.jsonJSON5。文档给出的对象形式示例文档示例// ~/.openclaw/openclaw.json { agents: { defaults: { model: { primary: anthropic/claude-opus-4-6, fallbacks: [minimax/MiniMax-M2.7], }, }, }, }model接受字符串只设主模型或{ primary, fallbacks }对象主模型 有序回退列表。Gateway 监视该文件并自动应用变更无需手动重启。完整键位参考 Gateway configuration。验证回退配置是否生效CLI 侧。openclaw models fallbacks list应列出你添加的备用模型openclaw models status显示解析出的默认模型、回退链和各路由的认证概览处于冷却中的 profile 会出现在Unavailable auth profiles段并附带原因和恢复动作。openclaw models fallbacks list openclaw models status会话内。/status显示选中的模型当回退状态与选中模型不同时还会显示当前生效的回退模型和原因。/model status则是更详细的视图每个 provider 的认证候选、如有provider 端点baseUrl与api模式。注意models status不检查具体聊天会话的模型覆盖会话内状态要在该会话里查。运行中的提示。限流重试期间Control UI 会显示一条瞬态Retrying… n/10指示。在非群组/非频道的会话里回合切到自动选定的回退模型时会收到操作通知文档示例↪️ Model Fallback: fallback (selected primary; reason)主模型恢复、回合重新落回选中主模型时↪️ Model Fallback cleared: primary (was fallback)这两条是操作消息而非助手内容每次状态变化只发一次连续同对的回合不会重复发送群组和频道会话保留相同的回退状态但不发这些通知。回退不生效的常见边界会话内选定的模型如上文所述是精确严格的回退链对它不生效失败会直接报出来。上下文溢出不触发回退request_too_large、input token count exceeds the maximum number of input tokens、input too long for the model、ollama error: context length exceeded这类错误留在压缩/重试逻辑内不会前进到下一个候选。计费失败走更长的禁用窗口“insufficient credits” 类失败会把该凭据标记为禁用 10 分钟并轮换到下一个可用 profile临时性的用量窗口限制如weekly usage limit exhausted则归为rate_limit走短冷却路径。冷却是递增的普通非计费、非 auth-permanent冷却随近期错误次数升级——第 1 次失败 30 秒、第 2 次 1 分钟、第 3 次起 5 分钟封顶计数器在失败窗口过后重置。格式类错误通常不轮换invalid-request 错误重试同样负载仍会失败OpenClaw 会直接上报而不是轮换 auth profile。可选跳过近期失败的备用模型默认情况下每个新回合都会重试所有配置的回退候选包括刚以auth或auth_permanent失败的备用模型。启用以下环境变量可抑制重复的认证类失败文档示例值OPENCLAW_FALLBACK_SKIP_TTL_MS60000启用后非主回退候选发生认证类失败会记录一个进程内、会话级的跳过标记0或未设置表示禁用该缓存正值被限制在 1 秒到 10 分钟之间。主候选永远不会被跳过显式用户选定的模型仍会暴露真实的认证错误缓存随 Gateway 重启清除。可选同一 provider 内先轮换账号再切模型如果同一个 provider 配了多个 auth profile例如 OpenAI 的 Codex 订阅 API-key 备份失败时 OpenClaw 会先在 provider 内轮换 profile而不是立刻切到下一个模型。对外暴露的轮换顺序用auth.order配置文档示例openai:userexample.com需替换为你自己的 profile id{ auth: { order: { openai: [openai:userexample.com, openai:api-key-backup], }, }, }订阅触发 Codex 用量上限时OpenClaw 会记录 Codex 给出的确切重置时间尝试下一个有序 profile并保持在 Codex harness 内运行重置时间过后订阅 profile 重新可用。轮换顺序、冷却细节和 profile 健康状态见 Model failover、Models CLI 与 Model selection。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考