真实系统里，模型调用一定会失败。
可能是：
429 rate limit 认证过期 provider 超时 模型临时不可用 上下文太大 网络波动 工具结果过长OpenClaw 要解决的不是“永不失败”，而是“失败后知道该不该重试、换 key、换模型，还是直接告诉用户”。
先说结论：Retry 和 Failover 不是一回事
可以这样区分：
Retry 同一个请求，短暂失败后再试一次 Auth profile rotation 同一个 provider，换另一个 key / OAuth profile Model failover 当前模型或 provider 不可用时，换 fallback model User-visible error 不应该自动绕过时，把结构化失败告诉用户不要把所有失败都暴力重试。
Retry：按请求重试，不按整条流程重跑
官方 retry policy 的目标包括：
按 HTTP request 重试 保持顺序 避免重复非幂等操作默认配置包括：
attempts: 3 maxDelayMs: 30000 jitter: 0.1这意味着 OpenClaw 不会随便重放已经完成的复合流程。否则可能出现重复发消息、重复上传、重复执行命令。
Provider SDK 和长 Retry-After
对 OpenAI、Anthropic 这类 SDK，OpenClaw 允许 SDK 处理普通短重试。
但如果 retry-after 很长，OpenClaw 会让 SDK 快速暴露错误，这样 model failover 可以接管，换 auth profile 或 fallback model。
这避免了用户等几分钟却没有任何进展。
Auth profile rotation：先换同 provider 的身份
OpenClaw 使用 auth profiles 管理 API key 和 OAuth token。
当某个 profile 遇到 rate limit、auth 或类似 cooldown 错误时，可以尝试同 provider 下的下一个 profile。
例如：
openai-codex:user@example.com ↓ 使用量限制 openai:api-key-backup这仍然可能保持同一个模型或 runtime，只是换了认证来源。
Model failover：再换模型候选
官方 model failover 文档说明，OpenClaw 先在当前 provider 内进行 auth profile rotation，再根据agents.defaults.model.fallbacks尝试下一个模型候选。
运行时会：
解析 session 当前模型状态 构建 candidate chain 尝试当前 provider 和 auth profiles 遇到可 failover 错误时进入下一个模型 把 auto fallback override 写入 session 失败时窄范围回滚 全部失败时抛出 FallbackSummaryError用户还会看到 fallback notice，例如从 primary 切到 fallback，或 primary 恢复后清除 fallback。
哪些选择不应该自动 fallback
如果用户显式/model选择了某个模型，这通常是 user session override。
官方文档说明，用户显式选择是严格选择。如果失败，OpenClaw 应报告失败，而不是悄悄用另一个模型回答。
原因很简单：
用户明确要求用 A 系统不应该无声换成 B常见误解
误解一：失败就应该一直重试
不对。非幂等流程不能随便重放。
误解二：Fallback 等于换更差模型
不一定。Fallback 只是下一个候选，可以是更快、更便宜、更稳，也可以是备用强模型。
误解三：用户指定模型也应该自动降级
不一定。显式用户选择通常应该严格执行。
最后总结
可靠性来自分层处理失败。
一句话总结：
短暂错误用 retry，身份问题用 profile rotation，模型不可用用 fallback，不该绕过的错误要透明报告。本节作业
- 设计一个 primary + two fallbacks 的模型链。
- 解释 retry 和 model failover 的区别。
- 思考哪些工具调用不能自动重试。
- 找一次 429 或 timeout，判断它应该 retry、rotate 还是 fallback。
下一节预告
下一节进入工具系统、Browser、Shell 与 Canvas：我们会把 OpenClaw 如何真正“动手做事”讲透。
参考资料
- OpenClaw Docs：Model failover
- OpenClaw Docs：Retry policy
- OpenClaw Docs：Model providers
- OpenClaw Docs：Models CLI
- OpenClaw Docs：FAQ: models and auth
原文链接：模型降级、重试和错误处理策略 | Harries Blog™
