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

多模型路由最佳实践

状态：生效范围：公开，当前状态最近审阅：2026-09-13 负责人：ax-code 运行时

本指南记录推荐做法：用一个高价推理模型，以及同一提供商更便宜的辅助模型来运行 ax-code。

核心原则

把昂贵模型用于推理密集的工作，把便宜模型用于机械或只读工作。真正的节省来自上下文过滤：高价模型只看到由更便宜的模型或子 agent 准备好的提炼上下文。

推荐分层

层	模型类别	典型 agent / 任务
工人 / 执行者	可用时使用已连接的 flash SKU（例如 DeepSeek Flash）	未钉住的会话、`build`、`general`、`scout`、`test`、`devops`、`perf`
顾问 / 推理	更强的已连接模型（例如 DeepSeek V4 Pro）	`plan`、`architect`、`security`、`debug`
便宜 / 只读辅助	同一 flash SKU	`explore`、`compaction`、标题、回顾、低复杂度分类

钉住已连接的 provider/model ID。已禁用的第一方计划 ID（alibaba-token-plan、deepseek、zai-coding-plan、minimax-coding-plan）仍按 SKU 解析，但每次调用会先尝试已禁用的提供商并发出警告。Qwen 3.8 Max 是有效的显式选择，不是产品默认，也不是示例默认；没有 config.model 时，隐式默认按此顺序遍历已连接目录：deepseek-flash、glm-5.3-flash、qwen3.8-flash、MiniMax-M3、grok-4.6、claude-sonnet-5、gpt-6、gemini-3.8-flash、qwen3.8-27b。

配置模板

仓库根目录的 ax-code.json.example 给出一份具体示例：默认使用 DeepSeek Flash，推理 agent 使用 Pro。

Codex CLI 辅助模型

Codex 模型是否可用，取决于账户的登录方式和客户端，而不只取决于目录中的文本或工具能力。因此 AX Code 不会从名称或家族元数据推断 codex-cli 小模型。没有显式的 small_model 或压缩 agent 模型时，压缩使用会话模型。

如果配置了辅助模型，请用同一 Codex 登录验证它确实可用。当 Codex 明确拒绝某模型不支持 ChatGPT 账户时，压缩可以尝试一次会话模型，并跳过其他小模型。被拒绝的尝试仍留在会话历史中。其他身份验证、计费、校验、取消和上下文溢出失败保留其既有处理；本地提供商隐私防护仍然适用。

对于受影响的较旧安装，移除不兼容的 small_model 或 agent.compaction.model 覆盖，并把 agent.compaction.model 显式钉到已经用该 Codex 账户验证过的模型。只改可见的会话模型，不会覆盖单独钉住的压缩模型。

按任务类型自动路由的规则

请不要把所有低价值任务都自动路由到便宜模型。按失败代价拆分：

可以自动路由（只读，或可由人审阅）：
- 仓库探索、grep/搜索分诊、文件分类
- 代码摘要、日志摘要、代码解释
- 为高价模型准备上下文
- 文档
仅在选择加入时（机械上可验证，但可能掩盖行为变化）：
- 样板代码、lint 修复
默认绝不自动路由（静默错误代价高）：
- 单元测试
- 重命名与重构
- 简单 SQL
- API 包装
- 简单 CRUD

最后一组应留在会话模型上，除非用户显式钉住更便宜的模型。

操作手册

非平凡任务从 plan 模式开始，让顾问在工人写代码之前校验设计。
如果工人循环，或验证失败两次，切换到 debug，并带上失败信号。
当两种修复都说得通时，用 council 做独立诊断，而不是用来完成任务。
把手动切换模型留给罕见的推理沉重轮次；之后切回去。

已知的 ax-code 限制

Provider.getSmallModel() 返回 undefined，当提供商目录既没有标记带层级的 family，也不匹配硬编码优先级列表时；辅助调用随后回退到会话模型（日志记为“no small model for provider”）。
没有从卡住的工人在运行中途升级到更强模型的机制。