Claude Code 2.1.269：一个 60 项修复包里藏着的三个 operator 级变更

Claude Code 2.1.269 今天早上落地，changelog 里超过六十条单独变更。大多数读起来像终端兼容性补丁，某些冷门终端模拟器的光标渲染，SSH 慢连接时的乱码字符，那种只有撞上的人才在意的问题。埋在这些项目里，有三个变更是以团队或企业规模运行 Claude Code 的 operator 在下次会话前应该读的。

gateway discovery 的超时一直是写死的三秒

Claude Code 启动会话时，如果配置了自定义 LLM gateway，会在发出第一个请求前先探测 /v1/models 来发现可用模型。这个探测有一个硬编码的三秒超时，没有任何办法调整。

对于跑在同一局域网的 gateway，三秒够用。但在两种常见的生产配置下会出问题。第一是 gateway 有冷启动路径，比如 Lambda、Cloud Run 或其他 function-as-a-service 后端；第二是 gateway 挂在有检查开销的企业代理后面。会话会在模型发现阶段超时，退回默认值，然后静默地路由到和配置不一样的地方，或者直接会话失败。

2.1.269 加入了 CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS，单位毫秒，覆盖三秒默认值。

export CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=10000  # 10 秒

如果你通过有非平凡冷启动延迟的企业 gateway 路由 Claude Code，这个环境变量应该和 ANTHROPIC_BASE_URL 放在同一个部署配置里。以前的变通方法是在会话启动前预热 gateway endpoint，现在不需要了。

对于本地托管的 gateway，三秒默认值本身没问题，不需要改大，除非你实际观察到 discovery 失败。

并发 workflow agent 现在有了 operator 可设置的上限

Workflow 工具让 Claude Code 能把工作分发给并行的子 agent。2.1.269 之前，每次运行的并发 agent 上限由 Claude Code 内部决定，operator 没有控制手段。一个任务分解成很多并行分支时，实际并发度取决于模型自己的判断。

2.1.269 加入了 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS，接受 1 到 256 之间的整数。

export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=8

这个参数往两个方向都有意义。对于关心推理成本的团队，并行 agent 会同时消耗配额，这个上限限制了突发并发，但不会限制 Workflow 工具本身能做什么。超出上限的工作会排队而不是报错。对于想要比 Claude Code 内部默认值更激进的并行度的团队，设高于默认值的数值可以解锁这一点。

实际应该设多少，取决于你的 provider 的速率限制和团队的成本预算。对着有分级配额的 gateway 运行 Claude Code 的团队，应该把这个参数和连接池大小一样对待，设一次，在最初几个并行 workflow 上监控 token 消耗，然后调整。

以 ! 开头的 deny rule 在悄悄跨越配置源生效

这是本版本里实际影响最大的一个变更，changelog 里的描述很容易被低估。原文是「Fixed a deny or ask permission rule starting with ! applying beyond the settings source that wrote it; such a rule now applies only within its own source, and a bare ! negation is ignored.」

Claude Code 从多个来源按层级应用权限规则，包括组织 managed settings、项目级设置、用户设置、本地 .claude/settings.json。以 ! 开头的 deny rule 是一种否定写法，用来把某个路径从更宽泛的 allow 里排除出去。这个 bug 导致那些否定规则被当作全局规则处理，而不只是写它的那个来源的局部规则。一个写在项目 .claude/settings.json 里的 ! 规则，会静默地把效果延伸到组织级别的 allow grants 里。

实际后果是这样的。如果你写了一个项目级 ! 规则来在项目范围内做例外，那个例外同时也在限制组织管理员预期完全生效的 org 级 allow。根据那些 allow 覆盖的范围，一个团队可能一直在以比预期更严格的限制运行，也可能在某些配置下宽松了。

修复是精确的，每条 ! 规则现在只作用于写它的那个来源。在现有配置里依赖旧的（错误的）跨源行为的团队，升级后实际行为会变化。在把 2.1.269 推给整个机队前，逐层检查你的权限规则配置，确认预期的作用域。

这个问题对 Bedrock 和 Vertex 部署同样适用，使用 managed settings 的走的是同一套权限管道，跟后端 provider 无关。

两个 prompt cache 修复对长跑 agent 的影响

2.1.269 里有两个 cache 修复，主要影响长时间运行或多轮 agent 会话。

第一个修复，在 output token limit 截断后 auto-resume 时，下一轮的 prompt cache 会被部分失效。经常跑到 output token limit 的大上下文 agent，在 resume 那轮本来应该命中缓存的 input token，实际上在按未缓存价格计费。

第二个修复，在 Claude 思考中途打断会话再恢复时，早期上下文的重新发送方式可能变化，损害恢复轮次的 cache 复用。这两个问题叠加时影响更明显。一个既经常被打断、又经常触达 output token limit 的会话，在两个时机都在损失 cache 复用。

两个修复都不需要配置变更，升级后自动生效。

需要检查的几件事

如果你通过自定义 endpoint 路由 Claude Code 会话，把 CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS 加到你的部署配置里，和 ANTHROPIC_BASE_URL 放在一起。设一个比你 gateway p95 启动延迟高出足够余量的值。

如果你在 fan-out 工作负载里用 Workflow 工具，把 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 设成和你 provider 速率限制匹配的值。超出配额产生的突发并发会产生可重试错误，但那些重试消耗你的速率限制窗口，给整个 workflow 加延迟。

在把 2.1.269 推给现有机队成员前，先检查你的权限规则配置，特别是项目或本地作用域里用了 ! 否定写法的规则。这个变更是正确的修复，但对依赖旧的跨源传播行为的配置，实际效果会变。

相关历史报道见 Claude Code 2.1.268 gateway 修复，Claude Code 2.1.266 gateway 回归。