Claude Code子代理模型配置：让Explore跑在Haiku 5.5上

Claude Code 的 Explore 子代理默认跟随主模型运行，仅靠设置 CLAUDE_CODE_SUBAGENT_MODEL 环境变量并不能把它切换到 Haiku 5.5。本文基于实际测试，给出三种可行的配置方案。

问题背景：为什么环境变量不生效

Claude Code 在架构上区分了「主模型」与「子代理模型」。Explore 子代理负责代码库探索、文件检索等辅助任务，理论上适合用更轻量、更便宜的模型来执行。但实际使用中会发现，即便设置了 CLAUDE_CODE_SUBAGENT_MODEL，Explore 依然跑在主模型上。

这说明 Claude Code 对子代理的模型绑定并非全部走同一个环境变量。Explore 可能有独立的模型解析逻辑，或者配置项的优先级高于环境变量。理解这一点，是找到正确配置方式的前提。

Claude Code 的模型层级与子代理体系

Claude Code 是 Anthropic 推出的命令行 AI 编程工具，其架构中存在「主模型」与「子代理（subagent）」两个概念。主模型负责对话、推理和代码生成等核心任务；子代理则是在主模型调度下、针对特定任务启动的独立执行单元。Claude Code 内置了多个子代理，例如 Explore（代码库探索）、Plan（规划）等，各自承担不同职责。

这种设计的意义在于将复杂任务拆分：主模型专注于理解和决策，子代理负责执行检索、遍历等辅助工作。由于不同子代理的任务复杂度差异很大，理论上应允许为每个子代理绑定不同的模型——例如探索类任务用便宜快速的 Haiku，核心推理用能力更强的模型。

问题在于，Claude Code 的模型解析逻辑并不统一。某些子代理会读取 CLAUDE_CODE_SUBAGENT_MODEL 环境变量，某些则走配置文件或专属解析路径。Explore 恰好属于后者，因此单设环境变量无效。理解这套层级结构，是排查所有「模型配置不生效」问题的起点。

三种把 Explore 切到 Haiku 5.5 的方法

方法一：通过配置文件覆盖子代理模型

绕过环境变量，直接在 Claude Code 的配置文件中为子代理指定模型。配置文件的优先级通常高于环境变量，能够覆盖 Explore 的默认解析路径。这种方式适合需要长期稳定使用 Haiku 5.5 的场景，配置一次即可持续生效。

方法二：在调用层指定模型参数

通过 Claude Code 的接口或调用参数，在触发 Explore 子代理时显式传入模型标识。这种方式粒度更细，可以针对特定任务切换模型，而不影响其他子代理的行为。适合需要在不同任务间灵活切换模型的开发者。

方法三：调整子代理的模型解析顺序

如果前两种方式仍不生效，问题可能出在模型解析的优先级链上。通过调整配置项的加载顺序，或覆盖 Explore 专属的模型设置，可以强制其使用 Haiku 5.5。原文作者通过多轮测试验证了这一路径的可行性。

三种方法各有适用场景：配置文件适合长期固定，调用参数适合精细控制，解析顺序调整适合解决疑难情况。

关于 Haiku 5.5 与 Claude 模型分级

Anthropic 的 Claude 模型通常按能力与价格分为三档：Haiku（轻量快速）、Sonnet（均衡）、Opus（旗舰强大）。Haiku 系列定位为低延迟、低成本，适合高频调用但对推理深度要求不高的任务，如文件检索、简单分类、代码库遍历等。

「Haiku 5.5」指该系列的一个具体版本，其能力足以胜任 Explore 子代理的探索类工作，同时单价和响应时间都显著优于 Sonnet/Opus。把 Explore 绑定到 Haiku，正是利用了模型分级的性价比梯度：把便宜模型放在简单任务上，把昂贵模型留给真正需要深度推理的环节。

此外，「配置优先级」也是一个关键概念。在 Claude Code 中，模型来源可能同时存在多处：环境变量、项目配置文件、用户全局配置、调用时显式传参。它们的覆盖顺序决定了最终生效值，通常「越具体、越接近调用点」的配置优先级越高。这也是为什么环境变量会被配置文件覆盖的根本原因。

测试验证与实际效果

原文作者对三种方式都进行了测试运行（test runs），确认 Explore 子代理能够正确切换到 Haiku 5.5。测试的意义在于验证配置确实生效，而非仅仅「看起来设置了」。

对于日常使用 Claude Code 的开发者来说，把 Explore 放在 Haiku 5.5 上有两个直接收益：一是降低主模型的 token 消耗，二是加快探索类任务的响应速度。Explore 属于高频但相对简单的操作，用轻量模型处理是更经济的选择。

对开发者的实践建议

如果你也在使用 Claude Code 并希望优化成本，建议按以下顺序排查：先确认当前 Explore 实际运行在哪个模型上，再尝试配置文件覆盖，最后考虑调用层参数或解析顺序调整。不要假设设置环境变量就万事大吉。

这类配置问题的本质，是工具在抽象层面对不同组件做了差异化处理，而文档往往不会把每一条解析路径都写清楚。遇到「设置了但不生效」的情况，从配置优先级和组件专属逻辑入手，通常比反复尝试环境变量更有效。

系统排查「配置不生效」问题的通用思路

这类问题本质上是「配置优先级链」问题，而不仅限于 Claude Code。在任何具备多层级配置的工具中（如 Git、npm、各类 CLI），都存在系统级、用户级、项目级、调用级的多重覆盖关系。排查时应遵循自下而上的原则：先确认运行时实际生效的值，再逐层回推是哪个配置项在覆盖。

具体到 Claude Code，可以通过在会话中观察当前使用的模型标识、查看配置加载日志、或使用调试命令来确认实际模型。不要凭「我设置了」就断定生效——很多问题的根源是配置被更高优先级的来源覆盖，或指定了错误的键名。

另一个通用教训是：文档通常只描述「常见路径」，而工具的差异化逻辑（如某个子代理有专属解析代码）往往不写在文档里。遇到疑难配置问题，从「组件专属逻辑」和「优先级顺序」两个角度入手，比反复试错环境变量更高效。