路由
ZeroClaw 使用路由来做出两种不同的决策：
- 代理调度用于选择负责某个通道或请求的代理。每个代理都有自己的提供商配置和运行时策略。
- 提供商和模型路由会为一次调用选择已配置的提供商配置和模型，然后应用该配置的重试和回退策略。
外部路由服务（例如 OpenRouter）仍可通过单个提供商配置来执行供应商选择。它是可选的：ZeroClaw 还支持第一方提示路由、同一提供商配置中的模型回退，以及跨提供商配置回退。
每代理分发
将每个路由目标定义为独立的 agent，然后将通道指向应处理其流量的 agent。
每个通道绑定到一个代理。要在代理之间移动通道，请在应当接管这些通道的代理上编辑 channels = [...]；Config::validate() 会确保引用能够正确解析。
对于单个会话中的临时多步骤路由，spawn_subagent 工具允许智能体以自身身份运行一个临时子进程。该子进程会继承父进程的权限范围（参见 [risk_profiles.<alias>].allowed_tools），并将其最终响应返回给父进程的工具循环。
基于提示的模型路由
更窄的机制：[[model_routes]] 允许智能体针对标记了提示字符串的提示词覆盖已配置的 model_provider。当某个智能体需要偶尔切换到不同的模型，而无需启动第二个智能体时，这非常有用。每个路由条目包含一个 hint（提示词必须声明以触发该路由的字符串）、一个 model_provider（要切换到的点分 <type>.<alias> 配置文件，例如 deepseek.reasoner）以及一个 model（提供方本地的模型 id，例如 deepseek-reasoner）。可通过网关、zerocode 或 zeroclaw config set 配置路由；字段架构请参阅 Config reference。
Routes 通常在提示明确带有匹配的提示标记时触发。已启用 effort-routing 的运行时配置文件还可以在提供方执行之前自动选择两个命名路由。
未知的 hint:<name> 会记录警告，并保留在默认可靠性域中，同时将提示的字面值保留为请求的模型。已固定的默认条目仍会提供其活动/默认固定值。未固定的默认条目会转发该字面值，提供方可能会先拒绝该值，然后才继续正常的回退或错误处理。
model_provider 始终是采用点分隔的 <type>.<alias> 形式的提供商配置文件引用，例如 anthropic.sonnet 或 openai.default。该配置文件包含端点、凭据引用、兼容性风格、回退链以及可选的默认模型。model 字段是该配置文件下的提供商本地状态。
**当前限制：**路由固定取决于目标配置。主目标会固定到用于构造路由器的活动/默认模型，即使已识别的提示指向活动的主配置时也是如此；该提示中的
model_routes[].model值不会覆盖主目标的固定模型。配置了配置模型的非主目标会固定到该模型，因此其路由模型同样不会覆盖配置模型。未配置模型的非主目标保持未固定状态，并接收路由模型；其fallback_models不会被实例化，但仍会遍历所引用的回退配置。目标存在固定模型时，请让路由模型与该固定模型保持一致。
基于投入程度的本地/云端路由
effort_routing 代码块位于运行时配置文件上，可以为简单和模糊的对话轮次选择本地路由，为复杂的对话轮次选择云端路由。除非存在该代码块，否则此功能处于关闭状态。它会复用精确匹配、区分大小写的 [[model_routes]].hint 值，因此服务商凭据和模型 ID 仍由现有的路由和服务商配置文件管理。
[[model_routes]]
hint = "local"
model_provider = "ollama.local"
model = "qwen3:8b"
[[model_routes]]
hint = "cloud"
model_provider = "anthropic.sonnet"
model = "claude-sonnet-4-5"
[runtime_profiles.local_first.effort_routing]
local_hint = "local"
cloud_hint = "cloud"
cloud_escalation = "auto"
ZeroClaw 的首个实现使用确定性的复杂度估算器，不会把提示词发送给其他模型进行分类。该估算器按 UTF-8 字节数计算：少于 50 字节且不含推理类关键词的文本判定为简单；超过 200 字节、包含代码围栏，或包含至少两个英文推理关键词的文本判定为复杂；其余情况为标准。简单和标准的对话轮次选择 local_hint。复杂的对话轮次仅在 cloud_escalation = "auto" 时选择 cloud_hint；默认值 "never" 会让所有自动决策都保持在本地。渠道对话轮次会对用户在富化前的文本进行分类，并移除附件标记，因此抓取的链接摘要和编码后的媒体字节不会触发云端升级。
路由决策以轮次为单位进行。日志包含所选目标、复杂度等级、升级策略和消息长度，但不包含消息文本。本地决策会将提供方尝试限制在已配置的本地提供方内，包括流式到非流式的恢复过程，从而确保可用性回退不会悄无声息地将该轮次泄露给云端。云端决策则允许使用已配置的本地和云端提供方引用。
操作员的选择优先于自动 effort 路由。CLI 中的 --provider 或 --model 覆盖会绕过该路由。渠道中的 /model <model-or-hint> 选择会保持生效，不会在下一次可分类的轮次被替换。使用 /model auto 可清除发送者会话的选择，并恢复已配置的自动路由；带范围的 /model --user auto 和 /model --agent auto 会清除对应范围的选择。结构化会话中的 provider 或 model 覆盖对该会话保持显式生效。模型发出的 model_switch 仍受当前 effort 策略约束，且只能选择该轮次允许的 provider 配置文件。
effort_routing 会替代该智能体的 auto_classify 和渠道 query_classification。配置校验会拒绝同时设置 effort_routing 和 auto_classify 的运行时配置文件。对于设置了 effort_routing 的智能体，渠道命令保留 auto 用于恢复自动路由。未设置 effort_routing 的智能体保持现有的模型和路由选择行为，包括名为 auto 的模型或路由提示。
该切片不提供“云端前询问”模式、升级频率限制或单独的成本上限。使用 cloud_escalation = "never" 可使按 effort 路由的模型提供商调用保持在本地;成本控制请使用提供商预算和常规可观测性。此设置不约束无关工具或媒体预处理发起的独立网络或提供商调用。
当所选提供方不支持视觉，且图片轮次需要使用已配置的 vision_model_provider 时，该提供方必须解析为本轮允许使用的本地或云端提供方引用之一。若专用视觉提供方不在该集合内，则本轮采取失败即关闭（fail closed）策略，直接中止。
Effort 路由与相邻工作的关系被刻意限定在较小的范围内：
- Issue #5287 负责处理本地或小型模型被选中后的行为方式。
- Issue #7539 涉及本地模型路由器和发现功能的工作；effort 路由使用已配置的别名，而不是发现模型。
- Issue #7431 涉及的是投递与工具路由意图，而非本地与云端模型选择。
可靠性回退
提供商配置可以声明 fallback_models，用于指定同一端点上的备用模型；也可以声明 fallback，用于指定其他以点号分隔的提供商配置。ZeroClaw 仅在配置具有有效的主模型时才展开 fallback_models；否则，该配置会贡献一个未指定模型的条目。随后，它会以深度优先方式遍历备用配置。每个备用配置都保留其自身的端点、凭据、请求头、可选模型和嵌套的备用声明。
触发速率限制后，实际执行情况可能有所不同：同一配置文件中的条目共享一个冷却键，因此主模型收到 429 后，在冷却期间可能会跳过该配置文件中其余的备用模型。
通过 ZeroCode Config 编辑器、控制面板或 zeroclaw config set 配置链路；请参阅提供商配置。提供商路由生命周期介绍了构建、重试分类、流式恢复、不可重放边界和归因所有权。
运行时模型切换
运行时切换使用与基于配置的路由相同的提供商配置文件契约：
/models <type>.<alias>为发送方会话选择活动的提供方配置文件。当某个提供方系列恰好只配置了一个别名时，频道运行时还可接受裸<type>简写形式。/model <model-id>可在当前活动的提供商配置中选择模型。如果该值通过[[model_routes]]条目解析，该路由可以选择不同的提供商配置。已固定的目标使用其有效固定值，而不一定是model_routes[].model；未固定且未配置提供商配置模型的目标则使用路由模型。model_switch工具使用model_provider = "<type>.<alias>"加上model = "<provider-local-model-id>"。
运行时开关属于会话/运行时状态。它们不会修改 config.toml；持久化默认值需要显式写入配置。对于工具驱动的开关，像 openai 这样的裸供应商系列名称不能作为开关目标，因为它们无法标识应使用哪个已配置的配置文件、凭据、端点或兼容模式。
可观测性
每个智能体的调度决策都可在追踪日志中查看：
INFO channel=telegram.home routed to agent=fast
INFO agent=fast model_provider=anthropic.haiku turn_id=...
INFO model_provider=anthropic.haiku stream complete tokens={input=512, output=128}
对于生产部署，将日志输出连接到 Loki / Grafana。请参阅 运维 → 日志与可观测性。