Claude Code 环境变量里的超时与开关陷阱

Claude Code 把四分钟的测试跑到一半就报超时，未必是测试出了问题，也可能只是 Bash 工具默认只等两分钟。作者从这类误判出发，梳理了 10 个环境变量，涉及命令执行、模型选择、推理投入、账号配置和网络请求。

最值得带走的不是一份配置清单，而是两个判断：同名配置放在哪里，会影响它是否生效；变量看起来像布尔值，也未必按布尔值解析。原文依据的是 2026 年 10 月 15 日读取的文档，具体行为需要结合版本看。

测试没跑完、日志没读全，都会让 Agent 判断失真

Agent 执行命令时，至少受两道限制：命令能运行多久，以及结果能返回多少字符。

BASH_DEFAULT_TIMEOUT_MS 控制前台 Bash 命令的默认超时，默认 120000 毫秒，也就是两分钟。作者用四分钟的集成测试举例：工具先超时，Agent 接到失败结果，接下来可能去排查一个并不存在的代码问题。

原文给出的调整值是 300000，即五分钟。另一个变量 BASH_MAX_TIMEOUT_MS 默认 600000，即十分钟，控制模型为单条命令请求的超时上限。按原文，两者形成的有效上限取较大值。

需要每次启动都生效，可以把配置写进 settings 文件：

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

注意 env 中的值是字符串。~/.claude/settings.json 覆盖所有项目，仓库里的 .claude/settings.json 可以随项目共享；同名变量同时存在于 shell 和 settings 时，作者称 settings 通常会覆盖继承的 shell 值。

日志则由 BASH_MAX_OUTPUT_LENGTH 控制，默认 30000 字符，最大 150000，原文示例提高到 80000。长构建日志里的关键错误可能没被完整返回，但多读日志也会占用上下文。如果已经设置 bashOutputMaxChars，这个环境变量会被忽略。

生成结果还有另一道限制：CLAUDE_CODE_MAX_OUTPUT_TOKENS。原文示例设为 64000；不同模型有各自的默认值和上限，超出上限会被压回去。遇到无法识别的模型 ID，原文列出的默认值是 32000，上限是 128000。

日志读得更多、回答允许更长，都要从上下文预算里付账。

因此，大文件生成被截断和构建日志读不全，需要分别处理，不能靠一个「调大输出」的开关解决。原文还提醒，更高的输出 token 配额会压缩自动整理上下文之前的可用空间。

模型和推理强度，为什么会出现相反的优先级

ANTHROPIC_MODEL 可以填别名 opus、sonnet、haiku、fable，也可以填完整模型名。原文称，在 Anthropic API 上，opus 和 sonnet 分别解析到 Opus 5.5、Sonnet 5.5。这是作者记录的文档口径，不宜当作永久映射。

它的优先级是：会话里的 /model 和启动参数 claude --model 都高于环境变量，环境变量又高于 settings 中的 model 字段。

偏偏推理投入的规则相反。

CLAUDE_CODE_EFFORT_LEVEL 支持 low、medium、high、xhigh、max，以及使用模型默认值的 auto。原文列出的 Opus 5.5、Sonnet 5.5、Haiku 5.5 默认都是 medium，其他多数支持 effort 的模型默认是 high。

这个环境变量会覆盖 --effort、/effort 和 effort 设置。原文还称，只有通过它配置，才能让 max 持续生效；其他方式设置的 max 只维持当前会话。

如果要按任务选择 effort，就不要在全局 shell 配置里固定它。

否则，启动器界面明明选了另一个等级，实际执行仍可能被环境变量覆盖。

子 Agent 则由 CLAUDE_CODE_SUBAGENT_MODEL 提供默认模型，适用于未通过其他方式指定模型的子 Agent、agent-team 队友和 workflow agents。作者用 haiku 举例，希望主会话使用大模型，辅助任务使用便宜模型。但创建 Agent 时传入的模型，以及 Agent 定义中的 model 字段，仍然优先；强制统一则另有 CLAUDE_CODE_SUBAGENT_MODEL_FORCE。

