Claude Code 小课 · 2026年9月18日

2026-09-18 · 当日主题选定理由:v2.1.273 于 09-15 发布、09-16 起被广泛验证,是过去 48 小时内 Claude Code 唯一的重大版本。这一版 64 项改动里几乎没有花哨新功能,全是每天都会踩到的东西:长会话被提前压缩、subagent 结果丢失、权限规则没真正生效。按由浅入深排,四条。

来源:官方 CHANGELOG · Claude Code Changelog 文档 · DevelopersIO v2.1.273 逐条解读(2026-09-16)

技巧 1(入门):先升级,然后确认你的上下文窗口「变大了一倍」

问题:v2.1.273 之前,上下文计量器和 auto-compact 把 advisor 工具轮次按实际体积的约两倍计数。结果就是:明明还剩一半窗口,auto-compact 却已经开始压缩了。长会话用户长期以来的「怎么这么快就压缩」并不是错觉,是个 bug。

动作:

# 1. 升级(原生二进制自更新)
claude update

# 2. 确认版本 ≥ 2.1.273
claude --version

# 3. 进会话后,拿同一个项目跑一遍你最长的那个任务,看 /context
#    对比升级前的截图:同样的对话深度,占用百分比应该明显下降

会话内查看上下文占用:

/context

怎么判断修好了:跑一个会大量调用工具的任务(比如全仓检索 + 多文件编辑),观察 auto-compact 触发点。升级前若在「看起来还剩 50%」时就触发,升级后应推迟到接近真实阈值。

顺带:如果你之前为了绕开这个 bug 把 autoCompactThreshold 之类的设置调歪过,现在该调回来了。

技巧 2(日常):把「subagent 莫名失败」从你的工作流里划掉

问题:v2.1.273 修了一个很隐蔽的 bug —— 当流式响应末尾缺少 token 用量或缺少 model ID 时,subagent 和后台 agent 会被判定为失败,结果不投递。重度使用 subagent 的工作流里,这表现为「偶发的、无法复现的、没有错误信息的失败」。同时修了另一个:当 subagent 在执行途中被移到后台(例如设了 CLAUDE_AUTO_BACKGROUND_TASKS),SDK 与 --output-format stream-json 的输出会丢掉剩余消息和最终报告。

动作 —— 升级后用一个最小脚本验证 subagent 结果确实回来了:

# 无头模式跑一个必然派发 subagent 的任务,把结构化输出落盘
claude -p "用 3 个并行 subagent 分别审查 src/api、src/db、src/web 三个目录的错误处理，\
每个 subagent 返回不超过 5 条发现，最后你汇总成一张表" \
  --output-format stream-json \
  > /tmp/subagent-check.jsonl

# 检查:每个 subagent 都应该有完整的结束事件,而不是中途断掉
grep -c '"type":"result"' /tmp/subagent-check.jsonl
python3 -c "
import json,sys
for line in open('/tmp/subagent-check.jsonl'):
    e=json.loads(line)
    if e.get('subtype') in ('error','error_during_execution'):
        print('异常事件:', e)
"

如果你有 CI 里跑的 subagent 流水线,这一版之后值得把历史的「随机失败重试」逻辑重新评估一遍——很可能不再需要了。

技巧 3(团队/进阶):复核你的权限与管理设置是不是真的生效了

这一版有 8 项安全修复,其中 3 项都是同一类问题:你配了限制,但它没生效。逐条对照检查:

# A) permissions.blockReadsOutsideWorkingDirectories
#    旧版:权限检查器解析不了的 Bash 命令会跳过确认提示;
#         bypass 模式下子 shell 里的危险 rm 能被藏住。
#    检查方式:在一个临时项目里开启该设置,然后试探性地跑
claude --print "运行 bash: eval 'cat /etc/hosts'"
#    期望:弹出确认提示(而不是直接读)

