openclaw支持主模型异常时自动切换备用模型，提供yaml静态配置、json多实例配置、命令行验证、熔断参数控制及环境变量覆盖五种fallback实现方式。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您正在运行OpenClaw，但主模型在调用过程中出现超时、HTTP 5xx错误或连续三次内容校验失败，则服务将中断。以下是实现主模型不可用时自动切换的多种配置与操作方法：

一、YAML配置文件中声明fallback序列

该方法通过静态定义主备模型优先级，使OpenClaw在检测到主模型异常时按顺序尝试备用项。系统仅对已预拉取且存在于白名单中的模型执行切换，未部署模型会被自动跳过。

1、打开OpenClaw配置文件，路径通常为~/.openclaw/config.yaml。

2、在agents.defaults.model节点下，设置primary字段指定主模型，例如"qwen3:32b"。

3、在同一层级添加fallbacks列表，按降序优先级填写备用模型名称，例如：
- "qwen2.5:14b"
- "gpt-4-turbo"
- "glm5.0:7b"

4、在agents.defaults.models节点下，显式声明所有允许调用的模型，构成受信白名单，例如：
- "qwen3:32b"
- "qwen2.5:14b"
- "glm5.0:7b"

5、保存文件后，执行openclaw gateway restart --verbose重启网关并观察日志中是否输出[Fallback] primary model timeout, switching to backup。

二、JSON格式配置启用多实例fallback

该方式适用于需为不同Agent实例独立配置fallback策略的场景，支持在agents.list中为每个ID指定专属主备链，避免全局策略冲突。

1、编辑~/.openclaw/openclaw.json文件。

2、定位至agents.list数组，选取目标Agent（如id: "main"）。

3、在其model对象内，设置primary为当前主力模型，例如"anthropic/claude-opus-4-6"。

4、添加fallbacks数组，填入至少两个备用模型标识，例如：
[ "openai-codex/gpt-5.3-codex", "google-antigravity/claude-opus-4-6-thinking" ]

5、确保该Agent的default字段为true，以激活其fallback逻辑。

6、执行openclaw agent reload main重新加载该实例配置。

三、命令行触发动态fallback验证

该方法不修改配置文件，而是通过临时停用主模型服务并观察OpenClaw是否自动启用备用链，用于快速验证fallback机制是否就绪。

1、在终端中运行ollama ps确认主模型服务进程ID。

2、执行kill -9 [PID]强制终止主模型服务。

Nutrient Openclaw 1.2.5

OpenClaw 原生 PDF/文档处理技能，适用于 Nutrient DWS，帮助用户完成 PDF 转换、OCR、文字/表格提取、PII 脱敏等功能。

下载

3、向OpenClaw发起一次API请求或发送一条测试消息，触发模型调用。

4、立即查看日志输出，确认是否出现[Fallback] attempting qwen2.5:14b类提示。

5、若切换成功，检查响应头中X-Used-Model字段值是否已变更为备用模型标识。

6、恢复主模型服务后，等待约30秒，观察日志中是否出现[Recovery] primary model back online, switching back。

四、熔断参数精细化控制fallback行为

该方法通过设置失败阈值与冷却时间，防止因瞬时抖动引发频繁切换，保障模型调度稳定性。

1、在config.yaml的agents.defaults.model节点下，新增failure_threshold字段，设为整数如3，表示连续3次失败才触发fallback。

2、添加cooldown字段，单位为秒，例如60，表示该模型在被标记为不可用后需等待60秒才重新参与健康检查。

3、可选配置timeout字段覆盖默认15秒超时，例如设为20以适配大模型推理延迟。

4、若启用图像处理能力，需单独指定imageModel字段，并为其配置独立的fallbacks与failure_threshold。

5、全部参数配置完成后，运行openclaw gateway healthcheck --full验证熔断规则加载状态。

五、基于环境变量的运行时fallback覆盖

该方法允许在不修改持久化配置的前提下，通过启动参数临时指定fallback行为，适用于A/B测试或紧急回滚场景。

1、停止当前OpenClaw网关进程。

2、设置环境变量：export OPENCLAW_FALLBACK_OVERRIDE="qwen2.5:14b,gpt-4-turbo"。

3、同时设置主模型覆盖：export OPENCLAW_PRIMARY_MODEL="glm5.0:7b"。

4、执行openclaw gateway start --env-file .env启动网关，其中.env文件包含上述两行变量声明。

5、发起请求后，检查响应体中metadata.fallback_used字段是否为true。

6、该覆盖仅在本次进程生命周期内生效，重启后自动还原为配置文件设定。