多模型配置

介绍使用多个模型提供商的常见模式：按代理分发、提示路由、成本分层、本地优先并以托管服务作为备用、非流式提供商回退、速率限制处理以及流式恢复。

参考材料位于提供程序系统的以下位置：

模型提供方 → 概述：提供方是什么，以及配置形式

模型提供商 → 路由：代理调度、提示路由和提供商回退

模型提供方 → 目录：每个提供方的配置结构

何时使用多模型配置

多模型配置适用于：

成本分层：低成本模型处理大批量通道；推理模型处理复杂请求
能力路由：为含图像的通道使用支持视觉的模型，为研究工作流使用推理模型
本地优先开发：开发时使用本地 Ollama，生产环境使用托管端点
团队级隔离：不同团队使用不同的智能体，配备不同的 model_providers 和凭据
非流式速率限制处理：在可重试的 429 后切换到另一个已配置的提供商配置文件

核心理念：按代理分发

每个 [agents.<alias>] 条目都从一个 [providers.models.<type>.<alias>] 开始。该提供商配置可以通过 fallback_models 声明备用模型，并通过 fallback 声明其他提供商配置。完整模式请参阅路由。

要运行多个模型，请运行多个代理，每个代理绑定到一个模型提供方。每个通道一次只能绑定到一个代理。要将通道迁移到其他代理，请编辑应接管该通道的代理上的 channels 列表；Config::validate() 会确保在启动时正确解析这些引用。

跨提供商可靠性

对于非流式调用，ZeroClaw 可以在提供商配置之间遍历有序的回退图。每个回退配置都保留其自身的端点、凭据、模型、请求头、能力覆盖项和嵌套回退声明。运行时会根据错误分类和配置冷却状态进行重试或转至下一个回退配置。

OpenRouter 仍是一等提供商，并可通过一个端点执行供应商选择。它是可选的外部路由层，并非 ZeroClaw 自有回退机制的必需项。

非流式重试和回退

对于网络故障、503 或超时等瞬态错误，非流式调用会使用有界指数退避进行重试，可在 reliability 下进行全局配置（默认值：重试 2 次，初始退避 500 毫秒）。某个条目耗尽重试次数后，可靠包装器会依次尝试配置文件中的 fallback_models 和备用配置文件。

流式恢复边界

流式调用会选择第一个符合条件、未处于冷却状态且支持所需流式能力的条目。流开始后，它不会转到另一个条目。如果流在可见输出到达不可变消费者之前失败，运行时会通过非流式路径重试整个调用，此路径可能遍历回退图。一旦存在可见输出，运行时会保留部分响应，不会重放请求或切换提供商。有关完整契约，请参阅提供商路由生命周期。

API 密钥轮换限制

不要依赖 reliability.api_keys 实现凭据故障转移。在可重试的速率限制情况下，可靠封装器会选择并记录备用密钥，但 ModelProvider trait 无法将其应用于已构造的提供程序。重试仍使用原始凭据。Issue #9190 跟踪了此限制。

当需要凭据级故障转移时，请使用各自具有独立凭据的提供商配置文件，或使用外部路由服务。

本地开发与托管替代方案

并排运行本地 Ollama 代理和托管服务商代理；将每个通道路由到你希望其使用的代理。

dev 代理从 CLI 运行（无需绑定通道，使用 zeroclaw agent -a dev 即可）。当 Ollama 宕机时，dev 代理会快速失败并显示错误。生产通道不受影响。

本地小型无文本回退配置

小型本地模型通常需要运行时配置文件，而不是特定于提供方的模式。让 Ollama provider 只专注于连接细节，然后使用 [runtime_profiles.<alias>] 来收紧提示词/工具循环行为。ZeroClaw 为直接安装运行时预设的代码路径提供了内置的 local_small 运行时预设。如果你手动编辑配置，请使用这个等效的块：

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

[agents.local]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.local_small]
agentic                 = true
compact_context          = true
strict_tool_parsing      = true
max_tool_iterations      = 4
max_actions_per_hour     = 10
max_cost_per_day_cents   = 100
shell_timeout_secs       = 30
max_delegation_depth     = 1
delegation_timeout_secs  = 60
agentic_timeout_secs     = 120
max_history_messages     = 20
max_context_tokens       = 8000
parallel_tools           = false
max_system_prompt_chars  = 4000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

此配置文件由现有的基本组件组成：

