ZeroClaw 多模型接入实战Per-Agent 调度、跨厂商降级与成本分层配置指南【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw导读本文是 ZeroClaw 多模型Multi-Model配置的完整实战指南围绕 multi-model-setup.md 讲解如何同时使用多个模型提供商按 Agent 分发per-agent dispatch、提示词 hint 路由、成本分层cost tiering、本地优先 托管备份、非流式提供商降级、限流429处理与流式恢复边界。读完本文你将掌握在config.toml中编排多 Agent、多提供商、多模型的完整配置形态理解ReliableModelProvider的重试与降级语义并能用zeroclaw doctor traces排查每次请求实际命中的模型与提供商。何时需要多模型配置多模型配置不是炫技而是针对以下五类真实诉求原文场景成本分层Cost tiering廉价模型承接高流量渠道推理模型只处理复杂请求让预算花在刀刃上。能力路由Capability routing带图片的渠道交给视觉模型研究工作流交给推理模型。本地优先开发Local-first development开发环境用本地 Ollama生产环境用托管端点。团队隔离Per-team isolation不同团队使用不同 Agent各自绑定独立的model_providers与凭据。非流式限流处理Non-streaming rate-limit handling遇到可重试的429后切换到另一个已配置的提供商 profile。核心思想Per-Agent 调度没有全局默认ZeroClaw 的多模型体系建立在每个 Agent 绑定一个模型提供商之上不存在全局默认模型这样的开关每个[agents.alias]条目从且仅从一个[providers.models.type.alias]profile 出发该 provider profile 可以通过fallback_models声明同端点上的备用模型通过fallback声明其他 dottedtype.aliasprovider profile要运行多个模型就运行多个 Agent每个 Agent 绑定一个 provider profile每个渠道channel同一时刻只绑定一个 Agent要把某个渠道迁移到另一个 Agent编辑目标 Agent 的channels列表即可启动时Config::validate()会确保所有引用都能解析无法解析则启动失败报错。配置形态为providers.models.type.aliastype是厂商规范槽位每个厂商一个槽位无同义词例如azure_openai与azure-openai不会被同时接受alias是操作者自取的实例名同一 type 下可以定义任意多个 alias——例如同一个 Anthropic 账户体系下可以同时存在anthropic.personal与anthropic.work两个 profile各自携带独立的api_key与model。完整配置形状见 providers/overview.md逐厂商配置示例见 providers/catalog.md。设计佐证Config::validate()在启动时对model_provider、risk_profile等引用做强校验见 providers/configuration.md任何悬空引用都会启动失败而不是运行期静默降级。同时 Agent 的risk_profile与runtime_profile引用的是彼此独立的 alias 映射名字不必相同。跨提供商可靠性有序降级图对于非流式调用ZeroClaw 可以在多个 provider profile 之间按顺序走一张降级图fallback graph。每个降级 profile 保留自己的endpoint端点credentials凭据model模型headers请求头capability overrides能力覆盖例如视觉能力嵌套的fallback声明可递归运行期根据错误分类与 profile 的冷却cooldown状态决定是原地重试还是前进到下一个候选。降级图的物化与组合发生在crates/zeroclaw-providers的 factory 与ReliableModelProvider见 crates/zeroclaw-providers/src/lib.rs、crates/zeroclaw-providers/src/factory.rs、crates/zeroclaw-providers/src/reliable.rs。值得强调的是OpenRouter 依然是一等公民可以在单一端点后做服务端厂商选择但它只是可选的外部路由层不是 ZeroClaw 第一方降级机制的前提——即不使用 OpenRouterZeroClaw 自带的 hint 路由、同 profile 模型降级与跨 profile 降级依然完整可用见 providers/routing.md。非流式重试与降级对于瞬时错误网络失败、503、超时非流式调用采用有界的指数退避重试退避参数在全局[reliability]下配置默认2 次重试provider_retries 2默认500 ms 初始退避provider_backoff_ms 500当某个候选条目entry的重试被耗尽后可靠包装器Reliable wrapper按序前进先走该 profile 的fallback_models再走fallback声明的其他 provider profile。源码佐证ReliabilityConfig定义于 crates/zeroclaw-config/src/schema.rs其默认值函数default_provider_retries()返回 2、default_provider_backoff_ms()返回 500同一结构还承载api_keys备用密钥池、渠道/守护进程重启退避channel_initial_backoff_secs默认 2s、channel_max_backoff_secs默认 60s以及调度器轮询与 cron 重试参数。候选条目的尝试顺序对生产 aliasfactory 按深度优先展开配置的降级图有效顺序为见 architecture/provider-routing-lifecycle.md该 profile 的有效主模型若无有效主模型则贡献一个 unpinned 条目该 profile 的fallback_models仅在存在有效主模型时按序物化每个fallbackprofile依次展开其自身的主/unpinned 条目、可用降级模型与嵌套降级 profile。配置示例fallback_models与fallback两轴独立来源providers/configuration.md[providers.models.anthropic.prod] model claude-sonnet-4-5 fallback_models [claude-haiku-4-5] # 同端点同凭据只换模型 fallback [openai.backup] # 跨厂商使用 openai.backup 自己的凭据 [providers.models.openai.backup] model gpt-4.1此时尝试顺序为anthropic.prod/claude-sonnet-4-5→anthropic.prod/claude-haiku-4-5→openai.backup/gpt-4.1。降级链最长 3 层 alias成环的链会被裁剪fallback_cycle警告超深链截断max_fallback_depth_exceeded警告悬空引用dangling_fallback_ref警告在运行期跳过——这些都是非致命的Config::validate()仍通过坏链只是被优雅跳过绝不影响 Agent 运行。冷却cooldown对执行顺序的影响有一个容易踩坑的细节物化顺序 ≠ 实际执行顺序。一个 profile 的主模型与其fallback_models共享同一个冷却键cooldown key因此主模型收到429后在该冷却期内同一 profile 的其余降级模型也可能被整体跳过直接前进到下一个 profile实现见 crates/zeroclaw-providers/src/reliable.rs 中的provider_cooldown_active/provider_should_skip_for_cooldown冷却时长优先取响应头Retry-After缺省用内置默认。流式恢复边界一旦可见输出出现绝不重放流式调用与重试的关系比非流式更严格契约完整定义于 architecture/provider-routing-lifecycle.md流式调用只选择第一个满足流能力要求且不在冷却中的条目流开始后不切换到其他条目如果流在可见输出到达不可变消费者之前失败运行期把整个调用按非流式路径重试从而可以重新走完整降级图一旦文本、推理或已预执行的工具事件到达了不可变事件汇immutable event sink中断就变为StreamInterruptedAfterOutput运行期保留部分响应不重放请求也不切换提供商取消永远不会自动变成提供商重试取消发生在转发文本之前则终止本轮发生在转发文本之后则保留该部分助手文本。流结束但没有任何最终文本或工具调用属于语义空响应而非成功回答当运行期标记该结果为可重放且provider_retries非零时Reliable 允许一次非流式恢复调用指向产出空流的同一个提供商/模型该配额只消耗一次恢复失败则前进到剩余候选。这一边界由 crates/zeroclaw-runtime/src/agent/turn/provider_call.rs 与 crates/zeroclaw-runtime/src/agent/turn/stream_consume.rs 承接流完成信号协议侧翻译则由 crates/zeroclaw-providers/src/stream_guard.rs 负责。已知限制reliability.api_keys无法做凭据级故障转移原文明确警告不要依赖reliability.api_keys做凭据故障转移。在可重试限流发生时可靠包装器会选出一个备用密钥并打日志但ModelProvidertrait 无法把这个新密钥应用到已经构造好的 provider 实例上重试仍然使用原始凭据。该限制由 ZeroClaw 的 issue #9190 跟踪此处不贴外部链接可按该编号在仓库 issue 区检索。替代方案需要凭据级故障转移时请使用各自携带独立凭据的独立 provider profile即走fallback图或使用外部路由服务如 OpenRouter。本地开发 托管备份让本地 Ollama Agent与托管提供商 Agent并排运行再把每个渠道路由到你想用的那个devAgent 直接从 CLI 运行无需绑定渠道zeroclaw agent -a dev即可Ollama 宕机时dev Agent 快速失败并直接把错误抛给操作者prod 渠道不受任何影响——它们绑定的是另一个 Agent。这正体现了 per-agent 隔离的价值一个环境的故障被 Agent 边界完全隔离开。每个环境dev / prod各自拥有自己的[agents.alias]条目各自绑定自己的渠道。本地小模型专用local_small 无文本回退 profile小尺寸本地模型通常需要的是运行期 profile约束 prompt/工具循环行为而不是提供商特定的模式。Ollama provider 只负责连接细节行为收紧交给[runtime_profiles.alias]。ZeroClaw 内置了local_small运行期预设代码路径中直接安装预设的入口可见于 crates/zeroclaw-config/src/presets.rs常量LOCAL_SMALL_RUNTIME_PRESET_NAME。若手工编辑配置使用与该内置预设等价的完整块原文原样[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 prompt_injection_mode compact 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 8000 max_tool_result_chars 4000 keep_tool_context_turns 1 memory_recall_limit 3字段含义逐项拆解该 profile 是对现有原语的组合各字段作用如下compact_context让启动上下文保持精简prompt_injection_mode compact技能skill元数据保持内联仅在有read_skill加载器时按需加载完整指令没有该加载器的提供商保留原有的完整注入回退strict_tool_parsing true除非提供商返回原生工具调用否则把形似 XML/JSON 的回退文本当作助手文本不执行文本形式工具标记max_tool_iterations、max_context_tokens、max_system_prompt_chars、max_tool_result_chars兜住失控循环与过大的 prompt/工具上下文max_actions_per_hour、max_cost_per_day_cents以及各 timeout/delegation 字段让本地运行的预算形态与内置预设完全一致parallel_tools false与keep_tool_context_turns 1本地运行保持串行限制保留的工具上下文轮数。与 Ollama 搭配时这是一个**无文本回退no-text-fallback**profile授权工具仍然由risk_profile配置但来自模型的文本形式工具标记不会被当作工具执行。适用场景聊天优先的本地 Agent或返回原生/结构化工具调用的提供商。若本地模型必须使用 ZeroClaw 的文本回退工具语法则设置strict_tool_parsing false同时保留其余小模型限制项。实现佐证local_small预设的工厂函数local_small_runtime()位于 crates/zeroclaw-config/src/presets.rs与文档块中的取值一一对应配套测试local_small_runtime_matches_documented_small_model_shape专门验证该预设与文档描述的小模型形态一致。成本分层需要时用重模型平时用快模型运行两个 Agent把渠道路由到对应的层。delegate工具允许一个 Agent 在对话中途把任务交给另一个 Agent实现见 crates/zeroclaw-runtime/src/tools/delegate.rs。委托是有门槛的完整规则见 agents/delegation.md调用方的 risk profile 必须设置delegation_policy mode allow默认是forbidden目标必须是调用方可达的同 risk profile 的同侪peer或调用方delegates列表中的显式条目。典型形态示意字段与文档所述模式一致[agents.frontline] model_provider anthropic.haiku # 前端 Agent廉价快速模型 risk_profile trusted runtime_profile frontline_runtime [agents.heavy] model_provider anthropic.opus # 重型 Agent深度推理模型 risk_profile trusted # 与 frontline 同一 risk profile → 互为同侪 runtime_profile heavy_runtime [risk_profiles.trusted] level trusted delegation_policy { mode allow }关键设计frontline 与 heavy 运行在同一个trustedrisk profile上因此互为同侪、天然可达它们的差异只在模型与运行期 profile迭代预算而非信任面trust surface。运行流程是frontline 在 Haiku 上处理每一条入站消息当它判断需要更深推理时调用delegate工具并传agent heavy由于两者共享允许委托的trustedprofileheavy Agent 在 Opus 上接管子任务。非流式错误处理哪些该重试哪些不该原文给出了明确的两张清单可重试的失败会触发重试/降级超时Timeout提供商在配置的超时时间内未响应连接错误Connection error网络或 DNS 故障限流 429Rate limit将该 provider profile 置于内存中的临时冷却存在其他条目时前进服务不可用 503Service unavailable临时服务问题。不触发重试的失败直接失败无效请求 400Invalid request输入畸形重试无益永久性认证失败Permanent auth failure例如 API key 格式非法模型输出错误Model output errors模型已响应但返回了错误负载。当每个已物化条目都被耗尽或处于冷却中失败会携带收集到的各次尝试失败信息上抛给调用方渠道。错误分类与NonRetryableProviderError标记的实现位于 crates/zeroclaw-providers/src/reliable.rsis_non_retryable、is_non_retryable_rate_limit、parse_retry_after_ms等。调试从持久化日志中还原路由过程持久化日志默认是rolling滚动模式会记录重试、冷却与降级行为。然后按需查询 tracezeroclaw doctor traces --contains retry zeroclaw doctor traces --contains 429 zeroclaw doctor traces --contains model_provider观测面还能看到每个 Agent 的路由决策与模型命中例如INFO channeltelegram.home routed to agentfast INFO agentfast model_provideranthropic.haiku turn_id... INFO model_provideranthropic.haiku stream complete tokens{input512, output128}生产部署可把日志接入 Loki / Grafana见 ops 可观测性文档。最佳实践原文 8 条一个路由意图对应一个 Agent如果两个渠道需要不同的模型行为就命名两个 Agent给降级 profile 显式的归属每个 endpoint、凭据、模型与能力覆盖都放在服务它的那个 profile 上把 OpenRouter 当作可选路由层需要服务端厂商选择时用它希望运行期自己掌控顺序时用 ZeroClaw 的降级 profile不要依赖reliability.api_keys在 issue #9190 修复前使用各自独立构造的 profile逐个隔离冒烟测试每个 Agentzeroclaw agent -a alias可以在没有渠道管线干扰的情况下运行某个 Agent给 Agent 写注释用# comment说明每个 Agent 服务哪些渠道及原因用环境变量注入密钥不要内联ZEROCLAW_providers__models__type__alias__api_key...可在启动时设置api_key开发与生产 Agent 分离每个环境拥有自己的[agents.alias]条目绑定自己的渠道。凭据解析顺序每个 provider 条目按以下顺序解析凭据内联api_key写在 provider 条目上密钥库Secrets store位于~/.zeroclaw/secrets通用环境变量覆盖启动时ZEROCLAW_providers__models__type__alias__api_key...。如果你的 shell 已经导出了ANTHROPIC_API_KEY、OPENROUTER_API_KEY等厂商默认名需要在启动前把它桥接bridge进这个 schema 镜像变量除非该厂商族文档明确声明了原生运行期环境变量桥接。几点要点凭据不在 provider profile 之间共享每个 profile 单独设置路由级model_routes[].api_key是更高优先级的覆盖在其路由目标被构造时生效路由目标按model_provider去重因此多个 hint 共享同一个目标时第一个匹配的路由凭据即可构造该共享 provider多个 hint 共享目标时优先把凭据放在 profile 上。环境变量的完整语法、桥接示例与 alias 命名规则小写字母/数字/下划线、1–63 字符、禁止__与连字符等见 reference/env-vars.md。深入阅读providers/overview.mdProvider 抽象与配置形态providers/routing.mdAgent 分发、hint 路由与 provider 降级providers/configuration.md[providers.*]完整 schema 与降级配置providers/catalog.md每个受支持厂商的配置示例architecture/provider-routing-lifecycle.md构造、重试分类、流式恢复与 attribution 归属agents/delegation.mddelegate与 SubAgent 的完整门槛规则reference/env-vars.md环境变量语法与密钥注入源码入口Provider trait 见 crates/zeroclaw-api/src/model_provider.rs路由选择见 crates/zeroclaw-providers/src/router.rs重试/冷却/降级见 crates/zeroclaw-providers/src/reliable.rsprofile 模型钉扎见 crates/zeroclaw-providers/src/model_pin.rs运行期流重放见 crates/zeroclaw-runtime/src/agent/turn/provider_call.rs 与 crates/zeroclaw-runtime/src/agent/turn/stream_consume.rs。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZeroClaw 多模型接入实战：Per-Agent 调度、跨厂商降级与成本分层配置指南
ZeroClaw 多模型接入实战Per-Agent 调度、跨厂商降级与成本分层配置指南【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw导读本文是 ZeroClaw 多模型Multi-Model配置的完整实战指南围绕 multi-model-setup.md 讲解如何同时使用多个模型提供商按 Agent 分发per-agent dispatch、提示词 hint 路由、成本分层cost tiering、本地优先 托管备份、非流式提供商降级、限流429处理与流式恢复边界。读完本文你将掌握在config.toml中编排多 Agent、多提供商、多模型的完整配置形态理解ReliableModelProvider的重试与降级语义并能用zeroclaw doctor traces排查每次请求实际命中的模型与提供商。何时需要多模型配置多模型配置不是炫技而是针对以下五类真实诉求原文场景成本分层Cost tiering廉价模型承接高流量渠道推理模型只处理复杂请求让预算花在刀刃上。能力路由Capability routing带图片的渠道交给视觉模型研究工作流交给推理模型。本地优先开发Local-first development开发环境用本地 Ollama生产环境用托管端点。团队隔离Per-team isolation不同团队使用不同 Agent各自绑定独立的model_providers与凭据。非流式限流处理Non-streaming rate-limit handling遇到可重试的429后切换到另一个已配置的提供商 profile。核心思想Per-Agent 调度没有全局默认ZeroClaw 的多模型体系建立在每个 Agent 绑定一个模型提供商之上不存在全局默认模型这样的开关每个[agents.alias]条目从且仅从一个[providers.models.type.alias]profile 出发该 provider profile 可以通过fallback_models声明同端点上的备用模型通过fallback声明其他 dottedtype.aliasprovider profile要运行多个模型就运行多个 Agent每个 Agent 绑定一个 provider profile每个渠道channel同一时刻只绑定一个 Agent要把某个渠道迁移到另一个 Agent编辑目标 Agent 的channels列表即可启动时Config::validate()会确保所有引用都能解析无法解析则启动失败报错。配置形态为providers.models.type.aliastype是厂商规范槽位每个厂商一个槽位无同义词例如azure_openai与azure-openai不会被同时接受alias是操作者自取的实例名同一 type 下可以定义任意多个 alias——例如同一个 Anthropic 账户体系下可以同时存在anthropic.personal与anthropic.work两个 profile各自携带独立的api_key与model。完整配置形状见 providers/overview.md逐厂商配置示例见 providers/catalog.md。设计佐证Config::validate()在启动时对model_provider、risk_profile等引用做强校验见 providers/configuration.md任何悬空引用都会启动失败而不是运行期静默降级。同时 Agent 的risk_profile与runtime_profile引用的是彼此独立的 alias 映射名字不必相同。跨提供商可靠性有序降级图对于非流式调用ZeroClaw 可以在多个 provider profile 之间按顺序走一张降级图fallback graph。每个降级 profile 保留自己的endpoint端点credentials凭据model模型headers请求头capability overrides能力覆盖例如视觉能力嵌套的fallback声明可递归运行期根据错误分类与 profile 的冷却cooldown状态决定是原地重试还是前进到下一个候选。降级图的物化与组合发生在crates/zeroclaw-providers的 factory 与ReliableModelProvider见 crates/zeroclaw-providers/src/lib.rs、crates/zeroclaw-providers/src/factory.rs、crates/zeroclaw-providers/src/reliable.rs。值得强调的是OpenRouter 依然是一等公民可以在单一端点后做服务端厂商选择但它只是可选的外部路由层不是 ZeroClaw 第一方降级机制的前提——即不使用 OpenRouterZeroClaw 自带的 hint 路由、同 profile 模型降级与跨 profile 降级依然完整可用见 providers/routing.md。非流式重试与降级对于瞬时错误网络失败、503、超时非流式调用采用有界的指数退避重试退避参数在全局[reliability]下配置默认2 次重试provider_retries 2默认500 ms 初始退避provider_backoff_ms 500当某个候选条目entry的重试被耗尽后可靠包装器Reliable wrapper按序前进先走该 profile 的fallback_models再走fallback声明的其他 provider profile。源码佐证ReliabilityConfig定义于 crates/zeroclaw-config/src/schema.rs其默认值函数default_provider_retries()返回 2、default_provider_backoff_ms()返回 500同一结构还承载api_keys备用密钥池、渠道/守护进程重启退避channel_initial_backoff_secs默认 2s、channel_max_backoff_secs默认 60s以及调度器轮询与 cron 重试参数。候选条目的尝试顺序对生产 aliasfactory 按深度优先展开配置的降级图有效顺序为见 architecture/provider-routing-lifecycle.md该 profile 的有效主模型若无有效主模型则贡献一个 unpinned 条目该 profile 的fallback_models仅在存在有效主模型时按序物化每个fallbackprofile依次展开其自身的主/unpinned 条目、可用降级模型与嵌套降级 profile。配置示例fallback_models与fallback两轴独立来源providers/configuration.md[providers.models.anthropic.prod] model claude-sonnet-4-5 fallback_models [claude-haiku-4-5] # 同端点同凭据只换模型 fallback [openai.backup] # 跨厂商使用 openai.backup 自己的凭据 [providers.models.openai.backup] model gpt-4.1此时尝试顺序为anthropic.prod/claude-sonnet-4-5→anthropic.prod/claude-haiku-4-5→openai.backup/gpt-4.1。降级链最长 3 层 alias成环的链会被裁剪fallback_cycle警告超深链截断max_fallback_depth_exceeded警告悬空引用dangling_fallback_ref警告在运行期跳过——这些都是非致命的Config::validate()仍通过坏链只是被优雅跳过绝不影响 Agent 运行。冷却cooldown对执行顺序的影响有一个容易踩坑的细节物化顺序 ≠ 实际执行顺序。一个 profile 的主模型与其fallback_models共享同一个冷却键cooldown key因此主模型收到429后在该冷却期内同一 profile 的其余降级模型也可能被整体跳过直接前进到下一个 profile实现见 crates/zeroclaw-providers/src/reliable.rs 中的provider_cooldown_active/provider_should_skip_for_cooldown冷却时长优先取响应头Retry-After缺省用内置默认。流式恢复边界一旦可见输出出现绝不重放流式调用与重试的关系比非流式更严格契约完整定义于 architecture/provider-routing-lifecycle.md流式调用只选择第一个满足流能力要求且不在冷却中的条目流开始后不切换到其他条目如果流在可见输出到达不可变消费者之前失败运行期把整个调用按非流式路径重试从而可以重新走完整降级图一旦文本、推理或已预执行的工具事件到达了不可变事件汇immutable event sink中断就变为StreamInterruptedAfterOutput运行期保留部分响应不重放请求也不切换提供商取消永远不会自动变成提供商重试取消发生在转发文本之前则终止本轮发生在转发文本之后则保留该部分助手文本。流结束但没有任何最终文本或工具调用属于语义空响应而非成功回答当运行期标记该结果为可重放且provider_retries非零时Reliable 允许一次非流式恢复调用指向产出空流的同一个提供商/模型该配额只消耗一次恢复失败则前进到剩余候选。这一边界由 crates/zeroclaw-runtime/src/agent/turn/provider_call.rs 与 crates/zeroclaw-runtime/src/agent/turn/stream_consume.rs 承接流完成信号协议侧翻译则由 crates/zeroclaw-providers/src/stream_guard.rs 负责。已知限制reliability.api_keys无法做凭据级故障转移原文明确警告不要依赖reliability.api_keys做凭据故障转移。在可重试限流发生时可靠包装器会选出一个备用密钥并打日志但ModelProvidertrait 无法把这个新密钥应用到已经构造好的 provider 实例上重试仍然使用原始凭据。该限制由 ZeroClaw 的 issue #9190 跟踪此处不贴外部链接可按该编号在仓库 issue 区检索。替代方案需要凭据级故障转移时请使用各自携带独立凭据的独立 provider profile即走fallback图或使用外部路由服务如 OpenRouter。本地开发 托管备份让本地 Ollama Agent与托管提供商 Agent并排运行再把每个渠道路由到你想用的那个devAgent 直接从 CLI 运行无需绑定渠道zeroclaw agent -a dev即可Ollama 宕机时dev Agent 快速失败并直接把错误抛给操作者prod 渠道不受任何影响——它们绑定的是另一个 Agent。这正体现了 per-agent 隔离的价值一个环境的故障被 Agent 边界完全隔离开。每个环境dev / prod各自拥有自己的[agents.alias]条目各自绑定自己的渠道。本地小模型专用local_small 无文本回退 profile小尺寸本地模型通常需要的是运行期 profile约束 prompt/工具循环行为而不是提供商特定的模式。Ollama provider 只负责连接细节行为收紧交给[runtime_profiles.alias]。ZeroClaw 内置了local_small运行期预设代码路径中直接安装预设的入口可见于 crates/zeroclaw-config/src/presets.rs常量LOCAL_SMALL_RUNTIME_PRESET_NAME。若手工编辑配置使用与该内置预设等价的完整块原文原样[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 prompt_injection_mode compact 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 8000 max_tool_result_chars 4000 keep_tool_context_turns 1 memory_recall_limit 3字段含义逐项拆解该 profile 是对现有原语的组合各字段作用如下compact_context让启动上下文保持精简prompt_injection_mode compact技能skill元数据保持内联仅在有read_skill加载器时按需加载完整指令没有该加载器的提供商保留原有的完整注入回退strict_tool_parsing true除非提供商返回原生工具调用否则把形似 XML/JSON 的回退文本当作助手文本不执行文本形式工具标记max_tool_iterations、max_context_tokens、max_system_prompt_chars、max_tool_result_chars兜住失控循环与过大的 prompt/工具上下文max_actions_per_hour、max_cost_per_day_cents以及各 timeout/delegation 字段让本地运行的预算形态与内置预设完全一致parallel_tools false与keep_tool_context_turns 1本地运行保持串行限制保留的工具上下文轮数。与 Ollama 搭配时这是一个**无文本回退no-text-fallback**profile授权工具仍然由risk_profile配置但来自模型的文本形式工具标记不会被当作工具执行。适用场景聊天优先的本地 Agent或返回原生/结构化工具调用的提供商。若本地模型必须使用 ZeroClaw 的文本回退工具语法则设置strict_tool_parsing false同时保留其余小模型限制项。实现佐证local_small预设的工厂函数local_small_runtime()位于 crates/zeroclaw-config/src/presets.rs与文档块中的取值一一对应配套测试local_small_runtime_matches_documented_small_model_shape专门验证该预设与文档描述的小模型形态一致。成本分层需要时用重模型平时用快模型运行两个 Agent把渠道路由到对应的层。delegate工具允许一个 Agent 在对话中途把任务交给另一个 Agent实现见 crates/zeroclaw-runtime/src/tools/delegate.rs。委托是有门槛的完整规则见 agents/delegation.md调用方的 risk profile 必须设置delegation_policy mode allow默认是forbidden目标必须是调用方可达的同 risk profile 的同侪peer或调用方delegates列表中的显式条目。典型形态示意字段与文档所述模式一致[agents.frontline] model_provider anthropic.haiku # 前端 Agent廉价快速模型 risk_profile trusted runtime_profile frontline_runtime [agents.heavy] model_provider anthropic.opus # 重型 Agent深度推理模型 risk_profile trusted # 与 frontline 同一 risk profile → 互为同侪 runtime_profile heavy_runtime [risk_profiles.trusted] level trusted delegation_policy { mode allow }关键设计frontline 与 heavy 运行在同一个trustedrisk profile上因此互为同侪、天然可达它们的差异只在模型与运行期 profile迭代预算而非信任面trust surface。运行流程是frontline 在 Haiku 上处理每一条入站消息当它判断需要更深推理时调用delegate工具并传agent heavy由于两者共享允许委托的trustedprofileheavy Agent 在 Opus 上接管子任务。非流式错误处理哪些该重试哪些不该原文给出了明确的两张清单可重试的失败会触发重试/降级超时Timeout提供商在配置的超时时间内未响应连接错误Connection error网络或 DNS 故障限流 429Rate limit将该 provider profile 置于内存中的临时冷却存在其他条目时前进服务不可用 503Service unavailable临时服务问题。不触发重试的失败直接失败无效请求 400Invalid request输入畸形重试无益永久性认证失败Permanent auth failure例如 API key 格式非法模型输出错误Model output errors模型已响应但返回了错误负载。当每个已物化条目都被耗尽或处于冷却中失败会携带收集到的各次尝试失败信息上抛给调用方渠道。错误分类与NonRetryableProviderError标记的实现位于 crates/zeroclaw-providers/src/reliable.rsis_non_retryable、is_non_retryable_rate_limit、parse_retry_after_ms等。调试从持久化日志中还原路由过程持久化日志默认是rolling滚动模式会记录重试、冷却与降级行为。然后按需查询 tracezeroclaw doctor traces --contains retry zeroclaw doctor traces --contains 429 zeroclaw doctor traces --contains model_provider观测面还能看到每个 Agent 的路由决策与模型命中例如INFO channeltelegram.home routed to agentfast INFO agentfast model_provideranthropic.haiku turn_id... INFO model_provideranthropic.haiku stream complete tokens{input512, output128}生产部署可把日志接入 Loki / Grafana见 ops 可观测性文档。最佳实践原文 8 条一个路由意图对应一个 Agent如果两个渠道需要不同的模型行为就命名两个 Agent给降级 profile 显式的归属每个 endpoint、凭据、模型与能力覆盖都放在服务它的那个 profile 上把 OpenRouter 当作可选路由层需要服务端厂商选择时用它希望运行期自己掌控顺序时用 ZeroClaw 的降级 profile不要依赖reliability.api_keys在 issue #9190 修复前使用各自独立构造的 profile逐个隔离冒烟测试每个 Agentzeroclaw agent -a alias可以在没有渠道管线干扰的情况下运行某个 Agent给 Agent 写注释用# comment说明每个 Agent 服务哪些渠道及原因用环境变量注入密钥不要内联ZEROCLAW_providers__models__type__alias__api_key...可在启动时设置api_key开发与生产 Agent 分离每个环境拥有自己的[agents.alias]条目绑定自己的渠道。凭据解析顺序每个 provider 条目按以下顺序解析凭据内联api_key写在 provider 条目上密钥库Secrets store位于~/.zeroclaw/secrets通用环境变量覆盖启动时ZEROCLAW_providers__models__type__alias__api_key...。如果你的 shell 已经导出了ANTHROPIC_API_KEY、OPENROUTER_API_KEY等厂商默认名需要在启动前把它桥接bridge进这个 schema 镜像变量除非该厂商族文档明确声明了原生运行期环境变量桥接。几点要点凭据不在 provider profile 之间共享每个 profile 单独设置路由级model_routes[].api_key是更高优先级的覆盖在其路由目标被构造时生效路由目标按model_provider去重因此多个 hint 共享同一个目标时第一个匹配的路由凭据即可构造该共享 provider多个 hint 共享目标时优先把凭据放在 profile 上。环境变量的完整语法、桥接示例与 alias 命名规则小写字母/数字/下划线、1–63 字符、禁止__与连字符等见 reference/env-vars.md。深入阅读providers/overview.mdProvider 抽象与配置形态providers/routing.mdAgent 分发、hint 路由与 provider 降级providers/configuration.md[providers.*]完整 schema 与降级配置providers/catalog.md每个受支持厂商的配置示例architecture/provider-routing-lifecycle.md构造、重试分类、流式恢复与 attribution 归属agents/delegation.mddelegate与 SubAgent 的完整门槛规则reference/env-vars.md环境变量语法与密钥注入源码入口Provider trait 见 crates/zeroclaw-api/src/model_provider.rs路由选择见 crates/zeroclaw-providers/src/router.rs重试/冷却/降级见 crates/zeroclaw-providers/src/reliable.rsprofile 模型钉扎见 crates/zeroclaw-providers/src/model_pin.rs运行期流重放见 crates/zeroclaw-runtime/src/agent/turn/provider_call.rs 与 crates/zeroclaw-runtime/src/agent/turn/stream_consume.rs。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考