# B) 同一设置的另一处缺口:仓库设置里指定的 memory 目录
#    旧版仍会被用于 prompt 载入 / recall / 索引 / 记忆抽取。
#    检查 .claude/settings.json 里是否有指向工作目录之外的 memory 路径
grep -rn "memory" .claude/settings.json

# C) MDM / managed-settings.json 下发的三项设置,
#    在同时存在 server 管理设置时会被忽略:
#      allowManagedMcpServersOnly / deniedMcpServers / disableClaudeAiConnectors
#    升级后实地验证:列出实际加载的 MCP server,确认被禁的确实不在
claude mcp list
/doctor

另一个必须知道的反向变更(回滚):v2.1.268 曾把 Read/Edit 的 deny 规则套用到权限检查器解析不了的 Bash 行(如 eval、env -C),v2.1.273 把它回滚了。也就是说 time -p make build 这类命令不再被直接拒绝,而是回到确认提示。如果你在 v2.1.268~v2.1.272 期间依赖 deny 规则做硬限制,行为已经变了,升级后务必重新验证你的规则集。

# 把你的 deny 规则列出来逐条过一遍
cat .claude/settings.json | python3 -m json.tool | grep -A20 '"deny"'

还有一条容易漏的:组织关闭 Skills 后,从 claude.ai 同步下来的 skill 旧版仍可继续使用;这一版改为移入可恢复的回收站。管理员关过 Skills 的团队,升级后确认一遍。

技巧 4(平台/进阶):给 LLM 网关装上 Claude Code 的「行为提示头」

新增能力:v2.1.273 新增 5 个发给 LLM 网关的请求头,让网关侧第一次能区分「这次请求是什么性质」:

Header	含义
`x-claude-code-request-class`	请求类别
`x-claude-code-agent-type`	发起请求的 agent 类型
`x-claude-code-prev-tool-durations`	上一轮工具耗时
`x-claude-code-compaction`	是否是压缩相关请求
`x-claude-code-context-compacted`	上下文是否已被压缩过

默认关闭,需显式开启:

# 单次会话开启
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 claude

# 团队常开:写进项目的 .envrc(direnv)或启动脚本
echo 'export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1' >> .envrc
direnv allow

为什么值得开:配合第 27 课讲过的 OTLP 遥测,这组头把成本归因从「这个项目花了多少」细化到「主会话 vs subagent 花了多少、压缩本身花了多少、哪类请求在慢」。网关侧(LiteLLM / 自建反代)可以直接按 x-claude-code-agent-type 分桶统计。

同一版还改进了 OTEL_LOG_TOOL_DETAILS=1:成本与 token 指标里现在会带上真实的 agent 名、skill 名、plugin 名和 MCP server 名,而不再只是匿名标识:

CLAUDE_CODE_ENABLE_TELEMETRY=1 \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOG_TOOL_DETAILS=1 \
claude

这两项合起来,是第 27 课那套看板这半年来最实质的一次精度提升——之前只能看到「某个 subagent 很贵」,现在能看到「是 security-review 这个 skill 很贵」。

本课小结

你是谁	这一版最该做的事
跑长会话的个人开发者	升级,重新体感 auto-compact 触发点(技巧 1)
重度 subagent / CI 用户	升级并去掉为「随机失败」写的重试兜底(技巧 2)
团队/组织管理员	逐条复核三处权限缺口 + 确认 v2.1.268 deny 规则回滚的影响(技巧 3)
自建网关 / 有可观测看板	打开 `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` 与 `OTEL_LOG_TOOL_DETAILS=1`(技巧 4)

已知不可用:Remote Control 会话的 fork 虽已在 changelog 中列为新功能,但第三方在 iPhone 端 Claude app、桌面端(2.110.0)与 web 端实测均返回 /fork isn't available over Remote Control.,终端侧同样如此。暂时别把它排进工作流。(实测记录)

相关旧课:第 8 课(上下文管理)、第 9 课(权限与沙箱)、第 27 课(可观测性)、第 31 课(周配额)。