本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

自动路由

状态：生效范围：当前状态最近审阅：2026-10-10 负责人：ax-code 运行时

自动路由控制 ax-code 中两种彼此独立的路由行为：

关键词路由 — 默认活动。当消息匹配某位专家的关键词或模式时切换代理。它在 1 毫秒内触发，并且不需要 LLM 调用。当路由被显式禁用、用户显式点名了某个代理，或该消息是保留当前代理的合成延续时，会跳过它。
复杂度路由 — 可选，由自动路由开关启用。一次轻量 LLM 调用把每条消息分类为 low、medium 或 high 复杂度。low 复杂度的消息会自动由显式配置的 small_model 来服务，从而降低简单问题的延迟。

默认情况下，自动路由是关闭的 — 复杂度路由被禁用。关键词路由与这个开关分开，除非被配置禁用或被显式的代理选择绕过，否则默认保持活动。

快速开始

从 TUI 切换：

在提示中输入 /smart-llm，或
按下 Ctrl+P 并搜索“自动路由”，或
点击状态栏中的 自动路由开/关 指示

状态栏显示当前状态：

自动路由开启（紫色文字）— 复杂度路由处于活动状态
自动路由关闭（白色文字）— 复杂度路由已禁用（默认）

该设置会跨会话保存在 ax-code.json 中。

它如何工作

权威来源

本页总结面向用户的行为。行为变化时，请对照以下内容核验文档：

packages/ax-code/src/agent/router.ts：关键词路由规则和 classifyComplexity()。
packages/ax-code/src/session/prompt.ts：何时跳过关键词路由，以及何时运行复杂度分类。
packages/ax-code/src/server/routes/smart-llm.ts：默认、环境、配置和持久化行为。
packages/ax-code/src/config/schema.ts：路由配置字段和弃用说明。
packages/ax-code/src/cli/tui/app.tsx：斜杠命令名称、别名、标签和状态栏操作。
packages/ax-code/test/agent/router.test.ts 以及 TUI 同步测试：预期的激活行为。

不要把关键词路由和快速模型复杂度路由描述成同一个功能。它们是有意分开的。

关键词路由（默认活动，小于 1 毫秒）

用户消息会与每个专家代理（安全 security、架构 architect、调试 debug、性能 perf、运维 devops、测试 test）的关键词和正则模式匹配。如果匹配得分的置信度 ≥ 0.4，代理可以立即切换 — 不会进行 LLM 调用。这条路径独立于自动路由开关，但当路由被禁用、用户显式点名了某个代理，或当前回合为了合成延续而保留现有代理时，会跳过它。

复杂度路由（仅自动路由，约 200–500 毫秒）

启用自动路由时，每条消息都会通过 classifyComplexity() 发给一个快速/廉价模型。这次 LLM 调用返回复杂度估计（low / medium / high）：

low 复杂度的消息自动使用显式配置的 small_model
medium 和 high 消息照常使用默认模型
如果 small_model 缺失或不可用，则跳过
1.5 秒超时 — 如果 LLM 很慢或不可用，会静默回退
所有错误都被静默捕获 — 从不会挡住用户

复杂度路由独立于代理路由。它不会分类该使用哪位专家代理 — 那完全由关键词路由处理。

自动路由有什么帮助

场景	没有自动路由	有自动路由
“这个变量做什么？”	使用完整模型	`low` 复杂度 → 快速模型
“列出此文件中的全部导出”	使用完整模型	`low` 复杂度 → 快速模型
“扫描漏洞”	关键词路由到安全	相同 — 关键词路由总会触发
“跨 8 个文件重构认证模块”	默认模型	`high` 复杂度 → 默认模型
“这个函数很迟钝”	没有关键词匹配，没有路由	`low`/`medium` → 正确的模型档位

关键词路由根据技术关键词处理专家代理选择。复杂度路由根据答案需要多少推理来选择合适的模型档位。

缺点与注意事项

延迟

复杂度路由会给定触发分类调用的消息增加 200–500 毫秒。关键词路由（始终活动）不受影响 — 无论怎样它都在 1 毫秒内返回。

需要一个小模型

复杂度路由需要显式的 small_model 配置。AX Code 不会从模型名称推断辅助模型，也不会把不可用的钉选移到另一个提供商。没有可用的辅助模型时，会跳过分类并保留所选的主模型。见模型恢复。

token 用量

每次分类调用大约使用 100–200 个输入 token 和 10–20 个输出 token — 与随后的主 LLM 调用相比可以忽略。

不能代替显式选择

自动路由改善自动的模型档位选择，但不能仅凭自然语言路由到专家代理。对于专家是否正确很关键的任务，通过代理选择器或 @agent 提及来显式选择代理更可靠。

配置

从 TUI 切换

使用 /smart-llm 或命令面板（Ctrl+P → “打开/关闭自动路由”）。变更立即生效，并保存到项目的 ax-code.json。

配置文件

{
  "routing": {
    "llm": true
  }
}

环境变量

AX_CODE_SMART_LLM=true ax-code

环境变量会覆盖配置文件设置。

自动路由与其他设置

设置	交互
自主模式	自动路由独立工作。代理路由和复杂度分类发生在权限检查之前。
沙盒模式	没有交互。自动路由只影响选择哪个代理和模型档位，不影响代理能做什么。
模型选择	自动路由开启且没有显式钉住模型时，`low` 复杂度的消息使用显式配置的 `small_model`。
执行模式	混合放置（`modes.default: "hybrid"`）是分开的：它选择本地还是云端。见执行模式。

何时启用自动路由

在以下情况启用：

你希望简单问题自动路由到更便宜、更快的模型
你希望降低低复杂度交流的 token 成本
你使用的提供商有可靠的小型/flash 模型

在以下情况保持禁用：

你希望每条消息都没有额外延迟
你离线工作，或网络不可靠
你希望把 token 用量降到最低
你总是显式钉住一个模型