compact_context 可保持启动上下文较小。
除非提供方返回原生工具调用，否则 strict_tool_parsing 会将形似 XML/JSON 的回退文本视为助手文本。
max_tool_iterations、max_context_tokens、max_system_prompt_chars 和 max_tool_result_chars 用于限制失控的循环以及过大的提示词/工具上下文。
max_actions_per_hour、max_cost_per_day_cents 以及超时/委托字段使本地运行保持与内置预设相同的预算结构。
parallel_tools = false 和 keep_tool_context_turns = 1 会使本地运行保持串行，并限制保留的工具上下文。

使用 Ollama 时，这是一个无文本回退配置文件：已授权的工具仍在 risk_profile 中配置，但模型的文本形式工具标记不会被执行。可将其用于聊天优先的本地智能体，或用于返回原生/结构化工具调用的提供商。如果本地模型必须使用 ZeroClaw 的文本回退工具语法，请设置 strict_tool_parsing = false 并保留其他小模型限制。

运行两个代理并将通道路由到合适的层级。delegate 工具允许一个代理在对话过程中将任务移交给另一个代理。委派受到限制：调用方的风险配置文件必须设置 delegation_policy mode = "allow"，并且目标必须可从调用方访问（同一配置文件的对等方，或调用方 delegates 列表中的显式条目）。下面的前线代理和重型代理运行在相同的 trusted 风险配置文件上，因此它们作为同一配置文件的对等方相互访问；它们在模型和运行时配置文件（迭代预算）上有所不同，而非信任面。

前线智能体使用 Haiku 处理每一条入站消息。当需要更深入的推理时，它会调用 delegate 工具并设置 agent = "heavy"；由于两个智能体共享 trusted 风险配置，且该配置允许委派，因此更重量级的智能体将使用 Opus 接管该子任务。

非流式错误处理

非流式调用的可重试失败包括：

超时：提供程序未在配置的超时时间内响应
连接错误：网络或 DNS 故障
速率限制 (429)：将提供商配置文件置于临时的内存冷却状态，并在存在其他条目时继续处理
服务不可用 (503)：临时性服务问题

重试不会由以下情况触发：

无效请求 (400)：输入格式有误；重试无济于事
永久身份验证失败：API 密钥格式无效
模型输出错误：模型已响应，但返回了错误负载

当所有已实例化的条目都已耗尽或处于冷却状态时，失败会连同收集到的尝试失败信息一起传递到调用通道。

调试

持久化日志（"rolling" 为默认值）会记录重试、冷却和回退行为。然后查询跟踪信息：

sh

zeroclaw doctor traces --contains 重试
zeroclaw doctor traces --contains "429"
zeroclaw doctor traces --contains "model_provider"

最佳实践

每个路由意图对应一个 agent。 如果两个渠道需要不同的模型行为，请命名两个 agent。
为回退配置文件明确归属。 将每个端点、凭据、模型和能力覆盖项保留在为其提供服务的配置文件中。
将 OpenRouter 作为可选的路由层。 当服务端的供应商选择有用时使用它；当应由运行时控制顺序时，使用 ZeroClaw 回退配置文件。
不要依赖 reliability.api_keys。在问题 #9190 修复之前，请使用单独构建的配置文件。
单独对每个 agent 进行冒烟测试。 zeroclaw agent -a <alias> 可在不受通道连接干扰的情况下运行 agent。
记录代理意图。 添加 # comment 行，说明每个代理服务于哪些通道以及原因。
通过 env 注入密钥，而非内联。 ZEROCLAW_providers__models__<type>__<alias>__api_key=... 会在启动时设置 api_key；参见环境变量。
分离开发和生产代理。 每个环境都有各自的 [agents.<alias>] 条目，并绑定到各自的通道。

凭证解析

每个提供商条目按以下顺序解析凭据：

内联 api_key（在 provider 条目中）。
~/.zeroclaw/secrets 中的密钥存储。
通用环境变量覆盖：在启动时设置 ZEROCLAW_providers__models__<type>__<alias>__api_key=...。如果您的 shell 已导出 ANTHROPIC_API_KEY、OPENROUTER_API_KEY 或类似的供应商默认名称，请在启动前将其桥接到此 schema-mirror 变量，除非该提供商系列明确记录了原生运行时环境桥接。有关完整语法和桥接示例，请参阅环境变量。

凭据不会在提供商配置之间共享；请为每个配置分别设置。路由级别的 model_routes[].api_key 是在构建其路由目标时优先级更高的覆盖项。路由目标按 model_provider 去重，因此第一个匹配的路由凭据可以构建由多个提示共同使用的提供商。路由共享目标时，优先使用配置自有的凭据。

ZeroClaw Docs