还要区分 effort 与 MAX_THINKING_TOKENS。后者名字像固定思考预算，但自适应推理模型会忽略正数，自行决定深度。设为 0 可以在 Anthropic API 上关闭部分模型的思考，但原文明确排除了 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 系列。

Opus 4.6、Sonnet 4.6 可以用 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 回到固定预算。对原文列出的 5.5 模型，应关注 effort，而不是期待旧变量继续生效。

隔离账号、冻结更新、关闭流量，是三件不同的事

CLAUDE_CONFIG_DIR 修改默认的 ~/.claude 配置目录，其中包含设置、会话历史和插件。作者引用的别名是 alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'，用于并行使用不同配置。

它适合工作与个人环境分开，也适合用干净配置测试插件。但凭据有独立规则，不能直接把「换目录」理解成完整的账号隔离保证。这个变量可以放在 shell 或用户设置中；写进 settings 时要用绝对路径，项目设置和本地设置会忽略它。

更新方面，DISABLE_AUTOUPDATER=1 只停止后台自动更新，手动 claude update 仍可用。更严格的 DISABLE_UPDATES=1 还会阻止 claude update 和 claude install，面向自行分发 Claude Code 的团队。

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 的影响更广：自动更新、遥测、错误上报、/feedback、发布说明、PR 状态徽标检查、可用性检查都会受影响。它还关闭功能标记获取，因此 Remote Control 等依赖功能标记的能力会不可用。

如果只想关闭错误上报，可以看 DISABLE_ERROR_REPORTING；DISABLE_TELEMETRY 则会关闭遥测，并按原文描述同时关闭功能标记获取。原文称遥测事件不包含代码、文件路径或 Bash 命令，但没有提供抓包验证。

标题里的陷阱，来自这些变量的解析方式：

export DISABLE_TELEMETRY=0   # 仍然退出遥测
unset DISABLE_TELEMETRY      # 恢复默认行为

注意第一行：这里检查的是值是否非空，0 仍然会触发禁用。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DISABLE_ERROR_REPORTING 都属于这种情况。恢复默认要 unset，或者设为空字符串，不能照搬普通布尔变量接受 1/true/yes/on、0/false/no/off 的直觉。

我的判断

这份清单最有价值的部分，是提醒读者检查工具边界和配置优先级。命令超时、日志截断、参数被覆盖，都可能让 AI 编程过程看起来像模型判断出了问题。

但原文主要整理文档，没有给出调整前后的耗时、成功率、成本或模型对照数据。主 Agent 用大模型、辅助 Agent 用便宜模型，是一种配置思路；是否划算，还取决于任务能否拆开，以及返工成本。

作者把超时、自动更新和非必要流量开关归为可以长期固定的配置，我会更谨慎。超时需要匹配项目命令，冻结更新需要配套升级安排，关闭流量还会影响 Remote Control。它们都有适用前提。

作者同时开发 Hermes IDE，后半段有明确的产品推广目的。其按任务保存模型、effort 和账号的思路可以借鉴，但原文没有证明它比 shell 脚本或团队配置更好。也别忽略：settings 中的 env 由 Claude Code 自行读取，换启动器并不会自动绕过它。

能拿来做什么

• 遇到前端构建、集成测试或容器构建中途失败，先检查实际耗时是否撞上 120000 毫秒，再判断是否需要提高超时，避免让 Agent 围着工具限制反复改代码。
• 排查长日志时，按任务提高 BASH_MAX_OUTPUT_LENGTH，同时检查有没有 bashOutputMaxChars 覆盖它；生成大文件被截断时，再单独检查 CLAUDE_CODE_MAX_OUTPUT_TOKENS。
• 使用脚本、IDE 或 CI 启动 Claude Code 时，同时核对 shell 和 settings 中的 env。需要按任务切换 effort，就清理长期固定的 CLAUDE_CODE_EFFORT_LEVEL。
• 把关闭遥测、冻结更新和切换配置目录分别记录清楚。恢复这几个按非空值判断的禁用开关时，使用 unset 或空字符串。