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

第 36 课:新功能速用 —— v2.1.281(无限重试熔断、网关企业级加固、MCP URL 授权)

📅 2026-09-24 上一课(第 35 课)讲的是 v2.1.280 的 Opus 5.5 默认切换。这一课覆盖 v2.1.281(09-23)——这一版没有引人注目的新功能发布会,但修的全是"用了很久却说不清哪里出问题"的老毛病:无限重试、崩溃、会话恢复内容变形、prompt cache 因网关断连而失效。对每天靠 Claude Code 吃饭的人,这种版本比"加个新模型"更值得花 10 分钟看一眼。 前置:第 15 课(成本控制)、第 18 课(无头模式与 CI)、第 17 课(插件与 Marketplace)。 来源:Claude Code Changelog

技巧 1(基础):--max-turns 终于真的能兜底了

解决的问题:你在 CI 里跑 claude -p --max-turns 20 "...",以为超过 20 轮就会自动停,结果某次任务卡进一个"改了又错、错了又改"的死循环,烧了几十分钟额度才被外部超时杀掉——--max-turns 之前在某些重试路径下会被忽略。

v2.1.281 修复了"turns 可以无限重试、无视 --max-turns"的 bug,同时也修了 API 请求重试时偶发的 "unrecoverable interface error" 崩溃。这意味着无头模式下的轮次上限现在是真正的硬上限,而不是"大多数时候有效"。

Before:CI 任务偶发挂起到外部超时(比如 10 分钟)才被杀掉,日志里看不出是哪一轮开始死循环。 After:轮次上限生效后,任务会在你设定的轮数内自然退出并返回状态,日志能定位到具体在第几轮开始"原地打转"。

# CI 里给一次性任务加硬上限 + 把退出码接进你的流水线判断
claude -p --max-turns 15 --output-format json \
  "修复 tests/ 下失败的用例,只改必要文件" > run.json

# 用 jq 检查是不是"轮数用尽但没做完"(is_error / num_turns 字段随版本可能略有差异,
# 建议先跑一次并打印完整 JSON 确认字段名)
jq '{is_error, num_turns, result}' run.json

📖 官方文档:Claude Code Changelog · 无头模式文档

技巧 2(进阶):网关/代理后面的 prompt cache 不再"莫名其妙"失效

解决的问题:公司统一走 LLM 网关访问 Claude,某天发现 token 账单突然涨了一截——排查半天发现是 MCP 服务器中途断连导致 prompt cache 被清空,之后所有请求都在"冷启动"重建上下文;更隐蔽的是,代理/网关截断响应时,Claude Code 之前会把这当成"已完成",你根本不知道结果是不完整的。

v2.1.281 同时修了两个网关相关问题:①MCP 服务器中途断连不再连带清空 prompt cache;②代理/网关截断响应流时不再被误判为"已完成",而是会正确报告为异常。

Before:代理偶尔丢事件 → Claude 认为任务做完了 → 你拿到一个看似正常、实则半截的结果,还得靠肉眼发现。 After:流被截断时会被正确识别为失败,你可以在脚本里直接判断重试,而不用每次人工检查输出是否完整。

# 如果你在自建网关后面跑批量任务,建议加一层基于 exit code / is_error 的重试
for prompt_file in tasks/*.txt; do
  claude -p --output-format json "$(cat "$prompt_file")" > "out/$(basename "$prompt_file").json" \
    || echo "FAILED: $prompt_file" >> failed.log
done

📖 官方文档:Claude Code Changelog

技巧 3(进阶):MCP URL-mode elicitation —— 工具第一次能"礼貌地"把你导向外部授权页

解决的问题:你接的某个 MCP 工具需要走 OAuth 之类的外部授权(比如连接第三方 SaaS),以前只能靠工具自己在描述里塞一段"请手动打开这个链接"的文字提示,体验割裂、还容易被用户忽略。

v2.1.281 支持了 MCP 2026-07-28 协议规范里的 URL-mode elicitation:MCP 服务器可以用协议原生的方式,让 Claude Code 引导用户跳转到指定 URL 完成交互(如授权、二次确认),而不是塞在纯文本里让你自己判断。这是 MCP 规范持续被各客户端实现的又一例——参见此前小课讲过的第 17 课(插件与 Marketplace)里对 MCP 配置的基础用法。

// ~/.claude/mcp_servers.json(示例结构,具体字段以你使用的 MCP server SDK 版本为准)
{
  "mcpServers": {
    "your-oauth-tool": {
      "command": "npx",
      "args": ["-y", "@yourorg/mcp-oauth-server"],
      // 若该 server 走 2026-07-28 协议且支持 elicitation,
      // Claude Code v2.1.281+ 会在需要时自动弹出授权链接引导,无需额外配置
      "protocolVersion": "2026-07-28"
    }
  }
}

📖 官方文档:MCP 2026-07-28 规范 · Claude Code Changelog

技巧 4(企业级):网关模式下的 Bedrock 上游加固——assume_role 与 guardrail

解决的问题:团队用 Claude Apps Gateway 统一收口所有人的 Claude 访问,但走 Bedrock 上游时,凭证管理和内容护栏(guardrail)之前没法在网关层面统一配置,只能各自为战。

v2.1.281 给网关模式下的 Bedrock 上游加了两项企业级能力:①assume_role 支持通过 STS 临时角色假设访问 Bedrock,不用给每个使用方发长期密钥;②guardrail: {id, version} 支持在网关层直接挂载 Bedrock Guardrails 策略。同时网关的 Claude Desktop 密钥新增了 blockReadsOutsideWorkingDirectories(禁止读工作目录外的文件)与 disableBypassPermissionsMode(禁用绕过权限确认模式)两个安全开关。

# claude-apps-gateway 配置示例(字段名以你部署的网关版本文档为准)
upstreams:
  bedrock-prod:
    type: bedrock
    assume_role:
      role_arn: "arn:aws:iam::123456789012:role/claude-gateway-role"
    guardrail:
      id: "gr-abc123"
      version: "3"

desktop_keys:
  team-default:
    blockReadsOutsideWorkingDirectories: true
    disableBypassPermissionsMode: true

📖 官方文档:Claude Code Changelog · Claude Apps Gateway 文档

今日实操(10-20 分钟)

  1. 打开你最近一次在 CI/无头模式下跑的 claude -p 任务日志,搜索有没有出现过异常长的运行时间或"卡住又自己恢复"的迹象;如果有,升级到 v2.1.281 并重新加上 --max-turns + --output-format json,用 jq 检查 is_error 字段是否能正确反映失败。
  2. 如果你的团队用了 MCP server 或走网关代理:升级后故意让某个 MCP 连接中断一次(比如临时关掉对应进程),观察 prompt cache 是否还会被连带清空(对比升级前的历史账单曲线)。

验收标准:你能明确说出"我的 CI 任务现在有没有硬性轮数上限"和"我的网关/MCP 场景里 prompt cache 会不会因为连接抖动被清空"这两件事的答案,而不是"应该没问题吧"。

Claude Code 小课 · 第 36 课 · 2026-09-24 · 完整每日简报见同目录 AI每日简报-2026-09-24.md