Mingyu's Library主页
2026年9月11日

第 29 课:新功能速用 —— v2.1.267 / v2.1.268

日期:2026-09-11 · 版本:v2.1.267(9/9)、v2.1.268(9/10) 主题:effort 封顶、system prompt 快照、插件命令 JSON 化、WebFetch 死线、gateway 定价对齐 前置:第 15 课(成本控制)、第 17 课(插件与 Marketplace)、第 23 课(/effort 会话级覆盖)、第 27 课(可观测性)。 来源:Claude Code changelog

这两个版本没有惊天动地的新玩法,但有四个「装上就一直在帮你省事」的小开关。按由浅入深排列。

技巧一:maxEffortLevel —— 给 effort 档位上一个不会被绕过的天花板

第 23 课讲过 /effort 可以做会话级覆盖,第 15 课讲成本控制时,effort 是最容易失控的一根杠杆:随手一句「仔细想想」就可能把一整晚的后台任务顶到最高档。v2.1.267 补上了缺的那一半——封顶。

maxEffortLevel 可以写在设置顶层,也可以写在 modelSettings 里按模型分别设置。关键点:它在所有 provider 上生效,包括 Bedrock、Vertex 和 Microsoft Foundry;用户仍然可以主动往低了选,但选不上去。

顶层封顶(整个项目一刀切):

// .claude/settings.json
{
  "maxEffortLevel": "medium"
}

按模型分别封顶(贵的模型压低,便宜的模型放开):

// .claude/settings.json
{
  "modelSettings": {
    "claude-opus-5": { "maxEffortLevel": "low" },
    "claude-fable-5-1": { "maxEffortLevel": "high" }
  }
}

什么时候用:① 定时任务 / CI 跑的无头会话——它们没人盯着,跑飞了只有账单知道;② 团队里把 maxEffortLevel 写进 managed settings,给新人一个不会踩雷的默认值;③ 自己在探索期开高档,进入批量执行期时把项目级设置压下来。

顺带一提:v2.1.268 修了「组织管理员给某模型设了 effort 上限时,routine 恢复会话或会话未设 effort 会报 Invalid effort level」——如果你在 Claude Code on the web 上踩过这个,升级即可。

技巧二:--system-prompt-snapshot off —— 调 prompt 时别再被快照坑

默认情况下,一个会话会记录并复用它启动时渲染出的 system prompt。这对缓存是好事(前缀稳定 = 缓存命中),但对「正在改 prompt 文本」的人是灾难:你改了 CLAUDE.md、改了 agent 文件、改了 output style,重新发一条消息,生效的还是旧快照,于是你以为改动没用,开始怀疑人生。

v2.1.268 给了显式开关:

# 迭代 prompt 时:每次请求都重新渲染 system prompt
claude --system-prompt-snapshot off

什么时候用:只在写/调 prompt 的那一小段时间开。写 skill 描述、调 subagent 的 system prompt、试 output style 措辞时开着,改一行发一句,立刻看到差别。

什么时候一定要关掉:日常干活和 CI。每次重渲染 = 前缀可能变化 = prompt 缓存作废,成本和延迟都会明显变差(第 15 课算过这笔账)。把它当成一个「调试模式」,不是常驻配置。

配套一条:同版本还修了 SDK 会话用 excludeDynamicSections 时「prompt 缓存和 extended thinking 会话中途失效」的问题——第一条消息不再每次请求重新渲染。如果你用 Agent SDK 且观察到缓存命中率莫名塌方,升级看看。

技巧三:claude plugin ... --json —— 让插件管理能被脚本接管

第 17 课把插件讲成「把配置打包分发」,但落到自动化上一直卡在同一处:所有 claude plugin 命令只输出给人看的文本,脚本要解析就得写正则,版本一变就崩。

v2.1.268 给 install / uninstall / update / enable / disable 全部加了 --json,并给 claude plugin list --json 的每一行补了 errorDetails 和 noteDetails。

一个可直接用的例子——新机器/新容器的插件自举脚本,失败会真的失败(而不是静默跳过):

#!/usr/bin/env bash
set -euo pipefail

PLUGINS=("my-org/eng-toolkit" "my-org/review-bot")

for p in "${PLUGINS[@]}"; do
  if ! claude plugin install "$p" --json | jq -e '.success == true' >/dev/null; then
    echo "安装失败: $p" >&2
    exit 1
  fi
done

# 体检:列出所有插件,挑出带错误详情的那些
claude plugin list --json \
  | jq -r '.[] | select(.errorDetails != null) | "⚠️  \(.name): \(.errorDetails)"'

注意:--json 的字段名请以你本机 claude plugin list --json | jq keys 的实际输出为准再写死到脚本里,不同版本字段可能增补。

同版本的顺手改进:/plugin 里安装、启用、禁用插件,现在关掉菜单就生效,不再需要 /reload-plugins;VS Code 的 Manage plugins 对话框也会把变更应用到已打开的会话,不用重启。

什么时候用:Docker 镜像构建、dotfiles 初始化、CI job 的 setup 阶段、给团队新人的一键环境脚本。配合第 12 课的无头模式,这一步终于能写进流水线并在失败时正确退出。

技巧四:CLAUDE_CODE_WEBFETCH_DEADLINE_MS 与 gateway 定价对齐 —— 两个「省心向」开关

4a. WebFetch 不再无限期挂着

以前遇到一种服务器:响应开着不关、也不结束,WebFetch 就会永远等下去,整个会话卡死。v2.1.268 给了默认 300 秒死线,并开放了环境变量:

# 调研类任务,给慢站多一点耐心
export CLAUDE_CODE_WEBFETCH_DEADLINE_MS=600000

# CI 里要快速失败,压到 60 秒
export CLAUDE_CODE_WEBFETCH_DEADLINE_MS=60000

# 0 = 关闭死线(回到旧行为,不推荐)
export CLAUDE_CODE_WEBFETCH_DEADLINE_MS=0

什么时候用:① 定时任务 / 调研类会话要抓一堆页面时,调大;② CI 里宁可早失败也不要 job 超时,调小。如果你的每日任务偶尔「跑到一半不动了」,这个变量值得先怀疑。

4b. gateway 定价对齐 —— /cost 终于和财务口径一致

这条是给走 Claude apps gateway 的团队的:在 gateway.yaml 里设 pricing: 之后,已登录的 Claude Code 客户端会通过 managed settings 拿到同一套费率,于是 /cost 和 OpenTelemetry 遥测(第 27 课)显示的数字与网关的消费计量表对得上。

这解决的是第 27 课留下的一个尴尬:你把 metrics 接进了 Grafana,但看板上的成本和财务看到的账单是两套数,谁也说服不了谁。现在两边同源。

同版本还加了两道运维护栏: - 启动时若 access_control.allow_cidrs 为空,会给出告警;首次收到来自公网地址的请求时再警告一次; - 新增 gatewayInternalNetworks 托管设置,允许管理员把 /login 放行到组织自有的公网 IPv4 段; - claude self-hosted-runner --remove-session-state(默认关):会话结束时删除 <base-dir>/_sessions/ 下的每会话目录。

什么时候用:只在你的组织自建了 gateway 或 self-hosted runner 时。个人开发者可以跳过 4b,但 4a 人人有用。

一句话回顾

来源