claude@cli:~/docs$ cat claude-code.md

Claude Code CLI 指南:安装、配置、命令与环境变量

# 完整的 Claude Code 指南:配置、权限、钩子、MCP 与子代理,以及真正决定其实际运作方式的设置与命令。

author: words: 39711 read_time: 478m updated: 2026-11-04 14:25

Part 3 of New to Claude Code

完整的 Claude Code 指南:配置、权限、钩子、MCP 与子代理,以及真正决定其实际运作方式的设置与命令。

最后更新: 2026-11-04 · 478 分钟阅读 · 39K+ words

$ less claude-code.md

TL;DR:Claude Code 是一款智能体式 CLI,能够读取您的代码库、运行命令并编辑文件,由五大系统管控:配置、权限、hooks、MCP 和 subagents。凡是每次都必须执行的事情,请使用 hooks 而非提示词。

当前状况(CLI v2.1.317,2026年11月2日;npm latest 与 next 为 2.1.317,stable 为 2.1.311):284

  • 默认模型:Claude Opus 5.5(claude-opus-5-5),适用于 Pro、Max、Team、Enterprise 和 Anthropic API,以及 AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform。Microsoft Foundry 是例外:其默认模型为 Sonnet 4.5,且其 opus 别名指向 Opus 4.6。221
  • Opus 5.5 概览:每百万 token $4/$20,缓存读取 $0.20;在 Anthropic API 上默认 1M 上下文,自 v2.1.287 起 Bedrock、Agent Platform 和 Foundry 亦然;默认 effort 级别为 medium;思考功能无法关闭。快速模式下价格为 $8/$40。当任务无需 Opus 时,Sonnet 5.5($2/$10;自 v2.1.284 起在 Anthropic API 上对应 sonnet 别名)是更经济的选择。220222223228232
  • 自动模式(Auto mode)是所有套餐和提供商上交互式终端与 VS Code 会话的起始权限模式(v2.1.283-284),而 claude -p 和 Agent SDK 会话则以手动模式(Manual)启动,除非传入 --permission-mode auto(v2.1.302 撤销了 v2.1.285 引入的在第三方提供商上以及关闭遥测时的自动模式启动)。275 其安全检查在服务器端免费运行,覆盖 Enterprise 和 Claude API 账户、AWS 上的 Claude Platform、Bedrock、Agent Platform、Foundry 以及通过网关的使用;计费的本地检查则作为后备方案。219227228229230
  • AGENTS.md:自 v2.1.277 起,当项目没有 CLAUDE.md 时,AGENTS.md 会被读取为项目指令,但在无法获取功能标志的环境(如 Bedrock)以及安装或升级后的首次会话中除外。219223
  • Opus 4.8 上的快速模式已于2026年10月30日弃用,并将于2026年11月30日移除;此后针对 Opus 4.8 的快速模式请求将返回错误,而不是以标准速度运行,因此请通过 /model 切换到 Opus 5.5 以继续享受加速。在终端提示中输入 ultrathink 现在会以 xhigh effort 级别运行该轮对话(v2.1.311)。284285

逐版本的更新历史请参阅更新日志。

Claude Code是作为一个智能体系统运行的,而不是一个具备编程知识的聊天界面。这款 CLI 会读取您的代码库、执行命令、修改文件、管理 git 工作流、通过 MCP 连接外部服务,并将复杂任务委派给专门的 subagents。一切都经由一个命令行界面流转,并融入开发者的真实工作方式。截至2026年2月,公开 GitHub 提交中有 4%(每天约 135,000 次)由 Claude Code 编写——这是自研究预览版发布以来 13 个月内 42,896 倍的增长——而 Anthropic 自身 90% 的代码由 AI 编写。103

随意使用与高效使用 Claude Code 的差别,归结于五大核心系统。掌握它们,Claude Code 就会成为倍增您效能的利器:

  1. 配置层级:控制行为
  2. 权限系统:管控操作
  3. Hook 系统:实现确定性自动化
  4. MCP 协议:扩展能力
  5. Subagent 系统:处理复杂的多步骤任务

核心要点

  • 五大系统决定您的效能:配置层级、权限、hooks、MCP 和 subagents 掌控着从行为到自动化的一切。
  • 将工作下放到委派层:subagents 在干净的上下文窗口中隔离探索工作,只返回摘要,从而避免上下文膨胀。
  • Hooks 保证执行,提示词则不然:对于无论模型如何表现都必须每次运行的代码检查、格式化和安全检查,请使用 hooks。
  • 模型分级可在不牺牲质量的前提下节省成本:将 subagent 的探索工作路由到更便宜的模型,把 Opus 留给真正的架构推理——如果质量是您唯一的考量,也可以统一使用 Opus。
  • MCP 将 Claude 连接到您的工具链:数据库、GitHub、Sentry 以及 3,000 多种集成,让 Claude 的能力超越文件读取和 bash 命令。

我花了数月时间,在生产代码库、CI/CD 流水线和企业部署中把 Claude Code 推向极限。本指南将这些经验提炼成一份完整的参考资料——正是我刚入门时希望能拥有的那种。每项功能都附有实际语法、真实的配置示例,以及那些让资深用户也会栽跟头的边缘情况。

选择您的路径

您的需求 前往
安装与首次会话 5 分钟快速入门——安装、配置、运行您的第一条命令
命令与配置查询 速查表——以易于浏览的表格呈现每个标志、快捷键和设置
Hooks 参考 Claude Code Hooks 详解——完整的 hooks 参考:每个事件和退出码
深度参考(本页) 继续阅读——hooks、MCP、subagents、架构、企业模式

如何使用本指南

这是一份超过 5,000 行的参考资料——您无需从头读到尾。请从符合您经验水平的位置开始:

经验水平 从这里开始 然后探索
Claude Code 新手 如何安装? → 快速入门 → 思维模型 配置、权限
日常用户 Hooks、Subagents、Skills MCP、计划模式
团队负责人 / 企业 企业部署 → 最佳实践 决策框架、工作流配方
从其他工具迁移 面向特定受众的指南 决策框架

使用浏览器的 Ctrl+F / Cmd+F 搜索特定的标志、命令或配置键。文末的快速参考卡提供了所有主要命令的一览式摘要。

以下博客文章深入探讨了 Claude Code 的特定方面:

主题 文章
源码内幕:自动模式、bash 安全、缓存 Claude Code 源码泄露揭示了什么
Hooks 作为编排层 解剖一只 Claw:作为编排层的 84 个 Hooks
Hook 系统模式与示例 Claude Code Hooks 教程
Claude Code 作为生产基础设施 Claude Code 作为基础设施
自主智能体架构 Ralph 智能体架构
Apple 平台的智能体模式 iOS 智能体开发指南与Apple 生态系统系列
iOS 项目的 XcodeBuildMCP 集成 两个 MCP 服务器,一个 Xcode 项目
用于 iOS 工作的 .pbxproj 保护 hooks 面向 Apple 开发的 Hooks

60秒快速上手

如果您只想运行 Claude Code 并看到输出,请按顺序执行以下步骤:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

就这么简单。本节之后的全部内容都在展开介绍安装选项、配置权限与 hooks、接入 MCP 服务器以及企业部署,但这些对于上手而言都不是必需的。

前提条件:仅旧版 npm 安装路径需要 Node 22+(自 v2.1.198 起由 18 提高而来;在线安装文档写的是“Node.js 22 or later”,2026年8月7日核实);推荐的原生安装程序不依赖 Node。支持 macOS / Linux / Windows 10+。Claude Pro、Max、Team 或 Enterprise 订阅,或按 token 付费的 Anthropic API 密钥,均可覆盖使用费用。平台细节、故障排查以及原生二进制安装路径(自 v2.1.113 起为默认方式)请参阅如何安装 Claude Code?。本指南中的最新版本证据按版本逐一维护;当前的验证戳记请查看更新日志中最新的一行。267


Claude Code 的工作原理:心智模型

在深入了解各项功能之前,先要理解 Claude Code 的架构如何左右您使用它的每一个环节。整个系统分为三层:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

核心层:您的主对话。每条消息、每次文件读取和每个工具输出都会消耗同一个共享窗口中的上下文(标准为 200K token91,使用 Opus 4.6 或扩展上下文模型时为 1M token)。上下文一旦填满,Claude 就会丢失对先前决策的记忆,质量随之下降。这一层按 token 计费。

委派层:Subagents 以干净的上下文启动,完成专注的工作,然后返回摘要。探索过程的结果不会让您的主对话臃肿,只有结论会返回。不妨把 subagents 路由到更便宜的模型层级做探索;如果质量比成本更重要,也可以全程使用主模型。

扩展层:MCP 用于连接外部服务(数据库、GitHub、Sentry)。Hooks 可确保 shell 命令无论模型如何行事都会被执行。Skills 封装了领域专业知识,由 Claude 自动加以运用。Plugins 则把以上所有内容打包,便于分发。

关键洞见:大多数用户完全在核心层中工作,眼睁睁看着上下文膨胀、成本攀升。高阶用户则把探索和专项工作推给委派层,让扩展层始终按自己的工作流配置就绪,核心层只用于统筹编排和最终决策。


目录

  1. 如何安装 Claude Code?
  2. 快速上手:您的第一次会话
  3. 核心交互模式
  4. 配置系统深入解析
  5. 我应该选择哪个模型?
  6. Claude Code 的费用是多少?
  7. 决策框架
  8. 权限系统如何工作?
  9. Hooks 如何工作?
  10. 什么是 MCP(Model Context Protocol)?
  11. 什么是 Subagents?
  12. 什么是扩展思考模式?
  13. 输出风格
  14. 斜杠命令
  15. Skills 如何工作?
  16. Plugin 系统
  17. 记忆如何工作?
  18. 图像与多模态输入
  19. 语音模式
  20. Git 集成如何工作?
  21. 如何在我的 IDE 中使用 Claude Code?
  22. 高级用法模式
  23. 远程与后台代理 [研究预览]
  24. Chrome 中的 Claude
  25. Slack 中的 Claude Code [研究预览]
  26. 网页版 Claude Code [研究预览]
  27. Microsoft 365 中的 Claude(2026年5月)
  28. 性能优化
  29. 如何调试问题?
  30. 企业部署
  31. 键盘快捷键参考
  32. 最佳实践
  33. 工作流配方
  34. 迁移指南
  35. 面向特定受众的指导
  36. 快速参考卡
  37. 更新日志
  38. 参考资料

如何安装 Claude Code?

系统要求

Claude Code 可在 macOS 13+、Ubuntu 20.04+/Debian 10+ 和 Windows 10+(原生或 WSL)上运行。系统至少需要 4 GB 内存和有效的互联网连接。92 Bash、Zsh 或 Fish 的 Shell 兼容性最佳。

在 Windows 上,WSL 1 和 WSL 2 均可使用。如果倾向于原生 Windows 环境,也可以使用 Git Bash。Alpine Linux 和其他基于 musl 的系统需要安装额外的软件包:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

平台支持矩阵

平台 支持情况 首选安装方式 已知注意事项
macOS 13+(Intel) ✓ 原生安装程序或 Homebrew 无
macOS 13+(Apple Silicon) ✓ 原生安装程序或 Homebrew 无需 Rosetta 2;从 v2.1.113 起提供原生 arm64 二进制文件
Ubuntu 20.04+ ✓ 原生安装程序 v2.1.50 修复了 glibc < 2.30 系统上的原生模块加载问题
Debian 10+ ✓ 原生安装程序 glibc 兼容性注意事项与 Ubuntu 相同
Fedora / RHEL 8+ 尽力支持(非官方目标平台) 原生安装程序 依赖 v2.1.50 中相同的 glibc 兼容性修复;RHEL 7 不是经过测试的目标平台
Alpine / musl ✓(需运行 apk add libgcc libstdc++ ripgrep 并设置 USE_BUILTIN_RIPGREP=0) 原生安装程序 需要自定义 ripgrep,因为捆绑版本仅支持 glibc
Windows 10+(x64,原生) ✓ 原生安装程序(PowerShell)或 winget PowerShell 工具需要设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 环境变量(v2.1.111+)
Windows 10+(ARM64,原生) ✓ 原生安装程序 于 v2.1.41 中新增
Windows 10+(WSL 1) ✓ 在 WSL 内使用原生安装程序 条件允许时优先使用 WSL 2
Windows 10+(WSL 2) ✓ 在 WSL 内使用原生安装程序 推荐的 Windows 使用方式,可与 Linux 保持一致
Windows 10+(Git Bash) ✓ 原生安装程序 如果自动检测失败,请设置 CLAUDE_CODE_GIT_BASH_PATH(v2.1.98+)
Docker 沙箱 ✓(实验性) docker sandbox run claude 请参阅上方安装矩阵中的对应行;提供容器级隔离

安装、更新与卸载速览

便于快速查阅——所有方式、全部命令和版本检查尽在一览。以下小节将介绍各安装方式的具体细节和故障排除方法。

方式 安装 更新 卸载 版本检查
原生安装程序(macOS / Linux / WSL) curl -fsSL https://claude.ai/install.sh \| bash claude update(或自动更新;请参阅 DISABLE_AUTOUPDATER) rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude claude --version
原生安装程序(Windows PowerShell) irm https://claude.ai/install.ps1 \| iex claude update Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force; Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force claude --version
原生安装程序(Windows CMD) curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd claude update 请参阅 PowerShell 行 claude --version
Homebrew(macOS / Linux,稳定版) brew install --cask claude-code brew upgrade --cask claude-code brew uninstall --cask claude-code claude --version
Homebrew(macOS / Linux,最新版本通道) brew install --cask claude-code@latest brew upgrade --cask claude-code@latest brew uninstall --cask claude-code@latest claude --version
winget(Windows) winget install Anthropic.ClaudeCode winget upgrade Anthropic.ClaudeCode winget uninstall Anthropic.ClaudeCode claude --version
npm(旧版方式,自 v2.1.15 起弃用) npm install -g @anthropic-ai/claude-code npm install -g @anthropic-ai/claude-code@latest npm uninstall -g @anthropic-ai/claude-code claude --version
Docker 沙箱(实验性) 按照 docker sandbox run CLI 参考文档运行 docker sandbox run claude;Claude Code 沙箱快速入门展示了等效的 sbx run claude 简写形式 拉取最新的镜像标签 按照 Docker 文档移除容器和镜像 检查镜像标签

自 v2.1.113 起,标准 CLI 会通过各平台的可选依赖项启动原生 Claude Code 二进制文件,不再使用捆绑的 JavaScript——请使用原生安装程序,以获得经过测试的发行版本。npm 方式仍然可用,但会显示最早于 v2.1.15 中加入的弃用通知。

安装方式

原生安装(推荐)

原生二进制文件无需依赖 Node.js,可提供最简洁流畅的体验:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

如需安装指定版本:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

通过代理或网关时,绝对不要固定到版本 2.1.275。 在该版本中,当 ANTHROPIC_BASE_URL 指向代理或网关时,每个请求都会因 400 ... Input tag 'advisor_20260301' 而失败;2.1.276 已修复此回归问题。218

NPM 安装(已弃用)

注意: 自 v2.1.15 起,npm 安装会显示弃用通知。目前推荐使用原生二进制文件。请运行 claude install 进行迁移。

对于仍需使用 npm 的旧版环境:

npm install -g @anthropic-ai/claude-code

安装 npm 时切勿使用 sudo。否则会产生权限问题,让后续操作复杂棘手。

从现有安装迁移

如果目前使用的是较旧的 npm 安装,请迁移到原生二进制文件:

claude install

身份验证选项

Claude Code 支持三种身份验证方式,各有取舍:

Claude Console(API 计费)

通过 platform.claude.com(以前为 console.anthropic.com)直接连接到 Anthropic 的 API。创建账户、设置计费方式,然后通过 CLI 进行身份验证。Console 按使用量计费,并提供完整的 API 访问权限。系统会自动创建一个专用的“Claude Code”工作区;无法为此工作区创建 API 密钥,但可以监控使用情况。自 v2.1.243 起,/login → Anthropic Console 除创建 API 密钥外,还提供一种无需密钥的登录方式:“使用您的 Console 账户登录”(推荐)。因此,不允许使用 API 密钥的组织也能通过 Console 凭据登录。250

Claude Pro 或 Max 订阅

使用 claude.ai 账户凭据。单一月度套餐同时涵盖 Web 界面和 CLI 使用费用。对于希望费用可预测的个人用户,订阅模式可以简化计费。

企业平台

AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 均可依托现有云计费关系提供企业级访问。Bedrock 设置向导(v2.1.92+): 登录界面上的交互式向导会引导您完成 AWS 身份验证、区域选择、凭据验证和模型固定。137 Vertex AI 设置向导(v2.1.98+): Google Cloud 提供了类似的向导,引导完成 GCP 身份验证、项目与区域配置、凭据验证和模型固定。142 Vertex AI mTLS 工作负载身份联合(v2.1.121+): Vertex AI 现已支持基于 X.509 证书的工作负载身份联合(mTLS 应用默认凭据)——可使用客户端证书签发短期 GCP 令牌,无需服务账户 JSON。154 操作系统 CA 证书信任(v2.1.101+): 企业 TLS 代理现在默认即可使用——Claude Code 信任操作系统证书存储。若只需使用捆绑的 CA,请设置 CLAUDE_CODE_CERT_STORE=bundled。143

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

对于位于代理之后或通过 LLM 网关访问的企业部署:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

网关提示标头(v2.1.273): Claude Code 可以添加供 LLM 网关路由和观测的请求标头——x-claude-code-request-class、x-claude-code-agent-type、x-claude-code-prev-tool-durations、x-claude-code-compaction、x-claude-code-context-compacted,以及自 v2.1.283 起新增的 x-claude-code-prompt-id。后者是一个随机 UUID,同一用户提示所产生的每个请求都会共享该 UUID,包括 subagents 回合。217226 通过自定义基础 URL 或 Bedrock 等第三方提供商连接时,这些标头默认关闭,需设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 才会启用。网关协议文档还指出,直接连接到 Anthropic API 时会默认发送这些标头,而设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=0 则会在所有连接上停止发送。227

验证

claude doctor

该命令会报告安装类型、版本、系统配置以及检测到的所有问题。

身份验证管理(v2.1.41+)

无需进入 REPL 即可管理身份验证:90

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

自 v2.1.268 起,claude auth status --json 会包含 configDirectory——即 CLI 实际读取的配置目录。当 CLAUDE_CONFIG_DIR 间接指向其他位置、导致配置目录不明确时,此字段尤其有用。216

自 v2.1.273 起,使用 Claude 账户登录时还会请求访问您的 claude.ai plugins。217

自 v2.1.286 起,claude auth status 会将通过 Console 登录后存储的 API 密钥报告为 api_key,而非 claude.ai。231

在账户或组织之间切换的常见工作流:

claude auth logout && claude auth login

另请参阅:如何调试问题?,了解身份验证失败的故障排除方法。

更新

Claude Code 默认自动更新,会在启动时及会话期间定期检查更新。更新会在后台下载,并于下次启动时应用。

禁用自动更新:

export DISABLE_AUTOUPDATER=1

也可以在 settings.json 中设置:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

手动更新:

claude update

卸载

原生安装(macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

原生安装(Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

清理配置(移除所有设置):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

快速上手:您的首次会话

1. 安装并启动:

claude                           # Launch in current directory

2. 进入项目目录:

cd ~/my-project && claude        # Or launch from any git repo

3. 让Claude执行任务:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. 在会话期间使用键盘快捷键:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. 稍后继续:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

专家提示:在项目根目录创建一个CLAUDE.md文件,其中包含构建命令、编码规范和架构说明。Claude每次会话都会读取该文件——这是提升质量最行之有效的一项举措。


核心交互模式

交互式 REPL

不带参数启动 Claude Code,即可进入交互式的读取-求值-输出循环:

cd your-project
claude

REPL 会在多轮对话之间保留上下文。直接输入问题、获取回复,如此往复,直到使用 /exit 或 Ctrl+D 退出为止。

也可以附带一条初始提示词启动,让会话一开始就聚焦于目标:

claude "explain the authentication flow in this project"

专家提示:REPL 在上下文压缩事件之后仍会保留状态。当上下文过大时,Claude 会自动总结较早的对话内容,同时保留关键决策和代码片段。您可以通过 /compact 手动触发压缩,也可以添加自定义指令来指定需要保留的内容。

非交互模式

打印模式(-p)只执行一次查询,随后退出:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

如需便于脚本解析的结构化输出:

claude -p "count lines by file type" --output-format json

JSON 输出包含自动化所需的全部信息:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

如需实时处理流式输出:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

输出格式选项:

格式 标志 适用场景
文本(默认) --output-format text 人类可读的输出,适合通过管道写入文件
JSON --output-format json 脚本解析、CI/CD 集成
流式 JSON --output-format stream-json 实时处理、进度监控
stream-json 中的 subagent 文本(v2.1.211+):默认情况下,stream-json 输出只包含主会话的事件,subagents 内部完成的工作仅以摘要形式呈现。--forward-subagent-text 标志(或 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1)会把 subagent 的文本和思考输出也转发到流中,这样编排框架和日志管道就能实时观察委派出去的工作,而不是只看到最终报告。188

嵌套 subagents 现在也会转发(v2.1.219)。最初只有深度为 1 的 subagents 会显示出来。现在,在深度 2 及更深层级生成的 subagents 同样会出现在转发的流中,每个都以生成它的 Agent 调用的 tool_use id 作为键,因此管道可以据此重建委派树,而不是只看到一份扁平的文本列表。这与同一版本默认恢复深度 3 的嵌套生成直接配套:若没有这一改动,三层中的两层都将不可见。196

转入后台的 subagents 不再失联(v2.1.273):当 subagent 在运行中途被移至后台(例如通过 CLAUDE_AUTO_BACKGROUND_TASKS)后,SDK 和 stream-json 输出不再丢弃该 subagent 的剩余消息和最终报告。217

挂起的 -p 运行现在会以错误退出(v2.1.277):此前,claude -p 和 Agent SDK 会话遇到内部错误时可能会无结果地挂起,这对管道而言是最糟糕的故障模式,只能靠外部超时来终止运行。现在它们会报告错误并以退出码 1 退出,因此下方的退出码表再次成为完整的契约。同一版本还让无头会话在退出时保存其成本和用量总计:无头恢复(claude -p --resume、SDK、VS Code 扩展窗口重新加载)不再从零开始计算会话总计,跨恢复的无头运行的成本核算也不再少算。219

退出码:

退出码 含义
0 成功
1 错误(运行时故障、API 错误,或 Claude 报告了错误)
在 -p 模式下控制代理行为:
# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+); only CLI-named MCP servers (v2.1.286)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

受限模式(v2.1.248+):--restricted(或 CLAUDE_CODE_RESTRICTED=1)专为在共享机器上驱动 claude 的评估框架而设计。它会移除运行命令或代码的内置工具以及 WebFetch,除非您在 --tools 中逐一点名启用(default 预设不算数);将内置文件工具限制在工作目录之内;只加载托管设置和 --settings(用户、项目和本地设置文件均被忽略);拒绝 bypassPermissions;并拒绝创建云会话。206209

--permission-prompts none(v2.1.259):无人值守主机的配套选项。任何会触发权限提示的操作都会被自动拒绝,而当前生效的权限模式(包括自动模式)仍会继续做出所有无需您介入的决定。请勿将其与 --permission-prompt-tool 混淆,后者是把提示委托给某个 MCP 工具处理,而不是直接拒绝。CLI 参考文档尚未列出这个新标志,CHANGELOG 才是信息来源。211

非交互会话中 cd 在多轮之间持续生效(v2.1.265):接收 stream-json 输入的 -p 会话、Agent SDK 会话以及云会话不再在每条新用户消息到来时重置 shell 工作目录,某一轮中执行的 cd 现在会在下一轮继续保持。215

--system-prompt-snapshot off(v2.1.267):默认情况下,对话会在每次请求时重用已记录的系统提示词。而此标志会让每次请求都重新渲染系统提示词,适合迭代打磨提示词文本的场景:每次运行都应采用您的最新修改而非快照,代价则是牺牲快照本来要保护的提示词缓存稳定性。216

--bare 的限制如今切实生效(v2.1.286):--bare 现在只连接命令行中指定的 MCP 服务器,不向模型发送任何系统提醒,也不启动任何后台任务;达到超时的 shell 命令会直接停止,而不是转入后台。无头模式文档指出,在 v2.1.286 之前这些限制只是部分生效,并建议在脚本化调用和 SDK 调用中使用 --bare。231233

CI/CD 集成模式:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

打印模式下的退出码(v2.1.311 至 v2.1.317)。claude -p 现在会在启动失败时(v2.1.314),以及磁盘已满或配额耗尽导致转录文件或 ~/.claude.json 写入丢失时(v2.1.317,文本和 json 输出均适用)打印错误并以退出码 1 退出;此前这两种情况都会在无任何输出的情况下以 0 退出。--output-format json 和 stream-json 会把字符串内的 DEL、C1 控制字符和 Unicode 格式字符写成 \uXXXX 转义,因此解析后的值保持不变(v2.1.311)。需要在首次查询时就用到您 claude.ai skills 的 -p 运行,应设置 CLAUDE_CODE_SYNC_SKILLS=1;在关闭功能标志拉取的情况下,它会复用本机其他会话拉取的、最多 10 分钟前的 skills 列表(v2.1.311)。284285

会话管理

会话会持久保存对话历史,以便后续继续。对于跨越多个会话的复杂工作而言,会话持久化不可或缺:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

# Open the Claude desktop app on this directory, or on a session (v2.1.285)
claude --desktop
claude --desktop --continue

使用 /cd 移动正在运行的会话(v2.1.169+;自 v2.1.246 起配置立即生效):/cd path 可在不破坏提示词缓存的前提下切换工作目录。自 v2.1.246 起,新目录的项目设置、hooks、.mcp.json 服务器(仍需经过常规的批准提示)、skills 和 agents 会在移动后立即生效,无需等待 --resume。262249 PR 关联会话(v2.1.27+,v2.1.119+ 扩展): 启动一个与特定 pull request 或 merge request 关联的会话。自 v2.1.119 起,--from-pr 除 github.com 之外,还接受 GitLab MR、Bitbucket PR 以及 GitHub Enterprise 的 PR URL:74152

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

在会话期间通过 gh pr create 创建 PR 时,会话也会自动与该 PR 关联。这样一来,之后就能轻松恢复针对特定 PR 的工作。页脚的 PR 标记可通过 prUrlTemplate 设置(v2.1.119+)指向自定义的代码审查 URL——当您的团队需要从 PR 链接到独立的审查工具时,这一设置很有用。152

/resume 接受 PR URL(v2.1.122+)。 将 PR URL 粘贴到 /resume 搜索框中,现在可以找到最初创建该 PR 的会话——支持 github.com、GitHub Enterprise、gitlab.com(以及自托管的 GitLab)和 bitbucket.org。154

命名会话: 可在启动时或会话期间为会话命名:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

注意: --session-id 需要有效的 UUID(例如 550e8400-e29b-41d4-a716-446655440000)。如需人类可读的会话名称,请改用 /rename 和 --resume。

/fork 会生成一个后台会话;/subtask 则是会话内的分叉(v2.1.212)。 /fork 命令现在会将当前对话复制到一个新的后台会话中——它在 claude agents 中拥有自己的一行,因此您可以让这个副本去探索另一种方案,而主会话继续进行。原先的行为——在当前会话内分叉——以新名称 /subtask 延续下来。189 自 v2.1.214 起,以分叉方式启动的会话会将 SessionStart hook 的来源报告为 "fork"(此前为 "resume"),因此按来源匹配的 hooks 可以区分两者。190 v2.1.216 将 /fork 的确认信息精简为一行,显示新会话的名称及其 claude attach id。192 自 v2.1.221 起,分叉出的会话会创建自己的 worktree,而不是在原会话的检出目录中工作——探索替代方案的分叉不再会与主会话中未提交的文件发生冲突,而这正是此前派出副本去做实验时的一大隐患。199 v2.1.232 还让分叉成为 subagents 的默认方式:subagent_type: "fork" 的 subagent 会继承完整的对话和提示缓存,并且交互式会话中非队友(non-teammate)的 agent 生成现在默认在后台运行。255

Claude Code 将会话存储为 JSONL 转录文件。Agent 执行时会分配唯一的 agentId 值,转录文件存储为 agent-{agentId}.jsonl。恢复会话时会完整保留先前对话的上下文。

计划模式(Plan Mode)

计划模式将 Claude 限制为只读探索——不能编辑文件、不能执行 bash、不能进行破坏性操作。Claude 会设计实现方案,将其写入计划文件,并在执行任何操作之前等待您的批准。

进入计划模式:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

工作原理:

  1. Claude 进入计划模式(复杂任务会自动进入,也可通过 Shift+Tab 进入)
  2. 使用只读工具探索代码库:Read、Glob、Grep、WebSearch、WebFetch
  3. 将计划写入 .claude/plans/{session-slug}.md
  4. 通过 ExitPlanMode 退出计划模式,并提交计划供您审阅
  5. 您可以批准、要求修改或拒绝

计划模式下可用的工具: Read、Glob、Grep、LS、WebSearch、WebFetch、AskUserQuestion。编辑类工具(Edit、Write、Bash、NotebookEdit)会被禁用。

计划获批后(v2.1.32+): Claude 提供三个选项: - “Yes, clear context and auto-accept edits”(是,清除上下文并自动接受编辑;Shift+Tab)——以完整的上下文空间重新开始执行计划 - “Yes, and manually approve edits”(是,并手动批准编辑)——保留上下文,每项更改由您逐一批准 - “Yes, auto-accept edits”(是,自动接受编辑)——保留上下文,Claude 无需逐项批准即可执行

批准时自动清除上下文是推荐的工作流程。它为计划提供一个全新的上下文窗口,可显著提升对计划的遵循度——Claude 不会受旧对话干扰,能更长时间地保持在正轨上。

何时使用计划模式: - 涉及架构决策的新功能实现 - 希望先审阅方案再动手的多文件重构 - 不熟悉的代码库,应先探索再修改 - 存在多种可行方案、您希望参与决策的任何任务

专家提示: 在计划模式中投入的时间越多,Claude 成功完成实现的可能性就越大。计划模式实际上是免费的探索——没有有风险的工具调用,也不会产生无效的编辑。请放心大胆地使用。

屏幕阅读器模式(v2.1.208)

Claude Code 提供了专门的屏幕阅读器模式,可针对辅助技术调整终端界面。可通过以下三种方式之一启用:186

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic 在官方文档新增的无障碍页面中记录了该模式及其交互方式。186

每行之前不再暂停(v2.1.287): 屏幕阅读器模式现在写入新增或更改的行时,不再先将光标停在行首暂停。CLAUDE_AX_PREPARK_MS 以毫秒为单位设置该暂停时长;其默认值现在为 0(此前为 50),因此如需恢复原有行为,可设置 CLAUDE_AX_PREPARK_MS=50。同一版本还修复了一系列屏幕阅读器问题,其中包括搜索框中光标偏离所输入文本,以及编辑批准提示中缺少更改行的问题。232233


配置系统深度解析

Claude Code 采用分层配置系统。理解这一层级结构至关重要,因为高层级会覆盖低层级,而企业级设置则完全无法绕过。

配置层级

层级 位置 作用范围 可被覆盖
企业级 /etc/claude-code/managed-settings.json(Linux) 所有用户 否
/Library/Application Support/ClaudeCode/managed-settings.json(macOS)
C:\Program Files\ClaudeCode\managed-settings.json(Windows)
CLI 标志 命令行参数 当前会话 是
本地项目 .claude/settings.local.json 个人,仅当前项目 是
共享项目 .claude/settings.json 团队(通过 git 共享) 是
用户 ~/.claude/settings.json 您的所有项目 是
状态 ~/.claude.json 运行时状态、OAuth、MCP 不适用
专家提示: 在共享项目中,个人偏好请放在 .claude/settings.local.json(并将其加入 .gitignore)。团队范围的配置则放在 .claude/settings.json,并提交到版本控制。

从提示符设置配置:/config key=value(v2.1.181)

自 v2.1.181 起,/config key=value 可直接在提示符中内联设置任意选项,例如 /config thinking=false,无需打开交互式 /config 界面;该方式在交互式会话、-p 会话以及 Remote Control 会话中均可使用。/config --help(v2.1.183)会列出可用的简写键。v2.1.183 还调整了交互式 /config 界面:Enter 和 Space 均可切换所选设置,Esc 则保存并关闭(此前为撤销更改)。174

完整的 settings.json 参考

一份展示所有主要选项的完整配置:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "claude-opus-5-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

当团队拥有庞大的 skill 库、却希望收紧运行时的暴露范围时,skillOverrides 就很有用。使用 off 可将某个 skill 同时对模型和斜杠命令选择器隐藏;user-invocable-only 保留按名称调用的能力,但将其从模型可选范围中移除;name-only 则只显示 skill 名称,而不显示完整描述。156

较新的设置(v2.1.174–176):

  • availableModels / enforceAvailableModels(托管,v2.1.175+): availableModels 允许列表限制会话可选择的模型。设置 enforceAvailableModels: true 后,该允许列表还会约束 Default 模型——若 Default 解析到的是被禁止的模型,则回退到第一个允许的模型——并且用户/项目设置无法再扩大托管的 availableModels 列表。配套修复(v2.1.176)堵住了一个漏洞:此前通过 ANTHROPIC_DEFAULT_*_MODEL,别名选择可能被重定向到受屏蔽的模型;此外,/fast 现在会拒绝切换到允许列表之外的模型。172 自 v2.1.187 起,组织可以在 /model 选择器、--model、/model 和 ANTHROPIC_MODEL 中直接强制执行模型限制——选择受限模型时会显示“restricted by your organization’s settings”(受您的组织设置限制)消息。176
  • language(v2.1.176 改进): 除了设置回复语言外,会话标题现在默认以对话所用的语言生成;设置 language 可为标题固定某种特定语言。172
  • footerLinksRegexes(v2.1.176): 页脚行中按正则表达式匹配的链接徽章,可通过用户设置或托管设置进行配置。172
  • wheelScrollAccelerationEnabled(v2.1.174): 设为 false 可在全屏模式下禁用鼠标滚轮滚动加速。172

较新的设置(v2.1.207–v2.1.212):

  • vimInsertModeRemaps(v2.1.208): vim 插入模式的自定义按键重映射——经典用法是将 jj 映射为 Escape(参见 Vim 模式)。186
  • axScreenReader(v2.1.208): 持久启用屏幕阅读器模式(参见 屏幕阅读器模式)。186
  • processWrapper(v2.1.208): 让 Claude Code 为自身生成的每个进程都经由一个包装器可执行文件启动——专为企业启动器设计(参见 企业启动器)。186
  • autoMode 来源限制(v2.1.207): autoMode 设置不再从仓库的 .claude/settings.local.json 中读取——请改在 ~/.claude/settings.json 中配置。这堵住了克隆仓库可能夹带自动模式配置的途径。185

较新的设置(v2.1.217):

  • emojiCompletionEnabled(v2.1.217): 提示输入框中的 emoji 短代码自动补全——输入 :heart: 可插入 ❤️,输入 :hea 之类的部分内容则会显示建议。默认开启;设为 false 可禁用。194

较新的设置(v2.1.219):

  • sandbox.network.strictAllowlist(v2.1.219): 对沙箱化命令不经提示直接拒绝未列入允许列表的主机,而不是弹出权限对话框。参见 沙箱模式。196
  • workflowSizeGuideline(v2.1.219): 可从任意设置文件(用户、项目或托管)设置 Dynamic workflow 规模的建议性准则,而不再只能通过 /config 设置。Dynamic workflow 默认采用 medium 准则(“aim for fewer than 15 agents”,即目标为少于 15 个 agent);当某个设置文件提供了该值时,/config 中对应的行会自动隐藏。这只是建议,并非强制上限。参见 Subagents。196

较新的设置(v2.1.242–243):

  • modelPicker(用户或托管,v2.1.242+): 用一组有序、带标签的模型列表来定制 /model 选择器。其值是一个对象,包含一个 options 数组(每行必须含 model,可选 label 和 description;model 会按原样使用,因此别名、Anthropic ID 以及 Bedrock/Vertex/Foundry/网关 ID 均可使用)和一个可选的布尔值 replaceBuiltInOptions(默认为 false,将这些行追加在内置列表之后;true 则只显示您的行、Default 以及会话当前运行的模型)。Claude Code 会从托管设置、--settings 和用户设置中读取该键,而忽略项目设置和本地设置中的该键,因此克隆的仓库无法重新标记选择器;设置了该键的最高层级来源提供整个列表。availableModels 允许列表仍对每一行生效,而标签只改变选择器显示的内容,不改变实际运行的模型。250248
  • promptCacheTtl / subagentPromptCacheTtl(任意文件,v2.1.242+): 按请求类别设置 "5m" 或 "1h",这样使用 API 密钥的用户和云服务商用户可以让主对话保持一小时缓存,而 subagents 维持五分钟。参见 缓存策略。250248
  • modelPricing(托管,v2.1.243+): 组织签约的按模型费率和折扣系数,供 /cost、状态行和遥测成本数据使用,以取代标价。参见 查看成本。250

较新的设置(v2.1.247): - feedbackDrafts(v2.1.247): 控制新增的 SendFeedback 工具——会话中出现问题时,Claude 可以起草一份反馈报告,供您在 /feedback 中审阅并发送;通过此设置可关闭起草功能。请参阅斜杠命令中的 /feedback 行。245 - spinnerTipsOverride 结构扩展(v2.1.247): 提示条目现在除了纯字符串之外,还可以是 {id, text, cooldownSessions, priority} 对象,并且该对象新增了 tipsFile 和 label 键,组织可以借此让自己的提示与内置提示轮流显示(上面的示例展示了扩展后的结构)。设置参考文档现已记录这些新键。245227

较新的设置(v2.1.248–251):

  • desktopSessionCleanupPeriodDays(v2.1.248): 限定由桌面端写入的会话可以豁免于转录清理多长时间。与之一同发布的修复比这个选项本身更重要:Claude Desktop 和 Cowork 会话以前会在 cleanupPeriodDays(默认 30 天)之后消失;现在只要这些会话仍在应用中,清理就会保留它们,除非组织策略管理着保留期限。206
  • 项目级 env 限制(v2.1.251): 项目级 .claude/settings.json 中的 env 块不能再设置 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR 或 TMPDIR/TMP/TEMP——请改在 shell、用户或托管设置中设置它们,这样克隆下来的仓库就无法改变 Claude Code 写入配置和临时文件的位置。206

较新的设置(v2.1.257-259):

  • timeFormat / timeZone(v2.1.257): 控制 Claude Code 显示时间的方式——包括回合结束时的完成时钟和转录中的时间戳。timeFormat 接受 12 小时制、24 小时制、24 小时制 UTC 或显式的 strftime 模式;timeZone 指定时区。211设置参考文档现已记录这两个键。227
  • permissions.blockReadsOutsideWorkingDirectories(v2.1.257): 直接拒绝读取会话工作目录之外的文件。若未启用此项,自动模式现在会在会话首次进行此类读取之前询问一次(请参阅自动模式)。211v2.1.273 堵上了两个漏洞:检查器无法完整分析的 Bash 命令会触发提示,而不是跳过检查;由仓库设置选定的记忆目录在此设置下不会被加载、召回或索引。217
  • permissions.blockWritesOutsideWorkingDirectories(v2.1.314): 让 Write、Edit 和 NotebookEdit 在所有权限模式下(包括 bypassPermissions)都拒绝会话工作目录之外的路径。它不限制 shell 命令、MCP 工具或 hooks 运行的程序(那是沙箱的职责),并且在其启用期间,Claude Code 会移除 EnterWorktree 和 ExitWorktree 工具。任何设置文件都可以开启它,因此仓库可以封锁自身,但无法解除您设下的封锁。284285
  • managedMcpServers / managedSourcesBehavior: 托管作用域的键,详见企业部署——组织向每位用户提供 MCP 服务器(v2.1.259),以及跨托管来源的可选合并(在 v2.1.257 中改进)。211244

较新的设置(v2.1.261):

  • bashOutputMaxChars / taskOutputMaxChars(v2.1.261): 提高 Claude 在余下部分被保存到文件之前以内联方式接收的命令输出量(后者对应后台任务输出),最高可达 128K 个字符。这与 BASH_MAX_OUTPUT_LENGTH 环境变量是不同的机制:后者设定的是从命令工作输出文件回读的窗口(默认 30,000 个字符,上限 150,000);而这两个键控制的是内联与持久化文件之间的阈值——超过该阈值后,输出会存入一个 Claude 可按需读取的文件,而不是被截断。214自 v2.1.265 起,持久化一侧也有了上限:保存到磁盘的工具结果最大为 1 GB,并且对话中的预览会说明所保存的文件是否被截断。215 任务这一半在 v2.1.277 中退役: 已弃用的 TaskOutput 工具被移除——Claude 改用 Read 读取后台任务的输出文件——taskOutputMaxChars 和 TASK_MAX_OUTPUT_LENGTH 不再有任何效果。bashOutputMaxChars 不受影响。219

较新的设置(v2.1.267-269):

  • maxEffortLevel(v2.1.267): 限制用户可选的努力级别上限——可在顶层设置,也可在 modelSettings 下按模型设置——并适用于所有提供商,包括 Bedrock、Vertex 和 Foundry。用户仍可选择低于上限的级别;这是 /effort 在管理员一侧的对应项。216
  • advisorModel: /advisor 写入用户设置的已保存顾问模型(fable、opus、sonnet 或完整 ID);--advisor 可在单次会话中覆盖它,CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 则关闭该工具。请参阅Advisor 工具。274
  • sandbox.allowNestedUserNamespaces(v2.1.305): 允许 Linux 和 WSL2 上的沙箱化命令创建用户命名空间(Chromium、rootless podman);这会让它们绕过沙箱的文件保护,因此该设置仅从用户或托管设置中读取。请参阅沙箱模式。278279
  • bashEditDiffEnabled(v2.1.269): 当 Bash 工具处理文件编辑时,工具结果会附带命令所更改文件的 diff,这样对话中就能看到 sed 式编辑实际做了什么。216

较新的设置(v2.1.275):

  • syncClaudeAiSkills / syncClaudeAiPlugins(v2.1.275): 在您的 claude.ai 账户上启用的 skills 和 plugins 现在会同步到以该账户登录的终端会话中。将任一键设为 false,即可让终端会话只使用本地的 skills 和 plugins。请参阅 Skills 和插件系统。218

较新的设置(v2.1.282-283):

  • maxProseWidth(v2.1.282): 限制 Claude 的文字在宽终端中的最大宽度。段落、标题、列表和块引用会在该列数内换行,而表格和代码块保持全宽。该值为整数列数,最小为 40。225227
  • deniedModels / availableModelsMatch(托管,v2.1.283): deniedModels 会屏蔽特定模型,即使 availableModels 允许它们。像 "opus" 这样的系列别名会屏蔽整个系列,"claude-opus-5" 也会屏蔽 Opus 5.5(若只想屏蔽 Opus 5,请写 "claude-opus-5-0")。默认情况下,availableModels 中诸如 "claude-opus-5" 的条目也会允许在其基础上扩展的后续版本;availableModelsMatch: "exact" 则让每个条目只允许它所指名的版本,因此新发布的版本在您将其列出之前会一直被屏蔽。Claude Code 仅从托管设置中读取这两个键。226227
  • allowClaudeInChromeWithManagedMcp(托管,v2.1.282): 允许 claude --chrome 与独占的 managed-mcp.json 同时运行;Chrome 被阻止时显示的错误现在会指明该键。225设置参考文档现已记录它:该键仅从设备自身的托管设置中读取,而 deniedMcpServers 中针对 claude-in-chrome 的条目仍会阻止该服务器。233

较新的设置(v2.1.285):

  • allowedProviders(托管,v2.1.285): 限制一台机器可以使用哪些 API 提供商:Anthropic API、自定义端点、Bedrock、Mantle、Vertex AI、Foundry、AWS 上的 Claude Platform,或 Cloud 网关。229设置参考文档记录了该键;当服务器托管设置也提供一份列表时,来自机器自身管理员来源的列表仍然生效,因此会话只能使用同时出现在两份列表中的提供商。233

设置速查:搜索最多的标志

如果您是按名称查找某个特定设置而来到这里,这就是那份简短索引。每个条目都标明了它随哪个版本发布,以及(在有特定作用域归属时)属于哪个作用域:

设置 作用
disableBundledSkills 对模型隐藏内置的 skills 和斜杠命令——让自带这些内容的 harness 从零开始(v2.1.169+)
modelPicker 定制 /model 选择器:有序、带标签的行,可追加到内置列表之后或替换内置列表;仅限用户或托管作用域(v2.1.242+)
promptCacheTtl / subagentPromptCacheTtl 每个请求类别的提示缓存生存时间,"5m" 或 "1h"(v2.1.242+)
maxEffortLevel 限制用户可选的努力级别上限,可在顶层或 modelSettings 下按模型设置;适用于所有提供商,包括 Bedrock/Vertex/Foundry(v2.1.267+)
sandbox.excludedCommands 当一次调用中的每条命令都匹配某个条目时,这些命令会在沙箱之外运行(该设置自身的描述在 v2.1.314 更正之前一直写的是“始终”),例如 ["git", "docker"]——用于在隔离环境下会出问题的工具(请参阅沙箱模式)
sandbox.network.strictAllowlist 直接拒绝不在允许列表中的主机而不是弹出提示——适用于无人值守运行的设置(v2.1.219+)
worktree.bgIsolation 设为 "none" 可让后台会话直接编辑工作副本,适用于不便使用 worktree 的仓库(v2.1.143+)
allowAllClaudeAiMcps 企业:在 managed-mcp.json 之外同时加载 claude.ai 云端 MCP 连接器(v2.1.149+)
allowClaudeInChromeWithManagedMcp 托管:允许 claude --chrome 与独占的 managed-mcp.json 并行运行(v2.1.282+)
deniedModels / availableModelsMatch 托管:即使 availableModels 允许某些模型,也可将其屏蔽;"exact" 会将每个 availableModels 条目限定为其所指定的那个版本(v2.1.283+)
maxProseWidth 在宽终端中限制 Claude 输出文本的宽度;表格和代码块仍保持全宽(v2.1.282+)
allowedProviders 托管:限制某台机器可以使用的 API 提供商(v2.1.285+)
wslInheritsWindowsSettings 托管策略:WSL 会话继承 Windows 侧的托管设置(v2.1.118+)
### 各主题的官方文档在哪里?
本指南是一本实战手册,而非权威参考文档。当您需要查阅某个子系统在 Anthropic 的官方页面时,以下是各主题的官方位置(本指南的各个章节也会交叉链接到各自对应的页面):
主题 官方文档 本指南对应章节
Hooks 参考 + 指南 code.claude.com/docs/en/hooks · hooks-guide Hooks 如何工作?
MCP(claude mcp add、服务器) code.claude.com/docs/en/mcp 什么是 MCP?
Subagents code.claude.com/docs/en/sub-agents Subagents
权限模式(含 auto 模式) code.claude.com/docs/en/permission-modes 权限模式
设置文件 code.claude.com/docs/en/settings 配置系统
模型配置 code.claude.com/docs/en/model-config 我应该选择哪个模型?
CLAUDE.md / 记忆 code.claude.com/docs/en/memory 记忆如何工作?
Agent 团队 code.claude.com/docs/en/agent-teams Agent 团队
跨会话消息传递 code.claude.com/docs/en/cross-session-messaging 跨会话消息传递
版本更新日志 code.claude.com/docs/en/changelog 更新日志
### 环境变量参考
身份验证与 API:
ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

模型配置:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5-5         # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5    # What the `opus` alias resolves to (Opus 5.5 since v2.1.280; Opus 5 v2.1.219-278)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001  # pin the haiku alias; on the Anthropic API it resolves to Haiku 5.5 (claude-haiku-5-5) as of v2.1.293[^274][^275]
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1             # Turn the advisor tool off: /advisor becomes unavailable, advisorModel is ignored, --advisor is accepted but does nothing[^282]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_SUBAGENT_EFFORT=high                # Effort level subagents run at when nothing else names one, instead of inheriting the session's (v2.1.316+); a subagent on another model uses that model's saved effort or its default (v2.1.317+)[^292]
CLAUDE_CODE_DISABLE_ULTRATHINK=1                # Turn the ultrathink keyword off; since v2.1.311 it runs a terminal turn at xhigh effort on Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1 (v2.1.316+)[^292][^293]
CLAUDE_CODE_DISABLE_WORKFLOWS=1                 # Turn dynamic workflows off for one session; same effect as "disableWorkflows": true, and whichever of the two turned them off, the other cannot turn them back on. Workflows are on by default except on Pro, where "enableWorkflows": true (the Dynamic workflows row in /config) turns them on; the v2.1.147 opt-in CLAUDE_CODE_WORKFLOWS=1 no longer appears in the env-vars reference[^291]
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_MAX_TURNS=10                        # Cap agentic turns when no --max-turns is passed; the flag wins when both are set, and a value that is not a positive integer is rejected at startup[^291]
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

云服务商配置:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
VERTEX_REGION_CLAUDE_HAIKU_5_5=us-east5          # Vertex region for Claude Haiku 5.5 (v2.1.293+)[^276]
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send the x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted, and prompt-id from v2.1.283) through a gateway or third-party provider; a direct Anthropic API connection sends them by default, and =0 stops them everywhere (v2.1.273+)[^253][^262][^263]
CLAUDE_CODE_AUTO_MODE_SERVER=0                  # Opt out of the server-side auto-mode checks, the default since v2.1.278 for Enterprise and Claude API accounts, Claude Platform on AWS, Bedrock, Agent Platform, Foundry, and gateways (not charged when the server performs them; =1 was the v2.1.273-277 opt-in); also applies on a direct Anthropic API connection since v2.1.281, where server-side is the default with telemetry off since v2.1.282; the docs call it temporary[^253][^255][^259][^260][^261]
CLAUDE_CODE_AUTO_MODE_MODEL=claude-sonnet-5-5   # Model the client-side auto mode classifier uses; no effect on server-side auto mode (v2.1.302+)[^283]
CLAUDE_CODE_MODEL_CATALOG=off                   # Stop Bedrock, Mantle, Vertex AI, and Foundry sessions loading model settings from the signed file on downloads.claude.ai (v2.1.311+)[^292]
CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0              # Keep the full system prompt; =1 uses the shorter one on any model. Since v2.1.312 Bedrock, Mantle, Vertex AI, and Foundry use the shorter prompt for model names Claude Code does not recognize, even when they front Sonnet or Haiku[^292][^293]
CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1          # Turn off the automatic model switch after a safety classifier flags a request (the switchModelsOnFlag setting); since v2.1.312 the switch also covers model names Claude Code does not recognize[^292][^293]

行为控制:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_DISABLE_WEB_FETCH=1                 # Turn off the WebFetch tool; WebSearch stays available (v2.1.285+)[^265][^269]
CLAUDE_CODE_DISABLE_ARTIFACT=1                  # Turn the Artifact tool off for one session; while it is set, no settings file turns artifacts back on[^291]
CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0                # Do not open the browser when a new artifact is published[^291]
CLAUDE_CODE_SKIP_PROMPT_HISTORY=1               # Write no prompt history or transcript; the session never appears in --resume, --continue, or up-arrow history (ephemeral scripted runs)[^293]
CLAUDE_CODE_TRANSCRIPT_LOCAL_GC=1               # In a long -p or Agent SDK session, drop the pre-compaction history from a transcript over 5 MB after each compaction; resume still restores the conversation; environment only (v2.1.287+)[^293]
CLAUDE_CODE_SYNC_SKILLS=1                       # Make a -p run download the skills enabled for your claude.ai account and wait for the list before its first query; since v2.1.311 a session with feature-flag fetching off reuses a list up to 10 minutes old that another session on the machine fetched[^292][^293]
CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1         # On a self-hosted runner, let claude -p run inside a session share that session's ID and transcript, as before v2.1.317 (v2.1.317+)[^292]
CLAUDE_CODE_DISABLE_CFC_PROMPT=1                # Keep the Claude in Chrome tools but leave the Chrome section out of the system prompt; in VS Code (v2.1.314+) also out of a session's messages (v2.1.257+)[^292][^293]
FORCE_HYPERLINK=0                               # Render terminal hyperlinks as plain text; =1 forces OSC 8 links on where detection misses them. false, no, and off also turn links off since v2.1.314 (they turned them on before)[^292][^293]
CLAUDE_CODE_DISABLE_LOOPED_CROSS_CERT_DROP=1    # Keep system cross-certificates that certify each other in a loop, for a private CA that needs one (v2.1.316+)[^292]
OTEL_EXPORTER_OTLP_TIMEOUT=30000                # OTel's standard export timeout (milliseconds by the OTel convention); an OTLP export behind a proxy that never answers gives up after 10 seconds, or this value up to 30 seconds (v2.1.317+)[^292]
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES=2      # Cap re-sends of a non-streaming fallback request that timed out (v2.1.285+)[^265]
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=5000 # Starting delay of the exponential backoff between retries of a 529 overloaded request, default 500; whole milliseconds from 500 to 32000; no effect with CLAUDE_CODE_RETRY_WATCHDOG=1 or in fast mode (v2.1.292+)[^272][^276]
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=60000 # Ceiling of that backoff, default 32000 ms (v2.1.296+; in the env-vars docs since October 14)[^274][^280]
CLAUDE_CODE_RETRY_WATCHDOG=1                     # Unattended sessions: retry 429 and 529 capacity errors indefinitely, backing off up to 5 minutes or until the limit resets (v2.1.186+)[^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # Cap, per request, on how long the watchdog waits out 429 and 529 errors; unset means no limit (v2.1.295+)[^274][^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=3600000 # Under the watchdog, end a request at a usage limit that resets further away than this instead of waiting it out (v2.1.301+)[^283]
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=60000 # Minimum interval between checks that a usage limit was lifted before its reset, while the watchdog waits on it (v2.1.305+)[^286][^287]
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1      # Keep the dangerous-rm prompt waiting in auto mode and --dangerously-skip-permissions instead of denying after 2 minutes (v2.1.281+)[^260]
CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1    # Skip the prompt for a recursive rm whose target is only command-substitution output, such as rm -rf "$(pwd)" (v2.1.281+)[^260]
CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1     # Keep prompting for an rm built at run time inside a shell -c script Claude Code cannot read; such scripts no longer prompt by default (v2.1.299+; release-notes only as of 2026-10-14)[^279][^280]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=0                     # Turn fork subagents off; on by default in the terminal and, since v2.1.302, in claude -p, the Agent SDK, the desktop app, and VS Code (=1 was the external-build opt-in from v2.1.117; claude mcp serve never offers them)[^160][^283]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+). Since v2.1.290 an interactive session's budget refills instead of ending at 200 (next line); the env-vars docs, fetched Oct 6, still describe the 200 cap[^206][^271][^273]
CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=100     # WebSearch budget refill rate: 100 calls/hour by default in an interactive session, 0 (off) in a non-interactive one (v2.1.290+)[^271][^276]
CLAUDE_CODE_DISABLE_ATTACHMENTS=1               # Send @-mentions as plain text instead of expanding file content; a repo's .claude/settings.json or settings.local.json can no longer set it (v2.1.290)[^271][^273]
CLAUDE_CODE_DISABLE_FILE_MENTIONS=1             # Hand Claude the path of an @ mention to read with its file tools, not the file's contents, so PreToolUse hooks see the read; ignored in project and local settings (v2.1.299+)[^279][^280]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL=sonnet         # Run every workflow agent on one model while other subagents keep theirs (v2.1.296; release-notes only as of 2026-10-14)[^274][^280]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

工具配置:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192     # Override the cap on MCP tool descriptions and server instructions, every server in the session: 4,096 chars since v2.1.296, 2,048 in v2.1.280-295; Anthropic's first-party servers at api.anthropic.com are uncut since v2.1.299[^279][^256][^274]
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

后台命令时间限制(v2.1.285 引入,v2.1.288 收窄): 后台运行的 Bash 和 PowerShell 命令会在达到时间限制后停止,该限制即使用 run_in_background 运行时所设的 timeout(默认 30 分钟,最长 2 小时);命令被停止时,Claude 会收到通知。229 自 v2.1.288 起,该限制仅适用于无人值守会话(-p、Agent SDK、CI 以及云端会话);终端、桌面应用和 VS Code 会话中的后台命令不受时间限制。工具参考文档对此予以确认:“在 v2.1.288 之前,该限制适用于所有会话。”234237

网络与代理:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
CLAUDE_CODE_GZIP_REQUEST_BODIES=0              # Turn off gzip compression of large request bodies sent to api.anthropic.com, on even with telemetry off since v2.1.300[^281][^282]
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI 与终端:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope); also the opt-out for the v2.1.287 1M default on Bedrock/Vertex/Foundry/Claude apps gateway[^103][^217][^268]
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k           # Auto-compact window, 100000 to 1000000 tokens; k and M suffixes since v2.1.304 (200k had set a 100K window), out-of-range values warn[^286][^287]
CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1  # Let claude ultrareview run in a folder you have not trusted where it cannot ask, such as CI; environment only, not a settings env block (v2.1.309+)[^286][^287]
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=150000     # Context size at which idle compaction applies, default 200000; values below 100000 are raised to 100000; "idleCompaction": false in settings.json turns the feature off (v2.1.299; the docs date both to v2.1.290+); since v2.1.314 it also runs in VS Code and the desktop app's Code tab, with telemetry off, and on Bedrock, Vertex AI, Foundry, and LLM gateways once the one-hour prompt cache is on[^279][^280][^292]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
CLAUDE_AX_PREPARK_MS=50                       # Screen reader mode: pause before writing a changed line; default 0 since v2.1.287 (was 50)[^268][^269]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry 导出器与敏感字段门控:268

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set; v2.1.290 also skips the startup connection warm-up[^271]
CLAUDE_CODE_ATTRIBUTION_HEADER=0              # Omit the system-prompt attribution block; behind a Claude apps gateway, set it in the env of the gateway's code or cli policy (v2.1.299+)[^279][^280]

项目设置无法开启遥测(v2.1.282):项目设置文件和本地设置文件现在会忽略用于开启导出、设置其端点或捕获内容的OpenTelemetry变量,例如CLAUDE_CODE_ENABLE_TELEMETRY、OTEL_*_EXPORTER选择器以及OTEL_LOG_*。用于关闭某项功能的值(导出器选择器的none、内容标志的0)仍会从这些文件中生效。其余变量请在shell、用户设置或托管设置中配置。当项目文件设置了此类变量时,交互式会话会在启动时显示提示,/status和claude doctor会列出被忽略的变量名;-p和Agent SDK会话不会显示任何提示,因此升级后请确认您的收集器仍能收到数据。225227

v2.1.121+ LLM请求span属性:stop_reason、gen_ai.response.finish_reasons和user_system_prompt现在会在LLM请求span上发出。由于user_system_prompt可能包含个人身份信息(PII),它受OTEL_LOG_USER_PROMPTS=1控制。154

v2.1.122+事件级变更:api_request和api_error日志事件上的数值属性现在以数字形式发出(此前为字符串),修复了对模式进行严格类型校验的下游OTel收集器的问题。新增的claude_code.at_mention日志事件会在Claude Code解析@提及时触发。154

v2.1.300属性:api_request事件将缓存写入拆分为cache_creation_5m_tokens和cache_creation_1h_tokens;追踪span携带GenAI语义约定属性(gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name、error.type);user_prompt事件和交互span记录的是经mod的prompt.submit hook改写后的提示词;在reftable仓库中执行git commit -q后,tool_result事件会携带git_commit_id。273

v2.1.301和v2.1.302属性:tool_decision事件携带classifier_verdict和permission_mode,从而可以区分auto模式分类器的决定与权限规则;在设置OTEL_LOG_TOOL_DETAILS=1时,还会携带classifier_category,指明分类器拦截所匹配的内置规则(v2.1.301);v2.1.302为大多数分类器拦截补全了此前缺失的classifier_category,并在OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT较低时仍在事件上保留tool_use_id、tool_source和tool_parameters。监控文档尚未列出这三个属性。275276

v2.1.307事件:对于每一次被权限规则、auto模式、安全检查、hook或沙箱阻止、提示确认或退回的工具调用,都会触发claude_code.safety_event;除回合结束事件外,该事件都带有tool_use_id。监控文档已列出该事件,现在也列出了classifier_verdict(v2.1.301+)。278279Claude Code自v2.1.312起不再发送claude_code.safety_event;上述属性不受影响。284

v2.1.312至v2.1.317遥测:指标、事件和span携带anthropic.plan、anthropic.seat_type、anthropic.provider和anthropic.custom_base_url(v2.1.317);对于由官方Anthropic市场中的plugin声明的固定URL远程MCP服务器,mcp_server.name报告其真实名称,而不再是custom(v2.1.312);通过始终无响应的代理向https://端点导出时,会在10秒后超时,或按OTEL_EXPORTER_OTLP_TIMEOUT最多30秒超时,而此前会一直挂起(v2.1.317)。监控文档尚未列出这四个anthropic.*属性。284285

v2.1.193+ claude_code.assistant_response日志事件:Claude Code可以将模型的完整响应文本作为OTel日志事件发出,由OTEL_LOG_ASSISTANT_RESPONSES控制。这一控制机制有一个值得注意的升级陷阱:当OTEL_LOG_ASSISTANT_RESPONSES未设置时,它会跟随OTEL_LOG_USER_PROMPTS,因此任何已在记录提示词内容的部署在升级后都会开始收到助手响应内容。若要让遥测仅记录提示词,请设置OTEL_LOG_ASSISTANT_RESPONSES=0。179

v2.1.214遥测新增内容:OTel日志事件现在携带message.uuid、client_request_id和tool_source属性,用于消息级关联和工具来源追溯;subagentStatusLine负载包含subagent的推理强度(reasoning effort),因此自定义状态行可以同时显示模型和推理强度;新增的CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH环境变量用于配置OTel内容属性的60 KB截断上限。190

v2.1.265网关遥测:当网关的托管设置在OTEL_EXPORTER_OTLP_ENDPOINT中指定了收集器时,Claude应用网关会话现在会将OpenTelemetry数据直接导出到该收集器,而不再经由网关的中继转发;未指定收集器的会话仍继续使用中继。同一版本还为Claude Desktop和Cowork通过Claude应用网关发送的遥测数据添加了user.email和user.groups,与终端会话保持一致。215

v2.1.280 hook遥测:hook_execution_complete OTel事件现在携带hook输出的大小,以及因超出上限而保存到文件的输出数量。220

v2.1.287 prompt_text:user_prompt事件现在携带prompt_text,它是prompt的副本,供会将带点的键嵌套处理的后端使用。凡是您的管道会丢弃或遮蔽prompt的地方,都应对prompt_text做同样处理。232

API / 模型控制:268

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+); a Read call with allow_large can pass it when the context has room (v2.1.296+)[^274][^276]
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1      # Stop sending structured outputs, for Mantle or gateways that reject them; session titles, memory recall, and prompt hooks failed there before (v2.1.288+)[^270][^273]
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:268

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation: with direct HTTP servers (default everywhere as of v2.1.274) and, since v2.1.292, with local (stdio) servers on every install, Bedrock, Vertex, and Foundry included and, since v2.1.299, with cloud session and Remote Control connectors[^279][^254][^272]

Shell / IDE:268

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

企业 / 认证:268

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Skill变量(v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

SDK调用方身份(v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

调试:

ANTHROPIC_LOG=debug                             # Enable API request logging

我应该选择哪个模型?

为每项任务选择合适的模型,对成本和质量都有显著影响。Claude Code 支持在多个层级灵活切换模型。

可用模型

别名 模型 最适合 输入/1M 输出/1M
fable Claude Fable 5.1 最艰深的推理与长程任务;位于 Opus 之上的顶级层级(模型 ID 为 claude-fable-5-1;自 v2.1.257 起该别名解析至此,这是首个可安装且包含 Fable 5.1 的版本)211242 $10.00 $50.00
best 您可用的最新 Fable 模型(自 v2.1.257 起为 Fable 5.1),否则为最新的 Opus “始终选择可用的最强模型” 因模型而异 因模型而异
opus Claude Opus 5.5 复杂推理、智能体编码、长程任务;自 v2.1.280 起为默认 Opus 模型(模型 ID 为 claude-opus-5-5;v2.1.219-278 期间该层级由 Opus 5 担任)220221 $4.00 $20.00
sonnet Claude Sonnet 5.5 日常编码,速度与智能的最佳平衡;自 v2.1.284 起该别名在 Anthropic API 上选择的模型(模型 ID 为 claude-sonnet-5-5;v2.1.197-283 期间由 Sonnet 5 担任)。Claude Platform on AWS 将 sonnet 解析为 Sonnet 4.6,而 Bedrock、Agent Platform 和 Foundry 则解析为 Sonnet 4.5228230 $2.00 $10.00
haiku Claude Haiku 5.5 简单任务、快速操作、探索型 subagents;自 v2.1.293 起该别名在 Anthropic API 上选择的模型(模型 ID 为 claude-haiku-5-5;此前由 Haiku 4.5 担任,在 Bedrock、Google Cloud 的 Agent Platform、Foundry 以及 Claude Platform on AWS 上至今仍是如此)238239 $0.10(提示超过 100K token 时为 $0.50) $0.50(超过 100K 时为 $2.50)
default 自 v2.1.280 起所有套餐均为 Opus 5.5——Pro/Team Standard 从 Sonnet 5 迁移而来;文档的按套餐表格显示 Pro、Max、Team、Enterprise、Anthropic API、Claude Platform on AWS、Bedrock 和 Google Cloud 的 Agent Platform 均为 Opus 5.5(Microsoft Foundry:Sonnet 4.5);管理员可设置组织默认值,在 /model 中显示为“Org default”(v2.1.196+)220221 通用 因模型而异 因模型而异
opus[1m] 具备 1M 上下文的 Opus 长会话。在 Anthropic API 上无效,因为 Opus 5.5 在那里已经以 1M 运行;自 v2.1.287 起,在 Bedrock、Google Cloud 的 Agent Platform、Foundry 和 Claude 应用网关上同样无效,因为 Opus 4.7 及更高版本在这些平台上默认为 1M(v2.1.287 之前,除非固定的模型 ID 带有 [1m],否则它们在那里以 200K 运行)。对 Opus 4.6 仍然需要,而 Foundry 的 opus 正是指它;自 v2.1.311 起,模型名称和 ID 在 [1m] 后缀无效之处会去掉该后缀及其标签,但该后缀仍被接受223232233284 $4.00 $20.00
sonnet[1m] Sonnet 5.5(原生即为 1M) 当 sonnet 解析为 Sonnet 5.5 或 Sonnet 5 时无效;在 LLM 网关之后,它会为该模型选择 1M 窗口230 $2.00 $10.00
opusplan Opus(规划)+ Sonnet(执行) 复杂重构 混合 混合
Claude Haiku 5.5(2026年10月7日): 自 v2.1.293 起成为 Anthropic API 上的默认 Haiku 模型,该版本将 haiku 别名指向它;在 Claude Platform on AWS、Bedrock、Google Cloud 的 Agent Platform 和 Foundry 上,该别名仍解析为 Haiku 4.5。模型 ID:claude-haiku-5-5(Bedrock:anthropic.claude-haiku-5-5)。按提示长度计价: 提示不超过 100,000 token 时,输入 $0.10/MTok、输出 $0.50/MTok;超出后为 $0.50/$2.50;缓存读取分别为 $0.01 和 $0.05(标准的 10%)。该阈值计入请求的每一个输入 token(包括缓存读取和写入),且每个请求单独计价,因此一旦提示超过 100K token,其全部 token 都按较高费率计费。1M token 上下文窗口,最大输出 128K(在 Batches API 上使用 output-300k-2026-03-24 beta 标头时为 300K)。自适应思考且无法关闭,在 Claude API 上 effort 默认为 medium,分词器与 Opus 4.7 及更高版本相同(同样的文本比 Haiku 4.5 多出约 30% 的 token),可靠知识截止日期为2026年6月,退役时间不早于2027年10月7日。Haiku 仍是 availableModels 允许列表无法禁用的唯一模型系列,因此 haiku 现在会在每个选择器中放入 Haiku 5.5,而在 Haiku 4.5 上保存、model 设置为该别名的会话会在 Haiku 5.5 上恢复。VERTEX_REGION_CLAUDE_HAIKU_5_5 用于设置其 Vertex 区域。需要 Claude Code v2.1.293 或更高版本;v2.1.296 修复了它在某些网关之后的 token 计数;若要留在 Haiku 4.5,请固定 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001。238239

Claude Sonnet 5.5(2026年9月28日): 自 v2.1.284 起成为 Anthropic API 上的默认 Sonnet 模型,该版本将 sonnet 别名指向它;所有套餐的默认模型仍为 Opus 5.5。模型 ID:claude-sonnet-5-5(Bedrock:anthropic.claude-sonnet-5-5)。输入 $2/MTok,输出 $10/MTok,与 Sonnet 5 相同,缓存读取为 $0.10/MTok(按定价页面为输入价格的 0.05 倍,与 Opus 5.5 费率相同;v2.1.296 修正了 Claude Code 自身的成本数字,此前使用的是 $0.20)。1M token 上下文窗口,最大输出 128K(在 Batches API 上使用 output-300k-2026-03-24 beta 标头时最高可达 300K)。可靠知识截止日期:2026年6月,与 Opus 5.5 和 Fable 5.1 相同。退役时间不早于2027年9月28日。在 Claude Code 中,Sonnet 5.5 的 effort 默认为 medium(Claude API 自身的默认值为 high),且思考无法关闭。基于内容的回退:被标记为网络安全的请求会在 Sonnet 5 上重新运行,而被标记为生物学的请求会以拒绝告终,因为 Sonnet 5.5 没有生物学回退模型。需要 Claude Code v2.1.284 或更高版本;若要留在 Sonnet 5,请固定 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5。228230

模型页面列出了 API 代码从 Sonnet 5 迁移时的五项破坏性变更:使用 between_tools 时会关闭前置思考,强制工具使用会返回错误,思考块与模型和对话绑定,computer_20251124 在 Claude API 和 Google Cloud 上不被接受,以及 advisor 工具拒绝将 Opus 4.8、Opus 4.7 和 Sonnet 5 用作 advisor。工具调用之间的文本也会以 thinking 块的形式返回,因此以流式方式输出这些文本的界面会陷入沉默,直到设置能返回该文本的 display 值为止。230

Claude Opus 5.5(2026年9月22日): 自 v2.1.280 起成为 Claude Code 中新的默认 Opus 模型——并且根据模型配置文档的按套餐表格,它是所有套餐和第一方提供商的默认模型:Pro、Max、Team、Enterprise、Anthropic API、Claude Platform on AWS、Amazon Bedrock 以及 Google Cloud 的 Agent Platform(Microsoft Foundry 仍停留在 Sonnet 4.5,其 opus 别名解析为 Opus 4.6)。同一版本将 Pro 和 Team Standard 的默认模型从 Sonnet 改为 Opus,“与 Max、Team Premium 和 Enterprise 保持一致”——结束了自高级层级转向 Opus 以来一直存在的套餐分化。模型 ID:claude-opus-5-5(Bedrock:anthropic.claude-opus-5-5)——不带日期的固定快照,与 claude-opus-5 采用相同方案。定价低于 Opus 5:输入 $4/MTok,输出 $20/MTok(Opus 5:$5/$25),缓存读取为 $0.20/MTok——即输入价格的 5%,是标准 10% 的一半(只有 Fable 5.1 和 Mythos 5.1 更低,为 2.5%)。1M token 上下文窗口,最大输出 128K(在 Batches API 上使用 output-300k-2026-03-24 beta 标头时最高可达 300K)。自适应常开思考——模型概览表格给它的标注与 Fable 相同,都是“Adaptive (always on)”,而不是 Opus 5 那种默认开启但可关闭的形态。effort 默认为 medium(Opus 5 默认为 high),v2.1.280 也相应地修改了沿用规则:在 /effort 改为按模型设置之前保存的 effort 级别,不再适用于 Opus 5.5 这类新发布的模型——在您选定级别之前,模型会从自身默认值开始。可靠知识截止日期:2026年6月(训练数据同样截至2026年6月),与 Fable 5.1 并列为当前所有模型中最新的。退役时间不早于2027年9月22日。需要 Claude Code v2.1.280 或更高版本。220221

将 API 代码从 Opus 5 迁移到 Opus 5.5 时的破坏性变更:222

  1. 思考无法禁用。 thinking: {type: "disabled"} 和 thinking: {type: "enabled", budget_tokens: N} 都会返回 400。请移除 thinking 字段,改为选择一个 effort 级别。
  2. 强制工具使用会返回错误。 tool_choice 仅接受 auto 和 none;any 和 tool 会返回 400,在 token 计数端点上也是如此。请将 auto 与严格工具使用或结构化输出搭配使用。
  3. 思考块与模型绑定。 将对话从 Opus 5.5 转移到其他模型的路由器或回退机制,在运行这些轮次时将不带 Opus 5.5 的思考块(Claude API 上的 Fable 5.1 和 Mythos 5.1 是例外)。
  4. computer_20251124 在 Claude API 和 Google Cloud 上会被拒绝。 请改为声明 computer_toolset_20260801 工具集;Bedrock 保留了旧版工具。 还有一项变更不会使任何请求失败,但会改变响应的形态:模型在工具调用之间写下的文本会以thinking块的形式返回,而在默认的display设置下这些块是空的。依靠流式输出这些叙述文字的界面会就此沉默,直到设置display: "updates"(测试版)或"summarized"为止。222

Claude Code中基于内容的回退机制。 Opus 5.5运行时带有安全分类器,最常标记的是生物学和网络安全类内容。一旦某个分类器标记了请求,Claude Code会改用另一个模型重新运行该请求并显示一条提示:被标记为生物学内容的请求交给Opus 5处理,被标记为网络安全内容的请求交给Opus 4.8处理,并且会话会一直停留在回退模型上,直到您通过/model切换回来。如果希望改为每次都先询问您,可以在/config中关闭Switch models when a message is flagged(消息被标记时切换模型,即switchModelsOnFlag: false)。223 自v2.1.287起,切换时会保留您当前的effort级别,而不是采用回退模型的默认值,因此一个处于Opus 5.5默认medium级别的会话,切换到默认为high的Opus 4.8之后仍保持medium。232233

Claude Opus 5(2026年7月;上一代Opus层级): 从v2.1.219(2026年7月24日)起直到v2.1.280将Opus 5.5设为默认Opus模型为止,它一直代表Opus层级,也是opus别名所解析到的模型;下文呈现的是它在2026年7月发布时的面貌。Anthropic将其描述为Opus 4.8的可直接替换升级:输入$5/MTok、输出$25/MTok的价格保持不变,“以同样的成本大幅提升性能”,并且在最高推理强度下平均比Opus 4.8少用约26%的token。它曾是Claude Max上的默认模型,也是Claude Pro上最强的模型。模型ID:claude-opus-5——这是一个不带日期的固定快照,与claude-opus-4-8和claude-sonnet-5采用同一命名方案,而非会随新版本滚动更新的指针。1M token上下文窗口(无需beta标头,与Opus 4.8相同),最大输出128K(在Batches API上配合output-300k-2026-03-24 beta标头可达300K)。仅支持自适应思考——不支持thinking.type: "enabled"形式的扩展思考。可靠知识截止日期:2026年5月(训练数据截止日期同为2026年5月)——从发布之日起直到2026年9月1日Fable 5.1(知识截止2026年6月)问世为止,它都是当时所有Claude模型中最新的。241 随着Opus 5的到来,Opus 4.8移入文档中的旧版模型(Legacy models)表,与4.7和4.6并列——仍然可用,但不再是推荐的默认选择。197

将调用框架(harness)从Opus 4.8迁移到Opus 5时,有两项破坏性变更:197

  1. 思考默认开启。 在Opus 4.8上,不带thinking字段的请求不会进行思考;而在Opus 5上,同样的请求会以自适应思考模式运行。max_tokens仍是对总输出(思考内容加响应文本)的硬性上限,因此凡是此前在无思考状态下运行的工作负载,都应重新核查余量。传入thinking: {type: "disabled"}可恢复旧行为,但需遵守下一条的限制。
  2. 禁用思考时effort最高只能为high。 thinking: {type: "disabled"}与xhigh或max级别的effort组合使用会返回400错误。这项检查按请求逐一执行——在思考被禁用的情况下将effort提高到xhigh会被拒绝,即使同一对话中之前的轮次已被接受。

具体到Claude Code:Opus 5上的effort默认为high(与Claude API上一致),并且完整的级别阶梯均可使用——low、medium、high、xhigh、max。Anthropic自身的迁移指南建议,在能力比token消耗更重要的场景下测试max级别的effort。快速模式也覆盖Opus 5,价格为每MTok $10/$50(参见快速模式)。197198

Claude Fable 5.1(2026年9月1日): Fable层级的新顶点,并且自v2.1.257起成为fable别名所解析到的模型(除非ANTHROPIC_DEFAULT_FABLE_MODEL固定指向了其他模型);best现在的含义是“您可用范围内最新的Fable模型”。版本下限需要稍作解读:模型配置文档称该别名在v2.1.255中完成切换,模型页面则称Fable 5.1“需要Claude Code v2.1.255或更高版本”,但2.1.253至2.1.256从未在npm上发布——v2.1.257(9月1日)是第一个可供安装且包含该模型的版本。模型ID:claude-fable-5-1(Bedrock:anthropic.claude-fable-5-1)。层级与每token价格均与Fable 5相同——输入$10/MTok、输出$50/MTok、1M上下文、最大输出128K、始终开启的自适应思考、effort默认为high——但有一项对长时间智能体会话影响重大的定价变化:缓存读取仅需$0.25/MTok,即输入价格的0.025倍(2.5%),而标准比例为10%;只有Fable 5.1和Mythos 5.1享有这一费率,缓存写入则维持标准价格(5分钟缓存$12.50,1小时缓存$20)。可靠知识截止日期:2026年6月(训练数据同为2026年6月)——是当前所有Claude模型中最新的,随后Opus 5.5(知识截止2026年6月)于2026年9月22日、Sonnet 5.5于9月28日追平这一纪录。退役时间不早于2027年9月1日。自v2.1.301起,当最新的Fable模型对您的组织不可用时,fable和best会在上一代Fable模型上重试一次,而不是直接报错。275

相对于Fable 5有三项破坏性变更:强制工具使用会返回错误,早期模型无法读取它的思考块,编辑之前的轮次会使思考块失效。另有五项新增变更:按消息设置effort(测试版)、限定于单轮的系统消息(测试版)、工具调用之间的进度更新(display: "updates",测试版)、更便宜的缓存读取,以及内容溯源。Claude Mythos 5.1是规格完全相同的同一模型,仅通过Project Glasswing以邀请制提供。随着此次发布,Fable 5移入文档中的旧版模型(Legacy models)表,与Opus 4.8/4.7/4.6/4.5和Sonnet 4.6/4.5并列。

发布说明中还有一条关于网关的注意事项:在Claude应用的网关会话中,fable和best目前仍解析为Fable 5——尚未为5.1配置的网关会拒绝该模型——因此在这类环境下请在/model中明确选择Fable 5.1;需要注意的是,v2.1.260之前的/model选择器并未列出Fable 5.1,因此明确选择它意味着要完整输入/model claude-fable-5-1(参见下文的发布期集中修复)。发布时各套餐的默认模型:高级套餐为Opus 5,Pro和Team Standard为Sonnet 5——后被v2.1.280的所有套餐默认Opus 5.5所取代(2026年9月22日)。211241242221

Fable 5.1发布期集中修复(v2.1.260,9月3日): 发布后的第一个版本修补了四处遗留的粗糙之处。/model选择器现在会为有权使用的组织显示Fable 5.1——在此修复之前,只有完整输入/model claude-fable-5-1才会被接受。Fable 5.1上的提示词缓存现在覆盖了附加在工具结果之后的上下文,此前这部分内容在每一轮工具调用中都作为未缓存输入重新发送——恰恰在这项0.025倍缓存读取优惠本应服务的长时间智能体会话中,悄悄削弱了它的经济效益。在会话中途更改/effort不再使提示词缓存失效。此外,设置了model: fable的agents现在会遵守ANTHROPIC_DEFAULT_FABLE_MODEL固定值上的[1m]标记,而不是在不作任何提示的情况下以200K上下文窗口运行。212

Claude Fable 5(2026年6月9日;自2026年9月1日起为旧版): 一个高于Opus的全新模型层级——Anthropic最强大、最智能的模型,在几乎所有参与测试的基准上都达到了最先进水平,并且专为在数百万token的上下文中保持连贯而打造。Fable 5是经过安全处理、可供一般用途使用的“Mythos级”前沿模型:它内置安全分类器,遇到网络安全、生物化学和模型蒸馏类查询时会回退到Opus 4.8(Claude Mythos 5是同一模型,但为获授权的研究人员解除了这些防护措施)。自v2.1.170(2026年6月9日)起可在Claude Code中选用——运行claude update,然后执行/model fable(简短别名,自v2.1.257起解析为Fable 5.1——如今要选择Fable 5,请使用/model claude-fable-5)——并于2026年6月22日前向各订阅套餐推送完毕(已完成)。模型ID:claude-fable-5。Fable 5默认包含1M上下文窗口,因此无需[1m]后缀——而且自v2.1.173(2026年6月11日)起,claude-fable-5[1m]这样的模型名会被自动规范化,去掉后缀变为claude-fable-5(该后缀仅对Opus/Sonnet有意义,这两个系列需要加上[1m]才能启用1M上下文);最大输出128K。定价为输入$10/MTok、输出$50/MTok——约为Opus 4.8的2倍——因此应将其留给真正困难的推理任务,而非日常编辑。它与Opus 4.8共享同一套请求接口(仅支持自适应思考;移除了temperature/top_p/top_k和budget_tokens),但多了一个新细节:显式传入thinking: {type: "disabled"}会返回400错误,因此若要在不思考的情况下运行,请完全省略thinking参数。261 具体到 Claude Code:Fable 5 与 Opus 5 一样支持完整的 effort 等级(low/medium/high/xhigh/max,默认为 high)。Fable 5 上无法关闭思考功能——会话中的思考开关、alwaysThinkingEnabled 设置以及 MAX_THINKING_TOKENS=0 均不起作用;它始终以自适应方式进行推理。完整的 fable 系列配置项与 Opus 的各项开关一一对应:ANTHROPIC_DEFAULT_FABLE_MODEL 固定 fable 别名所解析到的模型(在 Bedrock/Vertex/Foundry 上很实用),DISABLE_PROMPT_CACHING_FABLE 让 Fable 退出提示缓存,而基于内容的自动回退同样适用于企业网关。/model opus 现在选择的是 Opus 5.5(v2.1.280;默认 medium effort,最难的任务可用 /effort xhigh),开箱即用的默认模型也不再取决于您的套餐——除 Microsoft Foundry 外,所有由 Anthropic 运营的套餐都默认使用 Opus 5.5;若想要绝对的能力上限,请有意识地通过 /model fable 选择 Fable 层级——自 v2.1.257 起,这意味着 Fable 5.1。261197207242220221

Opus 4.7(2026年4月16日): 上一代旗舰模型,目前仍完全可用。100 万 token 上下文窗口按标准价格计费——没有长上下文附加费。最大输出 128K,仅支持自适应思考(扩展思考已移除),并新增 xhigh effort 等级,官方建议将其作为编码和智能体工作负载的起点。145 可靠知识截止日期:2026年1月。训练数据截止日期:2026年1月。模型 ID:claude-opus-4-7。定价与 Opus 4.6 相同,为每百万 token $5/$25,5 分钟缓存写入 $6.25,1 小时缓存写入 $10,缓存读取每百万 token $0.50。144 在 SWE-Bench 上,Opus 4.7 解决的生产任务数量是 Opus 4.6 的 3 倍,在 CursorBench 上得分 70%(4.6 为 58%),在 Anthropic 包含 93 个任务的内部编码基准上解决率提升了 13%。144 采用了新的分词器——同样的文本预计会产生约 1 倍至 1.35 倍的 token 数量;请相应提高 max_tokens 余量并调整压缩触发阈值。145 视觉能力支持最高 2,576 像素 / 375 万像素的图像,并采用 1:1 像素坐标。145

Opus 4.7 编码基准测试(2026年4月):151

基准测试 Opus 4.7 Opus 4.6 GPT-5.4(OpenAI 当前前沿模型) GPT-5.3-Codex GPT-5.2-Codex GPT-5-Codex
SWE-bench Verified 87.6% 约 80.9%(报告的 Opus 4.5 基线) 约 80%(第三方数据;官方页面未列出) — — 74.9%(基线)
SWE-bench Pro 64.3% — 57.7%(官方) 56.8% 56.4% —
Terminal-Bench 2.0 69.4% 发布时最高 75.1%(官方) 77.3% 64.0% —
CursorBench 70% 58% — — — —
在 SWE-bench Verified 上,Opus 4.7 比广为引用的 GPT-5-Codex 基线高出 12.7 个百分点;在 SWE-bench Pro 上比 GPT-5.4(57.7%)高出 6.6 个百分点。在 Terminal-Bench 2.0 上,GPT-5.3-Codex 仍略胜 GPT-5.4(77.3% 对 75.1%),两者均领先于 Opus 4.7(69.4%)。基准测试的领先地位变动频繁;在做出跨多个季度的选择之前,请先查阅各厂商的官方页面。

各套餐的默认模型(Claude Code):207221

自 v2.1.280(2026年9月22日)起,套餐之间的区分已不复存在:所有由 Anthropic 运营的套餐和第一方提供商都默认使用 Opus 5.5,唯一的例外是 Microsoft Foundry。这里曾经最关键的一行——“我用的是哪个套餐?”——如今已不再影响答案。

套餐 默认模型
Pro、Max、Team(Standard 和 Premium)、Enterprise、Anthropic API 自 v2.1.280 起为 Opus 5.5;Pro 和 Team Standard 在该版本中从 Sonnet 5 迁出,“与 Max、Team Premium 和 Enterprise 保持一致”220221
AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform 自 v2.1.280 起为 Opus 5.5(v2.1.219 起为 Opus 5,v2.1.207 起为 Opus 4.8)221
Microsoft Foundry Sonnet 4.5——保持不变,也是唯一一处 opus 仍解析为 Opus 4.6 而非 Opus 5.5 的地方221
历史沿革:高级套餐/API 的默认模型自 v2.1.154 起解析为 Opus 4.8,自 v2.1.219 起为 Opus 5,自 v2.1.280 起为 Opus 5.5;AWS 上的 Claude Platform、Bedrock 和 Google Cloud 的 Agent Platform 则在 v2.1.207 加入 Opus 4.8 阵营(此前:AWS 上的 Claude Platform 为 Opus 4.7,另外两者为 Sonnet 4.5)。Pro 和 Team Standard 从 v2.1.197(2026年6月30日)到 v2.1.280 一直使用 Sonnet 5,这也是本指南直到 v2.105 所报告的状态;模型配置文档现已附上同样的历史说明,即在 v2.1.280 之前,Pro 和 Team Standard 上的 default 解析为 Sonnet 5。Enterprise 订阅席位在 CLI v2.1.251 时加入了高级套餐的默认模型行列(这一点上文档落后于 CHANGELOG);v2.1.280 则让这一区分变得无关紧要。Opus 4.7 从 4 月 16 日到 v2.1.154(2026年5月28日)一直是 Max/Team Premium 的默认模型;v2.1.219 将 opus 别名指向 Opus 5,v2.1.280 又将其指向 Opus 5.5。147181197206207220221

Opus 4.7 中 Messages API 的破坏性变更(调用方可见):145

  • 扩展思考的 budget_tokens 已被移除。请改用 thinking: {type: "adaptive"}。自适应思考默认关闭;不含 thinking 字段的请求将在不进行思考的情况下运行。
  • 将 temperature、top_p 或 top_k 设置为非默认值会返回 HTTP 400。请省略这些参数,改为通过提示词来引导模型。
  • 响应中默认不包含思考内容。设置 thinking.display: "summarized" 可恢复可见的推理过程(如果您的产品会向用户流式输出思考内容,则必须设置)。

任务预算(beta 请求头 task-budgets-2026-03-13)允许您通过 output_config.task_budget 向模型告知整个智能体循环的 token 目标;最低为 20K token。145

Opus 4.6(旧版): 仍可通过 claude-opus-4-6 使用,具备 100 万 token 上下文和 128K 最大输出。为获得更好的智能体编码能力,建议迁移到 Opus 4.7。Opus 4.6 最初于 2026年2月5日发布。79144 自 v2.1.117(2026年4月22日)起,Pro 和 Max 订阅用户在 Opus 4.6 和 Sonnet 4.6 上默认使用 high effort(此前为 medium);Opus 4.7 保持 xhigh。这一调整恢复了模型的智能水平,此前 4 月 23 日的事后分析报告记录了 3 月 4 日至 4 月 7 日期间的 effort 降级问题。152153

Sonnet 5(2026年6月30日;上一代 Sonnet 层级): 从 v2.1.197 起直到 v2.1.284 将其改为 Sonnet 5.5 之前,sonnet 别名在 Anthropic API 上选择的就是这个模型。发布时,Anthropic 将其定位为“速度与智能的最佳组合”。Anthropic 表示其性能接近 Opus 4.8,但价格更低,并且在智能体推理、工具使用、编码和知识工作方面相比 Sonnet 4.6 有大幅提升——同时,其不良行为的总体发生率更低,网络安全能力也远弱于 Opus 系列模型(正是这一安全权衡使其得以在没有出口管制限制的情况下发布)。模型 ID:claude-sonnet-5(无日期的固定快照)。100 万 token 上下文窗口,128K 最大输出(在 Batches API 上配合 output-300k-2026-03-24 beta 请求头可达 300K),仅支持自适应思考。可靠知识截止日期:2026年1月。定价:输入/输出每百万 token $2/$10,现已成为标准定价。 Anthropic 在发布时宣布 $2/$10 为截至 2026年8月31日的首发优惠价,随后将其保留下来:定价页面声明原定 9 月 1 日上调至 $3/$15 的计划“不会执行”,v2.1.243 也更新了 /model 选择器和内置的 claude-api skill,将 $2/$10 显示为正式定价而非限时促销价。251 这比 Opus 5.5 的 $4/$20 低 50%(比 Opus 5 曾经收取的 $5/$25 低 60%)。在 Claude Code 中,Sonnet 5 的 effort 参数默认为 high(如需更改请显式设置)。可通过 /model claude-sonnet-5 选择该模型。180230

v2.1.197(2026年6月30日)使 Sonnet 5 成为 Claude Code 中新会话的默认模型,并在标准层级(Pro、Team Standard)上一直沿用,直到 v2.1.280 于 2026年9月22日将这些套餐切换到 Opus。如今 Sonnet 5 已不再是 Claude Code 中任何套餐的默认模型,而且自 v2.1.284 起,/model sonnet 在 Anthropic API 上选择的是 Sonnet 5.5;若要继续使用 Sonnet 5,可用 /model claude-sonnet-5 或 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5。请参阅上方的套餐表格。181207220221228

Sonnet 4.6(2026年2月17日,现已被 Sonnet 5 取代): 均衡型模型;取代 Sonnet 4.5 成为 claude.ai 和 Claude Cowork 的默认模型。93 定价与 Sonnet 4.5 相同(每百万 token $3/$15)。智能体搜索性能有所提升,同时消耗的 token 更少。支持扩展思考、自适应思考以及 100 万 token 上下文窗口(beta)。最大输出 64K(v2.1.77 中上限为 128K)。119 知识截止日期:2025年8月(可靠),2026年1月(训练数据)。模型 ID:claude-sonnet-4-6。 Claude Mythos Preview(2026年4月7日): 面向防御性网络安全工作的研究预览版前沿模型,通过 Project Glasswing 计划提供。139 仅限邀请,尚未全面开放。Anthropic 将 Opus 4.7 定位为在网络安全维度上刻意弱于 Mythos——这是一项安全权衡——并已在 https://claude.com/form/cyber-use-case 开设了 Cyber Verification Program(网络安全验证计划),供需要更高访问权限的正规安全研究人员申请。146

为什么这些价格差异很重要: 一次典型的编码会话会消耗 50K-200K 输入 token 和 10K-50K 输出 token。按 Haiku 5.5 在提示不超过 100K token 时的费率计算,每次会话约为 $0.01-$0.05。换成 $4/$20 的 Opus 5.5,同样的会话则需 $0.40-$1.80,大约贵 40 倍(未计入提示缓存折扣)。任务不需要 Opus 时,请改用 Sonnet 或 Haiku。1222

各模型的适用场景

Haiku:适用于执行探索、简单文件搜索和快速问答的 subagents。按提示不超过 100K token 的费率计算,它比 Opus 5.5 便宜约 40 倍(提示超过 100K 时为 8 倍),响应也更快。非常适合不需要深度推理的后台任务。

Sonnet:在成本敏感的日常开发中担当主力——自 v2.1.284 起,Anthropic API 上的 Sonnet 是 Sonnet 5.5,价格与 Sonnet 5 相同,为 $2/$10228——而自 v2.1.280 将 Pro 和 Team Standard 切换到 Opus 之后,它不再是任何套餐的默认模型(原生 1M 上下文,标准定价为每 MTok $2/$10;原计划 9 月 1 日的涨价已取消)。181251207220 这正是需要理解的变化:Sonnet 现在是您主动选择的模型,而选择它的理由是一道算术题——在同样的 1M 上下文下,每 token 成本只有 Opus 5.5 的一半。它能胜任大多数编码任务:实现功能、修复 bug、编写测试、代码审查。历史说明:v2.1.197(2026年6月30日)曾长期被报道——包括本指南——为让 Sonnet 5 成为所有场景的默认模型,但模型配置文档中按套餐划分的说明显示,高级套餐/API 的默认模型自 v2.1.154 起解析为 Opus 4.8,自 v2.1.219 起解析为 Opus 5,因此所谓“所有场景”其实只是标准档——而 v2.1.280 连这一点也终结了。直到 2026 年 6 月,Sonnet 4.6 一直担任 Sonnet 角色。93147207221 当您需要更便宜的 token、更低的延迟或更经济的 subagent 运行成本时,请使用 Sonnet。

Opus:深度推理层级——自 v2.1.280 起,opus 别名指向 Claude Opus 5.5(每 MTok $4/$20,1M 上下文,effort 默认为 medium),并且从该版本起,Opus 也是所有套餐的起始模型。因此,问题变成了何时离开它:架构决策、棘手的调试、理解复杂系统、安全分析以及长周期的智能体工作,请留在 Opus 上;当任务足够常规、token 价格减半比额外的推理能力更重要时,再切换到 /model sonnet。220221(从 v2.1.219 到 v2.1.278,opus 别名解析为 $5/$25 的 Opus 5。)197 本段其余内容描述的是 Opus 4.7 在 2026年4月16日发布时的情况,作为历史记录保留。144147 Opus 4.7 在 SWE-Bench 上解决的生产任务数量是 Opus 4.6 的 3 倍,在 CursorBench 上得分 70%(对比 58%),并在一项包含 93 个任务的内部编码基准测试中将解决率提升了 13%。144 Claude Code 在 Opus 4.7 上默认使用 xhigh effort,可通过 /effort 调节(v2.1.111+)。146147 Max 订阅用户可通过 Anthropic API 在 Opus 4.7 上使用 Auto Mode,无需 --enable-auto-mode;其他套餐/提供商的可用性因套餐而异并由管理员控制。146 1M 上下文按标准价格计费——没有长上下文溢价。值得了解的行为变化: Opus 4.7 更严格地按字面执行指令,根据任务复杂度调整回复长度,默认运行更少的 subagents,语气更直接,减少了迎合式措辞。如果您的提示中包含用于强制输出中间进度消息或反复确认行为的脚手架,不妨尝试移除。145

Opusplan:一种混合模式,用 Opus 做规划(推理质量最关键的环节),用 Sonnet 做执行(速度更重要的环节)。非常适合复杂重构:您希望得到最佳方案,但并非每一次编辑都需要 Opus 级别的推理。

切换模型

会话期间:

> /model opus
> /model sonnet
> /model haiku

启动时:

claude --model opus

通过环境变量:

export ANTHROPIC_MODEL=opus

在 settings.json 中:

{
  "model": "claude-sonnet-5"
}

定制模型选择器本身(modelPicker,v2.1.242+): 用户级或托管设置文件可以列出 /model 提供的模型,按您的顺序排列并使用您的标签,而不必让内置阵容成为唯一的菜单。每一行指定一个 model(--model 接受的任何写法,包括 Vertex 和 Bedrock ID),并可选附带 label 和 description;将 replaceBuiltInOptions 设为 true,则只显示这些行加上 Default 和会话当前的模型。此键会忽略项目级和本地设置,availableModels 允许列表仍会过滤这些行。Claude Code 会移除无法提供的行,将您暂时无法选择的行灰显并注明原因,若没有任何行保留下来,则回退到内置阵容。250248

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

专门针对 subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

自 v2.1.251 起,CLAUDE_CODE_SUBAGENT_MODEL 设置的是 subagent 的默认模型,而不再覆盖一切:agent 定义中的 model: 以及每次生成时显式指定的模型优先于它。206 自 v2.1.257 起,CLAUDE_CODE_SUBAGENT_MODEL_FORCE 以可选方式恢复旧行为:它将 CLAUDE_CODE_SUBAGENT_MODEL(未设置时则为主对话的模型)应用于每一个 subagent,忽略每次生成时的选择和 agent 定义中的 model:。211

回退模型链(v2.1.166+): fallbackModel 设置最多可配置三个回退模型,在主模型过载或不可用时按顺序尝试。--fallback-model 标志(此前仅用于会话中途切换)现在从启动起也适用于交互式会话。263

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

当 API 返回意外的不可重试错误时,Claude Code 现在也会先在回退模型上重试该轮一次,再报告失败,这样主模型的短暂故障会平稳降级,而不是直接丢弃该轮。263 自 v2.1.286 起,当 Anthropic API 拒绝您的默认模型或别名所解析到的模型时,Claude Code 会在同一层级的上一代模型上重试一次,而不是每一轮都失败;并且因拒绝或 --fallback-model 而重试到无法以快速模式运行的模型时,会以标准速度运行。231

自 v2.1.178 起,压缩操作同样遵循回退链——如果主模型在压缩过程中过载或不可用,压缩步骤会回退到已配置的 fallbackModel/--fallback-model 链,而不是让该轮失败。对于长时间的自主运行,这弥补了一个缺口:原本可恢复的压缩可能因模型的短暂错误而导致整个会话中断。173

扩展上下文

对于大型代码库或长会话,可启用 1M token 上下文:

claude --model sonnet[1m]
claude --model opus[1m]           # 1M for a model that reaches it only through [1m], such as Opus 4.6

或在会话中:

> /model sonnet[1m]
> /model opus[1m]

自 v2.1.311 起,在后缀不起作用的模型上(例如 Anthropic API 上的 Opus 5.5),模型名称和 ID 不再带有 [1m] 后缀及其标签;该后缀仍被接受,因此现有命令和设置继续有效。284

后缀在哪些情况下有意义(2026年10月): 在 Anthropic API 上,Fable 5.1、Fable 5、Sonnet 5.5、Sonnet 5 以及 Opus 4.7 及更高版本(含 Opus 5.5)在所有套餐上都使用 1M 窗口运行,因此 [1m] 在那里不会改变任何东西。自 v2.1.287 起,Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude apps 网关也是如此:Opus 4.7 及更高版本以及 Fable 默认使用 1M 窗口,无需 [1m] 后缀,而 CLAUDE_CODE_DISABLE_1M_CONTEXT=1 可将它们保持在 200K。在 v2.1.287 之前,Opus 4.8 及更高版本在这些提供商上以 200K 运行,除非 ANTHROPIC_DEFAULT_OPUS_MODEL 中固定的模型 ID 带有 [1m];10 月 1 日获取的 Bedrock 和 Agent Platform 文档页面仍将该后缀描述为在那里获得 1M 的方式。Sonnet 5 在所有提供商上都是 1M。对于 Opus 4.6 和 Sonnet 4.6,该后缀仍然有意义,它们只能通过各自的 [1m] 变体达到 1M。223232233 Opus 4.7、Opus 4.6 和 Sonnet 4.6 均按标准定价提供完整的 1M token 上下文窗口——没有长上下文附加费。148 一个 900K token 的请求与一个 9K token 的请求按相同的每 token 费率计费。提示缓存和批处理折扣在整个上下文窗口内均按标准费率适用。

[1m] 变体的访问权限取决于套餐:Max、Team 和 Enterprise 套餐包含 1M 上下文的 Opus 4.6,而 1M 上下文的 Sonnet 4.6 在所有订阅套餐(包括 Max)上都需要用量额度。233(1M 上下文的 Opus 自 2026年3月13日的 v2.1.75 起成为 Max、Team 和 Enterprise 套餐的默认模型。)117147 API 和按量付费用户可按标准每 token 费率获得完整的 1M 访问权限。147

要在模型选择器中禁用 1M 上下文变体,请设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。自 v2.1.223 起,该变量的作用范围有所变化:它通过自动压缩将所有原生支持 1M 窗口的模型限制在 200K——而不再只是一份固定的已知变体列表——并且当自动压缩实际上未能将会话限制在 200K 时,启动时会显示警告。如果您为了某个模型系列的成本可预测性而设置了此变量,它现在会在新的 1M 模型发布当天即对其生效,而不会悄然失效。同一版本还让自动压缩将使用未识别模型 ID 的会话保持在假定的上下文窗口之内,而不是任其超出;对于注册了实际窗口更大的自定义 ID 的网关,CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 可恢复旧行为。200 自 v2.1.287 起,该变量也是在 Bedrock、Vertex、Foundry 和 Claude 应用网关上将 Opus 4.7 及更高版本以及 Fable 保持在 200K 的方法,因为 1M 已成为这些平台上的默认值。232

自 v2.1.247 起,Sonnet 5 的默认自动压缩窗口即为其完整的 1M 上下文:使用 1M 窗口的会话现在会在约 967K token 时自动压缩,而不是约 934K。245 v2.1.260 将临近上限的自动压缩扩展到 1M 层级的其余模型:Opus 和 Fable 会话现在同样会在接近 1M token 上限前不久进行压缩,并且超大上下文的恢复压缩不再在 10 分钟时超时。212

自定义基础 URL 也获得 1M 窗口(v2.1.285)。 通过自定义 ANTHROPIC_BASE_URL 运行的会话现在会使用具备 1M 上下文窗口的模型(Opus 4.7 及更高版本、Sonnet 5 及更高版本、Fable)的 1M 窗口。如果您的网关止步于 200K,请运行 /autocompact 200k。229233

自 v2.1.271 起,--resume 会保留 [1m] 窗口:恢复一个模型系列与已配置默认模型不同的会话时,不再丢失 [1m] 后缀。216

v2.1.273 修复了上下文计量器和自动压缩将 Advisor 工具轮次按约两倍于其实际上下文大小计算的问题——此前自动压缩会在实际窗口约一半处触发。217

查看当前模型

> /status

该命令会显示当前模型、账户信息、已应用的设置以及其他会话状态。

模型选择器标签(v2.1.51+): /model 选择器现在对固定版本显示易读的标签(例如“Sonnet 4.6”),而不是原始模型 ID,并在有更新版本可用时给出升级提示。98 v2.1.219 修复了合并后的 Opus 行显示为普通“Opus”而非 “Opus (1M context)” 的问题,并将新版本高亮范围缩小到仅最新模型的名称,使高亮标记的是实际发布的内容,而不是列表中的任意一段。196 v2.1.283 在 Opus 已具备 1M 上下文窗口的情况下,从 Opus 行和默认模型名称中去掉了“(1M context)”;窗口本身没有变化。226

快速模式(v2.1.36+)

快速模式让同一模型的输出速度显著提升;它不会切换到更便宜的模型。在会话中可用 /fast 开关它。86

> /fast            # Toggle fast mode on/off

适用模型(截至 v2.1.280): 快速模式适用于 Claude Opus 5.5、Opus 5 和 Opus 4.8,自 v2.1.280 起 Opus 5.5 是快速模式的默认模型(v2.1.219 起默认为 Opus 5)。v2.1.219 将 Opus 4.7 移出了快速模式,而该功能从未在 Sonnet、Haiku 或 Fable 上提供。它目前仍仅在 Claude API(包括 Claude Managed Agents)上作为研究预览提供——Amazon Bedrock、Google Cloud、Microsoft Foundry 或 AWS 上的 Claude Platform 均不支持。访问受限:请联系您的客户经理或加入候补名单。196198223 Opus 4.8 即将退出快速模式: 2026年10月30日弃用,2026年11月30日移除。移除日期之后,对 Opus 4.8 的快速模式请求会返回错误,且不会回退到标准 Opus 4.8;可用 /model 切换到 Opus 5.5 以保留快速模式(切换后它会保持开启),或运行 /fast off 以标准速度留在 Opus 4.8 上(v2.1.316)。284285

远程会话(v2.1.271): 快速模式现已覆盖 Claude Code Remote 会话——云端会话和自托管运行器。主机的快速模式设置会生效,也可以直接在会话中输入 /fast;两者都只在您的组织允许快速模式时有效。同一版本还修复了 /fast off:当组织禁用了快速模式时,它现在会关闭快速模式,而不是回答“Fast mode unavailable”。216

定价(快速模式):198222223

模型 标准(输入 / 输出) 快速模式(输入 / 输出)
Opus 5.5 $4 / $20 每 MTok $8 / $40 每 MTok(基础价 2 倍)
Opus 5 和 Opus 4.8 $5 / $25 每 MTok $10 / $50 每 MTok(基础价 2 倍)
快速模式以基础价 2 倍的定价提供最高 2.5 倍的每秒输出 token 数。它以更快的推理配置运行同一模型——相同的权重、相同的智能、没有能力上的变化。提升体现在每秒输出 token 数(OTPS),而非首个 token 的响应时间,因此在流式输出时最为明显。198

Opus 4.7 陷阱(v2.1.219)。 不受支持的模型表现并不一致。带 speed: "fast" 的 claude-opus-4-7 请求现在会返回错误——它不会悄然回退到标准速度。Opus 4.6 是让这一点值得了解的例外:它接受 speed: "fast",但仍以标准速度运行、按标准费率计费,并报告 usage.speed: "standard"。如果您的 harness 固定使用 4.7 并依赖快速模式请求静默降级,这些请求现在会直接失败;请将固定版本迁移到 Opus 5.5、Opus 5 或 Opus 4.8。198

何时使用快速模式: - 在延迟是瓶颈的小改动上快速迭代 - 生成测试、样板代码或重复性代码,此时速度比成本更重要 - 顺序处理一系列相似任务

何时不应使用快速模式: - 长时间运行的智能体任务(整个运行过程的成本仍会翻倍) - 后台 subagent 工作(没有人在等待输出) - 注重预算的会话

快速模式包含完整的 1M 上下文窗口(v2.1.50+)。定价在整个上下文范围内都是统一的倍数,包括超过 200K 输入 token 的请求——没有额外的长上下文附加费——并且会与提示缓存和数据驻留倍数叠加。96198

运行注意事项。 快速模式有独立于标准 Opus 限制的速率限制;超出后会返回带 retry-after 的 429(anthropic-fast-*-tokens-* 响应头会报告剩余容量)。在快速与标准之间切换会使提示缓存失效——不同速度的请求不共享缓存前缀,因此在会话中途切换 /fast 会付出一次缓存未命中的代价。快速模式不适用于 Batch API 或 Priority Tier 承诺。198

专家提示: 快速模式与 opusplan 不搭配(opusplan 本身已混合使用 Opus 和 Sonnet;快速模式只影响 Opus 这一段)。在延迟比成本更重要时使用它,在自主或批量工作中则禁用它。/fast 需要额外用量;Team/Enterprise 管理员可能需要先启用它(v2.1.37 修复)。可通过 CLAUDE_CODE_DISABLE_FAST_MODE=1 将其彻底禁用。自 v2.1.218 起,当通过 /config model=<x> 或 Remote Control 切换模型改变了您的快速模式状态时,Claude Code 会发出提示;v2.1.219 则修复了 Remote Control 客户端在切换、重连或组织检查失败后保留过期快速模式状态的问题。86149195196

Advisor 工具(实验性)

advisor 工具允许 Claude 在任务的关键时刻咨询第二个(通常更强的)模型:在确定方案之前、在某个错误反复出现时,或在宣布工作完成之前。advisor 作为服务器工具在 Anthropic 的基础设施上以服务端方式运行,接收包括每次工具调用及其结果在内的完整对话,并返回指导意见,Claude 会在继续之前加以应用。何时调用由 Claude 自行决定;您可以在提示词中要求进行一次咨询,但没有任何设置可以限制或强制调用。该功能仍处于实验阶段,通过 Anthropic API 向订阅账户和按 API 计费的账户开放,并于 v2.1.300 登陆 AWS 上的 Claude Platform(文档页面仍将该平台列为不受支持)。通过网关使用时,它依赖请求完整无损地到达 Anthropic API,并且需要获取功能标志,因此诸如 DISABLE_TELEMETRY 之类的变量会使其保持关闭。273274

启用方式。 共有三种途径:在会话中执行 /advisor <model>,该选择会保存到用户设置中的 advisorModel(不带参数的 /advisor 会在终端中打开选择器,而在 -p、SDK、桌面端和 Remote Control 会话中则打印当前的 advisor,这些会话自 v2.1.260 起支持文本形式;/advisor off 则将其关闭);在设置文件中写入 "advisorModel": "opus";或者使用 claude --advisor <model> 仅对单个会话生效,这个标志未在 --help 中列出,其优先级高于设置项,且若配对无效则会在启动时退出。可用的别名为 fable、opus 和 sonnet,也可以使用完整的模型 ID。CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 会移除该命令、忽略该设置,并使该标志不产生任何效果。274

配对、费用与可见内容。 advisor 的等级必须不低于主模型:Opus 4.7 和 4.8 可搭配 Fable、Opus 4.7 或更高版本以及 Sonnet 5.5(自 v2.1.287 起);Sonnet 5.5 可搭配 Fable、Opus 5 或更高版本以及 Sonnet 5.5;Opus 5 和 5.5 可搭配 Fable 和 Opus 5 或更高版本;Fable 5.1 只能搭配 Fable 5.1;Haiku 4.5 可以调用 advisor,但不能充当 advisor。等级低于主模型的 advisor 不会被附加,并会有通知说明这一点;被 API 拒绝的 advisor 则会在该对话的剩余部分被静默丢弃。subagents 在同样的配对检查下继承 advisor,并且会遵循 availableModels 允许列表。每次调用按 advisor 模型的输入和输出费率计费,或计入套餐限额;唯一例外是,在 Fable 本身计入用量积分的套餐上,Fable advisor 也会计入用量积分,前提是已通过 /model fable 给出过一次性同意。开关 advisor 不会影响主模型的提示词缓存;advisor 自身对对话的读取则从不缓存。在会话记录中,Advising 行会显示 Reviewed、Declined 或 Unavailable,按 Ctrl+O 可查看指导内容。Mods 会在 turn.step 上以 serverToolUses 的形式看到 advisor 调用(v2.1.290)。274

Effort 控制(v2.1.111+,Opus 4.7)

Opus 4.7 引入了一个新的 effort 调节旋钮,用于在速度与智能之间进行权衡。在会话期间使用 /effort:

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly
级别 适用场景
low / medium 适合可通过抽查把控质量的快速迭代
high 对智能敏感的用例的推荐最低级别;除 Opus 5.5 和 Sonnet 5.5(medium)以及 Opus 4.7(xhigh)外,所有模型的默认值
xhigh 在 Opus 4.7 上进行编码和代理式工作的推荐起点,也是该模型的默认值
max 质量最高,但速度最慢、费用最高;除非通过 CLAUDE_CODE_EFFORT_LEVEL 设置,否则仅对当前会话生效。即使在 v2.1.251 引入按模型持久化之后依然如此,该持久化只覆盖会持久保存的级别(low 到 xhigh)206
ultracode 这是一个 Claude Code 设置,而非模型的 effort 级别:Claude 会为实质性任务编排动态工作流。自 v2.1.284 起,它成为一个独立的开关(在 /effort 滑块中按 Tab,或使用 /effort ultracode on / /effort ultracode off),不会改变 effort 级别,且在任何级别下都保持开启;在 v2.1.284 之前,开启它会将会话设为 xhigh。claude --effort ultracode(v2.1.203+)仍以 xhigh 启动并开启 ultracode,"ultracode": true 设置则让会话在启动时即开启该功能;effortLevel 和 CLAUDE_CODE_EFFORT_LEVEL 不接受此值247228230
Claude Code 在 Opus 4.7 上默认使用 xhigh effort。该调节旋钮刚推出时,xhigh 仅限 Opus 4.7,其他模型会回退到 high;如今已不再如此。Opus 5.5、Sonnet 5.5、Opus 5、Opus 4.8、Sonnet 5、Fable 5 和 Fable 5.1 均支持完整的 low/medium/high/xhigh/max 阶梯,因此 /effort xhigh 和 /effort max 在当前模型阵容上都是可用选项,而非 Opus 4.7 独有。除 Opus 5.5 和 Sonnet 5.5 默认为 medium230 外,其余模型均默认为 high;在 /effort 改为按模型保存之前存下的顶层 effortLevel 不适用于 Opus 5.5,因此它会以 medium 启动,直到您为其选定级别。223 Claude Managed Agents 会自动处理 effort;effort 参数是 Messages API 的概念。145146197

按模型保存(v2.1.251+): /effort 现在会按模型保存您的默认 effort 级别,因此切换模型时每个模型都保留各自的设置;在 Opus 上养成的 xhigh 习惯不会再跟随您转到 Haiku(CHANGELOG:”Changed /effort to save your default effort level per model, so each model keeps its own setting when you switch”)。max 仅限当前会话的例外规则依然适用。206 v2.1.284 滑块按键: effortSlider:decreaseEffort、increaseEffort 和 toggleUltracode 这几个键绑定操作允许您在 keybindings.json 中重新绑定滑块的方向键和 Tab 键。228 v2.1.257 完善了这两个调节旋钮: /effort 接受 s 作为仅限会话的选择,与 /model 的约定保持一致;--effort 标志现在的作用域为会话级,它只在该会话中解除新模型的默认 effort 锁定,而不是永久解除(CLI 参考文档的说法:它“覆盖”默认值,“仅对本会话生效且不会持久保存”)。211243

Max 套餐上的自动模式(v2.1.111+)

自动模式是所有套餐和所有提供商上交互式终端会话与 VS Code 会话的内置初始权限模式(v2.1.283-284);从 v2.1.285 起直到 v2.1.302 将其撤回为止,对于第三方提供商上或关闭遥测时的 claude -p 和 Python Agent SDK 会话也是如此;自 2026年8月14日起(8月7日宣布),它已是 Pro、Max 和 Team 套餐的默认模式。关于该公告中的研究数据、退出途径以及仍以手动模式启动的会话,请参阅权限模式。203226227228229

一个独立的分类器模型(自 v2.1.210 起为 Claude Sonnet 5)会在每项操作运行前进行审查,确认其符合您的意图且安全无虞。187 使用 --permission-mode auto 以自动模式启动会话;v2.1.111 移除了旧的 --enable-auto-mode 标志。

可用范围的扩展历程:

版本 变更
v2.1.111 作为 --dangerously-skip-permissions 更安全的替代方案推出,最初面向通过 Anthropic API 使用 Opus 4.7 的 Max 订阅用户146
v2.1.158 在 Bedrock、Vertex AI 和 Foundry 上为 Opus 4.7 和 Opus 4.8 提供可选启用,通过 CLAUDE_CODE_ENABLE_AUTO_MODE=1 开启266
v2.1.207 这些提供商上不再需要手动选择启用;管理员可通过 disableAutoMode 托管设置关闭自动模式。autoMode 设置不再从仓库的 .claude/settings.local.json 读取,因此请在 ~/.claude/settings.json 中配置规则。同一版本还将 Bedrock、Vertex AI 和 AWS 上的 Claude Platform 的默认模型改为 Opus 4.8185
v2.1.247 Bash 权限提示提供一键选项“Yes, and switch to auto mode”(是,并切换到自动模式)245
2026年8月14日 成为 Pro、Max 和 Team 套餐的默认初始模式;在此之前 Pro 一直被排除在外203
v2.1.283 成为第三方提供商上以及关闭遥测时交互式会话的内置初始模式;权限模式文档将“所有套餐和提供商”的默认设置追溯至此版本226227
v2.1.284 发行说明:交互式终端会话和 VS Code 会话“在所有套餐和提供商上”均以自动模式启动;自动模式在读取工作目录之外的内容前的提示新增了 Yes, but ask again next time(是,但下次再询问)选项228
v2.1.285 在未配置权限模式时,第三方提供商上或关闭遥测时的 claude -p 和 Python Agent SDK 会话以自动模式启动(--permission-mode 可覆盖);将自动模式设为默认的一次性提示也会在这些会话中显示229
v2.1.302 在第三方提供商上、关闭遥测时以及全新安装的情况下,未指定权限模式的 claude -p 和 Agent SDK 会话重新以 default(手动模式)启动;--permission-mode auto 仍保持自动模式。交互式会话不受影响275
安全检查在何处运行(v2.1.278+)。 v2.1.273 曾短暂地让 Bedrock、Vertex AI 和 Foundry “暂时”默认使用本地分类器,并通过 CLAUDE_CODE_AUTO_MODE_SERVER=1 选择服务器。217 v2.1.278 推翻了这一做法。如今,对于 Enterprise 和 Claude API 账户、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry,以及经由 LLM 网关的连接,auto mode 默认都请求服务器执行检查。自 v2.1.282 起,不获取功能标志(例如因为关闭了遥测)的直连 Anthropic API 会话也默认请求服务器。225227 由服务器执行的检查不计费;本地分类器的请求则按普通 token 用量计费。219223

/auto-mode-setup(v2.1.304)。 引导式设置会读取您的项目以及您在该项目中的近期会话,为 ~/.claude/settings.json 起草 autoMode.environment 条目,即分类器据以推理的信任与敏感度槽位;它在 Bedrock、Vertex、Foundry、Claude apps 网关以及关闭遥测的情况下同样可以运行。auto mode 配置文档对此有专门说明。v2.1.310 改写了 auto mode 在首次读取工作目录之外的内容前显示的提示,说明在何种情况下阻止这些读取会导致 shell 命令请求权限;环境变量页面现在也记载了 CLAUDE_CODE_AUTO_MODE_MODEL,该变量需要填写完整的模型 ID。278279

  • 选择退出: CLAUDE_CODE_AUTO_MODE_SERVER=0 保留本地分类器(其请求会计入用量),1 则选择加入。在 v2.1.281 之前,直连 Anthropic API 时不会读取该变量;v2.1.281 起在直连场景下也会应用它,auto mode 计费文档现已注明,直连时需要 v2.1.281 或更高版本。224227 文档称该变量是临时性的。若该变量未设置而设置了 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1,同样会停止服务器端检查。
  • 当服务器端检查无法触达会话时: 最常见的原因是网关或代理剥离了 safeguards 请求字段、从响应中丢弃了 safeguard_results,或改写了工具使用 ID。Claude Code 会显示一次性通知(“此会话不符合条件”),能识别出网关时会指出其名称,并在会话余下的时间里改用自身计费的分类器请求。在 -p 模式下,该通知输出到 stderr,stream-json 输出则会发出一条 system 警告。Pro、Max 和 Team 会话永远不会看到此通知。网关侧的修复方法是将请求字段和响应键原样透传。
  • 检查某个会话: /status 会显示一行 Auto mode server,当服务器端检查决定会话操作时显示 Enabled,回退之后则显示 Disabled。219

Auto Mode 不是什么:它不是安全边界。 下文的大部分内容都是在加固一个分类器,而分类器并不是沙箱。2026年8月26日,提示注入研究者 Johann Rehberger 公布了一条针对 auto mode 下 Claude Code Opus 5 的可行攻击链,报告称在小样本上的攻击成功率为 60% 到 80%——派生隔离 python3 子进程的主攻击链为 5 次中成功 3 次,载荷派生无头 claude -p 实例的变体在两种配置下分别为 5 次中 3 次和 5 次中 4 次——他本人也提醒,这些只是小样本,而非普适的攻击成功率测量。210 这条攻击链值得弄清楚,因为其中每一步单独看都合情合理:服务器对 WebFetch 回应 HTTP 415,于是 agent 回退到 curl;下载的归档解压到一个临时目录,里面带有一份清单、七条 Base85/zlib 编码的数据记录、一个原生二进制文件和一个 struct.py;Claude 拒绝运行这个不受信任的二进制文件,随后却写了它自己的 Python 解码器,并在该目录内部运行;解码器导入 base64,base64 导入 struct,而 Python 首先解析到的是攻击者的 struct.py。整个序列中没有一条明显恶意的指令——注入只需让被攻陷的路径成为完成任务最合理的方式即可。Rehberger 还报告,在少数几次运行中,Claude 在察觉到被攻陷后曾试图终止恶意软件进程,而 auto mode 拒绝了这条清理命令。210 他将整个发现与 Anthropic 曾用于宣传的一个数字对照来看:一项受委托的第三方评估报告称,Opus 5 在 auto mode 下跨 72 个场景、每个场景运行十次,提示注入攻击成功率为 0.00%。他的攻击链并不在那组场景之内,这正是 0.00% 的基准结果与一条可行的代码执行链为何能同时成立的原因;在他看来,这两条信息彼此并不相容。210 还要留意其分类:Simon Willison 在8月30日的更新中认同一位读者的观点,即这并非经典的提示注入——模型从未读取并遵循攻击者的指令——而是一种环境混淆攻击(confused environment attack)。210

Anthropic 以 Informative(信息性,即行为符合设计)结案了该报告,而 Rehberger 转述的回复立场,正是设计时应当依据的立场:auto mode 是尽力而为的分类器,而非安全保证;由各自无害的步骤拼成的蓄意注入链,超出了分类器被期望捕获的范围;真正的隔离边界是操作系统级隔离与网络出站控制。210 这与下文的加固措施并不矛盾——它恰恰是理解这些措施的正确框架。auto mode 减少了您需要回答的提示数量,并阻止一份记录在案的破坏性操作清单;但它并不能让一个处理不受信任输入的会话变得安全。如果会话会接触受攻击者影响的内容——抓取的网页、下载的归档、issue 文本、第三方 MCP 服务器——真正限制损害范围的控制措施都在模型之外:容器或虚拟机、受限的网络出站、对 agent 实际行为的监控,以及一个不存放您不愿丢失的 SSH 密钥和云凭据的主目录。auto mode 的批准并不能证明某个操作是安全的。

自定义规则而不丢失默认规则(v2.1.118+)。 早期版本中,autoMode.allow、autoMode.soft_deny 和 autoMode.environment 是非此即彼的:定义了自己的列表,就会失去内置的安全规则。$defaults 哨兵值解决了这个问题——它会在您放置它的确切位置内联展开为内置列表,因此可以在内置规则周围叠加自定义规则:152

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

从 /permissions 编辑分类器的规则(v2.1.246)。 运行 /permissions 并打开 Auto mode 选项卡,该选项卡仅在会话可使用 auto mode 时出现。它列出分类器读取的每个作用域中的 allow、soft_deny、hard_deny 和 environment 条目,并显示每个部分的内置规则是否生效;来自托管设置或 --settings 的条目为只读,所有更改都保存到 ~/.claude/settings.json。向某个部分添加第一条规则时会同时插入 "$defaults",以保持内置规则生效;可以按部分开关内置规则(一个部分必须先有至少一条您自己的规则,才能关闭其内置规则);environment 则会作为一份文档在您的编辑器中打开。249247

“不再询问”选择加入(v2.1.118+)。 Auto Mode 的选择加入提示现在提供“Don’t ask again”(不再询问)选项,经常使用的用户无需通过脚本设置标志即可隐藏说明。152

破坏性命令防护(v2.1.183)。 auto mode 现在会硬性阻止一组不可逆命令,除非您在本次会话中明确要求执行:在您未要求丢弃本地工作时的破坏性 git 操作(git reset --hard、git checkout -- .、git clean -fd、git stash drop);提交并非 agent 在本次会话中创建时的 git commit --amend;以及基础设施拆除(terraform destroy、pulumi destroy、cdk destroy),除非您指明了具体的 stack。这恰恰针对那些会悄悄丢失工作或拆毁环境的操作,收窄了分类器的影响范围——agent 仍然可以运行它们,但只能依您的明确指示,而不能自作主张。174

对每条 shell 命令进行分类(v2.1.193)。 默认情况下,auto mode 分类器只审查匹配任意代码执行模式的 shell 命令;常规命令会跳过审查。新的 autoMode.classifyAllShell 设置改为将所有 Bash/PowerShell 命令都送入分类器,以少许延迟换取更严密的安全网,适合希望每一次 shell 调用都经过审核的场景。同一版本还在转录、拒绝提示和 /permissions 的近期拒绝记录中显示 auto mode 拒绝原因,因此被阻止的命令现在会说明被阻止的原因。179 又增三条加固规则(v2.1.205)。 自动模式现在会阻止篡改会话记录文件——审计轨迹本身对代理来说是禁区;在对无法从上下文解析的变量执行 rm -rf 之前会先询问——堵上了 rm -rf $DIR 而 $DIR 未知这一类事故;此外,后台任务通知现在会明确声明没有发生任何人工输入,这样记录中伪造的“用户已批准”一行就无法被洗白成一次已被执行的批准。183 第三条是一项值得牢记的提示注入防御:批准必须通过批准渠道到达,而 harness 现在把这一假设变成了明文规定。

命令替换藏不住灾难性操作(v2.1.208)。 诸如 rm -rf ~ 之类的灾难性删除,即使藏在 $(...)、反引号或进程替换(<(...))里,现在也会触发提示——而且即便在 --dangerously-skip-permissions 和自动模式下,提示同样会弹出。把破坏性命令包进替换语法,再也无法让它绕过安全网。186

重置自动模式状态:claude auto-mode reset(v2.1.212)。 新增的子命令可以直接在终端重置自动模式状态;传入 --yes 可跳过确认提示:189

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

对话框更少,审查不减(v2.1.218)。 过去有三类检查会以权限对话框打断自动模式——危险的 rm、后台 & 以及可疑的 Windows 路径——现在不再如此;改由自动模式分类器裁决,安全审查照常进行,却不必每次命中都把您拉进来。同一版本还把这一机制扩展到了启用自动模式的计划模式:静态分析器无法证明为只读的 Bash 命令不再弹出提示——改由分类器判断,而不是退回到对话框。195

逃逸隔离规则(v2.1.257)。 分类器的“永不自动批准”清单新增了一条“逃逸隔离”(Containment Escape)规则:获取云元数据凭证、规避网络出站限制以及跨租户访问,除非环境明确标记为预期行为,否则不再自动批准。请按上文注意事项设定的框架来理解:这是分类器的持续加固——又一个有据可查的拒绝类别,而非对自动模式本质的改变。211

读取工作目录之外的文件时一次性提示(v2.1.257)。 自动模式现在会在会话首次读取工作目录之外的文件前询问一次;自 v2.1.284 起,该提示还提供是,但下次再问这一选项。228 配套的 permissions.blockReadsOutsideWorkingDirectories 设置会把提示变成拒绝——此类读取会被直接阻止。211 v2.1.273 把这两种行为扩展到了检查器看不见的地方:无法完全分析的 Bash 命令会触发提示而不是跳过检查;在阻止设置生效时,由仓库设置指定的记忆目录不再被加载进提示、被回忆、被索引,也不再被记忆提取使用。217

图表渲染器 URL 视同上传(v2.1.261)。 把内容打包进公共图表渲染器 URL 的链接——mermaid.live 这类,数据直接编码在 URL 里——除非是您主动要求,否则不再自动批准。分类器把这种链接当作一次上传:打包的数据随 URL 本身传输,页面一打开,渲染站点自己的脚本就能读到它——mermaid.live 这类链接把载荷放在 URL 片段中,浏览器会把它交给页面的 JavaScript,而不是随网络请求发送。框架与上文注意事项相同:这是加固中的分类器又堵上了一条数据外泄渠道,而非划定新的边界。214

分类器的两种失败模式有了终止条件(v2.1.280)。 在此版本之前,当安全检查没有返回可用的裁决时,自动模式束手无策;从操作者的角度看,这两个缺口表现一模一样:一个回合空转,为一个永远不会获批的操作白白消耗 token。v2.1.280 为两者各自设定了终止状态。

失败模式 之前 之后(v2.1.280)
安全检查拒绝审查该操作 自动模式一遍又一遍地重试该操作 该操作仅被拒绝一次,并附带说明重试也无济于事220
安全检查没有给出答复 自动模式不停地反复拒绝该操作 重试会逐步退避,并在连续十次之后回合停止并给出提示220
请把这些视为可靠性修复,而非策略变更:之前获批的操作现在不会被拒绝,之前被拒绝的也不会获批。变化在于,分类器给出不确定结果时现在会终止而不是循环。两点实用提示。第一,“仅拒绝一次,重试无济于事”这条消息既是说给您听的,也是说给模型听的——它的作用是阻止 Claude 再次尝试同一调用,而这正是循环的根源。第二,连续十次检查无答复会结束回合,因此如果您在自动模式下运行长时间无人值守的会话,而某个会话带着这条消息提前停止,该排查的是安全检查是否能到达会话,而不是您的权限规则。发布说明没有指明原因;自动模式计费文档把会篡改请求字段或响应的网关或代理列为服务器端检查无法到达会话的最常见原因,因此不妨把它作为首要排查对象。

服务器端审查覆盖更多命令(v2.1.281)。 在分类器审查于服务器端运行的场景下,只读命令和沙箱内的 shell 命令现在也要等待该审查,被标记时同样会被阻止。拒绝消息也有所调整,让 Claude 把一次拒绝理解为针对结果本身,而不只是针对那条具体命令。会话在新进程中恢复后,分类器可以复用先前的提示缓存,而无需重新生成。此外,/insights 新增了自动模式建议,估算在您最近的会话中自动模式本可以处理多少权限提示。224

无人值守的会话不再卡在 rm 提示上(v2.1.281)。 在自动模式和 --dangerously-skip-permissions 下,危险 rm 提示现在会等待 2 分钟,无人应答则拒绝该命令并给出改写建议,这样无人值守的会话得以继续;设置 CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1 可关闭这一超时。目标完全来自命令替换输出的递归 rm,例如 rm -rf "$(pwd)",过去在两种模式下都会不经提示直接运行;现在即使匹配了 Bash 允许规则也会询问,除非设置了 CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1。危险 rm 检查还会标记以下几类删除:目标是 shell 变量后接顶层目录名、目标是从工作目录派生的变量,或目标仅为一个反斜杠。224 自 v2.1.299 起,不执行 rm 的 shell -c 脚本不再触发提示;而在 Claude Code 无法读取的脚本中于运行时拼出的 rm,只有在设置了 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 时才会触发提示。271

内联 ! shell 脱离分类器;subagent 的交回操作纳入分类器(v2.1.271)。 这是两项机制调整,而非新增拒绝类别。skill 或斜杠命令中的内联 ! shell 命令现在遵循默认模式的权限规则,而不再交给分类器——没有任何规则裁定的命令会作为受审查的工具调用来运行。另外,subagent 现在通过一个专门的交回调用向调用方汇报,该调用由安全分类器审查,而不再是事后审查它的最后一条消息——检查点从交接之后移到了交接本身。216

v2.1.311 至 v2.1.317 的新变化

Claude Code 在 2026年10月26日至11月2日之间发布了五个版本:2.1.311(10月26日,npm 19:47 UTC;92 条)、2.1.312(10月27日;39 条)、2.1.314(10月30日 00:12 UTC;119 条)、2.1.316(10月31日 00:42 UTC;55 条)和 2.1.317(11月2日 23:57 UTC;87 条),每个 GitHub 发布版本都与其 CHANGELOG 章节完全一致。2.1.313 从未发布,2.1.315(npm,10月30日 21:05 UTC)既无 CHANGELOG 条目,也没有 GitHub 发布版本。npm 的 latest 和 next 均为 2.1.317,stable 则从 2.1.308 移到了 2.1.311。284 努力程度(v2.1.311、v2.1.316、v2.1.317)。 在交互式终端中输入 ultrathink,现在会让该轮对话以 xhigh 努力级别运行,覆盖通过 Anthropic 的 API 使用的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1;若在 Claude 工作期间输入,则会提升该轮余下部分的努力级别。彩虹高亮只会出现在该词能够提升努力级别的位置,被引用或作为路径一部分时不会显示(v2.1.311)。VS Code 从 v2.1.316 起具有同样的行为,CLAUDE_CODE_DISABLE_ULTRATHINK=1 可关闭该关键字(v2.1.316)。CLAUDE_CODE_SUBAGENT_EFFORT 用于设置 subagents 在没有其他设置指定时的运行努力级别,而不再继承会话的级别(v2.1.316);与主对话使用不同模型的 subagent 或团队成员,会采用该模型已保存的努力级别或其默认值(v2.1.317)。请参阅扩展思考和Subagents。284285

模型与提供商(v2.1.311 至 v2.1.316)。 对于后缀不起作用的模型,模型名称和 ID 不再显示 [1m] 后缀及其标签,但该后缀仍可被接受(v2.1.311)。Bedrock、Mantle、Vertex AI 和 Foundry 会话会从 downloads.claude.ai 上的签名文件加载模型设置,CLAUDE_CODE_MODEL_CATALOG=off 可关闭此行为(v2.1.311)。在这些提供商上,Claude Code 无法识别的模型名称(例如自定义部署名称或推理配置文件 ARN)会使用较短的系统提示,即使它背后实际是 Sonnet 或 Haiku;CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0 可保留完整提示。请求被标记后的自动模型切换同样覆盖无法识别的名称,CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1 可将其关闭(v2.1.312)。当 ANTHROPIC_DEFAULT_OPUS_MODEL、availableModels 或 deniedModels 只留下较旧的 Opus 模型或一个都不剩时,被标记的请求会改在另一个模型上重试,而不是以拒绝告终(v2.1.314)。经由 LLM 网关、以点号拼写的模型 ID(例如 claude-opus-4.8)不再被当作旧模型处理,从而避免了错误的上下文窗口、输出上限、努力级别、思考模式和成本(v2.1.314)。Opus 4.8 的快速模式已于2026年10月30日弃用,并将于2026年11月30日移除;此后,Opus 4.8 上的快速模式请求会返回错误,且不会回退到标准 Opus 4.8,因此请使用 /model 切换到 Opus 5.5 以保留加速效果,或运行 /fast off 继续使用 Opus 4.8(v2.1.316)。284285

权限、沙箱与 hooks(v2.1.311 至 v2.1.317)。 permissions.blockWritesOutsideWorkingDirectories 会让 Write、Edit 和 NotebookEdit 在所有权限模式(包括 bypassPermissions)下拒绝工作目录之外的路径;它不限制 shell 命令、MCP 工具或 hooks 运行的程序,并且会移除 EnterWorktree 和 ExitWorktree 工具(v2.1.314)。在网页或 shell 工具调用把您的账户电子邮件地址发送到网络之前,Claude Code 会先行询问(v2.1.317)。--restricted 会话不再上传工作目录之外的文件,即使 Read 允许规则覆盖了这些文件(v2.1.316)。匹配 Bash 的 hooks 现在也会在 Monitor 工具的 shell 命令上运行,可以阻止或询问,但不能批准或改写;hook 的 if 条件(例如 Monitor(tail *))匹配这些命令的方式,与 Bash(tail *) 匹配 Bash 命令的方式相同(v2.1.314)。PreCompact hook 的输出会在 10,000 个字符处截断,因此超大输出不会导致压缩失败或重复压缩(v2.1.314)。prompt 类型和 agent 类型的 hooks 在每个会话中(包括 subagents)同时最多运行 24 个,外加最多 12 个等待时间已超过其事件超时的 hooks;小于一秒的 timeout 按一秒计算(v2.1.312)。SubagentStop hooks 在 subagent 完成时触发一次,而不再在其运行期间大约每分钟触发两次(v2.1.311)。sandbox.excludedCommands 的说明现在如实描述了 v2.1.277 起的实际行为:一次调用中的每条命令都必须匹配某个条目(v2.1.314)。在 /permissions 中,审查标签页现在名为“Recently blocked”(最近被阻止),且拒绝批准无法完整显示的调用(v2.1.314)。284285

压缩、上下文与打印模式(v2.1.311 至 v2.1.317)。 空闲压缩已扩展到 VS Code 和桌面应用的 Code 标签页:达到 200K 或更多 token 且处于空闲状态的对话会被摘要,待提示缓存过期后,您的下一条消息便会使用该摘要;此功能同样适用于关闭了遥测的订阅用户,并且在 Bedrock、Vertex AI、Foundry 和 LLM 网关上,只要启用了一小时提示缓存也会运行(v2.1.314)。标准上下文会话的请求超过 200K token 时会进行压缩并继续,而不再因“Usage credits required for 1M context”而停止(v2.1.311)。当模型的回复不包含摘要时,压缩通常会再请求一次,然后才替换对话(v2.1.311);当压缩不得不缩短自身请求时,超长对话会保留此前的摘要(v2.1.317)。设置文件或 mod 的 $.env.set 中的 DISABLE_COMPACT 只能关闭压缩,不能重新开启(v2.1.311)。subagent 的 autoCompactWindow 可以调低 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设定的窗口,但仍然不会调高(v2.1.312)。用量限制消息把 5 小时窗口称为“5-hour limit”(5 小时限制),而不再称为“session limit”(会话限制)(v2.1.312)。claude -p 在启动失败(v2.1.314)以及磁盘已满或配额耗尽导致转录文件或 ~/.claude.json 写入丢失(v2.1.317)时,会打印错误并以 1 退出;这两种情况此前都以 0 退出。达到超时的 shell 命令会显示截至当时的输出,并在后台继续运行(v2.1.311)。再次读取未更改的文件会返回其内容,“file unchanged since your last Read”(文件自上次 Read 以来未更改)占位提示已被移除(v2.1.317)。284

云会话、运行器与 Remote Control(v2.1.311 至 v2.1.317)。 claude self-hosted-runner 新增 --hold-idle-file <path> 和 --max-hold-min <n>,用于在您的主机报告其遗留的仍在运行的进程期间保持空闲会话(v2.1.311);CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 则让在运行器会话内执行的 claude -p 复用该会话的 ID 和转录文件,即 v2.1.317 之前可能恢复到错误对话的那种行为。在遇到 501 或 529 以外的 5xx 错误,或心跳无响应之后,运行器会话会建立新连接,而不再复用失败的那个连接(v2.1.317)。当 MCP 服务器要求您访问某个 URL 时,云会话会显示链接卡片(v2.1.317);当它请求填写表单时,则显示表单卡片(v2.1.316);切换回云会话或 Remote Control 会话时,加载期间会显示“Catching up”(正在同步);Enterprise 成员可以在自己的云环境中添加和删除网络密钥(v2.1.316);在云端运行的例程可在其模型选择器中设置努力级别(v2.1.312);Anthropic 云端的计划任务会加载您 claude.ai 账户上启用的 plugins,并且即使设置脚本以错误退出,云会话也会照常启动(v2.1.314);新的计划任务会在组织的默认环境中启动(v2.1.317)。当 disableRemoteControl 设置已关闭 Remote Control 时,/remote-control 会予以说明(v2.1.317)。在某些桌面会话中,项目级和本地 MCP 服务器不再在第一轮对话之后断开连接(v2.1.317)。284285

企业版:网关、托管设置与遥测(v2.1.312 至 v2.1.317)。 Claude apps 网关:oidc.user_id_claim 可通过 sub 以外的 id_token 声明来识别用户(v2.1.312);上游的 groups 列表只会把属于这些 IdP 组的开发者发送到该上游,故障转移时亦是如此,guardrail_trace 则会记录触发了哪个 Amazon Bedrock 护栏过滤器(v2.1.314);pooled_budget 为一个组提供一份共享的月度预算,managed.policy_mode: layered 会把每条匹配的策略合并叠加在其下层策略之上,guardrail.input_tagging 会添加 Bedrock 提示攻击过滤器所需的输入标签(v2.1.316);GET /v1/organizations/analytics/cost 可按开发者、日期或 IdP 组报告历史支出(v2.1.317)。为 Team 和 Enterprise 登录从 Anthropic 的 API 获取的服务器托管设置无需审批提示即可生效,而无法通过验证的本地存储副本会被拒绝(v2.1.316);Claude 的文件工具在编辑这些设置的本地副本之前会先行询问(v2.1.314);桌面应用的 Code 标签页会在组织的远程托管设置尚未加载时予以提示,并在加载完成后再次提示(v2.1.317)。OpenTelemetry 指标、事件和 span 现在携带 anthropic.plan、anthropic.seat_type、anthropic.provider 和 anthropic.custom_base_url;经由始终无响应的代理导出时,会在 10 秒后超时,或按 OTEL_EXPORTER_OTLP_TIMEOUT 设定最长 30 秒超时(v2.1.317);Claude Code 不再发送其在 v2.1.307 中添加的 claude_code.safety_event 事件(v2.1.312)。与前一版本交叉签名的续期根证书不再因 UNABLE_TO_GET_ISSUER_CERT 而失败(v2.1.314);对于需要循环交叉证书的私有 CA,CLAUDE_CODE_DISABLE_LOOPED_CROSS_CERT_DROP=1 可保留相互循环认证的系统交叉证书(v2.1.316)。284285 VS Code、Slack 及其他(v2.1.311 至 v2.1.317)。 VS Code:回复中的代码块现在带有语法着色;当 VS Code 自身的遥测关闭时,会话启动时会设置 DISABLE_TELEMETRY(v2.1.311);ultrathink 会以 xhigh 级别运行该轮对话并显示彩虹效果(v2.1.316);可以从聊天面板登录 Claude apps 网关(v2.1.316);CLAUDE_CODE_DISABLE_CFC_PROMPT=1 现在还会将 Claude in Chrome 的指令排除在会话消息之外,同时浏览器工具仍然可用(v2.1.314)。Slack 中的 Claude Tag:频道的“自动回复”开关变为“Claude 如何参与”选项(v2.1.316),分析页面新增 Skills 视图(v2.1.311),粘贴的 artifact 链接会显示带“打开”按钮的卡片(v2.1.317)。Code Review 分析页面新增了按严重程度统计发现项的卡片(v2.1.316)。FORCE_HYPERLINK=false(以及 no 和 off)会关闭终端超链接;在 v2.1.314 之前,这些值反而会开启超链接。Pro 和 Max 账户在距上次检查一小时内的启动会跳过两次网络请求,而仅带选项参数的启动(例如 claude --model opus)会更快(v2.1.311)。发送给正在运行的后台 agent 的 SendMessage 会更快送达:其正在运行的命令会转入后台而不会被中止(v2.1.317)。284285

应对建议:升级。如果某个会话仍在以开启快速模式的 Opus 4.8 运行,请在11月30日之前通过 /model 切换到 Opus 5.5(或运行 /fast off)。读取 claude -p 退出码的脚本应预期在启动失败或磁盘故障时得到 1。如果您之前为了启用超链接而设置了 FORCE_HYPERLINK=false,请将其改为 1。284

v2.1.309 和 v2.1.310 新增内容

Claude Code 2.1.309 于2026年10月22日发布(npm 20:34 UTC;GitHub 发布 22:18 UTC,79 个条目),2.1.310 于10月23日发布(npm 21:20 UTC;GitHub 发布 23:39 UTC,26 个条目),两者均与官方 CHANGELOG 完全一致。npm 的 latest 和 next 均为 2.1.310,stable 从 2.1.292 移至 2.1.308,后者的整个发布说明只有一句“Bug fixes and reliability improvements”(错误修复与可靠性改进);2.1.303(10月18日)也只有同样的一行。2.1.302 到 2.1.310 之间没有跳过任何版本。278

沙箱与权限修复(v2.1.309)。 macOS 和 Linux 上的沙箱化 Bash 命令不再在每条命令之前于沙箱外运行 shell 的启动文件;当模式中的文件夹是经由符号链接到达时,macOS 的 denyWrite glob 规则会应用于该路径的真实位置;沙箱化命令和自动接受的编辑不再能修改通过 --mcp-config 传入的 MCP 配置文件;当后台命令比会话存活更久时,Linux 的写入拒绝规则不再解除;在沙箱已启用但无法运行的情况下,被设置排除在沙箱之外的命令在写入沙箱写入列表中的路径之前现在会先询问,并且此时拒绝回退到非沙箱执行。Bash 权限检查不再信任由重定向可能失败的命令所设置的变量,会在 git 之前对被包装或带前缀的 cd 发出提示,并将 Edit(path) 拒绝规则应用于子 shell 内的 Bash 重定向;worktree 隔离守卫会拒绝更多带 locale 前缀的命令和 zsh 算术命令;profile 存储的写保护在通过符号链接访问的配置目录中同样生效。sed -i 现在会收到标准的 Bash 提示并按原样运行,而不是模拟的文件编辑预览;与其他 Bash 编辑一样,它也不再由 /rewind 恢复。请参阅沙箱模式。278

信任、worktree 与 skills(v2.1.309)。 claude ultrareview 需要工作区信任:在终端中会询问,否则拒绝运行;脚本可传入不带值的 --trust-workspace,或设置 CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1。在桌面应用和 VS Code 中,绕过权限模式下针对危险 rm 和 rmdir 的提示现在会立即拒绝该命令并给出改写提示,因此无人值守的会话可以继续运行。worktree 的创建和复用不再按需获取 git 对象(带有 Bash 沙箱的部分克隆会先行获取),worktree 和分支检出会忽略 git replace 引用。超出大小限制的嵌套 CLAUDE.md 现在只加载开头部分,这避免了会话在读取其下的文件后反复压缩。--add-dir 文件夹中与另一个 skill 同名的 skill 会以 <folder>:<name> 的形式提供,/verify 和 /code-review 能找到嵌套包自己的 skill。分屏 agent 队友会继承领导者的工具拒绝规则和 --tools 规则,/rewind 会列出通过 /code-review --fix、subagent 或 shell 命令更改了检查点文件的轮次。278

v2.1.310。 Monitor 工具和插件监视器现在可在 Bedrock、Vertex 和 Foundry 上使用,在遥测或非必要流量被禁用时也可使用,且在这些环境中长时间的前台 sleep 现在同样会被阻止。对于拒绝 effort-2025-11-24 beta 值或对话中途系统消息的网关和兼容服务器,请求会在去掉这些内容后重试。出现“Prompt is too long”错误后的压缩不再保留过多 base64 或 SVG 之类的密集文本;当 cleanupPeriodDays 设得非常大时,后台清理不再删除粘贴图片等近期文件;文件读取提示会显示符号链接的指向;auto 模式在首次读取工作目录之外的内容前显示的提示,现在会在适用时说明阻止这些读取将使 shell 命令转而请求权限;非交互式会话在压缩超大对话记录时占用更少内存;在 Ubuntu 上,/sandbox 和启动警告会指出 AppArmor 对用户命名空间的限制及其解除方法;mod 的 Image 可以在开启了 allow-passthrough 和 focus-events 的 tmux 中绘制,也可以在全屏渲染模式下的 kitty、Ghostty 和 iTerm2 3.5+ 中绘制;在非交互式会话中,若 MCP 工具调用因服务器的 elicitation 未获回应而超时,会告知 Claude 不要重复调用。云会话和 Remote Control 权限已加入 Enterprise 自定义角色。278

v2.1.307 新增内容

Claude Code 2.1.307 于2026年10月21日发布(npm 20:47 UTC;GitHub 发布 22:17 UTC;43 个条目,与官方 CHANGELOG 完全一致),此前的 2.1.306(10月21日 02:28 UTC)包含两项修复:云会话中的 claude -p 在缺少会话环境变量时不再报告“Not logged in”;在拥有大量 MCP 工具的会话中,API 错误不再被替换为“prompt is too long”并触发不必要的压缩。2.1.308(10月22日 04:19 UTC)是那个只有一行说明的可靠性版本,并成为了 stable。278

遥测与 API skill。 每当权限规则、auto 模式、安全检查、hook 或沙箱阻止、提示或退回某次工具调用时,都会触发 claude_code.safety_event OpenTelemetry 事件(请参阅环境变量参考)。/claude-api api-version 会将 Claude API 代码迁移到 API 版本 2026-10-21,/claude-api managed-agents-secure(v2.1.304)会将 Managed Agents 中某个 agent 的设置与 Anthropic 发布的安全指南进行比对,但不做任何更改;该 skill 现在基于 multiagent_20261001 构建 Managed Agents subagent 团队,并默认开启动态工作流(v2.1.309)。278279

修复与行为。 CLAUDE_CODE_DISABLE_1M_CONTEXT 搭配带 [1m] 后缀的别名(例如 opus[1m])时不再产生“模型未找到”错误;在自定义 ANTHROPIC_BASE_URL 网关之后或在 Foundry 上,不再发送 prompt-caching-scope beta 标头;在 macOS 登录钥匙串锁定期间无法连接的 MCP 服务器现在会说明原因,解锁后的下一次运行无需重新登录即可连接;当连接在调用中途关闭时,HTTP MCP 工具调用不再被发送两次,因为只有只读或幂等的工具会被重试;修复了读取大量 PDF 页面或图片的轮次中出现的“Autocompact is thrashing”错误;无法解析的工具调用最多重试两次,之后该轮次才以错误结束;一同启动的 fork subagent 会各自被告知哪一次启动属于自己;/permissions > “最近拒绝”会显示被拒绝的 shell 命令;axScreenReader 设置以及设置 env 块中的 CLAUDE_AX_SCREEN_READER 仅在来自用户、托管或 --settings 设置时生效(自 2.1.305 起);自托管 runner 的检出 hook 默认在 30 分钟后停止(--checkout-hook-timeout-min,设为 0 表示不限制)。Code Review 新增 @claude review stop(也可用 off 和 pause)用于结束 @claude review always 订阅。278

v2.1.304 和 v2.1.305 新增内容

Claude Code 2.1.304 于2026年10月19日发布(npm 19:47 UTC;GitHub 发布 21:34 UTC;76 个条目),2.1.305 于10月20日发布(npm 19:29 UTC;GitHub 发布 20:46 UTC;38 个条目),两者均与官方 CHANGELOG 完全一致;2.1.303(10月18日)是只有一行说明的可靠性版本。278 自动模式设置与 /usage 修复建议。 /auto-mode-setup(v2.1.304)是一个引导式设置流程,它会读取您的项目和近期会话,据此草拟 autoMode.environment 条目;该命令同样可在 Bedrock、Vertex、Foundry、Claude 应用网关以及禁用遥测的会话中使用,自动模式配置文档已对其作了说明。/usage(v2.1.305)将每条警告转换为一行修复建议并注明其来源,按 f 即可应用这些修复,它们也会出现在 VS Code 和 /doctor 中;/usage 还会显示用量数据的速率限制何时解除。在 Pro 和 Max 计划上,恢复一段会占用 5 小时用量上限中相当比例的闲置对话时,现在会显示警告,并提供改为开启新对话的选项(v2.1.304)。请参阅 Max 上的自动模式 以及 斜杠命令 下的 /usage 行。278279

设置与环境。 sandbox.allowNestedUserNamespaces(v2.1.305)允许 Linux 上的沙箱命令创建用户命名空间(Chromium、rootless podman),代价是这些命令可以绕过沙箱的文件保护。CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS(v2.1.305)让无人值守的重试模式能够察觉到在重置时间之前就已解除的用量限制。CLAUDE_CODE_AUTO_COMPACT_WINDOW 与 --autocompact 一样接受 k 和 M 后缀,并对超出范围的值发出警告(此前 200k 会悄无声息地设成 100K 窗口)。allowedMcpServers 不再过滤仅在 env 中使用 ${VAR} 的 managed-mcp.json stdio 服务器,因此您的允许列表中遗漏的某个服务器会在升级后被加载(如需继续禁用,请使用 deniedMcpServers)。在自定义 ANTHROPIC_BASE_URL 之下,工具搜索默认开启(v2.1.304);v2.1.305 修复了 2.1.304 的回归问题,该问题曾导致 Vertex、Bedrock 以及其他端点拒绝工具搜索的提供商上的每个请求都失败:Claude Code 现在会在不带工具搜索的情况下重试。Claude Desktop 按路径挂载的插件在 allowManagedPermissionRulesOnly 之下会失去其 allowed-tools。截至 10 月 23 日,除工具搜索默认值外,上述内容均已载入文档。278279

Mods、skills 与 hooks。 mod 的 tool.check 事件携带 e.isReadOnly,其回答可以设置 decider: "person",使得只有权限对话框或宿主回调才能批准;settings.read hooks 会接收每一层设置并改写合并后的设置;会话记录中会有一行指出哪个插件跳过了您的某个 hook;停靠面板的宽度保持在终端宽度的 45% 以内(v2.1.305)。压缩之后会再次向 Claude 发送 skill 列表,而 /reload-skills 只发送新增或有变动的 skills;同一来源的 skills 每个会话最多可注册 1,024 个 hooks 和 16,384 个匹配器字符;某个 skill 的 once hook 不再移除另一个 skill 的相同 hook。恢复工作流时,已完成的 pipeline() 和 parallel() 代理会从该次运行的日志中直接取回结果,而不是重新运行(v2.1.305);自定节奏的 /loop 按 1 小时上限安排的唤醒不再恰好落在提示缓存过期之后;当 HEAD 处于分离状态或位于其他分支时,claude --worktree 退出时不再未经询问就删除工作树及其分支;对已挂载驱动器或其顶层文件夹执行 rm -r 会触发安全提示;Code Review 新增审查级别(Quick、Standard、Deep)以及审查 GitHub 组织中每个仓库的选项。/fast 对话框在 Opus 5.5 上去掉了“(research preview)”标签。278

v2.1.302 新特性

Claude Code 2.1.302 于 2026年10月16日发布:npm 在 16:48 UTC 发布了它,GitHub 发布版本随后于 20:53 UTC 推出,包含与规范 CHANGELOG 相同的 63 条要点;npm 的 latest 和 next 均指向该版本,而 stable 仍停留在 2.1.292。它紧随 2.1.301(10月15日,51 条要点)之后;没有跳过任何版本。10月17日获取的文档已包含 2.1.301 的 vim 动作和 VS Code 数学公式渲染,但尚未收录下列任何条目,因此这些条目均以 CHANGELOG 为依据。275276

claude -p 与 SDK 再次以 Manual 模式启动。 未指定权限模式的 claude -p 或 Agent SDK 会话,在第三方提供商上、在关闭遥测时以及在全新安装后,现在均以 default(Manual)模式启动;--permission-mode auto 则保持自动模式。这推翻了 v2.1.285 中让这些会话以自动模式启动的规则,而交互式终端和 VS Code 会话维持原状:在所有计划和提供商上均为自动模式。权限模式文档仍描述的是 v2.1.285 的行为。请参阅 权限模式。275276

Fork subagents 与后台默认行为。 Fork subagents(subagent_type: "fork")在 claude -p、Agent SDK、桌面应用和 VS Code 中默认开启,与终端中原有的行为一致;CLAUDE_CODE_FORK_SUBAGENT=0 可将其关闭,而 claude mcp serve 从不提供此功能。桌面应用和 VS Code 现在总是像终端一样在后台运行主对话的 subagents,而不再交由 Claude 选择;与此同时,subagent 自身在 claude -p、SDK、桌面应用和 VS Code 中发起的 Agent 调用默认在前台运行。提示 hooks 和代理 hooks 现在同一事件最多同时运行 12 个,其余的排队等候(v2.1.312 中提高为每个会话同时 24 个)。环境变量文档和 sub-agents 文档仍称 fork 模式仅在交互式会话中开启。请参阅 什么是 Subagents?。275276

自动模式与压缩。 CLAUDE_CODE_AUTO_MODE_MODEL 用于指定客户端自动模式分类器所使用的模型;它不会改变服务器端自动模式的模型。使用服务器端分类器时,对于长度超出安全检查上限的对话,现在会对其进行压缩,而不再拒绝每一个受检的工具调用。/config 新增 Idle compaction(闲置压缩)一行,用于关闭或重新开启闲置压缩;闲置压缩后显示的通知也会说明如何将其关闭。在压缩进行中停止一轮对话时出现的“Prompt is too long”错误已修复;当网关以 anthropic/claude-opus-4-1 之类的前缀形式命名 Opus 4 或 4.1 时,/autocompact 和 /effort 会保存到正确的模型。275

Claude Design 将于 2026年12月14日前关闭。 /design-sync 和 /design-login 现在会显示一则通知,说明独立的 Claude Design(claude.ai/design)将在该日期前关闭;/design consent 和 /design revoke 会将云会话指向 claude.ai/design/settings,而不再是 /design-login。请参阅 斜杠命令 下的 /design 行。275

值得了解的修复。 Read 工具不再将任意大小的图片,或名称形似图片的管道或设备,整个加载到内存中:超过 128 MB 的图片源会被拒绝。会话中途添加、随后通过 ToolSearch 或在压缩后再次加载的工具,不再导致提示缓存未命中。claude plugin 及其他子命令会等待排队中的设置或配置写入完成后再退出,因此更改不再丢失或遗留为 .tmp 文件。当 git 默认使用 reftable 引用格式时,插件市场不再在每次刷新时重新克隆,git 插件也不再显示版本“unknown”;当一个残留的 .git 文件指向不存在的目录时,工作树隔离在 git 2.56 或更高版本下仍可正常工作。协商协议版本为 2026-07-28 但省略了 resultType、ttlMs 或 cacheScope 的 MCP 服务器现在会显示其工具。在一次以用量额度(usage credits)计费的回复之后,会跳过提示建议。会话中途切换到 Vertex 或 Bedrock 后,请求不再因“diagnostics: Extra inputs are not permitted”而失败。安装大量插件时的启动速度更快,在 Windows 上尤为明显;Windows 上对 exFAT 或 FAT32 驱动器的文件写入也不再被拒绝。275

云会话与 Claude Tag。 例程(routine)页面会显示一条横幅,说明其上一次运行未能启动的原因,例如组织对并发云会话数的限制;“Rewind to here”(回退到此处)对每条消息均可用(自托管运行器需要 v2.1.246 或更高版本);中途失败的运行不再在一小时后从头重复执行;云会话在新进程中恢复后,其费用和用量不再从零重新开始计算。Claude Tag 的管理员设置重新组织为 Bundles、Connectors、Skills and plugins 以及 Channels 标签页;在 Slack 中附加的 HEIC、SVG、TIFF 和 BMP 图片现在会以文件形式送达 Claude;在按角色限制使用的组织中,manager 角色现在也可授予 Slack 中的 Claude Tag 使用权限。275

v2.1.301 新特性

Claude Code 2.1.301 于 2026年10月15日发布(npm 为 14:34 UTC;19:22 UTC 的 GitHub 发布版本包含与规范 CHANGELOG 相同的 51 条要点)。npm 的 latest 次日便移至 2.1.302,因此这两个版本在此一并介绍。275 无人值守重试新增用量上限封顶。 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS 让无人值守重试模式(CLAUDE_CODE_RETRY_WATCHDOG)在遇到重置时间过于遥远的用量限制时直接结束请求,而不是一直等待;它与 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 一同列在环境变量参考中。同样面向运维人员:切换到上下文窗口更小的模型时,如今会由先前的模型为新模型摘要过长的对话,而不是未经询问就消耗用量额度生成摘要;当最新的 Fable 模型对您的组织不可用时,fable 和 best 别名会在上一代 Fable 模型上重试一次;而位于 LLM 网关之后、响应中标注的模型与所请求模型不一致的对话,也不再被反复压缩。275

遥测、vim 与 mods。 OpenTelemetry 的 tool_decision 事件新增 classifier_verdict 和 permission_mode,使自动模式分类器的决策能与权限规则区分开来;当 OTEL_LOG_TOOL_DETAILS=1 时,还新增 classifier_category,标明分类器拦截所匹配的内置规则。Vim 模式新增 % 动作:跳转到匹配的括号,可单独使用,也可与 d、c 或 y 组合(交互模式文档已列出该项)。Mods 的 Input 新增 rows,用于在终端中呈现多行文本框,其中 Enter 提交,Shift+Enter 或在 Enter 前输入反斜杠则换行;mod hook 的 .catch 处理器如今仅在 hook 抛出异常或超时时运行;$.env.set 在变量设置或取消设置后以 {} 解析,或以说明原因的 { deny } 解析;$.model.fork 在新进程的首个响应到来之前不再返回 nothing-to-fork;在 VS Code 以及桌面和移动应用中,绘制在问题对话框上方的树形视图可容纳 Markdown 内容,最多 48 行。请参阅 Mods 和 Vim 模式。275276

值得了解的修复。 退出时,若由 WorktreeCreate hook 创建的 worktree 可能含有未推送的提交,将不再未经询问就将其删除。Grep 和 Glob 在搜索程序失败时会报告错误,而不是显示“无匹配项”。参数名数量极多或极长的 skills 与命令不再卡顿数秒:只填入前 64 个名称,每个最多 64 个字符。Read 工具不再将 .xlsm、.parquet、.epub 和 .heic 等二进制文件当作文本读取。执行 /rewind 后,skills 会再次列给模型。在权限检查期间被轮次中途发送的消息打断的工具调用,不再向模型报告为被您拒绝。Vim 模式下按 Esc 不再丢弃已输入的 AskUserQuestion 答案:自由文本字段支持 NORMAL 模式,只有在该模式下按 Esc 才会取消。磁盘已满时,如今会产生指明该磁盘的错误,而不是误导性的“请运行 /login”提示。从 Slack 启动的自托管运行器在托管设置限制 MCP 服务器时也可以附加仓库(使用 deniedMcpServers 可继续禁用这些工具)。VS Code 会在回复中渲染 LaTeX 数学公式,包括 $$ 与 \[ ... \] 块,并在 Pro 和 Max 的用量限制横幅上显示“获取更多用量”链接。275

v2.1.300 新特性

Claude Code 2.1.300 于 2026年10月14日发布,距 2.1.299 仅数小时:npm 于 14:27 UTC 以 next 标签发布,GitHub 发布版于 18:24 UTC 跟进,所含 88 条要点与权威 CHANGELOG 完全一致;到当晚,npm 的 latest 与 next 均为 2.1.300,而 stable 则从 2.1.287 升至 2.1.292。没有任何版本被跳过。273

Advisor 工具登陆 AWS 上的 Claude Platform。 /advisor 现已可在 AWS 上的 Claude Platform 使用;在您通过 /advisor、advisorModel 或 --advisor 选定 advisor 之前,不会运行任何 advisor,而 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 可关闭该工具。截至 10 月 14 日,advisor 文档页面仍将 AWS 上的 Claude Platform 列在不受支持的提供商之中。该工具本身允许 Claude 在决策点咨询第二个模型,早于此版本便已存在,详见 Advisor 工具。273274

Mods 与遥测。 Mods 新增 virtualText 提示框装饰(绘制在提示框中、但永不进入草稿的文本)、用于在主视图中显示某个 agent 会话记录的 $.ui.view({ agentId })($.ui.view({}) 返回原视图)、Text 上用于从右到左行的 dir 属性,以及针对非键入编辑的提示框变化(调出的历史记录条目、清空、撤销、plugin 的填充)的 prompt.change hook;agent.spawn 如今可以改写工作流 agent 的 prompt 和 model,而不只是拒绝它,mods 参考文档也将 next.error.cause 上的 rewritten 原因标注为 v2.1.300 引入。OpenTelemetry 的 api_request 事件将缓存写入拆分为 cache_creation_5m_tokens 和 cache_creation_1h_tokens,追踪 span 携带 GenAI 语义约定属性,例如 gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name 和 error.type;被 mod 的 prompt.submit hook 改写或丢弃的提示,不再在 user_prompt 事件中记录为用户键入的内容。本地会话记录现在还会记录每次 API 请求的系统提示、工具和参数,因此您分享的会话记录可以精确复现一次请求(请参阅 Mods 和遥测)。273274

运维与行为变更。 发往 api.anthropic.com 的大型请求即使在遥测关闭时也会使用 gzip;CLAUDE_CODE_GZIP_REQUEST_BODIES=0 可将其关闭。来自 PreToolUse 和 PermissionRequest hooks 的 updatedInput 会像 Claude 自身的输入一样接受校验:未知键会被丢弃,被工具拒绝的输入则会导致调用被拒。退出时,在被要求停止后 1.5 秒仍在运行的后台命令会被强制终止。claude remote-control 移除了原本没有任何效果的 --sandbox 和 --no-sandbox 标志;传入其中任一都会报错退出,要对此类会话启用沙箱,应使用设置中的 sandbox.enabled。处于 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 下的会话会忽略设置中的 CA 证书包、工具代理、git TLS 以及 SSL_CERT_FILE 等 git 配置变量。在 Cowork 云会话中,PermissionRequest hook 的 setMode 会被忽略,其批准的其余部分照常生效。当 forceLoginGatewayUrl 指向一个由 Anthropic 运营、且服务于该会话主机名的网关时,Claude Desktop 的 Code 标签页会应用托管设置;而 claude gateway 遇到无法使用的 desktop: 策略键时会在启动时停止。/sandbox 的选项现显示为“Sandbox commands”。VS Code 新增 claudeCode.attachSelection,可让编辑器中的选中内容不随消息一起发送。在 Slack 中,经管理员允许后,Claude Tag 可以在 Slack Connect 频道中作答。273

值得了解的修复。 在后台命令仍在运行时退出,SessionEnd hooks 也会运行;ENABLE_TOOL_SEARCH=auto 不再在对话进行到一半时自行关闭;被 forceLoginOrgUUID 拒绝的登录不再留下该组织的令牌;无头会话与 SDK 会话在压缩后恢复时,会保留压缩所保存的消息及其摘要;当 API 拒绝某个 MCP 工具的输入 schema 时,对话不再每一轮都以 400 失败(改为不带参数发送该工具);agent hooks 会遵循其 model 设置;当标签或分支的名称形似提交 ID 时,--worktree 会话会从正确的提交启动,并且可以在 reftable 仓库中重新打开;claude daemon stop --any 会等待、强制终止卡住的服务,若服务仍然存在则以退出码 1 退出;Cowork 云会话中的 Write 和 Edit 不再对您本机上的路径报告成功;当无法读取组织策略时,云会话不再每轮挂起五分钟;自托管运行器在没有人读取其输出时也不再冻结。273

v2.1.299 新特性

Claude Code 2.1.299 于 2026年10月14日发布(npm 00:23 UTC;GitHub 发布版于 02:49 UTC 推出,所含 190 条要点与权威 CHANGELOG 完全一致)。2.1.297 和 2.1.298 从未发布,因此没有任何版本被跳过。npm latest 曾为 2.1.299,直到当天稍晚 2.1.300 被提升为最新版(请参阅 v2.1.300 新特性)。271273 从 2.1.296 升级:此版本修复了该版本引入的两个回归问题,一是在 Cowork 和 claude.ai 云会话中,若某条消息在其 UserPromptSubmit 或 mod prompt.submit hooks 运行期间被停止,Edit 和 Retry 会失败;二是云会话或无头会话在重启后恢复时,如果恰有新消息到达,已批准的工具调用会被执行两次。 空闲压缩(v2.1.299)。 一段 token 数达到 200K 及以上、闲置约 54 分钟的终端对话,现在会在其一小时的提示缓存过期前自动压缩,这样下一条消息就无需重新处理整个上下文。CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 可修改 200K 这一最低阈值(低于 100,000 的值会被提升至 100,000),在 settings.json 中设置 "idleCompaction": false 则可将其关闭;设置参考和环境变量页面均已列出这两项,并标注为 v2.1.290 或更高版本。CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 会让 @ 提及只把文件路径交给 Claude,由其用文件工具读取,而不是直接交出文件内容,因此您的 PreToolUse hooks 会在读取时运行;项目级和本地设置无法设置此项(请参阅环境变量参考)。271272 v2.1.302 在 /config 中新增了一行 空闲压缩,可用于关闭或重新开启该功能,空闲压缩后显示的提示也会说明操作方法。275

权限与 MCP。 诸如 mcp__a 这样的允许规则现在只匹配名为 a 的服务器,而不会匹配 a__b 或 a_;请使用服务器完整的规范化名称编写 mcp__<server>__*,名称中包含 __ 的服务器在 agent 的 tools: 列表中也要以同样方式列出,该列表现在只会引入该服务器的工具。规范化名称中含有双下划线的服务器,其拒绝规则和询问规则重新生效。来自 api.anthropic.com 上 Anthropic 第一方 MCP 服务器的工具描述和服务器指令现在会完整传递给 Claude,而不再在 4,096 个字符处被截断。云会话和 Remote Control 连接器在未获取任何功能标志的安装上默认协商 MCP 协议 2026-07-28 版本(MCP_PROTOCOL_NEGOTIATION=legacy 可选择退出);发往 claude.ai 连接器代理和 Anthropic 托管的 MCP 服务器的请求不再跟随 HTTP 重定向;MCP OAuth 现在会发送已配置的 headers 和 headersHelper 值;空的 .mcp.json 不再被报告为无效;名为 constructor 或 prototype 的服务器也能正常连接。沙盒中的命令不再能写入 --plugin-dir 文件夹,也无法通过符号链接访问被拒绝的路径;不运行 rm 的 shell -c 脚本不再触发 rm 提示;对于脚本内在运行时拼装出来、Claude Code 无法读取的 rm,只有在设置 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 时才会提示。271

Hooks 与 mods。 UserPromptSubmit hooks 现在在 skill 或自定义斜杠命令展开之前运行,因此拦截提示词的 hook 也会一并阻止其中嵌入的 shell 命令;而 skill 自身 front-matter 中的 UserPromptSubmit hook,最早只会在调用该 skill 的那条提示词之后的下一条提示词上运行。无法接收到动作、或无法返回其判定结果的插件 hook,现在会拒绝该动作而不是放行;对于已经运行过的工具,其结果会被扣留。对于 mods,turn.start hook 现在也能监听 subagents 和队友的回合(通过 e.agentId 加以区分);skill.prompt 会收到 skill 的 frontmatter、来源、插件名称和文件路径(mods 参考文档将这些标注为 v2.1.299);$.prompt.media 让托管设置 mod 的 prompt.submit hook 可以读取附带的图片或文档;$.session.identity() 报告会话的登录方式;Text 接受 size、weight、mono 和 tabular,Box 接受命名的间距档位(bold 已弃用,改用 weight);session.append 新增 queue 入口;agent.spawn 在恢复的 subagent 或队友上触发时会带上 resume 标记。被远程关闭的 mods 会在回合之间卸载;在由组织管理 Claude Code 的环境中,/plugin 和 claude plugin validate 会指出哪些 hooks 被跳过(请参阅 Mods)。271272

命令、界面与运维。 /usage 现在会就 max 努力级别、workflows、常驻上下文以及过大的工具结果给出警告。在 agent 视图中,/effort 和 /fast 可设定新会话的初始配置;不带参数的 /model、/effort 或 /fast 会打开选择器;对于以 --safe-mode 启动的会话,预览面板会显示一行安全模式说明。当 bypass permissions 可用、计划模式因此在大多数编辑前不再询问时,它会打印一次性的提示说明。claude plugin eval 接受 --disallow-tools 以及用例字段 disallowed_tools,以 API 错误结束的运行计 0 分并导致整个测试套件失败。claude self-hosted-runner orchestrator --shutdown-drain-sec 让进行中的轮询和 spawn hooks 在收到 SIGTERM 时有时间完成。在 Claude apps 网关之后,在 code 或 cli 策略的 env 中设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 可移除署名块。在 Cowork 云会话中,PermissionRequest hook 在自动模式下不再能批准 shell 命令或 subagents;在已批准的站点上,被安全分类器标记的 Claude in Chrome 操作会转为向您询问,而不是直接拒绝。退出时打印的恢复命令以 ID 指明会话;非交互式会话中的 /btw 会在 11 分钟后超时;本地会话可监视的已发布 artifacts 从 10 个增至 25 个;网络安全防护提示不再要求您申请 Cyber Verification Program。271

值得了解的修复。 通过自定义 ANTHROPIC_BASE_URL 的流式传输现在会等待数据 300 秒,而不是在 180 秒时中止;发往 Anthropic 的功能标志、启动、快速模式、配置文件和服务器托管设置请求不再携带第三方网关的 API 密钥;/usage 和状态栏不再显示超过 100% 的用量;在夏令时结束时重复的那一小时内,定时任务和 loops 不再在每个回合后重复触发;在 --debug 下或父进程停止读取 stderr 时,内存不再无限增长;重启后 SendMessage 能按名称找到 subagent;Read 可以处理带字节顺序标记的 UTF-16LE 文件,Write 则拒绝将 Windows-1252、Shift-JIS、GBK 或 UTF-16BE 文件静默转换为 UTF-8;在 Windows 上,未指定 shell 的 PreToolUse 和 PermissionRequest hooks 在缺少 Git for Windows 时会阻止调用,而不是失效放行。271

v2.1.293-v2.1.296 新特性

2026年10月7日至10月9日期间发布了四个版本。npm 的 latest 和 next 为 2.1.296;stable 从 2.1.285 升至 2.1.287。238 最重要的变化是新模型:Claude Haiku 5.5 随 v2.1.293 到来,成为 haiku 在 Anthropic API 上所选择的模型(请参阅可用模型)。如果您通过托管设置登录 Claude apps 网关,请升级到 v2.1.296:它修复了 v2.1.295 中的一个回归问题,即当 forceLoginMethod 为 gateway 且未设置 forceLoginGatewayUrl 时,已保存的网关登录会被忽略。

v2.1.296(10月9日)。 在 /cost、状态栏、--max-budget-usd 以及 SDK 的成本数据中,Sonnet 5.5 的缓存读取按每百万 token $0.10 计价,此前使用的是 $0.20。预先发送的 MCP 工具描述和 MCP 服务器指令的默认上限从 2,048 个字符提高到 4,096 个字符。Subagent 的 frontmatter 和 --agents 定义接受 autoCompactWindow,因此 subagent 可以比主对话更早地自动压缩。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 让每个 workflow agent 都在同一模型上运行,而其他 subagents 保留各自的模型;CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 可为 529 退避设置更长的最大延迟。Read 工具接受 allow_large,因此在上下文有余量时,Claude 可以一次调用就读取超出常规大小限制的文本文件。托管设置中以 "continue": false 拒绝工具调用的 PreToolUse hooks,以及拦截工具调用的托管 prompt hooks,现在除了拒绝调用外还会结束该回合。--debug 会指出自定义 agent 文件中无法识别的 frontmatter 字段,并记录每个命令 hook 的命令、插件、结果和耗时。Claude apps 网关在 managed.policies[] 下新增 code 键,其设置与 cli 相同,同时也应用于 Claude Desktop 的 Code 标签页。在按 ← 将会话移入后台时启动的回合或 ! 命令,现在会被停止,而不是在后台悄然完成。文档后来跟进了其中两项:hooks 参考文档将逐 hook 的 --debug 日志行标注为 v2.1.296,Claude apps 网关文档描述了 code 策略键;autoCompactWindow 和 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 已于10月14日进入 sub-agents 和环境变量文档;截至2026年10月14日,CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 仍仅出现在发布说明中。238240270272 v2.1.295(10月8日)。 命令 hooks 和 HTTP hooks 接受 onFailure: "block":无法启动、超时或以意外退出码结束的 hook 会阻止该操作,而不是放行(请参阅Hook 输入/输出协议)。CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 限定无人值守重试模式等待 429 和 529 错误恢复的最长时间。Subagents 最多从 skills 字段预加载 32 个 skills;通过工具搜索加载的 MCP 工具描述的截断上限由 2,048 个字符提高到 16,384 个字符。在没有托管设置的机器上,forceLoginMethod: "gateway" 和 forceLoginGatewayUrl 现在也可以在您自己的用户设置中生效,这样 /login 会直接在该网关上打开,网关文档现已介绍这种配置;每个网关上游都接受可选的 models 列表(* 为通配符),云上游则遵循 timeouts.upstream_ttfb_ms。实现了 Program Status Protocol(OSC 7501)的终端可以显示 Claude Code 正在工作、等待您的输入还是已经完成。经由 Claude apps 网关的后台请求在该网关提供 Haiku 4.5 时会改用它,而不是会话所用的模型。若网关、Bedrock、Vertex 或 Foundry 拒绝某个 [1m] 模型的 context-1m beta,请求会去掉该 beta 后重新发送,而不是直接失败。在已附加的后台会话的空闲提示符下按 Ctrl+C 不会影响待触发的 /loop 唤醒,因此连按两次会分离会话而循环继续运行;按 Esc 则会停止循环。在不获取功能标志的安装上,claude.ai 连接器默认协商 MCP 协议 2026-07-28 版本。/copy 提供引用文本,claude -p 会在最后一轮之后通过 stderr 说明它在等待什么,mods 则新增 $.ui.notify。在 xhigh 和 max 努力级别下,网页搜索和 agent hook 评估不再明显变慢。238240

v2.1.294(10月8日)。 针对以指令形式编写的 prompt 和 agent hooks 的两项修复:诸如“阻止那些……的命令”之类的 hook 不再放行本应阻止的内容;诸如“如果构建已损坏就继续”之类的 Stop 和 SubagentStop hooks 的判定方式也有所调整,使 Claude 更不容易提前停止。238

v2.1.293(10月7日)。 Claude Haiku 5.5(claude-haiku-5-5)成为 Anthropic API 上默认的 Haiku 模型:1M 上下文,每百万 token $0.10/$0.50,超过 100K 的提示为 $0.50/$2.50。subagentStatusLine 负载新增 agentType,状态栏脚本因此能够区分自定义 subagent 类型;mods 在 $.tool.register 上新增 isDeferred。两项回退:一是 v2.1.281 的自动模式拒绝消息,它曾告知 Claude 一次拒绝涵盖的是结果而不仅是那条确切命令;二是 v2.1.290 针对容器重启后丢失 /loop 唤醒的云会话修复,因此此类会话又会保持休眠。此外:Claude 不再把压缩前自己的最后几步操作当作压缩后已完成的事项;HTTP MCP 连接不再把发送过的每个请求一直保留到关闭;claude purge 会列出无法移除的内容并以退出码 1 结束,而不是悄然停止;在没有会话使用时,claude.ai skill 同步的检查间隔由 10 分钟改为 40 分钟;Team 和 Enterprise 启动时会更早获取策略和托管设置,并在请求停滞 3 秒后重试。238240

v2.1.288-v2.1.292 新增内容

2026年10月2日至10月6日期间发布了五个版本。npm 的 latest 和 next 为 2.1.292;stable 仍为 2.1.285。234 如果您正在使用 2.1.288、2.1.289 或 2.1.290,请升级:v2.1.291 修复了 2.1.288 引入的一个回归(退出时可能丢失会话的最后几条消息),以及 2.1.290 引入的另一个回归(云会话可能丢弃对权限提示的回答)。235

v2.1.292(10月6日)。 设置 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 可为重试过载(529)请求的退避给出更长的基础延迟;环境变量文档现已给出默认值 500 毫秒和可接受范围 500 到 32000。Agent 工具接受 effort 参数,Claude 因此可以按您指定的努力级别运行 sub-agent;subagents 文档现已记录这个按调用生效的参数,它会覆盖 frontmatter 字段,并在 subagent 恢复后继续生效,而 CLAUDE_CODE_EFFORT_LEVEL 的优先级高于两者。claude plugin install --marketplace <source> 用一条 shell 命令即可添加 marketplace 并从中安装。本地(stdio)MCP 服务器现在在所有安装上(包括 Bedrock、Vertex 和 Foundry)默认协商 2026-07-28 协议,可通过 MCP_PROTOCOL_NEGOTIATION=legacy 退出;MCP 文档现已说明 stdio 服务器默认会被请求使用该修订版本。代理名称上限为 256 个字符:超长的名称会被拒绝,skill 或 plugin 文件中超长的 name 会被忽略;subagents 文档现已注明 name 字段的这一上限,名称超长的 subagent 文件会被跳过,并在调试日志中写入一条错误。一项安全修复阻止 PreToolUse hook 批准和自动模式绕过从网络(UNC)路径读取文件时的提示。Mods 新增 prompt.autocomplete、$.model.complete 中的提示缓存以及 agent.spawn 中的工作流代理;claude plugin test 现在会在存根回答被拒绝时判定失败。截至2026年10月6日,其余条目仅见于发布说明。236237240

v2.1.290(10月5日)。 交互式 WebSearch 配额改为每小时补充 100 次调用(CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR;设为 0 可关闭),而不是在 200 次调用后用尽。claude attach 和 claude logs 接受会话名称的一部分。/claude-api managed-agents-onboard <url> 可将一篇介绍 Managed Agents 模式的页面转换为 ant apply 文件,/claude-api managed-agents-onboard <quickstart-name> 则使用 ant CLI 构建诸如 deep-researcher 之类的 Console 快速入门模板。多项默认设置收紧:项目设置不能再开启 Claude in Chrome,仓库的 .claude/settings.json 或 .claude/settings.local.json 不能再设置 CLAUDE_CODE_DISABLE_ATTACHMENTS,pyright 以及更多形式的 ps 在运行前会先询问,链接到托管设置文件夹之外的托管设置文件会触发警告。WebFetch 现在会说明页面中超过 100,000 个字符后有多少内容未读取,并接受 offset 参数以继续读取,此前它会悄然丢弃这部分文本。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 现在也会跳过启动时的连接预热,CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS=5m 不再被解读为 5 毫秒:带单位后缀的值会回退到 dialogExpiry 设置。235237

v2.1.290,团队与网关。 Claude apps 网关的登录批准页面新增 Deny 按钮,其支持的最低 PostgreSQL 版本由 14 降至 11。在自托管运行器上,claude --environment <id> 通过当前的 Sessions API 创建会话。如果某个文件夹取代了同名的受跟踪文件,而 stash 会删除该文件夹中的文件,claude --teleport 和 /teleport 会拒绝这样的 stash;--channels 中继会忽略重复的回复 ID,而不是批准另一个提示。在 Slack 中,!fast 将线程切换到快速模式,!fast off 则切换回来。VS Code 默认显示消息时间戳(可通过 Claude Code: Show Message Timestamps 设置关闭)。235

v2.1.289(10月3日)。 Mods 获得用于队友的 agent.spawn、跨 plugin hook 事件统一的代理 ID,以及 $.agent.list() 中的空闲和等待状态;claude plugin validate 不再跳过文件夹中同时含有 marketplace 清单的 plugin;沙箱自动允许下的两个 Bash 拒绝规则漏洞已被堵上。235237

v2.1.288(10月2日)。 claude project purge 现已改为 claude purge;旧名称仍然可用,但会打印一条提示。后台命令时间限制仅适用于无人值守会话(-p、Agent SDK、CI、云端)。/code-review --max-findings <n>|all 会更改发现项数量上限,直到您传入 --max-findings default 为止。/autocompact 按模型分别保存其窗口设置。CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS 可为 Mantle 或拒绝结构化输出的网关关闭结构化输出。按路径限定的规则和嵌套的 CLAUDE.md 文件在 Write 和 Edit 时也会加载,而不仅限于 Read。语言服务器会在 60 秒后超时(可按服务器设置 requestTimeout),而不是一直挂起。在自动模式下,对客户端分类器而言过长的对话会被压缩,而不是对每次工具调用都发出提示;客户端分类器会忽略指定 Claude Sonnet 5.5 或 Opus 5.5 的 ANTHROPIC_DEFAULT_SONNET_MODEL 固定设置,改用 Claude Sonnet 5。Mods 获得 $.ui.selection(),没有 GitHub CLI 的云会话获得内置的 gh api,在空提示符下按上方向键可恢复被 Ctrl+C 清除的草稿。234237

v2.1.105–v2.1.114 中的新命令146150

命令 版本 功能
/recap v2.1.108+ 恢复会话时返回先前上下文的摘要。可在 /config 中配置;禁用遥测时,CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1 可强制开启。
/ultrareview v2.1.111+(v2.1.113更新) 在云端运行的多智能体代码审查。不带参数时审查当前分支;传入<PR#>可拉取指定的GitHub PR。v2.1.113通过并行化检查加快了启动速度,在启动对话框中新增了diffstat,并显示动画形式的启动状态。Pro/Max订阅用户可获得3次免费云端审查。自v2.1.309起,claude ultrareview要求工作区信任:在终端中会先询问,否则直接拒绝;脚本可传入--trust-workspace(不带值;PR编号或基础分支须放在它前面),或设置CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1278279
/less-permission-prompts v2.1.111+ 扫描近期会话记录中经常被批准的只读Bash/MCP调用,并为.claude/settings.json提出一份按优先级排序的允许列表。
/tui / /tui fullscreen v2.1.110+(横幅于v2.1.132更新) 在对话过程中切换或进入无闪烁渲染模式。对应的tui设置可用于持久化偏好。v2.1.132更新了启动横幅,说明该渲染器内存占用更低、支持鼠标,并在选中时自动复制。159 自v2.1.260起,全屏模式还可以在对话旁边显示实时diff面板,以Claude编辑的形式呈现您尚未提交的更改,通过/diff切换(参见“斜杠命令”)。v2.1.260还让Ctrl+L / Cmd+K像终端的clear一样清空全屏会话记录视图;v2.1.280撤销了这一改动,这两个快捷键重新变为重绘屏幕而非清空会话记录,与全屏模式之外的行为一致。212220
/focus v2.1.110+ 进入专注模式。现已与Ctrl+O分离,后者仅在普通与详细会话记录之间切换。
/undo v2.1.108+ /rewind的别名。
/proactive v2.1.105+ /loop的别名。v2.1.113为“下一次触发”倒计时新增了按Esc取消的功能。
/effort(不带参数) v2.1.111+ 打开交互式推理强度滑块(方向键 + Enter)。也接受直接传参:/effort xhigh。
/extra-usage v2.1.113+(支持Remote Control客户端) 现在也可在Remote Control(移动端/网页端)客户端中使用,不再局限于本地终端。
### 会话回顾(v2.1.108+)
一项新的会话级功能:当您回到已暂停的会话时,它会把相关上下文呈现出来。默认启用,可通过/config或CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0退出。模型还可以通过Skill工具调用内置斜杠命令(/init、/review、/security-review),这是对subagent/skill模式的延伸。146

推送通知(v2.1.110+)

在Remote Control中启用“由Claude决定何时推送”后,Claude现在可以通过新的推送通知工具,自行判断并发送移动端推送通知。它与现有的Remote Control移动端/网页端界面配合使用。146 /context、/exit和/reload-plugins现在也可以在Remote Control客户端中使用。

Windows PowerShell工具(v2.1.111+,分阶段推出)

Claude Code正在分阶段推出原生的Windows PowerShell工具。在Linux/macOS上,可通过CLAUDE_CODE_USE_POWERSHELL_TOOL=1启用(要求PATH中有pwsh)。在Windows上,推出期间同一变量用于控制选择启用或退出。146

权限模式下的自动批准(v2.1.119+)。 PowerShell工具命令现在可以像Bash命令一样,在权限模式下获得自动批准。诸如PowerShell(Get-*:*)之类的允许规则以及现有的模式语法,现在对只读操作会跳过提示,与团队在Linux/macOS上已有的操作体验保持一致。152

减少权限提示:只读Bash(v2.1.111+)

带有glob参数的只读Bash模式(例如ls *.ts、cat src/*.md)以及以cd <project-dir> &&开头的命令,不再触发权限提示。146 再配合/less-permission-prompts,日常工作流中的打断会显著减少。

分布式追踪(v2.1.110+)

SDK和无头会话现在会从环境中读取TRACEPARENT和TRACESTATE,从而将Claude Code的运行纳入分布式追踪链路。搭配OTEL_LOG_RAW_API_BODIES=1(v2.1.111+)使用,可将完整的API请求/响应正文作为OpenTelemetry日志事件输出,便于调试。146

原生二进制分发(v2.1.113+)150

v2.1.113改变了CLI的启动方式:claude现在通过按平台划分的可选依赖启动原生Claude Code二进制文件,而不再运行打包的JavaScript。安装和更新命令保持不变,团队无需修改部署脚本。

提示编辑器快捷键(v2.1.113+)150

提示编辑器在多行输入中新增了readline风格的导航,并支持全屏视口滚动:

快捷键 效果
Shift+↑ / Shift+↓(全屏) 当选区扩展到可见边缘之外时滚动视口。
Ctrl+A 移动到当前逻辑行的行首(readline风格)。
Ctrl+E 移动到当前逻辑行的行尾(readline风格)。
Ctrl+Backspace(Windows) 删除前一个单词。
这些快捷键默认启用,无需配置键位绑定。

Subagent停滞超时(v2.1.113+)150

在流式传输中途停滞的subagents,现在会在10分钟后以明确的错误失败,而不是无声地挂起。搭配CLAUDE_STREAM_IDLE_TIMEOUT_MS(v2.1.84+)使用,可对流式API上的卡死进程提供更全面的覆盖。

v2.1.114稳定性修复150

v2.1.114(2026年4月18日)只包含一项修复:当agent teams中的队友请求工具权限时,权限对话框可能崩溃。如果您使用Agent Teams,请升级。

内容标记:文本水印与C2PA文件元数据(2026年8月)

Anthropic宣布为Claude生成的内容加入机器可读标记,其推动力是欧盟《人工智能法案》第50条(对新推出的AI系统自2026年8月2日起强制执行)。该系统包含两个组成部分:生成文本中不可见的统计水印,以及依据C2PA开放标准、附加在.svg、.png、.jpg等生成文件上的签名溯源元数据。252204 新闻标题模糊掉的细节是:两个组成部分遵循同一条模型时间线。 按支持页面的说法,“2026年8月2日及之后推出的Claude模型将在发布时即支持机器可读标记”;在该日期之前推出的模型,即当前的全部阵容(Fable 5、Opus 5、Sonnet 5、Haiku 4.5),则适用欧盟法律的过渡期,Anthropic“也在努力为这些模型添加标记支持”。204

这份名单截至8月。Fable 5.1(9月1日)、Opus 5.5(9月22日)和Sonnet 5.5(9月28日)在截止日期之后推出,因此按规则它们属于发布即标记的一方;Fable 5.1的发布说明在新增内容中列出了内容溯源,而Opus 5.5的模型页面和迁移指南,以及Sonnet 5.5的模型页面和新功能页面,均未提及标记。241222230 8月之前推出的模型,其输出不带任何标记,无论文本还是文件;较新模型的输出则会带有标记,并覆盖所有平台——Claude Platform(API)、claude.ai、Claude Code、Claude Cowork、Claude Tag以及各云端网关——因为标记是在模型层面实现的。有一个推论值得明说,因为某个疯传的帖子把它弄反了:您在8月之前的任何模型上感知到的风格或行为变化都不可能是水印所致,因为这些模型上的标记尚未生效。

工作原理:它是Google DeepMind的SynthID-Text的一个变体。当Claude在语义等价的选项之间做选择时,水印会改变“用于挑选词语的随机性来源”——不添加任何字符,不做后处理,并且根据Anthropic的内部测试,“水印对内容、创造力水平或可读性没有影响”。252

Claude Code用户会关心的一点是:代码只带有稀疏的水印。 能正常运行的代码几乎没有任意选择的余地,因此标记集中在存在自由度的地方——注释、命名——Anthropic称其“对实际生成的代码影响可以忽略不计”。252 持久性是概率性的,且因组成部分而异:对文本而言,轻度编辑“可能不会完全去除水印”,彻底重写则会去除,而由Claude生成的译文会带有自己的新标记;对文件元数据而言,格式转换、重新保存和截图都可能剥离C2PA签名。204 检测API已在计划之中;阳性结果证明“Claude很可能在某个时刻参与了该内容”,但明确无法区分“这是Claude写的”和“Claude对此做了大量编辑”——而且按支持页面的说法,没有标记同样证明不了什么。没有提到任何客户层级可以选择退出。252204

Claude Code的费用是多少?

要长期可持续地使用Claude Code,理解并控制成本至关重要。有关各模型的能力,请参阅模型选择;有关如何为每项任务选择合适的模型,请参阅决策框架。

查看费用

> /cost

输出:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

订阅用户可在/cost中看到按模型和缓存命中拆分的明细,清楚显示哪些模型消耗了token,以及有多少内容由缓存提供(v2.1.92+)。137

以合同价取代标价(modelPricing,托管设置,v2.1.243+):已协商好按模型费率或折扣倍数的组织,可以将其作为modelPricing托管设置进行部署;此后/cost、状态栏和遥测中的费用数字都会采用这些费率而非标价,开发者看到的数字便与组织实际支付的金额一致。250自v2.1.271起,该倍数也可以大于1(最高为10),以便向内部团队按加价费率收费的组织使用。216

按会话显示的提示缓存行(v2.1.251+):/cost新增一行会话级的提示缓存统计,包括命中率、未命中次数、重新缓存的token数,以及缓存处于热态还是冷态;同时为状态栏脚本提供对应的prompt_cache对象。该对象在主对话收到第一个API响应后出现,不统计子代理的请求,并且根据API响应中的缓存token计数计算得出,因此在所有提供商上均可使用。/usage在其Prompt cache (main)行显示同样的统计数据。206209自v2.1.260起,/cost中的这一行和状态栏的prompt_cache对象还会指出缓存未命中的可能原因,例如工具定义或系统提示发生了变化,或者会话闲置时间超过了缓存TTL。212

代理流量不再破坏自身的缓存前缀(v2.1.265):两项修复堵住了委派工作中的提示缓存泄漏。恢复由前台生成的子代理时,其工具列表和系统提示前缀不再发生变化;代理团队成员和恢复后的子代理在后续轮次中,也不再把SubagentStart hook上下文和预加载的skills移出提示前缀。这两个缺陷都会破坏提示缓存的复用——前缀一变,其后的所有内容都会作为未缓存输入重新发送——而且恰恰发生在缓存经济性最为关键的长时间代理会话中(与v2.1.260为Fable 5.1工具调用轮次修复的是同一类故障)。215

v2.1.267缓存稳定性批次修复:一个版本,约十项修复,针对的都是同一类故障——对话中途有东西重写了提示前缀,导致其后所有内容都作为未缓存输入重新发送。恢复的会话不再重写工具列表、重新渲染工具描述,也不再在连接器重连之前重写此前的MCP工具公告;用/model切换模型不再重新发送全部工具定义(提交和PR的署名文本现在以对话备注的形式送达,并随模型切换而更新);以--system-prompt或--append-system-prompt启动的子代理和会话只记录一次系统提示和工具定义;会话中途加入的MCP和插件工具,在没有ToolSearch的会话中以延迟定义的形式送达,而不是重写工具列表。这一批次将v2.1.260和v2.1.265的修复延伸到了恢复会话、切换模型和MCP重连的场景。216

v2.1.273延续了这一脉络:/login、/upgrade和/extra-usage此前会丢弃对话中早先的思考内容,迫使下一次请求完全重写提示缓存。217

v2.1.277又堵住三处前缀泄漏:在/clear之后续接的会话(重启、--continue、--resume),若SessionStart hook打印了输出,其第一条消息会缺失一部分,导致提示缓存完全未命中;恢复后的子代理和团队成员会重新渲染已加载的MCP工具定义,破坏了该代理的提示缓存;对话中早先记录的附件会在恢复或重新启动后被重新渲染,丢弃扩展思考并错过提示缓存。这与v2.1.265至267各批次属于同一类故障——有东西重写了前缀,其后所有内容都未经缓存重新发送——如今覆盖范围扩展到SessionStart输出、恢复代理的MCP定义和已记录的附件。219

v2.1.280再添两项:在Claude工作期间从宿主应用(Claude Desktop、VS Code、SDK)切换模型,不再导致下一个提示的缓存未命中;恢复后的fork子代理现在会重新发送其最初使用的工具列表,而不是重建一份,此前的重建行为一直在破坏该代理的提示缓存。220

v2.1.281再添三项:在权限提示待处理期间重启后恢复的会话,不再发送与之前不同的历史记录,此前这会从该点起破坏提示缓存;在对话中途断开、或在恢复后仍处于连接中的MCP服务器,在工具搜索关闭时(例如位于代理或网关之后)不再造成缓存损失;恢复后的会话不再以改变后的形式重新发送早先的轮次,此前这可能导致API丢弃对话之前的推理内容。224

订阅方案

方案 价格 用量 访问权限
免费版 $0 有限 无法使用Claude Code
Pro 每月$20 免费版的5倍 可使用Claude Code和Opus13
Max (5x) 每月$100 Pro的5倍 优先访问,性能增强
Max (20x) 每月$200 Pro的20倍 最高优先级,可购买额外用量
速率限制(2025年8月):Anthropic为付费订阅用户引入了每周速率限制。Max订阅用户可以按标准API费率购买超出限制的额外用量。14

速率限制翻倍(2026年5月6日):在旧金山举办的Code with Claude活动期间,Anthropic将Pro、Max、Team以及按席位计费的Enterprise方案的Claude Code五小时速率限制翻倍,取消了Pro和Max账户在高峰时段的额度缩减,并“大幅”提高了Claude Opus模型的API速率限制。算力保障来自与SpaceX的Colossus 1协议:“本月内新增超过300兆瓦的算力(超过220,000块NVIDIA GPU)。”157

自2026年9月14日起的每周限制(8月29日宣布):自5月提额以来一直实施的50%临时每周限额上调将于9月14日结束,取而代之的是针对Pro、Max、Team和按席位计费的Enterprise方案,在提额前基线之上永久上调25%。Anthropic自己对这一变化的计算是:“与今天相比,这相当于Claude Code的每周限额减少17%。”如果您今天的每周上限是150个单位,9月14日起将变为125。五小时限制不在此次公告范围内,5月的翻倍措施继续有效。如果您经常运行长时间的无人值守会话,不妨现在就为更低的上限做好准备:重置时自动继续的开关(v2.1.234)和/usage是两个关键的控制手段。213

API Token定价(2026年10月)1144222239

对于按API计费的用户,每百万token的价格如下:

模型 输入 输出 说明
Haiku 5.5 $0.10 $0.50 当前的Haiku,也是haiku在Anthropic API上所选用的模型(v2.1.293+);超过100K token的提示按$0.50/$2.50计费;1M上下文,128K输出,缓存读取$0.01(标准的输入价0.1倍)238239
Haiku 4.5 $1 $5 上一代Haiku;在Bedrock、Google Cloud的Agent Platform、Foundry以及AWS上的Claude Platform中,haiku仍选用此模型239
Sonnet 5.5 $2 $10 当前的Sonnet,也是sonnet在Anthropic API上所选用的模型(v2.1.284+);1M上下文,128K输出,缓存读取$0.10(输入价的0.05倍)228230239
Sonnet 5 $2 $10 上一代Sonnet(v2.1.197至283期间的sonnet别名);$2/$10最初是发布时的优惠价,原定9月1日的提价取消后便成为标准标价251
Sonnet 4.6 $3 $15 已被Sonnet 5取代
Opus 5.5 $4 $20 当前的Opus,也是Claude Code的默认模型(v2.1.280+);1M上下文,128K输出,思考始终开启,缓存读取$0.20(输入价的0.05倍)220222
Opus 5 $5 $25 上一代Opus(v2.1.219至278期间的默认模型);1M上下文,128K输出,思考默认开启197
Opus 4.8 $5 $25 旧版——此前的默认模型;快速模式于2026年10月30日弃用,2026年11月30日移除197284
Opus 4.7 $5 $25 旧版——2026年4月至5月的旗舰模型;已从快速模式中移除197
Opus 4.6 $5 $25 旧版Opus;1M上下文按标准价格计费(无溢价)
1M上下文定价(2026年4月):Opus 4.7、Opus 4.6、Sonnet 4.6和Mythos Preview均以标准每MTok费率提供1M上下文,不收取长上下文溢价。148这是近期的一次统一调整;此前关于Opus 4.6或Sonnet 4.6在输入超过200K token时需按2倍输入价、1.5倍输出价付费的说法已不再适用。旧版Opus 4.5及更早的模型仍保留其原有的定价结构。

数据驻留定价:通过inference_geo指定仅在美国进行推理时,所有token定价(包括缓存读取与写入)均需乘以1.1倍(适用于Opus 4.6及更高版本的模型)。148

提示缓存可大幅降低重复输入的成本:缓存写入的费用为基础价格的1.25倍(5分钟缓存)或2倍(1小时缓存),而缓存读取仅为0.1倍,可节省90%。还有两个例外的费率更低:Claude Opus 5.5的读取费率为0.05倍($0.20/MTok,节省95%);Claude Fable 5.1和Mythos 5.1的读取费率为0.025倍(Fable 5.1为$0.25/MTok,节省97.5%)。241222对于RAG系统以及上下文反复出现的代码助手而言,缓存可将成本降低88%到95%。

Batch API为夜间测试套件等非紧急任务提供50%的折扣,处理周期为24小时。

多账户政策52

可以拥有多个Claude账户吗?可以,只要用途正当。Anthropic明确允许出于不同目的持有多个账户。

允许的情形:

场景 示例 状态
家庭成员 您与配偶各自拥有Max账户 允许
工作+个人 个人账户+由雇主管理的工作账户 允许
个人+团队 个人Pro/Max账户与组织账户同时使用 允许
同一网络 同一家庭WiFi下的多个账户 允许
同一台电脑 在同一台机器上切换账户 允许
技术限制:
- 同一手机号最多可验证3个账户
- 明确支持来自同一IP/网络的多个付费订阅
- 各账户完全独立;账户之间无法转移聊天记录或项目

禁止的行为(依据使用政策): - 在被封禁后创建新账户以规避封禁 - 跨账户协同开展恶意活动以逃避检测 - 利用多个账户绕过速率限制或重复领取免费层级额度

真实案例:2026年1月,重度用户Jeffrey Emanuel(@doodlestein)的22个Max账户被自动标记并临时封禁。Anthropic员工Thariq(@trq212)在确认其使用正当后,于4小时内解决了问题。如果您在多个账户间大量使用Claude Code处理工作和个人项目,这正是该服务的设计初衷,但请不要试图钻系统的空子。

如有疑问:请联系Anthropic支持团队,以书面形式确认您的具体配置。

成本因素

因素 影响 优化方式
模型选择 Opus >> Sonnet >> Haiku 简单任务使用Haiku
输入token 上下文越多,成本越高 保持CLAUDE.md精简聚焦
输出token 回复越长,成本越高 设置MAX_OUTPUT_TOKENS
思考token 扩展思考会增加成本 仅在需要时使用
提示缓存 降低重复输入的成本 保持启用(默认)
### 实际成本示例
任务 模型 输入
------ ------- -------
快速文件搜索 Haiku 5.5 20K
修复bug并编写测试 Sonnet 5.5 100K
架构评审 Opus 5.5 150K
全天会话(Sonnet) Sonnet 5.5 500K
全天会话(混合使用,各占一半) Haiku 5.5+Sonnet 5.5 500K
以上成本按标价计算(每MTok:Haiku 5.5为$0.10/$0.50,适用于不超过100K token的提示;Sonnet 5.5为$2/$10;Opus 5.5为$4/$20),未计入提示缓存折扣。

省钱心得:与全部使用Sonnet相比,探索类subagents使用Haiku、实现工作使用Sonnet,通常可将成本降低40%到50%。

团队成本管理

按团队规模推荐的TPM/RPM:

团队规模 每用户TPM 每用户RPM
1-5 200k-300k 5-7
5-20 100k-150k 2.5-3.5
20-50 50k-75k 1.25-1.75
50-100 25k-35k 0.62-0.87
100+ 10k-20k 0.25-0.5
### 隐藏的工具费用
除按token计费外,部分工具还会产生额外费用:9
工具 费用 说明
代码执行 $0.05/会话小时 每个组织每月前1,550小时免费。请求中包含web_search或web_fetch工具时免费。33
网页搜索 $10/1,000次搜索 仍需支付token费用。失败的搜索不计费。
网页抓取 免费 除抓取内容的标准token费用外,不收取额外费用。1
Bash工具 每次调用+245个输入token 每次调用的额外开销
文本编辑器 每次调用约+700个输入token 典型开销
这些费用在agent循环中会不断累积。一个使用Bash的100次迭代调试周期,仅额外开销就要多消耗约24,500个输入token。

节省成本的策略

  1. 为subagents使用Haiku:大多数探索工作并不需要Sonnet
  2. 启用提示缓存:默认开启,但请确认未被禁用
  3. 设置最大轮次:claude --max-turns 5可防止对话失控
  4. 设置美元上限:claude --max-budget-usd 5会在花费达到上限时强制终止会话。自v2.1.217起,该上限同样适用于后台subagents:一旦达到上限,新的派生请求将被拒绝,正在运行的后台agent也会被叫停(此前后台agent不受此预算约束)194
  5. 探索时使用计划模式:不执行操作,就不会意外产生高昂费用
  6. 主动压缩上下文:上下文越小,token越少
  7. 限制输出:export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
  8. 非紧急工作使用Batch API:输入和输出token均享5折
  9. 分析项目的Claude API支出:/claude-api cost-optimize(v2.1.247+)可分析现有项目的Claude API支出,并逐一调整各项成本杠杆(缓存、token用量管理、批处理、effort、模型选择),每次只做一项可衡量的改动。它针对的是您用API构建的应用,而非Claude Code会话本身245

监控用量

  • Claude控制台:platform.claude.com(需要Admin或Billing角色)
  • 工作区限制:为每个工作区设置支出上限
  • Bedrock/Vertex:使用云平台原生的成本监控
  • LiteLLM:适用于在第三方提供商下进行精细的按用户追踪

后台token消耗

部分操作会在后台消耗token: - 供/resume使用的对话摘要 - /cost和/status命令 - 自动压缩

每次会话通常低于$0.04。

Claude Code Analytics API(Team/Enterprise)46

通过Admin API以编程方式获取您所在组织的Claude Code使用分析数据和生产力指标。

端点:GET /v1/organizations/usage_report/claude_code

要求: - Admin API密钥(sk-ant-admin...) - Team或Enterprise套餐 - Admin、Billing或Developer角色

可用指标:

指标 说明
num_sessions 发起的Claude Code独立会话数
lines_of_code.added/removed 新增/删除的代码总行数
commits_by_claude_code 创建的git提交数
pull_requests_by_claude_code 创建的PR数
terminal_type 运行环境(vscode、iTerm.app、tmux等)
customer_type api(API客户)或subscription(Pro/Team)
请求示例:
curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

使用场景: - 开发者生产力分析(会话、提交、PR) - 工具使用指标(Edit、Write等工具的接受/拒绝率) - 跨团队的成本追踪与分摊 - 为AI编码工具的ROI提供论证依据

注意:数据会在活动完成后1小时内出现。为保持一致性,响应中仅包含1小时之前的数据。

决策框架

仅仅知道有哪些功能还不够,还需要知道何时该用哪一个。这些决策树将知识转化为行动。

应该使用哪个模型?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 5.5 (medium effort default; /effort high or xhigh for harder)
                  │         Cost: ~$1.60/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.50/task
                           Balance: Best overall when cost matters

经验法则:自 v2.1.280 起,默认模型不再随您的订阅计划而变,每个会话都以 Opus 5.5 启动(Microsoft Foundry 除外)。因此,过去“升级到 Opus”的操作如今正好反过来:当任务不需要深度推理时,用 /model sonnet 降档,token 价格即可减半。181197207220221 Subagents 则可降至 Haiku。若降档后的回答显得浅薄,就继续留在 Opus 上。借助代理团队(v2.1.32+),Opus 可以协调多个代理并行处理不同的子任务。79

命令、Skill、Subagent 还是代理团队?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook 还是提示词?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

何时使用扩展思考?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

会话期间可用 Alt+T 切换。思考预算越高,成本越高;建议从最低档起步,仅当回答显得仓促时再逐步提高。

Opus 4.6 自适应思考:Opus 4.6 会根据问题的复杂程度自动调整思考深度。对于大多数任务,无需显式控制思考预算——遇到难题时 Opus 会自动加深思考,简单问题则保持快速响应。手动切换思考模式在使用 Sonnet 时最为有用,适合需要强制进行更深入分析的场景。

选择哪种执行界面?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools
场景 界面 原因
调试失败的测试 主 REPL 需要本地文件,需反复迭代
分拣处理 20 个 GitHub issue 后台代理 运行时间长,无需本地文件
审查 PR Subagent 或 --from-pr 上下文隔离,输出聚焦
生成变更日志 claude -p 一次性执行,可脚本化
每次提交时运行 lint 和测试 Hook(针对 git commit 的 PreToolUse)或 git pre-commit hook 必须每次执行,确定性强
跨仓库搜索某个模式 Subagent(Explore) 避免上下文膨胀
向预发布环境应用迁移 后台代理 需要远程访问
快速解释代码 主 REPL 或 /fast 交互式,需要快速响应
多模块重构 代理团队 跨文件并行工作

代理团队、Subagents 还是并行会话

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL
方式 最大并行度 共享上下文 协调方式 成本
代理团队 5-10 个代理 共享仓库,上下文各自独立 由 Opus 编排 高(N 个代理)
Subagents 默认 20 个并发(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) 无(相互隔离) 由您通过提示词编排 每个代理中等
并行会话 受终端数量限制 无 手动 每个会话中等

选择哪种 Hook 类型?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

何时使用 /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast   (Opus 5.5 or Opus 5; Opus 4.8 until Nov 30, 2026)
│         Same model, ~2.5× output speed at 2× price
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast 用于切换当前会话的快速模式。它沿用同一模型——Opus 5.5(自 v2.1.280 起的快速模式默认模型)、Opus 5,或在2026年11月30日之前的 Opus 4.8——只是优化了输出速度。它不会切换到更便宜的模型,而且按 Opus 5.5 每百万 token $8/$40(Opus 5 和 4.8 为 $10/$50)的价格计算,也并不更便宜。196198223 Opus 4.8 上的快速模式已于2026年10月30日弃用,并将于11月30日移除(v2.1.316)。284


权限系统如何运作?

Claude Code 的权限系统可对允许执行的操作进行细粒度控制。理解这一系统,对安全性和工作流效率都至关重要。如需了解在整个组织范围内强制执行权限的托管设置,另请参阅企业部署。

权限层级

只读工具(自动批准): - Read - 读取文件内容 - Glob - 按模式查找文件 - Grep - 搜索文件内容 - WebSearch - 搜索网络 - LSP - 代码智能(跳转到定义、查找引用、悬停文档)18

LSP 工具功能(v2.0.74+): LSP 工具提供类似 IDE 的代码智能: - 跳转到定义:跳转到符号的定义位置 - 查找引用:列出符号在整个代码库中的所有用法 - 悬停文档:获取任意符号的类型信息和文档 - 支持 TypeScript、Python、Go、Rust 以及其他支持 LSP 的语言 - 需要可用的语言服务器(通常随工具链一同安装)

修改类工具(需要批准): - Edit - 修改现有文件 - Write - 创建新文件 - Bash - 执行 shell 命令 - WebFetch - 获取 URL 内容 - NotebookEdit - 修改 Jupyter notebook

修改类工具首次运行时,Claude Code 会请求批准。除非另有明确配置,批准在整个会话期间持续有效。

EndConversation 工具(v2.1.214)。 Claude Code 现已具备 Claude 自 2025 年起在 claude.ai 上拥有的结束对话能力:在极少数出现严重辱骂性输入或持续越狱尝试的情况下,Claude 可以通过内置的 EndConversation 工具直接结束会话。这是一项抗滥用与模型福祉措施,而非工作流功能——正常的开发会话不会触发它。190193

权限模式

模式 行为 使用场景
default / manual — 自 v2.1.200 起标注为 “Manual” 每个工具首次使用时提示 手动批准;是 claude -p 和 Agent SDK 的起始模式(自 v2.1.302 起再次全面适用;见下文),也是自动模式成为默认之前交互式会话的起始模式227229275
acceptEdits 自动批准文件编辑,bash 命令仍需提示 受信任的项目
auto 由分类器逐一审查每个操作的安全性 自 v2.1.283-284 起,成为所有套餐和提供商下交互式终端及 VS Code 会话的内置起始模式(Pro/Max/Team 自 2026年8月14日起);此外仅在 v2.1.285 至 v2.1.301 期间,也是第三方提供商或关闭遥测时 claude -p 和 Python Agent SDK 会话的起始模式203226228229275(v2.1.85+)
plan 不允许执行或编辑 仅分析
bypassPermissions 跳过所有提示 CI/CD 自动化
自 v2.1.200 起,default 模式标注为 “Manual”。 此次更名覆盖 CLI、--help、VS Code 和 JetBrains;配置值并未改变,因此 "defaultMode": "default" 依然有效,同时 --permission-mode manual / "defaultMode": "manual" 现已作为别名被接受。行为完全相同——每个工具首次使用时提示——只是标签不再让人误以为是”碰巧默认得到的模式”,而如实体现其手动批准的本质。同一版本中,AskUserQuestion 对话框默认不再自动继续;提出问题的 subagent 现在会等待您的回答,而不是在超时后自行继续。如需恢复空闲超时,可通过 /config 重新启用。

v2.1.302 将 claude -p 和 SDK 改回 Manual。 未配置权限模式的 claude -p 或 Agent SDK 会话,在第三方提供商、关闭遥测以及全新安装这三种情况下——即 v2.1.285 曾以自动模式启动的情形——现在均以 default 启动;--permission-mode auto 仍保持自动模式,permissions.defaultMode 也依然生效。交互式终端和 VS Code 会话仍以自动模式作为起始模式。10月17日获取的权限模式文档对于不获取功能标志的会话仍沿用 v2.1.285 的规则,因此在采信该表格之前,请先核对版本说明。275276

v2.1.285 扩展至非交互式会话。 在第三方提供商或关闭遥测的情况下,未配置权限模式的 claude -p 和 Python Agent SDK 会话现在以自动模式启动,”与交互式会话一致”;--permission-mode 仍可覆盖此行为。当您的用户设置默认采用其他模式时,将自动模式设为默认权限模式的一次性提示,现在也会在第三方提供商和关闭遥测时显示。10月1日获取的权限模式文档现已与之一致:在 v2.1.285 或更高版本中,不获取功能标志的 -p 或 Agent SDK 会话(例如使用第三方提供商或关闭遥测时)以 auto 启动;获取功能标志的会话则以 default(Manual)启动,组织策略不提供 auto 默认值时的会话亦然。229233

v2.1.283 和 v2.1.284 将交互式默认值扩展至所有套餐和提供商。 自动模式现已成为 Enterprise、Claude API 以及第三方提供商上交互式终端和 VS Code 会话的内置起始模式。如需保留 Manual,请在 ~/.claude/settings.json、项目的 .claude/settings.json 或托管设置中将 permissions.defaultMode 设为 "default";项目设置文件中的 "auto" 值不会生效。226227 v2.1.283 的发布说明提及第三方提供商和关闭遥测的会话;v2.1.284 的说明则称该默认值适用于”所有套餐和提供商”;权限模式文档将该默认值的起始版本记为 v2.1.283。227228 同样在 v2.1.284 中,自动模式在读取工作目录以外内容前的提示新增了 Yes, but ask again next time 选项,可允许本次读取,后续读取仍会继续询问。228

2026年8月14日,自动模式成为 Pro、Max 和 Team 的开箱即用默认模式——该变更于8月7日宣布,并在切换当日于官方权限模式文档中确认上线。文档当前的措辞补充了两个值得了解的范围细节:默认值适用于新会话;并且”您自行设置的默认值保持不变,除非您接受一次性切换提示;由组织管理的默认值也不受影响。”这些套餐上的新会话以自动模式启动,该模式”将每个工具调用交由分类器处理,专门拦截不可逆、具有破坏性或指向您环境之外的操作。”Anthropic 给出的切换理由是:在一项有 1,053 名测试者参与的研究中,自动模式拦截了 89% 的危险命令,而人工审查仅为 13.6%——况且用户本就会批准 97% 的权限提示,这正是手动审查在实践中形同虚设的原因。分类器的 token 开销在 Pro/Max/Team 上不再计费(自宣布之日起生效)。切换回去只需按一次 Shift+Tab(或使用桌面端的模式下拉菜单);如需固定其他默认值,可在设置中配置 defaultMode;组织管理员可通过 disableAutoMode 托管设置完全禁用自动模式。切换时,Enterprise、Claude API、AWS 上的 Claude Platform、Bedrock、Google Cloud 的 Agent Platform 以及 Foundry 仍需手动启用,Anthropic 计划”在未来一个月内”将默认值扩展至这些平台。203 关于自动模式不承诺的内容——以及促使 Anthropic 作出此说明的研究人员所演示的绕过手法——请参阅 Max 上的自动模式。

即使在 acceptEdits 下,代码执行类配置文件现在也会触发提示(v2.1.160)。 acceptEdits 会自动批准普通编辑,但自 v2.1.160 起,在写入可能导致静默执行命令的文件之前,它会停下来请求确认:包括 shell 启动文件(.zshenv、.zlogin、.bash_login)、~/.config/git/,以及构建工具配置(.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/ 等)。原因在于,对这些文件的任何编辑都会把下一次 shell 启动、安装或提交变成执行载体——因此,即便是在其他编辑一律放行的受信任项目模式下,它们也需要经过专门的关卡。这与现有针对 .claude/、.git/ 和 .vscode/ 的写入保护采用同一威胁模型,只是扩展到了更广泛的”编辑即执行”类文件。265

自动模式(v2.1.85+): --dangerously-skip-permissions 的更安全替代方案。一个独立的分类器模型——自 v2.1.210 起为 Claude Sonnet 5(最初为 Sonnet 4.6)——会在执行前审查每个操作,检查其是否符合用户意图且安全。124187

工作原理: - 只读操作和工作目录内的文件编辑自动批准 - 自定义的允许/拒绝规则优先判定 - 其余操作交由分类器评估 - 若被拦截,Claude 会自动尝试其他方案

默认自动拦截:curl | bash、强制推送到 main、生产环境部署/迁移、大规模云资源删除、IAM/权限变更、向外部发送敏感数据。125 熔断机制:单个会话中连续 3 次拦截或累计 20 次拦截,即会暂停并退回手动确认。125

# Enable at startup
claude --permission-mode auto

# Or cycle into it during a session
Shift+Tab  # Cycles through: Manual (aka default) → acceptEdits → auto → plan

Auto mode 不再需要手动启用(v2.1.152),在 Bedrock/Vertex/Foundry 上无需环境变量标志即可使用(v2.1.207),自 2026年8月14日起成为 Pro/Max/Team 的开箱默认模式,并自 v2.1.283-284 起成为所有套餐和提供商下交互式会话的内置起始模式。267185203226228

YOLO Mode(v2.0.68+): 如需在没有任何安全分类器的情况下完全自主运行,请使用 --dangerously-skip-permissions 标志。该标志会对一切操作放行:文件编辑、bash 命令以及所有工具调用。“dangerous”一词是有意为之。对于大多数使用场景,推荐改用 Auto Mode。54

claude --dangerously-skip-permissions

通过 CLI 设置模式:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

在会话中切换:

Shift+Tab  # Cycles through modes

在 settings.json 中:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

defaultMode 的作用域限制(v2.1.257): 项目的 .claude/settings.json 或 .claude/settings.local.json 不能再设置 defaultMode: "bypassPermissions"——该值在这些文件中会被忽略,与此前 "auto" 的处理方式一致。文档现已明确这一规则:permissions.defaultMode 的 auto 和 bypassPermissions 两个值“不会在项目或本地设置中生效”——应在用户设置或托管设置中配置,或通过 --permission-mode 按会话设置。因此,克隆下来的仓库无法附带一个让会话以绕过权限状态启动的设置文件。(上例使用的是 acceptEdits,任何作用域均可设置;本指南此前也从未记录早已存在的 auto 限制——两者现已一并载明。)211243

权限规则语法

细粒度规则用于控制特定操作。规则按顺序评估:首个匹配项生效。

Bash 命令模式:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

星号提供前缀匹配:Bash(npm run test:*) 允许 npm run test、npm run test:unit 和 npm run test:integration。

重要限制: Bash 模式仅匹配前缀,不支持正则表达式。像 Bash(curl http:*) 这样的模式无法匹配 curl -X GET http://...,因为选项位于 URL 之前。若要可靠地拦截,请直接拒绝整个命令:Bash(curl:*)。

将 * 放在子命令之后。 Claude Code 会按原样匹配第一个 * 之前的所有内容,因此真正限定规则范围的是这些词:Bash(git log *) 仅允许 git log 命令,而在 Bash(git * main) 中,* 代替的是子命令及其之前的所有选项。其中包括 -c,它会让 git 运行您指定的程序,因此 Bash(git * main) 也会放行 git -c core.fsmonitor=<script> diff main。自 v2.1.246 起,只要允许规则在子命令之前带有通配符,无论它位于设置文件、托管设置,还是 --allowedTools/--settings 的取值中,Claude Code 都会在启动时发出警告;修复方法是写出您真正想要的确切值,用 Bash(git checkout main) 取代 Bash(git * main)。249247

文件拒绝规则可穿透重定向;参数层面的扩展上线后不到一天即被回滚(v2.1.257-260)。 作用于 Bash 命令的 Read(...) 和 Edit(...) 拒绝规则覆盖输入重定向(< file)以及 tac、egrep 等读取类命令(v2.1.257)——这正是 v2.1.233 回滚 v2.1.232 的输入重定向检查时所承诺的收窄版本;这部分保持有效。v2.1.259 将同样的覆盖范围扩展到隐藏在选项值和操作数中的文件路径(--ignore-revs-file=.env、-f.env、@file 参数、git diff 和 git grep 的操作数、cd DIR && cat FILE 复合命令;对包含被拒绝文件的目录执行 grep -r/cp -r 时会先询问),而 v2.1.260 次日便回滚了这一扩展:它在所有模式下都因 Read(./**/build/**) 规则而拒绝了 npm run build,并让 cd ... && grep 即使在 auto mode 下也会弹出确认。这是参数级覆盖的第三次尝试——v2.1.232 上线,v2.1.233 回滚,v2.1.257 落地了保留至今的重定向与读取命令子集,v2.1.259 扩展到参数,v2.1.260 回滚该扩展——因此自 v2.1.260 起,拒绝规则能捕获重定向和读取类命令,但无法捕获隐藏在任意命令参数中的路径;这一状态由 v2.1.260 确立并沿用至今,此后的改动只是针对特定绕过方式的单点修复,而非第四次尝试(见下一段)。211212

回滚后的单点修复,以及第二次小范围回滚(v2.1.268-273)。 对参数扩展的回滚依然有效;以下改动封堵的是特定的绕过方式——其中一项本身也被撤回。v2.1.268: 针对符号链接系统目录(macOS 上的 /etc、/tmp、/var;Linux 上的 /bin)的拒绝和询问规则,现在在路径以真实位置书写时同样生效;Bash 命令也不再忽略以符号链接写法编写的拒绝规则——两者均保持有效。同一版本还让同一行中权限检查器无法分析的 env -C、eval 或类似命令不再能绕过 Read 或 Edit 拒绝规则——而 v2.1.273 恰好回滚了这项检查:“time -p make build 之类的命令重新改为弹出确认,而非直接拒绝。”v2.1.269: Edit() 拒绝规则和写入路径检查现在覆盖 Bash tee 命令写入的文件;Bash(tee:*) 允许规则不再覆盖工作目录之外的目标;以 ! 开头的拒绝或询问规则仅在编写它的设置来源内生效(单独的 ! 否定会被忽略)。v2.1.271 修复的是检查器本身:fmt、column 等命令读取的文件,即使位于检查器无法识别的选项之后也会被检查;当通配符位于模式或选项值中时(例如 grep -v dir/* file),通配符展开得到的文件会被检查;shell 变量声明标志不再能伪装实际运行的命令;在 bypass 和 auto mode 下,包含两次目录切换、子 shell 或 cd+git 链的命令,不再能跳过 permissions.blockReadsOutsideWorkingDirectories 下的确认。v2.1.273 在回滚的同时附带三项单点修复:在 permissions.blockReadsOutsideWorkingDirectories 下,无法分析的 Bash 命令不再跳过确认;在 bypass 模式下,隐藏危险 rm 的子 shell 不再跳过确认;在该设置下,由仓库设置指定的记忆目录不再被加载、召回或建立索引。对于检查器无法分析的 Bash 命令行,最终规则简单来说就是:拒绝规则会改为弹出确认而非直接拒绝,blockReadsOutsideWorkingDirectories 会弹出确认而非跳过。216217

写入按实际落点判断,而非按书写形式(v2.1.280)。 上文 v2.1.268 的修复覆盖的是经由符号链接系统目录的读取。这一项封堵的是写入一侧,也是影响更大的一半:经由符号链接路径的写入此前是按其项目内的写法来判断的,因此看似本地的路径,实际可能写到链接所指向的任何位置。原文如下:“修复了经由符号链接路径的写入按其项目内写法判断的问题:确认提示会标明写入的实际落点,acceptEdits、允许规则和 auto mode 不再批准落在项目之外的写入。”有三点后果值得牢记,因为这三者都是悄无声息的失效,您此前很可能毫无察觉:

  • acceptEdits 的暴露面最大。 acceptEdits 的全部前提是“本项目内的编辑都没问题”。而项目树中只要有一个符号链接,一次看似已获批准的编辑就可能写到项目之外,且不会弹出任何确认,因为规则匹配的是写法而非目标。
  • Edit(src/**) 式的允许规则不再穿透链接生效。 规则现在必须匹配字节实际写入的位置,因此 src/vendor -> /etc 这类链接再也无法为路径“洗白”。
  • 确认提示的文字变了,这正是需要细读的部分。 当写入确实触发确认时,提示中现在显示的是实际落点路径。如果提示显示的目标与 Claude 输入的路径不符、出乎您的意料,那是符号链接在如实相告,而非渲染错误。

如今,读取和写入遵循一致的通用规则:权限检查器会先解析路径,再做判断。 如果您一直依赖针对符号链接写法编写的拒绝规则,或某条被链接悄然放宽的允许规则,请对照真实目标重新审视这两者。220 Shell 写入同样受限(v2.1.287)。 如果 shell 写入经由已提交到仓库的符号链接,最终落在敏感文件上或工作树之外,现在会注明实际写入位置并等待人工确认,目标为 ~ 的命令行也不例外。对于 Claude Code 的文件工具会直接拒绝的文件(例如 Anthropic 配置文件存储和主机凭据文件),整工具级 Bash 允许规则和放行型 hooks 现在会先弹出提示,而不是直接执行 shell 写入。同一版本还修复了一个问题:危险的 rm(例如作用于 / 或主目录的命令)在同时将输出重定向到 ~ 或通配符路径时,会失去其“始终询问”的保护。232

更多提示,更少放行(v2.1.288-292)。 这几个版本将多条命令从“直接运行”改为“先询问”:

  • v2.1.288: 在 bypassPermissions 模式下或 shell 允许规则之下,bash -c 或 sh -c 脚本中的危险 rm(例如作用于 / 或主目录的命令)不再无提示运行。PreToolUse 和 PermissionRequest hooks 匹配失败时,或工具输入无法序列化为 JSON 时,现在会阻止该调用,而不是跳过 hooks。234
  • v2.1.290: pyright 不再被视为只读命令,会先询问;更多形式的 ps 会询问;rg 或 git grep 等只读命令,若其参数仍会被 shell 作为通配符展开,也会弹出提示;此外,PreToolUse hook 改写工具调用的输入后,权限规则和安全检查现在会作用于改写后的调用。235
  • v2.1.292(安全修复): PreToolUse hook 的批准和自动模式曾可绕过对网络(UNC)路径文件读取的权限提示,此问题已修复。236

文件操作模式:

{
  "allow": [
    "Edit(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

路径语法: - 相对路径:Edit(src/**) - 相对于工作目录 - 相对于设置文件的绝对路径:Edit(/build/**) - 相对于设置文件所在位置 - 真正的绝对路径:Edit(//tmp/**) - 以 // 开头 - 主目录:Read(~/.zshrc)

单段 dir/** 允许规则现在只匹配 <cwd>/dir(v2.1.214)——请审查现有规则。 在 v2.1.214 之前,Edit(src/**) 这样的允许规则会自动批准对目录树中任意名为 src 的目录的写入——vendor/src/、packages/foo/src/ 等一概放行。现在它只匹配工作目录正下方的 src 目录。如果您依赖旧的任意深度匹配行为,请将规则改写为 Edit(**/src/**)。deny 和 ask 规则仍保持任意深度匹配——此项变更只收窄自动批准的范围,绝不收窄拦截的范围。升级后,悄然失效的规则不会报错,而是表现为新出现的权限提示,因此请检查所有以单段形式编写的允许规则。同一版本中,hook 的 if: 条件也获得了相同的 cwd 作用域限定(参见匹配器)。190

使用 Edit(path)/Read(path),而非 Write(path)/NotebookEdit(path)/Glob(path)(v2.1.210)。 对于针对 Write(path)、NotebookEdit(path) 或 Glob(path) 编写的权限规则,Claude Code 现在会在启动时显示警告。规范形式是真正控制文件访问的两类规则:Edit(path) 涵盖所有写文件工具(包括 Write 和 NotebookEdit),Read(path) 涵盖读文件工具(包括 Glob)。建议迁移所有旧规则,既可消除警告,也能让意图保持明确。187

“始终允许”保存在仓库根目录(v2.1.211)。 通过“始终允许”提示选项创建的权限规则,现在写入仓库根目录而非当前工作树。因此,在一个工作树中授予的批准会跨会话持久保留,并适用于该仓库的所有工作树——无需在每个并行检出中重复批准同一命令。188

含括号的路径和格式错误的模式均可安全失败(v2.1.260)。 此版本对文件权限规则做了三项解析修复,其中第一项为安全修复。路径中含括号的 Edit/Write/Read 规则——例如 Next.js 路由组 Edit(src/app/(admin)/**)——此前会被当作无效规则丢弃,或被 Bash 沙箱忽略,导致管理员以为只读的文件夹实际可写;现在这些规则会正常生效。含有无法编译的模式(例如未闭合的 [)的文件拒绝规则,此前会让所有文件编辑都以 Invalid regular expression 失败;现在此类规则会保护其字面所写的路径。此外,对于 Edit(C:\dir\(name)\**) 这类规则(其中 \( 会被解读为转义括号而非路径分隔符),设置错误信息现在会建议一种无歧义的写法。同一版本也不再静默忽略右括号之后带有文本的规则(Bash(ls) x 从来不会匹配任何内容),而是将其报告为无效设置。212

MCP 工具模式:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

使用通配符语法 mcp__server__* 可以允许或拒绝某个 MCP 服务器的全部工具。32 通配符语法便于快速启用受信任服务器的所有工具,或整体屏蔽来源不可信的服务器。

服务器名称须完整匹配(v2.1.299)。 诸如 mcp__a 的允许规则只作用于名为 a 的服务器,不再同时放行名为 a__b 或 a_ 的服务器。请使用服务器完整的规范化名称编写 mcp__<server>__*。子代理的 tools: 列表同样适用此规则;对于规范化名称中含双下划线的服务器,拒绝和询问规则现在也会生效。权限文档早已要求允许规则中的通配模式必须带有字面、不含通配符的 mcp__<server>__ 前缀。271272

自 v2.1.166 起,拒绝规则在工具名称位置也接受通配模式:在工具名称位置使用单独的 "*" 即可拒绝所有工具,从而先全部屏蔽,再放行一小部分。相比之下,允许规则不接受非 MCP 的通配模式——无法以同样的方式一键全部放行,从而使默认姿态保持严格。263

参数级匹配——Tool(param:value)(v2.1.178):

除工具名称外,规则还可以匹配工具的输入参数,并以 * 作为值的通配符:

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus) 会阻止任何基于 Opus 层级启动的子代理——被拒绝的是启动本身,而不仅仅是要求提示词避免这样做。这将权限控制从“使用哪个工具”细化到“如何调用”,并以确定性规则而非提示词层面的请求来实现。它与托管设置 enforceAvailableModels 相辅相成:允许列表定义会话中存在哪些模型层级,Tool(model:...) 规则则约束子代理如何从中选用。173

自 v2.1.186 起,这些 Agent(...) 规则也会对具名子代理启动强制执行:启动特定具名代理时(通过工作流、--agents 或代理团队),Agent(agent_type) 拒绝规则和 Agent(x,y) 允许类型限制同样适用,而不仅限于匿名的 Task 式启动。启动会在发起时即被阻止,从而堵上了具名代理绕过本应约束它的规则这一漏洞。175

WebFetch 模式:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

自 v2.1.268 起,普通的 WebFetch 拒绝和询问规则不再作用于 Artifact 工具的读取和更新——如需阻止或管控这些操作,请编写 Artifact 规则,或使用 WebFetch(domain:claude.ai)。216

如需在自己的会话中关闭 artifacts,可以设置 "enableArtifact": false(/config 中的 Artifacts 一行会将其写入用户设置;已弃用的 "disableArtifact": true 仍然有效),导出 CLAUDE_CODE_DISABLE_ARTIFACT=1,或将 Artifact 添加到 permissions.deny。一旦 --settings 文件、该环境变量或托管设置关闭了 artifacts,任何设置文件都无法再将其重新开启;项目的 .claude/settings.json 或 .claude/settings.local.json 只能关闭、不能开启(自 v2.1.242 起生效)。CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0 可在发布新 artifact 时阻止浏览器自动打开。283

附加目录

将 Claude 的访问范围扩展到当前项目之外:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

对于 monorepo,或 Claude 需要引用同级目录中的代码时,附加目录必不可少。

沙箱模式

启用文件系统和网络隔离:

> /sandbox

或在设置中配置:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

自 v2.1.187 起,sandbox.credentials 设置可阻止沙箱内的命令读取凭据文件和机密环境变量,作为纵深防御措施,防止沙箱内的命令窃取机密信息。176

自 v2.1.221 起,凭据文件在 allow/deny 之外新增了第三种模式:mode: "mask"(Linux 和 WSL)。沙箱内的命令读取该文件时,得到的是一份哨兵副本:可以是整个文件,也可以只是 extract 正则表达式捕获的片段。沙箱代理会在出站时替换为真实值。命令照常工作(可以通过代理完成身份验证),而机密信息从未出现在其环境中。当遭受提示注入的命令四处搜寻令牌时,这正是您需要的特性。在 macOS 上,由于代理替换机制不可用,mask 会回退为 deny。因此,为 Linux CI 编写的配置会安全降级,而不会悄无声息地暴露文件。199

v2.1.224 将掩码能力扩展到静态文件内容之外。extract 和 onExtractNoMatch 用于处理结构化的环境变量值;decode: "jwt" 配合 maskClaims 只掩码 JWT 中选定的声明,而非整个令牌,这样命令仍可读取令牌的路由元数据,敏感声明则保持为哨兵值;awsPairs/sigv4 会在代理处重新签署 AWS SigV4 请求,正是这一点让掩码能够真正用于 AWS CLI,否则被掩码的密钥将无法通过签名验证。以上功能均需要 network.tlsTerminate,并且只在用户、托管或 --settings 作用域中生效。代码仓库无法附带一份悄悄改道您凭据的掩码配置。201

自 v2.1.216 起,sandbox.filesystem.disabled 设置会跳过文件系统隔离,同时保留网络出站控制。当文件系统隔离导致构建工具无法正常运行、而您仍希望对出站流量执行域名允许列表时,这一设置十分有用。192

自 v2.1.219 起,sandbox.network.strictAllowlist 设置会直接拒绝不在允许列表中的主机,不再弹出提示。默认情况下,沙箱内的命令访问 allowedDomains 之外的主机时会触发权限提示;启用 strictAllowlist 后,连接会被直接拒绝。在无人值守的运行场景中(CI、后台智能体、通宵循环),应当使用这一设置:无人应答的提示只会导致卡顿,而”遇到意外出站时询问我”本身就是错误的策略。它补全了网络三件套:allowedDomains 规定允许什么,deniedDomains(见下文)在宽泛的允许范围中划出例外,strictAllowlist 则决定其余一切是询问还是失败。196 v2.1.229 进一步收紧了域名列表语法本身:IPv6 字面量必须加方括号([::1]:443),有歧义的写法按失败即关闭(fail-closed)处理,/doctor 也会将其标出。257 v2.1.236 新增两项加固措施:在 macOS 上,通配符读取拒绝规则(例如 **/.env)现在在允许读取的区域内优先生效,覆盖匹配目录的内容,且无法通过重命名被拒绝的文件来绕过;此外,在 auto mode 激活期间,Monitor 允许规则会被搁置,Monitor 命令与 Bash 命令接受同样的分类器审查。auto mode 分类器本身在 Bedrock、Vertex AI 和 Foundry 上以及禁用遥测时,现在也与在 Claude API 上采用相同的默认设置运行,包括带严重程度评分的分类。246 v2.1.273 改变了这些网关上该机制的默认值:auto mode 在这些网关上“暂时”默认使用本地分类器,设置 CLAUDE_CODE_AUTO_MODE_SERVER=1 可选择使用平台的服务器端分类器。217 v2.1.278 又改了回来,并扩大了适用范围:对 Claude API 和 Enterprise 用户,以及在 Bedrock/Vertex/Foundry 和各类网关上,服务器端分类器成为默认选项,分类器开销不收费;在这些环境中,CLAUDE_CODE_AUTO_MODE_SERVER=0 现在是退出选项,回退到计费模式时会给出一次性警告。完整机制详见 Auto Mode 一节。219

auto mode 下的按命令 allowed_domains(v2.1.271):启用沙箱后,auto mode 下的 Bash、PowerShell 和 Monitor 命令可以携带各自的 allowed_domains。命令所需的主机会与命令一同接受审查,并且只对该命令开放,其他主机一律拒绝。出站访问不再是整个会话范围的授权:每条命令都要写明自己的目的地,审查的对象也恰好是这一组合。216

excludedCommands 通配符现在必须匹配复合命令的每个部分(v2.1.277)。过去,只要复合 Bash 命令中有一个部分匹配,sandbox.excludedCommands 通配符就会将整条命令排除在沙箱之外。例如,git* 排除规则会把 git pull && ./deploy.sh 整体带出沙箱。现在,复合命令的每个部分都必须匹配,命令才会在沙箱外运行。如果某个依赖排除规则的工作流把被排除的工具与其他命令串联在一起,整条命令链会留在沙箱内运行。此时请拆分复合命令,或者在审慎考虑后放宽排除规则。219

在严格策略下,项目设置无法扩大 excludedCommands(v2.1.282)。当托管设置或 --settings 设置了 allowUnsandboxedCommands: false,或托管设置设置了 allowManagedDomainsOnly: true 时,Claude Code 会忽略来自项目设置和本地设置的 sandbox.excludedCommands 条目。225

严格沙箱模式与 ! 例外(sandbox.allowUnsandboxedCommands,v2.1.260)。本指南此前尚未提及这一设置:默认情况下,在沙箱中执行失败的命令可以通过 dangerouslyDisableSandbox 这一应急出口在沙箱外重试,但仍需经过常规权限流程。sandbox.allowUnsandboxedCommands: false 会关闭这一出口(在 /sandbox 的 Overrides 选项卡中显示为 Strict sandbox mode):该参数将被忽略,每条命令要么在沙箱中运行,要么必须列在 excludedCommands 中。自 v2.1.260 起,您在 ! bash 模式提示符下亲自输入的命令即使在严格沙箱模式下也在沙箱外运行,”就像在您自己的终端中输入一样”。严格模式约束的是 Claude 运行的命令,而非您亲手输入的命令。如果您的威胁模型依赖 ! 命令继承沙箱限制,那么这一前提已不再成立。212

在沙箱模式下: - 写入仅限于工作目录、一个临时目录以及您添加的目录;读取范围覆盖”机器的大部分区域,包括凭据文件”,除非您通过 sandbox.filesystem.denyRead 或 permissions.blockReadsOutsideWorkingDirectories 加以收窄269 - 网络访问受到管控 - 部分命令不受沙箱限制 - 若 autoAllowBashIfSandboxed 为 true,Bash 命令会被自动允许

专家提示:沙箱模式非常适合在不受信任的代码库上运行 Claude。探索陌生项目时,或者希望多加一层防护时,建议启用它。Anthropic 的内部测试发现,沙箱可将权限提示减少 84%。38 沙箱借助操作系统级原语(macOS seatbelt、Linux bubblewrap)实现文件系统和网络隔离。因此,即便提示注入触达了沙箱内的 Bash 命令,也会被限制在配置的边界之内:只能写入允许的路径,只能访问允许的域名,只能读取 denyRead 未拦截的位置。这一边界有明确记载的例外:内置的文件和网络工具遵循权限规则而非沙箱,而命令 hooks、本地 MCP 服务器、插件监视器、LSP 服务器和辅助命令则以您的完整权限运行。269 Anthropic 已开源沙箱运行时,供构建自有智能体的团队使用。82

项目设置无法放宽管理员沙箱(v2.1.285)。项目设置不再能够扩大或关闭管理员强制要求的沙箱,不能替换托管拒绝列表背后的代理,不能扩展严格允许列表,也不能重新开放托管的读取拒绝规则。229

安全说明(v2.1.34+):此前,在启用 autoAllowBashIfSandboxed 时,通过 sandbox.excludedCommands 或 dangerouslyDisableSandbox 排除在沙箱之外的命令可以绕过 Bash 的 ask 权限规则;该问题已在 v2.1.34 中修复。87 自 v2.1.38 起,沙箱模式会阻止对 .claude/skills 的写入,防止提示注入篡改 skill 定义。88 v2.1.77 新增了 allowRead 沙箱文件系统设置,可在 denyRead 区域内重新允许读取访问。如果您想屏蔽大部分目录树,同时将特定子目录列入白名单,这一设置非常有用。119

.claude/ 智能体配置豁免(v2.1.121+):--dangerously-skip-permissions 在写入 .claude/skills/、.claude/agents/ 和 .claude/commands/ 时不再弹出提示。154 嵌套 .claude/ 解析(v2.1.178): 现在,嵌套 .claude/skills 目录中的 skills 不再只能从仓库根目录加载。当您处理该目录下的文件时,它们会自动加载。如果出现名称冲突,可以通过 <dir>:<name> 调用嵌套的 skill,因此两者都能继续使用。项目的其余部分也按同样的方式解析:如果 agent、workflow 或 output-style 的名称在多个嵌套 .claude/ 目录之间冲突,以离工作目录最近的那个为准。在项目范围保存 workflow 时,会写入离工作目录最近的现有 .claude/workflows/。对于 monorepo 或由多个仓库组成的仓库,这意味着每个包都可以拥有随上下文激活的专属工具,而不必共用一个扁平的全局配置。173

自定义 bubblewrap 与 socat 路径(v2.1.133+): 管理员可以通过 sandbox.bwrapPath 和 sandbox.socatPath 这两项托管设置,让 Linux/WSL 部署使用非标准位置的 bubblewrap 和 socat 二进制文件。如果发行版把这些工具安装在 $PATH 之外,或者组织自行提供加固版本,这两项设置会很有用。160

v2.1.113 中的安全加固:150

  • sandbox.network.deniedDomains 可以屏蔽特定主机,即使更宽泛的 allowedDomains 通配符本来会放行它们。借助这份阻止列表,您可以切断对 pastebin、文件投放站点或已知恶意主机的访问,而无需重写整个允许策略。如果希望允许列表之外的所有请求都被直接拒绝、不再弹出提示,可以搭配使用 sandbox.network.strictAllowlist(v2.1.219,见上文)。
  • 包装命令的拒绝规则。 Bash 拒绝规则现在可以匹配经 env、sudo、watch、ionice、setsid 等执行包装器包裹的命令。例如,Bash(rm:*) 这类规则现在可以拦截 env rm -rf、sudo rm -rf 及类似的绕过方式。
  • Bash(find:*) 允许规则不再自动批准 find -exec 或 find -delete。 这两个标志会执行命令或删除文件,因此 Claude Code 会让它们走正常的权限流程。
  • macOS 删除保护。 Bash(rm:*) 允许规则现在会把 /private/etc、/private/var、/private/tmp 和 /private/home 视为危险的删除目标。/var、/etc 和 /tmp 都是指向 /private/ 的符号链接,因此旧的规则写法漏掉了它们实际指向的目标。

v2.1.214 中的权限失败即关闭(fail-closed)加固:190

这一版本集中修补了一批权限检查漏洞,并且一律采用失败即关闭的方式:只要分析器无法确定,就会弹出提示。

  • 修复 Windows PowerShell 5.1 绕过问题。 此前,在 PowerShell 5.1 会话中运行的命令可能绕过权限检查。
  • Bash 文件描述符重定向改为失败即关闭。 如果某种重定向写法在 bash 中的解析结果与权限分析器不同,现在会弹出提示,而不是直接运行。
  • 超过 10,000 个字符的命令一律弹出提示。 超长命令此前可能被误判,现在永远不会自动运行。
  • [[ ]] 中的 zsh 下标和修饰符会触发提示。 [[ ]] 比较中的变量下标和修饰符此前被当作无害文本,但它们其实可以执行代码,因此现在需要批准。
  • 不安全的 help/man 变体不再自动批准。 某些调用方式会打着查阅文档的幌子,运行不安全的选项、命令替换或反斜杠路径。
  • 远程会话的提示顺序。 在远程会话中,权限提示不再可能先于本地确认对话框被放行。
  • docker 守护进程重定向标志会触发提示。 带有 --url、--connection、--identity 或 Podman 远程模式的 docker 命令(包括 Podman 的 docker 兼容层)此前无需提示即可运行,而这些标志会让命令指向完全不同的守护进程。
  • file 被指定写入位置时,不再按只读命令放行。 file -m/--magic-file 和 -f/--files-from 现在需要授权,不再作为只读命令被自动允许。

沙箱自动允许(v2.1.289-292)。 v2.1.289 修补了两个在沙箱自动允许模式下 Bash 拒绝或询问规则被跳过的漏洞:一是命令前带有环境变量前缀且其值会被展开(TZ="$HOME" rm -rf build),二是命令前带有单独的变量赋值。235 v2.1.290 让沙箱中的 Monitor 工具命令也遵循您的权限规则,不再跳过提示。此外,管道传给另一条命令的沙箱 heredoc(cat <<EOF | python3)也不会再每次运行都询问。235 从 v2.1.292 起,如果在用户设置、托管设置或 --settings 设置中启用了严格沙箱模式,带环境变量前缀的解释器命令(如 FOO=bar python3 app.py)可以直接运行,无需提示。236 如果托管设置忽略了您配置的沙箱 allowRead 路径或允许的域名,v2.1.290 还会在 /status 和 doctor 中显示警告。235

沙箱加固(v2.1.305-310)。 sandbox.allowNestedUserNamespaces(v2.1.305)允许 Linux 上的沙箱命令为 Chromium 或 rootless podman 创建用户命名空间,但这也会让这些命令绕过沙箱的文件保护。v2.1.309 修补了多个漏洞:

  • 在 macOS 和 Linux 上,沙箱 Bash 命令每次运行前,不再在沙箱外执行 shell 的启动文件。
  • 如果 macOS denyWrite glob 模式中的文件夹要经过符号链接才能到达,规则现在会作用于路径的真实位置。
  • 沙箱命令和自动接受的编辑不能再修改通过 --mcp-config 传入的 MCP 配置文件。
  • 后台命令在会话结束后仍在运行时,Linux 上的写入拒绝不再随之解除。
  • 如果沙箱已启用但无法运行,被设置排除在沙箱之外的命令在写入沙箱写入列表中的路径前会先询问,并且不允许改为在沙箱外运行。

同一版本中,sed -i 改为使用标准的 Bash 提示,并按原样执行,不再显示模拟的文件编辑预览。与其他 Bash 编辑一样,它所做的修改不再能通过 /rewind 撤销。如果 Ubuntu 的 AppArmor 对用户命名空间的限制导致 bubblewrap 无法启动沙箱,v2.1.310 会在 /sandbox 和启动警告中指出这项限制以及解除方法。AppArmor 配置文件见沙箱文档。278279

Hooks 如何工作?

Hooks 会在 Claude Code 工作流的特定节点执行确定性的 shell 命令。与通过提示让 Claude 执行操作不同,hooks 无论模型如何表现都能保证执行。它们是落实团队规范、自动化重复任务的关键手段。关于涵盖 command、prompt 和 agent 三类 hook 的“该选哪种 Hook 类型?”决策树,请参阅决策框架。

为什么用 hooks 而不是提示词: 告诉 Claude“编辑文件后务必运行 Prettier”有时管用。但 Claude 可能会忘记、优先追求速度,或者认定这次改动“太小”而跳过。Hooks 则保证执行:每一次 Edit 或 Write 都会触发您的格式化工具,每次如此,绝无例外。在合规、安全和团队规范方面,确定性胜过概率性。4

可用事件

事件 触发时机 可否阻止 用途
PreToolUse 工具执行前 是 验证、记录或阻止操作
PostToolUse 工具完成后 否 格式化输出、运行 linter、触发构建
PostToolUseFailure 工具失败后 否 记录失败、发送告警、提供纠正性反馈
PostToolBatch 一批并行工具调用完成后、下一次模型调用之前 是 在模型调用之间设置检查点或中止智能体循环4
UserPromptSubmit 用户发送提示词 是 添加上下文、验证输入、注入数据
UserPromptExpansion 输入的命令展开为提示词 是 审计或否决 skill/斜杠命令的展开;stdout 会添加上下文4
Notification 触发提醒 否 自定义通知处理
MessageDisplay 显示助手消息文本时 否 通过 displayContent 转换或隐藏屏幕上的文本——仅影响显示,转录记录不变(v2.1.152+)267
Stop Claude 完成响应 是 防止过早停止,强制执行完成标准。包含 last_assistant_message(v2.1.47+)
SubagentStart Subagent 启动 否 记录智能体类型,通过 additionalContext 注入上下文
SubagentStop Subagent 完成 是 防止 subagent 停止,强制执行质量门禁。包含 last_assistant_message(v2.1.47+)
TeammateIdle 智能体团队成员空闲 是 在队友停止前强制执行质量门禁(v2.1.33+)
TaskCreated 通过 TaskCreate 创建任务 是 强制执行任务命名和范围规则;exit 2 会回滚创建操作(v2.1.84+)。注意:自 v2.1.233 起,任务工具在 Opus 4.8/Sonnet 5/Fable 5 及更新模型上默认关闭(CLAUDE_CODE_ENABLE_TODO_TOOLS=1 可恢复);注意:自 v2.1.268 起,任务工具仅在允许列表内的模型上提供——Claude 3.x、Opus 4.0-4.7、Sonnet 4.0-4.6、Haiku 4.5——其他模型需通过 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 启用(v2.1.233 首次在较新模型上将其关闭),因此在列表之外的模型上,此事件仅在重新启用后才会触发131254216
TaskCompleted 任务标记为完成 是 强制执行完成标准、运行测试(v2.1.33+)
SessionStart 会话开始 否 环境设置、加载上下文、设置环境变量
SessionEnd 会话结束 否 清理、最终日志记录
Setup --init/--init-only/--maintenance 标志 否 环境设置任务(v2.1.10+)53
InstructionsLoaded 加载 CLAUDE.md 或 .claude/rules/*.md 时 否 响应指令文件变更、注入上下文(v2.1.69+)
ConfigChange 会话期间配置文件发生变更 是 审计设置变更、强制执行安全策略(v2.1.49+)
DirectoryAdded 会话中途注册了新的工作目录 否 响应 /add-dir 或 SDK 的 register_repo_root 控制请求——加载各仓库的上下文、重新设定 linter 的作用范围、审计范围扩展(v2.1.219+)196
CwdChanged 工作目录发生变化 否 重新加载 direnv 风格的环境(v2.1.83+)123
FileChanged 被监视的文件在磁盘上发生变化 否 响应监视路径的变更——通过 SessionStart hook 的 watchPaths 输出注册路径(v2.1.83+)123
WorktreeCreate 正在创建 worktree 是 自定义 VCS 设置(替代默认的 git 行为)(v2.1.50+)
WorktreeRemove 正在移除 worktree 否 自定义 VCS 清理(v2.1.50+)
PreCompact 上下文压缩之前 是(v2.1.105+) 验证、日志记录、阻止压缩(exit 2 或 {"decision":"block"});自 v2.1.314 起输出截断至 10,000 个字符,因此体量过大的 hook 不会导致压缩失败或重复284
PostCompact 上下文压缩之后 否 日志记录、缓存复用优化(v2.1.76+)118
Elicitation MCP 服务器请求结构化输入 是 拦截/覆盖 MCP 的 elicitation 对话框(v2.1.76+)118
ElicitationResult 用户响应 MCP 的 elicitation 是 验证/转换 elicitation 响应(v2.1.76+)118
StopFailure 因 API 错误(速率限制、认证失败)导致回合结束 否 错误告警、重试逻辑(v2.1.78+)120
PermissionRequest 显示权限对话框 是 自定义审批逻辑
PermissionDenied 自动模式分类器拒绝操作 否 记录拒绝情况,返回 {retry: true} 以允许重试(v2.1.88+)127
PreModelSwitch 在您或客户端请求的模型切换之前:/model 及其选择器、/config 中的 Model 设置、会更改模型的快速模式开关、SDK 或 Remote Control 的 set_model 是 阻止、确认模型切换,或为其估价。匹配器比较的是由 to_model 派生出的规范名称(别名、带日期的 ID 和 Bedrock ID 都会解析为该名称;精确名称、竖线分隔的列表和正则表达式均可使用);输入携带 from_model/to_model 以及缓存成本字段(context_tokens、prompt_cache_warm、cache_ttl、estimated_cache_write_usd)。Exit 2 或 permissionDecision: "deny" 会取消切换,"ask" 会提示用户,而在默认 30 秒超时时被取消的 hook 会阻止切换。Claude Code 自行发起的切换不会运行此 hook(v2.1.251+)206208
PostModelSwitch 会话模型发生变化之后,包括 Claude Code 自行做出的变更:自动回退、opusplan 阶段切换、恢复会话时还原的模型 否 针对特定模型的指导:exit 0 时的纯文本 stdout(或 JSON 格式的 additionalContext)会在切换后的下一次请求中作为上下文传递给 Claude。与 PreModelSwitch 使用相同的规范名称匹配器和输入,另加 source 值 auto 和 resume;默认 30 秒超时(v2.1.251+)206208
SessionStart 的 source 值。 SessionStart hook 的输入包含一个 source 字段,用于说明会话是如何开始的:"startup"、"resume"、"clear" 或 "compact"。自 v2.1.214 起,以 fork 方式诞生的会话会报告 source: "fork" 而非 "resume"——这是 v2.1.212 中 /fork 转入后台这一变更在 hook 侧的对应改动。如果某个 SessionStart hook 依据 source 分支处理(例如仅在 "resume" 时重新注入上下文),请更新其匹配列表,将 "fork" 也纳入其中。190 自 v2.1.251 起,当 source 为 "resume" 或 "fork",且转录记录中至少包含一条 Claude 的先前响应时,SessionStart hooks 还会收到四个恢复成本字段——seconds_since_last_response、context_tokens(首次请求作为提示词重新发送的内容量)、prompt_cache_likely_expired(当最后一条响应早于会话的缓存 TTL,或后续的压缩替换了已缓存的对话时为 true)以及 estimated_cache_write_usd——这样 hook 就能在首次请求之前报告恢复一段陈旧对话的成本。206208

Hook 配置

在 settings.json 或专用的 hooks.json 中定义 hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

匹配器

matcher 字段决定哪些工具会触发 hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

使用 | 可匹配多个工具(Edit|Write)。自 v2.1.191 起,逗号分隔的匹配器(例如 Bash,PowerShell)也能正确触发——早期版本会静默丢弃它们,因此带有逗号匹配器的 hook 从未运行过。178 自 v2.1.195 起,带有连字符标识符的匹配器(例如 code-reviewer、mcp__brave-search)采用精确匹配,而不再意外地进行子串匹配,因此匹配器不会再在仅仅包含该字符串的非预期工具上触发。若要匹配来自带连字符的 MCP 服务器的所有工具,请使用显式模式,例如 mcp__brave-search__.*。179

自 v2.1.214 起,hook 的 if: 路径条件以当前工作目录(cwd)为作用域。 影响权限允许规则的同一项单段作用域变更(参见权限规则语法)同样适用于 hook 的 if: 条件:像 dir/** 这样的条件现在只匹配 <cwd>/dir,而不是目录树中的每一个 dir/。若希望恢复任意深度的匹配,请写成 **/dir/**。190 自 v2.1.314 起,诸如 Monitor(tail *) 的条件会匹配 Monitor 工具的 shell 命令,就像 Bash(tail *) 匹配 Bash 的命令一样;匹配 Bash 的 hook 也会在这些命令上运行,在那里它们可以阻止或询问,但不能批准或改写。284

Hook 输入/输出协议

Hook 通过 stdin 接收 JSON:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Hook 事件信息增强(v2.1.69+): 当从 subagent 或 --agent 会话触发时,所有 hook 事件现在都包含 agent_id 和 agent_type 字段,状态栏 hook 命令中还会额外包含 worktree 字段。110

Stop/SubagentStop hook(v2.1.47+)会额外收到一个 last_assistant_message 字段,其中包含 Claude 的最终回复文本,因此 hook 无需解析转录文件即可检查输出:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

不阻止的软性反馈(v2.1.163+): Stop 和 SubagentStop hook 可以在其 JSON 输出中返回 hookSpecificOutput.additionalContext,向 Claude 传递反馈并让本轮继续进行,而不会把回复标记为 hook 错误。在此之前,Stop hook 唯一真正的手段是退出码 2 的阻止(它会显示为错误,并计入连续阻止上限);additionalContext 则增加了一条引导通道,用于传达“这是您遗漏的内容,请继续”之类的指引,而不会与循环相冲突。264

退出码决定行为: - 0:成功:Claude Code 会应用 hook 打印的所有 JSON 输出字段,除非这些字段阻止、拒绝或停止操作,否则操作继续进行。对于大多数事件,stdout 会写入调试日志,不会显示在转录中;在 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch 事件上,纯文本 stdout 会作为 Claude 可以看到并据此行动的上下文添加进来。277 - 2:阻止性错误:操作停止。stderr 会成为反馈给 Claude 的错误消息。 - 1、3 等:非阻止性错误:操作继续进行,除非该 hook 属于失败即阻止操作的类型,例如 onFailure 设为 "block" 的 hook。当 stdout 为纯文本或为空时,<hook name> hook error 通知(在 PreToolUse 等事件上)会携带 stderr 的第一行;通过验证的 JSON 仍会被应用,退出码则被忽略(对于失败即阻止操作的 hook,该次运行会被计为失败)。277

失败即阻止(v2.1.295+): 默认情况下,hook 无法启动、超时、以 0 或 2 以外的退出码退出、遇到 HTTP 错误,或打印的输出未通过 JSON 验证,都属于非阻止性错误,因此路径拼写错误的策略 hook 会放行一切。在 command 或 http hook 上设置 "onFailure": "block" 后,上述每一种失败都会产生与退出码 2 在该事件上相同的效果:PreToolUse 失败会阻止工具调用,UserPromptSubmit 失败会阻止提示,而在 PermissionRequest 上则会拒绝请求。错误行显示为 failed; blocking because onFailure is "block"(超时后为 timed out),后面紧跟 hook 自身的输出。以退出码 1 退出但带有允许操作的 JSON 的 command hook 仍被计为失败;若要返回 JSON 决定,请以退出码 0 退出。该字段在 Stop、SubagentStop、TaskCompleted 和 TeammateIdle hook 上会被忽略(在这些 hook 上,退出码 2 会让 Claude 回去继续工作),在 async 或 asyncRewake command hook 上也会被忽略。默认值为 "continue"。238240

若需更高级的控制,hook 可在 stdout 上打印 JSON 并以退出码 0 退出。对于非异步的 hook,stdout 上不要再打印任何其他内容:shell 配置文件在启动时回显的一行文本,就足以让 Claude Code 无法将该对象识别为 JSON。参考文档描述了三类字段:所有事件都接受的通用字段(部分事件会丢弃它们,或把 systemMessage 投递到转录以外的地方;参考文档中各事件的章节会说明具体情况)、部分事件用于阻止或提供反馈的顶层 decision 和 reason,以及 hookSpecificOutput——一个供需要更精细控制的事件使用的嵌套对象,它要求包含一个设为事件名称的 hookEventName 字段。通用字段如下:277

字段 默认值 说明
continue true false 会在 hook 运行后完全停止 Claude;它优先于任何事件特定的决定字段
stopReason 无 continue 为 false 时向用户显示的消息;它会保留在对话中,因此如果对话继续,Claude 会看到它
suppressOutput false 可接受但无任何效果:成功 hook 的 stdout 永远不会显示在转录中,而是记录到调试日志
systemMessage 无 向用户显示的警告;在 Agent SDK 和 --output-format stream-json 输出中,它可能以 SDKInformationalMessage 的形式出现
terminalSequence 无 Claude Code 代表 hook 发出的终端转义序列(桌面通知、窗口标题、响铃);仅限 OSC 0、1、2、9、99、777 和 BEL,如果值包含其他任何内容则被忽略;仅在交互式会话中且界面显示在屏幕上时写入,在 -p 模式下和 Agent SDK 中会被忽略
{
  "continue": false,
  "stopReason": "The deploy window is closed. Nothing else runs until it reopens.",
  "systemMessage": "deploy-gate stopped this turn"
}

PreToolUse 决定控制(推荐格式): PreToolUse hook 使用 hookSpecificOutput 实现更精细的控制:三种结果(allow/deny/ask),外加修改工具输入和注入上下文的能力:89

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}
字段 取值 说明
permissionDecision "allow"、"deny"、"ask"、"defer" allow 绕过权限检查,deny 阻止,ask 提示用户,defer 则暂停以等待外层包装进程处理(v2.1.89+;多 hook 优先级为 deny > defer > ask > allow)
permissionDecisionReason 字符串 向用户显示(allow/ask)或向 Claude 显示(deny)
updatedInput 对象 在执行前修改工具输入;自 v2.1.300 起,它会像 Claude 自身的输入一样接受验证:未知键会被丢弃,工具拒绝的输入会导致调用被拒绝273
additionalContext 字符串 注入到 Claude 本轮的上下文中44
注意: 顶层的 decision 和 reason 字段在 PreToolUse 中已弃用。请改用 hookSpecificOutput.permissionDecision 和 hookSpecificOutput.permissionDecisionReason。其他事件(PostToolUse、Stop 等)仍使用顶层 decision。89

UserPromptSubmit 会话标题(v2.1.94+): UserPromptSubmit hook 可以通过 hookSpecificOutput.sessionTitle 设置会话标题。140

UserPromptSubmit 在展开之前运行(v2.1.299)。 UserPromptSubmit hook 现在会在 skill 或自定义斜杠命令展开之前运行,因此阻止提示的 hook 也会一并阻止该命令内嵌的 ! shell 行;UserPromptExpansion 仍会在展开本身时触发。在 skill 自身 frontmatter 中声明的 UserPromptSubmit hook,首次运行是在调用该 skill 的那条提示之后的下一条提示上。hooks 参考文档尚未描述这一顺序。271272

异步 Hook(2026年1月)

Hook 现在可以在后台运行,而不会阻塞 Claude Code 的执行。在 hook 配置中添加 async: true:81

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

何时使用异步 hooks: - 不应拖慢会话的通知(Slack、电子邮件、Pushover) - 可在后台运行的日志记录与遥测 - 非关键的后处理(分析、备份)

何时不应使用异步 hooks: - 格式化(必须在下一次编辑前完成) - 验证(失败时必须阻断) - 任何需要修改工具输入/输出的 hook

基于提示词与基于代理的 Hooks(v2.1.32+)

除 shell 命令 hooks(type: "command")之外,Claude Code 还支持两种由 LLM 驱动的 hook 类型,它们借助 AI 推理而非脚本来评估条件。89

Prompt hooks(type: "prompt")向快速的 Claude 模型发送单轮提示。模型返回 { "ok": true } 表示允许,返回 { "ok": false, "reason": "..." } 表示阻断:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

HTTP hooks(type: "http")将事件的 JSON 输入以 POST 请求发送到某个 URL,并接收返回的 JSON。适用于 webhook、外部通知服务或基于 API 的验证(v2.1.63+):104

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTP hooks 使用与命令 hooks 相同的决策格式(返回包含 decision 和 reason 的 JSON)。启用沙箱时,它们会经由沙箱网络代理路由。不支持 SessionStart/Setup 事件。

Agent hooks(type: "agent")会生成一个具备工具访问权限(Read、Grep、Glob)的 subagent,用于多轮验证。当检查需要查看实际文件或测试输出时,不妨使用这种类型:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

使用 $ARGUMENTS 作为 hook 的 JSON 输入的占位符。两种类型都支持 model(默认为快速模型)和 timeout 字段。支持的事件:PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、UserPromptSubmit、Stop、SubagentStop、TaskCompleted。TeammateIdle 不支持 prompt/agent hooks。

PermissionRequest 不再运行 agent 类型的 hooks(v2.1.280)。 其中的原因值得直说,因为它解释了一类从未真正起过作用的 hook:agent hook 的答复从来无法允许或拒绝请求,因此注册在 PermissionRequest 上的 agent hook 所做的工作,其结果都被直接丢弃了。Claude Code 现在不再默默接受这种配置,而是显示一条错误,引导您改用能够返回裁决的 command 或 http hooks。如果您的设置文件或插件中存在 PermissionRequest agent hook,那么在此版本之前它同样没有拦截任何东西——这条错误只是第一次有人告诉您这一点。请将相关逻辑移植到 command hook 中。220

Hook 并发(v2.1.302、v2.1.312)。 自 v2.1.302 起,prompt 和 agent hooks 对同一事件最多同时运行 12 个;自 v2.1.312 起,每个会话(包括 subagents)最多同时运行 24 个,另外最多再允许 12 个等待时间已超过其事件超时阈值的 hook,且不足一秒的 timeout 按一秒计。命令 hooks 不受影响,而 hooks 参考文档仍然只提到所有匹配的 hooks 会并行运行。275276284

MCP 工具 Hooks(v2.1.118+)

Hooks 现在可以通过 type: "mcp_tool" 直接调用 MCP 工具,无需再包一层调用服务器的 Bash 子进程。152

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

这与用户已配置好的 MCP 服务器配合得很好:任何可从 /mcp 访问的工具都可以被 hook 调用。

PostToolUse Hooks 中的 duration_ms(v2.1.119+)

PostToolUse 和 PostToolUseFailure 的 hook 输入现在包含 duration_ms,即工具的执行时间(不含权限提示和 PreToolUse hooks 所用的时间)。152 可用于慢工具检测、审计日志以及按工具统计的延迟指标:

# Stderr-flagged warning when an Edit takes more than 10 seconds
INPUT=$(cat)
DUR=$(jq -r '.duration_ms' <<<"$INPUT")
FILE=$(jq -r '.tool_input.file_path // "?"' <<<"$INPUT")
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $FILE" >&2
fi

适用于所有工具的 updatedToolOutput(v2.1.121+)

在 v2.1.118 中,MCP 工具 Hooks 获得了通过 hookSpecificOutput.updatedToolOutput 替换工具输出的能力。自 v2.1.121 起,同一字段适用于任何 PostToolUse hook——内置工具(Bash、Read、Edit、Glob、Grep 等)、subagent 工具以及 MCP 工具。用例包括:从任意工具的输出中脱敏敏感内容、为下游消费者规范化结构、在代理读取结果之前注入元数据。154

Hook 环境变量

Hooks 可以访问以下环境变量来解析路径:89

变量 可用范围 说明
$CLAUDE_PROJECT_DIR 所有 hooks 项目根目录(路径含空格时请加引号)
${CLAUDE_PLUGIN_ROOT} 插件 hooks 插件的根目录
$CLAUDE_ENV_FILE 仅 SessionStart 用于持久化环境变量的文件路径,供后续 Bash 命令使用
$CLAUDE_CODE_REMOTE 所有 hooks 在远程 Web 环境中设为 "true"
$CLAUDE_EFFORT 所有 hooks + Bash 工具子进程 当前的 effort 级别。Hooks 也可通过 effort.level JSON 输入字段获取该值(v2.1.133+)。160
$CLAUDE_CODE_SESSION_ID Bash 工具子进程 与传递给 hooks 的 session_id 一致的会话 ID。可让长时间运行的 shell 在同一会话中关联输出(v2.1.132+)。159
从 SessionStart 持久化环境变量:
#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Claude Code Hooks 与 Agent SDK Hooks 的区别

同一组生命周期事件——PreToolUse、PostToolUse、UserPromptSubmit、Stop、SubagentStop 以及上文列出的其余事件——存在于两种消费模型中。由于搜索 Agent SDK hook 生命周期的读者常常会来到这里,这一区别值得单独设一个标题。

Claude Code(CLI)hooks 正是本节所记录的内容:在 settings.json 中配置的处理程序,通过 stdin 接收事件 JSON,并以退出码或 stdout 上的 JSON 作出应答。强制执行由 CLI 负责——PreToolUse 的 deny 会在工具调用运行之前将其阻断,即使在 bypassPermissions 模式下也是如此。4

Agent SDK hooks 是面向将 Claude Code 运行时作为库嵌入的 harness 的编程接口。在 claude-agent-sdk-python 中,在 ClaudeAgentOptions 上设置 include_hook_events=True,就能让 HookEventMessage 对象(PreToolUse、PostToolUse、Stop 及其他事件)与助手消息和工具结果从同一个迭代器中产出;TypeScript SDK 通过 includeHookEvents 提供对应功能,其控制协议也跟随 CLI 的事件名册(TypeScript SDK 在 CLI 发布 DirectoryAdded 的同一版本中加入了该事件)。负载结构与 CLI 的 stdin JSON 一致——session_id、hook_event_name、tool_input 以及各事件专有的字段——PreToolUse 的决策语义也保持相同的优先级(deny > defer > ask > allow)。4

强制执行方面的注意事项是最值得牢记的部分。 SDK 侧的 hook 强制执行已两次被证明会在生命周期边缘处“失败即放行”(fail open)——在 TypeScript SDK 中,hook 挂起期间到达的调用方中止被转换成了 hook 成功;在 Python SDK 中,一条流关闭路径让后台 subagent 的工具调用完全绕过了 PreToolUse。两者均已修复,但这种模式是结构性的:当传输在收集到 hook 裁决之前就已终止时,被绕过的 hook 看起来与批准了的 hook 一模一样。如果 SDK hooks 把关的是任何与安全相关的事项,请固定当前的 SDK 版本,并保留一个 CLI 层的 shell hook 作为您能够证明的强制执行手段。Agent Architecture 指南深入介绍了 SDK hook 接口、版本下限以及 harness 模式。 HTTP hook 安全性(v2.1.51+): 将环境变量插入请求头的 HTTP hook 现在必须显式提供 allowedEnvVars 列表,以防止通过请求头值泄露任意环境变量。启用沙箱时,HTTP hook 还会经由沙箱网络代理路由,从而强制执行域名白名单。SessionStart/Setup 事件不支持 HTTP hook。98

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Hook 工作区信任(v2.1.51+): statusLine 与 fileSuggestion hook 命令现在必须先获得工作区信任,才能在交互模式下执行,从而堵住了一个潜在的安全漏洞。98

实用 Hook 示例

编辑后自动格式化 TypeScript 文件:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); [[ \"$FILE\" == *.ts ]] && npx prettier --write \"$FILE\" || true'"
          }
        ]
      }
    ]
  }
}

记录所有 bash 命令:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

阻止访问敏感文件:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

代码变更后运行测试:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); [[ \"$FILE\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

自定义通知系统:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

向提示词注入动态上下文:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hook 调试

启用调试模式以排查 hook 问题:

claude --debug

调试模式会记录: - Hook 执行耗时 - 输入/输出数据 - 错误信息与堆栈跟踪 - 决策结果(allow/reject/ask)

Hook 来源显示(v2.1.75+): 当某个 hook 需要用户确认时,权限提示现在会显示该 hook 的来源(settings、plugin 或 skill),更容易辨别是哪个组件在请求访问权限。117

组件级作用域 Hooks(v2.1.0+)

Hooks 可以通过 frontmatter 直接定义在 Skills、subagents 和斜杠命令中。这类 hook 的作用域限定于所属组件的生命周期,仅在该组件处于活动状态时运行。34

内嵌 hooks 的 Skill:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

支持的事件:PreToolUse、PostToolUse、Stop

once 选项(仅限 skills 和斜杠命令)可确保 hook 在每个会话中只运行一次,适合清理或收尾类任务。

Agent frontmatter hooks 需要工作区信任(v2.1.218)。 在 agent 文件 frontmatter 中声明的 hooks 不再从未受信任的文件夹中运行:包含该 agent 文件的文件夹本身必须先接受工作区信任,其 hooks 才会执行。这堵住了一个空子:此前,放进未受信任目录的 agent 文件可以在没有任何信任提示的情况下执行 hook 命令。此项变更将 v2.1.51 对 statusLine/fileSuggestion 的信任要求扩展到了 agent 作用域的 hooks。195

长时运行会话策略

对于通宵或无人值守的 Claude Code 会话,可以配置 hooks,让 Claude 无需人工干预也能保持在正轨上。核心思路是:把代码检查和测试 hooks 用作护栏,迫使 Claude 先修复问题再继续。57

“测试通过前绝不停下”模式:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

通宵会话策略:

  1. 预检:使用 Setup hook 确认环境已就绪
  2. 持续验证:PostToolUse hooks 在每次变更后运行测试
  3. 把关完成:Stop hooks 在 Claude 宣告“完成”之前核验所有验收标准
  4. 通知:当 Claude 完成任务或陷入停滞时,Stop hooks 可通过 Slack/Pushover 通知您

在沙箱容器中配合 --dangerously-skip-permissions 使用,即可实现完全自主的通宵运行。Claude 会持续迭代,直到测试通过或用尽所有办法。

什么是MCP(模型上下文协议)?

MCP通过标准化协议扩展Claude Code的能力,使其能够访问外部工具、数据库、API和服务。其生态系统迅猛发展:截至2026年1月,MCP的月下载量已达1亿次,MCP.so收录的服务器超过3,000个,巩固了其作为连接AI与工具和数据的行业标准的地位。347要将Claude集成到现有工具链中,理解MCP至关重要。

MCP对开发者的重要性:没有MCP,Claude Code只能读取文件和运行bash命令。有了MCP,Claude就能查询生产数据库、创建Jira工单、审查GitHub PR、检查Sentry错误,并与团队使用的任何API交互。这一切都可以通过自然语言请求完成。该协议统一了AI工具连接外部服务的方式,避免供应商锁定。关于何时选择MCP或其他扩展机制,请参阅决策框架。

远程MCP支持(2025年6月)

Claude Code现已支持远程MCP服务器,并原生支持OAuth身份验证。21无需管理本地服务器,即可连接工具和数据源。只需完成一次身份验证,Claude Code便会自动刷新令牌。

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri(v2.1.121+):Agent SDK的mcp_authenticate接受redirectUri参数,可通过自定义URI方案完成OAuth流程。对于无法使用默认环回重定向的桌面应用和claude.ai连接器流程,这是必需的。154

claude.ai MCP连接器(v2.1.46+)

Claude Code现在可以使用您在claude.ai账户中配置的MCP连接器。这打通了网页端与CLI:通过claude.ai界面设置的MCP服务器会自动出现在Claude Code中,无需在本地重新配置。95

禁用此功能:在环境变量或settings.json的env块中设置ENABLE_CLAUDEAI_MCP_SERVERS=false,即可阻止加载claude.ai MCP服务器。104

组织管理的连接器(v2.1.243+):对于由组织管理身份验证的claude.ai连接器,/mcp和/plugins会显示managed标签,方便区分管理员配置的连接器和您自行连接的连接器。250

MCP工具搜索(v2.1.7+)

随着MCP服务器的功能不断增强(有些服务器提供50多个工具),工具描述开始占用过多上下文。MCP工具搜索通过仅在需要时动态加载工具描述来解决这一问题,相当于为AI工具提供延迟加载机制。47

性能影响:内部基准测试显示,准确率显著提升: - Opus 4:MCP评估得分从49% → 74% - Opus 4.5:MCP评估得分从79.5% → 88.1% - Token开销降低:85%

工作原理:当MCP工具描述超过上下文窗口的10%(默认阈值)时,Claude Code会推迟加载完整描述,直到实际需要时才加载。Claude能看到工具名称,但会按需获取描述。

各提供商的默认行为(v2.1.304-305)。自v2.1.304起,使用自定义ANTHROPIC_BASE_URL时默认启用工具搜索;如果网关返回400或422,则会禁用工具搜索后重试。v2.1.305修复了v2.1.304引入的回归问题:在Vertex、Bedrock以及其他端点拒绝工具搜索的提供商上,或在禁止ToolSearch、或未将其纳入--tools的网关后,每次请求都会失败。Claude Code现在会禁用工具搜索后重试。在Vertex AI上,除非设置ENABLE_TOOL_SEARCH=true,否则工具搜索仍保持关闭。278

配置:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

可选值: - true - 始终启用工具搜索 - false - 始终禁用(预先加载所有工具描述) - auto:N - 当工具占用超过上下文的N%时启用(0-100)

专家建议:启用工具搜索后,您可以连接更多MCP服务器,无需担心上下文限制。上下文占用减少95%,意味着原本争夺上下文空间的服务器现在可以共存。

MCP始终加载覆盖设置(v2.1.121+)

工具搜索会推迟加载完整描述,直到需要使用工具时才加载(阈值:mcpToolSearchAutoEnable,默认值为auto:10)。对于可信且预计每轮都会使用其工具的服务器,可以设置alwaysLoad: true,单独关闭该服务器的延迟加载。这样,该服务器的所有工具都会在会话开始时加载到提示词中,无需经过ToolSearch往返调用:154

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

alwaysLoad: false(v2.1.287):将此字段设为false,会让该服务器的所有工具延迟至通过工具搜索时才加载。232

MCP启动自动重试(v2.1.121+):服务器启动出错时,现在会最多重试3次,之后才标记为断开连接。这适用于因父进程启动缓慢而出现时序冲突的stdio服务器,以及后端处于冷启动阶段的HTTP服务器。154

MCP信息征询(v2.1.76+)

MCP服务器现在可以在任务执行期间,通过交互式对话框向用户请求结构化输入。118当MCP服务器需要额外信息时(例如选择分支、输入项目名称或确认操作),会发送信息征询请求,Claude Code将其呈现为表单字段或浏览器URL。

hooks集成:两个新增的hooks事件——Elicitation(对话框出现前)和ElicitationResult(用户响应后)——允许您以编程方式拦截、验证或覆盖信息征询响应。由此可以实现企业工作流,对MCP服务器的提示表单进行预填,或按策略限制其内容。

URL模式(v2.1.281):对于使用2026-07-28版MCP协议的连接,服务器可以通过URL模式的信息征询,请求Claude Code打开浏览器流程。如果服务器无法确认流程是否完成,屏幕上不会保留等待对话框。224v2.1.287增加了对使用2025-11-25版协议的服务器所发出URL提示的支持,例如用于登录。如果服务器在更新后无法连接,请在其MCP配置条目中添加"bareElicitationCapability": true;10月1日获取的MCP文档中并未列出该键。232233从v2.1.288起,如果发出URL提示的服务器无法报告您何时完成操作,工具调用会等待您选择“我已完成,继续”后再继续,以便您先在浏览器中完成操作。234

MCP结果大小覆盖设置(v2.1.91+)

MCP工具结果默认会被截断。服务器可以使用_meta["anthropic/maxResultSizeChars"]注解,针对单个结果覆盖此限制,最多允许500K个字符。136这适合返回数据库结构、API响应或文件内容等大型数据,避免内容被截断。

MCP描述长度上限覆盖设置(v2.1.280+)

除了上述结果大小上限,Claude Code还会限制服务器加入上下文的描述文本:从v2.1.296起,MCP工具描述和服务器指令会在4,096个字符处截断(v2.1.280至v2.1.295为2,048个字符)。CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH可修改这一数值;自v2.1.295起,模型通过工具搜索加载的描述改为在16,384个字符处截断,而非2,048个字符。220238自v2.1.299起,来自api.anthropic.com上Anthropic第一方MCP服务器的工具描述和服务器指令,会完整传递给Claude;但截至10月14日,MCP文档的限制列表仍只列出4,096和16,384这两个数值。271272

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192 claude

使用此设置前,需要了解两个特点:

  • 它作用于整个会话,无法按服务器单独设置。更新日志明确指出,新上限适用于“会话中的每个MCP服务器”。您无法只提高某个描述冗长的服务器的上限,同时让其他服务器保持默认值——提高上限会影响所有服务器。
  • 放行的内容可能常驻上下文。服务器指令始终在会话开始时加载。只有工具搜索未延迟加载时,工具描述才会预先加载:包括工具搜索关闭时(ENABLE_TOOL_SEARCH=false、非第一方ANTHROPIC_BASE_URL)、工具描述占用低于阈值时,或服务器设置了alwaysLoad时。预先加载的描述会在每次请求中保留在提示词内,无论模型是否实际调用这些工具。因此,如果十几个这样的服务器都采用更高上限,就会持续占用上下文。223

适合调整此参数的情况:服务器的工具确实需要较长描述才能被正确调用,例如数据库结构复杂的数据库服务器,或参数含义不直观的内部API接口,而且已有明确迹象表明截断导致了错误调用。值得调整的具体症状是:模型误用了某个工具,而该工具在/mcp中显示的描述在句子中途就被截断。

不适合调整此参数的情况:服务器只是描述过于冗长。开销更低的修复方式仍然更好——MCP工具搜索能解决上述预先加载带来的开销,因为它会将工具定义留在提示词之外,直到Claude需要时才加载;精简服务器自身的描述则能从根源上解决问题,而非单纯放宽限制。只有准确性确实需要时才提高上限,随后检查/context,了解实际开销。

交互式MCP设置向导

不带参数运行claude mcp add,即可启动分步界面来添加MCP服务器。向导会引导您选择传输类型、完成身份验证并进行配置。8

传输类型

HTTP(推荐用于远程服务器):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE(已弃用,但仍可使用):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

从v2.1.265起,即使是旧版服务器,也很少需要显式指定此标志:配置为http但仅支持旧版HTTP+SSE传输的MCP服务器,以前完全无法连接,现在会按MCP规范所述自动回退到SSE。215v2.1.274补齐了这一回退机制的缺口——首次请求返回422或其他4xx错误的旧版服务器现在也能连接——并让剩余安装环境也采用了新版客户端:Bedrock、Vertex、Foundry以及禁用遥测的安装环境,现在与HTTP服务器直接连接时,也默认使用v2 MCP客户端和MCP 2026-07-28协议协商,与其他安装环境的既有行为一致。设置MCP_SDK_GENERATION=v1或MCP_PROTOCOL_NEGOTIATION=legacy可退出这一默认行为。218

Stdio(本地服务器):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

在Windows上,stdio需要通过cmd包装:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

stdio协议默认值(v2.1.292)。所有安装环境中的本地(stdio)服务器连接,现在都默认协商2026-07-28版MCP协议,包括Bedrock、Vertex和Foundry;设置MCP_PROTOCOL_NEGOTIATION=legacy可退出此默认行为,让所有服务器继续使用旧版握手方式。如果stdio服务器忽略新版协议检查,系统会在一次缓慢连接后记住该情况7天,之后采用旧方式连接,避免等待。MCP文档现已说明,Claude Code默认会向stdio服务器请求该协议版本,而legacy会让所有服务器继续使用旧版握手方式。如果stdio通道服务器在升级后停止传递消息,文档指出:采用2026-07-28版协议的通道服务器,在v2运行时中不会被注册为通道;文档给出的解决办法是使用legacy。236237240

工具名称超过128个字符(v2.1.292)。MCP工具的名称如果超过128个字符,以前会导致每次请求都失败。现在会跳过该工具,并在MCP错误信息中指出其名称。236

作用域管理

MCP服务器分为三个作用域,优先级明确(本地覆盖项目,项目覆盖用户):

作用域 存储位置 可见范围 使用场景
本地 ~/.claude.json(项目路径) 仅您本人,仅当前项目 个人API密钥
项目 .mcp.json 通过git共享给整个团队 共享集成
用户 ~/.claude.json(根级别) 您本人的所有项目 个人工具

安装时指定作用域:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

配置文件格式

.mcp.json文件定义项目级服务器:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

环境变量使用${VAR}语法展开,也可指定默认值:${VAR:-default}。从v2.1.268起,解析后的值不再出现在展示界面中:/mcp和/plugin的服务器详情、claude mcp list和claude mcp get,以及MCP登录错误,都不再显示从${VAR}占位符解析出的秘密值;plugins和市场错误也不再回显嵌入git源URL中的令牌或密码。216

有一个type值专供另一类宿主使用:从v2.1.274起,.mcp.json、设置文件、plugins和代理文件中的"type": "sdk"条目会被跳过并显示警告——只有SDK宿主应用才能注册进程内服务器,因此CLI会话无法加载它们。218

MCP管理命令

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON
claude mcp login github              # Authenticate a server from the CLI (v2.1.186); --no-browser completes over SSH
claude mcp logout github             # Sign out of a server (v2.1.186)

# Within Claude Code REPL
> /mcp                               # Interactive MCP management
> /mcp reconnect all                 # Retry every failed or unauthenticated server (v2.1.284)

OAuth身份验证

对于需要OAuth的服务器:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

从v2.1.288起,当MCP服务器在工具调用期间请求更多OAuth权限范围时,Claude Code会显示重新进行身份验证的提示。234

使用MCP资源和提示词

引用资源:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

将MCP提示词用作斜杠命令:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

输出限制

Claude Code会限制MCP输出,防止上下文溢出: - 警告阈值:10,000个token - 默认最大值:25,000个token

如有需要,可提高限制:

export MAX_MCP_OUTPUT_TOKENS=50000

耗时较长的MCP调用自动转入后台(v2.1.212)。运行超过2分钟的MCP工具调用会自动转入后台,不再阻塞对话。会话可以继续工作,并在调用完成后获取结果。可通过CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS调整阈值(单位为毫秒)。189

服务器 用途 主要功能
GitHub 仓库管理 PR、议题、CI/CD、代码审查
PostgreSQL 数据库访问 查询、结构检查、数据分析
Sentry 错误监控 错误查询、堆栈跟踪、部署关联
Linear 项目管理 议题、项目、迭代
Jira/Atlassian 企业项目管理 工单、看板、工作流
Playwright 网页自动化 端到端测试、无障碍树
Stripe 支付 交易查询、客户数据
Cloudflare 基础设施 DNS、workers、分析
Supabase 后端即服务 数据库、身份验证、存储
Context7 文档 实时获取特定版本的库文档
Figma Dev Mode 设计转代码 图层层级、自动布局、设计令牌。Figma于2026年2月通过原生合作深化了与Claude Code的集成。35108
Sequential Thinking 问题求解 结构化推理、反思过程36
Magic UI 组件 React + Tailwind营销页面组件

实用MCP模式

GitHub工作流:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

数据库查询:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

错误监控:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

企业MCP配置

系统管理员可以通过managed-mcp.json强制实施MCP策略:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

位置: - macOS:/Library/Application Support/ClaudeCode/managed-mcp.json - Linux:/etc/claude-code/managed-mcp.json - Windows:C:\ProgramData\ClaudeCode\managed-mcp.json

拒绝列表具有绝对优先级。命令必须完全匹配,包括参数顺序。

managedMcpServers——托管设置现在可以提供服务器(v2.1.259):除了筛选用户配置的服务器,托管设置键managedMcpServers还可向每位用户提供HTTP/SSE MCP服务器,条目格式与.mcp.json一致。指定要运行的命令的条目会被跳过——托管配置仅支持远程服务器。设置文档尚未记录此键;其来源是CHANGELOG。211

allowedMcpServers作用范围变更——升级陷阱(v2.1.259):允许列表现在只管理用户添加的服务器。在v2.1.259之前,它也会筛选直接定义在managed-mcp.json中的服务器,因此,以前被允许列表排除的托管服务器会在升级后重新加载。请使用deniedMcpServers继续禁用它——拒绝列表仍然优先于一切其他设置。211

无法读取managed-mcp.json时默认阻止加载(v2.1.271):以前,无法读取或解析的企业managed-mcp.json会被忽略,用户、项目和plugins服务器会照常加载,仿佛没有任何策略。现在,该文件仍会保有对MCP的独占控制权(这些服务器不会加载),并在启动时发出警告,与v2.1.259为托管设置引入的故障时默认阻止行为保持一致。216

MCP Apps(2026年1月)

Anthropic推出了MCP Apps,这是模型上下文协议的一项扩展,可直接在Claude界面内提供交互式工具UI。71借助MCP Apps,用户无需离开Claude,即可查看、编辑外部服务的内容并与之交互,支持的服务包括Asana、Box、Canva、Figma、Hex、monday.com和Slack。任何MCP服务器都可以提供在Claude内部渲染的交互式UI。虽然MCP Apps目前出现在claude.ai网页界面中,但随着服务器采用新的交互能力,其底层MCP协议扩展也与Claude Code的MCP生态系统相关。

API平台:代码执行工具v2(2026年1月)

Anthropic推出了代码执行工具v2公开测试版,以Bash命令执行和直接文件操作取代了最初仅支持Python的沙箱。72主要变化: - 在沙箱容器中执行Bash命令(不再仅限于Python) - 使用任意语言编写和运行代码 - 程序化工具调用(同样处于公开测试阶段):Claude可在代码执行过程中调用工具,降低多工具工作流的延迟和token用量

v2工具主要影响API用户,但也体现了Claude Code云端执行能力的发展方向。


什么是 Subagents?

Subagents 是专门化的 Claude 实例,能够独立处理复杂任务。它们是 Claude Code 中最强大、却也最少被人理解的功能之一。掌握 subagents 能极大拓展您所能完成的工作范围。关于 Agent Teams、Subagents 与并行会话之间如何取舍,请参阅决策框架。

Subagents 为何存在: Claude Code 的主对话只有一个上下文窗口。您讨论的每句话、Claude 读取的每个文件、每条工具输出,全都会消耗这一上下文。在长会话中,上下文逐渐被填满,Claude 会忘记先前的决定,性能随之下降。Subagents 通过隔离工作来解决这一问题:探索结果不会让主对话膨胀,只有摘要会返回。Claude 会并发运行 subagents——自 v2.1.217 起默认同时运行 20 个(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS),超出的生成请求会排队等待。2194 自 v2.1.198(2026年7月1日)起,subagents 默认在后台运行——它们运行期间 Claude 继续工作,并在它们完成时收到通知。同一版本还让内置的 Explore agent 继承主会话的模型(上限为 Opus),而不再总是运行在 Haiku 上;此外,subagents 与上下文压缩现在都会继承会话的扩展思考配置,从而提升委派任务的质量。181

Subagents 的工作原理

当 Claude 遇到需要专注处理的任务(深度探索、多步分析、专项工作)时,可以生成一个 subagent。该 subagent:

  1. 从干净的上下文开始(不受主对话污染)
  2. 可以访问指定的工具
  3. 使用特定模型运行(通常更便宜、更快)
  4. 将结果返回主对话

这种架构既能防止上下文溢出,又能支持复杂的工作流。嵌套生成默认开启,深度为 3(v2.1.219)——subagents 可以生成自己的 subagents,最多向下三层;设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 即可关闭嵌套。196

请将这一默认值视为不稳定项,并显式设置它。 六周之内它已变动三次:

版本 默认深度 行为
v2.1.172(2026年6月10日) 5 引入递归扇出;一直保持到 v2.1.216
v2.1.217(2026年7月21日) 1 关闭嵌套——委派回到单跳
v2.1.219(2026年7月24日) 3 重新开启嵌套,深度三层
如果您的编排依赖于委派任务能够扇出多深——无论是因为需要递归,还是因为需要保证递归绝不发生——都应在设置中固定 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH,而不是沿用当前版本恰好附带的默认值。171194196

自 v2.1.186 起,当后台 subagent 遇到需要审批的工具时,提示会出现在您的主会话中,而不再被自动拒绝——对话框会显示是哪个 agent 在请求,按 Esc 仅拒绝该工具。在主回合结束后、后台 agents 仍在运行时,Esc 与 Ctrl+C 也保持响应。175

会话预算与权限继承(v2.1.212)。 两道防失控循环的护栏以每会话上限的形式落地:subagent 生成次数与 WebSearch 调用次数均默认为每会话 200 次,可分别通过 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 和 CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 调整;运行 /clear 会重置 subagent 预算。同一版本弃用了 Task 工具的 mode 参数——该参数现已被忽略,subagents 始终继承父会话的权限模式,因此生成的 agent 再也无法申请比启动它的会话更宽松的权限姿态。189 自 v2.1.290 起,交互式会话的 WebSearch 预算不再在 200 次调用后耗尽:它以每小时 100 次的速度补充,CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR 设定补充速率,设为 0 则关闭补充。发行说明将这一变更限定于交互式会话,并未说明它与 CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 如何叠加;10月6日获取的环境变量文档与工具参考文档仍描述为 200 次调用上限。235237

200 次生成的默认上限已在 v2.1.224 中移除。 长时间运行的会话——通宵循环、持续数天的后台 agents——会触及这一天花板,并在任务中途拒绝新的 agents,恰恰惩罚了最不需要该上限的那些会话;并发上限(20)与嵌套深度(3)仍然约束着同时运行的规模,而这才是防失控保护真正所在之处。如果您仍想设置生命周期总预算,该环境变量依然是重新施加预算的途径。201

并发上限与真正的预算强制执行(v2.1.217)。 第二道护栏将同时运行的 subagents 默认限制为 20 个,可通过 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 覆盖——单条消息再也无法无限制地扇出后台 agents。这两个上限各不相同:CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 限制会话的总生成次数(即 v2.1.224 后来移除的 200 默认值——设置它即可重新施加上限),而 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 限制同时运行的数量(20)。同一版本还修复了 --max-budget-usd 无法停止后台 subagents 的问题:一旦达到上限,新的生成请求会被拒绝,正在运行的后台 agents 会被停止——此前后台 agents 会在超出预算后继续消耗。194

Fork 与后台默认设置(v2.1.302)。 继承完整对话的 fork subagents(subagent_type: "fork")现已在 claude -p、Agent SDK、桌面应用和 VS Code 中默认开启,与终端中一直以来的情况一致;CLAUDE_CODE_FORK_SUBAGENT=0 可在所有环境中将其关闭,而 claude mcp serve 从不提供它们。桌面应用和 VS Code 现在始终像终端那样在后台运行主对话的 subagents,而不再由 Claude 自行选择;在 claude -p、SDK、桌面应用和 VS Code 中,subagent 自身发起的 Agent 调用默认在前台运行。10月17日获取的 sub-agents 文档与环境变量文档仍将 fork 模式描述为仅在交互式会话中开启。275276 v2.1.307 会告知同时启动的 fork subagents 哪一次启动属于自己,因此 forks 大大降低了互相接手对方工作的可能;环境变量页面现在将 fork 模式描述为默认开启。278279

动态工作流规模(v2.1.202 引入,v2.1.219 设定默认值)。 动态工作流——即通过 /workflows 编排、扇出数十至数百个后台 agents 的机制——采用的是建议性的规模指引,而非强制上限。v2.1.202 将其作为“Dynamic workflow size”/config 控件公开(小 / 中 / 大三档 agent 数量,或不限);v2.1.219 为其设定了默认值:中,向模型描述为“力求少于 15 个 agents”。 同一版本新增了 workflowSizeGuideline 设置键,使该指引可以从任意设置文件(用户、项目或托管)中设定;当某个设置文件提供了该值时,/config 中的对应行会自行隐藏。正在运行的工作流的状态行现在会显示当前默认规模,并附有指向 /config 的提示。由于该指引只是建议而非限制,真正的上限仍是 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 和 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS。182196

内置 Subagent 类型

Explore(快速、只读): - 模型:继承会话模型,上限为 Opus(v2.1.198 及之后;此前始终为 Haiku) - 模式:严格只读 - 工具:Glob、Grep、Read,以及安全的 bash 命令(ls、git status、git log、git diff、find、cat、head、tail) - 彻底程度级别:快速、中等、非常彻底 - 适用于:代码库探索、查找文件、理解结构

General-purpose(通用): - 模型:继承自主对话 - 模式:完全读写 - 工具:所有可用工具 - 适用于:复杂的研究 + 修改任务

Plan(规划): - 模型:继承自主对话(使用 opusplan 时为 Opus) - 模式:只读 - 工具:Read、Glob、Grep、Bash - 适用于:在执行前规划复杂的实现

触发 Subagents

Claude 会根据任务类型自动委派给 subagents。您也可以显式请求它们:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

专家提示: 对于复杂任务,请显式请求 subagent 委派。“用一个 explore agent 来查找……”这样的表述可防止主对话的上下文膨胀。

创建自定义 Subagents

在 .claude/agents/(项目级)或 ~/.claude/agents/(个人级)中定义 subagents:

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

配置字段:

字段 是否必需 选项 用途
name 是 小写字母加连字符 唯一标识符
description 是 自然语言 何时调用(加入“PROACTIVELY”可鼓励自动委派)
tools 否 逗号分隔 省略时继承全部工具。支持使用Agent(agent_type)限制可生成的agent类型(v2.1.63+;Task(...)仍可作为别名使用);自v2.1.299起,此处列出的MCP服务器仅提供其自身的工具,名称中包含__的服务器则以mcp__<whole name>__*的形式列出271
disallowedTools 否 逗号分隔 要拒绝的工具,会从继承或指定的列表中移除。自v2.1.178起,MCP服务器级别的规则(mcp__server、mcp__server__*、mcp__*)在此处可被正确匹配;早期版本会静默忽略这些规则,因此原本用于屏蔽某个MCP服务器的拒绝规则实际上毫无作用。173
model 否 sonnet、opus、haiku、inherit 默认为inherit(与主对话使用相同模型)。自v2.1.251起,此处显式设置的model:与每次生成时显式指定的模型一样,优先级高于CLAUDE_CODE_SUBAGENT_MODEL,后者现在仅用于设置默认值206;但若设置了v2.1.257引入的CLAUDE_CODE_SUBAGENT_MODEL_FORCE,则连这一设置也会被覆盖211
permissionMode 否 default、acceptEdits、delegate、dontAsk、bypassPermissions、plan 权限处理方式。delegate仅允许使用团队管理工具
maxTurns 否 整数 subagent停止前可执行的最大自主回合数。自v2.1.246起,达到上限的subagent会将其输出标记为部分结果返回,并提示可通过SendMessage继续,而不会显示为已完成249
memory 否 user、project、local agent的持久化记忆范围(v2.1.33+)
skills 否 逗号分隔 启动时自动将skill内容加载到subagent上下文中;自v2.1.295起,前32个不重复的名称会被预加载,每个仅加载一次,拥有Skill工具的subagent仍可调用其余skills238240
mcpServers 否 服务器名称或内联定义 此subagent可用的MCP服务器
hooks 否 Hook配置对象 仅作用于此subagent执行过程的生命周期hooks
background 否 true、false 始终作为后台任务运行(v2.1.49+)
isolation 否 worktree 在临时git worktree中运行,使用隔离的仓库副本(v2.1.49+)
experimental.cacheTtl 否 "5m"、"1h" 按agent设置的提示缓存TTL,在未配置subagent级TTL设置时生效;v2.1.242优先级链中的CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL和subagentPromptCacheTtl设置若已设定,仍然优先(v2.1.248+)206
omitClaudeMd 否 true、false 运行subagent时不加载用户、项目和本地CLAUDE.md文件;托管策略文件仍会加载。--agents的JSON中也接受此字段(v2.1.271+)216
autoCompactWindow 否 token数量 让此subagent早于主对话的窗口进行自动压缩;--agents的JSON中也接受此字段(v2.1.296+;sub-agents文档现已列出该字段,接受100000到1000000之间的值)238272
Subagent的effort级别(v2.1.316至v2.1.317)。subagent的effort级别依次取自:CLAUDE_CODE_EFFORT_LEVEL、每次调用时的effort参数(v2.1.292+)、agent定义中的effort字段,然后是CLAUDE_CODE_SUBAGENT_EFFORT(v2.1.316);后者用于设定在没有其他来源指定时subagents运行的级别,而不再继承会话的级别。若subagent或teammate使用的模型与主对话不同,则按该模型已保存的effort级别或其默认值运行,而非会话的级别(v2.1.317)。/tasks会显示每个subagent运行时所用的模型和effort级别。284285

限制可生成的subagent类型(v2.1.33+,v2.1.63重命名):tools字段支持Agent(agent_type)语法,用于限制某个agent可以生成哪些类型的subagent。例如,tools: Read, Grep, Agent(Explore)允许该agent直接使用Read和Grep,但只能委派给Explore类型的subagent。这一限制可防止受约束的agent过度委派。注意:在v2.1.63中,Task工具已重命名为Agent。设置和agent定义中现有的Task(...)引用仍可作为向后兼容的别名使用。106

通过CLI定义的Subagents(v2.1.32+)

启动时以JSON形式定义subagents,便于快速测试或自动化。这些subagents仅在当前会话中存在,不会保存到磁盘:89

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents标志接受的JSON与基于文件的subagents使用相同的frontmatter字段:description、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills和memory。自v2.1.281起,--agents除内联JSON外,还接受JSON文件的路径(配合-p使用),并允许prompt为空。224

Subagent的skill发现修复(v2.1.133+):早期版本存在一个bug:subagents无法通过Skill工具发现项目、用户或plugin级别的skills,因此生成的subagents只能看到全局skill目录。v2.1.133修复了这一问题;subagents现在会继承父会话可用的完整skill图谱。对于随agents一同发布任务专用skills的plugin作者来说,这一点尤为重要。160

管理Subagents

v2.1.198移除了/agents向导:可以请Claude创建或管理subagents,或直接编辑.claude/agents/中的文件。输入/agents会说明向导的去向,v2.1.281则从命令菜单和/help中移除了残留的“(removed)”条目。224

部分结果与按agent显示的模型(v2.1.243–246):/tasks和agent详情对话框会显示每个subagent运行时所用的模型和effort级别(v2.1.243)。在maxTurns上限处停止的subagent会将已产出的内容标记为部分结果返回,并提示可通过SendMessage继续,而不会显示为已完成(v2.1.246);请将部分结果视为检查点,而非最终答案。250249

CLI列表(v2.1.50+):无需启动交互式会话,即可从命令行列出所有已配置的agents:

claude agents                # Shows agents grouped by source (built-in, user, project, plugin)

Agent View(v2.1.139+):在当前版本中,claude agents还会打开Agent View,这是一个处于研究预览阶段的运维界面,可在一处集中调度和监控多个Claude Code会话。可用它查看哪些会话正在运行、被阻塞或已完成;但不要将该视图当作质量关卡。工作是否完成,仍由测试、审查和hook证据来决定。162自v2.1.287起,n:<text>过滤器可匹配会话名称和任务,处于激活状态的过滤器会在折叠的分区中显示匹配项,按Enter可打开第一个匹配项。从claude agents发送的回复会以排队消息的形式送达:在回合进行中发送的非/stop斜杠命令会在回合结束后执行,而内容恰为/stop的回复会立即停止该会话。232233v2.1.288新增Ctrl+F按名称查找会话,以及Alt+Up/Alt+Down在分组之间跳转;这两项以及重命名操作均可在keybindings.json中通过agents:find、agents:previousGroup、agents:nextGroup和agents:rename动作重新绑定;在n:过滤或Ctrl+F搜索之后按Enter,现在会打开名称匹配度最高的会话,而不是最顶部的一行。234237自v2.1.290起,从claude agents向忙碌的后台会话发送的/model、/effort和/rename会立即生效,而不是等到回合结束;正在等待/loop唤醒的后台会话在更新和内存不足时会保持运行,因为重启可能会悄然丢失该唤醒。235自v2.1.299起,在agent view中发送的/effort和/fast会设定新会话的初始值;在该界面单独输入/model、/effort或/fast会打开选择器;以--safe-mode启动的后台会话,其预览面板会显示一行安全模式提示。271

远程控制(v2.1.51+):claude remote-control子命令将您的本地环境提供给外部构建使用,使所有用户都能远程访问本地环境的功能:98

claude remote-control                      # Start serving local environment
claude remote-control --name "My Project"  # Custom session title visible in claude.ai/code (v2.1.69+)[^117]
claude remote-control --continue           # Resume the most recent Remote Control session (v2.1.229)[^224]
# --sandbox and --no-sandbox were removed in v2.1.300 (they never had an effect); set sandbox.enabled in settings instead[^281]

在后台运行代理

适用于长时间运行的任务:

> Run a thorough security review in the background

> /tasks   # Check status of running agents

之后可通过代理 ID 获取结果。

后台会话的工作成果会如何处理(v2.1.221)。 后台会话现在会提交并推送以保留工作成果,仅在任务确实需要时才开启草稿 PR(此前的行为是例行开启),遵循您 CLAUDE.md 中的 git 指令,并始终在结束时报告工作成果所在的位置——分支、提交或 PR。实际影响是:通宵运行的后台任务不再把输出遗留在未推送的工作树中,而您 CLAUDE.md 里的 git 约定(提交信息格式、分支命名、“永不推送到 main”)如今对后台会话与交互式会话同样具有约束力。如果您的 CLAUDE.md 对 git 未作任何说明,不妨在其中写明您的偏好,而不是等一个意外出现的草稿 PR 来告诉您默认行为是什么。199

Shell 端管理(v2.1.251): 后台会话子命令 claude attach <id>、claude logs、claude stop、claude respawn 和 claude rm 现已出现在 claude --help 中,而针对正在运行的后台会话,--resume 的提示信息会给出应运行的确切 claude attach <id> 命令。206 自 v2.1.290 起,claude attach 和 claude logs 可以用运行中会话名称的一部分代替 ID,例如 claude logs "auth refactor"。235237

跨会话消息传递(v2.1.224)

Claude Code 会话现在可以在您的任意机器之间互发消息(macOS 和 Linux;Windows 自 v2.1.239 起支持):ListAgents 按名称发现您的其他本地会话、云端会话以及派生的 subagents,SendMessage 则负责将消息送达。笔记本上的会话可以把一项发现直接交给台式机上长时间运行的会话,无需您在终端之间手动搬运。

Anthropic 为该功能提供了专门的文档页面;要点如下:259

查看内部机制。 /list-agents(别名 /peers)会列出所有可达的代理:当前会话中的 subagents、您的其他本地会话(包括后台会话),以及——在 Remote Control 已连接时——您在其他机器上的会话和云端会话。/status 新增一行 Peer address,显示会话自身的收件箱套接字(以 uds: 为前缀);每个 hook 和 Bash 命令都会通过 CLAUDE_CODE_MESSAGING_SOCKET 接收到它,该变量在任何 hook(包括 SessionStart)运行之前就已导出。会话以 /rename 或 --name 设定的名称响应,否则使用由目录派生的名称,例如 myapp-3f。自 v2.1.229 起,ListAgents 会将已断开的 Remote Control 会话标记为 offline,并将云端会话标注为 cloud。259257 v2.1.232 让名称成为一等公民: 在提示中输入 @ 即可提及另一个活跃会话,Claude 会通过 SendMessage 联系它;一个与某个活跃会话完全匹配的裸名称会直接送达,而不再要求您确认 [ref];同一机器上的交互式会话名称保持唯一——启动或重命名为已被占用的名称时,会得到一个 name-word-word 形式的变体并收到提示。接收端也有了可见的调节项:/config 中新增的 “Dialog expiry” 和 “Messages from your other sessions”(accept/hold/refuse)两行,取代了只能通过设置文件进行的控制。255

消息是什么。 即一个 Claude 写给另一个的纯文本——绝不包含对话历史、文件或权限。若要转移对话,请改为恢复该会话。接收方 Claude 会在回合进行中的工具调用之间读取它(正在运行的工具绝不会被中断),或在空闲时将其作为新回合读取;已送达的消息与手动输入的提示一样计入用量。259

收到的消息不能代为行动。 接收端受四条规则约束:消息无法批准待处理的权限提示;接收方 Claude 被明确要求绝不因另一个会话的请求而更改权限设置、CLAUDE.md 或配置;文本中的斜杠命令以普通文字形式到达,绝不会被执行;消息所请求的任何操作仍需经过接收会话自身的权限提示。259

入站控制。 每条到达的消息都会被送达、暂留或拒收。crossSessionInbound(accept / hold / refuse)用于设定策略;未设置时,Claude Code 会根据两个会话的权限模式类别逐条判断——绕过权限的会话归为一类,其余会话归为另一类,凡是消息会从一类跨入限制更严格的一方时,就会被暂留(会弹出提示的会话会暂留来自绕过型会话的消息;绕过型会话则暂留除同为绕过型会话之外的所有消息)。被暂留的消息会打开一个审批对话框,该对话框在五分钟后过期(dialogExpiry),且同时最多暂留 100 条。无头的 claude -p 会话同样会绑定收件箱套接字,但无法显示该对话框——被暂留的消息会一直处于暂留状态——因此需要接收消息的无人值守工作进程,应在自己的 --settings 中设置 crossSessionInbound: "accept"。Bare 模式会话不绑定任何套接字,因而不可达。259

空闲通知(v2.1.236)。 SendMessage 新增 notify_when_idle:请求本机上的另一个 Claude Code 会话在下次进入空闲状态时发送一次通知——需主动开启、仅触发一次、无需轮询(macOS 和 Linux)。投递结果如实反馈(v2.1.235–238): 超长消息会被预先拒收,而不是被静默丢弃;向拒收入站消息的会话(crossSessionInbound: "refuse")发送时会报告“已拒收”,而不是假装成功;收件箱因速率限制或队列已满而丢弃消息的接收方,现在会告知发送方。246 v2.1.239 补全了发现机制:ListAgents 会告知会话它自己的名称(即其他会话用来给它发消息的名称),列出在线的队友(此前可达的队友看起来像是不存在),而向自己的名称发送 SendMessage 时会直接说明,而不是报“no agent named …”。205 自 v2.1.247 起,来自其他会话的消息默认折叠为一行 Message from @<sender>: <first line> 预览;按 Ctrl+O 可展开完整正文。245

传输方式。 同一机器上的消息通过每个会话独立的 Unix 套接字传输,绝不经过 Anthropic 的服务器;可达性取决于文件系统可见性,因此容器内的会话与宿主机上的会话彼此不可见,而同一容器内的两个会话则可以互相看到。发往您其他机器或云端会话的消息则经由 Anthropic 的服务器路由。这类消息在 v2.1.225 之前仅限回复,该版本起 SendMessage 可以按名称主动与您的 Remote Control 会话发起对话(ListAgents 将其显示为 name [ref]);云端会话仍然仅限回复。202259 isolatePeerMachines: true 要求任何内容离开本机前都必须经您批准,即使在 bypassPermissions 下也不例外;任一设置作用域中的 true 都会生效——已签入版本库的项目文件可以收紧这条边界,但绝不能放宽它。259

脚本化收件箱。 由于套接字路径已被导出,hook、git hook 或 CI 包装脚本都可以向其所属会话的收件箱投递消息;在没有显式 crossSessionInbound 设置生效时,Claude Code 会验证来自自身子进程的消息并直接送达,不加额外手续。验证方式因平台而异——Linux(以及 WSL 2)即使在投递进程退出后仍可验证,macOS 仅在该进程运行期间可以验证,而 PID 为 1 的容器则完全无法验证,会回退到常规的入站规则。沙箱化的命令需要通过 sandbox.network.allowUnixSockets 放行该套接字。259

循环与限制。 重复消息按发送方进行速率限制,短时间内完全相同的重复消息会被丢弃,每个会话未读的已接受消息上限为 50 条——两个会话之间的消息循环会自行耗尽而终止。仅支持纯文本;结构化的代理团队协议消息只在团队内部流转。259 可用性陷阱。 这些缺口是分阶段补上的:Windows 于 v2.1.239 加入支持;自 v2.1.248 起,跨会话消息传递还可以在 Bedrock、Vertex 和 Foundry 上同一台机器的会话之间使用,并且在遥测被禁用时同样可用(CHANGELOG:“Added cross-session messaging (SendMessage / ListAgents) between sessions on the same machine on Bedrock, Vertex, and Foundry, and when telemetry is disabled”)——但要联系到您的其他机器,仍然要经过 Anthropic 的服务器。在 v2.1.248 之前,此功能依赖功能开关(feature flag)的评估结果,因此在较旧版本上,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DO_NOT_TRACK 或 DISABLE_GROWTHBOOK 中的任何一个仍可能悄无声息地将其关闭。206诊断方法:如果 /list-agents 不被识别,说明该会话缺少此功能;如果命令可用但消息始终送达不了,则问题范围更窄(拒绝规则、接收方的入站控制,或者对方是网页会话——网页会话仍然只能回复)。组织级总开关:在托管设置中拒绝 SendMessage 和 ListAgents,并加上 crossSessionInbound: "refuse"——需注意,拒绝 SendMessage 同时也会移除 subagent 和代理团队(agent team)的消息传递,而一个处于拒绝状态的会话在其对等方看来与平常无异。259

这一信任设计与 v2.1.222 的改动一脉相承:那次改动让自动模式下出站的 SendMessage 载荷经过权限分类器审查。跨会话流量的两个方向都要经过检查点,因为来自另一个会话的消息只是输入,而不是授权。201 v2.1.271 将同一原则应用到自动模式下的 subagent:subagent 通过一次由分类器审查的专用交回(hand-back)调用向调用方汇报,而不是在事后才审查它的最后一条消息。216

自托管运行器(Self-Hosted Runners,v2.1.224,Team/Enterprise)

claude self-hosted-runner 可以把您自己的机器或容器变成一个能够运行 Claude Code 网页版、移动版和桌面版会话的地方。云端界面不再绑定于 Anthropic 托管的环境:从 claude.ai 或手机上发起的会话,可以在您掌控的硬件上执行,使用您的网络访问、您的凭据和您的合规边界。对于代码仓库不能离开自身基础设施的团队来说,正是这一环让网页版和移动版界面真正可用。201自 v2.1.229 起,运行器会话会遵循服务器提供的 Claude Code hooks(与托管环境的行为一致),并且在 Windows 上启动时必须显式指定 --base-dir——Windows 上没有默认的检出目录。257自 v2.1.248 起,claude self-hosted-runner --client-label <label>(或 SELF_HOSTED_RUNNER_CLIENT_LABEL)可覆盖运行器注册时使用的标签——默认值是主机名。206自 v2.1.281 起,运行器以私有文件而非命令行文本的形式把系统提示词传给 Claude Code,因此较大的提示词不再导致启动失败;如果某个包装脚本或 command hook 会追加 --system-prompt 或 --append-system-prompt,就必须改用 --system-prompt-file 或 --append-system-prompt-file。224自 v2.1.299 起,claude self-hosted-runner orchestrator --shutdown-drain-sec <seconds> 会让 SIGTERM 停止轮询,并给正在进行的轮询和正在运行的 spawn hooks 最多这么多秒的时间来完成。271自 v2.1.311 起,只要您的主机持续修改 --hold-idle-file <path>(或 SELF_HOSTED_RUNNER_HOLD_IDLE_FILE)所指定的文件,空闲会话就会一直保留在运行器上;而 --max-hold-min <n> 会在达到指定分钟数后无论如何都将其释放(默认 1440;0 表示关闭保留)。284285自 v2.1.317 起,在运行器会话内部执行的 claude -p 不再与该会话共用会话 ID 和转录记录——此前这可能导致重启后恢复到错误的对话;CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 可恢复旧行为。在遇到 501 或 529 以外的 5xx 错误,或者心跳没有收到应答之后,运行器的下一次轮询和会话的连接都会重新建立,而不是复用已失败的连接(v2.1.317)。284官方文档现在以自托管环境(self-hosted environments)的名称介绍此功能(Team 和 Enterprise 的公开测试版,默认关闭):包括概述、快速入门、会话配置、生产部署、会话身份以及运行器参考。285

高级模式

链式 subagent:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

并行探索:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

可恢复的代理: 代理可以通过其 ID 恢复,以继续之前的工作:

> Resume agent abc123 and continue the analysis

异步 Subagents(2025年12月)

异步 subagent 为大规模项目带来了多任务处理和并行执行能力:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

异步代理最初通过统一的 TaskOutputTool 返回结果;v2.1.277 移除了这个已弃用的工具——Claude 现在改用 Read 工具读取后台任务的输出文件,taskOutputMaxChars 设置和 TASK_MAX_OUTPUT_LENGTH 环境变量也不再有任何效果。219

权限拒绝后的韧性(v2.1.0+)

从 v2.1.0 开始,subagent 在权限被拒绝后会继续工作,而不是完全停下来。当 subagent 撞上权限之墙时,它会自动尝试其他方法。这一改动让自主工作流更有韧性,也减少了人工介入的需要。40

Agent Teams(2026年2月,研究预览版)

Agent Teams(代理团队)用于协调多个 Claude Code 实例协同工作。其中一个会话充当团队负责人(team lead),派生出多个队友(teammates);队友各自在独立的上下文窗口中工作,并通过共享的邮箱和任务列表直接相互通信。7984

与 subagent 不同(subagent 在单个会话内运行,只向调用方汇报结果),队友是完全独立的会话,可以互相发消息、质疑彼此的发现,并自行协调。

启用:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或者通过环境变量:export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

架构:

组件 作用
团队负责人 创建团队、派生队友并协调工作的主会话
队友 处理所分配任务的独立 Claude Code 实例
任务列表 由队友认领并完成的共享工作项(带文件锁)
邮箱 用于代理间通信的消息系统
显示模式:
模式 方式 最适合
in-process(默认) 所有队友都在主终端中,用 Shift+Up/Down 选择。 任何终端
tmux / iTerm2 每个队友都在自己的分屏窗格中 可视化监控
在设置中配置:"teammateMode": "in-process" 或 "tmux"。也可以按会话指定:claude --teammate-mode in-process。

关键控制: - Shift+Down:在队友之间循环切换(in-process 模式;切过最后一个队友后会绕回到负责人) - Shift+Tab:启用委派模式(delegate mode;将负责人限制为只做协调,不改代码) - Ctrl+T:切换共享任务列表的显示 - 在队友上按 Enter:查看其会话;按 Escape 中断其当前回合

何时使用代理团队,何时使用 subagent:

Subagents Agent Teams
通信 只向上汇报结果 队友之间直接互发消息
协调 主代理管理全部工作 共享任务列表,自行协调
最适合 只关心结果的专注型任务 需要讨论与协作的复杂工作
Token 成本 较低 较高(每个队友 = 独立的上下文窗口)
最佳用例:
- 研究与评审(同时获得多种视角)
- 新模块/新功能(每个队友各自负责一部分)
- 以相互竞争的假设进行调试(并行验证不同的理论)
- 跨层协调(前端、后端、测试分别由不同的队友负责)

队友的计划审批: 对于复杂或有风险的任务,可以要求队友先规划再实施。队友会一直在只读的计划模式下工作,直到负责人审阅并批准其方案:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

主导代理(lead)会自主做出审批决定。您可以通过设定标准来影响其判断,例如“只批准包含测试覆盖的计划”或“拒绝修改数据库架构的计划”。

示例提示词:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Spawn a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

存储:团队配置位于~/.claude/teams/{team-name}/config.json(members数组,包含名称、代理ID和代理类型)。任务列表位于~/.claude/tasks/{team-name}/。任务支持依赖关系:被阻塞的任务会在其依赖项完成后自动解除阻塞。84

Hook集成:使用TeammateIdle(退出码2可发送反馈并让队友继续工作)和TaskCompleted(退出码2可阻止任务完成)这两个hooks,对队友实施质量门禁。

限制(实验性): - 进程内队友不支持会话恢复(/resume无法还原它们) - 每个会话只能有一个团队;不支持嵌套团队 - 队友无法创建自己的团队 - 分屏窗格需要tmux或iTerm2(不支持VS Code终端、Windows Terminal或Ghostty) - 所有队友启动时都继承主导代理的权限模式 - 消耗大量token:每个队友都是一个独立的Claude实例

Claude Tag(2026年6月):原生于Slack的同门产品

Claude Tag是一款独立的Anthropic产品,并非Claude Code的功能,但两者在托管代理方面的设计基因颇为相近,如果您在团队中使用Claude Code,就值得了解一下。Claude Code是由您亲自驱动的终端CLI,而Claude Tag则栖身于Slack:队友在频道中标记@Claude即可交接任务,代理会将任务拆分为多个阶段,独立完成各个阶段,然后将结果回传到频道。177

其设计面向多人协作,而非以单个用户为中心。整个公司在Slack中共用一个Claude身份,因此任何成员都可以接手其他成员发起的任务,或交出做到一半的工作,而不必各自维护私人对话。管理员可以限定Claude能访问哪些工具、数据源和记忆,以及可在哪些频道中使用,并可设置按频道和按组织的token消耗上限,同时提供活动日志。177

它运行于Opus 4.8,并于2026年6月23日面向Claude Enterprise和Claude Team客户推出。据Anthropic称,其自身的产品团队已经通过一个内部版本处理了大部分代码变更,比例约为65%。177

与Claude Code的关系:两者属于同一模型家族,具有相同的代理化工作方式,但界面形态和控制模型不同。Claude Code是开发者的本地CLI,配备hooks、MCP、skills和subagents;Claude Tag则是一个托管的、异步的、共享的代理,用于Slack中的团队协作。需要对编码会话进行细粒度的本地控制时,选择Claude Code;希望在团队现有工作流中拥有一位可委派任务的队友时,选择Claude Tag。

Agent Skills(2025年12月)

Agent Skills是由指令、脚本和资源组成的、经过组织的文件夹,代理可以动态发现并加载它们。24它们提供可组合、可移植的领域专业知识:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Skills与命令有所不同:命令需要显式调用,而skills会根据任务上下文自动激活。Claude Agent SDK(由Claude Code SDK更名而来)提供了构建支持skills的自定义代理的框架。25


什么是扩展思考模式?

扩展思考让Claude在回复之前有更多时间来推理复杂问题。对于架构决策、调试棘手问题以及需要仔细分析的任务,它尤为有价值。

当前状态

截至2026年9月的模型支持情况:在Opus 4.7及更高版本(含Opus 5.5)、Sonnet 5和Sonnet 5.5以及Fable模型上,自适应思考是唯一模式(在Claude Code中,Opus 5.5、Sonnet 5.5和Fable完全无法禁用思考);在支持的模型上,/effort的级别阶梯为low/medium/high/xhigh/max。下方2026年4月的快照予以保留,供其所描述的较旧模型参考。

Opus 4.7改变了Claude Code中推理的工作方式。Opus 4.7完全采用自适应推理——不再有固定的思考预算,MAX_THINKING_TOKENS和CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING对它不起作用。147取而代之的是,模型会根据任务复杂度,并在/effort设置的引导下,自行决定每一步是否思考以及思考多少。

在Opus 4.6和Sonnet 4.6上,旧版扩展思考系统仍然有效:思考默认开启,预算为31,999个token,可通过MAX_THINKING_TOKENS或/config调整。63设置CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1即可恢复到之前的固定预算行为。147

完全关闭思考(v2.1.166+)。对于默认思考的模型,MAX_THINKING_TOKENS=0、--thinking disabled标志以及按模型的思考开关现在会真正禁用思考,而不再被忽略。当您希望让原本总会思考的模型进行一次快速、不带推理的处理时,不妨使用此方式。263例外:Opus 5.5和Fable模型。在这些模型上无法关闭思考;会话开关、alwaysThinkingEnabled和MAX_THINKING_TOKENS=0均不起作用,模型会根据努力级别自行决定每一步的思考量。在第三方提供商上,MAX_THINKING_TOKENS=0会改为省略thinking参数,自适应推理模型可能仍会思考。223

努力级别: - 在Opus 4.7上,可用级别为low、medium、high、xhigh、max。在所有套餐和提供商上,默认值均为xhigh。 - 在Opus 4.6和Sonnet 4.6上,可用级别为low、medium、high、max。默认值为high,Pro和Max套餐上为medium。 - 如果设置了当前模型不支持的级别,Claude Code会回退到不高于该设置的最高支持级别(例如,xhigh在Opus 4.6上会以high运行)。147

“ultrathink”关键词会在上下文中添加一条指令,要求在该轮次进行更多推理。自v2.1.311起,在交互式终端中输入该词,对于通过Anthropic的API运行的Opus 5.5、Sonnet 5.5、Haiku 5.5和Fable 5.1,还会将该轮次提升到xhigh努力级别;在Claude工作期间输入,则会提升该轮次的剩余部分。该词只在能够提升努力级别的位置以彩虹色显示,因此在被引号包裹、位于路径内、出现在以/开头的提示中,或努力上限(CLAUDE_CODE_EFFORT_LEVEL、maxEffortLevel、组织限制)低于xhigh时,均不起作用。VS Code自v2.1.316起行为相同,CLAUDE_CODE_DISABLE_ULTRATHINK=1可关闭该关键词(v2.1.316)。在Amazon Bedrock以及其他该词无法提升轮次的提供商上,请改为设置努力级别。147284285

旧版说明:在v2.1.68中,第一方API上的Claude Code已移除Opus 4和Opus 4.1。固定使用这些模型的用户已自动迁移到Opus 4.6。109

支持的模型

  • Claude Haiku 5.5(仅自适应推理;无法关闭思考;v2.1.293+)239
  • Claude Opus 4.7(仅自适应推理;已移除固定思考预算)
  • Claude Opus 4.6(自适应思考 + 固定思考预算)
  • Claude Sonnet 4.6(自适应思考 + 固定思考预算)
  • Claude Opus 4.5(固定思考预算)
  • Claude Sonnet 4.5(固定思考预算)
  • Claude Haiku 4.5(固定思考预算)

控制扩展思考

会话中快速切换:

Press Alt+T to toggle thinking on/off

注意:Anthropic已将思考开关从Tab改为Alt+T,以避免误触发。32

通过/config: 进入/config → Extended Thinking(扩展思考),即可启用、禁用或调整预算。

环境变量(永久生效):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

禁用以节省成本: 对于不需要深度推理的简单任务,可以在/config中禁用思考或降低预算,以减少开销:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

思考Token预算

预算 使用场景
1,024(最小值) 简单推理任务
8,000 大多数编码任务(经济高效)
31,999(默认值) 复杂推理、架构决策
63,999(默认值的2倍) 详尽分析(需要显式设置)

成本考量:Anthropic将思考token按输出token计费。默认的31,999预算适用于大多数任务,但对于简单操作,可以通过降低预算或完全禁用思考来节省成本。

工作原理

启用思考后,Claude会进行内部推理,这些推理会影响答案,但不会出现在输出中。Claude Code会对思考内容加密,并通过signature字段返回以供验证。

在包含工具使用的多轮对话中,思考块必须传回API以保持推理的连续性。Claude Code会自动处理这一点。

何时考虑禁用或降低预算

扩展思考现已默认开启,但在以下场景中可以考虑降低预算或禁用: - 简单的文件编辑 - 常规重构 - 快速提问 - 代码格式化 - 成本会不断累积的大批量操作

缓存行为

思考参数变化时,Claude Code会保留系统提示缓存。但在轮次之间更改思考预算或启用状态,会使消息缓存失效。


输出样式

输出样式可自定义Claude呈现信息的方式,适用于学习、编写文档或满足特定团队偏好等场景。12

内置样式

样式 用途
Explanatory 附带推理过程的详细解释
Learning 讲解概念的教学式格式
Concise 最精简的输出,只保留要点

设置输出样式

> /output-style Explanatory
> /output-style Learning

或通过设置文件:

{
  "outputStyle": "Explanatory"
}

自定义输出样式

在.claude/styles/中创建:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

使用/output-style my-style调用。

弃用与恢复:/output-style在v2.1.73中被弃用,改由/config取代——并在v2.1.269中恢复:/output-style [name]可再次列出并切换输出样式,包括通过Remote Control以及在云端和其他无头会话中使用,这些场景下无法访问/config面板。115216

自v2.1.237起,Claude Code自带内置的“Concise”样式:Claude会先给出结果,省略开场白和过程叙述,同时工作依然同样细致周全。可在/config的Output style(输出样式)下选择。246


斜杠命令

斜杠命令可快速调用 Claude Code 的各项功能,并支持自定义工作流。对于常见操作,用斜杠命令比输入完整提示词要快得多。

自 v2.1.265 起,在提示词中间输入斜杠命令也会得到真正的建议列表:匹配项以列表形式显示,而非只给出单个建议;在非全屏模式下按 Tab 可打开该列表;插件 skill 也可以直接按其简名找到。215

内置命令参考

命令 用途 说明
/init 使用 CLAUDE.md 初始化项目 创建包含项目结构的记忆文件
/memory 管理自动记忆 查看和编辑自动记忆文件(v2.1.59+)
/copy 复制代码块 交互式选择器,可选取单个代码块或整段回复;选择“始终复制完整回复”后,后续调用将跳过选择器;按 w 键可将所选内容直接写入文件,在 SSH 环境下尤为实用;/copy N 复制倒数第 N 条助手回复(v2.1.59+,v2.1.63、v2.1.72、v2.1.77 增强)104114119
/context 查看上下文窗口用量 以可视化方式分项展示,并给出可操作的建议(v2.1.74+)116
/compact 压缩对话历史 可添加侧重点:/compact focus on tests
/usage Token 用量、费用及套餐用量 自 v2.1.118 起合并为一个对话框:/cost 和 /stats 成为输入快捷方式,分别打开对应的标签页。订阅用户可查看按模型和缓存命中率的分项数据(v2.1.92+);进度条不再与“Resets …”标签重叠(v2.1.119)。VSCode(v2.1.174+):“Account & usage”对话框新增归因视图,显示最近 24 小时或 7 天内的缓存未命中、长上下文、subagents,以及按 skill/agent/plugin/MCP 的分项数据;v2.1.236 为 Team 和 Enterprise 成员新增用量额度支出行(尚无支出时显示为 0% 上限);v2.1.243 新增 Loops 分项:按任务提示词归类、按总 token 数排序,为最耗资源的每个 /loop 或定时任务各列一行,展示触发频率、运行次数、总 token 数与单次 token 数以及最近一次运行,并统计其余任务的数量,让失控或过于频繁的循环一目了然(需要 v2.1.242+);v2.1.251 为使用带支出限额的 Claude apps gateway 的开发者新增支出限额进度条,并配有对应的 rate_limits.spend_limit 状态栏字段137152172246250247206;v2.1.299 新增针对最高 effort、工作流、常驻上下文和大型工具结果的警告271;v2.1.305 将每条警告转化为一行指明来源的修复建议,按 f 即可应用这些修复,它们同样出现在 VS Code 和 /doctor 中278279
/usage-credits 购买或申请额外用量 由 v2.1.144 中的 /extra-usage 更名而来。自 v2.1.248 起,通过 AWS Marketplace 计费的 Enterprise 组织、自助式 Enterprise 以及 Enterprise 试用版也可使用,成员可据此向管理员申请更高的用量上限;v2.1.251 修复了 $0 上限的情形(改为提示联系管理员,而不再声称已达到上限),并且在组织隐藏了该命令(DISABLE_EXTRA_USAGE_COMMAND)时,速率限制和用量提示不再推荐该命令206
/design 发布一个包含可编辑 UI 画板的画布 研究预览版(基于 artifacts 的 Claude Design 工作流):描述需求简报,选择一块画板,再交由 Claude 实现。面向 Pro/Max/Team/Enterprise,需要 v2.1.233+。独立版 Claude Design(claude.ai/design)将于2026年12月14日前关闭;自 v2.1.302 起,/design-sync 和 /design-login 会给出相应提示,云端会话则指向 claude.ai/design/settings 进行授权与撤销205275
/slides 以 artifact 形式创建 Claude Slides 演示文稿 运行时附上简报(/slides a quarterly review of the platform team's reliability work, for the engineering all-hands);若未提供,Claude 会先询问演示文稿的主题,再开始创建。模板(Slides、Design、Docs)目前处于 beta 阶段,在 Pro、Max 和 Team 上默认开启;在 Enterprise 上,需由 Owner 在 Organization settings > Artifacts 中逐一开启,Slides 模板关闭期间 /slides 不会显示。Claude Docs 则以 claude.ai 连接器的形式提供,而非命令283
/diff 全屏 diff 面板 v2.1.260:在全屏模式下于对话旁打开,随着 Claude 的编辑实时显示您尚未提交的更改;用 /diff 切换开关。该命令早于此面板存在,但此前一直未在本表中列出(其详情视图在 v2.1.149 中支持了键盘滚动,在 v2.1.222 中改为渲染原始 git blob,忽略 diff driver 和 textconv)212
/cost 输入快捷方式 → 打开 /usage 的费用标签页 v2.1.118 之前为独立命令;现在仍可作为快捷方式使用
/stats 输入快捷方式 → 打开 /usage 的统计标签页 v2.1.118 之前为独立命令;现在仍可作为快捷方式使用
/theme 管理已命名的自定义主题 可在选择器中创建并切换,也可手动编辑 ~/.claude/themes/*.json;plugins 可自带 themes/ 目录(v2.1.118+)152
/permissions 管理权限设置 交互式界面。v2.1.246 新增 Auto mode 标签页(仅在自动模式可用时显示),可按作用域查看和编辑分类器的 allow、soft_deny、hard_deny 和 environment 条目;托管条目和 --settings 条目为只读,编辑结果保存到 ~/.claude/settings.json,向某一部分添加第一条规则时会自动插入 "$defaults",以确保内置规则继续生效249247
/auto-mode-setup 让自动模式了解您的环境 引导式设置,会读取项目和近期会话,为 ~/.claude/settings.json 起草 autoMode.environment 条目(信任与敏感度槽位);同样适用于 Bedrock、Vertex、Foundry、Claude apps gateway,以及关闭遥测的情形(v2.1.304+)。参见 Max 上的自动模式278279
/mcp 配置 MCP 服务器 另有 /mcp enable、/mcp disable;/mcp reconnect all(v2.1.284)会重试所有连接失败或需要身份验证的服务器228
/hooks 查看 hook 配置 调试 hooks;自 v2.1.286 起,打开后直接显示您已配置的全部 hooks 的单一列表,并按事件分组231
/config 打开设置界面 完整配置
/resume 恢复已命名的会话 /resume <n> 或 /resume session-name。自 v2.1.304 起,当恢复一段不活跃的对话会消耗 5 小时用量限额中相当可观的一部分时,Pro 和 Max 套餐会显示警告,并提供改为开始新对话的选项278
/rename 为当前会话命名 /rename feature-auth
/branch 为对话创建分支 在不丢失上下文的前提下探索其他方案(v2.1.77 中由 /fork 更名而来)119
/fork 将对话复制到一个新的后台会话 v2.1.212 中被赋予新用途:副本会在 claude agents 中拥有自己的一行并独立运行;不再是会话内的别名189
/subtask 会话内分叉 旧版会话内 /fork 行为的新名称(v2.1.212)189
/clear 清除对话历史 重新开始
/powerup 交互式功能教程 通过动画演示讲解 Claude Code 的各项功能(v2.1.90+)135
/ide 连接 IDE VS Code/JetBrains 集成
/sandbox 启用沙箱模式 隔离
/status 查看会话状态 模型、设置等。v2.1.243 新增 Skipped sources 行,列出存在但因有更高优先级的托管来源生效而未被应用的托管设置来源,并新增一行显示云端会话(Pro/Max)是否已连接 GitHub,未连接时指向 /web-setup;自 v2.1.274 起,该行显示为“Cloud sessions”,这是取代“Claude Code on the web”的新产品用语;v2.1.278 新增 Auto mode server 行:当本会话的自动模式分类器在服务器端运行时显示 Enabled,一旦回退为计费的本地分类器请求则显示 Disabled250218219
/statusline 自定义状态栏 配置显示内容。v2.1.251 新增两个状态栏 JSON 字段:rate_limits.spend_limit(used_percentage 取值 0 到 100,超出限额后会大于 100,另有 resets_at;仅在使用带支出限额的 Claude apps gateway 时存在,且每个 rate_limits 窗口都可能各自缺失)和 prompt_cache 对象(命中率、未命中数、warm/cold、TTL;在主对话收到第一个 API 响应之前不存在;由 API 的缓存 token 计数计算得出,因此在所有提供商上均可用)206209
/model 切换 AI 模型 /model opus
/advisor 设置、显示或关闭 advisor 模型,即 Claude 在决策节点上咨询的服务器端第二模型(实验性) /advisor opus、/advisor off;自 v2.1.260 起在无头和桌面会话中以文本形式提供,自 v2.1.300 起支持 AWS 上的 Claude Platform274
/fast 切换快速模式 模型不变,输出速度约为2.5倍,价格为2倍(v2.1.36+)。适用于Opus 5.5(自v2.1.280起为默认模型,每百万token $8/$40)以及Opus 5和Opus 4.8($10/$50;Opus 4.8已于2026年10月30日弃用,将于2026年11月30日移除);v2.1.219已将Opus 4.7从快速模式中移除196198223284。自v2.1.271起可用于Remote会话(云端及自托管运行器)216
/output-style [name] 列出并切换输出样式 在v2.1.73至v2.1.268期间曾被弃用,由/config取代;v2.1.269恢复启用——可通过Remote Control使用,也可在云端及其他无头会话中使用115216
/agents 已在v2.1.198中移除 可请Claude创建或管理subagents,或直接编辑.claude/agents/;输入/agents会说明该向导的去向224
/skills 列出已安装的skills 提供即输即筛的搜索框,便于浏览较长的列表(v2.1.121+);skill描述仍限制在250个字符以内154
/skill-doctor 审计已加载的skills 显示哪些已加载的skills从未被使用,以及每个skill占用多少上下文,便于您进行精简(v2.1.261+)214
/bashes 列出后台任务 长时间运行的命令
/tasks 列出后台代理 监控异步任务。自v2.1.243起,每个subagent的行及详情对话框都会标明其运行所用的模型和推理强度250
/goal 设置完成条件 让Claude持续朝目标推进,直到条件得到满足(v2.1.139+)。自v2.1.234起,若目标因后台任务等待超过30分钟,系统会主动查看进展,而不会无限等待;当某一轮因不可恢复的错误而中止时,目标会自行清除并给出提示;自v2.1.246起,空闲会话针对长时间运行的后台工作,每个目标最多发起三次查看,您发送下一条消息后可再发起三次253249
/export 导出对话 保存记录
/add-dir 添加工作目录 扩展访问范围。自v2.1.257起,--add-dir、/add-dir和additionalDirectories会拒绝网络路径(Windows UNC共享、/net/<host>自动挂载)并给出提示;在Windows上,请先将共享映射为盘符211
/cd 将会话移至另一个工作目录 保留提示缓存(v2.1.169+)。自v2.1.246起,新目录的项目设置、hooks、.mcp.json服务器(仍需经过常规的批准提示)、skills和agents会在移动后立即生效,而无需等到--resume时262249
/web-setup 为云端会话连接GitHub 将本地的gh CLI令牌同步到您的Claude账户,使云端会话能够访问您的仓库;Team/Enterprise的Owner可通过“Quick web setup”开关将其禁用,零数据保留(Zero Data Retention)组织则无法使用此功能。v2.1.243新增了一条提示,引导尚未连接的claude.ai用户使用此命令,并在/status中增加了一行;v2.1.274更改了产品用语,/web-setup、/ultrareview和teleport消息现在使用“cloud session”而非“Claude Code on the web”250247218
/terminal-setup 配置终端 支持Kitty、Alacritty、Zed、Warp18
/login 在会话中进行身份验证 切换账户或重新认证。自v2.1.206起,支持通过Anthropic运营的公共网关端点登录;自v2.1.243起,Anthropic Console路径在创建API密钥之外,还提供无需密钥的“Sign in with your Console account”选项(推荐),适用于不允许使用API密钥的组织184250
/commit-push-pr 提交、推送并创建PR 自v2.1.206起,自动允许git push推送到已配置的推送远程(remote.pushDefault或唯一的远程),而不仅限于origin;自v2.1.229起,带有危险标志(--force、--amend、--no-verify等)的git/gh命令不再自动批准184257
/logout 在会话中退出登录 清除凭据
/doctor 全面的安装配置检查,可诊断并修复问题(v2.1.205;此前仅检查安装)。/checkup是其别名。/doctor prompt-audit(v2.1.283)会审计CLAUDE.md文件、skills、agents和命令中为旧模型编写的提示模式,优先指出过时的路径、过时的命令以及相互矛盾的指令文件226 健康检查
/bug 报告bug 向Anthropic提交问题。自v2.1.273起,报告仅包含最近一次API请求中的模型行为参数(模型、系统提示、工具)——请求元数据和CLAUDE_CODE_EXTRA_BODY字段将被省略217
/feedback 向Anthropic发送反馈 对于跨越当前会话的问题,可附上最近24小时或7天内的会话(v2.1.141+);自v2.1.247起,当会话中出现问题时,Claude可通过新的SendFeedback工具自行起草反馈报告,供您审阅后在此发送(可通过feedbackDrafts设置关闭);v2.1.273以与/bug相同的方式精简所附的请求数据——仅保留模型行为参数164245217
/release-notes 交互式发行说明 带变更日志的版本选择器(v2.1.92+)137
/rewind 返回检查点 撤销更改(或Esc×2)。v2.1.191:可从/clear之前的对话恢复。
/theme 管理主题 Ctrl+T切换语法高亮
/plugin 管理plugins 安装、更新、移除plugins
/passes 访客通行证(仅限Max) 分享3张Claude Code Pro试用通行证55
/voice 切换语音模式 按键通话,按住空格键说话(2026年3月)111
/claude-api Claude API skill 使用Claude API/Anthropic SDK构建应用(v2.1.69+)110。自v2.1.219起,该skill默认使用Claude Opus 5,并提供从Opus 4.8迁移的路径196(v2.1.280的发行说明未说明其现在是否默认使用Opus 5.5);自v2.1.247起,该skill新增cost-optimize(分析现有项目的Claude API开销,并逐一有据地调整各项成本杠杆——缓存、token精简、批处理、推理强度、模型选择),并覆盖Admin API:组织成员、邀请、工作区、API密钥、速率限制报告、工作负载身份联合、CMEK245 /claude-api api-version将Claude API代码迁移到API版本2026-10-21(v2.1.307),managed-agents-secure [<agent-id>]则报告Managed Agent的设置与Anthropic安全部署指南的一致与差异之处,但不做任何更改(v2.1.304)278279
/reload-plugins 重新加载plugins 无需重启即可应用plugin更改(v2.1.69+)110。自v2.1.268起已很少需要:通过/plugin进行的安装、启用和禁用会在关闭菜单时生效216
/security-review 安全审查 审查代码中的漏洞(v2.1.70修复了git兼容性)109
/color 设置提示符颜色 为当前会话设置提示栏颜色。使用/color default/gray/reset/none恢复默认。所有用户均可使用(v2.1.75+)117
/code-review [effort] 正确性审查 在v2.1.147中由/simplify更名而来;按可选的推理强度报告正确性bug,并支持--comment在GitHub PR中添加行内评论。169自v2.1.215起,Claude不再自行运行/verify和/code-review这两个skills——只有在您显式调用时才会触发。191自v2.1.218起,/code-review以后台subagent的形式运行,审查工作不再占用您的对话;堆叠的斜杠命令仍是其审查目标。195自v2.1.223起,/review仅是/code-review的别名(审查当前diff或某个PR),结束了v2.1.202引入的双命令分裂——深度云端审查请使用/code-review ultra。该命令还会记住您上次输入的推理强度:直接输入/code-review会沿用该强度,/code-review high则会更改它。200自v2.1.288起,--max-findings <n>或--max-findings all可报告多于或少于常规上限的发现,后续审查会沿用该选择,直到您传入--max-findings default。234237自v2.1.290起,在没有专门调优审查设置的模型(包括Opus 5.5和Sonnet 5.5)上,中等强度的审查也会报告清理项和CLAUDE.md约定方面的发现。235
/deep-research 多来源研究报告 内置的研究skill。自v2.1.218起,仅在您调用时才会启动——Claude不再自行启动它,与v2.1.215对/verify和/code-review采用的显式调用规则相同。195
/batch 批量操作 内置斜杠命令(v2.1.63+)104
/team-onboarding 生成团队成员上手指南 根据您本地的CC使用模式创建入职指南(v2.1.101+)143
/effort 设置 effort 级别 将模型 effort 设为 low/medium/high/xhigh/max。对于 API 密钥、Bedrock/Vertex/Foundry、Team 和 Enterprise 用户,默认值已从 medium 改为 high(v2.1.94+);/effort ultracode 让 Claude 编排动态工作流——自 v2.1.284 起,它成为一个独立开关,保留当前的 effort 级别,而此前会强制设为 xhigh(--effort ultracode 标志,v2.1.203+,仍从 xhigh 起步);自 v2.1.251 起,默认 effort 级别按模型保存,切换模型时各模型保留各自的设置;v2.1.257 新增 s 用于仅本会话生效的选择(与 /model 一致),并使 --effort 标志仅在会话内生效——不再持久保存140247206211228
/loop 周期性任务 /loop 5m /foo 按固定间隔运行提示词;默认间隔为 10m。适合轮询部署、看护 PR 或定期检查(v2.1.71+);自 v2.1.243 起,/usage 显示 Loops 明细(每个循环的运行次数、token 数、上次运行时间),便于发现失控的循环,连续的空操作唤醒会折叠为终端中的一行;v2.1.248 使自主节奏的动态模式和无提示词的自主默认模式始终可用,包括在 Bedrock/Vertex/Foundry 上112250206
/schedule 创建或管理云端计划任务(原称 routine) 可对话式创建,也可内联:/schedule daily PR review at 9am、/schedule clean up feature flag in one week;/schedule update 设置 cron 表达式;/routines 是其别名。需要已启用云会话的 claude.ai 登录,因此在使用 API 密钥或云服务商登录、处于云会话内,以及 Owner 关闭了计划任务时,该命令会被隐藏;从 CLI 添加 GitHub 触发器需要 v2.1.225 或更高版本。请参阅「Claude Code on the Web」下的 Cloud Scheduled Tasks(云端计划任务)282
/buddy 终端伴侣宠物 住在终端里的电子宠物风格 ASCII 宠物。18 个物种,5 个稀有度等级(普通 60%、非凡 25%、稀有 10%、史诗 4%、传说 1%)。由账户 ID 确定性生成——您的宠物始终不变。它会观察对话并通过气泡发表评论。需要 Pro 订阅(2026年4月1日)138
### 创建自定义命令
在 .claude/commands/(项目级)或 ~/.claude/commands/(个人级)中创建可复用的命令:
---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

保存为 .claude/commands/security-review.md,通过 /security-review 调用。

命令 Frontmatter 选项

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---
选项 用途
description 帮助文本及自动委派匹配
allowed-tools 限制可用的工具
model 为此命令覆盖模型。自 v2.1.259 起在交互式会话中生效(此前在该场景下被忽略);在 auto 模式下,若 frontmatter 指定的模型是当前会话无法使用的,该轮不再以此运行——会话继续使用自身的模型211
argument-hint 说明预期的参数
disable-model-invocation 阻止通过 SlashCommand 工具调用
### 参数插值
所有参数作为单个字符串:
---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

用法:/fix-issue 123

编号参数:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

用法:/create-component Button functional

内联 Bash 执行

在命令提示词中执行 bash 命令:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

文件引用

在命令中包含文件内容:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

命令命名空间

将命令组织到子目录中:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

同名命令会在帮助中显示其命名空间:/test (project:backend) 与 /test (project:frontend)。


skills如何工作?

skills为扩展Claude Code提供了一种截然不同的方式。与需要显式调用的斜杠命令不同,skills由模型调用:Claude会根据上下文自动发现并使用它们。您将领域专业知识融入skill后,Claude就会在需要时运用这些知识,无需您记得主动提出要求。

为什么skills会带来根本性变化:以领域专业知识为例:支付处理规则、合规要求,以及团队经过多年打磨的架构模式。没有skills时,您要么在每次会话中重新解释这些背景,要么寄希望于Claude从代码注释中自行推断。有了skills,只需编写一次。Claude就会读取skill定义,并在相关场景中自动运用这些专业知识。初级开发者无需主动询问,就能获得资深开发者级别的指导。安全规范也能自动落实,无需记得手动调用。

这一区别至关重要。斜杠命令是需要您记得使用的快捷方式,而skill是Claude随时可用的知识。当您创建一个包含团队特定漏洞模式和合规要求的安全审查skill时,Claude只要遇到相关代码,就会运用这些专业知识,无论是在PR审查、重构,还是其他涉及安全的任务中。您无需调用/security-review;Claude会识别上下文并自动应用该skill。

skills、命令与subagents的区别

了解各种扩展机制的适用场景,有助于避免重复建设,并充分发挥各自的作用:

维度 斜杠命令 skills subagents
调用方式 用户调用(/command) 模型调用(自动) 显式或自动委派
触发条件 您记得使用 Claude识别上下文 任务需要委派
结构 单个Markdown文件 包含资源的目录 带有frontmatter的Markdown文件
上下文 主对话 主对话 独立的上下文窗口
复杂度 简单提示词 多文件能力 完整的智能体角色设定
最适合 显式操作 领域专业知识 复杂任务委派

使用斜杠命令来显式控制操作:/deploy、/test、/review PR 456。由您决定何时运行。

使用skills来自动应用专业知识:安全模式、代码风格规范、特定领域知识。由Claude决定何时应用。

使用subagents来隔离任务:后台探索、并行分析,以及不应干扰主对话的专门推理。

skill的结构与位置

skills存放在专用目录中,必须包含一个SKILL.md文件,也可以包含辅助资源:

个人skills(可在您的所有项目中使用):

~/.claude/skills/
├── code-reviewer/
│   ├── SKILL.md
│   ├── SECURITY_PATTERNS.md
│   └── PERFORMANCE_CHECKLIST.md
├── sql-analyst/
│   ├── SKILL.md
│   └── QUERY_PATTERNS.md
└── api-designer/
    └── SKILL.md

项目skills(通过git与团队共享):

.claude/skills/
├── domain-expert/
│   ├── SKILL.md
│   ├── BUSINESS_RULES.md
│   └── DATA_MODELS.md
└── deployment/
    ├── SKILL.md
    └── RUNBOOKS.md

项目skills会提交到版本控制系统。团队成员拉取代码后,即可自动获得这些skills,无需安装或配置。自动分发让整个团队都能使用统一的专业知识。

v2.1.275引入了第三种来源:在claude.ai账户中启用的skills会同步到使用该账户登录的终端会话,claude.ai中的plugins也会同步。可通过syncClaudeAiSkills: false关闭skills同步(plugins则使用syncClaudeAiPlugins: false)。同步后的skills仍归账户所有——编辑已同步账户skills文件夹中的文件,只会修改本地副本。Write/Edit结果会说明更改尚未保存到账户,并告知保存方法。218

anthropic-skills名称已被保留(v2.1.282)。同步的skills位于anthropic-skills命名空间中,因此在plugin之外,名为anthropic-skills或anthropic-skills:<name>的skill文件夹、命令文件或已保存工作流将不再加载,启动提示会指出第一个需要重命名的项目。同名plugin仍会加载,但在/anthropic-skills:<name>下发生名称冲突时,同步的skill优先。同名的MCP服务器会保留其工具,但在重命名前不会列出任何skills或提示词。Skill(anthropic-skills:*)允许规则仅适用于从claude.ai同步的skills。v2.1.282曾以相同方式保留claude-ai;v2.1.283撤销了这部分更改,因此名为claude-ai的项目可以重新加载。225226227

SKILL.md格式

每个skill都需要一个带有YAML frontmatter的SKILL.md文件:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review or audit code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Analysis

When reviewing code, check for:

### Input Validation
- All user input sanitized before use
- Parameterized queries for database operations
- Output encoding for rendered content

### Authentication & Authorization
- Session tokens properly validated
- Permission checks before sensitive operations
- No hardcoded credentials or API keys

### Data Exposure
- Sensitive data not logged
- PII properly masked in error messages
- API responses don't leak internal details

## Performance Patterns

### Database
- N+1 query detection
- Missing indexes on filtered columns
- Unbounded result sets

### Memory
- Large object lifecycle management
- Stream processing for big files
- Connection pool exhaustion risks

## Review Output Format

For each finding:
- **File**: path/to/file.ts:123
- **Severity**: Critical | High | Medium | Low
- **Category**: Security | Performance | Maintainability
- **Issue**: Clear description of the problem
- **Recommendation**: Specific fix with code example
- **Rationale**: Why this matters

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for detailed vulnerability patterns.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for optimization guidelines.

frontmatter参考

字段 必填 约束 用途
name 是 小写字母、数字、连字符;最多64个字符 唯一标识符
description 是 最多1024个字符 发现触发条件:Claude据此决定何时应用该skill
allowed-tools 否 以逗号分隔的工具名称 限制Claude使用此skill时的能力
context 否 fork 在隔离的上下文中运行skill(v2.1.0+)。避免对主智能体状态产生副作用。40从v2.1.218起,context: fork skills默认在后台运行。195
background 否 true / false 关闭context: fork skill的后台执行:background: false使其保持在前台运行。仅对context: fork有效,该模式默认在后台运行(v2.1.218+)。195
model 否 模型别名或ID 使用指定模型运行该skill的回合。从v2.1.259起,此字段在交互式会话中生效(此前会被忽略);在自动模式下,如果frontmatter指定了不受支持的模型,该回合将不再使用该模型运行,而是继续使用会话原有模型211
effort 否 low / medium / high / xhigh / max 以指定的推理投入级别运行该skill的回合(v2.1.80+)。从v2.1.267起,对于默认推理投入级别固定的模型(Opus 4.7、Opus 4.8、Fable 5),此字段也会生效,此前会被忽略;该修复同样适用于自定义命令和subagents216

字符串替换(v2.1.9+):skills可以通过${CLAUDE_SESSION_ID}替换访问会话上下文。适用于日志记录、追踪或生成会话专属输出。44

description字段至关重要。Claude会将您的请求与skill描述进行匹配,从而发现适用的skills。描述含糊不清,Claude就无法判断何时使用该skill。描述具体、触发条件明确,才能可靠地激活。

欠佳的描述:

description: Helps with code

有效的描述:

description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review, audit, or check code.

有效的描述包括: - skill的作用(审查代码中的特定问题) - 使用时机(检查变更、PR、质量分析) - 触发短语(审查、审计、检查)

工具限制

allowed-tools字段限定了skill启用时Claude可以执行的操作。对于只读或限定范围的skills,工具限制必不可少:

---
name: security-auditor
description: Audit code for security vulnerabilities without making changes
allowed-tools: Read, Grep, Glob
---

采用此配置后,Claude可以分析代码,但不能编辑文件、运行bash命令或进行修改。该skill强制执行只读行为。

常见的限制模式:

模式 工具 使用场景
只读分析 Read, Grep, Glob 安全审计、代码审查
安全探索 Read, Grep, Glob, Bash(git log:*), Bash(git diff:*) 历史记录分析
文档编写 Read, Grep, Glob, Write 生成文档而不编辑源代码
完全访问 (省略此字段) skill继承所有可用工具

辅助文件

skills可以包含多个文件。Claude会在激活时读取主文件SKILL.md,随后按需访问辅助文件,通过渐进式披露高效管理上下文。

结构模式:

my-skill/
├── SKILL.md           # Required: overview + quick reference
├── DETAILED_GUIDE.md  # Deep documentation
├── EXAMPLES.md        # Concrete examples
├── PATTERNS.md        # Reference patterns
├── templates/         # Reusable templates
│   └── component.tsx
└── scripts/           # Helper utilities
    └── validate.py

从SKILL.md引用辅助文件:

For detailed security patterns, see [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).

Use this template for new components:
@templates/component.tsx

Validate configurations with:
```bash
python scripts/validate.py config.json
```

专家提示:将必需信息直接放在SKILL.md中,把深入的参考资料放在辅助文件中。Claude会立即读取SKILL.md,但只会在需要时访问辅助文件。如果关键信息藏在辅助文件里,Claude可能无法找到。

完整示例:领域专家skill

以下是一个适用于金融科技应用、达到生产级质量的skill:

目录结构:

.claude/skills/payments-domain/
├── SKILL.md
├── BUSINESS_RULES.md
├── COMPLIANCE.md
└── DATA_MODELS.md

SKILL.md:

---
name: payments-domain
description: Expert knowledge of payment processing domain including transaction flows, compliance requirements, and business rules. Use when working with payment code, transaction handling, refunds, disputes, or financial calculations.
---

# Payments Domain Expertise

## Core Concepts

### Transaction States
```
PENDING → AUTHORIZED → CAPTURED → SETTLED
                    ↘ VOIDED
         AUTHORIZED → DECLINED
CAPTURED → REFUNDED (partial or full)
SETTLED → CHARGEBACK → REPRESENTED
```

### Money Handling Rules
- ALL monetary values stored as integers (cents, not dollars)
- Currency always explicitly tracked (never assume USD)
- Rounding: HALF_EVEN for calculations, HALF_UP for display
- Never use floating point for money

### Idempotency Requirements
Every payment operation MUST be idempotent:
```typescript
// Required pattern
async function processPayment(idempotencyKey: string, amount: number) {
  const existing = await findByIdempotencyKey(idempotencyKey);
  if (existing) return existing; // Return cached result

  const result = await executePayment(amount);
  await storeWithIdempotencyKey(idempotencyKey, result);
  return result;
}
```

## Quick Reference

### Fee Calculations
- Interchange: 1.5% + $0.10 (debit), 2.1% + $0.10 (credit)
- Platform fee: 2.9% + $0.30 (standard), 2.2% + $0.30 (enterprise)
- International: +1% cross-border fee
- Currency conversion: mid-market rate + 1%

### Compliance Thresholds
- $3,000: Enhanced due diligence trigger
- $10,000: CTR filing required
- $25,000: Additional verification required

### Refund Windows
- Full refund: 120 days from capture
- Partial refund: 180 days from capture
- Chargeback window: 120 days (Visa), 180 days (Mastercard)

## Key Files

- `src/payments/processor.ts` - Core payment logic
- `src/payments/refunds.ts` - Refund handling
- `src/compliance/aml.ts` - AML checks
- `src/models/transaction.ts` - Transaction model

See `BUSINESS_RULES.md` for detailed business logic.
See `COMPLIANCE.md` for regulatory requirements.
See `DATA_MODELS.md` for schema documentation.

配置好此skill后,当您处理交易代码、询问退款逻辑或调试支付流程时,Claude会自动运用支付领域的专业知识。无需调用任何内容,这些专业知识随时可用。

创建有效的skills

从描述入手。先写描述,再围绕描述构建skill内容。描述决定了Claude何时使用该skill,因此务必写准确:

  1. 说明skill提供的能力
  2. 列出具体的触发条件
  3. 包含相关关键词和短语

让skills保持专注。一个skill只覆盖一个领域或一种能力:

好(职责明确) 差(范围过广)
security-auditor code-helper
react-patterns frontend-stuff
postgres-optimization database-expert
api-documentation docs-generator

如果一个skill试图覆盖太多内容,其描述就会变得含糊,Claude也就无法可靠地判断何时使用它。

采用渐进式披露。将最重要的信息直接放在SKILL.md中,通过引用辅助文件提供深入内容:

## Quick Reference
[Essential patterns here - Claude sees this immediately]

## Deep Dive
For full coverage, see [DETAILED_GUIDE.md](DETAILED_GUIDE.md).

提供具体示例。抽象描述不如具体模式实用:

## Input Validation

### Pattern
```typescript
// Good: Explicit validation with typed errors
const validated = PaymentSchema.safeParse(input);
if (!validated.success) {
  throw new ValidationError(validated.error.issues);
}

// Bad: Implicit coercion
const amount = Number(input.amount); // Silent NaN on invalid input
```

使用真实请求进行测试。创建skill后,测试Claude是否会激活它:

> Review this payment processing code for issues
# Should activate payments-domain skill

> How should I handle refunds?
# Should activate payments-domain skill

> What's the weather like?
# Should NOT activate payments-domain skill

如果Claude未按预期激活skill,请修改描述,加入您实际使用的触发短语。

团队共享策略

基于Git共享(推荐用于项目skills):

# Add skill to project
mkdir -p .claude/skills/team-standard
# Create SKILL.md and supporting files

# Commit
git add .claude/skills/
git commit -m "Add team coding standards skill"
git push

# Teammates get it automatically
git pull
claude  # Skill now available

通过符号链接跨项目共享:

# Create canonical skill location
mkdir -p ~/shared-skills/security-reviewer
# Create SKILL.md

# Symlink into projects
ln -s ~/shared-skills/security-reviewer ~/.claude/skills/security-reviewer
# Now available in all your projects

通过plugins分发: 如需扩大分发范围,可将skills打包到plugins中:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

用户安装plugin后,即可使用其中附带的skills。

skills管理改进(v2.1.304-309)。现在,上下文压缩完成后会再次向Claude发送skill列表,而/reload-skills只发送新增或更改的skills(v2.1.304)。来自同一来源(代码仓库、个人文件夹或plugin)的skills,每个会话最多可注册1,024个hooks,匹配器字符总数上限为16,384;某个skill的once hook也不再移除其他skill中相同的hook。如果策略只允许来自plugins的hooks,那么hooks被排除的skill将不再获得其allowed-tools权限。位于--add-dir文件夹中的skill,如果名称已被其他skill占用,将以<folder>:<name>的形式提供(v2.1.309)。278279

调试skills

skill未激活:

  1. 检查描述是否与您的请求匹配: yaml # If you're saying "check this code" but description says "review" description: Review OR check code for issues...

  2. 确认文件位置: ```bash # Personal ls ~/.claude/skills/my-skill/SKILL.md

# Project ls .claude/skills/my-skill/SKILL.md ```

  1. 验证YAML frontmatter:
  2. 第一行必须严格为---
  3. Markdown正文之前必须有结束标记---
  4. YAML中不能使用制表符(请使用空格)
  5. 名称字段只能使用小写字母和连字符

  6. 以调试模式运行: bash claude --debug # Watch for skill loading messages

skill意外激活:

缩小描述的适用范围。如果skill在不该激活时被激活,说明描述过于宽泛:

# Too broad - activates on any "code" mention
description: Help with code

# Specific - activates only for security contexts
description: Audit code for security vulnerabilities including injection attacks, authentication flaws, and data exposure. Use when specifically asked about security, vulnerabilities, or when reviewing code for security issues.

找不到辅助文件:

  • 使用相对于SKILL.md所在位置的路径
  • 只使用正斜杠(即使在Windows上也是如此)
  • 检查文件是否确实存在:ls .claude/skills/my-skill/REFERENCED.md

何时创建skill

在以下情况下创建skill: - 需要自动应用领域专业知识 - 多名团队成员需要相同的知识 - 您反复解释相同的模式或规则 - 需要无需显式调用即可注入上下文 - 知识分散在多个文件中,需要加以组织

在以下情况下不要创建skill: - 您希望显式控制调用(使用斜杠命令) - 任务需要独立的上下文(使用subagent) - 只是一次性提示词(直接输入即可) - 所谓的“skill”实际上只是单个模板(使用斜杠命令)

专家提示:如果您发现自己每次处理身份验证代码前,都要输入/security-review,不妨将其转换为skill,让专业知识随时自动发挥作用。如果希望显式调用,则保留为命令。


Plugin 系统

Plugins 将 Claude Code 扩展打包以供分发。一个 plugin 可以包含自定义命令、subagents、skills、hooks 和 MCP 服务器。Anthropic 于2025年12月正式推出 plugin 市场,首批包含36个精选 plugins。40

Plugin 结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required: metadata
├── bin/                          # Executables invokable as bare commands (v2.1.91+)[^143]
├── commands/                     # Slash commands
│   └── hello.md
├── agents/                       # Subagents
│   └── helper.md
├── skills/                       # Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                        # Event handlers
│   └── hooks.json
└── .mcp.json                     # MCP servers

Plugin 清单

最简 plugin.json:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

v2.1.129 清单说明:themes 和 monitors 现在应在清单的 "experimental" 对象下声明。现有的顶层声明仍然有效,但 claude plugin validate 会发出警告,以便 plugin 作者在发布前完成迁移。156 自 v2.1.259 起,claude plugin validate --json 会将验证结果输出为 JSON。211

v2.1.281 验证:claude plugin validate 现在还会检查 MCP 服务器,报告加载时会被静默丢弃的 .mcp.json 条目、未声明的 ${user_config.*} 引用以及不安全的 URL。当 shell 形式的 hook 未用引号包裹 ${CLAUDE_PLUGIN_ROOT} 时,它也会发出警告,因为 plugin 路径包含空格时会导致命令失效;plugin hook 失败错误现在还会指明出错的 plugin。224

Plugin 管理

> /plugin                              # Interactive interface
> /plugin install name@marketplace     # Install
> /plugin install name --marketplace <source>  # Install, offering to add the marketplace first (v2.1.275+)
> /plugin enable name@marketplace      # Enable
> /plugin disable name@marketplace     # Disable
> /plugin uninstall name@marketplace   # Remove
> /plugin marketplace add ./local      # Add local marketplace
> /plugin marketplace list             # View marketplaces

对于一次性测试,v2.1.129 新增了一个会话标志,可以直接获取 plugin zip,而无须将其安装到常规市场状态中:

claude --plugin-url https://example.com/my-plugin.zip

自 v2.1.128 起,--plugin-dir 也接受 .zip plugin 归档,因此本地冒烟测试既可以指向 plugin 目录,也可以指向归档。156 自 v2.1.265 起,它还接受一个 plugins 文件夹:其中每个包含清单的子文件夹都会作为独立 plugin 加载,会话运行期间新增或移除的子文件夹也会被自动识别。215

如果要在不使用 git 或 npm 的情况下进行永久安装,v2.1.224 新增了 archive plugin 源:让市场条目指向通过 HTTPS 提供的 zip,并可选择固定 SHA-256;如果归档在您不知情的情况下发生变化,安装便会失败。现在,3种分发路径各司其职——--plugin-url 用于单次会话,archive 用于从 URL 固定安装,市场则适用于任何具有更新生命周期的内容。对团队而言,固定哈希尤为重要:它将“信任该 URL 今天提供的任何内容”转变为“信任我们审核过的确切字节”。201

v2.1.221 带来了3项易用性改进:/plugin install 在报告找不到 plugin 之前,会刷新过期的市场目录并重试(市场刚添加某项内容后出现的“找不到”问题已不复存在);通过 /plugin 安装的 plugins 会在安全的情况下立即激活,不再一律要求运行 /reload-plugins;plugin 清单还可以将 skills 指向 ".",从 plugin 根目录提供 skills——对于根目录中的 SKILL.md,验证错误现在会直接给出这一建议。199 v2.1.268 将这套体验补充完整:在 /plugin 中安装、启用或禁用 plugin 后,关闭菜单即可生效,之后不再需要运行 /reload-plugins。216

v2.1.229 新增了 command 市场源——市场条目可以指向一个本地命令(例如 IDE 或构建工具),该命令运行时会输出 plugin 目录。系统会在每次会话中重新解析路径并应用,无须重启;mode: "link" 会直接使用原目录,而不是复制目录。这是一种面向开发循环的来源:由编辑器管理 plugin 检出目录,Claude Code 则跟随其指向的位置。257

v2.1.275 新增了两项账号侧便利功能:/plugin install <plugin> --marketplace <source> 可以从尚未添加的市场安装——Claude Code 会先询问是否添加该市场——而且 claude.ai 账号上启用的 plugins 会同步到使用同一账号登录的终端会话中(即 name@synced 通道;现在可以通过 syncClaudeAiPlugins: false 明确选择退出;skills 也会以同样方式通过 syncClaudeAiSkills 同步)。218

Plugin 清理(v2.1.121+)

Plugins 可以将其他 plugins 声明为依赖项。安装一个 plugin 时,其依赖项会自动安装,并标记为“自动安装”。以下两个新命令可清理手动卸载或移除市场后遗留的内容:

命令 行为
claude plugin prune 移除父 plugin 已不存在的自动安装 plugins
claude plugin uninstall <name> --prune 卸载指定 plugin,并级联移除由此成为孤立项的自动安装依赖项

手动卸载 plugin 或移除市场后,请运行 prune,以保持 ~/.claude/plugins/ 简洁。154

本地开发

创建一个用于测试的本地市场:

mkdir dev-marketplace && cd dev-marketplace
mkdir my-plugin
# Create plugin structure

cd ..
claude
> /plugin marketplace add ./dev-marketplace
> /plugin install my-plugin@dev-marketplace

Plugin 安装改进(v2.1.51+)

从 npm 源安装时,Plugins 现在支持自定义 npm 注册表和固定特定版本。市场操作的默认 git 超时时间从30秒延长到120秒,并可通过 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 配置。98 自 v2.1.275 起,系统使用 npm pack --ignore-scripts 获取 npm 源 plugins 并验证完整性,因此软件包的安装脚本不再于您的计算机上运行——plugin 安装中的经典 npm 供应链攻击途径由此被封堵。218 v2.1.277 修复了重新安装与运行中会话发生冲突的问题:重新安装正被某个会话或其他程序使用的 plugin 版本时,claude plugin install 有时会失败并破坏已安装的副本;现在,未发生变化的副本会原样保留。同一版本还会在对已安装的 plugin 运行 claude plugin install 时,提示市场是否提供了更新版本,并明确给出 claude plugin update 命令。219 v2.1.286 会拒绝属于 git 仓库或文件夹的 npm plugin 源,并且仅从注册表软件包安装 plugin 依赖项。231

Plugin 配置安全性(v2.1.207)

两项加固改动封堵了 plugin 配置中的 shell 注入和仓库提供配置这两类攻击途径:185

  • shell 形式的命令会拒绝 ${user_config.*}。 将用户提供的配置值直接插入 shell 字符串会带来注入风险,因此引用 ${user_config.*} 的 shell 形式 plugin 命令现在无法通过验证。请改用 exec 形式(参数数组,不进行 shell 解析),或从 $CLAUDE_PLUGIN_OPTION_<KEY> 环境变量读取该值。
  • 不再从项目级 .claude/settings.json 读取 pluginConfigs。 Plugin 配置值现在仅来自用户级设置,因此克隆的仓库无法携带会改变已安装 plugins 执行方式的配置。

隔离加固仍在继续:v2.1.265 修复了 macOS 和 Linux 上 plugin 路径中的反斜杠可绕过符号链接隔离的问题;v2.1.267 又针对已获取的市场封堵了同类漏洞——市场条目路径中的反斜杠此前可绕过隔离检查。215216

Plugin 组件

  • 命令:可用作斜杠命令(/plugin-command)
  • Agents:可用作 subagents
  • Skills:根据 skill 配置自动加载
  • Hooks:与用户及项目 hooks 合并,并行运行
  • MCP 服务器:启用 plugin 时自动启动

通过 .claude/skills/ 使用本地 Plugins(v2.1.157+)

放置在项目 .claude/skills/ 目录中的 plugins 现在无须市场即可自动加载,claude plugin init <name> 则会在该目录中搭建一个全新的 plugin。这大幅缩短了从“我需要一个项目范围的工具”到“我已经拥有可用的 plugin”之间的路径——无须注册市场,也无须处理清单配置。/plugin 还新增了参数自动补全,与其余命令界面保持一致。266

Plugin CLI:JSON 输出、固定安装、评估套件(v2.1.268-271)

以下3项新增功能推动 plugin CLI 更好地用于脚本和 CI:216

  • 全面支持 --json(v2.1.268):claude plugin install、uninstall、update、enable 和 disable 均接受 --json;claude plugin list --json 的每一行也都包含 errorDetails 和 noteDetails——在此之前,包装脚本必须解析供人阅读的输出,如今则可直接使用机器可读状态。
  • 固定命令接受机制(v2.1.271):claude plugin install --accept-command <sha256>(claude plugin update 同样支持)只会接受上一次 --json 运行所显示的确切命令,而不是像 -y 那样一概允许——审核一次并批准这些字节;如果安装命令发生变化,则会失败而不会执行。
  • claude plugin configure <plugin>(v2.1.285):显示 plugin 的选项以及哪些选项尚未设置,或通过 --values-stdin 保存从 stdin 读取的新值。claude plugin install --config 也接受 <server>.<key>=<value>,因此可在安装时设置随附 .mcpb MCP 服务器自身的配置,使其无须前往 /plugin → 配置即可启动。229
  • claude plugin eval(v2.1.269):针对 Claude Code 运行 plugin 的评估套件,并获得以 JSON 形式呈现的可复现评分结果及一份 HTML 报告——这不仅验证清单,还能对 plugin 行为进行回归测试。claude plugin eval --help 记录了套件格式。自 v2.1.299 起,--disallow-tools 和 disallowed_tools 用例字段可阻止 Agent 等指定内置工具参与运行;如果运行以 API 错误结束,则无需评级直接计为0分,并使套件以状态码1退出。评估文档也记录了这项评分变更。271272
  • claude plugin install --marketplace <source>(v2.1.292):shell 命令新增了 /plugin install 自 v2.1.275 起便已支持的标志。它会在需要时按照与 claude plugin marketplace add 相同的策略检查添加市场,然后从中安装 plugin。Plugin CLI 参考现在也为 shell 命令列出了 --marketplace <source>,要求 v2.1.292。236237240
  • claude plugin validate 和 claude plugin test(v2.1.289-292):当某个 plugin 的文件夹中还包含市场清单时,validate 不再跳过该 plugin(始于 v2.1.289,plugin CLI 参考也证实了这一点);它会列出 mod 在每个门控位置注册的各个 hook,并注明是否具有 .catch,在 --json 下以 gatingHooks 呈现(v2.1.290)。自 v2.1.292 起,如果测试注册的 hook 中有 expect 失败,或引擎拒绝存根答案,claude plugin test 将判定失败,而不再静默通过。235236237

Mods(v2.1.287)

Mod 是一种 plugin,其 JavaScript 或 TypeScript 处理程序在 Claude Code 内部运行,而不是作为 shell 命令运行。当发生工具调用、提交提示词或绘制部分界面等事件时,Claude Code 会调用处理程序;处理程序可以监视、修改或接管该事件。这样一来,mod 可以在对话记录旁绘制窗格或在提示框上方绘制条带、添加无需 Claude 轮次即可运行的 /command,也可以挂起、应答或重新路由工具调用。232233

Mods 要求 v2.1.287,并且默认启用。Mod 使用您的权限运行,且不受沙盒隔离,因此请仅安装来自可信作者和市场的 mods;安装前,claude plugin validate ./some-mod 会列出 mod 挂接的事件及其进行的调用。若要停止已安装的 mods,可以在 /plugin 中禁用相应 plugin、使用 --safe-mode 启动单次会话,或在 ~/.claude/settings.json 中设置 "disableAllHooks": true;最后一种方式还会停止您的设置 hooks 和状态行。这些方法都不会停止内置 mods。自 v2.1.287 起,早期体验开关 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 将被忽略。233

部分内置功能本身就是 mods,它们列在 /plugin 的已安装选项卡下的内置分组中,例如 /diff 和 AGENTS.md 加载。其中有一项默认关闭:You should know 会运行一个随行 agent,为您留意情况,并指出您或 Claude 可能遗漏的问题。可通过 /plugin enable cc-plugin-you-should-know@builtin 启用它;发布说明指出,该功能仅适用于已开启遥测的第一方会话。232233

Mod API 新增功能(v2.1.288-292)。v2.1.288 新增了 $.ui.selection(),它会返回您上次在全屏模式中选择的文本;如果选区位于对话记录的某一行内,还会返回该行。v2.1.289 会为 agent 团队的队友触发 agent.spawn(e.isTeammate 为 true),在各 plugin hook 事件中保持同一个 agent ID,并在 $.agent.list() 中报告空闲和等待状态。10月13日重新获取的 mods 参考仍标注“截至 v2.1.290”,但现在已列出 tool.check 上的 e.agentId 和 e.ceiling(要求 v2.1.290),以及 v2.1.292 的 prompt.autocomplete 事件;截至2026年10月14日,serverToolUses 及下述其余内容仍仅见于发布说明:270272 v2.1.290 在 turn.step 结果中新增了 serverToolUses(即 API 自行进行的工具调用,例如顾问调用),在 tool.check 事件中新增了 agentId,使 hook 能区分 subagent 的权限检查与主会话的权限检查,并在 tool.check hook 读取的内容中新增了 ceiling,用于指明组织要求的审批。v2.1.292 新增了 prompt.autocomplete 事件,用于向提示框的自动补全列表添加行;在 $.model.complete 中新增提示词缓存(在块上设置 cache: true 会缓存截至该块的请求);还在 agent.spawn 中加入了工作流 agents 及其运行实例和索引,使 mod 可以拒绝它们。234235236237

Mod API 新增功能(v2.1.299)。$.prompt.media 允许由托管设置安装的 mod 的 prompt.submit hook 读取附加到提示词的图像或文档字节;$.session.identity() 则会告知此类 mod 当前会话的登录方式,并在托管的 forceLoginOrgUUID 包含相应组织时提供组织和电子邮件信息。Text 接受 size、weight、mono 和 tabular,Box 接受命名间距级别(xs 到 xl),而 bold 已弃用,建议改用 weight。skill.prompt 会接收 skill 的 frontmatter、来源、plugin 名称和文件路径;mods 参考将其列为要求 v2.1.299 的 e.frontmatter、e.source、e.pluginName 和 e.path。session.append 新增一个 queue 入口;恢复 subagent 或终止队友时会触发 agent.spawn 并设置 resume;turn.start 会接收 subagents 的轮次(e.agentId);$.http.fetch 则接受 Content-Length 超过 4 MiB 正文上限的 304、204 或 205 响应。如果提供的 $ 方法在10秒内没有响应,claude plugin test 会判定失败,并以 part: { plugin } 标记每个 mod 的 ui.render 根节点。Hook 返回的值如果嵌套超过28,000层,将被拒绝。271272

Mod API 新增功能(v2.1.300)。virtualText 提示框装饰会在提示框中绘制文本,但这些文本永远不会进入草稿或已提交的提示词;$.ui.view({ agentId }) 会在主视图中显示某个 agent 的对话记录,$.ui.view({}) 则会返回;Text 接受 dir,用于从右向左显示的行(Windows 和 VS Code 的终端);提示框并非因键入编辑而发生变化时,会触发 prompt.change hook;agent.spawn 可以重写工作流 agent 的 prompt 和 model;当 tool.call、PreToolUse 或 agent.spawn hook 改写了某个事件所源自的调用时,next.error.cause 会报告 rewritten。Mods 参考将该功能标注为始于 v2.1.300,但文档本身仍注明“截至 v2.1.290”。273274

Mod API 新增功能(v2.1.301)。Input 接受 rows,用于在终端中创建多行文本字段;按 Enter 提交,按 Shift+Enter 或在 Enter 前输入反斜杠可另起一行。Hook 的 .catch 处理程序仅在 hook 抛出异常或超时时运行;由该 hook 自身调用所引发的下层事件会跳过此 hook,也不会触发其 .catch。变量设置或取消设置后,$.env.set 会解析为 {};如果未执行写入,则解析为说明原因的 { deny }。在新进程首次响应完成前调用 $.model.fork 时,它不再返回 nothing-to-fork;这类情况常见于 claude -p 运行和云会话。在 VS Code 以及桌面和移动应用中,问题对话框上方绘制的树可以包含 Markdown 和最多48行内容(终端仍保留12行纯文本限制)。Mods 文档于10月中旬拆分为概述、参考,以及分别介绍事件、API 和界面的页面;其中 CLI 与桌面端参考标注为截至 v2.1.290,VS Code 参考标注为截至 v2.1.299。截至10月17日,所有页面均未列出 Input 的 rows、$.env.set、virtualText、$.ui.view、prompt.change、$.prompt.media 或 $.session.identity。275276


Memory 如何工作?

Claude Code 的 Memory 系统可跨会话保留上下文。能否有效管理 Memory,决定了 Claude 是能深入理解您的项目,还是每次会话都从头开始。

CLAUDE.md 层级结构

位置 作用域 是否共享 用途
/Library/Application Support/ClaudeCode/CLAUDE.md(macOS) 企业 所有用户 公司规范
./CLAUDE.md 或 ./.claude/CLAUDE.md 项目 通过 git 团队上下文
~/.claude/CLAUDE.md 用户 所有项目 个人偏好
./CLAUDE.local.md 项目本地 从不共享 个人项目笔记

AGENTS.md 支持(v2.1.277)

Claude Code 现在会读取 AGENTS.md。这是 Codex CLI 以及越来越多其他编码代理共同采用的跨工具指令文件约定:在没有 CLAUDE.md 的项目中,Claude Code 会改为读取 AGENTS.md。 已为其他代理配置好的代码仓库无需再添加 CLAUDE.md、导入或设置即可正常工作;可在 /config 的 “Project instructions” 下配置此行为,但该功能尚未覆盖 Bedrock、Vertex 或 Foundry。219 因此,本指南长期以来关于 Claude Code 不读取 AGENTS.md 的迁移建议现已失效。更新后的迁移路径请参阅从 OpenAI Codex CLI 迁移。

何时加载哪些文件(默认模式,文档称之为 claude-md-or-agents-md):219

您的代码仓库中包含 Claude 读取
存在 AGENTS.md,且工作目录及其上级目录中没有 CLAUDE.md 或 CLAUDE.local.md 您的 AGENTS.md
存在 AGENTS.md,且工作目录或其上级目录中存在 CLAUDE.md 或 CLAUDE.local.md 仅您的 CLAUDE.md 文件
存在导入 AGENTS.md(@AGENTS.md)的 CLAUDE.md 您的 CLAUDE.md,并通过导入包含 AGENTS.md

更新日志中的用词是“instead”(改为),而非“as well”(也会):项目中的 CLAUDE.md 拥有绝对优先权,默认情况下两者不会合并。检查范围包括工作目录或任意上级目录中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md;您的 ~/.claude/CLAUDE.md、组织管理的 CLAUDE.md 以及 .claude/rules/ 文件均不计入其中,它们仍会与 AGENTS.md 一同加载。请特别留意:如果向仅使用 AGENTS.md 的代码仓库添加用于个人笔记的 CLAUDE.local.md,Claude 将停止读取 AGENTS.md。解决方法是将 Project instructions 切换为 claude-md-and-agents-md,以便同时读取两者(先读取每个目录中的 CLAUDE.md 文件,并对已导入的副本去重)。其他可选值包括 claude-md(仅 CLAUDE.md)和 managed-only;除 /config 外,该值位于内置 agents-md@builtin plugin ID 对应的 pluginConfigs 中(options.instructionFiles)。用户、--settings 和托管作用域中的设置均会生效,但项目和本地设置文件中的配置会被忽略。219

符合条件时,其加载行为与 CLAUDE.md 类似:会话开始时加载工作目录及其上级目录中的所有 AGENTS.md 和 .claude/AGENTS.md(交互式会话会显示一行“no CLAUDE.md found; AGENTS.md loaded: …”);当 Claude 读取某个子目录中的文件,并且该子目录没有自己的 CLAUDE.md 时,会加载其中的 AGENTS.md;其中同样支持 @path 导入和 claudeMdExcludes。系统不会读取 AGENTS.local.md、AGENTS.override.md 和 .agents/ 目录。对于直接读取、而非由 CLAUDE.md 导入的 AGENTS.md,文档列出了以下3项差异:223

CLAUDE.md 直接读取的 AGENTS.md
InstructionsLoaded hooks 触发 不触发(如果 AGENTS.md 由 CLAUDE.md 导入或通过符号链接指向,则会触发)
设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 后通过 --add-dir 添加的目录 加载其中的 CLAUDE.md 不加载其中的 AGENTS.md
通过 @path 导入工作目录之外的文件 Claude Code 会请求您批准外部导入 仅当您此前已批准此项目的外部导入时才会加载,且不会提示

要确认 Claude 是否读取了您的 AGENTS.md,请运行 /memory 并查找其路径;在 v2.1.280 之前,/memory 和 /context 不会列出直接读取的 AGENTS.md。223

Claude 仅读取 CLAUDE.md 文件的情况:使用 v2.1.277 之前的版本;会话不获取功能标志(使用 Bedrock 或其他第三方提供商,或者已禁用遥测);安装或升级至支持 AGENTS.md 的版本后的首次会话(从下次会话起才会读取 AGENTS.md);以及内置 agents-md plugin 被禁用时。针对这些情况,请保留在简易 CLAUDE.md 中使用经典 @AGENTS.md 导入的做法。223

如果此前已手动接入 AGENTS.md,导入和符号链接这两种变通方案仍可保留,不会导致重复读取;但应移除用于输出 AGENTS.md 的 SessionStart hook,因为它现在会造成内容重复。219

有效的 CLAUDE.md 结构

# Project Context

## Architecture
- Monorepo with packages in /packages
- React frontend in /packages/ui
- Node.js API in /packages/api
- Shared types in /packages/types
- PostgreSQL database via Prisma

## Code Standards
- TypeScript strict mode everywhere
- ESLint + Prettier enforced (pre-commit hooks)
- No default exports
- JSDoc on all public APIs
- Tests required for all new code

## Commands
- `npm test` - Run all tests
- `npm run test:watch` - Watch mode
- `npm run lint` - Check linting
- `npm run lint:fix` - Auto-fix lint issues
- `npm run build` - Production build
- `npm run dev` - Start dev servers
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Seed database

## Patterns

### API Endpoints
Create in packages/api/src/routes/
Use Zod for request/response validation
All endpoints need OpenAPI documentation

### React Components
Create in packages/ui/src/components/
Use React Query for server state
Prefer composition over inheritance

### Database
Prisma schema in packages/api/prisma/
Always create migration for schema changes
Use transactions for multi-table operations

## Important Notes
- NEVER commit .env files
- API runs on :3000, UI on :3001
- Local DB: postgres://localhost:5432/myapp
- Feature flags in packages/api/src/flags.ts

## Recent Decisions
- 2025-12-01: Migrated to React Query v5
- 2025-11-15: Adopted Zod for all validation
- 2025-11-01: Moved to ESM modules

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

CLAUDE.md 中禁止提交署名的规则优先(v2.1.269):过去,Claude Code 的署名提醒(Co-Authored-By 和“Generated with Claude Code”行)会覆盖 CLAUDE.md 或 Memory 中禁止添加署名的规则;现在该规则拥有优先权。由托管设置配置的署名行仍会生效。216

"attribution": false(v2.1.281):在 settings.json 中将 attribution 设为 false,可隐藏所有提交和 PR 署名。旧版 CLI 会跳过包含此设置的设置文件,因此对于跨版本共享的文件,请保留对象形式:将 attribution.commit 和 attribution.pr 设为空字符串,并将 attribution.sessionUrl 设为 false,以移除会话链接。attribution 对象已取代弃用的 includeCoAuthoredBy 键。224 设置参考文档现也已说明 false 值。227

文件导入

在 CLAUDE.md 中引用其他文件:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

导入语法: - 相对路径:@docs/file.md - 项目中的绝对路径:@/absolute/path.md - 主目录:@~/.claude/file.md - 最大深度:5层导入

Memory 规则目录

为了更有条理地管理 Memory,可使用 .claude/rules/ 存储分类规则文件:11

.claude/rules/
├── testing.md          # Testing conventions
├── security.md         # Security requirements
├── api-patterns.md     # API design patterns
└── deployments.md      # Deployment procedures

规则会自动加载并提供结构化上下文,避免 CLAUDE.md 杂乱无章。如果某条规则的 frontmatter 中包含 paths 字段,则仅当 Claude 处理匹配文件时才会加载该规则。在 v2.1.288 之前,只有 Read 才会加载路径作用域规则和嵌套的 CLAUDE.md 文件;从 v2.1.288 开始,当 Write 或 Edit 在其作用域内创建或修改文件时,也会加载这些规则。Memory 文档现已明确说明:“当 Claude 使用 Read、Write 或 Edit 工具时,会触发路径作用域规则。”234237

快速添加 Memory

使用 # 前缀在会话期间添加笔记:

# Always run tests before committing
# The payment module is especially fragile
# Use the new logger from packages/api/src/logger.ts

系统会提示您选择用于存储该笔记的 Memory 文件。

自动 Memory(v2.1.32+)

Claude Code 现在会自动记录并回忆跨会话的项目上下文。80 在您工作时,Claude 会将观察结果(模式、约定、调试心得和关键文件路径)写入以下持久化 Memory 文件:

~/.claude/projects/{project-path}/memory/MEMORY.md

您会在会话开始时看到 Recalled memories,并在会话期间看到 Wrote memories。自动 Memory 与 # 前缀的区别如下:

自动 Memory # 前缀
触发方式 由 Claude 隐式决定 由您明确决定
内容 模式、约定、架构 特定事实或指令
存储位置 MEMORY.md(自动管理) 用户选择的 Memory 文件
编辑方式 由 Claude 管理;您也可以直接编辑文件 由您控制存储内容

自动 Memory 始终会加载到您的系统提示词中(前200行)。请保持内容精炼。详细笔记可拆分为单独的主题文件(例如 debugging.md、patterns.md),并从 MEMORY.md 链接到这些文件。

管理自动 Memory(v2.1.59+):使用 /memory 可直接在 Claude Code 中查看和管理自动 Memory 文件。100 这取代了过去 /memory 仅打开 CLAUDE.md 编辑器的行为。现在,您可以查看、编辑和整理 Claude 记住的内容。

Memory 时间戳(v2.1.75+):Memory 文件现在包含最后修改时间戳,帮助 Claude 判断哪些记忆较新、哪些已经过时。自动回忆时,过时记忆的优先级会降低,从而改善上下文质量。117

如需退出,请在启动时传入 --no-memory(这会禁用所有 Memory,包括 CLAUDE.md)。目前没有仅禁用自动 Memory、同时保留 CLAUDE.md 的标志(这是一个已请求的功能)。

使用 /dream 整理 Memory:随着时间推移,自动 Memory 会积累重复和过时的条目。/dream 命令会执行自动整理流程,清理并合并 Memory 条目、移除冗余内容,同时归纳相关观察结果。建议定期使用,以确保 Memory 文件重点突出,并控制在200行的预算内。128

上下文管理命令

查看上下文用量:

> /context

显示一个可视化网格,展示系统提示词、对话、工具和文件内容的上下文分配情况。

压缩对话:

> /compact
> /compact focus on the authentication changes
> /compact preserve test output and error messages

在保留关键信息的同时,智能总结较早的对话内容。

自定义压缩指令(在 CLAUDE.md 中):

# Summary Instructions
When using compact, focus on:
- Test output and failures
- Code changes made this session
- Architecture decisions

为上下文启用扩展思考:

export MAX_THINKING_TOKENS=10000

更多思考 token 意味着更强的推理能力,但成本也更高。

上下文优化策略

  1. 使用具体文件引用,而非让 Claude 搜索
  2. 在任务之间使用 /clear 清除无关对话
  3. 在长时间会话中主动压缩
  4. 使用 subagents 隔离探索性工作
  5. 将复杂任务拆分为目标明确的交互
  6. 对于持续进行的工作,恢复会话,无需重新说明

图像与多模态输入

Claude Code可以分析图像:截图、图表、设计稿、错误信息、数据库模式。

输入方式

  1. 拖放:将图像文件拖入Claude Code窗口
  2. 粘贴:使用Ctrl+V(Mac上也不是Cmd+V)从剪贴板粘贴
  3. 路径引用:“分析这张图像:/path/to/screenshot.png”

查看附加图像

当Claude在回复中引用图像时,可以点击图像链接直接查看:27

[Image #1]   # Click to open in default image viewer
[Image #2]   # Navigate attached screenshots

在检查截图或排查视觉问题时,可点击的链接很有帮助。点击引用,即可查看Claude分析的具体图像。

使用场景

  • 排查UI问题:“这是缺陷的截图,是什么原因导致的?”
  • 实现设计:“根据这份设计稿构建组件”
  • 分析图表:“解释这张架构图”
  • 数据库模式:“创建与这张ERD匹配的Prisma模型”
  • 错误分析:“这张错误截图是什么意思?”

专家建议:根据设计稿实现界面时,请提供展示不同状态的多张截图(默认、悬停、加载、错误)。视觉上下文越充分,实现效果越好。

PDF阅读(v2.1.30+)

Claude Code可以读取和分析PDF文档,并支持按页控制读取范围:76

基本PDF读取:

> Analyze this PDF: /path/to/document.pdf

读取指定页面范围:

> Read pages 1-5 of the PDF: /path/to/report.pdf

也可以通过Read工具的pages参数以编程方式读取: - pages: "1-5" - 读取第1至5页 - pages: "1,3,7" - 读取指定页面 - pages: "10-" - 从第10页读取至文档末尾

限制: - 每次请求最多读取100页 - 文件大小上限为20MB - 通过@提及大型PDF(超过10页)时,会返回轻量级引用,完整内容按需加载


语音模式(2026年3月)

语音模式让Claude Code成为可以通过交谈协作的结对编程伙伴,无需键入内容。通过/voice启用后,使用按住说话的方式精确控制语音采集时机。111

启用方式

> /voice           # Start voice mode

也可以在settings.json中设置voiceEnabled: true,在会话启动时自动启用。

工作原理

按住空格键说话,松开发送。Claude处理您的语音,并像接收到键入的提示词一样作出回应。按住说话的设计可避免编程期间意外触发。

支持的语言(共20种,v2.1.69+)

英语、西班牙语、法语、德语、葡萄牙语、意大利语、日语、韩语、中文、印地语、俄语、波兰语、土耳其语、荷兰语、乌克兰语、希腊语、捷克语、丹麦语、瑞典语、挪威语。110

推出状态

语音模式于2026年3月3日发布,在春季逐步开放,所有订阅级别均可使用。111

适用场景

  • 一边在白板上画草图,一边描述整体架构
  • 口述提交消息和PR描述
  • 双手不离键盘,以对话方式解释缺陷
  • 快速委派任务:“运行测试套件并修复所有失败项”

Git集成如何工作?

Claude Code深度集成了git,并内置安全机制。

安全机制

  • 自动遵循.gitignore
  • 未经许可不会修改分支
  • 提交前展示差异
  • 遵循项目的提交规范
  • 未经明确要求绝不强制推送
  • 修改已有提交前检查作者身份

常见工作流程

创建提交:

> commit these changes
> create a commit with a meaningful message

Claude将会: 1. 运行git status和git diff 2. 分析变更 3. 生成符合约定式提交规范的提交消息 4. 等待批准后再提交

创建拉取请求:

> create a PR for this feature
> summarize the changes and create a PR

一次完成提交→推送→PR:内置的/commit-push-pr命令会依次执行这3个步骤。从v2.1.206起,它会自动允许向仓库已配置的推送远程仓库执行git push——如果设置了remote.pushDefault,则使用该配置,否则使用唯一的远程仓库——不再仅限于origin,因此基于fork和多个远程仓库的工作流程在推送步骤中不再触发权限提示。184 从v2.1.229起,这种自动批准不再涵盖携带危险标志的git/gh调用——使用--force、--amend、--no-verify等标志时,现在会请求批准。257

审查代码:

> review the changes in this PR
> what could go wrong with these changes?

GitHub Actions集成

使用官方Action,在CI/CD中自动运行Claude:

快速设置:

> /install-github-app

手动配置工作流程文件:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for bugs, security issues, and performance problems"
          claude_args: "--max-turns 5"

用于Bedrock(使用OIDC):

- name: Configure AWS
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: '--model us.anthropic.claude-opus-5-5'

代码审查[研究预览](2026年3月)

Code Review是Anthropic的多智能体系统,可自动审查拉取请求,发现人工审查可能遗漏的缺陷。创建PR后,一组智能体会并行执行任务,各自从不同角度检查代码库,随后交叉验证发现的问题,过滤误报,并按严重程度排序。结果以一条总览评论和行内注释的形式呈现。113

可用范围:面向Claude for Teams和Claude for Enterprise客户提供研究预览(2026年3月9日)。

审查级别与停止订阅(v2.1.304-307)。所有者可以为组织选择Quick、Standard(默认)或Deep级别,也可以为各个仓库单独设置级别。另有一个选项可对GitHub组织中的所有仓库执行审查,包括之后新增的仓库(v2.1.304)。@claude review stop(也可使用off和pause)会结束拉取请求上的@claude review always订阅,且不会启动新的审查(v2.1.307);如果先前发现的阻塞性问题仍未解决,再次审查时也不再以LGTM开场(v2.1.305)。代码审查文档介绍了这3个级别;停止命令仅在发布说明中有记载。278279

工作流程: 1. 开发者创建PR 2. 多个AI智能体并行分析代码 3. 智能体相互交叉验证发现的问题 4. 最后由一个智能体汇总、去重,并按严重程度排序 5. 结果以PR评论形式发布(总览+行内注释)

性能指标(Anthropic内部数据):

指标 数值
大型PR(1,000行以上)中发现问题的比例 84%(平均7.5个问题)
小型PR(少于50行)中发现问题的比例 31%(平均0.5个问题)
人工异议率 不足1%的发现被标记为误报
平均审查时间 约20分钟
收到实质性评论的PR比例 54%(此前为16%)

费用:每次审查15–25美元,随PR的规模和复杂程度变化。组织可以通过月度支出上限、按仓库启用和分析仪表板管理支出。113

设置:管理员在Claude Code设置中启用该功能,安装GitHub App,并选择目标仓库。开发者无需配置——启用后,系统会自动审查新建的PR。

与GitHub Action的主要区别:开源的claude-code-action(见上文)通过提示词运行单个Claude实例。Code Review则派遣多个智能体组成的团队进行更深入的分析。合并仍须人工批准——Code Review提供参考信息,但绝不批准合并。113


如何在 IDE 中使用 Claude Code?

VS Code 扩展

要求: VS Code 1.98.0+

安装: 在扩展市场中搜索“Claude Code”

功能: - 侧边栏面板(Spark 图标) - 活动栏中的会话列表,会话以完整编辑器形式打开(v2.1.70+)109 - 计划的完整 markdown 文档视图,支持评论(v2.1.70+)109 - 在聊天面板中通过 /mcp 打开原生 MCP 服务器管理对话框(v2.1.70+)109 - 压缩内容显示为可折叠的“Compacted chat”卡片(v2.1.69+)110 - 带差异预览的计划模式 - 自动接受编辑开关 - 扩展思考开关 - 文件附件与图片粘贴 - 对话历史 - 多个并行会话 - 专注视图(v2.1.221): 聊天菜单中的一个开关,将工具活动折叠到可展开的逐轮摘要之后,并附带实时显示运行中工具的指示器;快捷键为 Ctrl+Alt+F,也可使用“Claude Code: Toggle Focus view”命令。想把对话当作文章来阅读、只展开自己关心的工具调用时,不妨开启它;默认视图仍是完整的活动流。199 - 会话分组(v2.1.229): 侧边栏将会话整理为带名称的分组;右键即可创建、重命名或删除,按住 Cmd/Ctrl 或 Shift 点击可一次移动多个会话。/btw 附带提问面板也可以通过拖动边界来调整大小。257

安全提示: Anthropic 已在 IDE 扩展 v1.0.24+ 中修补了一个 WebSocket 身份验证绕过漏洞(CVE-2025-52882)。请确保扩展已更新;Anthropic 已从扩展商店中移除所有存在漏洞的版本。31

第三方提供商配置(位于 .claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "your-profile"
  }
}

v2.1.311 至 v2.1.317: Claude 回复中的代码块在浅色、深色和高对比度深色主题下都有语法着色;运行缓慢的 UserPromptSubmit hooks 会在加载指示器中显示名称;VS Code 的遥测设置关闭时,会话启动即设置 DISABLE_TELEMETRY,因此不会发送任何使用指标,也不会拉取功能开关(v2.1.311)。闲置压缩会对在聊天面板中闲置的 200K+ token 对话进行摘要(v2.1.314)。可以在聊天面板中登录 Claude 应用网关;ultrathink 会以 xhigh 努力级别运行该轮并显示彩虹效果;当模型设置带有 [1m] 标签时,会显示 Effort 滑块、Ultracode 开关和模型名称(v2.1.316)。CLAUDE_CODE_DISABLE_CFC_PROMPT 还能让 Claude in Chrome 的指令不进入会话消息,同时浏览器工具仍然可用(v2.1.314)。分叉的对话会保留每一次并行工具调用以及压缩保留下来的消息(v2.1.317)。284

JetBrains 插件

支持: IntelliJ IDEA、PyCharm、WebStorm、GoLand、PhpStorm、DataGrip

安装: 设置 → 插件 → 搜索“Claude Code” → 安装 → 重启

常用快捷键: - Cmd+Esc(Mac)/ Ctrl+Esc(Windows):快速启动 - Cmd+Option+K(Mac)/ Alt+Ctrl+K(Windows):添加文件引用

功能: - 在 IDE 差异查看器中查看差异 - 自动共享选中内容的上下文 - 诊断信息集成 - 多会话

WSL2 配置: 将 Claude 命令设置为:

wsl -d Ubuntu -- bash -lic "claude"

终端集成

将外部终端连接到 IDE:

> /ide

Claude Code 会自动检测 VS Code、Cursor、Windsurf 和 JetBrains 系列 IDE。

Slack 集成(2025年12月)

Claude Code 现已直接与 Slack 集成,开发者可以在聊天线程中直接委派编码任务。7

工作方式: 1. 在 Slack 频道或线程中提及 @Claude 2. Claude 审阅消息,判断是否为编码任务 3. 一个 Claude Code 会话会在 Anthropic 的基础设施上自动启动 4. Claude 从频道/线程的近期消息中收集上下文 5. 进度更新会回传到您的 Slack 线程 6. 完成后提供用于审查更改和打开 PR 的链接

使用场景: - 根据 Slack 中发布的错误报告进行 bug 排查 - 基于团队反馈的快速代码审查 - 根据功能请求实现小型功能

要求: - 通过 Slack App Marketplace 安装 Claude 应用 - Slack 付费套餐 - 可访问云端会话(claude.com/code)

隐私: Claude 遵循 Slack 现有的权限结构,无法访问您无权查看的对话或仓库。对话内容不会用于模型训练。


高级用法

无头模式与 CI 模式

在脚本和 CI 流水线中运行 Claude Code:

#!/bin/bash
# Automated code review

result=$(claude -p "Review this code for quality issues" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --disable-slash-commands \
  --max-turns 5)

if echo "$result" | jq -e '.result | test("critical|high severity")' > /dev/null; then
  echo "Issues found:"
  echo "$result" | jq -r '.result'
  exit 1
fi

echo "Review passed"
exit 0

管道与链式调用

# Analyze logs
cat production.log | claude -p "summarize errors" > error-summary.md

# Process multiple files
find . -name "*.ts" -exec cat {} \; | claude -p "find security issues"

# Chain with jq
claude -p "generate config" --output-format json | jq -r '.result' > config.json

后台任务

运行耗时操作而不阻塞:

> start the build in the background

或在命令执行期间按 Ctrl+B。

管理后台任务:

> /bashes                    # List running tasks
> get output from task xyz   # Retrieve output

使用 Git Worktree 运行并行会话

# Create worktrees for parallel work
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123

# Run Claude in each worktree (separate project dirs = separate sessions)
cd ../project-feature-a && claude
cd ../project-bugfix && claude

每个 worktree 都是一个独立的项目目录,拥有自己的会话。

v2.1.304-309 中的 worktree 变更。 当 HEAD 处于分离状态或位于其他分支时,claude --worktree 退出时不再未经询问就删除 worktree 及其分支,此前这可能导致提交丢失(v2.1.304);裸仓库中的新 worktree 从默认分支而非本地 HEAD 创建,未发生更改的 subagent worktree 会被清理(v2.1.305);创建和复用 worktree 时不再按需拉取 git 对象,普通克隆如此,配置了 Bash 沙箱的部分克隆也如此(后者会预先拉取),并且 worktree 和分支检出会忽略 git replace 引用(v2.1.309)。278

JSON 输出解析

result=$(claude -p "analyze this code" --output-format json)

# Extract fields
echo "Result: $(echo $result | jq -r '.result')"
echo "Cost: $(echo $result | jq -r '.total_cost_usd')"
echo "Session: $(echo $result | jq -r '.session_id')"
echo "Duration: $(echo $result | jq -r '.duration_ms')ms"

以编程方式管理会话

# Name the current session for easy recall (inside Claude: /rename feature-auth)
# Then resume by name later:
claude --resume "feature-auth"

# Continue most recent session
claude -c "continue implementing the tests"

# List recent sessions to find one (shows up to 50 sessions, v2.1.47+)
claude --resume          # interactive picker

远程与后台代理 [研究预览]

Claude Code 通过两项互补功能突破了本地终端的边界:Remote(云端执行,并可传送回本地)和后台代理(并行执行任务,不阻塞终端)。两者都使用 & 前缀,并共享同一套云基础设施。

核心概念

claude.ai/code 的 Web 界面在云端运行 Claude Code。离开终端期间,任务会在后台继续执行。准备好继续时,将会话传送到本地机器,即可从 Claude 停下的地方无缝接续。

远程执行让以前无法实现的工作流成为可能: - 在手机上启动一项复杂的重构任务,通勤途中让它持续运行,回到工作站后收尾 - 在 Web 界面上排队多个任务,回到办公桌后再审阅结果 - 需要合上笔记本电脑时,把长时间运行的操作交给云端

& 前缀

将任务发送到 Claude Code Web 端在后台运行:

& Build a complete REST API for user management with authentication, CRUD operations, and proper error handling

& 前缀会把您的提示词派发到云端,由 Claude 异步处理。您可以关闭终端、切换设备,或者继续处理其他工作。claude.ai/code 的 Web 界面会显示正在运行和已完成的会话。

--teleport 标志

将云端会话拉取到本地终端:

claude --teleport session_abc123

该标志会从 Web 端获取会话状态并在本地恢复。您将获得完整的对话历史以及 Claude 修改过的所有文件,并能像全程在场一样继续交互。

会话 ID 显示在 Web 界面中。点击任意会话即可查看其 ID 和当前状态。

--cloud 标志

--teleport 把会话从云端移到终端;--cloud 则为新工作走相反的方向:它直接从命令行启动云端会话,无需打开浏览器。281

claude --cloud "Fix the authentication bug in src/auth/login.ts"

云端虚拟机克隆的是当前目录 GitHub 远程仓库中的当前分支,而不是您的本地检出,因此如有本地提交,请先推送。每个会话对应一个仓库;每条 --cloud 命令都会创建独立的会话,连续执行多条即可并行运行。容器配置期间,CLI 会显示实时检查清单(克隆、设置脚本),并将您输入的内容排队,直到会话就绪。旧的 --remote 写法仍可使用,但已作为弃用别名。281

配合 -p 以及会话 ID 或 claude.ai/code URL,同一标志可向正在运行的云端会话投递一条消息,然后不等待回复直接退出;只要在该机器上已通过 claude auth login 登录即可:

claude -p "Also update the README" --cloud session_01DiUkqY2kzbUbDmW1w96rfi
echo "your message" | claude -p --cloud <session-id>     # stdin works too

成功后会打印会话 ID 和一个 claude.ai 链接;--output-format json 返回 {ok, session_id, url}(此处不支持 stream-json)。不带 -p 的 --cloud <session-id> 会失败,并提示“Attaching to an existing cloud session is not enabled for your account”。该标志需要 Anthropic 账户以及组织的 allow_remote_sessions 策略,并且在 Claude Code 配置为使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或其他第三方提供商时不可用。它与 --remote-control 无关,后者的作用是将本地会话暴露给 claude.ai 和 Claude 应用。281

使用要求

Claude Code Remote 面向 Pro、Max、Team(高级席位)和 Enterprise(高级席位) 订阅用户开放。66 Web 界面运行在 Anthropic 的基础设施上,执行的能力与本地 Claude Code 完全相同(文件操作、bash 命令、MCP 集成),只是环境换成了托管的云端。Anthropic 于2026年1月扩大了 Team 和 Enterprise 的访问范围;账户管理员可以在 Claude 设置中开关访问权限。

iOS 应用(2025年11月): Claude Code 也可在 Claude iOS 应用中使用,让您随时随地发起编码任务,并在手机上监控代理进度。15 Code 标签页现在也已登陆 Android 版 Claude 应用,在手机上创建项目正是在这里完成。280 您可以在离开办公桌时启动任务,之后准备审阅时再将其传送到终端。

Remote Control(2026年2月): 一项会话迁移功能,让您可以在手机、平板或任意浏览器中继续本地的 Claude Code 会话。会话状态(文件引用、对话历史、工具配置、待处理操作)作为一个原子整体通过加密隧道迁移。自2026年8月起已结束研究预览,正式可用(v2.1.58 曾扩大早期预览范围);任何运行 claude remote-control 的机器都会以设备卡片的形式出现在 Claude 应用 Code 标签页的顶部。205 外部构建版本请使用 claude remote-control 子命令(v2.1.51 及以上)。101 会话名称现在默认采用基于主机名的前缀(例如 myhost-graceful-unicorn),可通过 --remote-control-session-name-prefix 覆盖。137 自 v2.1.251 起,Remote Control 客户端可以实时查看前台子代理的工具调用和结果流;默认的后台子代理仍只显示状态。206 自 v2.1.273 起,通过 claude --remote-control(或 /remote-control)启动的会话可以从 Claude 应用中分叉,分叉会作为后台会话在您的计算机上运行。217

自 v2.1.222 起,仓库本地设置(.claude/settings.json 或 .claude/settings.local.json)不能再开启 Remote Control 自动启动,但仍可将其关闭。请通过 /config 在用户范围内启用。这种不对称正是设计意图:克隆下来的仓库不应能悄悄把您的会话暴露给远程接续,但它可以合理地选择退出。199 在任何设置文件(含 MDM 强制执行的托管设置)中设置 disableRemoteControl,Claude Code 将拒绝 claude remote-control、--remote-control 标志、自动启动以及会话内切换;自 v2.1.317 起,/remote-control 会明确说明这一点,而不是回答“Unknown command”。来自应用的分叉名称会保留长名称末尾的“(fork)”,而在 claude remote-control 会话中,“Name (fork)”的分叉命名为“Name (fork 2)”(v2.1.317)。该功能的专属页面是使用 Remote Control 从任意设备继续本地会话。284285

实用工作流

早晨通勤:

& Review all PRs assigned to me and prepare summaries with recommendations

到达办公桌:

# Check what completed
# Visit claude.ai/code to see session list

# Pull the session locally to review and act on recommendations
claude --teleport pr-review-session-xyz

下班前:

& Run the full test suite, fix any failures, and prepare a summary of what was changed

第二天早晨:

claude --teleport test-fixes-session-abc
# Review what Claude did overnight, make final adjustments

Claude Code Channels [研究预览](2026年3月)

Claude Code Channels 让您可以从 Telegram 或 Discord 向正在运行的 Claude Code 会话发送消息。122 该功能采用基于插件的架构来集成消息平台,预计后续会支持更多平台。

使用要求: v2.1.80 及以上、Bun 运行时、claude.ai 登录。使用 --channels 标志启动,即可将工具审批提示转发到您的消息应用。Channel 服务器以插件形式安装。

适用场景: Claude Code 在工作站上运行时,您可以在手机上监控并审批代理操作。对于长时间运行的 /loop 任务或通宵的代理会话尤为实用:既能设置审批关卡,又不必守在终端前。

Claude Code Security [研究预览](2026年2月)

Claude Code Security 是内置于云端会话(claude.com/code)的漏洞扫描能力。97 它会扫描代码库中的安全漏洞,并给出有针对性的补丁建议供人工审查。

开放范围: 面向 Enterprise、Team 和开源维护者的有限研究预览。

工作原理: 1. 将 Claude Code Security 指向一个仓库 2. 它会扫描代码库中的漏洞 3. 结果包含具体的补丁建议供审查 4. 应用更改前必须经过人工审查

该功能依托 Opus 4.6 已被验证的能力:无需额外调校,便在开源代码中发现了 500 多个零日漏洞。79

当前状态

Claude Code Remote 已于2026年8月结束研究预览,现已正式可用。其核心工作流(云端执行加本地传送)实现了不间断的 AI 开发:您离开键盘时 Claude 继续工作,回来后从它停下的地方无缝接续。

当前限制: 会话传送目前仅支持单向:您可以把 Web 会话拉取到终端,却无法把已有的终端会话推送到 Web 端。目前还无法在远程机器(例如通过 SSH 连接的 AWS 实例)上继续本地会话。

后台代理

后台代理在您继续工作的同时运行,无需等待长时间任务完成。10

后台代理的工作方式:

Claude 执行复杂任务时不再阻塞您的终端,后台代理会: 1. 在独立进程中单独执行 2. 即使关闭终端也继续工作 3. 完成后通过通知报告结果 4. 运行期间可以监控和管理

启动后台代理

使用 Ctrl+B: Claude 工作期间,按下 Ctrl+B 即可将当前任务转入后台。终端会立即恢复可用。

使用 & 前缀:

& Run all tests and fix any failures
& Refactor the authentication module to use JWT
& Generate complete API documentation

& 前缀会派发到 Claude Code Remote(云端执行)。如需在本地后台执行,请对正在运行的任务使用 Ctrl+B。

监控后台任务

> /tasks                    # List all running tasks
> /task status abc123       # Check specific task
> /task cancel abc123       # Stop a task
> /task output abc123       # View task output so far

并行后台工作流

同时运行多个代理:

& Fix all failing tests in src/
& Update documentation for the API module
& Run security scan on the codebase

每个代理独立运行。使用 /tasks 监控进度,并在任务完成后逐一获取结果。

Claude in Chrome(2025年12月;2026年7月正式发布)

Claude Code现已通过Claude in Chrome扩展与您的浏览器集成,可直接从终端控制浏览器。17

前提条件

  • Chrome或基于Chromium的浏览器(Edge、Brave、Arc均可)
  • 在终端中运行的Claude Code v2.0+
  • Pro、Max、Team或Enterprise套餐(免费版不提供该扩展)
  • 已从 https://claude.ai/chrome 安装Chrome扩展

设置

  1. 从 https://claude.ai/chrome 安装Chrome扩展
  2. 按提示授予扩展权限(控制浏览器需要页面访问权限)
  3. 使用claude --chrome启动Claude Code,或运行/chrome并选择Enabled by default(默认启用),这样后续会话无需该标志即可连接;自v2.1.290起,项目的设置文件无法将其开启235237
  4. 使用自然语言控制浏览器

该扩展通过本地WebSocket连接与Claude Code通信。两者必须同时运行。

功能

从终端进行浏览器自动化:

> Navigate to github.com and open my repositories
> Fill out this form with the test user data
> Take a screenshot of the current page
> Click the submit button and wait for the page to load

网页抓取与测试:

> Extract all product prices from this e-commerce page
> Run through the signup flow and report any issues
> Check if the mobile menu works correctly

使用场景

  • 端到端测试:直接从Claude Code运行集成测试
  • 网页抓取:无需编写浏览器自动化代码即可从页面提取数据
  • 表单填写:自动化重复性的网页工作流
  • 视觉验证:截图并分析页面布局

Chrome集成在您现有的浏览器会话中运行,可访问您的登录状态和Cookie,便于测试需要身份验证的流程。

权限(v2.1.251+):浏览器操作始终经过Claude Code自身的权限检查,包括禁用遥测的会话(此前这类会话使用Chrome扩展自带的提示)。206自v2.1.260起,该集成还会遵循您所在组织的Claude in Chrome管理员设置:管理员将其关闭后,--chrome、/chrome和浏览器工具均不可用。212自v2.1.285起,/config chrome=true会将您引导至/config面板,而不是默认启用Claude in Chrome;/config chrome=false在其已开启时仍可将其关闭。229自v2.1.290起,项目的设置文件不再能开启Claude in Chrome;请使用--chrome、/chrome或您的用户设置。10月6日获取的设置参考文档已在全局配置范围下列出claudeInChromeDefaultEnabled(即/chrome → Enabled by default所设置的项)。235237

限制

  • 不支持多标签页:Claude仅控制当前活动标签页,无法同时跨多个标签页协调操作
  • JavaScript对话框会阻塞执行:alert()、confirm()和prompt()对话框会使扩展暂停,请避免在自动化流程中触发它们
  • 无法访问无痕模式,除非您明确在无痕模式下启用该扩展
  • WebSocket连接:如果Claude Code重启,Chrome扩展必须重新连接(通常会在几秒内自动完成)
  • 使用read_page从无障碍树获取元素引用;通过ref而非坐标进行交互

Claude Code in Slack(2025年12月)[研究预览]

Anthropic推出了Claude Code in Slack,开发者可以直接从聊天线程中委派编码任务。19

工作原理

  1. 在任意Slack频道或线程中标记@Claude
  2. 结合上下文描述编码任务
  3. Claude分析Slack消息以确定代码仓库
  4. 进度更新会显示在线程中
  5. Claude分享链接,供您审阅工作成果和已创建的PR

示例工作流

@Claude The login form validation is broken on mobile devices.
Can you fix it? Check the bug report from earlier in this thread.

Claude将会: 1. 读取线程以获取上下文 2. 识别相关的代码仓库 3. 克隆并分析代码库 4. 发布进度更新 5. 创建包含修复的PR 6. 分享PR链接供审阅

优势

  • 上下文感知:Claude会读取Slack历史记录中的错误报告、功能请求和讨论
  • 团队可见性:线程中的进度更新让所有人随时知情
  • 低门槛:无需终端或IDE,直接从聊天开始
  • GitHub集成:自动创建带有恰当描述的PR

前提条件

  • 已安装Claude应用的Slack工作区(需工作区管理员批准)
  • 已连接到Slack工作区的GitHub仓库
  • Pro、Max、Team或Enterprise套餐
  • Claude必须拥有目标仓库的写入权限(创建分支、创建PR)

限制

  • 仓库检测:Claude根据Slack上下文(频道主题、最近消息、线程内容)推断仓库。如果存在歧义,请明确指定仓库:@Claude in repo org/my-app, fix the login bug
  • 无法访问本地文件:Slack中的Claude完全在云端运行,它会克隆仓库、进行更改并创建PR,但无法访问您的本地文件系统
  • 线程上下文窗口:Claude会读取当前线程,但来自其他频道或私信的上下文有限
  • 审批流程:所有更改都经过PR审查,Claude绝不会直接推送到main
  • 速率限制:受您套餐的Claude Code用量限制约束(与CLI和网页端用量共享)

Slack集成目前面向Pro、Max、Team和Enterprise用户提供研究预览。

Claude Tag更新(v2.1.311至v2.1.317)。管理员分析新增了Skills视图,显示Claude在Slack频道中运行各个已附加skill的频率以及哪些从未被使用;在新会话中运行的例行任务(routines)在无事可报时可以直接结束,而不再发布一条无意义的消息;您自己的Slack账户可见的私有频道在管理员设置中显示锁图标而非#(v2.1.311)。频道的“Respond automatically”(自动回复)开关变为频道Configure页面和管理员设置中的“How Claude participates”(Claude如何参与)选项(v2.1.316)。新粘贴的Artifact链接会显示带有Open按钮的卡片,点击可在Claude中打开该Artifact(v2.1.317)。284


Claude in Microsoft 365(2026年5月)

2026年5月7日,Anthropic将其Microsoft 365产品从有限推出转为面向付费套餐正式发布。公告原文:“Claude for Excel、PowerPoint和Word已正式发布,Claude for Outlook现已面向所有付费套餐开放公开测试。”161

其卖点是跨应用互联的工作区。Anthropic的描述很具体:“在Excel中调整一个假设,PowerPoint中的图表和Word备忘录中的数字也会随之自动更新。”161对于Outlook,新功能是邮箱分拣:“让Claude整理您的收件箱,它会将邮件分为需要您回复的、它可以代您起草的,以及纯属噪音的。”161

可用性

  • Excel、PowerPoint、Word。正式发布。“所有付费套餐的Mac和Windows用户均可使用Claude for Microsoft 365。”161
  • Outlook。公开测试。“Claude for Outlook已在所有付费套餐上提供测试版。”161

与Claude Code的关系

Microsoft 365加载项位于Office应用内部,并路由到支撑Claude Code的同一套Claude基础设施。它们并不是Claude Code的一种使用界面(您不会从Excel中驱动CLI),但与2026年5月5日发布的智能体模板工作相辅相成:十个金融智能体模板以插件形式提供给Claude Cowork和Claude Code,同样的数据连接器和Moody’s MCP集成也可从这两种界面访问。158请将M365视为CLI的办公应用伴侣,而非替代品。


网页版 Claude Code [研究预览](2026年1月)

网页版 Claude Code 让您可以在浏览器中通过 claude.com/code 委派编码任务,任务运行在由 Anthropic 托管的云基础设施上。66 这是无需终端的 Claude Code:分派任务、跟踪进度,然后收回拉取请求。

命名(v2.1.274): 在 CLI 内部,产品名称现已改为 “云会话”(cloud session)。/status 中的 GitHub 行显示为“Cloud sessions”,/web-setup、/ultrareview 以及 teleport 相关消息也都改说“cloud session”,而不再是“网页版 Claude Code”。为保持连贯,本指南沿用原有章节标题,但凡指实际产品之处,一律称“云会话”。218

核心能力

  • 并行执行任务:在同一界面中同时启动多个跨仓库的编码任务
  • 实时进度跟踪:通过实时更新观察 Claude 处理任务的过程,并可在会话中途调整其思路
  • 自动创建 PR:Claude 生成附带清晰变更摘要的拉取请求
  • 会话传送:使用 claude --teleport 将网页会话拉取到本地终端,继续在本地工作
  • 移动端访问:iOS 和 Android 版 Claude 应用中的 Code 标签页可直接从手机启动云会话和项目280

安全架构

任务在带有网络和文件系统限制的隔离沙箱环境中执行。Git 交互经由安全代理转发,仅允许访问已授权的仓库。管理员可以配置 Claude 能够访问哪些域名(例如,允许下载 npm 包以进行测试)。66

可用性

套餐 访问权限
Pro / Max / Team 已包含(研究预览)
Enterprise 拥有高级席位或 Chat + Claude Code 席位的用户247

云会话与所有其他 Claude Code 用量(CLI、IDE、Slack)共享速率限制。

从终端连接 GitHub:/web-setup

云会话需要访问您的仓库。除了授权 Claude GitHub App 之外,已在使用 gh 的开发者可以在终端运行 /web-setup,将本地 gh CLI 令牌同步到自己的 Claude 账户;无需在仓库上安装该 App。两种访问方式都未配置时,/schedule 会提示运行 /web-setup。Team 和 Enterprise 的所有者可以在 claude.ai/admin-settings/claude-code 通过“Quick web setup”开关禁用 /web-setup;启用了零数据保留(Zero Data Retention)的组织无法使用 /web-setup 或其他云会话功能。自 v2.1.243 起,/status 会显示 GitHub 是否已为云会话连接(Pro/Max),未连接时会指向 /web-setup(v2.1.274 将该行改名为“Cloud sessions”);尚未连接 GitHub 的 claude.ai 用户会收到一条指引提示;此外,当旧版 gh(不支持 gh auth token)已完成认证时,/web-setup 不再反复要求登录。250247

网页版与终端:何时用哪个

场景 使用网页版 使用终端
Bug 积压分类处理 并行分派 5 个 bug —
离开工位时的快速修复 从手机分派 —
复杂的架构工作 — 完整的代码库上下文
自定义 hooks 和 MCP — 完整的扩展层
夜间批量任务 睡前分派,早上审阅 & 后台代理

当前限制: 会话传送仅支持单向:您可以将网页会话拉取到终端,却无法将终端会话推送到网页。66 claude --cloud 会从终端启动一个新的云会话,而不会迁移当前会话。281

项目(公开测试版,2026年9月17日)

项目是 claude.ai/code 上的一个持续对话,Claude 在其中协调一系列相关工作。您粘贴一个任务、一份 bug 报告或一个清单,Claude 便会为每项工作开启一个线程,或将其路由到已在处理该领域的线程,或就地回答一个简短问题。每个线程都是一个云会话,拥有自己的上下文窗口和分支;它会在您要求时或某项具体变更需要时打开拉取请求,然后在开启自动修复的情况下持续跟进。每个新线程都从项目的指令(最多 16,000 个字符)及其记忆出发。记忆是 Claude 以文件形式保存、由 MEMORY.md 索引的笔记,因此您只需陈述一次规则,便能传达到每个线程。Overview 面板按状态对线程分组(Ready for review、Waiting on you、Working、Landing、Idle、Resolved),并新增了 Library、Pull requests 和 Scheduled tasks 标签页。Anthropic 于2026年9月17日宣布了这次重新设计。该功能目前在 Pro 和 Max 上处于公开测试阶段,正逐步向使用过云会话的账户推出,设有候补名单,尚未登陆 Team 或 Enterprise。没有任何 CLI 发布说明提到它;文档页面和发布文章是信息来源。280

云线程会从您的仓库中读取什么,以及不会读取什么:

在每个仓库中 在云线程中
根目录下的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/ 线程启动时加载(子目录中的 CLAUDE.md 文件和路径特定规则不会加载)
.claude/skills/ 下的 skills 不加载;请改为在您的 claude.ai 账户中启用该 skill
.mcp.json 中的 MCP 服务器 不加载;线程使用您 claude.ai 账户上的连接器
.claude/settings.json 中的 plugins、权限规则、hooks 和 env 不应用;请在项目设置中添加 plugins,在线程内批准工具调用,并在云环境中设置变量

只要模型支持,线程就以自动模式运行;权限提示会在线程内部等待,在项目对话中告诉 Claude 继续并不会传达到线程。新建项目中,每个线程默认在 Opus 上以 high effort 运行,对话则以 low effort 运行;两者均可在 Project settings > General 中更改。用量计入您的套餐限额,并且消耗得更快,所有项目合计每天最多强制限制新建 200 个线程;触及五小时或每周限额的线程会暂停等待,限额重置后自动恢复。当任务需要只有您的电脑才有的东西时,可在对话中选择 Work locally:线程随后会通过 Remote Control 在您从桌面应用或用 claude remote-control 连接的文件夹中运行(在 git 仓库中加上 --spawn worktree,让每个线程拥有自己的 worktree)。这要求该机器上安装 v2.1.280 或更高版本,且在开启 Require trusted devices 期间会被阻止。项目在终端 CLI、VS Code 扩展、JetBrains 插件中均不可用,也无法通过 Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 使用;测试期间,一个项目仅属于一位用户,不支持共享。以“Reached the turn limit”停止的线程,是触到了 CLAUDE_CODE_MAX_TURNS 所设定的上限。280

云端计划任务:/schedule(原名 routines)

云端计划任务(原称 routine)是一份保存好的 Claude Code 配置(一条提示词、一个或多个仓库,以及一组连接器),它会作为云会话按以下方式运行:按计划(从每小时到每周,或在未来某个时间运行一次;可用 cron 表达式自定义节奏,但不能比每小时更频繁)、在 API 调用时(向该任务自己的 /fire 端点发送带 bearer 令牌的 HTTP POST,可附带可选的 text 字段,例如告警正文),或在 GitHub 事件(如拉取请求打开)发生时。一个任务可以组合多种触发器。可在 claude.ai/code/routines、桌面应用的 Scheduled 页面,或任意会话中用 /schedule 创建;/routines 仍作为别名保留。任务归属于您的账户,在 GitHub 和连接器上以您的身份行事,并像交互式会话一样消耗套餐用量;计划运行每个账户每小时上限 100 次,而 Run now、API 触发和重新运行一次性任务则为每个任务每小时 30 次。在 Pro、Max、Team 和 Enterprise 上均可用,处于研究预览阶段;Team 和 Enterprise 的所有者可通过 Organization settings > Capabilities > Remote sessions 下的 Scheduled tasks (Was Routines) 开关关闭此功能。282

桌面应用还增加了本地计划任务,它们在您的机器上运行,可使用您的文件和工具,但仅在应用打开且电脑处于唤醒状态时运行。三种调度器的对比如下:282

云任务 桌面任务 /loop
运行位置 Anthropic 托管的云,或自托管环境 您的机器 您的机器
需要机器开机 否 是 是
需要打开的会话 否 否 是
重启后保留 是 是 --resume 时恢复,有例外
本地文件 否(全新克隆) 是 是
MCP 服务器 按任务配置的连接器 配置文件和连接器 继承自会话
权限提示 默认自动模式 按任务可配置 继承自会话
最小间隔 1 小时 由 Claude 设置时为 1 分钟,在表单中为 1 小时 1 分钟

云会话(v2.1.311 至 v2.1.317)。 当 MCP 服务器请您访问某个 URL 时,链接卡片让您选择打开或拒绝(v2.1.317);当它请求填写表单时,表单卡片让您填写或拒绝,而不是让请求在您未察觉的情况下被取消(v2.1.316)。切换回某个会话时,消息加载期间会显示“Catching up”(v2.1.316)。在云端运行的 routine 可在其模型选择器中设置 effort 级别,设置脚本框则是带行号的 Bash 编辑器(v2.1.312)。从 CLI 启动的云会话由服务器分配名称和分支名(v2.1.312)。Anthropic 云端的计划任务会加载您 claude.ai 账户上启用的 plugins;即便设置脚本以错误退出,会话仍会启动;当已完成的一次性任务是唯一被隐藏的任务时,Scheduled tasks 页面会显示 Include completed 按钮(v2.1.314)。Enterprise 成员可以在自己的云环境中添加和删除网络机密(v2.1.316);为已有机密的主机再添加机密时会被拒绝,而不是悄然替换(v2.1.317)。新建的计划任务会在管理员选为组织默认的环境上启动(v2.1.317)。284

性能优化

降低延迟

模型选择: - Haiku:响应最快,成本最低 - Sonnet:兼顾速度与质量 - Opus:质量最佳,延迟最高

流式输出: 所有响应默认以流式方式返回,输出一经生成即可看到。

提示缓存: 默认启用。可降低重复上下文(系统提示、工具定义)的延迟。

缓存策略

Claude Code 会自动缓存系统提示和工具定义;命中缓存意味着计费的输入 token 更少、响应更快。缓存有效期(TTL)取决于您的计费方式,以及请求所属的类别:主对话(您的交互轮次、-p 运行、Agent SDK 轮次,以及与之内联运行的辅助请求)或其他所有请求(subagents、工作流、进程内队友、分叉、压缩、会话标题):248

请求类别 Claude 订阅,计划用量以内 用量额度、API 密钥或云服务商
主对话 一小时 五分钟
其他所有请求 五分钟(少数由服务器控制的辅助请求为一小时) 五分钟

订阅会话一旦超出计划所含用量、开始消耗用量额度,主对话的 TTL 便降为五分钟。两项设置(v2.1.242+)可按类别指定 TTL,取值均为 "5m" 或 "1h":promptCacheTtl 用于主对话,subagentPromptCacheTtl 用于其他所有请求;对应的环境变量分别为 CLAUDE_CODE_PROMPT_CACHE_TTL 和 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL。当多项控制同时适用时,以最先匹配者为准:依次为 FORCE_PROMPT_CACHING_5M=1、该类别的环境变量、该类别的设置、ENABLE_PROMPT_CACHING_1H=1,最后是上表中的类别默认值。一小时 TTL 的缓存写入按更高费率计费,因此对于空闲超过五分钟的会话较为划算,而对于从不出现长时间空闲的短时突发会话,反而会增加成本。250248

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

多轮对话会缓存之前轮次中的思考块。

如有需要,可按模型禁用缓存:

export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1

并行操作

Subagent 并行化: 多个 subagents 可以同时运行。每个 subagent 独立工作,不会污染主上下文。

后台 bash: 长时间运行的命令不会阻塞对话:

> run the full test suite in the background

自 v2.1.285 起,后台命令会在达到其 timeout(默认 30 分钟,最长 2 小时)时停止,并在停止时通知 Claude。229

Git worktrees(v2.1.49+): 在隔离的 git worktree 中启动 Claude,即可并行工作而不影响主工作树:

claude --worktree            # or -w; creates worktree in .claude/worktrees/
claude -w --name feature-x   # Named worktree

Subagents 的定义中同样支持 isolation: "worktree",为每个 subagent 提供一份隔离的仓库副本;若未做任何更改,该副本会被自动清理。96 ExitWorktree 工具允许 agent 以编程方式退出 worktree 会话(v2.1.72+)。114 对于非 git 的版本控制系统,可配置 WorktreeCreate/WorktreeRemove hooks 来处理自定义的创建与清理流程。96

面向 monorepo 的稀疏 worktree(v2.1.76+): worktree.sparsePaths 设置可为大型 monorepo 中的 worktree 启用 git sparse-checkout,只检出您指定的路径,而非整个仓库:118

{
  "worktree": {
    "sparsePaths": ["packages/my-service", "shared/utils"]
  }
}

跨 worktree 共享状态(v2.1.63+): 项目配置(.claude/settings.json)和自动记忆现已在同一仓库的各个 git worktree 之间共享。在某个 worktree 中对设置或记忆所做的更改,在其他所有 worktree 中均可见。104

worktree.baseRef 设置(v2.1.133+,默认行为存在破坏性变更): 控制 --worktree、EnterWorktree 以及 agent 隔离 worktree 从何处创建分支。共有两个取值:160

  • "fresh"(新默认值):从 origin/<default> 创建分支。此举撤销了 v2.1.128 的行为变更。创建 worktree 时,所有未推送的本地提交都不会被带入。
  • "head":从本地 HEAD 创建分支。如果希望新 worktree 中包含未推送的提交,则必须使用此值。
{
  "worktree": {
    "baseRef": "head"
  }
}

操作提示: 如果您已习惯 v2.1.128–v2.1.132 将未推送工作带入新 worktree 的行为,请在升级前设置 worktree.baseRef: "head",否则您的 EnterWorktree worktree 会悄无声息地改为从 origin/<default> 开始。160

会话中途切换 worktree(v2.1.157+)。 EnterWorktree 现在可以在会话中途于 Claude 管理的各个 worktree 之间切换,而不仅仅是进入一个新的 worktree。当 agent 需要在两个并行分支之间来回切换而又不想重启时,这一功能十分实用。此外,agent 完成工作后,后台 worktree 会保持未锁定状态,因此 git worktree remove / git worktree prune 不会再因残留的锁而失败。266

内存优化

  • 明确引用文件:使用 @src/auth.ts,而不是”找到 auth 文件”
  • 定向搜索:说”在 src/api 中搜索”,而不是”到处搜索”
  • 开启新会话:在不相关的任务之间使用 /clear
  • 自定义压缩:在 CLAUDE.md 中添加说明,指明需要保留的内容
  • 工具结果持久化到磁盘(v2.1.51+):超过 50K 字符的工具结果现在会持久化到磁盘(阈值由 100K 下调),从而减少上下文窗口占用,并在长会话中延长对话寿命98
  • BashTool 跳过登录 shell(v2.1.51+):当 shell 快照可用时,BashTool 现在默认跳过登录 shell 的 -l 标志,提升命令执行性能。此前需要设置 CLAUDE_BASH_NO_LOGIN=true98

如何调试问题?

安装问题

WSL 路径问题:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check
which npm  # Should start with /usr not /mnt/c

Node 版本冲突(nvm): 添加到 ~/.bashrc 或 ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

权限错误: 请使用原生安装方式,而非 npm:

curl -fsSL https://claude.ai/install.sh | bash

认证问题

# Complete reset
/logout
rm -rf ~/.config/claude-code/auth.json
claude  # Fresh login

性能问题

CPU/内存占用过高: - 使用 /compact 缩减上下文 - 在大型任务之间重启 - 将大型目录添加到 .gitignore - 运行 claude doctor

搜索缓慢: 安装系统级 ripgrep:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux
sudo apt install ripgrep

然后:

export USE_BUILTIN_RIPGREP=0

在 WSL 上运行缓慢: - 将项目迁移到 Linux 文件系统(而非 /mnt/c/) - 在搜索中使用具体的目录过滤条件

IDE 集成问题

未检测到 JetBrains(WSL2):

方案 1 - Windows 防火墙:

wsl hostname -I  # Get WSL IP
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16

方案 2 - 镜像网络(添加到 ~/.wslconfig):

[wsl2]
networkingMode=mirrored

然后执行:wsl --shutdown

Escape 键在 JetBrains 中无效: Settings → Tools → Terminal → 取消勾选”Move focus to the editor with Escape”

认证管理(v2.1.41+)

claude auth login                # Log in or switch accounts
claude auth status               # Check current authentication state
claude auth logout               # Log out and clear stored credentials

在 API 密钥与 OAuth 之间切换,或在不同组织之间切换时,可使用 claude auth logout && claude auth login 重置认证。

调试模式

claude --debug                    # Full debug output
ANTHROPIC_LOG=debug claude       # API request logging
claude doctor                    # Health check
/debug                           # Troubleshoot current session (v2.1.30+)

/debug 命令(v2.1.30+)提供针对当前会话的诊断信息,包括: - 当前模型与上下文用量 - 活跃的 MCP 服务器及其状态 - 权限状态与近期的拒绝记录 - 内存压力指标

重置配置

# Reset user settings
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project settings
rm -rf .claude/
rm .mcp.json

如需清除 Claude Code 为某个项目保存的本地状态,同时不影响其他项目,请使用 claude purge:它会先列出清理计划并请求确认,随后删除该项目的对话记录和自动记忆、任务、调试及文件编辑历史条目、提示历史记录行,以及该项目在 ~/.claude.json 中的条目。--dry-run 用于预览,-y 跳过确认,--all 则覆盖所有项目。在 v2.1.288 之前,该命令为 claude project purge;旧名称仍然可用,但会输出一条提示。234237

claude purge ~/work/my-repo --dry-run   # Preview what would be deleted
claude purge ~/work/my-repo             # Delete after one confirmation

常见错误信息

错误 原因 解决方法
“Rate limit exceeded” 请求过多 稍候再试或降低请求频率
“Context length exceeded” 对话过长 使用 /compact 或 /clear
“Authentication failed” token 无效或已过期 运行 claude auth login
“Tool not permitted” 权限被拒绝 检查 settings.json 中的权限配置
“MCP server failed to start” 服务器配置有误 检查 claude mcp get <name>

深入底层:源代码揭示了什么

2026年3月,一个 Bun 构建缺陷导致 Claude Code npm 包附带了 source map,完整可读的源代码随之泄露。133 该包虽被迅速撤下,社区仍对其内部机制做了深入分析。其中若干发现对 harness 构建者有直接参考价值。

Auto Mode 分类器(yoloClassifier.ts)

auto mode 权限系统实现在一个 1,495 行的文件中,内部命名为 yoloClassifier.ts。134 它以一次独立的 ML 模型调用(Sonnet 4.6)运行,结合对话上下文评估每一次工具调用。这意味着 auto mode 会为每次工具调用额外增加一次分类器推理。对于高吞吐量的自动化场景,这项延迟与成本开销值得留意。分类器检查的是该操作是否符合用户声明的意图,而不仅仅是命令本身是否“安全”。

Bash 安全:23 项检查,源于真实事件

bash 校验模块(bashSecurity.ts)长达 2,592 行,包含 23 项编号的安全检查。133 主要防御措施包括:

攻击向量 防御措施
Zsh =cmd 展开 拦截 =curl、=wget 等
zmodload 入口 拦截 18 个 Zsh 内置命令
Heredoc 注入 逐行内容匹配
ANSI-C 引用($'\x41') 模式检测
进程替换(<()、>()) 在不可信上下文中拦截
Unicode 零宽空格 注入检测
ztcp 数据外泄 拦截网络原语

如此细致的防御表明,每一项检查背后都有真实事件,绝非纸上谈兵。

Prompt 缓存架构

promptCacheBreakDetection.ts 追踪 14 种不同的缓存失效向量,并通过“粘性锁存”(sticky latches)防止模式切换导致缓存失效。134 实际影响是:调整 CLAUDE.md 中各节的顺序、在会话中途切换 extended thinking,或更改 MCP 服务器配置,都可能严重拉低 prompt 缓存命中率。为获得最佳缓存性能,请在单个会话内保持系统提示词稳定。

Autocompact 熔断机制

一条源码注释揭示了此前问题的规模:“1,279 个会话出现 50 次以上连续 autocompact 失败(单个会话最多达 3,272 次),每天浪费约 25 万次 API 调用。”133 修复方案是 MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3,超过该次数后 autocompact 即停止并报错。如果您反复遇到压缩失败,原因就在于此:系统现在会主动停止,而不是继续消耗 token。

Coordinator 模式:以提示词为架构

多智能体协调(coordinatorMode.ts)完全以系统提示词指令实现,而非代码层面的编排。134 编排模型接收一段提示词,说明如何委派、汇总与综合,这印证了“以提示词为架构”的模式。coordinator 提示词中包含这样一条指令:“切勿写‘根据你的发现’——这类措辞把理解工作推给了 worker,而不是由你亲自完成。”

挫败感检测

userPromptKeywords.ts 通过对粗话进行正则模式匹配来检测用户的挫败情绪,而非借助 LLM 推理。133 这比调用模型更快、成本更低。一旦触发,Claude 会调整行为,变得更谨慎、更明确、更顺从。如果您注意到在表达不满后 Claude 变得更加小心,背后正是这一机制。

对 Harness 构建者的启示

这些内部机制印证了若干 harness 模式:

  1. Auto mode 的分类器是一次独立的模型调用:在估算自主工作流的成本和延迟时,务必将其计入
  2. bash 安全防护层次很深:您的 PreToolUse hooks 是对内置 23 项检查的补充,而非替代
  3. Prompt 缓存十分脆弱:设计 CLAUDE.md 和规则文件时应以稳定为先,避免在会话中途频繁修改
  4. 多智能体协调由提示词驱动:coordinator 模式在 Anthropic 的规模下行之有效,证明系统提示词足以编排复杂的智能体工作流
  5. Autocompact 有硬性上限:如果您的会话陷入压缩循环,系统会在 3 次失败后停止,而不会无限消耗 token

质量事后复盘(2026年4月23日)

Anthropic 于4月23日发布了一份工程事后复盘,涵盖三起相互独立、却在3月至4月初叠加放大的质量退化问题。三者均已于4月20日(v2.1.116)解决,所有订阅用户的用量限额也已重置。153

问题 持续时间 受影响模型 根本原因 解决方式
推理强度默认值 3月4日 → 4月7日 Sonnet 4.6、Opus 4.6 为减少 UI 卡顿,默认值从 high 下调至 medium。但用户更看重更高的智能水平,而非 UI 流畅度。 4月7日回滚。(另外,4月22日发布的 v2.1.117 为使用 4.6 模型的 Pro/Max 用户恢复了 high 默认值;Opus 4.7 发布时即为 xhigh。)
Prompt 缓存 thinking 清除缺陷 3月26日 → 4月10日 Sonnet 4.6、Opus 4.6 一项缓存优化原本只应在会话空闲时清除一次 thinking,实际却在此后会话的每一轮都清除。导致健忘、重复以及用量消耗加快。 已在 v2.1.101(4月10日)修复。
系统提示词简洁性约束 4月16日 → 4月20日 Sonnet 4.6、Opus 4.6、Opus 4.7 为抑制 Opus 4.7 过于啰嗦而添加;据 Anthropic 称,这使 Opus 4.6 和 Opus 4.7 的编码质量下降约 3%(Sonnet 4.6 上测得的降幅较小)。 已在 v2.1.116(4月20日)回滚。

给用户的要点。 尤其是缓存清除缺陷,在长达 15 天的时间里悄无声息地拖累了长会话。如果您在3月下旬至4月中旬之间感觉会话突然变得健忘,请知悉这并非您的操作失误。Anthropic 公布的改进措施包括:更全面的发布前评估套件、更严格的系统提示词变更管控、对影响智能表现的变更强制进行代码审查,以及对任何涉及模型行为的改动采用渐进式发布。

企业部署

云服务商对比

功能 Anthropic 直连 AWS Bedrock Google Vertex Microsoft Foundry
认证 API 密钥 IAM/API 密钥 GCP 凭据 Entra ID/API 密钥
成本跟踪 控制台 AWS Cost Explorer GCP Billing Azure Cost Mgmt
审计日志 有限 CloudTrail Cloud Audit Logs Azure Monitor
SSO 否 IAM IAM Entra ID
自 v2.1.207 起,AWS Bedrock、Google Cloud 的 Agent Platform(原 Vertex AI)以及 AWS 上的 Claude Platform 的会话默认使用 Claude Opus 4.8——该默认值在 v2.1.219 被取代,三者全部改为 Claude Opus 5,并在 v2.1.280 再次更改为 Claude Opus 5.5207221;同时,在 Bedrock、Vertex AI 或 Microsoft Foundry 上,Auto Mode 不再需要通过 CLAUDE_CODE_ENABLE_AUTO_MODE 显式启用(管理员可通过 disableAutoMode 托管设置将其禁用)。185

托管设置部署

通过 managed-settings.json 部署覆盖全组织的策略:

位置: - macOS: /Library/Application Support/ClaudeCode/managed-settings.json - Linux: /etc/claude-code/managed-settings.json - Windows: C:\Program Files\ClaudeCode\managed-settings.json

策略示例:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)",
      "Read(.env*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  },
  "model": "claude-opus-5-5",
  "disableBypassPermissionsMode": "disable",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true
}

仅限托管设置的键:

键 作用
allowManagedPermissionRulesOnly 禁止用户/项目设置定义权限规则;仅托管规则生效
allowManagedHooksOnly 禁止加载用户/项目/插件 hooks;仅运行托管 hooks 和 SDK hooks
allowAllClaudeAiMcps 企业设置,用于在 managed-mcp.json 之外同时加载 claude.ai 云端 MCP 连接器(v2.1.149+)
allowClaudeInChromeWithManagedMcp 允许 claude --chrome 与独占模式的 managed-mcp.json 并行运行(v2.1.282+)
deniedModels / availableModelsMatch 即使 availableModels 允许,也可屏蔽特定模型;"exact" 将每个 availableModels 条目限定为其指定的版本(v2.1.283+)
allowedProviders 限制某台机器可使用的 API 提供商:Anthropic API、自定义端点、Bedrock、Mantle、Vertex AI、Foundry、AWS 上的 Claude Platform 或 Cloud 网关(v2.1.285+)
strictKnownMarketplaces 插件市场允许列表(空数组 = 完全锁定)。自 v2.1.223 起,条目支持 "owner/*" 通配符,可一次性允许某个 GitHub 组织下的全部市场仓库——只需一行,无需逐个枚举仓库,且该组织下新建的仓库会自动纳入。blockedMarketplaces 采用同样的通配符形式。v2.1.232 新增了更友好的别名:此键可写作 allowedMarketplaces,extraKnownMarketplaces 可写作 additionalMarketplaces;GitLab 仓库 URL(包括嵌套子组)也可作为市场来源。200255
allowedMcpServers 用户可配置的 MCP 服务器允许列表(空数组 = 完全锁定)。自 v2.1.259 起,它仅管控用户自行添加的服务器——不再过滤托管提供的字面条目,因此以前被允许列表拦住的托管服务器在升级后会重新加载;请改用 deniedMcpServers211 自 v2.1.305 起,它也不再过滤仅在 env 中使用 ${VAR} 的 managed-mcp.json stdio 服务器,因此允许列表未包含的此类服务器在升级后会被加载;请使用 deniedMcpServers 将其拦下278
deniedMcpServers MCP 服务器拒绝列表(优先级高于允许列表)
managedMcpServers 向每位用户提供 HTTP/SSE MCP 服务器,条目格式与 .mcp.json 相同;指定了可执行命令的条目会被跳过(v2.1.259+)211
disableBypassPermissionsMode 禁止使用 --dangerously-skip-permissions
disableAutoMode 在全组织范围内禁用 Auto Mode——既然网关用户不再通过环境变量显式启用,这便是管理员侧的控制手段(v2.1.207+)185
forceLoginMethod 限制用户的认证方式。自 v2.1.212 起,其强制范围不再局限于终端:VS Code 扩展、SDK、claude setup-token 和 /install-github-app 均会遵守该设置(此前仅终端生效)189。自 v2.1.261 起,"gateway" 还会清除残留凭据:固定到 Claude apps 网关的机器会忽略遗留的 API 密钥或 claude.ai 登录,转而要求执行 /login;Bedrock、Vertex AI 和 Foundry 会话不受影响214。自 v2.1.265 起,托管设置中包含 forceLoginGatewayUrl 的机器同样从启动起就是 Claude apps 网关会话——遗留的 claude.ai 登录或 API 密钥不会被使用215
gatewayInternalNetworks 允许 /login 登录到位于组织自有公网 IPv4 地址段上的 Claude apps 网关(v2.1.268+)216
modelPricing 合同约定的各模型费率及折扣系数;/cost、状态栏和遥测成本数据将采用这些数值而非标价(v2.1.243+)250;自 v2.1.271 起,该系数可以大于 1,最高至 10,用于加价的内部成本分摊费率——Claude apps 网关的 pricing 块也接受同样的设置216
disableSkillShellExecution 禁止在 skills、自定义命令和插件命令中内联执行 shell136
forceRemoteSettingsRefresh 在重新获取远程托管设置之前阻止启动;获取失败则退出(失败即关闭)137
parentSettingsBehavior 管理员层级的键("first-wins" \| "merge"),可让 SDK 的 managedSettings(父层级)参与策略合并,而不是在默认的”先到先得”规则下被覆盖(v2.1.133+)160
用户无法覆盖托管设置。托管设置在配置层级中拥有最高优先级。

管理控制台的控制同样作用于 CLI:自 v2.1.260 起,Claude Code 会遵循组织的 Claude in Chrome 管理设置——管理员关闭后,成员会话中的 --chrome、/chrome 和浏览器工具均不可用(请参阅 Claude in Chrome)。212

Claude apps 网关加固(v2.1.268):gatewayInternalNetworks 托管设置允许管理员放行 /login 登录到位于组织自有公网 IPv4 地址段上的网关;access_control.allow_cidrs 为空的网关现在会在启动时发出警告,并在首次收到来自公网地址的请求时再警告一次;而在 gateway.yaml 中设置了 pricing: 后,已登录的 Claude Code 客户端会通过托管设置收到相同的费率,使 /cost 和遥测数据与网关的支出计量保持一致。216

位于正向代理之后的 Claude apps 网关(v2.1.277):为处于封闭网络中的网关新增两项功能。CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 适用于唯一出口是正向代理的网关:每个出站请求都将主机名交由代理解析,而不是在本地解析,因此即使网关主机没有直接的对外路由——也无法解析外部域名的 DNS——仍可通过代理访问各提供商。此外,网关的上游(upstream)支持可选的 headers: 映射,可向您部署在提供商前方的代理发送静态请求头——这正是为依赖自有请求头进行认证或路由的代理准备的接入方式。同一版本还改进了网关的回环错误消息,使其明确提及 CLAUDE_GATEWAY_ALLOW_LOOPBACK,并修复了设置代理后网关遥测中继忽略 NO_PROXY 中所列收集器主机名或域名的问题。219

Claude apps 网关新增功能(v2.1.281):Bedrock 上游支持 assume_role,网关可借此以通过 STS 代入的 IAM 角色身份调用 Bedrock,必要时可跨 AWS 账户,并可选择为每位开发者使用独立会话;还支持 guardrail: {id, version},可对经由这些上游发送的每个请求应用 Amazon Bedrock 防护栏(须在所有 Bedrock 上游上统一设置,或全部不设)。telemetry.resource_attributes 可为 Claude Desktop 和 /login 会话的遥测数据添加固定标签;desktop 策略块支持更新的 Claude Desktop 键,包括 blockReadsOutsideWorkingDirectories 和 disableBypassPermissionsMode。当某个 managedMcpServers 条目的 envHelper 路径以 \??\ 或 /??/ 开头时,网关现在会拒绝启动——当前版本的 Claude Desktop 也拒绝运行这种路径形式。224 Claude apps gateway 新增功能(v2.1.312 至 v2.1.317): oidc.user_id_claim 可通过 sub 以外的 id_token 声明来识别用户,例如 Microsoft Entra ID 的 oid(v2.1.312)。上游可选的 groups 列表使其只接收所列 IdP 组中开发者的请求,故障转移时亦然;在 Bedrock 上游的 guardrail 旁设置 guardrail_trace: true,会记录某次请求触发了哪个 Amazon Bedrock guardrail 过滤器,但不记录匹配到的文本(v2.1.314)。支出限额管理 API 上的 pooled_budget 为一个组提供一份由成员共享的月度预算,叠加在每位成员自身的限额之上;managed.policy_mode: layered 会应用与某位开发者匹配的每一条策略,每条策略都合并覆盖在其下方列出的策略之上(此前用户只会得到第一条匹配的策略),而早于 v2.1.316 的网关在发现该键时会拒绝启动;guardrail.input_tagging 则用 Bedrock guardrail 的提示词攻击过滤器所需的输入标签包裹提示词,设为 all_messages_and_system 时系统提示词也会被加上标签(v2.1.316)。管理 API 上的 GET /v1/organizations/analytics/cost 可按日期范围报告历史支出,支持按总计、按开发者、按天或按 IdP 组统计,数据来源于每位开发者所属组的每日记录,该记录在设置了 admin: 的网关上保留 admin.identity_retention_days 天(默认 90 天)(v2.1.317)。网关还会将请求中指定的每个模型与 availableModels、deniedModels 和 models 逐一核对,不符时返回 400 并指明相应字段(v2.1.316);并且不再隐藏 Bedrock 的 “Input is too long.” 错误,此前该问题曾导致会话直接失败而不是进行压缩(v2.1.317)。参考:Claude apps gateway 配置。284285

平台原生部署(v2.1.51+): 除 JSON 文件外,托管设置还可以通过 macOS 属性列表(plist)或 Windows 注册表进行部署,从而与现有的 MDM(移动设备管理)和组策略基础设施集成:107

  • macOS plist: 通过 MDM 配置描述文件部署,或使用 defaults write 写入 com.anthropic.claude-code 域
  • Windows 注册表: 通过组策略部署到 HKLM\SOFTWARE\Policies\ClaudeCode 下

哪个托管来源优先生效: 默认情况下,各来源不会被合并(可选的合并方式请参阅下文的 managedSourcesBehavior)。当存在多个托管来源时,Claude Code 按以下顺序采用第一个至少提供了一个策略键的来源,并忽略其余来源(少数跨来源的键除外,例如沙箱锁定项、forceRemoteSettingsRefresh 以及按变量逐项合并的 env,这些仍会从每个管理员来源读取):248

  1. 来自 claude.ai 的远程设置(服务器托管设置)或 Claude apps gateway 的设置,仅当会话直接向 Anthropic 的 API 进行身份验证,或通过 /login 登录网关时才会获取
  2. MDM 或操作系统级策略:macOS plist 或 HKLM 注册表项
  3. 托管设置文件:managed-settings.d/*.json 与 managed-settings.json,二者合并在一起
  4. Windows 上的 HKCU 注册表(启用 wslInheritsWindowsSettings 后在 WSL 上同样适用),仅当上述来源均未提供策略键时才会读取

仅包含控制键 wslInheritsWindowsSettings 的文件或策略不计入其中,Claude Code 会继续检查下一个来源。对于被跳过的来源,它不会显示任何警告;自 v2.1.243 起,/status 会打印一行 Skipped sources,列出那些虽然存在但因更高优先级的来源处于活动状态而未被应用的托管来源(例如位于 MDM plist 之下的 managed-settings.json)。250

v2.1.273 填补了这一机制中的一个强制执行漏洞:通过 MDM 或 managed-settings.json 设置的 allowManagedMcpServersOnly、deniedMcpServers 和 disableClaudeAiConnectors,在同时存在服务器托管设置时曾被忽略;如今即使两个来源同时处于活动状态,MCP 与连接器锁定也能保持生效。217

选择启用合并:managedSourcesBehavior: "merge"。 “首个来源优先”只是默认行为。将控制键 managedSourcesBehavior 设为 "merge" 后,所有管理员来源将被组合在一起:大多数键以排名更高的来源为准,列表类型的键取各来源的并集,沙箱锁定项则采用任一来源所设的最严格值。有两个细节保证了合并结果可预测:其一,每个键都从设置了它的排名最高的来源中整体读取,v2.1.257 将这一规则扩展到了 sandbox.credentials.awsPairs 和 sandbox.ripgrep,二者此前会跨来源合并条目;其二,managedSourcesBehavior 本身是控制键而非策略键,因此仅设置了它的来源不算提供了策略。211244

诊断与安全审批对话框(v2.1.248–251): 服务器托管设置加载失败时现在会产生启动警告,/doctor 和 /status 会解释加载失败的原因,或说明为何根本没有获取这些设置:Bedrock/Vertex/第三方提供商会话,或自定义的 ANTHROPIC_BASE_URL,从不获取这些设置(v2.1.248)。针对高风险托管设置的审批对话框在 v2.1.251 中进一步收紧:凡是终止沙箱 TLS、将沙箱流量经由您自己的代理转发、注入凭据或削弱沙箱隔离的服务器托管设置,现在都需要经您批准后才会生效;来自托管设置或项目设置的 ANTHROPIC_CUSTOM_HEADERS,若设置了凭据、组织/租户、路由或影响 API 行为的标头(例如 Authorization 或 Host),同样需要审批。该对话框只列出自您上次批准以来发生变化的设置;若设置未变,再次登录同一 Claude apps gateway 后不会重复弹出;客户端超时、MCP 启动模式和流监控(stream-watchdog)环境变量则完全不再触发它(v2.1.248)。206 自 v2.1.259 起,无法解析的托管设置来源会使 Claude Code 拒绝启动,并指明出问题的来源;此前格式错误的来源会被悄然忽略而不予执行,对策略机制而言这是错误的失败模式。211 v2.1.260 则将一项设置移出了该对话框:托管的 CLAUDE.md(即 claudeMd 设置)不再触发安全审批对话框;hooks、shell 命令、沙箱和不安全的 env 设置仍需审批。212

免审批提示的服务器托管设置(v2.1.314 至 v2.1.317): 对于 Team 和 Enterprise 登录,从 Anthropic 的 API 获取的设置现在无需审批提示即可生效,而无法通过校验的本地存储副本会被拒绝(v2.1.316)。Claude 的文件工具在编辑您所在组织的服务器托管设置的本地副本前会先征求确认,与处理您自己的设置文件时一致(v2.1.314)。仅在远程托管设置中设置的 forceRemoteSettingsRefresh,在存储副本过期后仍会继续生效;此前在无法连接服务器时,这一问题曾让会话在没有策略的情况下启动(v2.1.314)。桌面应用的 Code 标签页会在组织的远程托管设置尚未为本次会话加载完成时显示一条通知,加载完成后再显示另一条(v2.1.317)。所有者可在 claude.ai 控制台中配置这些设置;对应的文档页面为配置服务器托管设置。284285

企业启动器:processWrapper(v2.1.208)

对于要求受管终端上的每个进程都必须经由安全或监控垫片(shim)启动的组织,现在可以让 Claude Code 的自行派生的进程也走这条路径。processWrapper 设置(或 CLAUDE_CODE_PROCESS_WRAPPER 环境变量)指定一个包装器可执行文件,Claude Code 会在为自身派生所有进程时调用它,从而无需修补 CLI 即可实现 EDR 归因、进程级策略和企业启动器集成。Anthropic 在专门的企业启动器页面中记录了这一模式。186

企业级 CLAUDE.md

部署覆盖整个组织的上下文:

位置: - macOS:/Library/Application Support/ClaudeCode/CLAUDE.md - Linux:/etc/claude-code/CLAUDE.md

内容:

# Company Standards

## Security Requirements
- Never commit secrets or credentials
- All external API calls require security review
- Use parameterized queries for all database access

## Code Standards
- Follow company style guide at @docs/STYLE.md
- All PRs require two approvals
- Test coverage minimum: 80%

## Approved Tools
- npm, yarn, pnpm for package management
- Jest for testing
- ESLint + Prettier for formatting

推广策略

  1. 从文档入手:在部署前先把 CLAUDE.md 打磨好
  2. 试点小组:从 5-10 名开发者开始
  3. 问答阶段:让试点人员使用 Claude 进行代码探索
  4. 引导式开发:逐步过渡到小型 bug 修复
  5. 全面部署:配合托管设置全面推广
  6. 成本监控:跟踪各团队的用量

审计与合规

数据处理: - 会话记录默认存储在本地(除 API 调用外,没有任何数据离开本机) - API 请求直接发送至 api.anthropic.com,或经由您的云服务商(Bedrock/Vertex/Foundry)转发 - Anthropic 的商业条款明确声明,API 的输入和输出不会用于模型训练 - 如有数据驻留要求,可使用 Bedrock(AWS 区域)或 Vertex(GCP 区域),将 API 流量限定在特定地理区域内

SSO 与身份认证: - Anthropic 直连:通过 claude login 进行基于 OAuth 的身份验证(不支持 SAML/SSO;如有 SSO 需求,请使用云服务商) - AWS Bedrock:IAM 角色,并可通过 AWS IAM Identity Center 实现 SSO - Google Vertex:GCP IAM,配合 Workforce Identity Federation 支持 SAML/OIDC - Microsoft Foundry:Entra ID,原生支持 SSO

合规框架: - Anthropic 发布 SOC 2 Type II 报告(签署 NDA 后可通过销售团队获取) - 云服务商(AWS、GCP、Azure)持有各自的合规认证(SOC 2、HIPAA BAA、ISO 27001、FedRAMP),经由它们路由即可继承其合规态势 - 对于受监管行业(医疗、金融),应通过签有相应 BAA 或合规附录的云服务商路由,而不要直接使用 API

日志与监控: - 使用云服务商的日志服务进行企业审计(CloudTrail、Cloud Audit Logs、Azure Monitor) - 可以考虑使用 LiteLLM 代理,对各团队的使用情况进行精细追踪 - 托管设置可强制执行合规策略 - Analytics API 提供每位用户的每日使用量汇总(见下文)

Analytics API(管理员)

Enterprise 和 Team 套餐可使用 Claude Code Analytics API,以编程方式追踪使用情况。

端点: GET /v1/organizations/usage_report/claude_code

身份验证: 需要 Admin API 密钥(sk-ant-admin...),由组织管理员在 Console 中创建。

可用指标:

类别 指标
生产力 每位用户的会话数、新增/删除行数、提交数、PR 数
工具使用 按工具(Edit、Write、NotebookEdit)统计的接受/拒绝率
成本 按用户和模型划分的预估成本明细
请求参数:
- starting_at - 每日汇总的日期(YYYY-MM-DD)
- 返回指定日期的用户级数据

示例:

curl -X GET "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-25" \
  -H "x-api-key: sk-ant-admin-..." \
  -H "anthropic-version: 2023-06-01"

限制: - 仅提供每日汇总(为保证一致性,约有 1 小时延迟) - 如需实时监控,请使用 OpenTelemetry 集成 - 仅追踪第一方 API 的使用情况(不含 Bedrock/Vertex)

成本: 拥有 Admin API 访问权限的组织可免费使用。


键盘快捷键参考

通用控制

快捷键 操作
Ctrl+C 取消当前操作
Ctrl+D 退出会话(EOF)
Ctrl+L 清屏(保留历史记录)
Ctrl+O 切换详细输出
Ctrl+R 搜索命令历史
Ctrl+V 从剪贴板粘贴图片
Ctrl+B 将当前操作转入后台
Ctrl+Enter(或 Ctrl+X Ctrl+S 组合键) 立即发送:一次性发送所有排队消息;已发送和排队的文本在模型接收前显示为灰色(v2.1.275+)。自 v2.1.281 起,正在运行的工具会转入后台,而不是取消当前轮次218224
Ctrl+X Ctrl+K 终止所有后台 agent(组合键;v2.1.83 中由 Ctrl+F 改绑而来;自 v2.1.265 起,第二个键有 3 秒的等待窗口)
Ctrl+Y Yank(从 kill ring 粘贴)
Ctrl+S 暂存提示词草稿(保存当前输入)
Alt+Y Yank-pop(在 Ctrl+Y 之后循环切换 kill ring)
Esc Esc 回退上一次更改
Tab 接受提示词建议
! + Tab Bash 历史自动补全(v2.1.14+)
Shift+Tab 循环切换权限模式
Alt+P / Option+P 输入提示词时切换模型
Alt+T 切换思考模式(更安全的替代方式)
Ctrl+T 在 /theme 中切换语法高亮
Ctrl+G 打开外部编辑器(在 AskUserQuestion 的”Other”输入中)
Shift+Down 循环切换 agent team 队友(循环往复,v2.1.47+)
Up/Down 浏览命令历史
Up(在 Ctrl+C 之后的空提示符上) 找回被 Ctrl+C 清除的草稿,包括粘贴的文本和图片(v2.1.288);自 v2.1.292 起,执行斜杠命令或发送消息后仍可找回234236
? 显示快捷键

可自定义键位绑定(v2.1.18+):运行 /keybindings 即可自定义键盘快捷键。支持特定上下文绑定、组合键序列(多键组合)以及完全个性化配置。Claude Code 将键位绑定存储在 ~/.claude/keybindings.json 中。完整配置参考请参阅键位绑定文档。70 自 v2.1.261 起,readline 单词编辑成为提示符唯一的编辑方式,与 Bash 保持一致:Ctrl+W 向后删除至空白字符,Alt+F 和 Alt+D 停在单词末尾,标点符号也作为单词分隔符——keybindingFlavor 设置已不再生效。214 为使用旧版本的读者梳理一下历史:v2.1.238 以可选方式推出该设置("readline" 对比当时默认的 "classic",覆盖 Ctrl+W),246 v2.1.239 将 "readline" 扩展到单词按键(Alt+F 和 Ctrl/Option+→ 停在单词末尾,Alt+D 删除至单词末尾,Ctrl+Y 将其粘贴回来),205 v2.1.261 则将该方式设为所有人的默认值并废弃了这一开关。214 此外,自 v2.1.265 起,双键组合会等待第二个键 3 秒,超时时显示提示——此前等待窗口仅为 1 秒且取消时毫无提示,因此在 tmux 下输入的组合键(第二个键可能延迟到达)会无声无息地消失。215 v2.1.269 还修复了 v2.1.247 在终端按键处理中引入的一系列回归问题——kitty 协议终端中的 F1/F2/F4、st 中的 Delete、rxvt-unicode 中 Alt+方向键被当作 Escape、WezTerm 中 Shift+标点输入的是未按 Shift 的字符——并改进了 SSH 及无法识别的终端中的键盘支持:响应 kitty 键盘查询的终端(foot、Alacritty 0.16+)现在可以使用 Shift+Enter 和 Ctrl+Shift 快捷键。216

对话框按键(v2.1.280)。在对话框中,Enter 表示确认,Esc 表示取消;误输入的 y 或 n 不再会确认或关闭对话框,因此预输入缓冲区中残留的字符无法替您回答尚未阅读的提示(如需恢复单键应答,可在 keybindings.json 中将 y/n 绑定到 confirm:yes/confirm:no)。连按两次 Ctrl+C 或 Ctrl+D 现在会关闭对话框,而不是退出 Claude Code;对话框中的文本框会保留输入的每个字母、数字和空格;在 /config 以及 /model 等选择列表中,Home/End 可跳转到第一项和最后一项。220

两项影响范围切实的文本处理修复(v2.1.280)。v2.1.278 为提示词新增的不可见字符清理功能曾剥离零宽不连字(ZWNJ,U+200C)——波斯语和阿拉伯语文本用这个字符将后缀附加到拉丁单词或数字上,例如”PDF”的复数形式。它并非不可见格式攻击,而是书写系统中字母层面的组成部分,删除它会悄无声息地破坏提示词。现在该字符会被保留。另外,在 Windows 终端中,按 Enter 移除不可见字符后,提示行可能一直保持显示错乱;现在屏幕会重新绘制,确保您所检查的内容与实际发送的内容完全一致。220

语音听写会按指令停止(v2.1.280)。此前 Ctrl+C 会清空提示词,但麦克风仍在录音;转录仍在处理时 Esc 无法取消;在转录视图和 vim NORMAL 模式下按住空格会启动听写。三个问题均已修复。其中第一个最为关键:停止键清除了可见文本而麦克风仍处于开启状态,这是隐私漏洞,而非单纯的界面瑕疵。220

提示词建议(2025年12月):Claude 现在会推荐提示词,帮助您加快工作流程。按 Tab 接受建议,或按 Enter 提交自己的提示词。6

多行输入

方法 按键
转义换行 \ 然后 Enter
macOS Option+Enter
开箱即用(v2.1.0+) 在 iTerm2、WezTerm、Ghostty、Kitty 中使用 Shift+Enter30
其他终端 Shift+Enter(需先运行 /terminal-setup)
控制字符 Ctrl+J
自定义键位绑定(v2.1.47+) 通过 /keybindings 将任意键绑定到 chat:newline95

快捷前缀

前缀 操作 示例
# 添加到记忆 # Always use TypeScript
/ 斜杠命令 /review
! 直接执行 bash ! git status
@ 文件引用 @src/index.ts
& 发送到云端 & Build the API

文件引用性能(2026年1月):在 git 仓库中,@ 提及的速度现已提升 3 倍。Claude Code 在推荐文件补全时也会遵循 .ignore 和 .rgignore 文件,便于将构建产物或生成文件排除在建议之外。28

Vim 模式

通过 /config → Editor mode 启用(/vim 命令已在 v2.1.92 中移除137):

Normal 模式: - h/j/k/l - 导航 - w/e/b - 按单词移动 - 0/$ - 行首/行尾 - gg/G - 缓冲区开头/结尾 - dd - 删除行 - cc/C - 修改整行/修改至行尾 - dw/de/db - 各种删除单词操作 - x - 删除字符 - . - 重复上一次编辑 - % - 跳转到匹配的 ()、[] 或 {} 括号;若光标不在括号上,则从该行的下一个括号开始;d%、c%、y% 会作用于跳转范围(v2.1.301+)275276

Insert 模式: - i/I - 在光标前/行首插入 - a/A - 在光标后/行尾插入 - o/O - 在下方/上方新开一行 - Esc - 返回 Normal 模式(在 INSERT 模式下不再撤回排队消息——再按一次 Esc 即可中断,v2.1.119+)152

Visual 模式(v2.1.118+):152 - v - 进入 visual(字符)模式 - V - 进入 visual-line 模式 - 使用 h/j/k/l、w/e/b、0/$、gg/G 移动以扩展选区 - 选区会高亮显示,提供视觉反馈 - 应用操作符:d(删除)、c(修改)、y(复制);执行后自动退出 visual 模式

Insert 模式按键重映射(v2.1.208):vimInsertModeRemaps 设置可为 insert 模式定义自定义按键重映射——将 jj 映射为 Escape 这一经典 vimrc 习惯,如今在 Claude Code 的编辑器中同样适用:186

{
  "vimInsertModeRemaps": { "jj": "Escape" }
}

最佳实践

会话策略

在 Claude 中使用 /rename 为会话命名,之后即可按名称恢复:

# Inside a session, name it:
> /rename feature-auth

# Later, resume by name:
claude --resume "feature-auth"

# Or continue the most recent session:
claude -c

对于持续进行的工作,建议直接恢复会话,而不是重新解释上下文。

CLAUDE.md 设计

保持易于浏览。 Claude 每次会话都会读取此文件,冗长密集的文字只会浪费上下文。

聚焦于不显而易见的内容。 记录项目特有的模式、非常规的约定以及各项决策。Claude 能从代码中推断出的内容无需赘述。

持续更新。 开发过程中使用 # 随时添加笔记,每周进行一次审阅与整合。

包含命令参考。 记录您经常运行的命令。

安全:不受信任的代码仓库

警告: 克隆不受信任的代码仓库并在其中运行 Claude Code 时,请注意仓库中的 CLAUDE.md 文件、.claude/settings.json 以及 hook 脚本都会被读取,并可能被执行。恶意仓库可借此注入提示词、覆盖权限设置或执行任意命令。在非自有仓库上运行 Claude Code 之前,务必先审查 CLAUDE.md、.claude/settings.json 及所有 hook 脚本。仅在受信任的代码库上使用 --dangerously-skip-permissions。

已知 CVE(请保持 Claude Code 为最新版本): - CVE-2025-59536(已在 v1.0.111 中修复):通过不受信任目录的工具初始化实现代码注入。 - CVE-2026-21852(已在 v2.0.65 中修复):项目加载流程中存在信息泄露漏洞,恶意仓库可借此窃取 API 密钥。102

自定义命令

为重复性工作流创建命令:

---
description: Start new feature
allowed-tools: Bash(git:*), Read, Edit
---

1. Create branch: !`git checkout -b feature/$ARGUMENTS`
2. Pull latest main
3. Set up boilerplate
4. Begin implementation

高效提示

具体明确:

# Good
"Add email validation to LoginForm in src/components/LoginForm.tsx"

# Too vague
"Improve the login"

直接引用文件:

"Review @src/auth/middleware.ts for security issues"

提供约束条件:

"Refactor using the same pattern as @src/repositories/UserRepository.ts"

使用 subagents 进行探索:

"Have an explore agent find all places where we handle errors"

成本控制

  • 定期使用 /cost
  • 简单任务和 subagents 使用 Haiku
  • 仅在必要时设置 MAX_THINKING_TOKENS
  • 自动化脚本使用 --max-turns
  • 在长会话中主动进行压缩

安全

  • 在 .claude/settings.json 中为敏感文件配置 deny 规则
  • 对不受信任的项目使用沙盒模式
  • 切勿允许 Bash(rm -rf:*) 或 Bash(sudo:*)
  • 使用 hooks 阻止对密钥的访问
  • 企业环境部署托管设置

社区技巧与方法4951

Claude Code 社区发现了许多超越官方文档的强大模式。这些技巧来自资深用户,包括 Boris Cherny(Claude Code 创建者)以及收录 40 多条技巧的代码仓库。

编码前先使用计划模式

如果只记住一条技巧,那就记住这一条。 花在规划上的时间越多,Claude 成功的可能性就越大。开始实现之前,按 Shift+Tab 切换到计划模式。完整说明请参阅计划模式。

经常清除上下文

多用 /clear。每次开始新任务时,都清空聊天记录。旧的历史记录只会消耗 token,或触发代价高昂的压缩调用。清空之后继续前进即可。

使用图片和截图

Claude 非常擅长处理视觉输入。在 macOS 上,按 Cmd+Ctrl+Shift+4 将截图捕获到剪贴板,再按 Ctrl+V 直接粘贴到 Claude Code 中。可借此分享 UI 设计稿、错误信息或设计参考。

安装 GitHub App 进行 PR 审查

运行 /install-github-app,Claude 便会自动审查您的 PR。随着 AI 辅助开发使 PR 数量不断增加,自动审查的价值尤为突出。Claude 常常能发现人工审查者遗漏的逻辑错误和安全问题。

基于容器的自主运行

如需完全自主运行,可在 Docker 容器中运行 Claude Code,并以 tmux 作为控制层。本地的 Claude Code 负责控制容器化实例,后者无需人工批准即可执行长时间运行或实验性的任务。即使出现问题,影响也被限制在沙盒之内。

# Conceptual pattern (varies by setup)
# Local Claude Code → tmux → Container Claude Code
# Results pulled back when complete

Docker 沙盒模式(快速入门): 在探索不受信任的代码库或运行实验性提示时,可在 Docker 容器内运行 Claude Code,实现完全隔离。56

# Run Claude Code in a Docker container (mount your project as a volume)
docker run -it --rm -v /path/to/project:/workspace anthropic/claude-code

# Or use the open-source sandbox runtime
# See: github.com/anthropic-experimental/sandbox-runtime

以下情况建议使用沙盒模式: - 探索陌生或不受信任的代码库 - 测试可能修改文件的实验性提示 - 运行需要完全隔离的自主会话 - 学习 Claude Code 时避免对实际文件造成风险

以 Gemini CLI 作为后备方案

Claude Code 的 WebFetch 工具无法访问某些网站(例如 Reddit)。不妨创建一个 skill,指示 Claude 使用 Gemini CLI 作为后备方案。Gemini 具备网络访问能力,可以抓取 Claude 无法直接访问的网站内容。

元代理工厂模式

与其创建执行任务的代理,不如创建一个能够创建其他代理的代理。对于复杂的自动化工作流,这种模式能切实成倍提升生产力,而非仅仅依靠巧妙的递归。

Claude Squad:多代理管理器

Claude Squad 可并行管理多个 Claude Code 实例,每个实例运行在独立的 tmux 会话中,并拥有隔离的 worktree。您可以同时让多个代理处理不同任务,在单一仪表板中监控进度,并在完成后取回结果。58

# Install (Homebrew)
brew install claude-squad

# Or install via script (puts `cs` in ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

# Launch the TUI — manages instances, tasks, and git worktrees
cs

# Auto-accept mode (experimental)
cs --autoyes

使用场景: - 将相互独立的功能分配给多个代理并行开发 - 运行探索性提示,而不阻塞主会话 - 将自主编码扩展到单个上下文窗口之外

资深用户生产力数据

Boris Cherny 展示了 Claude Code 的潜力:30 天内,他合并了 259 个 PR,包含 497 次提交,新增 40,000 行代码,删除 38,000 行。这些数字表明,当 Claude Code 完全融入开发工作流时,能够实现怎样的成果。

值得关注的人

关注以下账号,及时了解 Claude Code 的最新动态:

Anthropic 团队(一手信息源)

人物 平台 关注理由
Boris Cherny @boris_cherny Claude Code 创建者。发布功能、宣布更新、主办线下聚会。一手信息源。
Cat Wu @_catwu Anthropic。Claude Code 功能发布、subagent 更新。
@adocomplete X Advent of Claude 系列——深入的每日教程(hooks、plugins、提示暂存)。
Thariq @trq212 Claude Code 团队的 Anthropic 工程师。处理问题、发布更新。
Anthropic @AnthropicAI 官方公告与重大版本发布。

优秀内容创作者

人物 方向 代表内容
@dani_avila7 教程 Hooks 深度指南、规则详解
@mattpocockuk MCP/技巧 10 课时 MCP 教程、Docker 沙盒、JSON 优化
ykdojo GitHub Tips 收录 40 多条技巧的代码仓库、状态栏脚本、系统提示优化
@ai_for_success MCP/工作流 Hyperbrowser MCP、文档缓存模式
@jerryjliu0 代理 分步构建代理的教程

重要资源

  • GitHub Releases:anthropics/claude-code/releases——仅订阅版本发布通知
  • Discord:Anthropic 社区频道
  • 完整列表:请参阅 ~/.claude/docs/following-list.md,其中收录了 20 多个精选账号

Boris 和 Anthropic 团队会在功能上线时同步分享,这往往是在文档更新之前了解新功能的最快途径。

常见反模式

了解哪些事情不该做,往往比学习最佳实践更有价值。以下模式屡屡引发问题:

成本反模式

反模式 问题 解决方案
所有任务都使用 Opus 成本高出 5 倍,且往往并无必要 默认使用 Sonnet,仅在架构设计时使用 Opus
从不查看 /cost 账单出乎意料 完成重大任务后查看成本
简单任务也启用扩展思考 浪费 token 日常工作中关闭(Alt+T)
在主上下文中执行探索 上下文膨胀 改用 Explore subagent

上下文反模式

反模式 问题 解决方案
对上下文置之不理,直到其膨胀 推理能力下降,遗忘已做的决策 在容量达到 50% 时主动执行 /compact
只需部分内容却读取整个文件 无关代码浪费上下文 引用具体的行范围
从不使用 subagents 所有内容都塞满主上下文 将探索和分析工作委派出去
庞大的 CLAUDE.md 文件 每次会话都浪费上下文 控制在 500 行以内,使用导入

工作流反模式

反模式 问题 解决方案
创建功能重叠的 skills 和命令 造成混乱,行为不可预测 每种用途只用一种机制
用提示来保证必须执行的操作 Claude 可能跳过或遗忘 必须执行的操作使用 hooks
没有用于格式化的 hooks 代码风格不一致 为每次 Edit/Write 挂接格式化工具
默认允许所有 bash 命令 存在安全风险 为安全命令设置明确的允许列表

配置反模式

反模式 问题 解决方案
所有配置都放在用户设置中 无法与团队共享 团队标准放在项目设置中
提交个人偏好设置 覆盖队友的配置 个人设置使用 settings.local.json
没有 deny 规则 Claude 可以访问敏感文件 拒绝访问 .env、凭据和密钥
忽视托管设置 企业策略被绕过 使用托管设置满足合规要求

提示反模式

反模式 问题 解决方案
“改得更好一点” 含糊不清,效果不佳 明确说明”更好”的具体含义
不引用文件 Claude 只能猜测路径 使用 @path/to/file.ts 语法
忽略 Claude 提出的问题 基于错误假设开展工作 先回答问题再继续
片段足够时却提供完整文档 浪费上下文 提取相关部分

工作流程实战方案

常见场景的端到端模式。

方案 1:启动新项目

# 1. Initialize
cd my-project
claude

# 2. Let Claude understand the codebase
> "Explore this codebase and summarize the architecture"

# 3. Set up project configuration
> /init

# 4. Create CLAUDE.md with learned patterns
> "Create CLAUDE.md documenting the patterns you observed"

# 5. Add team commands
> "Create a /test command that runs our test suite"
> "Create a /deploy command for staging deployment"

方案 2:日常开发流程

# 1. Continue yesterday's session
claude -c

# 2. Quick context recap
> "What did we work on yesterday?"

# 3. Check current state
> /status

# 4. Work on feature (Sonnet handles most tasks)
> "Implement the user profile endpoint"

# 5. Proactive context management
> /compact  # Before context exceeds 50%

# 6. Check spending
> /cost

# 7. End session cleanly
> "Summarize what we accomplished today"

方案 3:复杂重构

# 1. Use Opus for planning, Sonnet for execution
> /model opusplan

# 2. Plan the refactoring
> "Plan refactoring our authentication from sessions to JWT"

# 3. Review the plan
# (Claude presents approach, you approve or modify)

# 4. Execute with Sonnet
> "Execute the plan"

# 5. Verify nothing broke
> "Have an explore agent verify all auth-related tests pass"

# 6. Review the diff
> !git diff

方案 4:PR 审查自动化

# In CI/CD (GitHub Actions, etc.)
cat pr_diff.txt | claude -p "Review this PR diff for:" \
  --output-format json \
  --permission-mode plan \
  --max-turns 5 << EOF
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing test coverage
Provide findings in JSON format.
EOF

方案 5:调试生产环境问题

# 1. Configure Sentry MCP for error access
claude --add-mcp sentry

# 2. Get error context
> "Fetch the last 10 errors from Sentry for the auth service"

# 3. Deep dive with thinking
> Alt+T  # Enable extended thinking
> "Analyze these errors and identify the root cause"

# 4. Fix and verify
> "Implement a fix and add a regression test"
> !npm test

迁移指南

正在从其他 AI 编程工具转过来?以下是各项概念的对应关系。

从 GitHub Copilot 迁移

Copilot 概念 Claude Code 对应功能
Tab 补全 并非主要侧重点:Claude Code 专注于智能体式编辑
Chat + 智能体式 CLI 带工具执行能力的 REPL 对话
Copilot 指令 CLAUDE.md + Skills
专用智能体(Explore、Plan) Subagents(Task 工具)+ 智能体团队
MCP 支持 3,000+ 个 MCP 服务器 + 远程 OAuth
ACP(Agent Client Protocol) Hooks(31 个生命周期事件)
IDE + CLI 终端原生 + IDE 扩展

您将获得:操作系统级沙箱、31 个 hook 生命周期事件、支持 OAuth 的远程 MCP、具备隔离上下文的 subagent 委派,以及用于云端到本地交接的 --teleport。Copilot CLI(2026年1月起)现已具备智能体能力——两者的对比在于功能差异,而非能力差距。

相互融合(2026年2月): Claude(Opus 4.6 和 Sonnet 4.6)现已作为编程智能体在 GitHub Copilot 中向 Business 和 Pro 订阅用户开放,且不额外收费——此前仅限 Enterprise 和 Pro+ 档位。您可以在 github.com、GitHub Mobile 和 VS Code 中,直接在现有 GitHub 工作流内运行 Claude、Codex 和 Copilot。105

从 Cursor 迁移

Cursor 概念 Claude Code 对应功能
Composer 拥有完整工具访问权限的会话
Chat 支持 subagent 委派的 REPL
代码库索引 实时文件访问(Glob、Grep、Read)
Tab 自动补全 并非主要侧重点
集成于 IDE 终端原生 + IDE 扩展
MCP 支持(内置) MCP 支持(3,000+ 个服务器,远程 OAuth)
Cursor 规则(.mdc)+ AGENTS.md CLAUDE.md + Skills
后台智能体 远程智能体(& 前缀、--teleport)

您将获得:用于自动化的 31 个 hook 生命周期事件、具备隔离上下文的 subagent 委派、操作系统级沙箱(seatbelt/bubblewrap)、原生支持 OAuth 的远程 MCP,以及终端原生工作流。两款工具都支持 MCP——Claude Code 的差异化优势在于远程 OAuth 和工具搜索自动延迟加载。

从 OpenAI Codex CLI 迁移

这是最常见的对比,也是我们的 GSC 数据证实开发者确实在问的问题。两者都是前沿实验室推出的智能体式编程 CLI,发布时间相隔不过数月。以下是直接对比矩阵。151

维度 Claude Code OpenAI Codex CLI
基础模型 Opus 5.5(自 v2.1.280 起为所有套餐的默认模型,也是 opus 所选模型)、Sonnet 5.5(自 v2.1.284 起为 Anthropic API 上 sonnet 所选模型)、Fable 5.1(高于 Opus 的档位)、Sonnet 5、Opus 5/4.8/4.7 旧版、Haiku 5.5(自 v2.1.293 起为 Anthropic API 上的 haiku 别名;其他提供商上为 Haiku 4.5)220221228238 GPT-5.4(当前默认,2026年3月5日发布,融合了 GPT-5.3-Codex 的编程能力 + 原生 Computer Use);另可选 GPT-5.3-Codex、GPT-5.2-Codex、GPT-5.1-Codex、GPT-5
上下文窗口 Opus 5.5 在 Anthropic API 上以标准价格提供 1M tokens;自 v2.1.287 起在 Bedrock、Agent Platform 和 Foundry 上也默认提供(此前为 200K)223232 GPT-5.4 默认 272K / 长上下文模式 1.05M(输入超过 272K 部分按输入 2× / 输出 1.5× 计费);GPT-5.3-Codex 和 GPT-5.2-Codex 为 400K 输入 / 128K 输出
SWE-bench Verified 87.6%(Opus 4.7,2026年4月发布时数据;此处未比较更新的 Opus 分数) 74.9%(GPT-5-Codex 基线);GPT-5.4 未在官方页面公布
SWE-bench Pro 64.3%(Opus 4.7,2026年4月) 57.7%(GPT-5.4 官方)、56.8%(GPT-5.3-Codex)、56.4%(GPT-5.2-Codex)
Terminal-Bench 2.0 69.4%(Opus 4.7,2026年4月) 77.3%(GPT-5.3-Codex)、75.1%(GPT-5.4 官方)、64.0%(GPT-5.2-Codex)
执行模型 默认本地运行;可通过 --teleport 选用云端沙箱 默认本地运行(Codex CLI);通过 Codex Cloud 提供基于容器的沙箱
沙箱机制 操作系统级(macOS 上为 seatbelt,Linux 上为 bubblewrap) Codex CLI 使用本地操作系统沙箱;Codex Cloud 使用容器隔离
指令文件 CLAUDE.md(以及 CLAUDE.local.md);项目中没有 CLAUDE.md 时读取 AGENTS.md(v2.1.277+,尚未支持 Bedrock/Vertex/Foundry)219 AGENTS.md
Hook 生命周期 31 个事件(PreToolUse、PostToolUse、UserPromptSubmit、Stop、SubagentStop 等) 有限,主要为运行级 hooks
Subagents / 智能体团队 默认 20 个并发 subagents(可调),隔离上下文,支持后台模式 默认单智能体;通过启动独立运行实现并行
MCP 服务器生态 3,000+ 个 MCP 服务器、远程 OAuth、工具搜索 支持 MCP(较新),生态规模较小
Plugins Plugin 市场、plugin.json 清单、版本锁定 尚无官方 plugin 系统
定价模式 Opus 5.5 为每 MTok $4/$20,自 v2.1.280 起为所有套餐的默认模型;订阅 $20–200/月220221 OpenAI API 按 token 计费;ChatGPT Pro/Plus 档位附带部分 Codex 额度
语音输入 /voice 按键通话(20 种语音识别语言) 无 CLI 原生语音模式;ChatGPT 应用支持语音
企业策略 托管设置(managed-settings.d/)、签名 plugin 市场、CVE 快速通道 通过 OpenAI 管理后台实现云原生策略
Windows 支持 原生二进制文件 + PowerShell 工具 Codex CLI 通常仅支持 WSL

Claude Code 在纸面上胜出之处(截至目前): 在公开基准测试中,Opus 4.7 在 SWE-bench Verified 上比广泛引用的 GPT-5-Codex 基线高出 12.7 个百分点,在 SWE-bench Pro 上比 GPT-5.4 官方的 57.7% 高出 6.6 个百分点。在 Terminal-Bench 2.0 上,GPT-5.3-Codex 领先(77.3%),GPT-5.4 紧随其后(官方 75.1%),两者均领先于 Opus 4.7(69.4%)。这些数字会随每次模型发布而变化,因此在做出跨季度的长期决策之前,请先查阅各厂商的最新页面。151

何时选择 Claude Code: 您维护着大型代码库(1M 上下文至关重要);需要具备内核级隔离的本地优先沙箱;希望实现基于 hook 的深度自动化(linter、策略检查、CI/CD 关卡);或需要原生 Windows 支持。就生产任务而言,SWE-bench Verified 和 Pro 目前都更青睐 Opus 4.7。

何时选择 Codex CLI: 您已在付费使用 ChatGPT Pro/Plus 并希望沿用同一账户;更倾向于用 Codex Cloud 基于容器的密封沙箱来执行一次性远程任务;或团队已统一采用 OpenAI 基础设施(Azure OpenAI、用于 Codex 的 Foundry)。对于重度依赖 shell 的工作流,Terminal-Bench 2.0 目前更青睐 Codex 系列(GPT-5.3-Codex 77.3%,GPT-5.4 75.1%)。

两者兼用,而非二选一: 许多团队同时使用两者。Claude Code 负责长周期重构和智能体式编程;Codex 负责从 ChatGPT 发起的快速云端沙箱任务。AGENTS.md 和 CLAUDE.md 可以共存于同一代码仓库——而且自 v2.1.277 起,两者的界限进一步淡化:当项目中没有 CLAUDE.md 时,Claude Code 会自行读取 AGENTS.md(参见 AGENTS.md 支持)。如需更深入的分析,另请参阅专题文章 Codex 与 Claude Code 2026 架构对比。

迁移路径(Codex → Claude Code): 自 v2.1.277 起,无需重命名任何文件——在没有 CLAUDE.md 的项目中,Claude Code 会将您现有的 AGENTS.md 作为项目指令读取(尚未支持 Bedrock、Vertex 或 Foundry;可在 /config 的“Project instructions”下配置)。219 早期版本不会读取 AGENTS.md,因此若锁定在旧版本,请将其内容复制到 CLAUDE.md 中,或通过一行 @AGENTS.md 存根导入。通过官方安装程序安装 Claude Code,使用 claude login 完成认证,然后用 claude --print "explain this repo" 进行测试。大多数 Codex 使用模式(文件读取、shell 命令、git 操作)都能一一对应;只有当您希望在共享文件之上叠加 Claude 专属指令时,再添加 CLAUDE.md 即可。

从 ChatGPT / Claude 网页版迁移

网页界面 Claude Code
复制粘贴代码 直接访问文件
手动创建文件 直接写入文件
无法执行 完整的 bash、git、npm 等
上下文重置 会话连续性(-c 标志)
不了解代码库 Glob、Grep、Read 工具
无自动化 Hooks、CI/CD 集成

您将获得:一切。网页界面依赖复制粘贴的工作流;Claude Code 则直接在您的代码库上操作。

关键思维转变

  1. 不再复制代码。Claude Code 直接写入文件。
  2. 不再频繁切换上下文。MCP 将外部工具引入会话之中。
  3. 大胆委派。Subagents 负责探索工作,不会让您的上下文臃肿膨胀。
  4. 用 hooks 实现自动化。格式化、代码检查、日志记录均自动完成。
  5. 以会话为单位思考。使用 -c 继续工作,而不是开启全新对话。

面向不同受众的建议

面向开发者: - 在不超过 100K tokens 的提示词上,Haiku 5.5 的成本约为 Opus 5.5 的 1/40;适合用于 subagents 和简单任务 - 在长会话中主动使用 /compact 管理上下文 - 在会话 ID 中编码上下文信息(feature-${branch}-${timestamp}),便于日后找回之前的工作 - 在常用提示词前加 # 前缀,即可将其添加到持久记忆中,无需额外输入

面向 DevOps 和平台团队: - Headless 模式(-p 标志)支持 CI/CD 集成,并提供便于解析的 JSON 输出 - Hooks 无论模型行为如何都保证执行;适用于代码检查、格式化和安全检查 - MCP 将能力扩展到数据库、GitHub、Sentry 以及 3,000 多个服务器 - 后台任务(& 前缀)在 Claude Code Remote 上异步执行

面向安全团队: - 权限规则按“首个匹配生效”的方式求值;请谨慎组织 allow/deny 列表 - Sandbox 模式可为不受信任的代码库隔离文件系统和网络 - Bash 模式仅匹配前缀,因此 Bash(curl:*) 会阻止所有 curl 调用,而不仅是特定 URL - 企业托管设置无法被用户覆盖

面向团队负责人: - Skills 根据上下文自动激活;无需显式调用即可嵌入领域专业知识 - 项目 skills 提交到 git 后,团队成员即可自动获得统一的专业能力 - 通过 /cost 跟踪成本,可查看会话明细;根据团队规模,为每位用户预留 10k-300k TPM 的预算 - .claude/commands/ 中的自定义命令可创建可复用的工作流

面向企业架构师: - 托管设置通过 /etc/claude-code/managed-settings.json 在全组织范围内部署策略 - AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 可与现有云账单体系集成 - Opus 4.6 配备 1M 上下文窗口,可在单个提示词中处理整个代码库 - Agent teams(v2.1.32+)支持并行的多智能体协作,以处理复杂任务 - 全面推广前,先由 5-10 名开发者进行试点


快速参考卡

打印出来,贴在显示器上。

╔═══════════════════════════════════════════════════════════════╗
║                    CLAUDE CODE QUICK REFERENCE                 ║
╠═══════════════════════════════════════════════════════════════╣
║  MODELS (Oct 2026)                                            ║
║    haiku     $0.10/$0.50  Haiku 5.5 (v2.1.293); a prompt over ║
║                           100K tokens pays $0.50/$2.50        ║
║    sonnet    $2/$10/M     Cost lever; no longer any default   ║
║                           (Sonnet 5.5 on the Anthropic API)   ║
║    opus      $4/$20/M     Opus 5.5; default on every plan     ║
║                           (v2.1.280; Foundry: Sonnet 4.5)     ║
║    opus[1m]  $4/$20/M     No-op on Anthropic API (native 1M); ║
║                           Bedrock/Vertex/Foundry too (.287+)  ║
║    sonnet[1m] $2/$10/M    No-op on Sonnet 5.5 (native 1M)     ║
╠═══════════════════════════════════════════════════════════════╣
║  ESSENTIAL COMMANDS                                            ║
║    /compact        Reduce context (do at 50% capacity)        ║
║    /cost           Check session spending                     ║
║    /model opus     Switch to Opus                             ║
║    /status         Show current state                         ║
║    /voice          Toggle voice mode (push-to-talk)           ║
║    /init           Set up project config                      ║
║    /mcp            Configure integrations                     ║
║    /copy [N]       Copy code blocks (Nth-latest response)     ║
║    /memory         View and manage auto-memory                ║
║    /claude-api     Build apps with Claude API/SDK             ║
║    /code-review    Correctness review (effort, --comment,     ║
║                    --max-findings n|all|default, .288+)       ║
║    /batch          Batch operations (bundled, v2.1.63+)       ║
║    /effort         low..max slider; saved per model (.251)    ║
║    /loop 5m /foo   Run prompt on recurring interval           ║
║    /recap          Context when returning to session (.108+)  ║
║    /goal target    Continue until a completion target is met   ║
║    /ultrareview    Cloud parallel multi-agent review (.111+)  ║
║    /less-permission-prompts  Propose allowlist (v2.1.111+)    ║
║    /tui fullscreen Switch to flicker-free render (v2.1.110+)  ║
║    /focus          Focus mode (separated from Ctrl+O, .110+)  ║
║    /undo           Alias for /rewind (v2.1.108+)              ║
║    /proactive      Alias for /loop (v2.1.105+)                ║
║    claude -n name  Start session with display name            ║
║    claude agents   Agent View / configured agents             ║
║    claude attach id  Attach bg session (--help, .251+)        ║
║    claude -w       Start in isolated git worktree             ║
║    claude remote-control  Serve local env for external builds ║
║    claude -p --bare  Scripted mode (no hooks/LSP/plugins)     ║
║    claude --channels Relay approvals to Telegram/Discord      ║
║    claude --plugin-url URL  Load plugin zip for one session   ║
║    claude --desktop  Open this directory in the desktop app   ║
║    claude purge path Delete local project state (was          ║
║                      `claude project purge` before .288)      ║
╠═══════════════════════════════════════════════════════════════╣
║  KEYBOARD SHORTCUTS                                            ║
║    Alt+T           Toggle extended thinking                   ║
║    Shift+Tab       Cycle permission modes                     ║
║    Ctrl+C          Interrupt current operation                ║
║    Ctrl+X Ctrl+K   Stop all agents                            ║
║    Ctrl+Enter      Send queued messages now (v2.1.275)        ║
║    Esc → Esc       Rewind last change                         ║
║    Ctrl+L          Clear screen                               ║
╠═══════════════════════════════════════════════════════════════╣
║  PREFIXES                                                      ║
║    #message        Add to persistent memory                   ║
║    @path/file      Reference file in prompt                   ║
║    !command        Execute bash directly                      ║
║    &task           Send to cloud (async)                      ║
╠═══════════════════════════════════════════════════════════════╣
║  CONFIG FILE HIERARCHY (first found wins)                      ║
║    .claude/settings.local.json    Personal (gitignored)       ║
║    .claude/settings.json          Project (shared)            ║
║    ~/.claude/settings.json        User global                 ║
║    /etc/.../managed-settings.json Enterprise (locked)         ║
║    CLAUDE.md                      Project context             ║
╠═══════════════════════════════════════════════════════════════╣
║  DAILY WORKFLOW                                                ║
║    1. claude -c              Continue session                 ║
║    2. Work on features       Use Sonnet                       ║
║    3. /compact               Before context bloats            ║
║    4. /cost                  Check spending                   ║
║    5. Summarize              Clean exit                       ║
╠═══════════════════════════════════════════════════════════════╣
║  DECISION RULES                                                ║
║    Simple task?        → Haiku                                ║
║    Hard reasoning?     → Opus                                 ║
║    Everything else?    → Sonnet                               ║
║    Must always run?    → Hook (not prompt)                    ║
║    Auto-apply wisdom?  → Skill (not command)                  ║
║    Needs isolation?    → Subagent                             ║
╚═══════════════════════════════════════════════════════════════╝

更新日志

本参考指南是一份持续更新的文档。随着 Claude Code 的演进,内容会相应更新。

日期 变更 来源
2026-07-28 更新日志渲染修复:恢复了一行被截断的内容。 2026-05-28 的条目将一个插件作用域示例写成了单个包含原始竖线字符的行内代码片段。python-markdown 的表格解析器会在处理行内代码之前先按竖线拆分,因此该行被解析为五个单元格,而表头只有三列:渲染结果在“applies review findings to the working tree”处句子中途被截断,本应显示来源引用的位置却显示了“project”一词。该条目约7,000个字符(v2.1.152 至 v2.1.154 的详细内容)从未出现在发布的页面上。现已重写,使竖线位于任何代码片段之外。曾测试过用 \| 转义但未采用:python-markdown 虽能修正单元格拆分,却会保留代码片段内的反斜杠,读者会看到它。 -
2026-08-18 指南 v2.90:内容标记章节补全——C2PA 文件元数据正是缺失的另一半。 Anthropic 的支持页面(8月11日,比 v2.89 所引用的工程博文早三天)描述了两个标记组件:此前已涵盖的统计学文本水印,以及生成文件(.svg/.png/.jpg)上经签名的 C2PA 来源元数据。已在支持页面核实:两个组件遵循同一条未来模型时间线(“2026年8月2日及之后发布的 Claude 模型将在发布时支持机器可读标记”)——媒体“现在已全面适用”的说法对文件同样不成立,因此本章节关于时态的核心论断(当前模型的任何输出如今都未被标记)得到的是加强而非修正。章节更名为“内容标记:文本水印与 C2PA 文件元数据”;新增产品列表、文件侧的去除途径(格式转换、重新保存、截图)、“没有标记不能证明任何事”,并用一句话否定了广为流传的“水印让 Opus 5 变差了”的说法(不可能:当前任何模型都未启用)。新增 204。 252204
2026-11-02 指南 v2.121:CLI v2.1.311(10月26日)至 v2.1.317(11月2日)(五个版本;npm latest 和 next 为 2.1.317,stable 升至 2.1.311;2.1.313 从未发布,2.1.315 仅在 npm 上;分别有92、39、119、55和87条更新项)。值得写入正文:ultrathink 以 xhigh 运行终端轮次(v2.1.311;CLAUDE_CODE_DISABLE_ULTRATHINK 可将其关闭);CLAUDE_CODE_SUBAGENT_EFFORT 与按模型设置的 subagent 推理强度;在不起作用的地方去掉了 [1m];第三方提供商上的签名模型目录(CLAUDE_CODE_MODEL_CATALOG=off);更短的系统提示词,以及对无法识别的模型名称的拒绝回退;Opus 4.8 的快速模式于10月30日弃用,11月30日移除;permissions.blockWritesOutsideWorkingDirectories;Monitor 命令上的 hooks、PreCompact 输出上限、hook 并发数为一次24个;VS Code、桌面应用和第三方提供商中的空闲压缩;claude -p 退出码;runner 的 --hold-idle-file 和 --max-hold-min、CLAUDE_CODE_DISABLE_NESTED_SESSION_ID,以及自托管环境文档;disableRemoteControl;六个网关密钥和成本报告 API;服务器托管设置不再弹出提示;OTel 的 anthropic.* 属性和 OTEL_EXPORTER_OTLP_TIMEOUT;不再发送 safety_event;FORCE_HYPERLINK=false;VS Code、云会话和 Claude Tag 段落。仅见于更新日志:其余修复(TLS 交叉签名根证书、Foundry 和 Bedrock 回退、代理团队、Windows 路径、vim、Artifact 工具)。从文档新增的环境变量行:CLAUDE_CODE_SKIP_PROMPT_HISTORY、CLAUDE_CODE_TRANSCRIPT_LOCAL_GC、CLAUDE_CODE_SYNC_SKILLS、CLAUDE_CODE_DISABLE_CFC_PROMPT。 284285
2026-10-26 指南 v2.120:文档更新;CLI 无新版本发布(npm latest 2.1.310,stable 2.1.308;10月24日至26日期间 code.claude.com 有66个页面发生变更)。值得写入正文:Projects(2026年9月17日发布;在 Pro 和 Max 上公开测试),此前从未出现在任何版本说明中,现在在“网页版 Claude Code”下获得了一个章节:协调者对话、作为云会话的线程、指令与记忆、线程从仓库中加载的内容、用量上限、通过 Remote Control 在本地工作;claude --cloud 从终端启动云会话,-p "msg" --cloud <session-id> 将消息排入正在运行的会话(--remote 为已弃用的别名);云端计划任务(原名 routines)和桌面计划任务,附带 /schedule 行和三种调度器的对比;/slides 与 artifact 模板测试版;关闭 artifacts(enableArtifact、CLAUDE_CODE_DISABLE_ARTIFACT、CLAUDE_CODE_ARTIFACT_AUTO_OPEN);在环境变量参考中,CLAUDE_CODE_DISABLE_WORKFLOWS 取代了 v2.1.147 的选择启用项(workflows 默认开启,Pro 除外);CLAUDE_CODE_MAX_TURNS。移动端条目现已点明 iOS 和 Android 版 Claude 应用中的 Code 标签页。 280281282283
2026-10-23 指南 v2.119:CLI v2.1.303(10月18日)至 v2.1.310(10月23日)(八个版本;npm latest 和 next 为 2.1.310,stable 升至 2.1.308;2.1.303 和 2.1.308 是只有一行说明的可靠性版本,2.1.306 包含两项修复;304、305、307、309 和 310 分别有76、38、43、79和26条更新项,均与官方 CHANGELOG 完全一致)。三个 What’s New 章节。值得写入正文:/auto-mode-setup;/usage 中按 f 进行单行修复;Pro/Max 的5小时恢复警告;sandbox.allowNestedUserNamespaces;CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS、CLAUDE_CODE_AUTO_COMPACT_WINDOW 后缀、CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK;claude ultrareview 的工作区信任;claude_code.safety_event;mods 的 e.isReadOnly、decider: "person"、settings.read 层级、45% 停靠面板、tmux 中的 Image;沙箱加固(shell 启动文件、经符号链接的 denyWrite、--mcp-config 保护、sed -i 按原样运行);worktree 和 skills 的清理整顿;Code Review 级别与 @claude review stop;自定义 base URL 下的工具搜索默认值及其回归修复;allowedMcpServers 和 ${VAR} 服务器;Bedrock、Vertex 和 Foundry 上的 Monitor。文档(10月23日)现已涵盖其中大部分内容,外加 2.1.302 的 -p 和 fork 模式规则;仍仅见于版本说明的有:decider、settings.read、review stop、sed -i、恢复警告、工具搜索默认值。 278279
2026-10-21 指南 v2.118:依据10月21日的 hooks 参考文档修正了 hook 输出部分。通用的 JSON 输出示例中出现了参考文档并未定义的 message 和 modifications 字段;现已改为参考文档中的三类输出字段以及通用字段表(continue、stopReason、suppressOutput、systemMessage 和 terminalSequence;其中 suppressOutput 可被接受但不起作用,terminalSequence 仅限交互模式)。退出码:退出码为0时,JSON 字段生效,除非这些字段阻止、拒绝或停止操作,否则操作继续进行,且 stdout 仅在 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch 事件上进入上下文;退出码不为0或2时,除非 hook 的失败阻止了操作,否则操作照常进行,当 stdout 为纯文本或为空时,转录记录中的通知会携带 stderr 的第一行,而已验证的 JSON 仍然生效,除非 hook 的失败阻止了操作。PreToolUse 章节自 2026-02-12 那一行起就已记录 hookSpecificOutput.permissionDecision,以及该事件顶层 decision/reason 的弃用;配套文章Claude Code Hooks:为什么我的95个 Hooks 每一个都有存在的理由在一位读者反馈后于2026年10月21日进行了修正。 277
2026-10-17 指南 v2.117:CLI v2.1.301(10月15日)+ v2.1.302(10月16日)(npm 发布时间 14:34Z 和 16:48Z;GitHub 发布时间 19:22Z 和 20:53Z;分别有51和63条更新项,与官方 CHANGELOG 完全一致;latest 和 next 为 2.1.302,stable 保持 2.1.292;无遗漏)。值得写入正文:claude -p 和 SDK 在第三方提供商上、关闭遥测时以及全新安装时再次以 Manual 模式启动(v2.1.302 撤销了 v2.1.285;涉及方框要点、可用性表、模式表和一个新段落);fork subagents 在 -p、SDK、桌面应用和 VS Code 中默认开启,桌面应用和 VS Code 始终将主对话的 subagents 置于后台运行,prompt hooks 与 agent hooks 同一事件最多12个;CLAUDE_CODE_AUTO_MODE_MODEL 和 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS;OTel 的 classifier_verdict、permission_mode、classifier_category;vim 的 %;mods 的 rows、.catch、$.env.set;/config 中的 Idle compaction 行;Claude Design 将于2026年12月14日前关闭;fable/best 重试;切换到上下文窗口更小的模型时,由先前的模型生成摘要。文档滞后:截至10月17日,除 vim % 和 VS Code LaTeX 外,其余内容均仅见于版本说明,且权限模式、环境变量和 sub-agents 页面仍沿用 2.1.302 之前的规则;mods 文档被拆分为一个独立章节,其参考部分标注的版本为 v2.1.290 和 v2.1.299。 275276
2026-10-14 指南 v2.116:CLI v2.1.300(10月14日)(npm 于 14:27Z 发布在 next 标签下,GitHub 发布于 18:24Z,88 条要点与规范 CHANGELOG 完全一致;当晚 latest 与 next 均为 2.1.300,stable 升至 2.1.292)。值得写入正文: advisor 工具登陆 AWS 上的 Claude Platform,指南依据文档页面新增首个 Advisor Tool 章节(/advisor、advisorModel、--advisor、CLAUDE_CODE_DISABLE_ADVISOR_TOOL、配对规则、费用);mods 的 virtualText、$.ui.view、dir、prompt.change、agent.spawn 重写;OTel 缓存写入拆分与 GenAI span 属性;CLAUDE_CODE_GZIP_REQUEST_BODIES;updatedInput 校验;claude remote-control 移除 --sandbox/--no-sandbox;会话转录会记录每个请求的系统提示词与工具。修复:退出时的 SessionEnd、工具搜索 auto、无头模式下压缩恢复、MCP schema 的 400 错误、claude daemon stop --any。 273274
2026-10-14 指南 v2.115:CLI v2.1.299(10月14日)(npm 于 00:23Z 发布,GitHub 发布于 02:49Z,190 条要点与规范 CHANGELOG 完全一致;2.1.297 与 2.1.298 从未发布;next 自 14:27Z 起为 2.1.300,尚无发布说明;stable 为 2.1.287)。值得写入正文: 200K 以上的对话在闲置约 54 分钟后自动压缩("idleCompaction": false、CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS)、CLAUDE_CODE_DISABLE_FILE_MENTIONS、MCP 允许规则与 agent 的 tools: 列表可匹配服务器的完整名称、第一方 MCP 描述不再截断、UserPromptSubmit 在命令展开之前触发、面向 subagents 的 turn.start 以及其他 mod API 新增项、agent 视图中的 /effort 与 /fast、/usage 警告、claude plugin eval --disallow-tools、--shutdown-drain-sec、CLAUDE_CODE_ATTRIBUTION_HEADER、CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT。文档已补上 autoCompactWindow 与 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS;CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 与 serverToolUses 仍仅见于发布说明。修复了两个 2.1.296 的回归问题。 271272
2026-10-13 指南 v2.114:对照10月13日的文档页面进行补齐,无新的 CLI 版本(npm latest 与 next 仍为 2.1.296,stable 为 2.1.287)。hooks 参考文档现已将各 hook 的 --debug 行以及 PowerShell 对 CLAUDE_ENV_FILE 的处理标注为始于 v2.1.296,网关文档描述了按开发者配置的 forceLoginGatewayUrl 设置与 code 策略键,mods 参考文档列出了 e.agentId、e.ceiling 和 prompt.autocomplete;v2.1.295、v2.1.296 与 mod-API 段落均已据此说明。仍仅见于发布说明:autoCompactWindow、CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL、CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS、serverToolUses。此外,10月12日,沙箱章节已更正为 Anthropic 所记载的边界:写入仅限于项目与允许的路径,读取可覆盖机器上的大部分位置(除非设置了 denyRead),内置的文件与网页工具遵循权限规则,而 hooks、本地 MCP 服务器与辅助命令则以完整权限运行。269 270
2026-10-11 指南 v2.113:CLI v2.1.293(10月7日)至 v2.1.296(10月9日)(npm latest 与 next 为 2.1.296,stable 升至 2.1.287;四个版本的发布正文与规范 CHANGELOG 完全一致:分别为 56、2、143 和 79 条要点)。新模型: 在 Anthropic API 上,haiku 现在选择的是 Claude Haiku 5.5(v2.1.293):模型表、Haiku 段落、定价表、费用示例、快速参考、对比表与思考列表均已更新;Sonnet 5.5 的缓存读取价格更正为 $0.10。Hooks: onFailure: "block"(v2.1.295)。默认值变更: MCP 描述上限 4,096(v2.1.296),工具搜索描述上限 16,384,预加载 skills 为 32 个(v2.1.295)。新增: autoCompactWindow、CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL、CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS、CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS、VERTEX_REGION_CLAUDE_HAIKU_5_5、Read 的 allow_large、网关 code 策略键。文档补齐: v2.1.292 行中的三项滞后内容现已有文档记载。仅见于更新日志:v2.1.294 的 hook 判定修复,以及 VS Code、云会话、Claude Tag 与 Code Review 的修复。 238239240
2026-10-06 指南 v2.112:CLI v2.1.288(10月2日)至 v2.1.292(10月6日)(npm latest 与 next 为 2.1.292,stable 仍为 2.1.285;自 2.1.287 起无跳过版本)。重命名: claude project purge 现为 claude purge,旧名称保留并附提示。默认值变更: 交互式 WebSearch 配额改为每小时补充 100 次调用(CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR),而非到 200 次即止;stdio MCP 服务器在每次安装时协商 2026-07-28 协议(MCP_PROTOCOL_NEGOTIATION=legacy 可退出);后台命令限制仅在无人值守会话中生效;项目设置不再能启用 Claude in Chrome;pyright 会询问。新增: CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS、CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS、Agent 工具的 effort、claude plugin install --marketplace、/code-review --max-findings、claude attach/logs 支持部分名称、mod API 新增项。修复: v2.1.291 修复了两个回归问题(2.1.288 引入的会话结束消息丢失、2.1.290 引入的云端权限应答被丢弃);一个 UNC 读取的提示绕过漏洞已关闭。 234235236237
2026-10-01 指南 v2.111:CLI v2.1.286(9月30日)+ v2.1.287(10月1日)(npm 分别于 17:14Z 与 16:59Z 发布;GitHub 发布于 19:10Z 与 18:00Z;88 条与 106 条要点,与规范 CHANGELOG 完全一致;自 2.1.285 起无跳过版本;npm stable 从 2.1.280 升至 2.1.285)。默认值变更: Opus 4.7+ 与 Fable 在 Bedrock、Vertex、Foundry 以及 Claude 应用网关上以 1M 上下文运行(v2.1.287);CLAUDE_AX_PREPARK_MS 降为 0;因消息被标记而切换模型时会保留您的 effort 级别;--bare 仅连接命令行指定的 MCP 服务器(v2.1.286)。新增: mods 与内置的 You should know mod、基于 2025-11-25 MCP 协议的 URL 提示(bareElicitationCapability)、alwaysLoad: false、agents 视图的 n:<text> 筛选器、OTel prompt_text,以及通过已提交的符号链接进行 shell 写入时的提示。文档: 权限模式表现已与 v2.1.285 一致。仅见于更新日志:重试上限,以及屏幕阅读器、VS Code、Remote Control 与云会话的修复。 231232233
2026-09-29 指南 v2.110:CLI v2.1.284(9月28日)+ v2.1.285(9月29日)(npm 分别于 17:11Z 与 17:32Z 发布;GitHub 发布于 18:02Z 与 19:27Z;100 条与 136 条要点,与规范 CHANGELOG 完全一致;自 2.1.283 起无跳过版本;npm stable 从 2.1.274 升至 2.1.280)。默认值变更: 在 Anthropic API 上,sonnet 选择 Claude Sonnet 5.5($2/$10)(v2.1.284);auto 模式成为交互式会话在所有套餐与提供商上的起始模式(v2.1.284),并在第三方提供商或关闭遥测的情况下也成为 claude -p 与 Python Agent SDK 会话的起始模式(v2.1.285);Ultracode 不再强制 xhigh;后台 shell 命令到达超时即停止;自定义 base URL 获得 1M 上下文窗口。新增: allowedProviders、claude --desktop、claude plugin configure、CLAUDE_CODE_DISABLE_WEB_FETCH、CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES、/mcp reconnect all、effort 滑块快捷键。仅见于更新日志:重试预算、Remote Control、VS Code 与 /ultrareview 的修复。 228229230
2026-09-26 指南 v2.109:CLI v2.1.282(9月24日)+ v2.1.283(9月25日)(npm 分别于 15:56Z 与 18:46Z 发布;GitHub 发布于 18:38Z 与 21:50Z;86 条与 94 条要点,与规范 CHANGELOG 完全一致;自 2.1.281 起无跳过版本;npm stable 从 2.1.273 升至 2.1.274)。默认值变更: auto 模式成为交互式终端与 VS Code 会话在所有套餐与提供商上的内置起始模式(v2.1.283);关闭遥测的直连 API 会话使用服务器端的 auto 模式检查(v2.1.282);项目设置与本地设置忽略 OpenTelemetry 导出与内容变量(v2.1.282)。新增: maxProseWidth、deniedModels、availableModelsMatch、allowClaudeInChromeWithManagedMcp、/doctor prompt-audit、x-claude-code-prompt-id 提示头、保留名称 anthropic-skills,以及项目级 excludedCommands 限制;Opus 选择器行去掉了“(1M context)”。文档: auto 模式计费页面与 "attribution": false 设置条目已补齐;直连 API 时提示头默认开启。仅见于更新日志:扩展思考、plugin、MCP 与 vim 的修复。 225226227
2026-09-24 指南 v2.108:CLI v2.1.281(9月23日)(npm 17:01Z,GitHub 发布 19:19Z,176 个要点,与官方 CHANGELOG 完全一致;2.1.280 之后没有跳过任何版本;npm stable 从 2.1.267 升至 2.1.273)。默认行为变更:发送操作现在会将正在运行的工具转入后台,而不是取消当前回合;CLAUDE_CODE_AUTO_MODE_SERVER 适用于直接的 Anthropic API 连接;由服务器审查的只读命令和沙箱化 shell 命令会等待审查结果;在无人值守模式下,危险 rm 操作的提示会在 2 分钟后自动拒绝。新增:"attribution": false、MCP URL 模式 elicitation、claude plugin validate 的 MCP 检查、--agents 支持 JSON 文件路径、网关的 assume_role、guardrail 和 telemetry.resource_attributes、runner 系统提示文件,以及三项提示缓存修复。更正:/agents 相关内容现已注明该向导已在 v2.1.198 中移除。仅记录于更新日志:恢复、流式传输和代理的可靠性修复;claude --bg 会请求工作区信任;--setting-sources 可传递至派生的会话。 224
2026-09-23 指南 v2.107:正确性与可读性修订;无新的 CLI 版本发布(npm latest 和 next 仍为 2.1.280,stable 为 2.1.267)。更正内容:Opus 5.5 已加入 API 定价表,并注明其 0.05 倍的缓存读取费率;快速模式现已列出 Opus 5.5($8/$40),它自 v2.1.280 起即为快速模式的默认模型;凡提及 effort 和 MAX_THINKING_TOKENS=0 之处,均已说明 Opus 5.5 的 medium effort 默认值及其始终开启的思考功能;opus[1m] 已针对 Bedrock、Agent Platform 和 Foundry 加以限定说明;AGENTS.md 的差异说明现已与文档一致,并附有首次会话的注意事项;AWS 上的 Claude Platform 已加入服务器端自动模式列表;删除了一条无来源的 v2.1.280 计费回退说法;配置示例已改用当前的模型 ID。新增:Opus 5.5 破坏性变更说明块,以及 Claude Code 基于内容的回退机制。可读性方面:TL;DR 更为简短,自动模式简介拆分为段落和表格,发布说明脚注精简为引用。 219220222223
2026-09-22 指南 v2.106:CLI v2.1.280(9月22日)+ Claude Opus 5.5。(npm 发布于 2026-09-22T15:44Z,GitHub 发布于 16:38Z,114 个要点;除 GitHub 的“What’s changed”标题外,发布正文与官方 CHANGELOG 完全一致。9月22日验证时的 npm dist-tags:latest 和 next 均为 2.1.280,stable 仍为 2.1.267。)已否定的前提:v2.1.279 并不存在。本次更新原定范围为“2.1.279 + 2.1.280”;但 npm 的已发布版本直接从 2.1.278 跳到 2.1.280,CHANGELOG 中也没有 2.1.279 的章节,因此未为其撰写任何内容——与 2.1.244、2.1.249、2.1.253-256、2.1.262 和 2.1.264 一样,都属于从未发布的版本。头条:Claude Opus 5.5(claude-opus-5-5)成为新的默认 Opus 模型,套餐之间的分化就此终结。1M 上下文,每百万 token $4/$20(低于 Opus 5 的 $5/$25),缓存读取 $0.20/MTok(为输入价格的 5%,是标准 10% 的一半;仅 Fable 5.1 和 Mythos 5.1 更低,为 2.5%),最大输出 128K,自适应、始终开启的思考,effort 默认为 medium(Opus 5 默认为 high),可靠知识截止日期为 2026年6月(与 Fable 5.1 持平),退役时间不早于 2027年9月22日,Bedrock 上为 anthropic.claude-opus-5-5,需要 CLI v2.1.280 及以上版本。同一版本还将 Pro 和 Team Standard 从 Sonnet 切换为 Opus,“与 Max、Team Premium 和 Enterprise 保持一致”——因此 Opus 5.5 现已成为 Anthropic 运营的所有套餐和第一方提供商的默认模型,Microsoft Foundry 除外(其默认为 Sonnet 4.5,也是 opus 仍解析为 Opus 4.6 的唯一场合)。Opus 5 进入文档的旧版(Legacy)模型表。遵循 v2.94 的教训(这一变化散落于多处),已全面梳理默认模型相关内容:TL;DR、opus/default/opus[1m] 别名表各行、Opus 5.5 模型说明块(新增)并将 Opus 5 说明块改为过去时态、“按套餐划分的默认模型”表由五行改写为三行(此前的修订遗漏了它,仍写着 Opus 5 为高级版 / Sonnet 5 为标准版)、Sonnet 5 说明块(Sonnet 如今不再是任何套餐的默认模型,而被定位为有意为之的成本调节手段)、Fable 5 和 Fable 5.1 说明块、“我应该选择哪个模型”中的 Opus 段落(选择 Opus 如今是一项降级决策,而非升级)、ANTHROPIC_DEFAULT_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL 环境变量示例、Codex 对比定价行,以及 ASCII 快速参考模型框。模型之外同样值得写入正文的内容:CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH——新增“MCP 描述长度上限覆盖”小节和环境变量表行;它覆盖 MCP 工具描述和服务器指令的 2,048 字符上限,作用于整个会话而非单个服务器,且由此放行的全部内容都会成为每次请求的常驻上下文,因此 Tool Search 和更简短的服务器描述仍是更经济的解决办法。符号链接写入路径修复(安全)——新增一段,延续权限规则的讨论:此前写入操作是按其树内路径写法来判断的,因此 acceptEdits、允许规则和自动模式都可能批准一次实际落在树外的写入;现在提示会指明写入的实际落点。v2.1.268 已封堵读取侧;本次封堵写入侧,而 acceptEdits 曾是暴露面最大的一处。自动模式重试修复——新增表格及解读:拒绝审查的安全检查现在只拒绝一次,并附注说明重试无济于事;不给出答案的安全检查则会退避,并在连续十次后终止该回合;这属于可靠性修复而非策略变更——此前获批的操作如今不会被拒绝。提示缓存主题延伸——工作中途在宿主应用(Claude Desktop、VS Code、SDK)中切换模型后,下一次提示不再错失缓存;恢复的 fork 子代理会重新发送其原始工具列表,而不是重新构建。hook_execution_complete OTel 事件新增 hook 输出大小以及保存到文件的超大输出数量。PermissionRequest agent hooks 被拒绝——agent hook 的回答从来无法允许或拒绝请求,因此它从未起到任何把关作用;现在错误信息会明确说明这一点,并指向 command/http hooks。TUI/对话框集群(对操作者的影响)——新增表格:连按两次 Ctrl+C/Ctrl+D 现在会关闭对话框,而不是退出 Claude Code(列出了 16 个对话框),误按的 y/n 不再触发确认或关闭(仅限 Enter 和 Esc;可通过 keybindings.json 重新绑定),对话框文本字段会保留已输入的字符,Home/End 在设置和选择列表中可正常使用;此外还有针对波斯语和阿拉伯语的 ZWNJ 保留(v2.1.278 的不可见字符清理曾剥离一个字母级字符)、Windows 提示重绘修复,以及按 Ctrl+C 停止语音听写(此前提示已清空但麦克风仍在录音)。Ctrl+L / Cmd+K 全屏清空记录已回退——于 v2.1.260 加入,本次移除;两个按键恢复为重绘屏幕,v2.1.260 的 TUI 行已予以更正而非保留原样。修复自上一次修订的遗留问题:[^256] 和 [^257] 分别在七处和五处被引用,却从未定义——两者现已补全完整定义,所有脚注均可正确解析。 220221
2026-09-21 指南 v2.105:CLI v2.1.277(9月18日)+ v2.1.278(9月19日)(v2.1.277 于 2026-09-18T16:22Z 发布到 npm,GitHub 发布版于 18:06Z 推出,共 87 条条目;v2.1.278 于 2026-09-19T01:48Z 发布到 npm,GitHub 发布版于 03:10Z 推出,共两条条目;两个发布说明正文除 GitHub 的“What’s changed”标题外,均与规范 CHANGELOG 完全一致。9月21日验证时的 npm dist-tags:latest 与 next 均为 2.1.278,stable 仍停留在 2.1.267)。v2.1.277 的头条:支持 AGENTS.md —— 在没有 CLAUDE.md 的项目中,Claude Code 会转而读取 AGENTS.md;可在 /config 的“Project instructions”下配置;Bedrock/Vertex/Foundry 上暂不可用。记忆章节新增 “AGENTS.md 支持(v2.1.277)” 小节,收录了文档中的加载矩阵(默认值 claude-md-or-agents-md,以及 claude-md-and-agents-md、claude-md、managed-only;设置位置为 pluginConfigs -> agents-md@builtin -> options.instructionFiles)、CLAUDE.local.md 会阻止加载 AGENTS.md 的坑、不会列在 /memory//context 中且没有 InstructionsLoaded 事件的差异、功能开关可用性的注意事项,以及变通方案退役的说明;Codex 迁移矩阵的对应行和迁移路径已重写 —— “Claude Code 不读取 AGENTS.md,需要重命名”这条建议已不再作为现状描述(保留为 2.1.277 之前版本的回退说明)。v2.1.278 的头条:自动模式分类器的默认值再次反转,并附带计费规则 —— 自动模式现在对 Claude API 和 Enterprise 用户,以及在 Bedrock/Vertex/Foundry 和网关上默认使用服务端分类器,并且由服务器执行检查时分类器开销不计费;在这些场景下,CLAUDE_CODE_AUTO_MODE_SERVER=0 是退出开关(v2.1.273 的 =1 选择加入语义已成历史 —— 该变量在直连 Anthropic API 时不会被读取,文档也注明其为临时变量,另一个关闭开关是 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1);回退到计费模式时会触发一次性警告,最常见的原因是网关剥离了 safeguards 请求字段或 safeguard_results 响应键 —— 解决办法是让其透传;/status 新增 Auto mode server 的 Enabled/Disabled 行。已更新的现状描述位置:TL;DR、自动模式章节、沙盒分类器说明、环境变量表的对应行、/status 行;已抓取并梳理自动模式分类器计费文档页面(通知文本、stderr/stream-json 输出位置、Pro/Max/Team 用户永远不会看到该通知)。同样值得写入正文(v2.1.277): CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 —— 对于唯一出口是正向代理的 Claude apps 网关,将主机名直接交给代理,不做本地 DNS 解析 —— 以及可选的上游 headers: 映射和 NO_PROXY 遥测中继修复(Enterprise 网关部分);claude -p/Agent SDK 遇到内部错误时不再挂起,而是报告错误并以退出码 1 退出,无头会话在退出时会保存成本/用量汇总(非交互模式);sandbox.excludedCommands 的 glob 模式必须匹配复合命令的每一部分(沙盒模式);重新安装插件不再破坏正在使用的副本,对已安装插件再次执行安装会提示使用 claude plugin update(插件安装改进);三项提示缓存修复 —— SessionStart hook 的输出不再导致 /clear 之后继续的会话完全缓存未命中,恢复的 subagents/队友不再重新渲染其 MCP 工具定义,已记录的附件在恢复时也不再重新渲染(缓存经济性主线)。仅见于更新日志(v2.1.277,节选): 空文本块导致的对话失败(包括 --resume 之后的情况)、旧版本构建的登出冲突、~/.claude.json 格式错误导致的崩溃修复(customApiKeyResponses、theme、claudeAiMcpEverConnected)、Grep/Glob 资源耗尽错误现在会直接显示而非报“无匹配”、Write 工具以目录为目标时的错误、Edit 工具的转义反斜杠和大段非 ASCII 内容修复、--worktree 加载未跟踪的 .claude/skills、$TMPDIR 展开为空、提示中不可见 Unicode 字符的清理、subagent 结果标头将输出标记为 subagent 文本、Fable 始终出现在 /model 中的变更、TaskOutput 工具的移除(taskOutputMaxChars/TASK_MAX_OUTPUT_LENGTH 现在为空操作)、更新检查和 winget/apk 修复,以及 [VSCode]、[Claude Code on the web] 和 [Claude Tag] 尾部条目。截至本行撰写时,v2.1.278 是最新发布版本,也是 npm latest。 219
2026-09-17 指南 v2.104:CLI v2.1.274 + v2.1.275(9月17日)以及 v2.1.276 回归修复(v2.1.274 于 2026-09-17T00:12Z 发布,共 108 条条目;v2.1.275 于 2026-09-17T22:33Z 发布,共 96 条条目;v2.1.276 于 2026-09-18T02:12Z 发布,仅一行。三个发布说明正文与规范 CHANGELOG 逐字节一致;npm latest 与 next 均为 2.1.276,stable 仍停留在 2.1.267)。v2.1.275 的头条:claude.ai 账户的 skills 和 plugins 会同步到终端会话(以该账户登录的会话)—— 退出选项为 syncClaudeAiSkills: false / syncClaudeAiPlugins: false(skills 章节、插件管理、设置参考);立即发送键 —— ctrl+enter(或 ctrl+x ctrl+s)会中断当前回合并一次性发送所有排队消息,已发送和排队中的文本在模型收到之前显示为灰色(键盘表 + 参考卡片);/plugin install <plugin> --marketplace <source> 会先提议添加该 marketplace(命令块 + 插件管理);npm 来源的插件改用 npm pack --ignore-scripts 获取并进行完整性校验 —— 包的安装脚本不再运行(插件安装改进);Artifact 首次发布时会要求提供一个单词的标签页图标,而不再是 emoji 网站图标(正文无变化 —— 指南从未记录过 emoji 网站图标)。v2.1.274 值得写入正文的内容: CLAUDE_CODE_MCP_STARTUP_WAIT_MS 限制首个非交互回合等待 MCP 服务器连接的时长,0 表示不等待(环境变量表);Bedrock/Vertex/Foundry 以及禁用遥测的安装现在默认使用 v2 MCP 客户端和 MCP 2026-07-28 协商(针对直连 HTTP 服务器),与其他安装方式此前的行为一致 —— 退出选项为 MCP_SDK_GENERATION=v1、MCP_PROTOCOL_NEGOTIATION=legacy(传输说明 + 环境变量表),并且旧版 HTTP+SSE 回退现在在首次响应为 422/4xx 时也能继续工作;.mcp.json/设置/插件/agent 文件中 "type": "sdk" 的 MCP 条目会被跳过并给出警告 —— 只有 SDK 宿主应用才能注册进程内服务器(配置格式说明);命名:产品用语现改为“cloud session” —— /status 的 GitHub 行显示为“Cloud sessions”,/web-setup、/ultrareview 和 teleport 消息不再使用“Claude Code on the web”(指南中各处的现行指引已更新;章节标题和历史行保持不变);本地会话中的 artifact 监视在其他地方发布新版本时不再启动新回合 —— Claude 会从后续的 Artifact 工具结果中得知此事(与 v2.1.271 对比:监视容量提升到 10 并保持不变;只是取消了重新发布时的唤醒)。v2.1.276: 修复 2.1.275 的回归问题 —— 当 ANTHROPIC_BASE_URL 指向代理或网关时,每个请求都会以 400 ... Input tag 'advisor_20260301' 失败;在版本固定部分新增一行注意事项:在代理或网关后面绝不要固定使用 2.1.275。仅见于更新日志: /code-review 为没有调优设置的模型使用更精简的内联提示;插件和 marketplace 克隆时 Git LFS 文件保留为指针(git lfs pull 可获取它们);claude_code.managed_settings_resolved OTel 事件 + OTEL_LOG_MANAGED_SETTINGS=1 脱敏设置开关 + llm_request span 上的 effort 属性;特殊 shell 变量的循环和赋值现在会请求权限(deny 规则连载系列,与净状态方向一致 —— 封堵了一处绕过,而非反转);worktree 隔离的会话拒绝某些嵌套的 shell 展开;/update-config 现在写入 Edit(path) 规则,而不再写入文件检查从不匹配的 Write(path) 规则;Chrome 自动模式对分类器批准的调用跳过扩展的逐站点检查,与绕过模式的行为相同;损坏转录文件的恢复和崩溃修复;Grep/Glob 20MB OOM 修复;/rewind 零填充恢复修复;可见的内存严重不足警告;MCP 传输修复(Streamable HTTP 按服务器配置的 timeout 在超过 5 分钟后仍然生效、无 listChanged 时的刷新、403 insufficient_scope 错误会指出缺失的权限);以及 [VSCode]、[Claude Code on the web]、[Claude Tag] 和 [Code Review] 尾部条目。截至本行撰写时,v2.1.276 是最新发布版本,也是 npm latest。 218
2026-09-16 指南 v2.103:CLI v2.1.273(9月15日)(GitHub release 发布于 2026-09-15T20:23:03Z,距 v2.102 的扫描约两小时;发布正文与规范 CHANGELOG 逐行比对——完全一致,各 64 行。v2.102 的 next 标签观察项就此了结:npm latest 与 next 均为 2.1.273——且 stable dist-tag 从 2.1.236 移至 2.1.267)。头条:拒绝规则的拉锯再次反转——v2.1.273 回退了 v2.1.268 的不可分析行检查(“诸如 time -p make build 之类的命令重新回到提示确认,而不再被直接拒绝”);此次回退范围很窄——268 的符号链接目录修复与 v2.1.260 的参数回退均保持有效——同一版本还追加了三项点修复:在 permissions.blockReadsOutsideWorkingDirectories 下,不可分析的 Bash 命令不再跳过提示;在 bypass 模式下,隐藏了危险 rm 的子 shell 不再跳过确认;在该设置下,由仓库设置指定的记忆目录不会被加载、召回或索引。对不可分析行的最终规则:拒绝规则改为提示而非拒绝,blockReads 改为提示而非跳过(“回退之后”段落已重写为覆盖 v2.1.268-273)。同样值得写入正文的还有:Bedrock/Vertex/Foundry 的自动模式现在“暂时”默认使用本地分类器——CLAUDE_CODE_AUTO_MODE_SERVER=1 可选择启用平台的服务端分类器(v2.1.236 相关论述线上的状态变更:TL;DR、Auto Mode、沙箱分类器说明、环境变量表);CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 向 LLM 网关发送五个 x-claude-code-* 提示头(request-class、agent-type、prev-tool-durations、compaction、context-compacted),需显式启用(网关配置 + 环境变量表);托管设置的执行缺口已补上——当服务器托管设置同时存在时,通过 MDM 或 managed-settings.json 配置的 allowManagedMcpServersOnly/deniedMcpServers/disableClaudeAiConnectors 曾被忽略;上下文计量/自动压缩修复——advisor 工具轮次曾按约 2 倍于真实大小计算,导致自动压缩在真实窗口约一半时就触发;/login、/upgrade、/extra-usage 不再丢弃此前的思考内容(这曾迫使提示缓存全量重写;缓存经济性话题线);OTEL_LOG_TOOL_DETAILS=1 现在会在成本与 token 指标上携带真实的 agent/skill/plugin/MCP 服务器名称;/bug 与 /feedback 的数据最小化——仅包含模型行为参数(模型、系统提示、工具),省略请求元数据与 CLAUDE_CODE_EXTRA_BODY;使用 Claude 账户登录时也会请求 claude.ai 插件访问权限;claude --remote-control 会话可以从 Claude 应用中分叉为主机上的后台会话;SDK/stream-json 不再丢弃后台子代理的剩余消息与最终报告。仅记录于变更日志:worktree 复制后 scheduled_tasks.json 会话错误的修复、组织关闭 Skills 时 claude.ai 同步的技能移入可恢复的废纸篓、会标明凭据名称的 401/403 错误、MCP 断开连接通知、macOS 拖入截图的 Read 读取修复、shell 模式 ! 提示修复、/tui 重启修复、长会话响应性、Artifact 工具改进,以及 [VSCode]、[Claude Code on the web]、[Claude Tag] 与 [Code Review] 末尾各节。 217
2026-09-15 指南 v2.102:CLI v2.1.266 至 v2.1.272(9月8日至14日)(npm latest 为 2.1.272;七个版本的发布正文均与规范 CHANGELOG 逐一比对——完全一致。2.1.273 仅存在于 npm next 标签(发布于 9月15日 18:06 UTC;无 GitHub release,无 CHANGELOG 小节)——留作下一轮循环的观察项,其内容在此有意不作记录。2.1.263 的观察项则永久关闭:仍是“Bug fixes and reliability improvements”,没有补充说明)。头条: /output-style 复活(v2.1.269)——/output-style [name] 重新可以列出并切换输出样式,包括通过 Remote Control 以及在云端/无头会话中;该命令曾在 v2.1.73 至 v2.1.268 期间被弃用,弃用说明与命令表行现已记录完整始末,弃用作为历史保留。claude plugin eval(v2.1.269)——可评分、可复现的插件评估套件,输出 JSON + HTML 报告(新增 Plugin CLI 小节,与 v2.1.268 为 install/uninstall/update/enable/disable 增加的 --json、list --json 中的 errorDetails/noteDetails,以及 v2.1.271 基于 --accept-command <sha256> 的固定哈希接受并列)。Remote 会话中的快速模式(v2.1.271)——支持云端与自托管运行器;通过主机设置或在会话中输入 /fast 启用,前提是组织允许(快速模式小节 + /fast 行;在组织禁用快速模式的场景下 /fast off 现已可用)。maxEffortLevel 设置(v2.1.267)——在顶层或 modelSettings 下按模型为 effort 设上限,适用于包括 Bedrock/Vertex/Foundry 在内的所有提供商;用户可以选择更低档位(设置列表 + 索引)。拒绝规则拉锯战,回退后的点修复(v2.1.268-271)——v2.1.260 的参数回退保持有效;新增段落:符号链接目录规则按真实路径写法生效,反之亦然,同一行中的 env -C/eval 不再绕过 Read/Edit 拒绝规则(268);tee 的目标路径纳入 Edit() 拒绝规则 + 写路径检查,Bash(tee:*) 允许规则不再触及工作目录之外,以 ! 开头的规则限定在各自的设置来源(269);fmt/column 读取、通配符展开、变量声明标志、blockReadsOutsideWorkingDirectories 的双重 cd(271)。同样值得写入正文的还有:v2.1.267 的提示缓存稳定性批次(约 10 项修复:恢复的会话不再重写工具列表/描述/MCP 公告,/model 切换不再重新发送工具定义——署名文本现在作为对话备注,--system-prompt 会话只记录一次,会话中途加入的 MCP/插件工具以延迟定义的形式到达;缓存经济性话题线续篇);--system-prompt-snapshot off(每次请求都重新渲染系统提示,便于迭代提示词);在默认 effort 被固定的模型上也会遵守 effort: frontmatter(新增 skill frontmatter 的 effort 行);修复了 marketplace 反斜杠越界绕过(267);任务跟踪工具重新定义为允许列表——仅在 Claude 3.x、Opus 4.0-4.7、Sonnet 4.0-4.6、Haiku 4.5 上提供,其他模型需 CLAUDE_CODE_ENABLE_TODO_TOOLS=1(环境变量表 + hook 表措辞调整,268);普通的 WebFetch 拒绝/询问规则不再覆盖 Artifact 读取——请改用 Artifact 规则或 WebFetch(domain:claude.ai)(268);/plugin 的更改在菜单关闭时生效(268;/reload-plugins 行 + v2.1.221 段落);WebFetch 300 秒截止时间 + CLAUDE_CODE_WEBFETCH_DEADLINE_MS(268);网关加固——gatewayInternalNetworks 托管设置、空 allow_cidrs 警告、网关 pricing: 同步使 /cost 与支出计量一致(268)——以及用于成本分摊的 modelPricing/网关 pricing multiplier 可大于 1、最高 10(271);密钥卫生修复——${VAR} 的解析结果不再出现在 /mcp//plugin/登录错误界面,git URL 中的令牌不再出现在插件错误中(268);claude auth status --json 新增 configDirectory(268);bashEditDiffEnabled(269);署名提醒不再覆盖 CLAUDE.md/记忆中反对署名的规则——托管设置中的条目仍然生效(269);新增环境变量 OTEL_METRICS_INCLUDE_REPOSITORY、CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS(1-256)、CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS(默认 3 秒)、CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0(269);修复 v2.1.247 的键盘回归 + kitty-query SSH 键盘支持(269);启用沙箱的自动模式下,Bash/PowerShell/Monitor 支持按命令设置 allowed_domains(271);omitClaudeMd agent frontmatter + --agents JSON(271);自动模式机制——技能/命令中的内联 ! shell 遵循默认模式规则而非分类器,子代理交还通过专门的、经分类器审查的调用完成(271);--resume 跨模型系列保留 [1m](271);无法读取的 managed-mcp.json 采取“失败即关闭”,保持对 MCP 的独占控制(271);修复第三方 ANTHROPIC_BASE_URL 的 HTTP 400 回归(268)。仅记录于变更日志:v2.1.266(仅一行:CLAUDE_CODE_USE_GATEWAY 2.1.265 回归修复)、v2.1.270(仅一行:269 的 git 提示回归修复)、v2.1.272(无实质内容:“Bug fixes and reliability improvements”,与 2.1.263 同一模式);Markdown artifact 渲染为带样式的文档页面,artifact 监视数上限提升至 10(271;本指南没有 artifact 工具小节,故记录于此)。截至本行写就时,v2.1.272 是最新发布版本,也是 npm latest。 216
2026-09-08 指南 v2.101:CLI v2.1.265(9月8日)(发布于 2026-09-08T20:37:31Z;npm latest 与 next 均为 2.1.265,stable 仍为 2.1.236;2.1.262 和 2.1.264 从未发布——即惯常的跳号模式——而 2.1.263(9月6日)仍无实质内容:“Bug fixes and reliability improvements”;发布说明正文与 CHANGELOG 经交叉核对 1:1 完全一致)。值得写入正文: --plugin-dir 插件文件夹模式——指向一个包含多个插件的文件夹时,每个带有清单文件的子文件夹都会被加载,会话运行期间新增或移除的子文件夹也会被识别(扩展了“插件管理”中的 .zip 说明);提示缓存前缀修复——恢复前台生成的子代理不再改变其工具列表和系统提示前缀,代理队友和恢复的子代理也不再在后续轮次中把 SubagentStart hook 上下文和预加载的 skills 移出提示前缀;这两个问题都曾破坏提示缓存的复用(在 v2.1.251 的 /cost 缓存条目旁新增一段,延续缓存经济学这条脉络);cd 在非交互式会话中跨轮次保持——使用 stream-json 输入的 -p、Agent SDK 以及云端会话不再在每条新用户消息时重置 shell 工作目录(print 模式部分);MCP http 传输会按 MCP 规范回退到旧版 HTTP+SSE,因此旧版服务器不再需要显式指定 --transport sse(SSE 传输说明处新增一句);保存到磁盘的工具结果上限为 1 GB,对话内预览会注明保存的文件是否被截断(扩展了 bashOutputMaxChars/taskOutputMaxChars 条目);forceLoginGatewayUrl 让机器从启动起就使用 gateway 会话,效果与 forceLoginMethod: "gateway" 相同——残留的 claude.ai 登录或 API 密钥不会被使用(设置表格行已扩展)——并配套 gateway 会话直接将 OTLP 导出到收集器,收集器由 gateway 托管的 OTEL_EXPORTER_OTLP_ENDPOINT 指定(未指定收集器 = 照旧中继),同时在 Desktop/Cowork 的 gateway 遥测中加入 user.email/user.groups(新增遥测段落);双键组合键会等待第二个按键 3 秒,超时后显示提示——此前为 1 秒且静默取消,即 tmux 的情形(组合键行 + 键盘快捷键段落);在提示中途输入斜杠命令会显示建议列表(非全屏模式下按 Tab 打开),插件 skills 可按裸名称找到(斜杠命令简介)。仅见于变更日志: /model opusplan[1m] 不再被拒绝;崩溃后恢复时将被中断的工具调用保持标记为已中断,而不是重写最后一条提示;插件安全修复(插件路径中的反斜杠在 macOS/Linux 上绕过符号链接限制、双点目录名被错误拒绝、无法检查的组件文件夹现在会在 /plugin 中连同错误代码一起报告);工件加固两项(发布时拒绝连接器并未暴露的连接器工具名;读取他人工件时作为不可信内容进行摘要并标记其中嵌入的指令);advisor 决策每次对话只做一次,变更时会通告;fork 出的 skills 会在 stream-json 中流式输出其启动提示(使用 --forward-subagent-text 时还包括文本轮次);大型仓库上的 --worktree 并行检出(git 2.32+);/workflows 代理详情(工具调用标记为运行中/失败/完成,按 Enter 展开输入与结果);/model 在保存默认值失败时会承认失败并说明原因;claude-api skill 错误代码更正(模型访问为 404、不可用的 beta 为 400,而非 403);--bg 空闲超时退役的竞态问题;VS Code/SDK 在令牌刷新关闭后重新登录;约 5 项 Remote Control 修复;gateway OTLP 中继在载荷被拒后不再暂停所有转发 30 秒;git status/diff 探测不再运行嵌套仓库的 clean 过滤器;修复了 Windows AppContainer 文件工具拒绝的问题;图像处理改用运行时内置功能(不再将原生模块解压到临时目录);MCP OAuth 客户端注册推迟至登录时进行;长会话恢复更快;VSCode 自动归档不活跃会话(默认 14 天)。截至本行撰写时,v2.1.265 为最新版本,亦是 npm latest。 215
2026-09-04 指南 v2.100:CLI v2.1.261(9月4日)(发布于 2026-09-04T19:58Z;npm latest 与 next 均为 2.1.261,stable 仍为 2.1.236)。值得写入正文: keybindingFlavor 已退役——readline 单词编辑成为提示输入行唯一的方言(“Ctrl+W 向后删除至空白处,Alt+F 与 Alt+D 在单词末尾停下,标点符号分隔单词;keybindingFlavor 不再产生任何效果”)——键盘快捷键段落已重写,TL;DR 新增一条退役旁注;/skill-doctor——显示哪些已加载的 skills 未被使用、各占用多少上下文,便于裁减(新增斜杠命令行);bashOutputMaxChars 和 taskOutputMaxChars 设置——提高 Claude 在命令和后台任务输出被保存到文件之前内联接收的输出量,最高 128K 字符(新增设置条目;有别于 BASH_MAX_OUTPUT_LENGTH 环境变量——后者是文档中从 Bash 工作输出文件回读的窗口——这两项控制的是内联与持久化文件之间的阈值);auto 模式将内容打包进 URL 的图表渲染器链接视为上传——把内容打包进公共渲染器 URL 的链接(mermaid.live 风格)不再自动批准,除非您主动要求(Auto 模式叙述,分类器加固框架);forceLoginMethod: "gateway" 现在会清除残留凭据——固定到 gateway 的机器会忽略残留的 API 密钥或 claude.ai 登录,并要求执行 /login;Bedrock、Vertex AI 和 Foundry 会话不受影响(设置表格行已扩展)。拒绝规则无变化:“截至 v2.1.260”的拒绝规则状态维持不变。仅见于变更日志: --append-subagent-system-prompt-file(从文件读取子代理系统提示,适用于超长提示);/status 和 claude doctor 中新增“Organization policy”诊断行;计数 API 不可用时 /context 改用本地令牌估算;危险 rm 提示扩展到位置参数和双引号包裹的 sh -c 脚本;/model 选择器和 VS Code 胶囊标签显示模型名称而非原始的 Bedrock/Vertex/gateway ID;一批修复(快速输入时丢字、恢复时丢失并行工具调用附近的 hook 输出、SDK/云端提前 Stop、约 6 项 Remote Control 修复、/usage 在速率限制下漏掉特定模型的每周限额行——与 v2.99 每周限额事项相邻的一个显示错误、后台代理重试导致 CPU 空转、功能标志跨版本泄漏、队友重复通告导致提示缓存未命中、感知 API_TIMEOUT_MS 的重试);约 24 项 VSCode 条目。截至本行撰写时,v2.1.261 为最新版本,亦是 npm latest。 审校(同日,Codex 交叉审校,发布前已采纳):BASH_MAX_OUTPUT_LENGTH 按工具参考文档的回读窗口语义重新表述(默认 30K,硬上限 150K;此前环境变量表中将其称为普通输出限制的注释也一并更正),图表渲染器那句改为按分类器的上传处理方式表述——URL 片段携带的状态由页面脚本读取,不会随网络请求发送。 214
2026-09-03 指南 v2.99:每周限额将于9月14日调整——不涉及任何 CLI 版本发布。 在速率限制部分新增一段:临时的 50% 每周限额提升于9月14日结束,取而代之的是在提升前基线之上永久提高 25%(Pro、Max、Team 以及按席位计费的 Enterprise);Anthropic 自己的后续说明称,与今天相比,这相当于“Claude Code 上每周限额减少 17%”。五小时限额不变。来源:2026年8月29日的两篇 Claude Developers 帖子,原文引用。 213
2026-09-03 指南 v2.98:CLI v2.1.260(9月3日)——在下方同日完成的 v2.97 验证之后数小时发布(GitHub 发布时间 2026-09-03T23:48Z,即太平洋时间 16:48;npm latest 与 next 均为 2.1.260,stable 仍为 2.1.236)。头条:v2.1.259 的 Read() 参数扩展已被回滚。 原文:“回滚了 2.1.259 中将 Read() 拒绝规则应用于 Bash 参数的更改;该更改在所有模式下都会依据 Read(./**/build/**) 规则拒绝 npm run build,并导致 cd … && grep 即使在 auto 模式下也会弹出提示。” v2.1.257 的那一半(输入重定向 < file、读取类命令 tac/egrep)未在回滚说明中提及,因此仍然有效——这已是该功能的第三次反复:v2.1.232 发布 -> v2.1.233 回滚 -> v2.1.257 部分实现 -> v2.1.259 扩展 -> v2.1.260 回滚扩展。权限规则段落已重写;下方的 v2.97 行与 211 记录了 v2.1.259 当时的发布内容,保持原样不动。纳入正文: /diff——对话旁的全屏差异面板,随 Claude 的编辑实时显示未提交的更改(新增一行斜杠命令 + 全屏/TUI 说明);含括号路径的权限规则修复(安全)——路径中含括号的 Edit/Write/Read 规则此前会被当作无效规则丢弃,或被 Bash 沙箱忽略(导致“只读”文件夹仍可写入);无法编译的拒绝模式(未闭合的 [)不再使每次文件编辑都失败,而是改为保护其字面拼写的路径;Edit(C:\dir\(name)\**) 的设置错误会建议一种无歧义的写法;带尾随文本的规则(Bash(ls) x)会被报告为无效,而不是被静默忽略;Fable 5.1 发布相关修复集——/model 选择器现在会为符合条件的组织显示 Fable 5.1(此前只有手动输入 /model claude-fable-5-1 才被接受),提示缓存覆盖工具结果之后附加的上下文(此前每个工具调用轮次都会未缓存地重新发送),会话中途更改 /effort 不再使提示缓存失效,并且 model: fable 代理会遵循 ANTHROPIC_DEFAULT_FABLE_MODEL 固定值上的 [1m] 标记(此前静默回落为 200K);接近 1M 上限时的自动压缩扩展到 Opus 和 Fable(此前仅限 Sonnet 5,v2.1.247),超大上下文的恢复性压缩不再受 10 分钟超时限制;/cost 与状态栏 prompt_cache 字段会指出可能的未命中原因(工具定义或系统提示发生变化、空闲超过 TTL);! bash 模式命令即使在严格沙箱模式下也在沙箱之外运行(sandbox.allowUnsandboxedCommands: false,新增文档说明),“就像在您自己的终端中输入一样”;托管 CLAUDE.md(claudeMd)不再触发安全批准对话框(hooks、shell 命令、沙箱和不安全环境变量设置仍会触发);Chrome 中的 Claude 遵循组织管理员设置(管理员关闭 = --chrome、/chrome 和浏览器工具均不可用)。仅记于更新日志: 无头会话中的 /reload-plugins(Desktop/SDK 命令列表);面向桌面端、Remote Control 和无头会话的 /advisor 文本形式(/advisor、/advisor <model>、/advisor off);网关 oidc.scope_on_refresh;桌面端策略键 userPluginMarketplacesEnabled/userPluginUploadsEnabled;以 Claude Desktop 1.15200.0+ 可读取的列表形式发送的 orgPluginSettings;网关刷新失败日志会指出失败的步骤;网关启动拒绝时会指出嵌套在 managedMcpServers/orgPluginSettings 条目中拼写错误的字段;Bedrock 网关使用免费的 CountTokens API 统计已中止请求的输入 token(需授予 bedrock:CountTokens);zsh 的 REPORTTIME/REPORTMEMORY/DIRSTACKSIZE 命令替换赋值现在会弹出提示;blockReadsOutsideWorkingDirectories 的 macOS 修复(不再隐藏用户的 git 配置或 worktree 子代理自身的检出);带有残留 API 密钥的 claude.ai Enterprise/Team 用户可正常加载托管设置,且 /status 会标明该凭据未在使用;skillOverrides 别名键(/doctor 的 checkup)生效,Skill(name) 拒绝规则覆盖嵌套的 <dir>:name 技能;插件 hook 或托管市场加载失败后模型切换不再被阻塞;一大批修复(SDK 的 MCP 服务器在首轮缺失、云会话中 Chrome 显示“Not connected”、/rewind 虚假成功 + 过期读取跟踪、丢失 worktree 元数据后的 -p --resume、SendMessage 唤醒子代理、ListAgents 幻影重复项、Ctrl+Z 全屏、压缩期间 Workflow 的停滞重启、GitLab 嵌套子组 + issue 链接、Glob/Grep 先授权再探测、Bedrock 企业根 CA、换行的 emoji/旗帜渲染等);改进项(Workflow agent({schema}) 会预先拒绝无法满足的 schema,-p/SDK 会话的空闲 CPU 占用,/ultrareview 等待 45 分钟,Ctrl+L/Cmd+K 清除全屏转录视图,自托管运行器的 --kill-session-after-min 会释放等待中的会话而非终止它,取消了子代理后台命令的一小时上限,以及一批 VSCode 修复)。v2.1.260 是撰写本行时的最新版本和 npm latest。 212
2026-09-03 指南 v2.97:CLI v2.1.257(9月1日)、v2.1.258(9月1日,仅含修复)、v2.1.259(9月2日),以及 Claude Fable 5.1 发布(9月1日);2.1.253-256 从未在 npm 上发布(npm 从 2.1.252 直接跳到 2.1.257,与 2.1.244/2.1.249 的模式相同)——2.1.258 说明中的“2.1.255 引入的回归”以及文档中的“Fable 5.1 需要 Claude Code v2.1.255 或更高版本”指的都是未发布的内部版本,因此 v2.1.257 是首个可安装并搭载 Fable 5.1 的版本。Fable 5.1(头条):模型 ID 为 claude-fable-5-1(Bedrock 上为 anthropic.claude-fable-5-1),每 MTok $10/$50,其中 缓存读取为 $0.25/MTok,即输入价格的 0.025 倍(2.5%,标准为 10%;仅 Fable 5.1 和 Mythos 5.1 享有),缓存写入按标准计价;1M 上下文、128K 输出、自适应常开思考、effort 默认为 high;可靠知识截止日期为 2026年6月(训练数据截至 2026年6月),为当前所有模型中最新——Opus 5 的“最新”之说已成历史,相关措辞已改写但未改动其记录;退役时间不早于 2027年9月1日;相较 Fable 5 有三项破坏性变更(强制工具调用会报错;早期模型无法读取其思考块;编辑较早轮次会使思考块失效),另有五项新增能力(按消息设置的 effort、轮次级系统消息、通过 display “updates” 推送进度更新——以上三项均为 beta——更便宜的缓存读取、内容溯源);Mythos 5.1 规格相同,仅通过 Project Glasswing 邀请制提供;Fable 5 移入文档的旧版模型(Legacy models)表;fable 别名解析为 Fable 5.1,除非用 ANTHROPIC_DEFAULT_FABLE_MODEL 固定,best 则是“您可用的最新 Fable 模型”;网关注意事项:Claude apps 网关会话目前仍将 fable/best 解析为 Fable 5(未配置的网关会拒绝 5.1)——请在 /model 中选择 Fable 5.1;各套餐默认值不变。值得写入正文(v2.1.257):timeFormat/timeZone 设置(12 小时制、24 小时制、24 小时制 UTC 或 strftime;用于轮次结束时钟和转录时间戳;文档滞后);auto 模式新增 “Containment Escape”(逃逸隔离)规则(获取云元数据凭据、规避出站控制、跨租户访问不再自动批准,除非环境将其标记为预期行为);CLAUDE_CODE_SUBAGENT_MODEL_FORCE(可选启用,恢复 v2.1.251 之前的覆盖行为);auto 模式在首次读取工作目录之外的文件前会一次性提示,并新增 permissions.blockReadsOutsideWorkingDirectories;/effort s 仅对当前会话生效,--effort 现在也仅限会话范围;项目级/本地级的 defaultMode: "bypassPermissions" 会像 "auto" 一样被忽略(本指南此前从未记录过这两个值的此项作用域限制);managedSourcesBehavior: "merge" 细化(sandbox.credentials.awsPairs/sandbox.ripgrep 整体取自最高优先级来源)——可选启用的合并模式本身也是新近才写入文档的,因此“来源不会合并”的说法仅适用于默认情况;Bash 的 Read()/Edit() 拒绝规则现已覆盖输入重定向(< file)以及 tac/egrep 等读取类命令——这正是 v2.1.232 的检查被回滚时(见 v2.87 行)承诺的收窄版本;承诺已兑现;--add-dir//add-dir/additionalDirectories 拒绝网络路径(UNC 共享、/net/<host> 自动挂载;Windows 上请映射为盘符)。值得写入正文(v2.1.259):managedMcpServers 托管设置(组织可按 .mcp.json 条目格式提供 HTTP/SSE MCP 服务器;command 类条目会被跳过;文档滞后);allowedMcpServers 作用域变更,是一个升级陷阱——它现在只管辖用户自行添加的服务器,因此此前被允许列表按字面名称过滤掉的托管服务器在升级后会重新加载(请改用 deniedMcpServers);--permission-prompts none(面向无人值守的无头主机:凡是会触发提示的操作都会被自动拒绝,而当前模式——包括 auto——仍照常做决定;与 --permission-prompt-tool 不同;尚未写入 CLI 参考文档);解析失败的托管设置现在会拒绝启动并指明来源(此前会静默失效);自定义命令和 skills 的 frontmatter model: 在交互式会话中生效,且 auto 模式不再在不受支持的 frontmatter 模型上执行轮次;claude plugin validate --json;Read() 拒绝规则的覆盖范围扩展到选项值和操作数(--ignore-revs-file=.env、-f.env、@file、git diff/git grep 的操作数、cd DIR && cat FILE 复合命令;对包含被拒文件的目录执行 grep -r/cp -r 现在会询问)。仅记于变更日志(v2.1.257):/doctor 新增沙箱掩码过期警告;/model 选择器条目显示网关提供的描述,且在 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 下仍可进行网关模型发现;/btw 历史记录按键改为 Shift+方向键或 [/];keybindings.json 新增 Agents 上下文;--resume <id> --bg 以自身 ID 继续运行;subagents 在流中途被截断后会自动续接;/fork 保留原有提示缓存;拒绝 plugin 中经符号链接指向的组件路径;修复 auto 模式下 permissions.ask 对复合命令/子 shell 的处理;网关登录启用 TLS 固定;读取 Cowork/云端产物始终询问;以及一大批修复/性能/VSCode 改动。v2.1.258(仅变更日志):修复 macOS 12 启动回归(由未发布的 2.1.255 引入);修复远程/计划会话的非空内容问题。仅记于变更日志(v2.1.259):识别 glab mr;修复并发会话覆写 ~/.claude.json 的问题;修复被拒思考内容重复的问题;修复关闭遥测时 OAuth 刷新导致的提示缓存问题;修复 CLAUDE_CODE_MAX_CONTEXT_TOKENS 在 Vertex 上的 @date 问题;修复阻塞式 Stop hook 的推理/缓存问题;嵌套后台 subagent 的结果会保存到父转录中;/install-github-app 增加 GitLab 指引;VSCode 会话列表筛选器;一批修复。截至本行撰写时,v2.1.259 是最新版本,也是 npm 上的 latest。 211241242243244
2026-09-01 指南 v2.96:Auto Mode 补上了此前缺失的注意事项——不涉及任何 CLI 版本发布。Auto Mode 一节记录了一个不断强化的分类器,却从未说明这个分类器不是什么。新增内容:Johann Rehberger 于 8月26日针对 auto 模式下 Claude Code Opus 5 的攻击链(服务器对 WebFetch 返回 HTTP 415,使代理回退到 curl;当 base64 导入 struct 时,下载归档中的 struct.py 被代理自身的解码器加载),小样本下报告成功率为 60-80%(python3 C2 链 5 次中 3 次;两种 claude -p 子进程配置分别为 5 次中 3 次和 5 次中 4 次),作者本人附有小样本提醒,并指出在少数几次运行中,auto 模式在发现入侵后拒绝了 Claude 的清理命令;还有 Anthropic 的处置结论(以 Informative 结案,属按设计工作)以及应据此设计的框架——分类器是尽力而为而非安全保证,注入链可由分类器范围之外的良性步骤组合而成,操作系统级隔离与网络出站控制才是真正的边界。针对处理不可信输入的会话新增指引:使用容器或虚拟机、限制出站流量、进行监控、将凭据移出代理的主目录。同时调和了宣传中 0.00% 的提示注入攻击成功率(ASR,来自委托进行的 72 场景评估)与一条不在该评估集内却实际可行的攻击链之间的矛盾,并记录了 8月30日对该链的重新归类——由一位 Lobste.rs 读者提出、Willison 在更新中予以认可——即它是一种环境混淆(confused environment)攻击,而非经典的提示注入。没有删除任何强化说明;该节现在为这些说明提供了应有的框架。 210
2026-08-31 指南 v2.95:CLI v2.1.252(8月31日)——仅作为变更日志行记录;四项修复,不涉及正文。原文照录:修复了部分 Mac 上 Bash 命令因“task output swap refused (tasks dir moved or linked)”而失败的问题;修复了在尚无 .claude/settings.local.json 的项目中“始终允许”无法保存的问题;修复了由 Claude Desktop 或 VS Code 托管的 Remote Control 会话在 claude.ai 连接质量下降时,工具执行完毕后停滞数分钟的问题;以及后台任务通知因失败输出过大而超出 API 请求大小限制的问题。四项修复均恢复了文档所述行为。截至本行撰写时,v2.1.252 是最新版本。 206
2026-08-30 指南 v2.94:CLI v2.1.248(8月27日)、v2.1.250(8月27日,仅修复)、v2.1.251(8月28日);2.1.249 从未在 npm 上发布。 更正(按套餐划分的默认模型): 高级套餐(Max、Team Premium、Enterprise 按量付费)以及 Anthropic API 默认使用 Opus 5,AWS 上的 Claude Platform、Bedrock 以及 Google Cloud 的 Agent Platform 亦然;Pro 和 Team Standard 默认使用 Sonnet 5;Microsoft Foundry 默认使用 Sonnet 4.5;按席位计费的 Enterprise 订阅自 v2.1.251 起改为 Opus 5(模型配置文档对席位订阅仍写着 Sonnet 5,落后于 CHANGELOG)。TL;DR、套餐表以及两个 Sonnet 5 章节均已将 v2.1.197 的“全面默认 Sonnet 5”改写为历史(文档历史注记:高级套餐/API 的默认模型自 v2.1.154 起为 Opus 4.8,自 v2.1.219 起为 Opus 5)。同时修正了跨会话章节中“不支持原生 Windows”的陷阱行(自 v2.1.239 起支持 Windows),该行现已纳入 v2.1.248 的扩展:Bedrock、Vertex 和 Foundry 上的同机 SendMessage/ListAgents,以及遥测关闭时同样可用。纳入正文: --restricted/CLAUDE_CODE_RESTRICTED=1(评估框架模式:工具必须在 --tools 中逐一列名,不允许云会话);experimental.cacheTtl agent 前置元数据;desktopSessionCleanupPeriodDays 及桌面端会话保留修复;面向 AWS Marketplace/自助/试用版 Enterprise 的 /usage-credits(新增行);/loop 自主节奏的动态模式始终可用;托管设置诊断及 v2.1.251 的审批对话框集群(终止 TLS、代理、注入凭据或削弱隔离的设置,以及 ANTHROPIC_CUSTOM_HEADERS 中的凭据/路由标头均需审批;对话框仅列出已更改的设置;超时/MCP 启动/流监视器环境变量不再提示);claude self-hosted-runner --client-label;PreModelSwitch/PostModelSwitch hook 事件(匹配器基于 to_model 的规范名称、缓存成本输入、因超时被取消的 PreModelSwitch 会阻止切换、PostModelSwitch 的 stdout 会成为模型可见的上下文)及 SessionStart 的恢复成本字段(seconds_since_last_response、context_tokens、prompt_cache_likely_expired、estimated_cache_write_usd);/effort 按模型分别保存;/usage 的支出上限进度条及状态栏的 rate_limits.spend_limit;/cost 的每会话提示缓存行及状态栏的 prompt_cache;--help 中收录 claude attach/logs/stop/respawn/rm;Claude in Chrome 的操作始终经过 CC 权限检查;CLAUDE_CODE_SUBAGENT_MODEL 从强制覆盖降级为默认值;项目设置的 env 不再能设置 CLAUDE_CODE_TMPDIR/TMPDIR/TMP/TEMP/CLAUDE_CONFIG_DIR;Remote Control 实时流式显示前台 subagents。仅见于变更日志: v2.1.251 的安全修复集群(文件工具会跟随在权限检查之后被调换的符号链接、插件市场路径遍历、Bash 自动批准 OPTIND=1/0 之类的整数算术赋值、Read 拒绝规则可通过符号链接的 Grep/Glob 搜索路径绕过);/ultrareview 不再上传 prod.env 类文件、*.tfvars 以及凭据文件的交换/临时/备份副本;通过捆绑的 workflow-authoring skill,Workflow 工具描述从约 5.7k token 缩减至约 1k。 **** 206207208209
2026-08-27 指南 v2.93:CLI v2.1.247(8月26日)。 纳入正文: SendFeedback 工具及 feedbackDrafts 设置:会话中出现问题时,Claude 可以起草一份反馈报告,供您在 /feedback 中审阅并发送(新增 /feedback 斜杠命令行,此前命令表从未收录该命令,并补充了设置说明);spinnerTipsOverride 结构扩展:支持 {id, text, cooldownSessions, priority} 形式的提示条目以及 tipsFile 和 label 键,组织可以将自己的提示与内置提示轮流展示(设置示例已更新;设置文档尚未记录这些新键);/claude-api cost-optimize:分析现有项目的 Claude API 支出,并逐项实测地调整各项成本杠杆(缓存、token 精简、批处理、effort、模型选择),每次只改一处(/claude-api 行及“节省成本策略”);此外该 skill 还新增了 Admin API 覆盖(组织成员、邀请、工作区、API 密钥、速率限制报告、工作负载身份联合、CMEK);Sonnet 5 的默认自动压缩窗口现为完整的 1M 上下文:1M 窗口的会话在约 967K token 时自动压缩,而非此前的约 934K(扩展上下文);Bash 权限提示中的自动模式提示,提供一键“是,并切换到自动模式”的选项(Max 上的自动模式);跨会话的对等消息现在默认折叠为一行 Message from @<sender>: <first line> 预览,按 Ctrl+O 展开完整内容(跨会话消息)。仅见于变更日志: 首次调用遇到模型 404 而终止的 subagents 现在会使用会话的回退模型链,且返回给父会话的错误包含错误类型、状态、请求 ID 和模型;hook 或后台 agent 输出数 MB 的错误信息时不再撑爆对话、使会话卡在“Prompt is too long”;Bash 沙箱的命令后清理不再删除由 dotfile 工具管理(nix/home-manager、stow)且被重新指向沙箱可写区域之外的 ~/.claude/settings.json 符号链接;后台 agent、shell 或监视器仍在运行时容器在轮次之间重启的云会话不再陷入沉默,恢复后的会话会报告丢失的工作。2.1.244 仍未在 npm 上发布。截至本行撰写时,v2.1.247 为最新版本。 245
2026-08-26 指南 v2.92:CLI v2.1.242–246(8月24–25日)。 2.1.242 和 2.1.244 没有 CHANGELOG 章节(2.1.244 从未上架 npm),文档将新设置的最低版本锚定为 v2.1.242。更正: Sonnet 5 的 $2/$10 现为正式定价(定价页面取消了 9月1日的涨价;v2.1.243 更新了 /model 选择器和 claude-api skill):修正了五处表述及模型表的三行,并注明 sonnet[1m] 在 Sonnet 5 上不起作用;托管来源优先级重写(第一个含有策略键的来源胜出,顺序为远程 → MDM → 托管设置文件 → HKCU;不做任何合并),并加入了新的 /status Skipped sources 行;提示缓存 TTL 改为两档表(订阅用户的主对话为一小时,其余均为五分钟),并补充 promptCacheTtl / subagentPromptCacheTtl、对应的环境变量及优先级链;effort 表删除了并不存在的 min 级别,新增 ultracode;Web 可用性已修正(Pro/Max/Team 为研究预览;Enterprise 需高级套餐或 Chat + Claude Code 席位)。纳入正文的新增内容: modelPicker(设置参考及“切换模型”)、modelPricing(托管表及“查看成本”)、免密钥的 Console 登录(“身份验证”及 /login)、/permissions 的自动模式标签页(“自动模式”及对应行)、Bash 通配符位于子命令之前的警告(“权限规则”)、/cd 立即应用设置/hooks/MCP/skills/agents(“会话管理”及新增行)、maxTurns 部分结果附带 SendMessage 提示、/goal 最多三次检查点、/usage 的 Loops 细分、/web-setup(Web 章节、新增行及 /status 的 GitHub 行)、/mcp 和 /plugins 中的 managed 标记、/tasks 显示模型及 effort;设置示例中过时的 claude-sonnet-4-5-20250929 和 Opus 4.6 提供商 ID 已替换为文档记录的当前 ID(-p --model 示例、Bedrock GitHub Action 和托管设置示例亦同);脚注 229 曾有两个定义(内容标记支持页面和 v2.1.235–238 发布说明),因此发布说明的引用现改为脚注 236。仅见于变更日志: 采用 zstd 压缩的原生二进制文件(Linux x64 上约 75 MB,而非 340 MB)、glibc 2.44 启动崩溃修复(2.1.245)、Bash 权限检查在遇到以 && 或双管道运算符结尾的畸形命令时始终提示、遥测不再将第三方网关的 API 密钥发送给 Anthropic、跨会话收件箱套接字在空闲 30 秒后关闭连接、轮次结束行显示完成时间。截至本行撰写时,v2.1.246 为最新版本。 251250249248247
2026-08-24 指南 v2.91:CLI v2.1.239(8月21日);v2.1.240–241(8月22–23日)仅含修复。 值得写入正文: /claude-api upgrade —— 将 Python 项目从 anthropic 0.x 迁移至 1.x,skill 参考资料已更新至 1.x(叙述性内容);数据驻留工作区的 1.1 倍仅限美国推理附加费 现已计入 /cost、状态栏和 --max-budget-usd 的估算;Windows 跨会话消息传递(SendMessage/ListAgents 现已覆盖全部三个平台);name@synced claude.ai 插件,可通过 claude plugin enable/disable &lt;name&gt;@synced 操作,绝不覆盖同名的本地安装;ListAgents 显示自身名称并列出在线队友;"readline" 按词移动快捷键(Alt+F/Alt+D/Ctrl+Y,以标点分隔);/goal 检查退避(30 分钟→1 小时→2 小时)以及通过 --resume 选择器恢复目标;Bedrock/Vertex/Foundry 上的一次性全屏提示(这些平台上的新安装默认以全屏启动)。来自第 34 周文档摘要的状态变更: /design 研究预览版已加入斜杠命令表(可在 artifacts 上编辑 UI 画板;Pro/Max/Team/Enterprise;v2.1.233+)—— 它在一个已覆盖的版本窗口内发布,但正文此前未作介绍;Remote Control 已脱离研究预览阶段 —— 正文中的两处标签均已更正,并补注了设备卡片。仅见于更新日志: 重试看门狗在达到支出上限/额度耗尽时快速失败;Bedrock 流式代理重复计费修复;Esc 竞态/空闲会话修复;WebFetch 的 15 分钟缓存现已真正生效;/resume 目录冲突及已删除 worktree 修复;带 UTF-8 BOM 的 agent/skill 文件不再被忽略;hook 延迟工具的 OTel 追踪碎片化修复;掩码输入的粘贴/历史记录加固。v2.1.241 是撰写本行时的最新版本。 205
2026-08-20 指南 v2.90:CLI v2.1.235–238(8月18–20日)。 值得写入正文: 内置 “Concise”(简洁)输出风格(结果优先,可在 /config 中选择;v2.1.237);ANTHROPIC_DEFAULT_MODEL 环境变量 —— 新会话启动时使用的模型,/model 的选择仍会覆盖并持久保存(v2.1.236,环境变量表);可选的 spellcheck 设置,使用已安装的 aspell/hunspell/ispell(v2.1.235);keybindingFlavor 设置,"readline" 与默认的 "classic" 二选一(v2.1.238,键盘快捷键);面向插件市场和 MCP 的 headersHelper —— 通过本地命令生成短期有效的 HTTP 标头,目录条目的 helper 仅在安装/更新时于显示之后运行(-y 可跳过 [y/N] 确认),项目/插件/agent 作用域的 helper 在文件夹信任保护下以剥离凭据环境变量的方式运行(v2.1.238);跨会话 SendMessage 的 notify_when_idle 以及投递诚实性 —— 被拒绝/丢弃的消息现在会报告给发送方,超大消息会被预先拒绝(v2.1.235–238,跨会话消息传递);自动模式会搁置 Monitor 允许规则,并在 Bedrock/Vertex/Foundry 上以 Claude API 默认值运行其分类器,同时关闭遥测(v2.1.236,沙箱模式);macOS 沙箱通配符读取拒绝规则的优先级 —— **/.env 这类规则在允许读取的区域内同样生效,且不受重命名影响(v2.1.236);面向 Team/Enterprise 的 /usage 用量额度支出行(v2.1.236);自托管 runner 新增 --defer-shutdown-max-min 以及按连接设置的 --proxy-authorization-command/-file(v2.1.238)。仅见于更新日志: 斜杠命令拼写错误不再执行最接近的模糊匹配;/goal 空闲检查按 30 分钟/1 小时/2 小时逐级延长;全屏模式下 Ctrl+L/Cmd+K 双击触发 /clear 的快捷键已移除(本指南从未记载);针对 LLM 网关和自定义 base URL 的提示缓存修复(v2.1.237);长会话内存无限增长修复;回顾摘要上限为 400 个字符;claude mcp list/get 会显示已禁用的服务器但不对其做健康检查;print/SDK 模式下的 SIGTERM 干净退出(退出码 143);Remote Control 弹性修复批次(数秒内离线、容忍 403、崩溃后复用、模型选择同步);Fable 5 额度提示回退修复;VS Code 转录文本的屏幕阅读器支持。v2.1.238 是撰写本行时的最新版本。 246
2026-08-17 指南 v2.89:文本水印已公布(8月14日)—— 模型区域新增小节。 已对照 Anthropic 的官方公告核实,与外界讨论相反:水印仅适用于未来模型;当前整个产品线(Fable 5、Opus 5、Sonnet 5、Haiku 4.5)均在欧盟《人工智能法案》第 50 条的截止日期(8月2日)之前发布,目前处于过渡期 —— 如今 Claude Code 的输出尚未加入水印,与“Claude 现在对所有内容加水印”之类的标题相左。机制:SynthID-Text 变体,基于随机源的 token 选择,在模型层面实施(上线后覆盖所有界面)。代码 = 稀疏水印(注释/命名;“对实际生成的代码影响微乎其微”)。轻微编辑后水印仍在,完整重写会将其去除,Claude 翻译会重新加注。检测 API 已在规划中;检测只能证明参与,而非作者身份;未提及退出选项。 252
2026-08-17 指南 v2.88:CLI v2.1.234(8月17日)。 值得写入正文: 会话现在会在 claude.ai 用量限制重置后自动继续(/config 中的开关“Continue automatically at usage limit”);新增环境变量 CLAUDE_CODE_PROJECT_DIR_NAME(为采用按会话配置目录的主机提供简短的按项目转录目录名)和 CLAUDE_CODE_GOAL_CHECKIN_MINUTES(后台任务使 /goal 停滞 30 分钟以上时会被检查;设为 0 可退出)—— 两者均已列入环境变量表;当某一轮因不可恢复的错误而中止时,/goal 也会自行清除。仅见于更新日志: /permissions 和 /add-dir(以及全屏模式下的 /theme、/config、/help、/advisor)现在可以在轮次中途打开,规则变更会应用于该轮的剩余部分;通过已认证的 glab 在页脚和状态栏显示 GitLab MR 徽章(!N,草稿/待处理/绿色);新增 selection:clear 键绑定操作;内置 claude-api skill 的上下文开销通过按需加载参考资料从约 200k token 削减至约 25k token;安全加固在远程读取、会话恢复、CLAUDE.md 包含、工作流脚本和上传中一律拒绝 Windows NT 命名空间(\??\)路径(进一步封堵 NTLM 泄露途径);自动模式在经过多次压缩的长会话中不再重复拒绝沙箱网络访问;会话级权限回答在后台子代理提示后依然有效;MCP 诊断信息不再打印已解析的密钥;strictKnownMarketplaces 封堵了一个 SCP 式的主机不匹配漏洞;Remote Control 账户切换会在数秒内停止会话并给出原因,向客户端发布权限模式/模型/努力程度的变更,手机/网页端选择的努力程度现在也会生效;排队的 ! 命令和全屏渲染器重启修复(后者此前会丢失权限模式和工具规则);自己的提示在转录中以 markdown 渲染;自动生成的会话标题读起来像名称而非句子;“Default teammate model”设置已移除(队友跟随领队的模型,除非生成时指定了模型 —— 本指南从未记载,因此正文无需更改)。v2.1.234 是撰写本行时的最新版本。 253
2026-08-15 指南 v2.87:CLI v2.1.233(8月14日)。 值得写入正文: 待办/任务跟踪工具(TodoWrite、TaskCreate/Get/Update/List)在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上默认关闭 —— 可通过 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 恢复(环境变量表 + TaskCreated hook 行已更新);新增环境变量 CLAUDE_CODE_TOOL_MEMORY_LIMIT(为 Bash 命令可选启用的 Linux 内存 cgroup)和 CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS;--worktree 中的 GitLab MR URL 在 claude agents 中以 !N 形式显示;用于在代理之后按用户归集支出的 forward_user_identity apps-gateway 设置。对 v2.1.232 记录的更正: Cygwin 式符号链接的 Bash 权限变更和输入重定向(< file)检查已被回退(官方承诺稍后推出范围更窄的版本),v2.1.232 的一个自动模式回归问题(Windows 上普通的 cd && command > file 反复弹出审批提示)已修复。仅见于更新日志:针对 NT \??\ 设备前缀路径的 NTLM 凭据泄露修复;自托管 runner 会话启动更快;MCP v2 订阅/监听在无服务器主机上的重连修复;Desktop/VS Code 下的权限提示现在会触发 Notification hook;沙箱化 Linux 上空闲会话 100% CPU 占用修复;捆绑 skill 别名遮蔽修复(-p 模式下的 /checkup、/review);参数替换重复展开修复;claude plugin validate 会检查裸 .claude/skills 目录;面向屏幕阅读器的 /effort 改进;print 模式下的 [claude-code:unrecognized_model] stderr 诊断信息;在 gitlab/bitbucket 远程源上不再显示 GitHub 应用提示。v2.1.233 是撰写本行时的最新版本。 254
2026-08-14 指南 v2.86:CLI v2.1.231 + v2.1.232(均于8月13日发布)。 v2.1.232 值得写入正文的内容:子代理默认启用 fork —— subagent_type: "fork" 继承完整对话与提示缓存,非队友的交互式生成在后台运行(参见“子代理”一节);在提示中以 @ 提及活动会话,经由 SendMessage 路由,裸名精确匹配投递取代了 [ref] 确认,每台机器的会话名称唯一(name-word-word 变体),/config 新增“对话框过期”和“跨会话入站”两行(参见“跨会话消息”一节);GitLab 对等支持 —— 九类 GitLab 令牌被脱敏(glrt-、gloas-、glptt-、glagent-、glimt-、glsoat-、glcbt-、glft-、glffct-;可路由的 glpat-/gldt- 完全脱敏),glab CLI 配置获得与 gh 同级的沙箱保护,裸 gitlab.com 市场 URL 的克隆方式与 GitHub 一致;市场设置别名 additionalMarketplaces/allowedMarketplaces(参见“托管设置”一节);对于拥有访问权限的组织,Fable 5 重新回到 /advisor。安全修复:PowerShell $PSDefaultParameterValues 权限绕过、Git Bash Cygwin 符号链接写入绕过、嵌套 git 仓库不再继承父目录的信任。仅见于更新日志:网关 desktop: 覆盖层接受所有 Desktop 设置并在启动时进行 schema 校验,空的策略组/管理员组及格式错误的邮箱域名条目会在启动时报错,Remote Control 桥接/恢复/历史修复,MCP 连接超时修复,mTLS 证书热重载,Bedrock/Vertex 上的区域回退与流空闲恢复修复。v2.1.231(8月13日)仅含一项修复 —— MCP OAuth 针对预注册客户端(如 Slack)的 redirect-URI 不匹配问题。v2.1.232 是撰写本行时的最新版本。 255
2026-08-12 指南 v2.85:CLI v2.1.228(8月11日)+ v2.1.229(8月12日)。 v2.1.229 值得写入正文的内容:插件市场command 来源 —— 由本地命令输出插件目录,每个会话重新解析、无需重启,mode: "link" 则直接就地使用(参见“插件管理”一节);claude remote-control --continue 恢复最近一次 Remote Control 会话;ListAgents 将已断开的 Remote Control 会话标记为 offline,并将云端会话标注为 cloud;/commit-push-pr 不再自动批准带有危险标志(--force、--amend、--no-verify)的 git/gh 命令;沙箱域名列表要求 IPv6 字面量加方括号,采用失败即拒绝(fail-closed)的方式强制执行,并由 /doctor 标出;自托管运行器遵循服务器下发的 hooks,Windows 需要显式指定 --base-dir;工作流扇出会错开同前缀的兄弟代理以复用提示缓存(CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0 可禁用);VSCode 新增侧边栏会话分组和可调整大小的 /btw 面板。v2.1.228 与正文相关的内容:在较新的模型上,Write 工具现在遵循与 Edit 相同的规则(覆盖未读取的文件不再要求本会话先行读取);从 claude.ai 同步的 skills 得到加固(不会遮蔽本地命令/MCP 提示,带标签的描述经过净化,不进行 !/@ 展开)。两个版本中仅见于更新日志的内容:TUI 重绘/流式输出/崩溃修复(窄终端下的 RangeError 可能导致 --resume 失效),跨会话首次安装收件箱修复及内联消息显示,Remote Control /resume 历史泄漏修复,Vertex 凭据快速失败,MCP OAuth 127.0.0.1 重定向,/model 在网关上的 1M 修复,自动模式归属标头修复,自托管运行器检出/清理修复,记忆文件夹清理修复,市场设置合并修复,32MB 请求压缩提示更清晰,OTel Desktop 网关修复,/login 令牌覆盖警告重复提示,首次使用提示中移除了自动模式费用说明。v2.1.229 是撰写本行时的最新版本。 256 257
2026-08-12 指南 v2.85:需求驱动的章节 —— 8月12日的第14天数据读取确认了7月28日的 codex/hermes 实验(codex 每日点击量 +109%),本指南是推广目标(周排名 21.1,崩盘前约为 9-12)。GSC 人工查询审计发现,该页面 42% 的展示落在没有对应标题可承接的查询上;为此新增三节:“设置速查:搜索最多的标志”(disableBundledSkills、sandbox.excludedCommands、strictAllowlist、worktree.bgIsolation、allowAllClaudeAiMcps、wslInheritsWindowsSettings —— 六项中有五项的版本锚点来自本指南自身的更新日志;excludedCommands 早于更新日志的覆盖范围)、“各主题的官方文档在哪里?”(主题 → code.claude.com 规范页面 → 指南内章节,共十行;八个 slug 来自现有已做链接检查的脚注,hooks 指南和设置两项在添加时实时抓取),以及 “Claude Code Hooks 与 Agent SDK Hooks 的对比”(约 1,000 次展示却零点击的 SDK 生命周期查询簇:include_hook_events / includeHookEvents 流消费、依据在线 Agent SDK hooks 文档核对的载荷形状一致性,以及来自 Agent Architecture 指南 SDK 部分的“生命周期边缘默认放行”强制执行注意事项)。标题/H1 未变;描述在之前的周期中已清理干净。第14天数据读取约在8月26日。无新的 CLI 版本发布。 —
2026-08-11 指南 v2.84:自2026年8月14日起,自动模式成为 Pro、Max 和 Team 套餐的默认权限模式(8月7日宣布;没有 CLI 版本发布 —— 这是套餐层面的推广)。这些套餐上的会话默认以自动模式启动:每次工具调用都经过一个分类器,其目标是“拦截不可逆、具有破坏性或指向您环境之外的操作”。Anthropic 给出的依据:一项 1,053 名测试者参与的研究显示,自动模式拦截了 89% 的危险命令,而人工审核仅为 13.6%,用户对 97% 的权限提示都选择了批准;分类器的 token 开销在 Pro/Max/Team 上不再计费。退出方式:按会话使用 Shift+Tab,用 defaultMode 固定,或在组织范围内使用 disableAutoMode 托管设置。Enterprise/API/Bedrock/Google Agent Platform/Foundry 仍为可选启用,官方表示将在未来一个月内跟进。已更新:TL;DR、权限模式表格及新增的公告段落、自动模式可用性说明(“Pro 不可用”的时代已经结束 —— 作为历史保留)、快速参考行。 203
2026-08-11 指南 v2.83:CLI v2.1.227(8月10日)—— 仅含错误修复与打磨;仅见于更新日志,正文各节无需更新。修复:当会话以过期的登录令牌启动时,功能标志的求值未考虑用户的订阅层级,可能错误地提示 Max 用户为 Fable 启用用量额度;在 GitHub 托管的运行器上,claude-code-action 配合 allowed_non_write_users 时所有 Bash 命令均失败;/tui 会重新调出已回退到首条消息之前的对话。改进:斜杠命令菜单高亮(蓝色仅标记选中行,匹配字符加粗,emoji 和带重音符号的名称保留其字形),以及在文件未找到建议和 @ 提及大小检查时事件循环卡顿减少。v2.1.227 是撰写本行时的最新版本。 258
2026-08-09 指南 v2.82:整体审计清扫 —— 首次全指南评估器通读得出 15 项发现(8.98 分,而标准为 9.3 分;逐版本的循环保持了前沿章节的准确性,但 2026年4月的一层内容却原地过时了)。模型时效性集群已按当前阵容在六处重写:套餐默认模型表、Opus 层级简介、API 定价表(Opus 5 为旗舰,4.8/4.7 为旧版)、快速参考模型块、ANTHROPIC_DEFAULT_OPUS_MODEL 示例、Codex 对比的基础模型行 —— 4月数据保留并标注为历史数据。已修正的明显矛盾:已移除的 --enable-auto-mode 标志不再作为进入自动模式的方式讲解(应为 --permission-mode auto);两节中的自动模式分类器均更新为 Sonnet 5(v2.1.210),并替换了过时的“Team 优先/需要 4.6”可用性说明;子代理并发数在四处统一为默认值 20(示意图、简介、Codex 表格、Agent Teams 对比);Explore 的模型卡片现在注明继承会话模型(v2.1.198);Codex 表格中的 hook 数量 22 → 31(v2.81 的核对遗漏了这一点,其对应行已修订);Ctrl+F 终止所有代理的快捷键已改绑为 Ctrl+X Ctrl+K(v2.1.83)。TL;DR:v2.1.202 的 /review 拆分现在内联注明了其在 v2.1.223 的重新合并,另有一句涵盖 v2.1.221–226 的内容:跨会话消息、自托管运行器、插件 archive 来源、凭据遮蔽扩展、Focus 视图、/fork 工作树,以及 200 上限/ultraplan 的移除。小规模清扫:移除了过时的 v2.1.154 验证戳;扩展思考一节前置了 2026年8月的模型支持说明;修正了 Claude-in-Chrome 的目录锚点并将 Microsoft 365 加入目录;MCP 生态系统数量统一为 3,000+ 服务器;虚构的 PreCommit hook 事件替换为真实机制;已过期的推广措辞(Fable 5、语音模式)改为过去时;跨会话传输的措辞不再与 v2.1.225 的发起方式变更相矛盾。无新的 CLI 版本发布。 187194197199200201202259
2026-08-09 指南 v2.81:可用事件表已补全至参考文档的全部 31 个事件——此前有六个已记录在案的事件缺少对应行:UserPromptExpansion(拦截/审计键入命令的展开)、PostToolBatch(在一个并行工具批次与下一次模型调用之间触发;退出码 2 会中止代理循环)、MessageDisplay(通过 displayContent 进行仅限显示的文本转换,v2.1.152)、TaskCreated(退出码 2 会回滚创建操作,v2.1.84),以及 CwdChanged/FileChanged(v2.1.83;FileChanged 监视通过 SessionStart hook 的 watchPaths 输出注册的路径)。同时校正了竞品对比章节中过时的 hook 数量(12+/22 → 31;Codex 表中的 22 在那一轮中被遗漏,已于同日在 v2.82 中更正)。更正——不存在的 $FILE_PATH:有五个 hook 代码示例使用了 $FILE_PATH(或 $TOOL_INPUT_FILE_PATH)环境变量,而 Claude Code 并不会设置该变量——参考文档中没有记载此类变量;工具输入仅以 stdin JSON 的形式传递给命令 hook。这五个示例均已改写为文档记载的 jq -r '.tool_input.file_path' stdin 模式(指南自身的保护文件示例原本就是正确的);Hook 环境变量表则一直是正确的。此缺口由第二波既往内容门禁发现:对照线上 hooks 参考文档核验的卫星文章统计出 31 个事件,而本表只有 25 个——v2.1.83/84 和 v2.1.152 的更新日志行记录了这些事件,但表格行始终未曾落地。无新的 CLI 版本发布。 4
2026-08-08 指南 v2.80:扩展覆盖范围,无新版本发布。跨会话消息传递章节已根据 Anthropic 的专门文档页面重建(该页面与 v2.1.224 同时发布):/list-agents+/peers 以及 /status 的 Peer address 行;接收方的四条规则(不做审批、不改配置、命令按文本处理、提示仍会触发);crossSessionInbound 的 accept/hold/refuse 及其以两类权限为准的默认值、五分钟的 dialogExpiry、100 条暂存上限;无头 -p 工作进程会绑定套接字,但需要 accept 才能在无人值守时接收消息;传输方式表(同机 Unix 套接字从不经由 Anthropic 服务器,跨机器仅能通过 Remote Control 回复,可达性取决于文件系统可见性);isolatePeerMachines 的只收紧语义;通过 CLAUDE_CODE_MESSAGING_SOCKET 实现脚本化收件箱,并附带依平台而异的自有子进程验证;循环节流(速率限制、去重、50 条未读上限);可用性陷阱,包括四个会悄然禁用该功能的特性开关环境变量。配套文章:Claude Code 中的跨会话消息传递。 259
2026-08-07 指南 v2.79:CLI v2.1.225–v2.1.226(两者均发布于 8月7日 PST)。v2.1.225 对 v2.1.224 的功能浪潮做了细化。SendMessage 现在可以按名称向您在其他机器上的 Remote Control 会话发起对话——ListAgents 将它们显示为 name [ref];此前只能回复(参见跨会话消息传递)。已确认的 Remote Control 接收方绝不会被悄然替换为同名的本地会话。用量警告新增网关支出上限支持:达到上限的提示会注明上限值、重置时间以及网关运营方的留言(需要网关运行在 2.1.225)。claude agents 对不受信任的目录新增工作区信任提示,与 claude 保持一致。值得了解的修复:瞬时 401 可能会用已存储登录的短期令牌替换长期有效的 CLAUDE_CODE_OAUTH_TOKEN,导致无头会话在重启前一直失效;macOS 上的 MCP OAuth 服务器在钥匙串读取超时后可能出现 401 连发而失败;auto 模式不再将安全过滤器对其自身权限检查的拒绝计入连续拦截上限;跨会话消息不再在无头会话中悄然滞留;当 --base-dir 不可写时,claude self-hosted-runner 会在启动时给出明确错误并退出,而不是让每个会话都失败;VSCode 的 Focus 视图会保持最新的待办列表和待回答问题处于展开状态。v2.1.226 仅包含错误修复和可靠性改进。截至本行撰写时,v2.1.226 为最新版本。 202
2026-08-07 指南 v2.78:CLI v2.1.224。自托管运行器——claude self-hosted-runner 让 Claude Code 的网页、移动端和桌面端会话在您自己的机器或容器上执行(Team/Enterprise;参见自托管运行器)。跨会话消息传递——各会话可通过 SendMessage 配合 ListAgents 发现机制在您的多台机器之间互发消息(macOS/Linux);新增的 crossSessionInbound 和 dialogExpiry 设置会暂存发往已绕过权限会话的消息,等待审批(参见跨会话消息传递)。archive 插件来源——通过 HTTPS 从 zip 包安装插件,可选 SHA-256 固定校验(参见插件管理)。沙盒凭据遮蔽功能扩展——针对结构化环境变量值的 extract/onExtractNoMatch、带 maskClaims 的 decode: "jwt",以及 awsPairs/sigv4 AWS 重签名;需要 network.tlsTerminate,且仅在 user/managed/--settings 作用域下生效(参见沙盒模式)。每会话 200 个子代理的生成上限已取消——长时间运行的会话不再拒绝新代理;并发数(20)和深度(3)限制仍然适用,CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 可重新设定预算(参见子代理)。安全修复:超过 200 个字符的项目路径可能解析到另一个项目的会话目录(会话列表/重命名/分叉/删除以及 /resume 不再跨项目);以斜杠结尾书写的沙盒文件系统拒绝条目(denyRead: "~/.aws/")在 Linux 和 macOS 上可被悄然绕过;沙盒违规详情现在会出现在 Bash 工具结果中,让 Claude 能看到哪项访问被拒以及原因。隐私说明:反馈调查的记录分享现在在征得同意后还会上传上一次请求的系统提示(包括 CLAUDE.md)、工具定义和模型参数,密钥会被脱敏。仅见于更新日志:ANTHROPIC_BEDROCK_REGION_PREFIX;移除不可用的粘贴内容会改变命令时,先取消再确认;SendMessage 收件箱写入失败现在报告为错误而非“Message sent”;回合中途加入的 MCP 工具会公布其名称以供工具搜索;插件安装记录在多项目安装时不再损坏;全屏回滚保留压缩前的完整历史;Remote Control 的压缩进度、重连指示器、过期会话归档以及冷启动凭据修复;Wayland 选中即复制的竞态修复。截至本行撰写时,v2.1.224 为最新版本。 201
2026-08-06 指南 v2.77:CLI v2.1.223。/review 现在是 /code-review 的别名——v2.1.202 引入的双命令拆分已不复存在;/code-review ultra 是深度云端审查,而不带参数的 /code-review 会沿用您上次键入的推理强度级别(参见斜杠命令)。strictKnownMarketplaces 和 blockedMarketplaces 支持 "owner/*" 通配符——一条配置即可允许或拦截某个 GitHub 组织下的所有市场仓库(参见托管设置)。CLAUDE_CODE_DISABLE_1M_CONTEXT 适用范围扩大:它现在通过自动压缩将所有原生支持 1M 窗口的模型限制在 200K,而不再依据固定列表;当自动压缩未能守住这一界限时,启动时会发出警告;自动压缩还会将使用未识别模型 ID 的会话保持在假定窗口之内(CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 可恢复先前行为——参见环境变量和我该选择哪个模型)。安全修复:精心构造的命令可以对 Bash 权限检查隐藏自身的一部分;用制表符或不可见 Unicode 填充的命令可以在审批对话框中隐藏部分命令内容;工作流脚本可以利用动态 import() 在工作流沙盒之外运行代码;代理定义中的 bypassPermissions 模式忽略了组织的绕过权限禁用策略。仅见于更新日志:当工作流代理、分叉技能或恢复的后台代理所请求的子代理模型受限、改由父模型运行时发出警告;云端会话中的 /teleport 提示;/cd 之后再恢复不再返回空内容;网关模型发现不再隐藏带提供商前缀的 Claude ID(vertex_ai/claude-*、bedrock/anthropic.claude-*);非 Anthropic 的 modelOverrides 键按文档说明被忽略;服务器下发的托管设置不再禁用本机 managed-settings.json 的 env 块(管理员 env 按键合并);修复了 denyWrite 覆盖当前工作目录时 Linux 沙盒无法启动的问题;修复了分叉后台代理恢复时的死锁;修复了格式错误的诊断信息导致恢复崩溃的问题;修复了罕见的 git push 输出解析挂起问题。截至本行撰写时,v2.1.223 为最新版本。 200
2026-08-05 指南 v2.76:CLI v2.1.221–v2.1.222。v2.1.221(8月4日): VSCode Focus 视图——聊天菜单中的开关,可将工具活动收进可展开的每轮摘要,并附带实时的运行中工具指示器,快捷键 Ctrl+Alt+F(参见 VS Code 扩展)。sandbox.credentials 文件新增 mode: "mask"(Linux/WSL)——沙盒内的读取得到的是哨兵副本(整个文件,或由 extract 正则捕获的片段),沙盒代理服务器在出站时替换为真实值;在 macOS 上 mask 回退为 deny(参见沙盒模式)。后台会话的 git 行为有变:提交并推送以保留工作成果,仅在任务需要时才起草 PR,遵循 CLAUDE.md 中的 git 指示,并始终报告工作成果所在位置(参见在后台运行代理)。/fork 副本现在拥有各自的 worktree,不再与原始检出共享。Plugins:/plugin install 会刷新过期的市场目录并重试;安全时安装即刻生效(无需 /reload-plugins);清单接受 "." 作为 skills 路径。安全修复:zsh 可在 [[ ]] 正则条件中执行隐藏命令,从而绕过 Bash 权限检查(现在会提示);PowerShell 在 Windows 上错误处理带引号字符的路径(现在会提示)。此外:claude-api skill 新增 prompt-audit 子命令;关闭思考时在 xhigh/max 努力级别下 WebSearch 不再返回 400;统计面板会统计缓存 token,并按输入/输出/缓存读取/缓存写入细分;自动模式的权限检查复用已缓存的对话前缀(更省钱、缓存效率更高);Vim 的 yank 寄存器在对话框/历史记录/转录视图之后仍会保留;/status 显示会话类型(interactive,后台 attached/unattended);表情符号自动补全接受 :thumbsup: 一类的替代写法;快速模式在会话中途用量额度耗尽时会在流中报告。v2.1.222(8月4日): Remote Control 自动启动不再能通过仓库本地设置启用——仅限用户范围,通过 /config 设置;仓库设置仍可将其禁用(参见 Remote Control)。安全:worktree 隔离的会话及其 subagents 曾可对主检出运行破坏性 git 命令——隔离现在对所有会话类型的文件编辑和 Bash 均生效;PreToolUse 自动允许 hooks 不再绕过后台代理任务中的工具限制;发往其他会话的 SendMessage 载荷现在在分发前先经过权限分类器(这是自动模式的一项安全改进;分类器会在自动模式下审查发送内容)。移除了 ultraplan。仅见于更新日志:/usage 的 MCP 归因现在只统计消耗了某服务器工具结果的请求;受组织限制时,model: opus 一类的别名会降级为组织允许的最新同系列模型,而非退回父模型;/diff 和工作区差异使用原始 git blob 内容(忽略 diff 驱动/textconv);带 disable-model-invocation 的 skills 会返回一条拒绝信息,告知 Claude 应请您自行运行;启动时的连通性检查可识别代理服务器;流空闲超时会尊重网关的保活信号;会话会关联推送后创建的 PR。撰写本行时,v2.1.222 为最新版本。 199
2026-07-25 指南 v2.75:CLI v2.1.219–v2.1.220 + Claude Opus 5。Claude Opus 5(claude-opus-5)是新的默认 Opus,也是 /model opus 所选中的模型(v2.1.219):1M 上下文,最大输出 128K(在 Batches 上配合 output-300k-2026-03-24 beta 可达 300K),每百万 token $5/$25——与 Opus 4.8 相同,自适应思考,effort 在 Claude API 和 Claude Code 上均默认为 high(级别梯度为 low/medium/high/xhigh/max),可靠知识截止日期为 2026年5月。它是 Claude Max 的默认模型,也是 Claude Pro 上最强的模型;Opus 4.8 移入文档的旧版模型(Legacy models)表。相较 Opus 4.8 的两项破坏性变更:未带 thinking 字段的请求现在默认开启思考;thinking: {type: "disabled"} 与 xhigh 或 max 努力级别组合会返回 400(逐请求校验)。参见我该选择哪个模型。更正——快速模式:本指南此前将快速模式描述为研究预览功能,仅限 Opus 4.6,价格 $30/$150(基础价的 6 倍),且不适用于 Opus 4.7。自 v2.1.219 起,/fast 适用于 Opus 5 和 Opus 4.8,价格为每百万 token $10/$50(基础价的 2 倍),每秒输出 token 数最高可达 2.5 倍;Opus 4.7 已从快速模式中移除,claude-opus-4-7 搭配 speed: "fast" 现在会报错,而不再回退到标准速度(Opus 4.6 仍是静默回退的例外)。仍属研究预览,仅限 Claude API——不支持 Bedrock/Vertex/Foundry/AWS 上的 Claude Platform——拥有独立的速率限制,且切换速度会使提示缓存失效。该节已重写。更正——subagent 嵌套:v2.74/v2.73 的文字称嵌套生成默认关闭(v2.1.217)。v2.1.219 再次反转:subagents 默认可嵌套生成 subagents,最深 3 层;CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可禁用嵌套。该默认值在六周内已从 5 → 1 → 3 几经变动,建议显式固定该值,而不要沿用默认(参见 Subagents 与环境变量参考)。新增 DirectoryAdded hook 事件——在 /add-dir 或 SDK 的 register_repo_root 控制请求于会话中途注册新的工作目录后触发(参见 Hook 事件)。新增 sandbox.network.strictAllowlist 设置——对沙盒命令访问未列入允许列表的主机直接拒绝,不再提示(参见沙盒模式)。动态工作流现在默认采用中等规模指引(“力求少于 15 个代理”),并新增 workflowSizeGuideline 设置键,可在任意设置文件中设置;设置后 /config 中的对应行会隐藏,运行中工作流的状态行会显示当前规模。stream-json 中的嵌套 subagent 转发——深度 2 及以上的 subagents 现在可通过 --forward-subagent-text 显示,以生成它们的 Agent tool_use id 为键。仅见于更新日志:无头 stream-json 初始化事件新增 mcp_server_errors,列出因配置校验而被跳过的 --mcp-config 条目(终端运行时会打印启动警告);托管 MCP 允许列表/拒绝列表中的 ${VAR} 条目改为从启动环境和托管设置的 env 解析,而非设置文件的 env;/model 选择器显示合并后的 “Opus (1M context)” 行而非单纯的“Opus”,且只高亮最新模型的名称;在包含 Fable 的套餐上,Fable 行不再显示过时的“需要用量额度”标签;当某轮因流中途的 API 错误而中断时,claude -p 不再丢弃已生成的文本;claude --teleport 在不匹配时会指出您的检出所指向的仓库;/claude-api skill 默认使用 Opus 5,并提供 4.8 迁移路径;修复了 Remote Control 在切换/重连/组织检查失败后快速模式状态过期的问题,“仅可通过 api.anthropic.com 使用”错误现在会指出引发它的设置;CLAUDE_CODE_GIT_BASH_PATH 指向非 bash 二进制文件时会被忽略并给出警告,而不是直接退出;GNU screen 的选中即复制不再输出 base64;Vim NORMAL 模式下在空提示符上按 ← 会返回代理视图;屏幕阅读器模式只回显输入的字符,而不再重写整行输入。v2.1.220(7月25日)仅包含错误修复与可靠性改进。另有更正:2026-07-24 行将 MCP HTTP 状态/空白字符警告一项归于 v2.1.218——实际随 v2.1.219 发布。撰写本行时,v2.1.220 为最新版本。 196197198
2026-07-24 指南 v2.74:CLI v2.1.218。/code-review 现在作为后台 subagent 运行——审查工作不再占据您的对话;堆叠的斜杠命令仍是审查目标(参见“斜杠命令”)。context: fork skills 默认在后台运行——可通过新的 background: false frontmatter 键按 skill 单独退出(参见“Skills Frontmatter 参考”)。自动模式对话框精简:危险 rm、后台 & 和可疑 Windows 路径检查不再弹出权限对话框——改由自动模式分类器裁决;自动模式下的计划模式不再对静态分析器无法证明为只读的 Bash 命令发出提示——改由分类器判断(参见“自动模式”)。安全:agent frontmatter hooks 不再从不受信任的文件夹运行——agent 文件所在的文件夹必须已接受工作区信任(参见“组件范围的 Hooks”)。/deep-research 仅限手动调用——Claude 不再自行启动它,与 v2.1.215 的 /verify//code-review 规则保持一致。仅见于更新日志:claude mcp list 和 /mcp 在连接失败时显示 HTTP 状态码和错误文本,并对带有隐藏首尾空白字符的 MCP 配置值发出警告(2026-07-25 更正:此项实际随 v2.1.219 发布,而非 v2.1.218——此处曾错误归入了另一版本);编辑后紧接着按左箭头键,现在会先确认再丢弃对话,在 agent 视图中按 Esc 会返回到被其转入后台的那个对话;服务器托管设置——无害的功能/成本开关跳过设置审批提示;拒绝包含 : 的 agent 名称(保留用于 plugin 命名空间);skill/plugin frontmatter 布尔值接受 yes/no/on/off/1/0;信任对话框会标明授权所覆盖的仓库根目录;改进了 IDE 交互的沙箱命令限制;Ctrl+B 转入后台时应用标准的后台 shell 上限;Bedrock application-inference-profile ARN 按所配置模型的费率计量;无头/SDK 会话在压缩后保留 fork 会话的谱系;修复 Windows \u 路径损坏问题;远程会话在其 worker 被替换后不再发送僵尸心跳。撰写此行时,v2.1.218 是最新版本。 195196
2026-07-22 指南 v2.73:CLI v2.1.217。Subagent 嵌套默认行为反转:subagents 默认不再派生嵌套的 subagents——设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 可允许更深层的嵌套。这使 v2.1.172 的“最多 5 层递归 sub-agents”不再是默认行为(v2.1.172–v2.1.216 期间递归为默认;参见“Subagents”及环境变量参考)。新增并发上限:默认最多 20 个同时运行的 subagents(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS),以防一条消息无限制地扇出后台 agents——这与 v2.1.212 的每会话派生总数(CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION,每会话 200 个)是两回事。--max-budget-usd 现在会停止后台 subagents:一旦达到上限,新的派生请求被拒绝,正在运行的后台 agents 也会被中止(此前后台 agents 不受预算约束)。提示输入框中的表情符号短代码自动补全——:heart: → ❤️,输入部分内容即有建议——可用 emojiCompletionEnabled: false 禁用。仅见于更新日志:后台会话隔离会规范化符号链接的工作目录(不再能逃出工作区文件夹);托管的 OTEL_EXPORTER_OTLP_ENDPOINT 现在管控所有信号(更低作用域的信号专属覆盖不再能重定向遥测数据);当转录写入失败(如磁盘已满)或会话保存因继承的环境变量而关闭时发出警告;修复 MCP 截断输出的内存泄漏;Windows 自动更新在更新失败后恢复保留的 claude.exe;修复 Bedrock Opus 4.8 自动压缩//compact 问题;企业 mTLS/TLS 验证/OAuth 作用域/代理设置在 Claude Desktop 会话中得到遵循;修复 --resume//resume 在附件条目格式错误时的 TypeError;修复高负载机器上 /background 或退出后无法停止的后台 shell;启动时的大括号展开 OOM 现已受预算限制;Remote Control 的后加入者现在能看到待处理的权限提示;修复屏幕阅读器启动播报和思考行重新渲染问题;页脚 PR 徽章在 ssh/tmux 下可点击(FORCE_HYPERLINK=0 可退出);登录过期警告提前至 3 天(原为 5 天);frontend-design plugin 提示终身最多显示 3 次。v2.1.217 是最新版本。 194
2026-07-21 指南 v2.72:CLI v2.1.214–v2.1.216(v2.1.213 从未发布——与 2.1.188/189/192/194 相同的跳号模式)。v2.1.214——权限作用域变更:单段 dir/** allow 规则(如 Edit(src/**))现在只匹配 <cwd>/dir,不再匹配目录树中任意位置的 dir/——如需任意深度匹配,请写成 **/dir/**;deny/ask 规则保留任意深度匹配,hook 的 if: 条件同样采用这一 cwd 作用域(参见“权限规则语法”和“匹配器”)。失败即拒绝(fail-closed)加固批次:修复 Windows PowerShell 5.1 绕过;Bash 文件描述符重定向形式默认拒绝;超过 10,000 个字符的命令始终提示;[[ ]] 中的 zsh 下标/修饰符会提示;不安全的 help/man 变体不再自动批准;远程会话提示在本地确认之前无法继续;docker/Podman 守护进程重定向标志(--url、--connection、--identity、远程模式)会提示;file -m/--magic-file/-f/--files-from 需要权限。新增 EndConversation 工具——Claude 可在遇到高度辱骂性输入或越狱尝试时结束会话,与 claude.ai 自 2025 年以来的做法一致。SessionStart hooks 对 fork 的会话报告来源为 "fork"(原为 "resume")。OTel:CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 用于配置 60 KB 的内容截断限制;日志事件新增 message.uuid/client_request_id/tool_source;subagentStatusLine 载荷新增推理强度。仅见于更新日志:超过 2 MiB 的设置文件在启动时以明确的错误信息失败;记忆 frontmatter 中采用 ISO 格式的 modified 时间戳;长时间无输出的工具调用有进度心跳;修复 stream-json 退出排空的扩展性问题;当 stdout JSON 未通过 schema 校验时,hook 退出码 2 现在按文档所述进行阻止;修复 --settings 的 plugin 加载回归(自 v2.1.181 起);后台守护进程/会话生命周期清理;修复 pkill -f 自匹配问题。v2.1.215:Claude 不再自动运行 /verify 和 /code-review skills——仅限显式调用。v2.1.216:新增 sandbox.filesystem.disabled 设置——跳过文件系统隔离,保留网络出口控制(参见“沙箱模式”)。仅见于更新日志:修复消息规范化的二次方级变慢问题;修复 OAuth 轮换后自动模式出现 HTTP 401 的问题;worktree 隔离的 subagents 不再能将 git 重定向到共享检出(git -C/GIT_DIR);修复 .claude 符号链接写入重定向问题;/rewind 拒绝符号链接/硬链接恢复路径;/context 在上下文窗口溢出时发出警告;会话中途对 skill/命令的编辑无需重启即出现在斜杠菜单中;/fork 确认信息显示会话名称和 claude attach id;云会话在回合中途容器重启后可恢复。v2.1.216 是最新版本。 190 191 192 193
2026-07-17 指南 v2.71:CLI v2.1.206–v2.1.212。v2.1.212: /fork 现在会将对话复制到一个新的后台会话中,并在 claude agents 中拥有独立的一行;原先的会话内 fork 更名为 /subtask;新增 claude auto-mode reset 子命令(--yes 可跳过确认);每会话上限——WebSearch 与 subagent 生成各默认为每会话 200 次(CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION / CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION,/clear 会重置 subagent 预算);超过 2 分钟的 MCP 工具调用会自动转入后台(CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS);Task 工具的 mode 参数已弃用并被忽略——subagent 继承父会话的权限模式;企业级 forceLoginMethod 现对 VS Code 扩展、SDK、setup-token 和 install-github-app 强制生效(此前仅限终端)。v2.1.211: --forward-subagent-text / CLAUDE_CODE_FORWARD_SUBAGENT_TEXT 可将 subagent 的文本与思考内容包含在 stream-json 中;“Always allow”规则保存于仓库根目录,因此 worktree 中的批准得以持久保留。v2.1.210: 针对 Write(path)/NotebookEdit(path)/Glob(path) 权限规则的启动警告——请改用 Edit(path)/Read(path)。v2.1.208: 屏幕阅读器模式(--ax-screen-reader、CLAUDE_AX_SCREEN_READER=1、axScreenReader)并配有新的无障碍文档;通过 processWrapper/CLAUDE_CODE_PROCESS_WRAPPER 使用企业启动器;vimInsertModeRemaps(例如 jj→Escape);$(...)/反引号/<(...) 内的灾难性删除操作,即使在 --dangerously-skip-permissions 和自动模式下也会提示确认。v2.1.207: 在 Bedrock/Vertex/Foundry 上,Auto Mode 不再需要通过 CLAUDE_CODE_ENABLE_AUTO_MODE 显式启用(管理员可用 disableAutoMode);Bedrock/Vertex/Claude-Platform-on-AWS 默认使用 Opus 4.8;autoMode 不再从仓库的 .claude/settings.local.json 读取;plugin 安全——shell 形式的命令中拒绝使用 ${user_config.*}(请使用 exec 形式或 $CLAUDE_PLUGIN_OPTION_<KEY>),pluginConfigs 不再从项目设置读取。v2.1.206: /login 支持由 Anthropic 运营的公共网关端点;/commit-push-pr 自动允许推送到已配置的推送远程仓库(remote.pushDefault 或唯一的远程仓库),而不仅限于 origin。仅见于变更日志:计划模式下修改文件的 Bash 修复;worktree 符号链接逃逸修复;LLM 网关后的提示缓存;hook 返回 ask 时自动模式也至少会提示确认;权限预览的 Unicode 欺骗防护加固;worktree 隔离 subagent 修复;Agent 工具的提示注入防护加固;MEMORY.md 超出限制的错误提示;大规模性能批次(转录文件缩减 79 倍、SDK 工具轮次提速 7 倍);后台代理可自我升级。v2.1.212 为最新版本。 184 185 186 187 188 189
2026-07-09 指南 v2.70:CLI v2.1.203–v2.1.205。自动模式加固(v2.1.205): 会话转录文件受到防篡改保护;对分类器无法解析的变量执行 rm -rf 时现在会先行询问;后台任务通知会明确说明没有发生任何人工输入,因此伪造的转录内批准无法被洗白为真实批准(参见 Auto Mode)。/doctor 现已成为完整的设置体检,可诊断并修复问题,/checkup 为其别名(参见斜杠命令表)。v2.1.203: 页脚的灰色 ⏸ 标记表示手动权限模式;会话的附加工作目录通过 roots/list 向 MCP 服务器公开(并附带 notifications/roots/list_changed);修复了后台会话丢失 shell 导出的 ANTHROPIC_BASE_URL 的问题(请求被发送至默认端点并返回 401)。v2.1.204: 仅含错误修复(无头模式下 SessionStart hook 的流式传输)。仅见于变更日志:代理视图中的各行获得由分类器撰写的标题和 PR 链接;自动更新程序改为流式下载(峰值内存减少约 400 MB);“Claude Browser”这一 MCP 名称已被保留。v2.1.205 为最新版本。 183
2026-07-07 指南 v2.69:CLI v2.1.200–v2.1.202。权限模式 default 更名为“Manual”(v2.1.200),覆盖 CLI、--help、VS Code 和 JetBrains——配置值保持不变,--permission-mode manual / "defaultMode": "manual" 可作为别名使用(参见权限模式)。同一版本中:AskUserQuestion 对话框默认不再自动继续(可通过 /config 选择启用空闲超时),另有一批启动与后台会话的崩溃/可靠性修复。v2.1.201: Sonnet 5 会话不再使用对话中途的 system 角色来发送框架提醒。v2.1.202: 新增 “Dynamic workflow size” /config 控制项(建议性的小/中/大代理数量,并非强制上限)以及 workflow.run_id/workflow.name OTel 属性;/review <pr> 恢复为快速的单轮审查,多代理审查则保留在 /code-review <level> <pr#>(参见斜杠命令参考);重复调用已加载的 skill 不再在上下文中重复其指令;当服务器配置含有 url 但缺少 type 时,MCP 错误提示更加清晰。v2.1.202 为最新版本。 182
2026-07-03 指南 v2.68:CLI v2.1.196–v2.1.199。Sonnet 5 成为 Claude Code 的默认模型(v2.1.197,6月30日),原生支持 1M 上下文,并在 8月31日前享有 $2/$10 的促销价格——模型选择指南、别名表和 TL;DR 均已相应更新。v2.1.196(6月29日): 组织默认模型(由管理员设置,在 /model 中显示为“Org default”);可读的默认会话名称;Cmd/Ctrl 点击即可附加文件;安全——claude mcp list/get 在不受信任的工作区中不再启动仓库自行批准的 .mcp.json 服务器;流式空闲看门狗默认开启(CLAUDE_ENABLE_STREAM_WATCHDOG=0 可禁用);/code-review 查找器整合(token 用量减少约 25%)。更正:我们 7月1日的记录称,按验证时的权威变更日志,v2.1.196“不存在”;此后它已在该处发布,其功能与早期 GitHub 摘要所述完全一致。 v2.1.198(7月1日): subagent 默认在后台运行;Claude in Chrome 正式发布(GA);后台代理可从 worktree 提交/推送/打开草稿 PR;Notification hook 会触发 agent_needs_input/agent_completed;/dataviz skill;Explore 继承会话模型(上限为 Opus);subagent/压缩操作继承扩展思考配置;移除 /agents 向导(请直接编辑 .claude/agents/)。v2.1.199(7月2日): 堆叠的斜杠 skill 调用最多加载开头的 5 个 skill;订阅用户遇到瞬时 429 错误时会自动退避重试;CLAUDE_CODE_RETRY_WATCHDOG 对非容量类错误默认重试 300 次,并解除 CLAUDE_CODE_MAX_RETRIES 上限;另有针对后台代理/守护进程的大规模可靠性改进。v2.1.199 为最新版本。 181
2026-07-01 指南 v2.67:Claude Sonnet 5(2026年6月30日)。全新的 Sonnet 层级,可在 Claude Code 中通过 /model sonnet / /model claude-sonnet-5 选用。模型 ID 为 claude-sonnet-5(无日期的固定快照);1M 上下文,最大输出 128K(在 Batches 上配合 output-300k-2026-03-24 beta 标头可达 300K),仅支持自适应思考,知识截止于 2026年1月。定价为每 MTok $3/$15,2026年8月31日前的入门价为 $2/$10——比 Opus 4.8 低约 40%;Anthropic 将其定位为“以更低的价格接近 Opus 4.8”。在 Claude API 和 Claude Code 上,effort 默认为 high。已加入模型别名表、Sonnet 文字条目(Sonnet 4.6 标记为已被取代)以及定价表。已对照权威的 Anthropic 模型文档(platform.claude.com)核实。 180
2026-06-30 指南 v2.66:CLI v2.1.193–v2.1.195(v2.1.192 和 v2.1.194 未发布)。Hooks: 带有连字符标识符(code-reviewer、mcp__brave-search)的匹配器现在会精确匹配,而不再意外地进行子串匹配——若要匹配某个带连字符的 MCP 服务器的所有工具,请使用类似 mcp__brave-search__.* 的模式(参见匹配器)。Auto Mode: 新增 autoMode.classifyAllShell 设置,可将所有 Bash/PowerShell 命令都交由分类器处理(而不仅是代码执行模式),拒绝原因现在会显示在转录、弹出提示和 /permissions 中。遥测: 新增 claude_code.assistant_response OTel 日志事件,携带模型的响应文本——由 OTEL_LOG_ASSISTANT_RESPONSES 控制,未设置时跟随 OTEL_LOG_USER_PROMPTS,因此记录提示词的部署在升级后会开始记录响应(将其设为 0 可保持仅记录提示词)。新增环境变量: CLAUDE_CODE_DISABLE_MOUSE_CLICKS(禁用全屏鼠标,保留滚轮滚动)、CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP(关闭空闲后台 shell 的回收)。此外还有 bash 模式(!)下的实时文件路径自动补全,以及当 MCP 服务器需要认证时的启动提示。v2.1.195 的其余内容为语音/后台/plugin 的可靠性修复。v2.1.195 为最新版本。 179
2026-06-25 指南 v2.65:CLI v2.1.191。/rewind 可跨越 /clear: /rewind 现在可以恢复到 /clear 之前的对话(参见斜杠命令参考)。Hooks: 逗号分隔的匹配器(例如 Bash,PowerShell)现在能正确触发——早期版本会悄然忽略它们(参见“匹配器”)。沙箱: 网络权限对话框会在本会话的剩余时间内记住您允许的主机。修复:从任务面板停止后台代理现在是永久性的(不会复活);在 /permissions 的“最近拒绝”列表中做出的批准在关闭后仍然保留;/voice 会说明组织策略限制,而不是显示通用消息;通过 ssh/tmux 使用 Ghostty 时的 Cmd+点击链接;claude agents 不再将内置斜杠命令作为提示文本发送,也不再显示原始图片路径;80×24 终端下欢迎屏幕溢出的问题;通过 MDM 下发 forceRemoteSettingsRefresh。性能:流式响应期间 CPU 占用降低约 37%;减少了终端输出缓存导致的长会话内存增长。v2.1.191 是最新版本。 178
2026-06-24 指南 v2.64:Claude Tag(生态系统说明,并非 CLI 版本发布)。Anthropic 推出了 Claude Tag,这是一款面向 Claude Enterprise 和 Team 客户的 Slack 原生托管代理:在频道中标记 @Claude 即可委派任务,代理会将其分解为多个阶段并异步完成,然后将结果发回;共享的单一 Claude 身份让团队成员能够交接进行中的工作;管理员可按频道限定工具、数据源和记忆访问范围,并设置 token 消耗上限和活动日志;基于 Opus 4.8 运行。在代理相关内容下新增了一个简短小节,区分 Claude Tag 与 Claude Code CLI(二者的界面和控制模型不同)。无 CLI 版本发布。 177
2026-06-24 指南 v2.63:CLI v2.1.190。这是一个错误修复与可靠性版本——没有面向用户的功能、设置、命令或定价变更。(v2.1.188 和 v2.1.189 未发布。)v2.1.190 是最新版本。 260
2026-06-23 指南 v2.62:CLI v2.1.187。安全: 通过 sandbox.credentials 设置可阻止沙箱内的命令读取凭据文件和机密环境变量(参见“沙箱模式”);组织配置的模型限制在 /model 选择器、--model、/model 和 ANTHROPIC_MODEL 中统一生效,选择受限模型时会显示“restricted by your organization’s settings”(受您组织的设置限制)消息(参见 enforceAvailableModels)。用户体验: 全屏菜单(权限提示、/model、/config)支持鼠标点击选择;/install-github-app 将 GitHub Actions 工作流步骤改为可选;/btw 新增 ←/→ 导航;/plugin 会列出未使用的插件以便清理;claude --help 现在会列出 --bg/--background。修复:--json-schema / 工作流 agent({schema}) 在成功后不再重复调用 StructuredOutput,并能在后续轮次中可靠地返回结构化输出;挂起的远程 MCP 工具调用会在 5 分钟后中止,而不是一直阻塞;当原始 -p 运行未产生任何模型轮次时,--resume 不再报“No conversation found”错误;子代理深度跟踪在恢复时会还原生成深度,并将分叉的子代理计入上限;泄漏的代理工作树注册会被清理;粘贴的韩文/CJK 文本不再变成乱码;当某一轮次在没有结构化输出的情况下结束时,后台任务不再卡在“工作中”状态。v2.1.187 是最新版本。 176
2026-06-23 指南 v2.61:CLI v2.1.184–v2.1.186。v2.1.186(实质性版本):claude mcp login <name> / claude mcp logout <name> 可直接从 CLI 对 MCP 服务器进行身份验证,无需使用交互式 /mcp 菜单(--no-browser 配合 stdin 重定向可通过 SSH 完成身份验证;参见“MCP 管理命令”);! bash 命令现在会自动触发 Claude 对其输出作出响应——设置 "respondToBashCommands": false 可保留此前仅加入上下文的行为;Agent(type) 拒绝规则和 Agent(x,y) 允许类型限制现在对具名子代理的生成同样生效(生成在启动时即被阻止,而不再仅限于匿名 Task 生成;参见“权限规则语法”);后台子代理会在主会话中显示权限提示,而不是自动拒绝——对话框会显示是哪个代理在请求,按 Esc 仅拒绝该工具;/review <pr> 现在与 /code-review medium 使用相同的引擎;skill frontmatter 键(display-name、default-enabled、fallback、metadata.*)接受 kebab-case、snake_case 和 camelCase,格式错误的 SKILL.md YAML frontmatter 会以空元数据加载正文,而不是静默失败;/workflows 的代理详情新增状态筛选(按 f);/plugin 的“已安装”标签页新增 Skills 部分;新增 teammateMode: "iterm2" 设置;配置了 awsAuthRefresh 时,/login 新增“Claude Platform on AWS — refresh credentials”选项;当 MEMORY.md 索引接近大小上限时,代理会收到压缩提醒;CLAUDE_CODE_MAX_RETRIES 现在上限为 15(无人值守会话请使用 CLAUDE_CODE_RETRY_WATCHDOG)。修复:机器从睡眠中唤醒后,流式请求不再报“Content block not found”错误;子代理转录的滚动不再渗入主转录;~~strikethrough~~ 可正常渲染;Workflow agent({schema}) 子代理在 5 次验证失败后中止,而不是无限循环。v2.1.185: 流停滞提示现在显示为“Waiting for API response · will retry in …”,并在静默 20 秒后触发(此前为 10 秒)。(v2.1.184 未发布。)v2.1.186 是最新版本。 175
2026-06-19 指南 v2.60:CLI v2.1.180–v2.1.183。v2.1.183: 自动模式现在会硬性阻止破坏性命令,除非是您明确要求的——包括破坏性 git 操作(git reset --hard、git checkout -- .、git clean -fd、git stash drop)、对非代理提交执行 git commit --amend,以及未指定堆栈名称的 terraform/pulumi/cdk destroy(参见“Max 上的自动模式”);attribution.sessionUrl 设置可在提交/PR 中省略 claude.ai 会话链接;/config --help 会列出简写键,/config 界面现在按 Esc 即可保存;已弃用模型的警告扩展到代理 frontmatter(在 -p 模式下输出到 stderr);移除了启动时的“setup issues”行。v2.1.181: /config key=value 可直接从提示符设置任意选项(例如 /config thinking=false);sandbox.allowAppleEvents 可选启用(macOS Apple Events);CLAUDE_CLIENT_PRESENCE_FILE 环境变量可在您正在使用本机时抑制移动端推送;内置 Bun 升级到 1.4;长段落逐行流式输出;思考过程中连接中断时自动重试;子代理面板优化(空闲时自动隐藏、最多 5 行)。(v2.1.180 和 v2.1.182 未发布。)v2.1.183 是最新版本。 174
2026-06-17 指南 v2.59:CLI v2.1.177–v2.1.179。v2.1.178(实质性版本):Tool(param:value) 权限规则可通过 * 通配符匹配工具的输入参数——例如用 Agent(model:opus) 阻止 Opus 子代理(参见“权限规则语法”);嵌套的 .claude/skills 现在会在您处理其下的文件时加载(名称冲突时显示为 <dir>:<name>),嵌套 .claude/ 中的代理/工作流/输出样式在冲突时按最接近当前工作目录的优先解析(项目范围的工作流保存会写入最近的现有 .claude/workflows/);自动模式现在会在启动前通过分类器审查子代理生成,堵住了以生成子代理绕过审查的漏洞;压缩会遵循 --fallback-model 链;disallowedTools 的 MCP 规范修复(mcp__server、mcp__server__*、mcp__* 此前被静默忽略);此外还有 /doctor 扁平树状布局、/bug 现在必须填写描述、工作流关键字仅在明确的短语下触发,以及大量子代理转录/Remote Control/身份验证方面的修复。v2.1.179: 错误修复版本——在流式传输中途连接中断时保留部分响应,修复 WSL2 鼠标滚轮滚动(v2.1.172 的回归问题),修复曾导致大型目录树的 Linux 会话无法使用的沙箱 denyRead glob 问题,对欢迎屏幕的推广内容去重,并提升远程/插件的可靠性。v2.1.177: 仅更新 CHANGELOG/feed.xml。v2.1.179 是最新版本。 173
2026-06-15 指南 v2.58:CLI v2.1.174–v2.1.176(均发布于6月12日)。v2.1.174: 新增 wheelScrollAccelerationEnabled 设置(可在全屏模式下关闭鼠标滚轮的滚动加速);/model 选择器将 Default 实际解析到的模型系列单独列为一行(Max/Team Premium/Enterprise/PAYG-API 为 Opus,Pro/Team 为 Sonnet);VSCode 的 /usage 新增用量归因(缓存未命中、长上下文、子代理,以及按 skill/agent/plugin/MCP 统计的 24 小时/7 天用量);修复了 Bedrock GovCloud 推理配置文件前缀、后台会话的提供商环境变量继承、git 共同作者模型名称,以及企业按用量计费账户上 Fable 5“正在消耗用量额度”横幅等问题。v2.1.175: 新增 enforceAvailableModels 托管设置——availableModels 允许列表现在同样约束 Default 模型(回退到列表中的第一个允许模型),且用户/项目设置不能再扩展托管列表。v2.1.176: 会话标题改为按对话所用语言生成(可通过 language 设置固定);新增 footerLinksRegexes 设置,用于按正则匹配页脚链接徽标;hook 的 if 条件现可匹配 Read/Edit/Write 的路径模式(例如 Edit(src/**)、Read(.env));availableModels 的强制执行补上了别名重定向的漏洞,/fast 会拒绝允许列表之外的模型;Bedrock 凭证按其 Expiration 缓存;对于没有 Opus 4.8 的组织,自动模式会从 Fable 5 回退到可用的最佳 Opus;此外还有大量 Remote Control、后台会话、claude agents、/cd git 分支以及通过 SSH 使用 tmux 时的剪贴板修复。v2.1.176 为最新版本。 172
2026-06-11 指南 v2.57:CLI v2.1.173。Fable 5 的 [1m] 后缀自动规范化——claude-fable-5[1m] 这样的模型名称现在会自动规范化并去掉后缀,变为 claude-fable-5,因为 Fable 5 默认即包含 1M 上下文,该后缀只对 Opus/Sonnet 有意义(它们需要通过 [1m] 才能启用 1M 上下文)。另外修复了 Windows 上启动时误报“sandbox dependencies missing”警告的问题。 171
2026-06-10 指南 v2.57:CLI v2.1.172。递归子代理——子代理现在可以生成自己的子代理,最多5层(递归委派)。从 ~/.aws 读取 Bedrock 区域——未设置 AWS_REGION 时,AWS 区域从 ~/.aws 读取,/status 会显示解析来源。插件市场搜索——/plugin 为市场新增了搜索栏。OTEL——claude_code.lines_of_code.count 指标新增 model 属性。修复:无额度时 1M 上下文会话卡住、图像处理错误、后台子代理卡住状态、模型选择器/限制,以及团队记忆召回等问题。 171
2026-06-10 指南 v2.56.1:补充来自模型配置文档的 Claude Code 专属 Fable 5 细节。文档记载的选择方式是简短的 /model fable 别名(以及 best:有 Fable 时选 Fable,否则选最新的 Opus);Fable 5 支持完整的 low–max effort 等级(默认 high);Fable 5 上无法关闭思考(会话开关、alwaysThinkingEnabled 和 MAX_THINKING_TOKENS=0 均不起作用——它始终自适应推理);claude-fable-5[1m] 扩展上下文变体以及 ANTHROPIC_DEFAULT_FABLE_MODEL / DISABLE_PROMPT_CACHING_FABLE 配置项共同构成了 fable 系列。没有新版本发布(v2.1.170 仍为最新)。 261
2026-06-09 指南 v2.56:CLI v2.1.170。Claude Fable 5——高于 Opus 的全新模型层级(Anthropic 最强大、最智能的模型;将“Mythos 级”前沿能力安全地开放给大众使用)——在运行 claude update 后即可通过 /model claude-fable-5 在 Claude Code 中选用。模型 ID 为 claude-fable-5;1M 上下文,128K 输出;每百万 token $10/$50(约为 Opus 4.8 的 2 倍);安全分类器在涉及网络安全/生物化学/蒸馏的查询上会回退到 Opus 4.8;6月22日前逐步向订阅套餐推出。请求接口与 Opus 4.8 相同(仅支持自适应思考),但有一项新的破坏性变更:显式传入 thinking: {type: "disabled"} 会返回 400——请改为省略该参数。Opus 4.8 仍是 Claude Code 的智能体默认模型。 另修复一个缺陷:从 VS Code 集成终端(或任何继承了 Claude Code 环境变量的 shell)启动的会话无法保存记录,且不会出现在 --resume 中。验证依据:GitHub 发布版本 v2.1.170(6月9日 17:23Z)及 code.claude.com/docs/en/changelog 的官方变更日志;Fable 5 规格已与 anthropic.com/news 和 claude-api 模型目录交叉核对。 261
2026-06-08 指南 v2.55:CLI v2.1.169。--safe-mode 标志(以及 CLAUDE_CODE_SAFE_MODE 环境变量)可在禁用所有自定义项(CLAUDE.md、plugins、skills、hooks、MCP 服务器)的情况下启动会话,便于在“洁净环境”中排查问题。/cd 可将会话切换到新的工作目录,而不会在会话中途破坏提示缓存。disableBundledSkills 设置(以及 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS)会对模型隐藏内置的 skills、工作流和内置斜杠命令。另有约 20 项修复:上/下方向键在自动换行的视觉行间导航;企业 MCP 策略(allowedMcpServers/deniedMcpServers)在重新连接和 IDE 类型配置上的强制执行;使用 claude.ai 凭证时 macOS 界面出现 30–50ms 卡顿;Windows 上 claude -p 的性能;Remote Control 重新连接;Windows 上弹出 Git Credential Manager 窗口;自定义状态栏下的页脚提示;远程会话中过期的权限/对话框提示重复出现;claude agents --json 遗漏被阻塞的会话;TaskCreate 输入自动修复;降低流式传输的 CPU 占用;恢复 Vertex/Foundry 的 5 分钟空闲超时;skill 标签的颜色对比度;后台会话在 retire→wake 过程中保留标志。验证依据:code.claude.com/docs/en/changelog 的官方变更日志及 GitHub 发布页面确认 v2.1.169(6月8日)为最新版本。 262
2026-06-06 指南 v2.54:CLI v2.1.166–v2.1.168。v2.1.166: 回退模型链——fallbackModel 设置可配置最多三个回退模型,在主模型过载或不可用时按顺序依次尝试;--fallback-model 现在也适用于交互式会话(不再仅限会话中途);当 API 返回意外的不可重试错误时,Claude Code 还会在回退模型上重试一次该轮对话。MCP 拒绝通配符——在拒绝规则的工具名位置使用通配符("*" 拒绝所有工具),即可先全部阻止再逐一放行;允许规则会拒绝非 MCP 的通配符,以保持默认的限制性姿态。安全——通过 SendMessage 从其他 Claude 会话转发的消息不再携带用户权限(跨会话消息传递加固)。思考控制——MAX_THINKING_TOKENS=0、--thinking disabled 和按模型的思考开关现在能真正关闭默认开启思考的模型的思考功能。用户体验——claude update 在下载前会先告知目标版本。另有图像处理、远程会话稳定性和终端渲染(JetBrains IDE、WezTerm/Ghostty 键盘)方面的修复。v2.1.167 和 v2.1.168(均发布于6月6日):仅包含缺陷修复和可靠性改进,没有单独记录的用户可见变更。验证依据:code.claude.com/docs/en/changelog 的官方变更日志及 GitHub 发布页面确认 v2.1.168(6月6日)为最新版本。 263
2026-06-04 指南 v2.53:CLI v2.1.163(v2.1.161/162 未发布;更新日志从 160 直接跳至 163)。Hooks:Stop 和 SubagentStop hooks 现在可以返回 hookSpecificOutput.additionalContext,向 Claude 传递反馈并让本轮继续进行,而不会将响应标记为 hook 错误——这是比阻止/批准二选一更柔和的引导通道。企业版本锁定:新增的 requiredMinimumVersion 和 requiredMaximumVersion 托管设置会让 Claude Code 在允许的版本范围之外拒绝启动,并向用户指出经批准的版本。Plugins:/plugin list 列出已安装的 plugins,支持 --enabled/--disabled 筛选。Skills:\$ 转义现在包含命令正文中数字前的字面 $。MCP:stdio 服务器在 --resume 时会收到与 hooks/Bash 相同的 CLAUDE_CODE_SESSION_ID。UX:/btw 新增“按 c 复制”原始 markdown 的快捷键;/ 菜单描述更清晰;订阅切换建议移至启动公告位。另有约 17 项修复:claude -p 在后台命令始终不退出时不再挂起(stdin 关闭后,后台 shell 会在最终结果产出约 5 秒后停止);Bedrock/Vertex/Foundry 上的 claude -p 在 CI=true 下不再要求 ANTHROPIC_API_KEY;$TMPDIR 覆盖重新限定为仅作用于沙盒命令(2.1.154 引入的回归问题,曾破坏 bazel/受 EDR 保护的 Go);Windows 会话环境在 OneDrive/只读目录下的 EEXIST 错误;组织托管的权限规则在全新配置目录上延迟生效;后台会话在更新期间保持运行中的任务(并在后台完成更新以避免冷重启);agent 视图按 Esc 挂起;粘贴结束标记导致输入锁死;hook 的 if: "Bash(...)" 模式现在可匹配子 shell/反引号内部,而不再对每个 $() 都触发;针对 ~ 路径的拒绝规则现在也会拦截 $HOME 引用;多余的“(no content)”转录行。验证:code.claude.com/docs/en/changelog 的权威更新日志确认 v2.1.163(6月4日)为最新版本。 264
2026-06-02 指南 v2.52:CLI v2.1.160。安全——“编辑即执行”门控:acceptEdits 现在会在写入 shell 启动文件(.zshenv、.zlogin、.bash_login)、~/.config/git/ 以及授予代码执行权限的构建工具配置(.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/ 等)之前进行提示——将现有的 .claude//.git//.vscode/ 写入保护扩展到更广的一类文件:对这些文件的一次编辑,会让下一次 shell/安装/提交变成执行向量。Workflow 关键词更名:动态 workflow 的触发关键词由 workflow 改为 ultracode(在提示输入框中以紫色高亮);“workflow”一词不再触发运行,但用自己的话提出请求仍然有效。编辑体验:对单个文件执行 grep/egrep/fgrep 现在即可满足“先读后改”检查,因此通过 grep 查看文件后,Edit 不再要求单独执行一次 Read。已移除:CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE 现为空操作(已完全移除);启动时不再显示 JetBrains plugin 安装建议。另有约 25 项修复:WSL 选中即复制改经 PowerShell 互操作实现(而非 OSC 52)、claude agents 会话恢复时丢失聊天记录/重新运行原始提示、夜间退役的后台会话丢失对话、claude --bg 的“socket missing”冷启动竞争、Windows 后台会话在高负载下输入无响应、Apple Terminal/tmux 上的终端同步输出残影、claude agents 中 CJK 输入法光标位置、Windows 上 file:///C:/... 链接被改写、项目/分支名含非 ASCII 字符时的语音模式、Bedrock/Vertex/Foundry 上的“auto 模式不可用”消息现在正确指向 CLAUDE_CODE_ENABLE_AUTO_MODE、无法运行 xhigh 的模型不再提供 /effort ultracode,以及后台会话拆除时先 SIGTERM 再 SIGKILL 以确保清理处理程序得以运行。验证:GitHub 最新版本 v2.1.160 于 2026-06-02 发布;更新日志见 code.claude.com/docs/en/changelog。 265
2026-05-31 指南 v2.51:CLI v2.1.155–v2.1.159。v2.1.155 / v2.1.156(5月29日):修复了 Opus 4.8 思考块被篡改并表现为 API 错误的问题。v2.1.157(5月29日):放置在项目 .claude/skills/ 目录中的 plugins 现在无需 marketplace 即可自动加载;claude plugin init <name> 可在该目录下搭建全新 plugin 的脚手架;/plugin 参数支持自动补全;EnterWorktree 现在可以在会话中途于 Claude 管理的各 worktree 之间切换;agent 完成后后台 worktree 保持未锁定状态,以便 git worktree remove/prune 正常工作;当 OTEL_LOG_TOOL_DETAILS=1 时,tool_decision 遥测事件包含 tool_parameters;此外还修复了:无法处理的图片导致请求崩溃(现降级为文本占位符)、桌面端/IDE/SDK 在 auto/bypass 模式下的沙盒网络权限提示、后台会话因存在停驻的 subagents 而无法退役、agents 列表中缓慢的“opening…”在按 Esc 时无法取消、后台 worktree 在 30 天作业保留清理后成为孤儿、--resume 未报告正在运行的后台 subagents、终端渲染与剪贴板问题(tmux、VS Code、Cursor、Windsurf)、WSL 图片粘贴/Windows 11 截图粘贴/Windows 资源管理器拖放、长时间恢复会话的性能,以及 /terminal-setup 在集成终端中禁用 GPU 加速以防止文本乱码。v2.1.158(5月30日):Auto 模式现在可在 Bedrock、Vertex 和 Foundry 上为 Opus 4.7 和 Opus 4.8 通过 CLAUDE_CODE_ENABLE_AUTO_MODE=1 选择启用——补上了权限模式文档中最后一处“仅限 API 直连”的缺口。v2.1.159(5月31日):仅涉及内部基础设施,无面向用户的变更。验证:GitHub 最新版本 v2.1.159 于 2026-05-31 发布;更新日志见 code.claude.com/docs/en/changelog。 266
2026-05-28 指南 v2.50:CLI v2.1.151–v2.1.154。v2.1.151(5月23日):仅涉及内部基础设施,无面向用户的变更。v2.1.152(5月27日):/code-review --fix 可将审查结论直接应用到工作树(复用、简化、效率、抽象层级);/simplify 会调用 /code-review --fix;skills 和斜杠命令可在 frontmatter 中设置 disallowed-tools,在 skill 激活期间移除相应工具;新增 /reload-skills 命令,无需重启即可重新扫描 skill 目录;SessionStart hooks 可返回 reloadSkills: true 并设置 hookSpecificOutput.sessionTitle;新增 MessageDisplay hook 事件,可在显示时转换或隐藏助手文本;新增 pluginSuggestionMarketplaces 托管设置,为上下文感知建议设定组织市场白名单;claude plugin marketplace remove --scope 接受 user、project 或 local;主模型未找到时,CLI 会在本次会话余下时间改用 --fallback-model;auto 模式不再需要主动选择加入(opt-in)的同意;vim NORMAL 模式下 / 打开反向历史搜索;/usage 明细通过流式读取纳入大型会话文件;thinking 摘要上限为 10 行,并以 markdown 渲染;新增 OTEL app.entrypoint 属性;另有约 16 项错误修复,涵盖样式池内存、专注模式隐藏计数器、markdown 表格边框、环境变量不同的插件 MCP 服务器去重、插件 git 分支更新跟踪、经出口代理的远程 MCP,以及 effort 变更对话框的边缘情况。v2.1.153(5月28日):github/git 插件市场源新增 skipLfs 选项以跳过 Git LFS;npm 全局安装无法自动更新时显示一次性通知(附 /doctor 修复清单);状态栏命令可获得 COLUMNS 和 LINES 环境变量;claude agents 的派发自动补全会推荐原生斜杠命令和内置 skills;PR 列显示 PR #N 或 N PRs;/doctor 显示上次更新结果;合并了 MCP/连接器的认证通知;macOS 后台 agents 在“隐私与安全性”中显示为“Claude Code”,授权持久保留;/model 将所选模型保存为新会话默认值(与 IDE 一致),s 仅为当前会话切换模型(以 modelPicker:thisSessionOnly 取代 d 键绑定 modelPicker:setAsDefault);另有 25 项以上修复,涵盖有状态 MCP tools/list 重连循环、自定义网关 OAuth 凭据泄漏、subagent frontmatter 中的 MCP 服务器遵循 --strict-mcp-config/--bare/远程/托管策略、Windows PowerShell 安装程序误报成功、claude update 对 npm 遵循发布渠道、恢复转录时的内存增长、二进制接管后守护进程陈旧、stream-json 在 stdin 关闭时挂起、格式错误的 file:// 链接渲染、claude --help 在窄终端中的换行、折叠视图中的 MCP 进度通知、subagent subagent_type: 'claude' 未记录的 worktree 丢失被 gitignore 的输出、/bg 响应中途的继续执行、后台中的 /btw 快捷方式、$CLAUDE_JOB_DIR 临时文件提示、工作目录被删除时的错误提示清晰度、EnterWorktree 的即时性、cmd+k 重绘、Windows 输入法定位、256 色附加时的颜色渗出、tmux 与后台组合下的 /copy、/agents 中的 Remote Control 僵尸条目、/rename 横幅刷新、Windows 更新回滚、VSCode 非正常退出报告。v2.1.154(5月28日):Opus 4.8 成为默认模型,并默认采用 high effort;新增 /effort xhigh 级别,用于最难的任务;动态工作流(dynamic workflows)可通过 /workflows 在后台编排数十到数百个 agents;Opus 4.8 上的 Fast 模式以标准费率的 2 倍换取 2.5 倍速度;精简系统提示词现已成为所有模型的默认设置,仅 Haiku、Sonnet 以及 Opus 4.7 及更早版本除外;Claude 仅在确实无法自行决断时才使用多选提示;/simplify 恢复为仅做清理的审查(不再调用 /code-review --fix 的错误查找环节);/effort 滑块标签从“Speed”/“Intelligence”改为“Faster”/“Smarter”;claude agents 支持 ! <command>,将 shell 命令作为可分离的后台会话运行(也可使用 claude --bg --exec '<command>');claude agents 中的 /logout 直接登出,而不是路由到后台会话;←← agents 视图在 Bedrock/Vertex/Foundry 上以及禁用遥测时均可使用;Claude in Chrome 可通过 /chrome → “Select browser…” 在多个浏览器间选择;插件可在 plugin.json 或市场条目中声明 defaultEnabled: false;/plugin 的 Discover 标签页会将匹配当前目录的插件置顶,并标注“suggested for this directory”;流式工具执行始终启用(包括禁用遥测以及 Bedrock/Vertex/Foundry 环境);stdio MCP 子进程可获得 CLAUDE_CODE_SESSION_ID 和 CLAUDECODE=1 环境变量;claude mcp list/get 将未批准的 .mcp.json 服务器显示为 ⏸ Pending approval,而非自动连接;/remote-control 自动补全在已连接时显示“Disconnect Remote Control”;/claude-api skill 支持 Opus 4.8 及 4.7→4.8 迁移;弃用 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE(6月1日移除,请改为先执行 /model claude-opus-4-6[1m] 再执行 /fast on);改进了 auto 模式下针对批量仓库传输的数据外泄检测;另有多项修复,涉及带尾部斜杠的 rm -rf $HOME、沙箱与非沙箱环境下 $TMPDIR 的一致性、claude agents 行对比度、后台会话“out of context”的精确性、定时 /command 的目标保留、置顶会话升级后的反复重启、卡住状态的退役处理、subagent worktree 隔离被绕过、孤立的 claude --bg-pty-host 占用 100% CPU、分隔线下方的数字键快捷方式、链接 worktree 内 worktree.baseRef: "head" 的 HEAD 解析、换行后的行首空格、VSCode thinking 加载指示器的颜色闪烁、计划文件名中的 [Image #N] 占位符、虚假的展开提示、单个错误条目导致托管 MCP 配置整体被丢弃、effort 参数导致的 400 错误、Windows 文件占用时的更新错误、VSCode auto 模式选择器、任务面板的“main”行、/mcp tools 长名称、Fast 模式定价显示、auto 模式 token 耗尽。验证:GitHub 最新发布版本 v2.1.154 于 2026年5月28日发布;更新日志见 code.claude.com/docs/en/changelog。 267
2026-05-24 指南 v2.49:CLI v2.1.148-v2.1.150。v2.1.148:修复了 Bash 工具的一处回归,此前部分用户每条命令都会返回退出码 127。v2.1.149:/usage 现在按类别细分额度用量(skills、subagents、plugins 以及每个 MCP 服务器的开销);/diff 详情视图支持键盘滚动;Markdown 可渲染 GFM 任务列表复选框;企业版新增 allowAllClaudeAiMcps;修复内容涵盖 PowerShell cd 权限绕过、git worktree 沙箱写入白名单范围、PowerShell 前缀/通配符及过期变量的权限分析、Bash find 耗尽 macOS 文件/vnode 表、托管设置导致的启动冻结、/ultraplan / 远程会话无变更时的捕获失败、含空格的 otelHeadersHelper 路径、来自 skill/agent frontmatter 的状态栏 effort 显示、Ctrl+O 转录跟踪、/insights、Remote Control 会话重命名同步,以及压缩前的 /feedback 上下文。v2.1.150:仅为内部基础设施改进,未公布面向用户的变更。本次本地验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm @anthropic-ai/claude-code 最新版本为 2.1.150,time.modified 为 2026-05-23T04:03:10.243Z;GitHub 最新发布版本为 v2.1.150,发布于 2026-05-23T04:03:51Z。 170
2026-05-21 指南 v2.48:CLI v2.1.147。工作流与审查:新增默认关闭的 Workflow 工具,通过 CLAUDE_CODE_WORKFLOWS=1 启用,用于确定性的多 agent 编排;/simplify 现为 /code-review [effort],专注于正确性错误,并可用 --comment 发布 GitHub PR 行内评论。Agent View 与后台工作:置顶的后台会话在空闲时保持存活,可原地重启以应用更新,且在内存压力下仅在非置顶会话之后才会被清退。安全性与可靠性:REPL 和 Workflow 沙箱已加固,可抵御原型污染和 thenable 逃逸;自动更新失败时会报告类别/操作系统错误码并显示当前版本;大型 diff 渲染更快;提示历史会去除连续重复项;修复了企业登录限制、PowerShell 输出/规则、MCP 资源/模板/提示分页、hook if 匹配、粘贴文本传递、Agent View 中的 CJK 行、插件组件计数、斜杠命令解析,以及剥离图片导致的循环。本次本地验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm @anthropic-ai/claude-code 最新版本为 2.1.147,time.modified 为 2026-05-21T20:38:35.053Z。 169
2026-05-19 指南 v2.47:CLI v2.1.145。Agent View 与脚本化:claude agents --json 以 JSON 形式列出活跃会话,便于脚本调用;Agent View 标签页标题显示等待输入的会话数量;回复窗格中的语音按住说话功能已修复;全屏模式下的斜杠命令 / @ 提及建议支持鼠标悬停和点击。可观测性与 hooks:claude_code.tool OTEL span 包含 agent_id 和 parent_agent_id,后台 subagent 的 span 归属于发起调度的 Agent 工具 span 之下,状态栏 JSON 包含检测到的 GitHub 仓库和 PR 信息,Stop/SubagentStop hook 输入现在包含 background_tasks 和 session_crons。插件与安全:安装前的插件界面会显示命令、agents、skills、hooks 以及 MCP/LSP 服务器;未列入许可名单的裸 Bash 环境变量赋值不再绕过权限提示;skill 的 context: fork 自调用循环已修复;当整文件读取超出 token 限制时,Read 工具返回截断的部分视图,而不是直接失败。本次本地验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm @anthropic-ai/claude-code 最新版为 2.1.145,time.modified 为 2026-05-19T22:20:44.083Z。 168
2026-05-19 指南 v2.46:CLI v2.1.144。后台会话:/resume 现在会包含通过 claude --bg 或 Agent View 启动的会话,并以 bg 标记;后台 subagent 的完成通知包含已用时长;/bg 和分离操作会保留已添加的目录。模型与用量体验:/model 现在只更改当前会话,除非按 d 将其设为默认;/extra-usage 更名为 /usage-credits,旧命令保留为别名。插件与诊断:插件浏览/发现窗格显示最近更新日期;对于缺少 command 的命令 hooks,/doctor 会显示 exec 形式的示例;skill 列表截断提示已从启动通知中移出。可靠性:当 api.anthropic.com 无法访问时,启动时的旁路调用会更快超时;终端显示错乱现在可以自行恢复;修复了 macOS 上在受“完全磁盘访问”保护的文件夹中启动后台会话的问题;MCP 分页的 tools/list 响应不再被截断;不受支持的 MCP 图像 MIME 类型会安全降级;并修复了多个 Agent View/后台会话交互缺陷。本次本地验证:claude --version 返回 2.1.144 (Claude Code),npm @anthropic-ai/claude-code 最新版为 2.1.144,time.modified 为 2026-05-19T17:40:52.832Z。 167
2026-05-18 指南 v2.45:CLI v2.1.143。插件:依赖强制检查会阻止禁用被其他已启用插件所依赖的插件,而启用插件时会强制启用其传递依赖;插件市场的浏览窗格现在显示预估的上下文开销。Worktree/后台会话:worktree.bgIsolation: "none" 允许后台会话直接编辑工作副本,适用于不便使用 worktree 的仓库;后台会话从空闲唤醒后会保留模型/effort 设置。Windows/PowerShell:PowerShell 现在会传入 -ExecutionPolicy Bypass;可通过 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1 退出此行为;除非设置了 CLAUDE_CODE_USE_POWERSHELL_TOOL=0,PowerShell 工具对 Bedrock、Vertex 和 Foundry 用户默认启用。可靠性:反复阻止的 stop hooks 现在最多连续阻止八次,除非通过 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 覆盖;当后台 shell 或委派的 subagents 仍在运行时,/goal 评估器不再触发;claude agents 的调度标志现在在仪表板和后台会话中一致生效。本次本地验证:claude --version 返回 2.1.142 (Claude Code),而 npm @anthropic-ai/claude-code 最新版为 2.1.143,time.modified 为 2026-05-18T19:57:55.006Z。 166
2026-05-15 指南 v2.44:CLI v2.1.142。Agent View:claude agents 可通过 --add-dir、--settings、--mcp-config、--plugin-dir、--permission-mode、--model、--effort 和 --dangerously-skip-permissions 配置所调度的后台会话。快速模式:快速模式现在默认使用 Opus 4.7;设置 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 可固定为旧的 Opus 4.6 默认值。插件:没有 skills/ 目录的插件根级 SKILL.md 文件现在会作为 skills 显示;插件详情显示 LSP 服务器;插件缓存清理不会删除当前使用的版本;skills: ["./"] 不再误报目录越界错误。可靠性:修复涵盖远程 HTTP/SSE MCP 服务器上的 MCP_TOOL_TIMEOUT、后台会话中已存在的 git worktree、守护进程的休眠/唤醒与升级后清理、Chrome 扩展后台 agent 崩溃、Agent View 编辑器/链接处理、Windows 网络驱动器启动死锁,以及远程客户端多余的 /model 面包屑提示。本次本地验证:claude --version 返回 2.1.141 (Claude Code),而 npm @anthropic-ai/claude-code 最新版为 2.1.142,time.modified 为 2026-05-14T22:54:49.491Z。 165
2026-05-14 指南 v2.43:CLI v2.1.141。Hooks:hook JSON 输出中的 terminalSequence 让 hooks 无需控制终端即可发出终端控制序列,用于桌面通知、窗口标题和响铃。插件:在没有 GitHub SSH 密钥的环境中,CLAUDE_CODE_PLUGIN_PREFER_HTTPS 会通过 HTTPS 而非 SSH 克隆 GitHub 插件源。企业认证:当一条联合规则覆盖多个工作区时,ANTHROPIC_WORKSPACE_ID 可将工作负载身份联合令牌限定到特定工作区。Agent View:claude agents --cwd <path> 将会话列表筛选为单个目录。反馈:对于跨越多个会话的问题,/feedback 可以附带最近 24 小时或 7 天内的会话。本次本地验证:claude --version 返回 2.1.141 (Claude Code);npm @anthropic-ai/claude-code 最新版为 2.1.141。 164
2026-05-13 指南 v2.42:CLI v2.1.139 + v2.1.140。v2.1.139:新增通过 claude agents 打开的 Agent View、/goal、命令 hook 的 args: string[]、PostToolUse 的 continueOnBlock、面向 MCP stdio 服务器和插件命令插值的 CLAUDE_PROJECT_DIR,并修复了 --print 模式下 claude_code.active_time.total 的 OTel 上报。v2.1.140:在 agent hook 输入中新增 subagent_type,并修复了 ConfigChange hooks、disableAllHooks、allowManagedHooksOnly、权限对话框中意外显示 hook 结果环境变量、设置同步时的样式重置、Windows Git Bash 上的原生包回退以及 /scroll-speed。本次本地验证:claude --version 返回 2.1.140 (Claude Code)。 162 163
2026-05-09 指南 v2.41:CLI v2.1.137 + v2.1.138 补丁版本更新。VSCode(Windows):v2.1.137 修复了 VSCode 扩展在 Windows 上无法激活的问题。v2.1.138:包含内部修复(发布说明中未公布新增的命令/配置)。没有新的命令、设置或环境变量。 162
2026-05-08 指南 v2.40:CLI v2.1.133 + 5月7日 Microsoft 365 正式发布。破坏性默认值变更 — worktree.baseRef:新的 fresh 默认值使 --worktree、EnterWorktree 和 agent 隔离的 worktree 重新从 origin/<default> 分支创建,撤销了 v2.1.128 改为本地 HEAD 的变更。设置 worktree.baseRef: "head" 可在新 worktree 中保留尚未推送的提交。Effort 传递:hooks 现在会收到 effort.level JSON 和 $CLAUDE_EFFORT;Bash 工具的子进程继承 $CLAUDE_EFFORT。沙箱托管设置:sandbox.bwrapPath 和 sandbox.socatPath(Linux/WSL)指向自定义的 bubblewrap 和 socat 二进制文件。管理层级:parentSettingsBehavior('first-wins' \| 'merge')让 SDK managedSettings 加入策略合并。Subagents:修复了 subagents 无法通过 Skill 工具发现项目、用户或插件 skills 的问题。v2.1.133 还解决了刷新令牌轮换后并行会话的 401 竞争、驱动器根目录允许规则的作用域、MCP OAuth 代理/mTLS、Remote Control 停止/中断时完成取消、跨会话 /effort 泄漏等问题,并在 --help 中列出 --remote-control。Microsoft 365(5月7日):面向 Excel、PowerPoint 和 Word 的 Claude 已在付费套餐上正式可用;面向 Outlook 的 Claude 已向所有付费套餐开放公测。 160 161
2026-05-07 指南 v2.39:CLI v2.1.132。TUI:CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 可退出全屏备用屏幕渲染器,让对话保留在终端原生回滚缓冲区中;/tui fullscreen 启动横幅已更新,宣传更低的内存占用、鼠标支持以及选中即自动复制。Bash 子进程:CLAUDE_CODE_SESSION_ID 环境变量与传递给 hooks 的 session_id 一致。此外还有 20 多项小修复,涵盖 SIGINT 优雅关闭、--resume 时的代理对表情符号损坏、计划模式下 --permission-mode 标志的处理、印度语系/ZWJ 光标与 NFD vim 操作、以 / 开头的粘贴内容被吞掉、MCP 内存无限增长及 tools/list 重试、Bedrock+Vertex 的 ENABLE_PROMPT_CACHING_1H 400 错误,以及状态栏 context_window 显示累计而非当前 token 数的问题。 159
2026-05-06 指南 v2.38:Code with Claude SF 2026 当日新增内容。新增 5 月 6 日的容量公告:Pro、Max、Team 以及按席位计费的 Enterprise 计划的 Claude Code 五小时速率限制翻倍;Pro 与 Max 取消了高峰时段的限额削减;Claude Opus 模型的 API 速率限制“大幅”提高。背后是与 SpaceX Colossus 1 的算力合作(“本月内新增超过 300 兆瓦的容量(超过 220,000 块 NVIDIA GPU)”)。新增 5 月 5 日的金融垂直领域发布:十个开箱即用的智能体模板(融资演示构建器、财报审阅器、KYC 筛查器、月末结账器,以及另外六个)以插件形式面向 Cowork 和 Claude Code 发布,并附带一份 Managed Agents 实用手册;面向 Excel、PowerPoint 和 Word 的 Microsoft 365 加载项已上线;来自 Dun & Bradstreet、Fiscal AI、Financial Modeling Prep、Guidepoint、IBISWorld、SS&C IntraLinks、Third Bridge 和 Verisk 的数据连接器;覆盖超过 6 亿家公司的 Moody’s MCP 应用;用于语音/文本任务分派的 Cowork Dispatch。 157 158
2026-05-06 指南 v2.37:CLI v2.1.131 最新版本线增量。NPM 最新版为 2.1.131,GitHub 最新发布版为 v2.1.131;本轮本地安装的 CLI 仍为 2.1.126。v2.1.131 是一个修复版本,针对 VS Code Windows 扩展激活和 Mantle 端点身份验证,发行说明中未宣布任何命令/配置方面的新增内容。覆盖至 v2.1.131。 156
2026-05-05 指南 v2.36:CLI v2.1.126–v2.1.129。最新发布版本线:NPM 最新版为 2.1.129,GitHub 最新发布版为 v2.1.129;本轮本地安装的 CLI 为 2.1.126。插件:--plugin-url <url> 可为当前会话加载插件 zip 包;--plugin-dir 接受 zip 压缩包;插件清单中的 themes 和 monitors 应移至 "experimental" 之下,否则 claude plugin validate 会发出警告。Skills:skillOverrides 现已支持 off、user-invocable-only 和 name-only。网关:/model 选择器的 /v1/models 发现功能在 2.1.126–2.1.128 中为自动开启,现改为通过 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 手动启用。更新/终端:CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 允许 Homebrew/WinGet 安装的版本在后台执行升级并提示重启;CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 可为自动检测遗漏的终端强制启用同步输出。安全/权限:v2.1.126 将 --dangerously-skip-permissions 改为对写入 .claude/、.git/、.vscode/ 及 shell 配置文件的操作跳过提示,同时保留灾难性删除提示作为安全网。修复:2.1.128–2.1.129 修复了插件状态污染、MCP 参数损坏、1 小时提示缓存 TTL 降级、/context ASCII 网格导致的转录膨胀、外部编辑器空白、OAuth/服务器托管设置的回归问题,以及若干全屏/历史/会话 UI 问题。 156
2026-04-29 CLI v2.1.123:修复了设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 时 OAuth 身份验证失败并陷入 401 重试循环的问题。 155
2026-04-28 指南 v2.35:CLI v2.1.121 + v2.1.122。MCP:alwaysLoad: true 服务器配置选项可让某个服务器不参与工具搜索延迟加载;瞬时启动错误会自动重试 3 次。Hooks:hookSpecificOutput.updatedToolOutput 扩展至所有工具(此前仅限 MCP)。权限:--dangerously-skip-permissions 在写入 .claude/skills/、.claude/agents/、.claude/commands/ 时不再提示。插件:claude plugin prune 可移除孤立的自动安装依赖;uninstall 时 --prune 会级联执行。斜杠命令:/skills 新增输入即筛选;/resume 接受 PR URL(GitHub、GHE、GitLab、Bitbucket)。Vertex AI:基于 X.509 证书的 Workload Identity Federation(mTLS ADC)。Bedrock:ANTHROPIC_BEDROCK_SERVICE_TIER 环境变量(default/flex/priority)。OTel:新增 LLM span 属性(stop_reason、gen_ai.response.finish_reasons,以及由 OTEL_LOG_USER_PROMPTS 控制的 user_system_prompt);新增 claude_code.at_mention 事件;api_request/api_error 上的数值属性现以数字形式输出。SDK:mcp_authenticate 新增 redirectUri。此外还有 MCP//mcp 的打磨、全屏滚动修复、claude.ai 连接器去重、在 tmux 中使用 /copy 时支持 iTerm2 剪贴板、升级后启动更快,以及数十项关于恢复/记忆/Bash/Bedrock/Vertex/回滚缓冲区的修复(参见 [^162])。 152 154
2026-04-24 指南 v2.34:CLI v2.1.116–v2.1.119 + 4 月 23 日质量事后分析。/usage 将 /cost 和 /stats 合并为一个对话框(两个名称仍可作为输入快捷方式使用)。Vim 可视模式:v(字符)和 V(行),支持选区、操作符和可视反馈。Hooks 现在可通过 type: "mcp_tool" 直接调用 MCP 工具;PostToolUse/PostToolUseFailure hook 的输入包含表示工具执行时长的 duration_ms。Auto Mode 的 $defaults 哨兵值可在 autoMode.allow/soft_deny/environment 中将自定义规则追加到内置列表之后(而非替换它);启用提示上新增“不再询问”选项。PowerShell 工具命令现在可在权限模式下自动批准(与 Bash 一致)。/config 设置(主题、编辑器模式、详细输出)现在会持久化到 ~/.claude/settings.json,并完整遵循项目/本地/策略的优先级顺序。主题现已具名:可通过 /theme 创建和切换,手动编辑 ~/.claude/themes/*.json,插件可随附 themes/ 目录。prUrlTemplate 可将页脚的 PR 徽章重定向到自定义代码审查 URL;--from-pr 现在接受 GitLab MR、Bitbucket PR 和 GitHub Enterprise PR。--print 和 --agent 会遵循智能体 frontmatter 中的 tools:/disallowedTools:/permissionMode。原生 macOS/Linux 构建通过 Bash 工具以内嵌的 bfs/ugrep 取代 Glob/Grep(更快,无需单独往返)。Opus 4.7 上下文修复:会话现在基于原生 1M 上下文窗口而非错误的 200K 来计算 /context(不再过早自动压缩)。默认推理强度变更:Pro/Max 在 Sonnet 4.6 和 Opus 4.6 上现默认为 high(此前为 medium);Opus 4.7 保持 xhigh。新增环境变量:CLAUDE_CODE_HIDE_CWD(在启动标志中隐藏工作目录)、DISABLE_UPDATES(阻止包括手动 claude update 在内的所有更新路径,比 DISABLE_AUTOUPDATER 更严格)、CLAUDE_CODE_FORK_SUBAGENT=1(在外部构建上启用分叉子智能体)、ENABLE_TOOL_SEARCH(Vertex AI 的手动启用开关)。新增托管设置策略:wslInheritsWindowsSettings 允许 WSL 继承 Windows 侧的托管设置。cleanupPeriodDays 保留期清理现在还覆盖 ~/.claude/tasks/、~/.claude/shell-snapshots/ 和 ~/.claude/backups/。Advisor Tool 现为实验性功能(带标签、了解更多链接,且出错后不再卡住)。claude plugin tag 可创建带版本校验的发布 git 标签;blockedMarketplaces/strictKnownMarketplaces 现在在每条插件安装/更新路径上强制执行,包括 hostPattern/pathPattern。安全:沙箱自动放行不再绕过对 /、$HOME 及其他关键系统根目录执行 rm/rmdir 的危险路径检查。事后分析(4 月 23 日):Anthropic 发布了一份事后分析,涵盖三项已于 4 月 20 日前解决的质量回归——(1)3 月 4 日至 4 月 7 日推理强度默认值被降至 medium(已回退),(2)3 月 26 日至 4 月 10 日的提示缓存思考清除 bug(已在 v2.1.101 中修复),(3)4 月 16 日至 20 日的系统提示冗长度约束(Opus 4.6 / Opus 4.7 的编码质量下降约 3%;Sonnet 4.6 降幅较小;已在 v2.1.116 中回退)。4 月 23 日已为所有订阅者重置用量限制。此外还有数十项 MCP/OAuth/键盘/UI 修复和 OTel 改进(tool_use_id、tool_input_size_bytes,以及状态栏中的 effort.level/thinking.enabled)。 152 153
2026-04-18 指南 v2.33:CLI v2.1.113 + v2.1.114。CLI 现在通过按平台划分的可选依赖启动原生 Claude Code 二进制文件,不再使用捆绑的 JavaScript。安全方面:sandbox.network.deniedDomains 阻止列表优先于 allowedDomains 通配符;Bash 拒绝规则可匹配 env/sudo/watch/ionice/setsid 包装命令;Bash(find:*) 不再自动批准 -exec/-delete;macOS 上的 Bash(rm:*) 规则将 /private/{etc,var,tmp,home} 视为危险目标。用户体验:全屏模式下扩展选区时可用 Shift+↑/Shift+↓ 滚动视口;当前逻辑行支持 readline 风格的 Ctrl+A/Ctrl+E;Windows 上 Ctrl+Backspace 删除前一个单词。斜杠命令:/loop 按 Esc 可取消待触发的唤醒;/extra-usage 可在 Remote Control 客户端中使用;/ultrareview 启动更快,检查并行执行,并显示 diffstat 和带动画的启动状态。停滞的 subagents 会在 10 分钟后以明确的错误失败。Opus 4.7 Bedrock 修复:通过 Application Inference Profile ARN 使用扩展思考时,不再返回 thinking.type.enabled is not supported 400 错误。v2.1.114 热修复:Agent Teams 队友请求工具权限时权限对话框崩溃的问题。 150
2026-04-16 指南 v2.32:Claude Opus 4.7 发布——Max 和 Team Premium 套餐即刻切换为新默认模型;Enterprise 和 API 计划于2026年4月23日切换;Pro 和 Team Standard 仍使用 Sonnet 4.6。1M 上下文按标准定价(Opus 4.7 不收取长上下文溢价)。最大输出 128K。Messages API 的破坏性变更:移除扩展思考的 budget_tokens(仅支持自适应思考),temperature/top_p/top_k 设为非默认值时返回 400,思考内容默认省略(设置 display: "summarized" 可恢复)。新增 xhigh 努力级别;Claude Code 在 Opus 4.7 上默认使用 xhigh。视觉支持最高 2,576 px / 3.75 MP,像素坐标 1:1。CLI v2.1.105–v2.1.112:PreCompact hooks 可阻止操作,/recap + 会话回顾(Session Recap),/ultrareview,/less-permission-prompts,/tui//focus,/proactive(/loop 的别名),/undo(/rewind 的别名),通过 Remote Control 推送通知,Max 套餐在 Opus 4.7 上的 Auto Mode(无需 --enable-auto-mode 标志),Windows PowerShell 工具推出(CLAUDE_CODE_USE_POWERSHELL_TOOL),只读 Bash 权限缩减,ENABLE_PROMPT_CACHING_1H 环境变量,TRACEPARENT/TRACESTATE 分布式追踪,用于调试的 OTEL_LOG_RAW_API_BODIES。 144 145 146
2026-04-13 指南 v2.31:CLI v2.1.98–v2.1.104。/team-onboarding 命令。Google Vertex AI 设置向导。面向企业 TLS 代理的操作系统 CA 证书信任。用于后台脚本的 Monitor 工具。用于跨用户缓存的 --exclude-dynamic-system-prompt-sections。用于 Perforce 工作流的 CLAUDE_CODE_PERFORCE_MODE。多项 bash 安全修复(反斜杠绕过、复合命令绕过、阻止 /dev/tcp 重定向)。 142 143
2026-04-09 指南 v2.30:CLI v2.1.97。修复了 --dangerously-skip-permissions 在写入受保护路径后静默降级为 accept-edits 的问题。修复了 MCP HTTP/SSE 连接在重连时每小时泄漏约 50 MB 内存的问题。修复了 429 重试在约 13 秒内耗尽全部尝试次数的问题。NO_FLICKER 模式下的聚焦视图切换(Ctrl+O)。状态栏 refreshInterval 设置。Cedar 策略语法高亮。 141
2026-04-08 指南 v2.29:CLI v2.1.94–v2.1.96。通过 Mantle 使用 Bedrock(CLAUDE_CODE_USE_MANTLE=1)。API/Bedrock/Vertex/Foundry/Team/Enterprise 的默认努力级别从 medium 改为 high。UserPromptSubmit hooks 支持 hookSpecificOutput.sessionTitle。v2.1.96 热修复 Bedrock 身份验证回归问题。 140
2026-04-07 指南 v2.28:新增 Claude Mythos Preview 和 Project Glasswing。超越 Opus 4.6 的新前沿模型,仅限 12 家合作伙伴用于防御性安全工作。通过 Claude Code 在隔离容器中运行。已承诺投入 1 亿美元额度。暂未普遍开放。 139
2026-04-06 指南 v2.27:新增 /buddy 终端伙伴宠物(18 个物种、5 个稀有度等级,由账户 ID 确定性生成)。已于4月1日正式发布。 138
2026-04-04 指南 v2.26:CLI v2.1.90–v2.1.92。/powerup 交互式课程。MCP _meta["anthropic/maxResultSizeChars"] 最高支持 500K。disableSkillShellExecution 设置。forceRemoteSettingsRefresh 失败即关闭的企业策略。交互式 Bedrock 设置向导。按模型 + 缓存命中的 /cost 明细。/release-notes 交互式选择器。Plugin bin/ 可执行文件。Remote Control 主机名前缀。移除了 /tag 和 /vim。 135 136 137
2026-04-01 指南 v2.25:新增 “Under the Hood”(幕后机制) 章节,汇总源码泄露中与 harness 构建者相关的发现:auto mode 分类器内部实现(yoloClassifier.ts)、bash 安全的 23 项检查模型、提示缓存架构(14 种失效路径)、autocompact 断路器(修复每天 250K 次浪费调用)、作为提示驱动编排的协调器模式、通过正则表达式检测用户挫败感。 133 134
2026-04-01 CLI 2.1.89:PreToolUse hooks 支持 "defer" 权限决策(无头模式下通过 -p --resume 暂停/恢复)。MCP_CONNECTION_NONBLOCKING=true 在 -p 模式下跳过等待 MCP。Autocompact 抖动循环检测(连续 3 次重新填充后停止)。格式化工具/linter 修改了先前已读取的文件时,Bash 工具会发出警告。Edit/Read 允许规则可识别符号链接。合并了 v2.1.88 的 35+ 项错误修复。 126
2026-03-31 指南 v2.24:新增 v2.1.88 功能。PermissionDenied hook 在 auto mode 分类器拒绝后触发。CLAUDE_CODE_NO_FLICKER=1 备用屏幕渲染。@ 提及自动补全中支持具名 subagents。思考摘要默认关闭(showThinkingSummaries: true 可恢复)。auto mode 拒绝的命令显示在 /permissions 的 Recent 标签页中。/btw 可滚动视口。35+ 项错误修复,包括提示缓存未命中、嵌套 CLAUDE.md 重复注入、StructuredOutput 50% 失败率、CJK/表情符号历史记录。根据 Boris Cherny 的技巧新增 /dream 记忆整合命令。 127 128
2026-03-31 CLI 2.1.88:PermissionDenied hook,CLAUDE_CODE_NO_FLICKER=1,@ 自动补全中的具名 subagents,思考摘要默认关闭,auto mode 拒绝的命令显示在 /permissions 的 Recent 标签页中,/env 适用于 PowerShell,/btw 可滚动视口。修复:提示缓存未命中、嵌套 CLAUDE.md 重复注入(长会话中多达数十次)、StructuredOutput 约 50% 失败率、Windows 上 Edit/Write 的 CRLF 重复、大型 JSON LRU 缓存的内存泄漏、CJK/表情符号提示历史记录、/stats 丢失历史数据。35+ 项错误修复。 127
2026-03-29 CLI 2.1.86–2.1.87:用于代理聚合的 X-Claude-Code-Session-Id 标头。Read 工具的紧凑行号格式降低了 token 用量。Auto mode 显示针对具体套餐的不可用提示。/skills 中的 skill 描述上限为 250 个字符。@ 文件提及不再进行 JSON 转义(降低 token 开销)。排除 Jujutsu/Sapling VCS 目录。15+ 项错误修复,包括对 2.1.85 之前会话执行 --resume、对项目根目录之外的文件执行 Write/Edit、macOS/Linux 上的 plugin 脚本权限。 129
2026-03-27 指南 v2.23:新增 v2.1.85 功能。Auto Mode——基于分类器的权限系统,取代 --dangerously-skip-permissions,让自主运行更加安全。Sonnet 4.6 在执行前审查每个操作,并配有自动阻止列表和断路器。hooks 支持使用权限规则语法的条件 if 字段。PreToolUse hooks 现在可以满足 AskUserQuestion。MCP OAuth 遵循 RFC 9728。25+ 项错误修复。 124 125 130
2026-03-27 CLI 2.1.85:hooks 的条件 if 字段,PreToolUse hooks 通过 updatedInput 满足 AskUserQuestion,headersHelper 脚本可用的 MCP 环境变量,MCP OAuth RFC 9728,被组织屏蔽的 plugins 在 marketplace 中隐藏,/loop 和 CronCreate 的时间戳标记,深层链接查询最长 5K 字符,针对超大对话的 /compact 修复,20+ 项错误修复。 130
2026-03-26 指南 v2.22:新增 v2.1.83 和 v2.1.84 功能。PowerShell 工具(Windows,可选加入的预览版)。3 个新的 hook 事件:TaskCreated、CwdChanged、FileChanged(共 25 个)。用于团队策略片段的 managed-settings.d/ 插入目录。sandbox.failIfUnavailable 设置。CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 从子进程中清除凭据。转录搜索(在 Ctrl+O 中按 /)。用于自动提交首轮对话的 initialPrompt agent frontmatter。Rules/skills 的 paths: 接受 YAML glob 列表。MCP 工具描述上限为 2KB。Token 计数以“1.5m”格式显示。闲置 75 分钟以上后返回时显示提示。停止所有 agent 的快捷键已更改:从 Ctrl+F 改为 Ctrl+X Ctrl+K。TaskOutput 已弃用(请改用 Read 读取输出文件)。支持 WorktreeCreate HTTP hook。两个版本共计 50+ 项错误修复。 123 131
2026-03-26 CLI 2.1.84:PowerShell 工具(Windows 需手动启用)、TaskCreated hook、WorktreeCreate HTTP hook 支持、ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL_SUPPORTS 环境变量、CLAUDE_STREAM_IDLE_TIMEOUT_MS、allowedChannelPlugins 托管设置、rules/skills 的 paths: YAML glob 列表、MCP 描述 2KB 上限、空闲返回提示(75 分钟以上)、深层链接在首选终端中打开、token 计数采用“1.5m”格式、CJK 输入法修复、25 项以上 bug 修复。 131
2026-03-25 CLI 2.1.83:managed-settings.d/ 插入式目录、CwdChanged/FileChanged hook 事件、sandbox.failIfUnavailable、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1、会话记录搜索、initialPrompt 代理 frontmatter、Ctrl+X Ctrl+E 外部编辑器、停止所有代理的快捷键由 Ctrl+F 改为 Ctrl+X Ctrl+K、TaskOutput 已弃用、35 项以上 bug 修复。 123
2026-03-21 指南 v2.21:新增 v2.1.80 和 v2.1.81 的功能。Claude Code Channels(研究预览版):通过基于插件的频道服务器,将来自 Telegram 或 Discord 的消息发送到正在运行的会话中。--bare 标志在脚本化的 -p 自动化中跳过 hooks、LSP、插件同步和 skill 目录遍历。--channels 标志将工具审批提示转发给频道服务器。状态栏脚本中可使用 rate_limits 字段。source: 'settings' 插件市场来源类型。skills 支持 effort frontmatter。助手会遵从“不要记忆”的请求。修复了 Git Bash 下 Windows PATH 继承问题。 122 132
2026-03-20 CLI 2.1.81:用于脚本化 -p 调用的 --bare 标志(跳过 hooks、LSP、插件同步和 skill 遍历)。面向频道服务器的 --channels 权限转发。助手会遵从“不要记忆”的请求。 132
2026-03-19 CLI 2.1.80:状态栏脚本中的 rate_limits 字段。source: 'settings' 插件市场来源。skills 的 effort frontmatter。Claude Code Channels(研究预览版):通过 --channels 标志将 Telegram/Discord 消息送入会话。修复了 Git Bash 下 Windows PATH 继承问题。 122
2026-03-19 指南 v2.20:新增 v2.1.78 和 v2.1.79 的功能。StopFailure hook 事件(共 23 个)。插件持久化状态(${CLAUDE_PLUGIN_DATA})。代理 frontmatter:插件代理可用 effort、maxTurns、disallowedTools。用于自定义 /model 条目的 ANTHROPIC_CUSTOM_MODEL_OPTION 环境变量。逐行响应流式输出。Tmux 通知透传。claude auth login 的 --console 标志。/remote-control VS Code 命令。VS Code 中由 AI 生成的会话标题。启动内存减少约 18MB。安全修复:沙箱依赖缺失时显示可见警告。SessionEnd hooks 现在会在 /resume 切换会话时触发。20 项以上 bug 修复。 120 121
2026-03-18 CLI 2.1.79:用于 API 计费认证的 --console 标志、/remote-control VS Code 命令、VS Code 中的 AI 会话标题、启动内存减少约 18MB、2 分钟非流式超时、/resume 切换时触发 SessionEnd hooks。修复:-p 作为子进程时挂起、打印模式下的 Ctrl+C、/btw 输出错误、语音模式启动、企业版 429 重试。 121
2026-03-17 CLI 2.1.78:StopFailure hook 事件、${CLAUDE_PLUGIN_DATA} 插件状态、代理 frontmatter(effort/maxTurns/disallowedTools)、ANTHROPIC_CUSTOM_MODEL_OPTION、tmux 通知透传、逐行流式输出。安全:沙箱依赖缺失时显示可见警告。修复:大型会话截断(>5MB)、stop hook 无限循环、沙箱路径处理、WSL2 下的语音、VS Code 中的 Homebrew PATH。 120
2026-03-17 指南 v2.19:新增 v2.1.77 的功能。Opus 4.6 默认输出 token 数提高至 64K,Opus 4.6 和 Sonnet 4.6 的上限提高至 128K。allowRead 沙箱文件系统设置,可在 denyRead 区域内重新允许读取访问。/copy N 复制倒数第 N 条助手响应。/fork 更名为 /branch(/fork 保留为别名)。Agent 工具不再接受 resume 参数,请使用 SendMessage({to: agentId}) 继续代理;SendMessage 会自动恢复已停止的代理。计划被接受后,会话自动根据计划内容命名。后台 bash 任务的输出达到 5GB 时会被终止。claude plugin validate 检查 skill/agent/command 的 frontmatter 以及 hooks/hooks.json。macOS 上启动速度提升约 60ms(并行读取钥匙串)。--resume 最多提速 45%,峰值内存减少约 100-150MB。安全修复:返回 "allow" 的 PreToolUse hooks 不再绕过 deny 权限规则(包括托管设置)。25 项以上 bug 修复,包括复合 bash 命令“始终允许”保存无效规则、自动更新程序内存泄漏、Write 工具 CRLF 转换、过期 worktree 清理的竞态条件、vim 模式修复、tmux 剪贴板修复。 119
2026-03-14 指南 v2.18:新增 v2.1.76 的功能。MCP elicitation(征询输入)支持:MCP 服务器可在任务进行中通过交互式对话框请求结构化输入。3 个新的 hook 事件:Elicitation、ElicitationResult、PostCompact(共 22 个)。-n/--name CLI 标志用于在启动时设置会话显示名称。worktree.sparsePaths 用于大型单体仓库的稀疏检出。/effort 斜杠命令用于设置模型 effort 级别。bug 修复:延迟加载工具在压缩后丢失 schema、计划模式重复审批、语音模式按键、自动压缩熔断器(最多 3 次尝试)、通过 SSH 使用 tmux 时的剪贴板、Remote Control 会话稳定性。 118
2026-03-13 指南 v2.17:新增 v2.1.75 的功能。Opus 4.6 在 Max、Team 和 Enterprise 计划中默认启用 1M 上下文窗口(无需 [1m] 后缀)。/color 命令面向所有用户开放。记忆文件现在包含最后修改时间戳,便于判断新鲜度。hook 权限提示现在会显示来源(settings/plugin/skill)。使用 /rename 后会话名称显示在提示栏上。bug 修复:语音模式激活、管道命令中的 Bash !、token 估算过高导致过早压缩、macOS 上的启动性能。破坏性变更:移除了已弃用的 Windows 托管设置回退路径。 117
2026-03-12 指南 v2.16:新增 v2.1.73 和 v2.1.74 的功能。v2.1.73:用于自定义提供商模型 ID(Bedrock/Vertex/Foundry)的 modelOverrides 设置、弃用 /output-style(改用 /config)、云提供商上默认使用 Opus 4.6、中断后按上方向键可恢复提示词并回退、响应过程中可使用 /effort、SSL 证书错误指引、CPU 卡死与死锁修复、SessionStart hooks 触发两次的修复。v2.1.74:/context 可操作的建议、autoMemoryDirectory 设置、--plugin-dir 覆盖行为变更、CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 可配置超时、托管策略强制执行修复、内存泄漏修复(流式缓冲区)、RTL 文本渲染修复、MCP OAuth 修复。 115116
2026-03-11 指南 v2.15:新增 v2.1.72 的功能和 Code Review 产品。Code Review [研究预览版]:多代理 PR 审查系统,派发并行代理以交叉验证审查结果。面向 Team/Enterprise,每次审查 15-25 美元,约 20 分钟。v2.1.72:/plan 接受描述参数、/copy 中的 w 键可写入文件、ExitWorktree 工具、CLAUDE_CODE_DISABLE_CRON 环境变量、扩展的 bash 允许列表(lsof、pgrep、tput、ss、fd、fdfind)、恢复 Agent 工具的 model 参数以支持按调用覆盖、简化的 effort 符号(○ ◐ ●)、/config 导航改进(Esc/Enter/Space)、打包体积减少 510KB、VSCode URI 处理程序。 113114
2026-03-10 新增:v2.1.72:配置了 ENABLE_TOOL_SEARCH 后,工具搜索可与 ANTHROPIC_BASE_URL 一同启用。/copy 中的 w 键可将所选内容写入文件(对 SSH 友好)。/plan 接受可选描述。ExitWorktree 工具用于退出 worktree 会话。CLAUDE_CODE_DISABLE_CRON 可停止计划任务。bash 允许列表:lsof、pgrep、tput、ss、fd、fdfind。恢复 Agent 工具的 model 参数以支持按调用覆盖模型。effort 级别简化为 ○/◐/● 符号。/config 导航:Esc 取消、Enter 保存、Space 切换。打包体积减少 510KB。语音转录准确度提升。VSCode URI 处理程序支持以编程方式打开标签页。修复了 Windows/OneDrive 上的插件安装、并行工具调用级联、代理进度跟踪问题。 114
2026-03-09 Code Review 发布。多代理 PR 审查系统:派发并行代理交叉验证审查结果并按严重程度排序。每次审查 15-25 美元。面向 Team/Enterprise 的研究预览版。54% 的 PR 收到实质性评论(此前为 16%)。错误发现率低于 1%。 113
2026-03-09 指南 v2.14:新增 /loop 循环任务命令(v2.1.71)。新增专门的“Claude Code 网页版”章节,涵盖功能、安全架构、可用性以及网页版与终端版的决策对照表。新增对移动应用(iOS)的提及。快速参考卡片更新了 /loop。 112
2026-03-07 新增:v2.1.71:/loop 命令可按间隔重复执行提示词(/loop 5m /foo)。语音快捷键自定义。Bash 自动审批允许列表扩展。标准输入卡死修复。macOS 上的 CoreAudio 启动优化。 112
2026-03-06 指南 v2.13:新增语音模式章节(/voice、按键通话、20 种 STT 语言)。v2.1.68 的 effort 变更(Max/Team 用户的 Opus 4.6 默认为中等 effort,重新引入 ultrathink,移除 Opus 4/4.1)。v2.1.69 功能:/claude-api skill、InstructionsLoaded hook 事件、agent_id/agent_type/worktree hook 字段、${CLAUDE_SKILL_DIR}、/reload-plugins、CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS、sandbox.enableWeakerNetworkIsolation、远程控制自定义名称、Ctrl+U 退出 bash 模式、数字小键盘支持。v2.1.70 修复:第三方网关导致的 API 400 错误、effort 参数错误、ToolSearch 之后的空响应。VS Code:火花图标会话列表、markdown 计划视图、原生 MCP 管理。性能:提示词渲染减少 74%,Remote Control 轮询频率降低 300 倍。subagent 模型默认值更新为 inherit。hook 事件总数达到 18 个。 109110111
2026-03-06 新增:v2.1.70——修复了使用 ANTHROPIC_BASE_URL 第三方网关时的 API 400 错误(工具搜索会为代理端点禁用 tool_reference 块)。修复了自定义 Bedrock 推理配置文件的 effort 参数错误。修复了 ToolSearch 之后模型返回空响应的问题。改进了压缩逻辑,保留图片以便复用提示词缓存。/rename 可在 Claude 处理过程中使用。提示词重新渲染减少约 74%。Remote Control 的 /poll 降至每 10 分钟 1 次(减少约 300 倍)。VS Code:火花图标会话列表以完整编辑器形式打开,带评论的完整 markdown 计划视图,原生 /mcp 对话框。每次 --resume 节省约 600 个 token(skill 列表重复注入修复)。多项 Windows/语音/plugin/安全修复。 109
2026-03-05 新增:v2.1.69——/claude-api skill。InstructionsLoaded hook 事件。hook 事件中的 agent_id/agent_type/worktree 字段。${CLAUDE_SKILL_DIR} skill 自引用变量。/reload-plugins 命令。用于 Go/MITM 代理的 sandbox.enableWeakerNetworkIsolation。includeGitInstructions 设置 + CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS 环境变量。远程控制自定义名称(--name)。语音 STT 新增 10 种语言(共 20 种)。effort 级别显示。Ctrl+U 退出 bash 模式。数字小键盘支持。git-subdir plugin 源类型。用于 MCP 服务器的 oauth.authServerMetadataUrl。Sonnet 4.5→4.6 自动迁移。安全方面:修复了从被 gitignore 的目录嵌套发现 skill、符号链接写入逃逸、信任对话框启用所有 .mcp.json 服务器等问题。70 多项错误修复,包括 macOS 钥匙串损坏、队友嵌套生成、内存泄漏。 110
2026-03-04 新增:v2.1.68——Max/Team 订阅用户的 Opus 4.6 默认使用中等 effort。重新引入用于高 effort 的“ultrathink”关键字。在第一方 API 上,从 Claude Code 中移除了 Opus 4 和 Opus 4.1。 109
2026-03-03 语音模式正式推出。 /voice 启用按键通话(按住空格键说话)。逐步推出(初期约 5%)。定位为专业的结对编程工具,而非休闲语音助手。 111
2026-03-02 指南 v2.12:记录了 Task 工具→Agent 工具的重命名(Agent(agent_type) 语法,Task(...) 作为别名)。托管设置支持 macOS plist 和 Windows 注册表(v2.1.51)。Figma 合作集成说明。 106107108
2026-02-28 指南 v2.11:新增 v2.1.63 功能。内置斜杠命令 /simplify 和 /batch。worktree 共享的项目配置和自动记忆。通过 ENABLE_CLAUDEAI_MCP_SERVERS=false 退出 claude.ai MCP 连接器。HTTP hooks 正式的 type: "http" 处理程序文档。/copy 的“始终复制完整响应”选项。VSCode 会话重命名/移除。/clear skill 缓存重置修复。多项内存泄漏修复。REPL 桥接竞态条件修复。GitHub Copilot Business/Pro 中 Claude 可用性的交叉引用。 104105
2026-02-27 指南 v2.10:新增 v2.1.58–v2.1.62 功能。/copy 命令(交互式代码块选择器)。/memory 命令增强,用于自动记忆管理。Remote Control 向更多用户开放(v2.1.58)。行业采用数据:占 GitHub 提交的 4%(约每天 13.5 万次)。在不受信任仓库警告中加入 CVE-2025-59536 和 CVE-2026-21852 安全公告。提示建议缓存修复(v2.1.62)。Windows 并发写入导致配置文件损坏的修复(v2.1.61)。改进了复合命令的 bash“始终允许”前缀建议。多代理会话中的内存使用改进。MCP OAuth token 刷新竞态条件修复。 100101102103
2026-02-25 指南 v2.9:新增 v2.1.52–v2.1.56 错误修复。修正了 Agent Teams 导航说明(仅 Shift+Down,而非 Shift+Up/Down)。新增团队存储路径和任务依赖详情。新增 TeammateIdle/TaskCompleted hook 集成说明。 99
2026-02-25 新增:v2.1.53–v2.1.56——修复了 Windows 上 VS Code 的崩溃问题,修复了提交后输入内容短暂消失的 UI 闪烁,修复了批量终止代理(Ctrl+F)改为发送单条汇总通知,修复了 Remote Control 优雅关闭时遗留过期会话的问题,修复了 --worktree 在首次启动时偶尔被忽略的问题,修复了 Windows 上 BashTool 的 EINVAL 错误,修复了 Windows ARM64 上以及 Linux/Windows x64 上 WASM 解释器中的崩溃。 99
2026-02-23 指南 v2.8:新增 v2.1.51 功能。面向外部构建的 claude remote-control 子命令。HTTP hook 安全:在标头中插值环境变量需要 allowedEnvVars;HTTP hooks 经由沙箱代理路由。工具结果持久化到磁盘的阈值降至 5 万字符(原为 10 万)。BashTool 默认跳过登录 shell。plugin 改进:自定义 npm 注册表、版本锁定、可配置的 git 超时。/model 选择器显示人类可读的标签。SDK 调用方身份环境变量。Agent Teams 队友的计划审批。 98
2026-02-24 新增:v2.1.51——面向外部构建的 claude remote-control 子命令,用于 HTTP hook 环境变量插值安全的 allowedEnvVars,HTTP hooks 经由沙箱网络代理路由,超过 5 万字符的工具结果持久化到磁盘(原为 10 万),BashTool 默认跳过登录 shell,plugin 市场 git 超时可配置(CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS),plugins 支持自定义 npm 注册表和版本锁定,/model 选择器人类可读标签,CLAUDE_CODE_ACCOUNT_UUID/CLAUDE_CODE_USER_EMAIL/CLAUDE_CODE_ORGANIZATION_UUID SDK 环境变量,statusLine/fileSuggestion hooks 需要工作区信任。修复:重复 control_response 导致的 API 400 错误,SKILL.md 描述为 YAML 数组时斜杠命令自动补全崩溃的问题。 98
2026-02-22 指南 v2.7:修正了快速模式定价表——删除了错误的 >200K 分层定价($60/$225)。官方 Anthropic 定价确认在整个上下文窗口内统一为 $30/$150,无长上下文附加费。在隐藏工具费用表中加入网页抓取(免费)。补充说明:包含 web_search/web_fetch 工具时代码执行免费。补充说明:失败的网页搜索不计费。 1
2026-02-21 指南 v2.6:新增 v2.1.49 和 v2.1.50 功能。新的 hook 事件:ConfigChange、WorktreeCreate、WorktreeRemove(共 17 个)。用于隔离 git worktree 的新标志 --worktree/-w。subagent 的 isolation: "worktree" 和 background: true 字段。claude agents CLI 命令。CLAUDE_CODE_DISABLE_1M_CONTEXT 环境变量。Opus 4.6 快速模式现已包含完整的 1M 上下文。Claude Code Security(研究预览版)。 —
2026-02-20 新增:v2.1.50——LSP 服务器的 startupTimeout,用于自定义 VCS 设置/清理的 WorktreeCreate/WorktreeRemove hook 事件,代理定义中的 isolation: worktree,claude agents CLI 命令,CLAUDE_CODE_DISABLE_1M_CONTEXT 环境变量,Opus 4.6 快速模式现已包含完整的 1M 上下文窗口,VSCode /extra-usage 命令支持。CLAUDE_CODE_SIMPLE 现在会禁用 MCP 工具、附件、hooks 和 CLAUDE.md 加载。修复:符号链接会话不可见,SSH 断开连接时的会话数据丢失,agent teams 中的内存泄漏(已完成任务未被垃圾回收),/mcp reconnect 对不存在的服务器卡死,LSP 诊断数据内存泄漏,提示建议缓存回归,Edit 工具 Unicode 弯引号损坏。Linux:修复了 glibc < 2.30(RHEL 8)上的原生模块问题。针对长会话的多项内存优化改进。 96
2026-02-19 新增:v2.1.49——--worktree(-w)标志可在隔离的 git worktree 中启动 Claude,subagents 支持 isolation: "worktree" 以在临时 git worktree 中工作,代理定义支持 background: true 以始终作为后台任务运行,用于企业安全审计的 ConfigChange hook 事件,plugins 可自带 settings.json 作为默认配置,SDK 模型信息现在包含 supportsEffort/supportedEffortLevels/supportsAdaptiveThinking 字段。CLAUDE_CODE_SIMPLE 现在包含文件编辑工具。移除了 1M 上下文的 Sonnet 4.5,改用 Sonnet 4.6。改进了 MCP OAuth,支持升级认证和发现缓存。修复:后台代理运行时 Ctrl+C 和 ESC 被忽略,WASM 内存无限增长,disableAllHooks 托管设置层级,--resume 显示原始 XML 标签。权限提示改进为显示限制原因。 96
2026-02-20 Claude Code Security(研究预览):内置于网页版 Claude Code 的漏洞扫描功能。扫描代码库并提出补丁建议,供人工审阅。面向 Enterprise、Team 以及开源维护者开放。 97
2026-02-18 新增:v2.1.47——Ctrl+F 可终止所有后台 agent(取代双击 ESC),Stop/SubagentStop hook 输入中新增 last_assistant_message 字段,新增 chat:newline 键绑定操作,statusline JSON 中新增 added_dirs,/rename 会更新终端标签页标题,恢复选择器显示 50 个会话(原为 10 个),队友导航简化为仅 Shift+Down。性能:启动速度提升约 500ms(延迟执行 SessionStart hooks),内存优化(释放 API 流缓冲区,修复 O(n²) 进度更新问题)。修复:压缩后保留计划模式,Edit 工具 Unicode 弯引号损坏问题,CJK 全角字符对齐,并发 agent API 400 错误,/resume 丢弃大型会话(>16KB),压缩后会话名称丢失,后台 agent 结果返回原始转录内容,以及多项 Windows 修复(通过 Git Bash 运行 hooks、清理 CWD 跟踪、盘符大小写、WSL2 上的 BMP 粘贴)。 95
2026-02-18 新增:v2.1.46——Claude Code 支持 claude.ai MCP 连接器,修复了 macOS 上终端断开后残留孤儿 CC 进程的问题。v2.1.45——新增 spinnerTipsOverride 设置、SDKRateLimitInfo/SDKRateLimitEvent SDK 类型,修复了 Bedrock/Vertex/Foundry 上的 Agent Teams 问题,修复了 macOS 上沙箱临时文件错误,并改进了启动速度与内存占用。 95
2026-02-18 指南 v2.5:键盘快捷键中新增 Ctrl+F 和 Shift+Down,设置参考中新增 spinnerTipsOverride,新增 last_assistant_message hook 字段、chat:newline 键绑定、claude.ai MCP 连接器章节,以及恢复选择器 50 个会话的更新。 —
2026-02-17 重大更新:Claude Sonnet 4.6 发布。 模型 ID:claude-sonnet-4-6。取代 Sonnet 4.5 成为 claude.ai 和 Claude Cowork 的默认模型。定价不变(每百万 token $3/$15)。智能体式搜索性能提升,消耗的 token 更少。支持自适应思考、扩展思考以及 1M token 上下文窗口(beta)。最大输出 64K。知识截止:可靠截止至 2025 年 8 月,训练数据截至 2026 年 1 月。Sonnet 4.5 转为旧版模型。另外:API 代码执行现与网页搜索/网页抓取搭配时免费,网页搜索工具和程序化工具调用现已正式发布(GA,无需 beta 标头)。 93
2026-02-17 指南 v2.4:为 Sonnet 4.6 更新了所有模型表格,将 Sonnet 4.6 加入扩展思考支持的模型列表,并更新了脚注和定价引用。 —
2026-02-14 新增:v2.1.44——修复了深层嵌套目录路径的 ENAMETOOLONG 错误,修复了身份验证刷新错误。v2.1.43——修复了 AWS 身份验证刷新挂起的问题(新增 3 分钟超时),修复了 .claude/agents/ 中非 agent markdown 文件触发的误报警告,修复了 Vertex/Bedrock 上无条件发送 structured-outputs beta 标头的问题。 94
2026-02-16 指南 v2.3:移除了已过期的快速模式促销定价(2 月 16 日截止日期已过),新增 >200K 长上下文快速模式档位($60/$225),修复了 protect-files.sh 的退出码(阻止操作由 1 改为 2),修正了 3 处过时的 Tab→Alt+T 键绑定引用,重写了 Copilot/Cursor 迁移表格(两者现均具备智能体式 CLI+MCP),修正了 Claude Squad 安装命令(brew/curl、cs 二进制文件、TUI 应用),补充了 4 条缺失的目录条目(输出样式、斜杠命令、插件系统),更新了 7 个脚注 URL(docs.anthropic.com→code.claude.com 规范链接),补充了 48 缺失的 URL,修正了 5 的重定向说明,新增托管设置键表格(allowManagedPermissionRulesOnly、allowManagedHooksOnly 等),针对不可信仓库新增提示注入安全警告。新增快速入门章节、专门的计划模式章节,扩充了非交互模式(-p)文档,加入退出码和 CI/CD 模式,修正了所有 --session-id 示例(需要 UUID;已迁移至 /rename + --resume),为远程和 Slack 章节添加了 [RESEARCH PREVIEW] 标记,为 1 个未标注的代码块补上标签,验证了全部 35 个目录锚点。评估后修复:TL;DR 模型推荐改为不区分套餐层级,jq 的 // 模式修正为 select(),虚构的 --input-file 标志替换为管道,修正了 Docker 沙箱语法,“sub-agent”连字符写法统一为“subagent”,在斜杠命令表格中新增 /login 和 /logout。 —
2026-02-13 新增:v2.1.42——修复了 /resume 将中断消息显示为会话标题的问题,修复了 Opus 4.6 发布公告向 Bedrock/Vertex/Foundry 用户显示的问题,改进了多图片尺寸限制错误的提示信息并建议使用 /compact。 90
2026-02-13 新增:v2.1.41——claude auth 子命令(login、status、logout),无需进入 REPL 即可管理身份验证;Windows ARM64 原生二进制支持;/rename 在不带参数调用时会根据对话上下文自动生成会话名称。修复:AWS 身份验证刷新无限期挂起(新增 3 分钟超时),带锚点片段的 @ 提及(例如 @README.md#installation),FileReadTool 在 FIFO//dev/stdin/大文件上阻塞,流式 Agent SDK 模式下的后台任务通知,分类器规则输入中的光标跳动,原始 URL 的 markdown 链接显示文本丢失,自动压缩失败通知向用户显示,权限等待时间被计入 subagent 耗时,计划模式下触发的主动 tick,设置变更后过时的权限规则未清除,hook 阻止错误在 UI 中显示 stderr。 90
2026-02-12 准确性与完整性校对:修正了 hooks 表格——Stop、SubagentStop、TeammateIdle、TaskCompleted 均可通过退出码 2 进行阻止。新增 PostToolUseFailure 事件。新增基于提示的 hooks(type: "prompt")和基于 agent 的 hooks(type: "agent")文档。将 PreToolUse 更新为推荐的 hookSpecificOutput 格式(顶层 decision 已弃用)。新增 hook 环境变量($CLAUDE_PROJECT_DIR、$CLAUDE_ENV_FILE)。新增 CLI --agents 标志,用于定义会话范围的 subagent。扩充了 subagent 配置表格:disallowedTools、maxTurns、mcpServers、hooks、delegate 权限模式。 89
2026-02-10 新增:v2.1.39——改进了终端渲染性能。修复:致命错误被吞没而未显示,会话关闭后进程挂起,终端屏幕边界处字符丢失,详细转录视图中出现空行。 88
2026-02-10 新增:v2.1.38——安全:沙箱模式下禁止写入 .claude/skills(防止提示注入篡改 skill 定义),改进了 heredoc 分隔符解析以防止命令夹带。修复:VS Code 终端滚动到顶部的回归问题,Tab 键将斜杠命令加入队列而非自动补全,使用环境变量包装的命令的 bash 权限匹配,非流式模式下工具调用之间的文本消失,在 VS Code 中恢复时出现重复会话。 88
2026-02-08 新增:v2.1.37——修复了启用 /extra-usage 后 /fast 无法立即使用的问题。 86
2026-02-08 新增:v2.1.36——快速模式现已支持 Opus 4.6。 同一模型,输出更快,采用溢价定价(标准费率的 6 倍,2 月 16 日前享 50% 促销折扣)。使用 /fast 切换。 86
2026-02-07 新增:v2.1.34——安全修复:当启用 autoAllowBashIfSandboxed 时,通过 sandbox.excludedCommands 或 dangerouslyDisableSandbox 排除在沙箱之外的命令可能绕过 Bash 的 ask 权限规则。同时修复了 agent teams 设置在渲染之间变更时导致的崩溃。 87
2026-02-05 新增:v2.1.33——面向多 agent 工作流的 TeammateIdle 和 TaskCompleted hook 事件,在 agent 的 tools frontmatter 中使用 Task(agent_type) 语法限制可生成的 subagents,agent 的 memory frontmatter 字段(user/project/local 范围),在 skill 描述和 /skills 菜单中显示插件名称。修复:tmux 中的 agent 队友会话无法收发消息,不支持的套餐上出现 agent teams 可用性警告,提交新消息时扩展思考被中断,带有空白+思考块的中途流式中止导致 API 错误,API 代理 404 流式回退,settings.json 环境变量中的代理设置未应用于 WebFetch,/resume 会话选择器显示原始 XML 标记。改进:API 连接错误消息现会显示具体原因(ECONNREFUSED、SSL 错误)。VSCode:为 OAuth 用户提供远程会话支持,会话选择器中显示 git 分支和消息数并支持分支搜索,修复了滚动到底部的问题。 85
2026-02-05 重大更新:Claude Opus 4.6 发布。 模型 ID:claude-opus-4-6。100 万 token 上下文窗口(测试版),是首个具备此容量的 Opus 级模型。最大输出 128K token。自适应思考(自动调节推理深度)。effort 强度控制(low/medium/high/max)。上下文压缩测试版。Agent teams 研究预览(多智能体并行协作)。Terminal-Bench 2.0 得分为业界最高。GDPval-AA:比 GPT-5.2 高 144 Elo,比 Opus 4.5 高 190 Elo。在 8-needle 1M MRCR v2 上准确率达 76%(竞品约为 18.5%)。开箱即用便在开源代码中发现 500 多个零日漏洞。定价与 Opus 4.5 相同:每百万 token $5/$25。长上下文(输入超过 200K):$10/$37.50。 79
2026-02-05 新增:v2.1.32——支持 Opus 4.6,agent teams 研究预览(需设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1),自动记忆记录/召回,消息选择器中新增“从此处开始总结”以对部分对话进行总结,自动加载 --add-dir 目录中的 skills,skill 字符预算随上下文窗口按比例调整(上下文的 2%)。修复:@ 文件补全在子目录中生成错误的相对路径,--resume 现在会沿用上一会话的 --agent 值,heredoc 中 JavaScript 模板字面量导致的 bash “Bad substitution” 错误,泰语/老挝语间距元音的渲染问题。VSCode:修复斜杠命令执行问题,历史对话列表新增加载指示器。 80
2026-02-04 GitHub 集成:Claude 和 Codex 现已在 GitHub 上开放公开预览,通过 Agent HQ 作为编码代理向 Copilot Pro+ 和 Enterprise 客户提供。Opus 4.6 已在 GitHub Copilot 中正式可用。83 83
2026-02-04 新增:v2.1.31——退出时显示会话恢复提示,说明如何继续;复选框选择支持日语输入法全角(zenkaku)空格输入。修复:PDF 错误导致会话被永久锁定,沙盒模式下 bash 出现“只读文件系统”错误,~/.claude.json 字段缺失时计划模式崩溃,流式 API 中 temperatureOverride 被静默忽略,LSP 关闭兼容性问题。改进:系统提示引导模型优先使用专用工具(Read、Edit、Glob、Grep)而非 bash 等价命令,PDF/请求大小错误消息(100 页、20MB 限制)。 75
2026-02-03 新增:v2.1.30——Read 工具的 PDF pages 参数(读取指定页码范围,如 pages: "1-5"),大型 PDF(超过 10 页)在被 @ 提及时返回轻量级引用,为不支持 DCR 的 MCP 服务器(如 Slack)预配置 OAuth 客户端凭据,用于排查问题的 /debug 命令,只读模式下支持更多 git log/git show 标志,Task 工具结果中包含 token 数量/工具调用次数/耗时指标,reducedMotion 配置选项。通过基于 stat 的会话加载,--resume 内存占用减少 68%。修复:API 历史中的幻影“(no content)”文本块(减少 token 浪费),工具变更时的提示缓存失效,带思考块的 /login 之后出现 400 错误,恢复损坏的转录文件时挂起,Max 20x 的速率限制提示信息,权限对话框抢占焦点,subagents 无法访问 SDK 提供的 MCP 工具,Windows 下 bash 与 .bashrc 的问题。 76
2026-01-31 新增:v2.1.29——修复了使用 saved_hook_context 恢复会话时的启动性能回退问题。 85
2026-02-01 企业采用:ServiceNow 选择 Claude 作为 ServiceNow Build Agent 的默认模型,并向 29,000 多名员工推广 Claude Code,将销售人员的准备时间缩短 95%。Allianz 宣布建立合作伙伴关系,向全体员工开放 Claude Code。 77
2026-01-30 重大变更:Xcode 26.3 引入原生 Claude Agent SDK 集成(与驱动 Claude Code 的是同一套运行框架),可直接在 Xcode 中使用 subagents、后台任务和 plugins,无需离开 IDE。在 SwiftUI 开发过程中捕获 Xcode Previews 以进行可视化迭代。 78
2026-01-30 新增:v2.1.27——--from-pr 标志用于恢复与 GitHub PR 编号/URL 关联的会话,通过 gh pr create 创建 PR 时会话会自动关联,调试日志中记录工具调用失败/拒绝情况,启用 VSCode 的 Claude in Chrome 集成。修复:网关用户的上下文管理验证,/context 彩色输出,状态栏重复显示后台任务指示器,权限优先级(内容级 ask > 工具级 allow)。Windows:bash 执行时加载 .bashrc,控制台窗口闪烁。VSCode:OAuth 令牌过期导致 401 错误。 74
2026-01-29 新增:v2.1.25——修复了 Bedrock 和 Vertex 网关用户的 beta 标头验证错误。临时解决方法:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。 73
2026-01-28 新增:v2.1.23——用于自定义加载指示文字的 spinnerVerbs 设置,企业环境的 mTLS/代理连接修复,按用户隔离的临时目录,ripgrep 超时错误报告(此前会静默返回空结果),提示符页脚中已合并 PR 的紫色状态指示器,bash 超时时长显示。修复:提示缓存竞争条件,无头模式下待处理的异步 hooks 未被取消,Tab 补全未更新输入内容,无头模式下 Bedrock 区域显示。 69
2026-01-28 新增:v2.1.22——修复了非交互(-p)模式下的结构化输出问题。 68
2026-01-28 新增:v2.1.21——VSCode 中自动激活 Python venv(claudeCode.usePythonEnvironment 设置),支持日语输入法全角(zenkaku)数字输入,Read/搜索进度指示器(“Reading…” → “Read”),Claude 现在优先使用文件操作工具而非 bash 等价命令。修复:退出时 shell 补全缓存被截断,恢复在工具执行期间中断的会话时出现 API 错误,在输出上限较大的模型上自动压缩触发过早,删除后任务 ID 被重用,VSCode 中的 Windows 文件搜索。 67
2026-01-28 新增:MCP Apps(在 Claude 内为 Asana、Figma、Slack 等提供交互式工具界面)。Code Execution Tool v2(以 Bash 执行取代仅限 Python 的执行,支持编程式工具调用)。网页版 Claude Code 扩展至 Team/Enterprise 高级席位。 667172
2026-01-27 新增:v2.1.20——--add-dir 标志用于从额外目录加载 CLAUDE.md(需设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1),提示符页脚中的 PR 审查状态指示器(彩色圆点显示已批准/需修改/待审查/草稿),通过 TaskUpdate 工具删除任务,vim 方向键历史导航,/copy 命令向所有用户开放,带时间戳的配置备份(轮换保留最近 5 份)。修复:恢复会话时会话压缩加载完整历史,agents 工作时忽略用户消息,宽字符(emoji/中日韩文字)渲染异常,MCP 响应中含 Unicode 时的 JSON 解析。 65
2026-01-26 增强:Analytics API 章节新增详细的端点文档、指标表、curl 示例和限制说明。现包含身份验证要求、可用指标(生产力、工具使用、成本)以及实时监控替代方案。 46
2026-01-24 新增:v2.1.19——自定义命令参数的 $0、$1 简写(从 $ARGUMENTS.0 改为 $ARGUMENTS[0] 方括号语法),CLAUDE_CODE_ENABLE_TASKS 环境变量用于禁用新任务系统,不含额外权限/hooks 的 skills 不再需要审批。VSCode:会话分叉和回退向所有用户开放。SDK:queued_command 以 SDKUserMessageReplay 事件形式重放。修复:关闭终端时进程残留,git worktree 中的 /rename//tag,使用提示暂存(Ctrl+S)时粘贴文本丢失,agent 模型显示,后台化的 hook 命令未提前返回,文件写入预览遗漏空行。 64
2026-01-24 新增:v2.1.17——修复了在不支持 AVX 指令集的处理器上崩溃的问题。 64
2026-01-24 重大变更:扩展思考现默认启用,预算为 31,999 token。自然语言触发词(think、think hard、ultrathink)已弃用,不再分配思考 token,请改用 MAX_THINKING_TOKENS 环境变量或 /config。已根据当前行为更新“扩展思考”章节。 63
2026-01-24 新增:v2.1.18——可自定义的键盘快捷键,支持特定上下文的键绑定、组合键序列,并可通过 /keybindings 命令进行完整的个性化配置。配置存储在 ~/.claude/keybindings.json 中。 70
2026-01-24 新增:v2.1.16——带依赖跟踪的任务管理系统,VSCode 原生 plugin 管理支持,OAuth 用户可从会话对话框浏览/恢复远程会话。修复:恢复 subagent 时的内存溢出崩溃,/compact 警告可见性,会话标题语言设置,Windows IDE 竞争条件。 62
2026-01-21 新增:v2.1.15——npm 安装方式弃用通知(推荐使用原生二进制文件),React Compiler 界面性能改进。修复:/compact 警告未清除,MCP stdio 服务器超时未终止子进程(可能导致界面冻结)。 61
2026-01-20 新增:v2.1.14——bash 模式下基于历史记录的自动补全(! + Tab)、已安装列表中的插件搜索、将插件固定到 git 提交 SHA、VSCode /usage 命令。关键修复:上下文窗口阻塞阈值(约 65%→约 98%)、并行 subagents 导致的内存崩溃、长会话中的内存泄漏、bash 模式下的 @ 符号文件自动补全、/feedback 无效 URL、/context token 计数显示、斜杠命令自动补全选择错误。 60
2026-01-20 新增:v2.1.12(消息渲染错误修复)。将 Setup hook 的版本更正为 v2.1.10,并附上完整发布说明:用于复制 OAuth URL 的“c”键盘快捷键、改进的启动按键捕获、可移除附件形式的文件建议、VSCode 插件安装数量与信任警告。新增 teleport 单向限制说明。 59
2026-01-19 文档更新:在事件表中新增 SubagentStart hook,扩充了 PreToolUse hooks 的 additionalContext 文档(v2.1.9),扩充了 LSP 工具功能部分,并在“值得关注的人”中补充了内容创作者和官方资源。 —
2026-01-19 新增:Setup hook 事件(v2.1.10)——通过 --init、--init-only 或 --maintenance CLI 标志触发,用于环境设置任务。 53
2026-01-18 新增:多账户政策部分(允许的做法、技术限制、禁止的做法)。新增社区技巧部分(计划模式自动清除上下文、/clear、截图、容器模式)。新增“值得关注的人”(Boris Cherny、Thariq、Jeffrey Emanuel)。新增 API token 定价表。 49505152
2026-01-17 新增:v2.1.11 版本——修复了 HTTP/SSE 传输方式下过多的 MCP 连接请求(为重度 MCP 用户提升稳定性)。 48
2026-01-16 新增:MCP 工具搜索部分及基准数据(Opus 4:49%→74%,Opus 4.5:79.5%→88.1%,token 开销减少 85%)。更新了 MCP 生态统计数据(每月 1 亿次下载,3,000 多个服务器)。 47
2026-01-16 新增:Claude Code Analytics API 部分——Team/Enterprise 用户可通过 Admin API 端点 /v1/organizations/usage_report/claude_code 以编程方式获取使用指标(会话、提交、PR、代码行数)。记录了 ${CLAUDE_SESSION_ID} skill 替换功能(v2.1.9)。 4446
2026-01-15 新增:v2.1.9 用于 MCP 工具搜索阈值的 auto:N 语法、plansDirectory 设置、AskUserQuestion 中的外部编辑器(Ctrl+G)、Web 会话提交/PR 的会话 URL 归属标注、PreToolUse hooks 的 additionalContext。修复了并行工具调用的 API 错误、MCP 重连挂起、Kitty 中的 Ctrl+Z 问题。新增 Cowork(面向非技术用户的 GUI 版本)。 4445
2026-01-15 新增:v2.1.7 权限反馈功能(接受权限提示时可提供反馈)。GitHub Action v1.0 正式发布(GA)。小幅文档更新。 41
2026-01-14 新增:v2.1.7 默认启用 MCP 工具搜索自动模式(当工具占用超过 10% 上下文时延迟加载)、showTurnDuration 设置、任务通知中内联显示 agent 响应、修复通配符权限匹配复合命令的安全问题。v2.1.6:/config 搜索、/doctor 的 Updates 部分、/stats 日期范围筛选、嵌套 .claude/skills 发现、context_window.used_percentage/remaining_percentage 字段、修复 shell 行续接导致的权限绕过安全问题。v2.1.5:CLAUDE_CODE_TMPDIR 环境变量。 414243
2026-01-13 新增:URL 从 console.anthropic.com 变更为 platform.claude.com(v2.1.4)。新增用于隔离上下文的 context: fork skill frontmatter 选项。新增 subagents 的权限拒绝容错能力(v2.1.0+)。新增插件市场上线信息(2025年12月,36 个精选插件)。 40
2026-01-12 新增:v2.1.4 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 环境变量,用于禁用全部后台任务功能,包括自动后台化和 Ctrl+B 快捷键。修复了“Help improve Claude”设置的 OAuth token 刷新问题。 39
2026-01-10 新增:沙箱可减少 84% 的权限提示(来自 Anthropic 工程博客)、Opus 4.5 的 SWE-bench 表现(80.9%)以及 token 效率提升。小幅文档更新。 38
2026-01-10 新增:v2.1.3 合并了斜杠命令与 skills(统一的心智模型)、/config 中的发布渠道切换(stable/latest)、/doctor 可检测无法生效的权限规则、hook 执行超时从 60 秒延长至 10 分钟。错误修复:计划文件在 /clear 后仍然保留、ExFAT 上的 skill 重复检测、后台任务计数不一致、subagents 在压缩期间使用错误的模型。VSCode:可点击的权限目标选择器。 37
2026-01-09 新增:v2.1.1(109 项 CLI 改进)、组件级作用域 Hooks(在 skill/命令 frontmatter 中定义的 hooks,支持 once 选项)、新的 MCP 服务器(Figma Dev Mode、Sequential Thinking、Magic UI、Context7)。MCP 生态服务器数量更新为 3,000 多个。 343536
2026-01-08 新增:settings.json 参考中的 language 和 respectGitignore 设置。新增 IS_DEMO 环境变量。更新了多行输入说明,指出 Shift+Enter 在 iTerm2/WezTerm/Ghostty/Kitty 中开箱即用。新增每个组织每月 1,550 小时的免费代码执行时长。 3033
2026-01-08 新增:v2.1.2 工具输出中可点击的文件路径(iTerm 使用 OSC 8)、Windows 包管理器(winget)支持、计划模式下通过 Shift+Tab 切换“自动接受编辑”、FORCE_AUTOUPDATE_PLUGINS 环境变量、SessionStart hook 中的 agent_type 字段。安全修复:bash 处理中的命令注入、tree-sitter 导致的内存泄漏。思考切换快捷键更新为 Alt+T。新增 MCP 通配符权限语法(mcp__server__*)。新增 PreToolUse hooks 的 updatedInput 支持 ask 权限。 32
2026-01-07 新增:v2.1.0 skill 自动热重载(~/.claude/skills 或 .claude/skills 中的 skills 无需重启即可立即使用)。安全:CVE-2025-52882 WebSocket 身份验证绕过漏洞已在 IDE 扩展 v1.0.24+ 中修补 3031
2026-01-06 新增:v2.0.74 可点击的图片链接([Image #N])、/context 分组显示、git 仓库中的文件 @ 提及速度提升 3 倍、.ignore 与 .rgignore 支持、Claude Agent SDK v0.1.74 272829
2025-12-28 新增:命名会话(/rename、/resume <n>)、插件发现搜索筛选、支持自定义会话 ID 的 --fork-session、Agent Skills 部分、异步 subagents、Claude Agent SDK(由 Claude Code SDK 更名而来)、Alt+Y yank-pop、Alt+T 思考切换、Ctrl+T 语法高亮切换、节日促销活动(12月25日至31日用量上限翻倍) 2223242526
2025-12-24 新增:Claude in Chrome 部分、Claude Code in Slack 部分、LSP 工具、远程 MCP OAuth 支持、“ultrathink”命令、/theme 与 /plugin 命令、Kitty/Alacritty/Zed/Warp 终端支持 161718192021
2025-12-14 新增:Pro 用户可使用 Opus 4.5、订阅计划表、速率限制(2025年8月)、iOS 应用可用性 131415
2025-12-12 新增:后台 Agents 部分、输出样式部分、隐藏的工具费用、/stats、/fork、/rename、/statusline、/tasks 命令、.claude/rules/ 记忆目录、Batch API 技巧 9101112
2025-12-12 新增:Slack 集成、提示词建议、Alt+P 模型切换、/release-notes 命令、/rewind 命令、交互式 MCP 设置向导 678
2025-12-12 初始 10.0 版本:架构心智模型、决策框架、反模式、工作流配方、迁移指南、快速参考卡 —
运行 /update-cc-guide 以扫描并应用最新的 Claude Code 更新。

参考资料


  1. Anthropic 定价。“Claude API 定价”。2025年12月。 ↩↩↩↩

  2. Claude Code Subagents。“Subagents 文档”。2025年12月。 ↩

  3. MCPcat。“MCP 服务器下载量增长统计”。2025年12月。 ↩

  4. Claude Code 文档。“Hooks 指南”。2025年12月起从 docs.anthropic.com 重定向;规范 URL 已于2026年2月更新。 ↩↩↩↩↩↩

  5. Anthropic。“Claude Code 最佳实践”。2025年4月。注:原 URL 现已重定向至 code.claude.com/docs(内容已并入主文档)。另请参阅 Claude Code 文档。 ↩

  6. Claude Code CHANGELOG。“提示建议:Claude 现在会建议您接下来可能想做的事”。2025年12月16日。有关2025年12月的功能报道,另请参阅 TechCrunch。 ↩↩

  7. Anthropic。“Claude Slack 集成”。2025年12月。 ↩↩

  8. Claude Code 文档。“交互式 MCP 设置”。2025年12月起从 docs.anthropic.com 重定向;规范 URL 已于2026年2月更新。 ↩↩

  9. Northflank。“Claude Code 的隐藏工具费用”。2025年7月。 ↩↩

  10. Anthropic。“后台代理”。2025年12月。 ↩↩

  11. Claude Code 文档。“记忆规则目录”。2025年12月。 ↩↩

  12. GitHub。“输出样式发布”。2025年12月。 ↩↩

  13. GitHub CHANGELOG。“Pro 用户现在可以在订阅中使用 Opus 4.5”。2025年12月。 ↩↩

  14. Northflank。“2025年8月速率限制变更”。2025年7月。 ↩↩

  15. Claude 博客。“网页版 Claude Code 与 iOS 应用”。2025年11月。 ↩↩

  16. Claude 博客。“面向 Team 和 Enterprise 用户的网页版 Claude Code”。2025年11月。 ↩

  17. GitHub Releases。“Claude in Chrome(Beta)功能”。2025年12月。 ↩↩

  18. GitHub Releases。“LSP 工具与终端支持更新(v2.0.74)”。2025年12月。 ↩↩↩

  19. TechCrunch。“Claude Code 登陆 Slack 的公告”。2025年12月。 ↩↩

  20. GitHub Releases。“思考模式触发词:think、think harder、ultrathink”。2025年12月。 ↩

  21. Anthropic。“支持 OAuth 的远程 MCP”。2025年6月。 ↩↩

  22. GitHub Releases。“通过 /rename 和 /resume 使用命名会话”。2025年12月。 ↩

  23. GitHub Releases。“plugin 发现搜索过滤、通过 –fork-session 自定义会话 ID(v2.0.73-74)”。2025年12月。 ↩

  24. Anthropic 工程博客。“Agent Skills:可复用的任务专用模块”。2025年12月。 ↩↩

  25. Anthropic 工程博客。“Claude Agent SDK(由 Claude Code SDK 更名而来)”。2025年12月。 ↩↩

  26. Apidog。“2025年12月25日至31日,Pro/Max 订阅者的 Claude Code 用量上限翻倍”。2025年12月。 ↩

  27. GitHub Releases。“v2.0.73-74:可点击的图片链接、/context 分组显示、ctrl+t 语法高亮切换”。2026年1月。 ↩↩

  28. GitHub Releases。“v2.0.72:git 仓库中的 @ 提及文件建议速度提升 3 倍,支持 .ignore 和 .rgignore 文件”。2026年1月。 ↩↩

  29. GitHub Claude Agent SDK。“Claude Agent SDK v0.1.74 与 Claude Code v2.0.74 保持同步”。2026年1月。 ↩

  30. GitHub Releases。“v2.1.0:skills 自动热重载、用于设置回复语言的 language 设置、settings.json 中的 respectGitignore、IS_DEMO 环境变量、Shift+Enter 在 iTerm2/WezTerm/Ghostty/Kitty 中开箱即用”。2026年1月。 ↩↩↩

  31. Datadog Security Labs。“CVE-2025-52882:Claude Code IDE 扩展中的 WebSocket 身份验证绕过漏洞已在 v1.0.24+ 中修补”。2026年1月。 ↩↩

  32. GitHub Releases。“v2.1.2:可点击的文件路径(OSC 8)、winget 支持、计划模式下 Shift+Tab 自动接受、FORCE_AUTOUPDATE_PLUGINS、SessionStart hook 中的 agent_type、安全修复(命令注入、内存泄漏)、思考切换键改为 Alt+T、MCP 通配符权限、PreToolUse updatedInput 支持 ask”。2026年1月。 ↩↩↩

  33. Anthropic 定价。“每个组织每月可免费使用代码执行工具 1,550 小时”。2026年1月。 ↩↩

  34. VentureBeat。“Claude Code 2.1.0 引入了基础设施级功能。面向代理、skills 与斜杠命令的 hooks,支持限定作用域的 PreToolUse、PostToolUse 和 Stop 逻辑”。2026年1月。Medium。“Claude Code 2.1.1 带来了 109 项 CLI 改进”。 ↩↩

  35. Builder.io。“Figma 官方的 Dev Mode MCP 服务器可呈现您所选图层的实时结构:层级、自动布局、变体、文本样式和令牌引用”。2025年12月。 ↩↩

  36. Apidog。“Sequential Thinking MCP 服务器让 Claude 能以结构化、反思式的思考过程有条不紊地解决问题”。2026年1月。MCP.so。“已收录超过 3,000 个 MCP 服务器”。 ↩↩

  37. GitHub Releases。“v2.1.3:合并斜杠命令与 skills、/config 中的发布渠道切换、/doctor 可检测无法生效的权限、hook 超时延长至 10 分钟”。2026年1月。 ↩

  38. Anthropic。“沙箱机制可安全地将权限提示减少 84%”。2026年1月。Anthropic。“Claude Opus 4.5 在 SWE-bench Verified 上取得 80.9% 的成绩,同时将 token 用量减半”。 ↩↩

  39. GitHub Releases。“v2.1.4:新增 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 环境变量,修复了‘Help improve Claude’设置的 OAuth 令牌刷新问题”。2026年1月。 ↩

  40. VentureBeat。“Claude Code 2.1.0:通过 skill frontmatter 中的 context: fork 派生子代理上下文,代理在权限被拒后仍可继续运行”。2026年1月。GitHub ykdojo/claude-code-tips。“Anthropic 于2025年12月正式推出 plugin 市场,首批包含 36 个精选 plugin”。 ↩↩↩↩

  41. GitHub Releases。“v2.1.7:MCP 工具搜索自动模式默认启用、showTurnDuration 设置、任务通知中内联显示代理回复、通配符权限安全修复”。2026年1月。 ↩↩

  42. GitHub Releases。“v2.1.6:/config 搜索、/doctor 的 Updates 部分、/stats 日期范围筛选、嵌套 skills 发现、context_window 百分比字段、shell 续行安全修复”。2026年1月。 ↩

  43. GitHub Releases。“v2.1.5:用于覆盖临时目录的 CLAUDE_CODE_TMPDIR 环境变量”。2026年1月。 ↩

  44. GitHub Releases。“v2.1.9:新增用于 MCP 工具搜索阈值的 auto:N 语法、plansDirectory 设置、AskUserQuestion 中的外部编辑器(Ctrl+G)、提交/PR 中的会话 URL 署名、PreToolUse hooks 的 additionalContext。修复了并行工具调用的 API 错误、MCP 重连挂起、Kitty 中的 Ctrl+Z。”2026年1月。 ↩↩↩↩

  45. Wikipedia。“一个名为‘Cowork’、带有图形用户界面、面向非技术用户的版本于2026年1月[推出]。”2026年1月。 ↩

  46. Claude 文档。“通过 Claude Code Analytics Admin API,以编程方式访问您所在组织的 Claude Code 使用分析和生产力指标。”2026年1月。 ↩↩↩

  47. VentureBeat。“MCP 工具搜索:Opus 4 的准确率从49%提升至74%,Opus 4.5 从79.5%提升至88.1%。Boris Cherny:‘每位 Claude Code 用户的上下文都一下子多了许多。’”2026年1月。Anthropic。“MCP 月下载量已达1亿次,并已成为行业标准。”2026年1月。 ↩↩↩

  48. GitHub Releases。“Claude Code v2.1.11:修复了 HTTP/SSE 传输方式下 MCP 连接请求过多的问题。”2026年1月17日。 ↩↩

  49. Medium。“Boris Cherny:使用 Claude Code 的30天内完成259个 PR、497次提交,新增4万行代码、删除3.8万行。”2026年1月。 ↩↩

  50. Anthropic 定价。“API Token 定价:Haiku 4.5($1/$5)、Sonnet 4.6($3/$15)、Opus 4.6($5/$25)。”2026年2月。 ↩

  51. GitHub ykdojo/claude-code-tips。“社区技巧合集:计划模式、经常使用 /clear、截图、用 GitHub 应用处理 PR。”2026年1月。 ↩↩

  52. Anthropic 使用政策。多账户政策。Anthropic 支持。“同一手机号最多可验证三个账户。支持来自同一网络的多个付费订阅。”2026年1月。 ↩↩

  53. GitHub Releases。“v2.1.10:新增通过 –init、–init-only 或 –maintenance CLI 标志触发的 Setup hook 事件;登录时按‘c’快捷键复制 OAuth URL;改进启动时的按键捕获;文件建议以可移除附件的形式呈现;VSCode 插件安装次数和信任警告。”2026年1月17日。 ↩↩

  54. @adocomplete。“Advent of Claude 第15天:用于完全自主运行的 –dangerously-skip-permissions 标志(YOLO 模式)。”2026年1月。 ↩

  55. @adocomplete。“Claude Max 订阅者可获得3张访客通行证,通过 /passes 命令与他人分享 Claude Code Pro 试用。”2026年1月。 ↩

  56. @mattpocockuk。“用于安全探索不受信任代码库的 Docker 沙盒模式。”2026年1月。 ↩

  57. Daisy Hollman。“通宵 hooks 策略:将 lint 和测试 hooks 用作护栏,让 Claude 持续迭代直到测试通过。”2026年1月。 ↩

  58. @moofeez。“Claude Squad:在隔离的 worktree 中并行运行多个 Claude Code 实例的多智能体管理器。”2026年1月。 ↩

  59. GitHub Releases。“v2.1.12:修复了消息渲染错误。”2026年1月17日。 ↩

  60. GitHub Releases。“v2.1.14:bash 模式下基于历史记录的自动补全、插件搜索、将插件固定到 git SHA、VSCode 的 /usage 命令。修复:上下文窗口阻断上限(约65%→约98%)、并行 subagents 导致的内存崩溃、长会话中的内存泄漏、@ 符号文件自动补全、/feedback URL、/context token 计数、斜杠命令自动补全。”2026年1月20日。 ↩

  61. GitHub Releases。“v2.1.15:npm 安装方式弃用通知、React Compiler 带来的 UI 性能改进。修复:/compact 警告持续显示、MCP stdio 服务器超时后未终止子进程(UI 冻结修复)。”2026年1月21日。 ↩

  62. GitHub Releases。“v2.1.16:带依赖跟踪的任务管理系统、VSCode 原生插件管理、OAuth 用户可浏览/恢复远程会话。修复:恢复 subagent 时的 OOM 崩溃、/compact 警告可见性、会话标题语言、Windows IDE 竞态条件。”2026年1月22日。 ↩

  63. GitHub Issues。“Ultrathink 已弃用。思考模式默认启用,上限为31,999个 token。‘think’、‘think hard’、‘ultrathink’等关键词不再分配思考 token,请改用 MAX_THINKING_TOKENS 环境变量。”2026年1月。Decode Claude。“UltraThink 已死,扩展思考万岁。” ↩↩

  64. GitHub Releases。“v2.1.19:自定义命令参数的 $0/$1 简写、CLAUDE_CODE_ENABLE_TASKS 环境变量、面向所有用户的 VSCode 会话分叉/回退。v2.1.17:修复了在不支持 AVX 指令集的处理器上崩溃的问题。”2026年1月23日至24日。 ↩↩

  65. Claude Code 文档。“v2.1.20:用于从额外目录加载 CLAUDE.md 的 –add-dir 标志、PR 审查状态指示器、通过 TaskUpdate 删除任务、vim 方向键历史导航、面向所有用户的 /copy 命令、带时间戳的配置备份。修复:会话压缩问题、智能体忽略用户消息、宽字符渲染、含 Unicode 的 JSON 解析。”2026年1月27日。 ↩

  66. Anthropic。“除 Pro 和 Max 用户外,网页版 Claude Code 现已以研究预览形式面向拥有高级席位的 Team 和 Enterprise 用户开放。”2026年1月26日。 ↩↩↩↩↩

  67. GitHub Releases。“v2.1.21:日语输入法全角数字输入、VSCode 中 Python venv 自动激活(claudeCode.usePythonEnvironment)、Read/搜索进度指示器、Claude 优先使用文件工具而非 bash。修复:shell 补全缓存、会话恢复时的 API 错误、自动压缩时机、任务 ID 复用、Windows 文件搜索。”2026年1月27日。 ↩

  68. GitHub Releases。“v2.1.22:修复了非交互(-p)模式下的结构化输出。”2026年1月27日。 ↩

  69. GitHub Releases。“v2.1.23:spinnerVerbs 设置、mTLS/代理连接修复、按用户隔离临时目录、ripgrep 超时报告、已合并 PR 的紫色指示器、bash 超时显示。修复:提示词缓存竞态条件、无头模式下的异步 hooks、Tab 补全、Bedrock 区域字符串。”2026年1月28日。 ↩

  70. Claude Code 文档。“v2.1.18:可自定义的键盘快捷键,支持特定上下文的键位绑定、组合键序列和个性化设置。运行 /keybindings 进行配置。”2026年1月22日。 ↩↩

  71. Help Net Security。“Anthropic 为 Claude 新增了交互式工具支持(MCP Apps),用户可直接在 Claude 界面中与 Asana、Box、Canva、Figma、Hex、monday.com 和 Slack 交互。”2026年1月26日。 ↩↩

  72. Anthropic 开发者平台。“Code Execution Tool v2 公开测试版:在代码执行环境内执行 Bash 命令、操作文件以及以编程方式调用工具。”2026年1月。 ↩↩

  73. GitHub Releases。“v2.1.25:修复了 Bedrock 和 Vertex 网关用户的 beta 头部校验错误。临时解决方法:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。”2026年1月29日。 ↩

  74. GitHub Releases。“v2.1.27:用于关联 PR 会话的 –from-pr 标志、通过 gh pr create 自动将会话关联到 PR、调试日志中记录工具调用失败、VSCode 中的 Claude in Chrome 集成。修复:上下文管理校验、/context 彩色输出、状态栏重复、权限优先级、Windows bash/.bashrc、Windows 控制台闪烁、VSCode OAuth 401 错误。”2026年1月30日。 ↩↩

  75. GitHub 发布记录。“v2.1.31:会话恢复提示、日语输入法全角空格输入、修复 PDF 过大错误导致会话永久锁定的问题、修复沙箱中 bash 只读文件系统错误、修复 temperatureOverride 被静默忽略的问题、LSP 关闭兼容性、改进系统提示词以优先使用专用工具而非 bash。”2026年2月。 ↩

  76. GitHub 发布记录。“v2.1.30:Read 工具新增 PDF pages 参数、大型 PDF 返回轻量级引用、为 MCP(Slack)预配置 OAuth、/debug 命令、–resume 内存占用减少 68%、修复幻影 ‘(no content)’ 文本块、修复提示词缓存失效问题、修复 subagents 访问 SDK MCP 工具的问题。”2026年1月30日。 ↩↩

  77. Anthropic。“ServiceNow 选择 Claude 作为 ServiceNow Build Agent 的默认模型,并向 29,000 多名员工推广 Claude Code,将销售人员的准备时间缩短了 95%。”2026年1月。 ↩

  78. IT Brief Asia。“Xcode 26.3 引入原生 Claude Agent SDK 集成(与驱动 Claude Code 的是同一套 harness),可直接在 Xcode 中使用 subagents、后台任务和 plugins。”2026年1月。 ↩

  79. Anthropic。“隆重推出 Claude Opus 4.6。”2026年2月5日。1M token 上下文(测试版)、128K 最大输出、自适应思考、effort 控制、agent teams、Terminal-Bench 2.0 最高分、GDPval-AA 领先 GPT-5.2 144 Elo、发现 500 多个零日漏洞。每百万 token $5/$25。另请参阅 TechCrunch、CNBC、Anthropic 定价。 ↩↩↩↩↩

  80. GitHub 发布记录。“v2.1.32:支持 Opus 4.6、agent teams 研究预览版、自动记忆记录、‘从此处开始总结’(Summarize from here)、自动加载 –add-dir 中的 skills、skill 字符预算随上下文窗口缩放、修复 bash heredoc 中 JS 模板字面量的问题、修复泰语/老挝语渲染问题。”2026年2月。 ↩↩

  81. Dev Genius。“Claude Code 异步 hooks:是什么以及何时使用。通过 async: true,hooks 现在可以在后台运行,而不会阻塞 Claude Code 的执行。”2026年1月25日。 ↩

  82. Anthropic Engineering。“让 Claude Code 更安全、更自主。”沙箱使用操作系统级原语(macOS seatbelt、Linux bubblewrap)。已在 github.com/anthropic-experimental/sandbox-runtime 开源。2026年1月。 ↩

  83. GitHub 博客。“Claude 和 Codex 现已在 GitHub 上公开预览。”2026年2月4日。另见:GitHub 博客。“Claude Opus 4.6 现已面向 GitHub Copilot 正式推出。”2026年2月5日。 ↩↩

  84. Claude Code 文档。“编排由多个 Claude Code 会话组成的团队。”2026年2月5日。Boris Cherny:“现已推出:Teams,即 Claude Code 中的 Agent Swarms。”另请参阅 Lydia Hallie。“Claude Code 现已支持 agent teams(研究预览版):主导 agent 可以将任务委派给多个队友,它们并行开展研究、调试和构建,同时相互协调。” ↩↩

  85. GitHub 发布记录。“v2.1.33:TeammateIdle 和 TaskCompleted hook 事件、Task(agent_type) 子 agent 限制语法、agents 的 memory frontmatter、skill 描述中显示 plugin 名称。修复:tmux agent 队友会话、agent teams 计划警告、扩展思考中断、API 代理 404 回退、WebFetch 的代理设置、/resume XML 标记。VSCode:OAuth 的远程会话、会话选择器中显示 git 分支。”2026年2月。 ↩↩

  86. GitHub 发布记录。“v2.1.36:Opus 4.6 现已支持快速模式。”2026年2月7日。Simon Willison。“Claude:使用快速模式加快响应速度。”快速模式定价:标准费率的 6 倍(Opus 4.6 输入 ≤200K 时每百万 token $30/$150;输入 >200K 时为 $60/$225)。首发促销(五折优惠)持续至 2026年2月16日。v2.1.37:修复了启用 /extra-usage 后 /fast 无法立即使用的问题。Anthropic 定价。 ↩↩↩↩

  87. GitHub 发布记录。“v2.1.34:修复了 agent teams 设置在渲染之间发生变化时的崩溃问题。修复了启用 autoAllowBashIfSandboxed 时,被排除在沙箱之外的命令可能绕过 Bash 询问权限规则的漏洞。”2026年2月6日。 ↩↩

  88. GitHub 发布记录。“v2.1.38:修复了 VS Code 终端滚动到顶部的回归问题、Tab 键斜杠命令排队、环境变量包装器的 bash 权限匹配、非流式模式下工具调用之间文本消失、VS Code 中恢复时出现重复会话等问题。改进了 heredoc 分隔符解析以防止命令走私。沙箱模式下禁止写入 .claude/skills。”2026年2月10日。v2.1.39:提升了终端渲染性能,修复了致命错误被吞掉、会话关闭后进程挂起、终端边界处字符丢失的问题。 ↩↩↩

  89. Claude Code 文档。“Hooks 参考:基于提示词的 hooks、基于 agent 的 hooks、hook 环境变量($CLAUDE_PROJECT_DIR、$CLAUDE_ENV_FILE)、PreToolUse 的 hookSpecificOutput 格式。”2026年2月。Claude Code 文档。“创建自定义 subagents:–agents CLI 标志、disallowedTools、maxTurns、mcpServers、delegate 权限模式。”2026年2月。 ↩↩↩↩↩↩

  90. Claude Code GitHub 发布记录。v2.1.41(2月13日):claude auth 子命令、Windows ARM64 支持、/rename 自动生成。v2.1.42(2月13日):/resume 标题修复、Bedrock/Vertex/Foundry 公告修复。 ↩↩↩

  91. Anthropic。“模型概览。”所有 Claude 3.5 和 Claude 4.x 模型默认支持 200K token 的输入上下文。Opus 4.6 在测试版中将其扩展至 1M token。 ↩

  92. Claude Code 文档。“Claude Code 入门。”系统要求:macOS 10.15+、Ubuntu 20.04+/Debian 10+、Windows 10+(WSL 或 Git Bash)、至少 4 GB 内存、可用的互联网连接。 ↩

  93. Anthropic。“Claude Sonnet 4.6。”2026年2月17日。Claude 开发者平台发布说明。“Sonnet 4.6:改进的 agentic 搜索、更少的 token 消耗、扩展思考、1M 上下文(测试版)。claude.ai 上的默认模型。Sonnet 4.5 转为旧版模型。”模型 ID:claude-sonnet-4-6。Anthropic 模型概览。“64K 最大输出,知识截止:可靠至 2025年8月 / 训练至 2026年1月。” ↩↩↩

  94. Claude Code GitHub 发布记录。v2.1.43:修复 AWS 身份验证刷新 3 分钟超时、修复 .claude/agents/ 的虚假 markdown 警告、修复 Vertex/Bedrock 的 structured-outputs 测试版请求头。v2.1.44:修复深层嵌套目录的 ENAMETOOLONG 错误、修复身份验证刷新错误。 ↩

  95. Claude Code GitHub CHANGELOG。v2.1.45(2月17日):支持 Sonnet 4.6、spinnerTipsOverride 设置、SDKRateLimitInfo/SDKRateLimitEvent 类型、修复 Agent Teams 在 Bedrock/Vertex/Foundry 上的问题、修复沙箱临时文件问题。v2.1.46(2月18日):Claude Code 中支持 claude.ai MCP 连接器、修复 macOS 上的孤儿进程问题。v2.1.47(2月18日):Ctrl+F 终止后台 agents、Stop/SubagentStop hooks 中新增 last_assistant_message、chat:newline 键绑定、statusline 新增 added_dirs 字段、/rename 设置终端标签页标题、恢复选择器显示 50 个会话、启动速度提升约 500ms、内存优化、修复 CJK 对齐问题、修复计划模式压缩问题、修复 Edit 工具 Unicode 问题、大量 Windows 修复。 ↩↩↩↩

  96. Claude Code GitHub CHANGELOG。v2.1.49(2月19日):--worktree(-w)标志、用于 subagents 的 isolation: "worktree"、代理定义的 background: true、ConfigChange hook 事件、MCP OAuth 升级认证(step-up auth)、SDK 的 supportsEffort/supportedEffortLevels/supportsAdaptiveThinking 字段、CLAUDE_CODE_SIMPLE 纳入 Edit 工具、移除 Sonnet 4.5 1M 以换用 Sonnet 4.6、WASM 内存修复、权限限制原因提示。v2.1.50(2月20日):WorktreeCreate/WorktreeRemove hooks、LSP 服务器的 startupTimeout、claude agents CLI 命令、CLAUDE_CODE_DISABLE_1M_CONTEXT 环境变量、Opus 4.6 快速模式支持完整 1M 上下文、CLAUDE_CODE_SIMPLE 禁用 MCP/hooks/CLAUDE.md、VSCode /extra-usage、代理团队内存泄漏修复、LSP 诊断泄漏修复、Linux glibc < 2.30 修复,以及多项内存优化。 ↩↩↩↩↩

  97. Cyber Unit。“Claude Code Security:企业应了解的 Anthropic AI 驱动漏洞扫描器。”2026年2月20日。以有限研究预览形式面向 Enterprise、Team 及开源维护者提供。Anthropic。“Claude Code Security 扫描代码库中的安全漏洞,并提出有针对性的补丁供人工审查。” ↩↩

  98. GitHub Releases。“v2.1.51(2月24日):claude remote-control 子命令、用于 HTTP hook 安全的 allowedEnvVars、HTTP hooks 经由沙箱代理、超过 50K 字符的工具结果持久化到磁盘、BashTool 跳过登录 shell、插件 npm 注册表/版本固定、/model 人类可读标签、SDK 调用方身份环境变量、statusLine/fileSuggestion 工作区信任。”2026年2月24日。Claude Code 文档。“Agent Teams:队友的计划审批、TeammateIdle/TaskCompleted 质量 hooks。” ↩↩↩↩↩↩↩↩↩

  99. GitHub Releases。“v2.1.52–v2.1.56(2月24–25日):VS Code Windows 崩溃修复、UI 闪烁修复、批量终止 agent 的汇总通知、Remote Control 过期会话清理、–worktree 首次启动修复、Windows 上的 BashTool EINVAL、Windows ARM64/WASM 解释器崩溃修复。”2026年2月25日。Claude Code 文档。“团队配置:~/.claude/teams/{team-name}/config.json。任务列表:~/.claude/tasks/{team-name}/。任务依赖自动解除阻塞。Shift+Down 在队友间循环切换(回绕至 lead)。” ↩↩

  100. GitHub Releases。“v2.1.59(2月26日):Claude 自动将有用的上下文保存到自动记忆(通过 /memory 管理)。/copy 命令提供代码块的交互式选择器。改进了复合 bash 命令的‘始终允许’前缀建议。多 agent 会话的内存占用改进。修复 MCP OAuth 令牌刷新竞争条件。修复并发写入导致的配置文件损坏。”2026年2月26日。 ↩↩

  101. Anthropic。“Claude Code Remote Control:会话移动性功能,可从手机、平板或浏览器继续本地会话。加密隧道,原子化的会话状态传输。”2026年2月。GitHub Releases。“v2.1.58:将 Remote Control 扩展至更多用户。” ↩↩

  102. Check Point Research。“CVE-2025-59536:不受信任目录中的代码注入(已在 v1.0.111 修复)。CVE-2026-21852:通过项目加载流程的信息泄露(已在 v2.0.65 修复)。”2026年2月。 ↩↩

  103. Anthropic/GitHub 统计数据。“公开 GitHub 提交中有 4%(约每天 135,000 次)由 Claude Code 编写。13 个月内增长 42,896 倍。Anthropic 自身 90% 的代码由 AI 编写(Dario Amodei,2026年2月)。”2026年2月5日。 ↩↩

  104. GitHub Releases。“v2.1.63(2月28日):内置的 /simplify 与 /batch 斜杠命令、worktree 共享的项目配置与自动记忆、ENABLE_CLAUDEAI_MCP_SERVERS=false 退出选项、HTTP hooks 的 type: http 处理程序、/copy 的‘始终复制完整响应’选项、VSCode 会话重命名/移除、/clear 重置 skill 缓存、多项内存泄漏修复、REPL 桥接竞争条件修复。”2026年2月28日。 ↩↩↩↩↩↩

  105. GitHub 博客。“Claude 与 Codex 现已面向 Copilot Business 和 Pro 用户提供。”2026年2月26日。将 Claude 的可用范围从 Copilot Pro+ 和 Enterprise 扩展至所有付费 Copilot 层级。 ↩↩

  106. Claude Code 文档。“在 2.1.63 版本中,Task 工具已更名为 Agent。设置和 agent 定义中现有的 Task(...) 引用仍可作为别名使用。”2026年2月28日。 ↩↩

  107. GitHub Releases。“v2.1.51:托管设置——支持 macOS plist 和 Windows 注册表,用于企业部署。”2026年2月24日。 ↩↩

  108. CNBC。“Figma 与 Anthropic 合作推出集成 Claude Code 的 AI 功能。”2026年2月17日。 ↩↩

  109. GitHub Releases。“v2.1.68:Opus 4.6 在 Max/Team 上默认采用 medium effort,重新引入 ultrathink 作为 high effort,移除 Opus 4/4.1。v2.1.70:修复了使用 ANTHROPIC_BASE_URL 时的 API 400 错误、effort 参数错误、ToolSearch 之后的空响应,改进了压缩时的图像保留,以及 VS Code 的 spark 图标与 MCP 管理。”2026年3月。 ↩↩↩↩↩↩↩↩

  110. GitHub Releases。“v2.1.69:/claude-api skill、InstructionsLoaded hook 事件、hook 事件中的 agent_id/agent_type/worktree、${CLAUDE_SKILL_DIR}、/reload-plugins、sandbox.enableWeakerNetworkIsolation、includeGitInstructions 设置、remote-control 自定义名称、语音 STT 新增 10 种语言(共 20 种)、effort 级别显示、Ctrl+U 退出 bash、数字小键盘支持、Sonnet 4.5→4.6 自动迁移。70 余项 bug 修复。”2026年3月5日。 ↩↩↩↩↩↩↩

  111. TechCrunch。“Claude Code 推出语音模式功能。/voice 启用按住说话。逐步推出(初期约 5%)。”2026年3月3日。9to5Mac。“Anthropic 正逐步为 Claude Code 添加语音模式。” ↩↩↩↩↩

  112. GitHub Releases。“v2.1.71:用于重复执行提示的 /loop 命令、语音快捷键自定义、bash 自动批准允许列表扩展、stdin 冻结修复、CoreAudio 启动优化。”2026年3月7日。Threads/@boris_cherny。“Claude Code 2.1.0 已发布:/loop、shift+enter 换行、agent/skill frontmatter 中的 hooks。” ↩↩↩

  113. Anthropic 博客。“Claude Code 的 Code Review:多 agent PR 审查系统。并行派发 agent,交叉验证发现,按严重程度排序。每次审查 $15-25,约 20 分钟。54% 的 PR 收到实质性评论(此前为 16%),错误率低于 1%。面向 Team/Enterprise 的研究预览。”2026年3月9日。TechCrunch。“Anthropic 推出代码审查工具。” ↩↩↩↩↩

  114. GitHub Releases。“v2.1.72:支持 ANTHROPIC_BASE_URL 的工具搜索、/copy 中用于写入文件的 w 键、/plan 描述参数、ExitWorktree 工具、CLAUDE_CODE_DISABLE_CRON、扩展的 bash 允许列表(lsof/pgrep/tput/ss/fd/fdfind)、Agent 工具恢复 model 参数、简化的 effort 符号(○/◐/●)、/config 导航改进、包体积减少 510KB、VSCode URI 处理程序。”2026年3月10日。 ↩↩↩↩

  115. GitHub Releases。“v2.1.73:用于自定义提供商模型 ID 的 modelOverrides 设置(Bedrock/Vertex/Foundry)。弃用 /output-style(改用 /config)。Bedrock/Vertex/Foundry 上的默认 Opus 改为 4.6。中断后按上箭头可恢复提示并回退。/effort 在响应过程中可用。SSL 证书错误指引。Bug 修复:CPU 冻结、死锁、SessionStart hooks 触发两次。”2026年3月11日。 ↩↩↩

  116. GitHub Releases。“v2.1.74:/context 可操作建议。autoMemoryDirectory 设置。--plugin-dir 覆盖行为变更。CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 可配置超时。托管策略强制执行修复(ask 规则被用户 allow 绕过)。内存泄漏修复(流式缓冲区)。RTL 文本渲染修复。MCP OAuth 修复。”2026年3月12日。 ↩↩

  117. GitHub Releases。“v2.1.75:Max/Team/Enterprise 的 Opus 4.6 默认启用 1M 上下文窗口。/color 命令面向所有用户开放。提示栏显示会话名称。记忆文件的最后修改时间戳。权限提示中显示 hook 来源。语音模式激活修复。管道命令中的 Bash ! 修复。令牌估算多计修复。macOS 启动性能改进。破坏性变更:移除已弃用的 Windows 托管设置回退。”2026年3月13日。 ↩↩↩↩↩

  118. GitHub Releases。“v2.1.76:MCP elicitation 支持——MCP 服务器可在任务进行中通过交互式对话框(表单字段或浏览器 URL)请求结构化输入。新增 Elicitation 和 ElicitationResult hooks。-n/--name CLI 标志用于设置会话显示名称。worktree.sparsePaths 用于 monorepo 中的 git sparse-checkout。PostCompact hook。/effort 斜杠命令。会话质量调查(feedbackSurveyRate)。错误修复:延迟加载的工具在压缩后丢失输入 schema、计划模式重复审批、语音模式按键、自动压缩断路器(最多 3 次尝试)、通过 SSH 在 tmux 中的剪贴板复制、Remote Control 会话稳定性。”2026年3月14日。 ↩↩↩↩↩↩

  119. GitHub CHANGELOG。“v2.1.77:Opus 4.6 的默认最大输出 token 数提高到 64K,Opus 4.6 与 Sonnet 4.6 的上限提高到 128K。allowRead 沙箱文件系统设置。/copy N 复制倒数第 N 条回复。/fork 更名为 /branch。移除 Agent 工具的 resume 参数(改用 SendMessage)。SendMessage 自动恢复已停止的 agents。会话根据计划自动命名。后台 bash 任务达到 5GB 时被终止。claude plugin validate 检查 frontmatter 与 hooks。macOS 启动快约 60ms,--resume 快 45% 且内存减少约 100-150MB。安全:PreToolUse 的 allow 不再绕过 deny 规则。25+ 项错误修复。”2026年3月17日。 ↩↩↩↩↩

  120. GitHub Releases v2.1.78。“v2.1.78:StopFailure hook 事件、${CLAUDE_PLUGIN_DATA} 持久化 plugin 状态、agent frontmatter(effort/maxTurns/disallowedTools)、ANTHROPIC_CUSTOM_MODEL_OPTION、tmux 通知透传、逐行响应流式输出。安全:缺少沙箱依赖时显示可见警告。修复:超过 5MB 的大型会话截断、stop hook 无限循环、沙箱绝对路径、WSL2 语音、VS Code 中的 Homebrew PATH。”2026年3月17日。 ↩↩↩

  121. GitHub Releases v2.1.79。“v2.1.79:用于 API 计费认证的 --console 标志、/remote-control VS Code 命令、VS Code 中由 AI 生成的会话标题、CLAUDE_CODE_PLUGIN_SEED_DIR 支持多个目录、启动内存减少约 18MB、非流式 API 超时为 2 分钟、/resume 切换时触发 SessionEnd hooks。修复:-p 作为子进程时挂起、打印模式下的 Ctrl+C、/btw 输出错误、语音模式启动、企业版 429 重试。”2026年3月18日。 ↩↩

  122. GitHub Releases v2.1.80。“v2.1.80:statusline 脚本中的 rate_limits 字段、source: 'settings' plugin marketplace 来源、skills 的 effort frontmatter。Claude Code Channels 研究预览:通过 channel server plugins 和 --channels 标志将 Telegram/Discord 消息接入会话。修复 Git Bash 的 Windows PATH 继承问题。”2026年3月19日。 ↩↩↩

  123. GitHub Releases v2.1.83。“v2.1.83:managed-settings.d/ 插入式目录、CwdChanged/FileChanged hook 事件、sandbox.failIfUnavailable、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1、会话记录搜索、initialPrompt agent frontmatter、Ctrl+X Ctrl+E 外部编辑器别名、停止所有 agents 的快捷键改为 Ctrl+X Ctrl+K、TaskOutput 已弃用。35+ 项错误修复。”2026年3月25日。 ↩↩↩↩

  124. Auto mode for Claude Code。Anthropic,2026年3月24日。Auto Mode:基于分类器的权限系统,由一个独立的 Sonnet 4.6 模型在每个操作执行前进行审查。是 –dangerously-skip-permissions 更安全的替代方案。Team 计划率先推出,Enterprise 与 API 随后跟进。 ↩↩

  125. Claude Code Auto Mode 文档。Auto Mode 架构:只读操作和工作目录内的编辑自动批准,自定义规则优先解析,其余操作由分类器评估。自动拦截:curl|bash、强制推送 main、生产部署、大规模云资源删除、IAM 变更、向外部泄露数据。断路器:连续 3 次或累计 20 次拦截后暂停并转为手动模式。 ↩↩↩

  126. GitHub Releases v2.1.89。“v2.1.89:无头会话可推迟权限决策、MCP_CONNECTION_NONBLOCKING=true、自动压缩抖动循环检测、Bash 过期编辑警告、符号链接感知的 allow 规则。合并了 v2.1.88 的全部修复。”2026年3月31日。 ↩

  127. GitHub Releases v2.1.88。“v2.1.88:PermissionDenied hook、CLAUDE_CODE_NO_FLICKER=1、@ 自动补全中的具名 subagents、思考摘要默认关闭、/btw 可滚动视口。修复:提示缓存未命中、嵌套 CLAUDE.md 重复注入、StructuredOutput 50% 失败率、CJK/emoji 历史记录,35+ 项错误修复。”2026年3月30日。 ↩↩↩

  128. How Boris Uses Claude Code。Boris Cherny(Claude Code 创建者),2026年3月。72+ 条技巧,涵盖 /dream 记忆整合、/batch 并行迁移、/schedule 云端作业、/btw 旁路查询、worktrees、自定义 agents、auto mode 以及高级工作流。 ↩↩

  129. GitHub Releases v2.1.86。“v2.1.86:X-Claude-Code-Session-Id 请求头、Read 工具紧凑格式、auto mode 计划提示信息、skill 描述长度上限、@ 提及 token 缩减、排除 Jujutsu/Sapling、修复 2.1.85 之前会话的 –resume 问题,15+ 项错误修复。”2026年3月27日。v2.1.87(3月28日):修复 Cowork Dispatch 消息投递问题。 ↩

  130. GitHub Releases v2.1.85。“v2.1.85:hooks 的条件 if 字段、PreToolUse hooks 可满足 AskUserQuestion、headersHelper 的 MCP 环境变量、MCP OAuth RFC 9728、隐藏组织已禁用的 plugins、/loop 的时间戳标记、深度链接查询支持 5K 字符、修复超大对话的 /compact 问题。20+ 项错误修复。”2026年3月26日。 ↩↩

  131. GitHub Releases v2.1.84。“v2.1.84:PowerShell 工具(Windows 需手动启用)、TaskCreated hook 事件、WorktreeCreate HTTP hook 支持、ANTHROPIC_DEFAULT 模型能力环境变量、CLAUDE_STREAM_IDLE_TIMEOUT_MS、allowedChannelPlugins 托管设置、rules/skills 中的 paths: YAML glob 列表、MCP 描述 2KB 上限、空闲 75+ 分钟后的返回提示、token 计数采用 1.5m 格式、CJK 输入法修复。25+ 项错误修复。”2026年3月26日。 ↩↩↩

  132. GitHub Releases v2.1.81。“v2.1.81:用于脚本化 -p 调用的 --bare 标志(跳过 hooks、LSP、plugin 同步和 skill 目录遍历)。面向 channel servers 的 --channels 权限中继。助手会遵从‘不要记忆’的请求。”2026年3月20日。 ↩↩

  133. Claude Code Source Analysis: Bun Source Map Leak。2026年3月。由于已知的 Bun 构建缺陷在生产环境中附带了 source map,npm 包中的 .map 文件暴露了完整可读的源代码。社区分析了 yoloClassifier.ts(1,495 行)、bashSecurity.ts(2,592 行,23 项检查)、自动压缩断路器(每天浪费 25 万次 API 调用)、基于正则的挫败感检测,以及伴侣宠物系统。 ↩↩↩↩↩

  134. Claude Code Source Deep Dive: Architecture Internals。2026年3月。技术分析涵盖协调器模式(由系统提示驱动的多 agent 编排)、提示缓存中断检测(14 个向量,带粘性锁存)、反蒸馏防御(伪造工具注入、连接文本摘要化)、用于隐藏代号的 undercover 模式、KAIROS 自主 agent 原型,以及通过 Bun 的 Zig HTTP 栈实现的原生客户端证明。 ↩↩↩↩

  135. GitHub Releases v2.1.90。“v2.1.90:/powerup 交互式课程、auto mode 尊重用户明确设定的边界、修复 --resume 提示缓存回归、修复 PreToolUse JSON stdout 退出码 2 的问题、修复 PostToolUse 保存时格式化的问题、PowerShell 安全加固(4 个攻击向量)、SSE 线性时间流式处理、会话记录写入性能、DNS 缓存隐私。”2026年4月1日。 ↩↩

  136. GitHub Releases v2.1.91。“v2.1.91:MCP _meta[\"anthropic/maxResultSizeChars\"] 最高可达 500K、disableSkillShellExecution 设置、plugin bin/ 可执行文件、多行深度链接提示、Edit 工具支持更短的 old_string 锚点、改进的 /claude-api skill、修复会话记录链断裂问题。”2026年4月2日。 ↩↩↩

  137. GitHub Releases v2.1.92。“v2.1.92:forceRemoteSettingsRefresh 失败即关闭策略、交互式 Bedrock 设置向导、按模型和缓存命中细分的 /cost 明细、/release-notes 交互式选择器、Remote Control 主机名前缀、提示缓存过期的页脚提示、移除 /tag 和 /vim、Linux 沙箱 apply-seccomp 辅助程序、Write 工具对大文件的 diff 速度提升 60%。”2026年4月4日。 ↩↩↩↩↩↩↩↩

  138. Claude Code Buddy 终端宠物。2026年4月1日。/buddy 命令会启动一只电子宠物(Tamagotchi)风格的 ASCII 陪伴宠物。共18个物种(鸭、鹅、猫、兔、猫头鹰、企鹅、乌龟、蜗牛、龙、章鱼、美西螈、幽灵、机器人、史莱姆、仙人掌、蘑菇、胖墩、水豚)。5个稀有度等级。5项属性(DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK)。由账户 ID 哈希(Mulberry32)确定性生成。需要 Pro 订阅。最初在源代码泄露中被发现,于4月1日正式发布。 ↩↩

  139. Claude Mythos Preview — Project Glasswing。Anthropic,2026年4月7日。超越 Opus 4.6 的新一代前沿模型。仅限 Project Glasswing 合作伙伴(Apple、Amazon、Microsoft、Google、Linux Foundation 等)用于防御性网络安全。已发现数千个高危/严重级别的零日漏洞,包括存在27年之久的 OpenBSD TCP SACK 缺陷、存在16年的 FFmpeg H.264 漏洞,以及 FreeBSD NFS 远程代码执行漏洞(CVE-2026-4747)。通过 Claude Code 在隔离容器中运行。提供1亿美元使用额度,并向开源安全领域投入400万美元。由 Nicholas Carlini 领导。尚未普遍开放;计划面向安全专业人员推出“Cyber Verification Program”(网络安全验证计划)。另请参阅:TechCrunch、VentureBeat、Simon Willison。 ↩↩

  140. GitHub Releases v2.1.94。“v2.1.94:通过 Mantle 使用 Bedrock(CLAUDE_CODE_USE_MANTLE=1),API/Bedrock/Vertex/Foundry/Team/Enterprise 的默认 effort 级别从 medium 改为 high,紧凑的 Slack MCP 标头,UserPromptSubmit hooks 支持 hookSpecificOutput.sessionTitle,插件 skill 名称取自 frontmatter,429 速率限制提示,macOS 钥匙串登录修复,插件 hook 修复,滚动历史/渲染修复。”2026年4月7日。v2.1.96(4月8日):Bedrock 身份验证回归热修复。 ↩↩↩

  141. GitHub Releases v2.1.97。“v2.1.97:修复了 --dangerously-skip-permissions 在写入受保护路径后静默降级为 accept-edits 的问题。修复了 MCP HTTP/SSE 连接在重连时每小时泄漏约 50 MB 内存的问题。修复了 429 重试在约13秒内耗尽全部尝试次数的问题。NO_FLICKER 模式下的焦点视图切换(Ctrl+O)。refreshInterval 状态栏设置。Cedar 语法高亮。25 项以上的缺陷修复。”2026年4月8日。 ↩

  142. GitHub Releases v2.1.98。“v2.1.98:Google Vertex AI 设置向导、CLAUDE_CODE_PERFORCE_MODE、用于后台脚本的 Monitor 工具、--exclude-dynamic-system-prompt-sections、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB PID 命名空间隔离、CLAUDE_CODE_SCRIPT_CAPS 限制。Bash 安全修复:反斜杠转义标志绕过、复合命令绕过、环境变量前缀自动放行、/dev/tcp 与 /dev/udp 重定向拦截。”2026年4月9日。 ↩↩

  143. GitHub Releases v2.1.101。“v2.1.101:/team-onboarding 命令,默认信任操作系统 CA 证书存储(可用 CLAUDE_CODE_CERT_STORE=bundled 覆盖),/ultraplan 自动创建云端环境,改进的简洁模式重试,改进的焦点模式摘要,速率限制重试会显示触发的是哪项限制及其重置时间,对无法识别的 hook 事件的设置容错。”2026年4月10日。 ↩↩↩

  144. 推出 Claude Opus 4.7。Anthropic,2026年4月16日。新一代旗舰模型。定价:每百万 token 输入 $5/输出 $25(与 Opus 4.6 相同)。模型 ID:claude-opus-4-7。可在 Claude 各产品、API、Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 中使用。SWE-Bench:解决的生产任务数量是 Opus 4.6 的3倍。CursorBench:70%,而 4.6 为 58%。另请参阅 Claude 模型定价。 ↩↩↩↩↩↩↩

  145. Claude Opus 4.7 新特性。Anthropic 平台文档。1M token 上下文按标准 API 价格计费,不收取长上下文溢价。最大输出 128K。破坏性变更:扩展思考的 budget_tokens 已移除(仅支持自适应思考),temperature/top_p/top_k 设为非默认值时返回 400,思考内容默认省略。新分词器(token 数量约为原来的 1×–1.35×)。新增 xhigh effort 级别。任务预算测试版(标头 task-budgets-2026-03-13)。视觉:2,576 px / 3.75 MP,像素坐标 1:1。 ↩↩↩↩↩↩↩↩

  146. Claude Code CHANGELOG。v2.1.105 至 v2.1.112 的主要来源。v2.1.105(PreCompact hooks 可以阻止操作、monitors 插件清单、EnterWorktree 路径参数、/proactive 别名、skill 描述上限提高至 1536)。v2.1.107(思考提示时机)。v2.1.108(ENABLE_PROMPT_CACHING_1H、Session Recap//recap、模型可通过 Skill 工具调用内置斜杠命令、/undo 别名、/model 会话中途切换警告)。v2.1.109(扩展思考指示器)。v2.1.110(/tui//tui fullscreen、Remote Control 的推送通知工具、/focus 与 Ctrl+O 分离、autoScrollEnabled、--resume/--continue 可恢复已计划的任务、Remote Control 客户端可使用 /context//exit//reload-plugins、面向已禁用遥测用户的 Session Recap、TRACEPARENT/TRACESTATE 分布式追踪、Write 工具会在用户编辑了 diff 时告知模型、围绕 PermissionRequest hooks 与在编辑器中打开功能的安全加固)。v2.1.111(Opus 4.7 发布支持、xhigh effort、/effort 交互式滑块、Max 计划无需标志即可使用 Auto Mode、/less-permission-prompts、/ultrareview、“Auto (match terminal)” 主题、通过 CLAUDE_CODE_USE_POWERSHELL_TOOL 启用的 Windows PowerShell 工具、借助 glob 模式减少只读 Bash 权限提示、/setup-vertex 与 /setup-bedrock 改进、OTEL_LOG_RAW_API_BODIES)。v2.1.112(针对 Auto Mode 下 Opus 4.7“暂时不可用”问题的热修复)。另请参阅:GitHub 关于 Opus 4.7 正式发布的博客、Cyber Verification Program 申请表。 ↩↩↩↩↩↩↩↩↩↩↩↩

  147. Claude Code — 模型配置。各计划默认模型的权威来源(Max/Team Premium → Opus 4.7;Pro/Team Standard/Enterprise/API → Sonnet 4.6;Bedrock/Vertex/Foundry → Sonnet 4.5;Enterprise 与 API 于2026年4月23日改为 Opus 4.7)。涵盖 /effort 级别(Opus 4.7 为 low/medium/high/xhigh/max;Opus 4.6 与 Sonnet 4.6 为 low/medium/high/max)、effort 回退行为、自适应推理(Opus 4.7 仅使用自适应模式;CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 可让 4.6 恢复固定预算),以及各计划的扩展上下文规则(Max/Team/Enterprise:包含 Opus 1M;Pro:通过额外用量获得;API:完全可用)。Opus 4.7 需要 Claude Code v2.1.111 及以上版本。 ↩↩↩↩↩↩↩↩↩↩

  148. Anthropic — 定价。权威定价参考(2026年4月)。基础输入/输出费率:Opus 4.7 与 4.6 为每百万 token $5/$25;Sonnet 4.6 为 $3/$15;Haiku 4.5 为 $1/$5。提示缓存倍率:5分钟缓存写入 1.25×,1小时缓存写入 2×,缓存命中为基础输入价格的 0.1×。长上下文:“Claude Mythos Preview、Opus 4.7、Opus 4.6 和 Sonnet 4.6 均按标准价格提供完整的 1M token 上下文窗口”,即当前一代模型均不收取长上下文溢价。数据驻留(inference_geo="us"):Opus 4.6 及更新模型的所有 token 类别均按 1.1× 计费。Batch API:50% 折扣。 ↩↩↩

  149. 已被取代,仅为 Opus 4.6 时代保留;当前的快速模式事实请参阅 198。 Claude Code — 快速模式,依据2026年2月的文档记录。研究预览功能。仅限 Opus 4.6:“快速模式在 Opus 4.7 或其他模型上不可用。”输出速度提升约 2.5 倍,价格为基础价格的 6 倍(每百万 token 输入 $30/输出 $150)。启用 /fast 会自动将会话切换到 Opus 4.6;禁用后会话仍停留在 Opus 4.6。不适用于 Bedrock/Vertex/Foundry。需要额外用量;Team/Enterprise 需由管理员启用。可通过 CLAUDE_CODE_DISABLE_FAST_MODE=1 完全禁用。 ↩

  150. Claude Code CHANGELOG。v2.1.113(2026年4月17日):CLI 通过各平台的可选依赖启动原生 Claude Code 二进制文件,不再使用内置的 JavaScript;sandbox.network.deniedDomains 可屏蔽特定域名,即使 allowedDomains 的通配符原本会放行它们;全屏模式下,当选区扩展到可见区域边缘之外时,Shift+↑/Shift+↓ 会滚动视口;在多行输入中,Ctrl+A/Ctrl+E 移动到当前逻辑行的开头/结尾(readline 风格);Windows 上 Ctrl+Backspace 删除前一个单词;在 /loop 中按 Esc 可取消待触发的唤醒,并显示“Claude resuming /loop wakeup”消息;/extra-usage 现在可从 Remote Control(移动端/网页)客户端使用;/ultrareview 启动更快,检查项并行执行,启动对话框中显示 diffstat,并带有动画的启动状态;流式传输中途停滞的 subagents 会在 10 分钟后以明确的错误失败;首行为注释的 Bash 多行命令会在记录中显示完整命令(修复 UI 伪装问题);cd <current-directory> && git … 在无实际操作时不再弹出提示;macOS 上的 Bash(rm:*) 允许规则将 /private/{etc,var,tmp,home} 视为危险的删除目标;Bash 拒绝规则可匹配被 env/sudo/watch/ionice/setsid 及类似包装器包裹的命令;Bash(find:*) 允许规则不再自动批准 find -exec/-delete;通过 Bedrock Application Inference Profile ARN 使用 Opus 4.7 时不再返回 thinking.type.enabled is not supported 400 错误;此外还修复了 MCP 并发调用的超时处理、含管道符内联代码的 markdown 表格、撰写过程中会话回顾自动触发、Remote Control 的 subagent 流式传输与归档、SDK 图像块失败降级为文本,以及 dangerouslyDisableSandbox 绕过权限提示等问题。v2.1.114(2026年4月18日):单项修复,解决 agent-teams 团队成员请求工具权限时权限对话框崩溃的问题。 ↩↩↩↩↩↩↩

  151. Codex 与 Claude Code 的基准测试和能力数据来源(2026年4月)。 Opus 4.7 的数据来自 Anthropic:Introducing Claude Opus 4.7:SWE-bench Verified 87.6%,SWE-bench Pro 64.3%,Terminal-Bench 2.0 69.4%。GPT-5.4 的规格来自 OpenAI GPT-5.4 模型文档:2026年3月5日发布(快照 gpt-5.4-2026-03-05),默认上下文 272K / 长上下文模式 1.05M,最大输出 128K,每百万 token 输入 $2.50 / 缓存 $0.25 / 输出 $15,输入超过 272K 时适用 2×/1.5× 的长上下文倍率。GPT-5.4 的编码基准(官方)来自 Introducing GPT-5.4:SWE-bench Pro 57.7%,Terminal-Bench 2.0 75.1%;官方页面并未公布 SWE-bench Verified 成绩。GPT-5-Codex 的 SWE-bench Verified 基线 74.9% 来自 OpenAI 最初的 Codex 发布材料。GPT-5.2-Codex 和 GPT-5.3-Codex 的数据来自 OpenAI:Introducing GPT-5.3-Codex:GPT-5.2-Codex 为 SWE-bench Pro 56.4% / Terminal-Bench 2.0 64.0%;GPT-5.3-Codex 为 SWE-bench Pro 56.8% / Terminal-Bench 2.0 77.3%。GPT-5.2-Codex 的上下文窗口(400K / 最大输出 128K)来自 OpenAI gpt-5.2-codex 模型文档。Codex CLI 的执行模型(默认本地运行)来自 OpenAI Codex CLI 帮助文档;Codex Cloud 的容器沙箱则是另一套独立机制。Claude Code 的指令文件(CLAUDE.md + CLAUDE.local.md,不支持 AGENTS.md)来自 Anthropic 记忆功能文档。竞品对比格式已与 Builder.io:Codex vs Claude Code 和 DataCamp:Codex vs Claude Code 交叉核对。 ↩↩↩

  152. Claude Code CHANGELOG——v2.1.116(2026年4月20日)、v2.1.117(2026年4月22日)、v2.1.118(2026年4月23日)和 v2.1.119(2026年4月23日)的综合参考。v2.1.116:/resume 在 40MB 以上的会话中速度提升 67%;使用多个 stdio 服务器时 MCP 启动更快(resources/templates/list 推迟到首次 @ 提及时才加载);内联思考旋转指示器(“still thinking”、“thinking more”、“almost done thinking”);/config 搜索现在可匹配选项值;/doctor 可在对话轮次进行中打开;插件自动安装缺失的依赖;Bash 工具会显示 gh GitHub API 速率限制提示;设置中的 Usage 标签页立即显示,且在用量端点受速率限制时仍可用;通过 --agent 以主线程 agent 身份运行时,agent frontmatter 中的 hooks: 会触发;安全修复——沙箱自动允许不再绕过针对 /、$HOME 或其他关键根目录的 rm/rmdir 危险路径检查。(v2.1.116 所回退的 4 月 16 日系统提示词冗长度约束记录在 153 的事后分析中,而非 v2.1.116 的发布说明里。)v2.1.117:CLAUDE_CODE_FORK_SUBAGENT=1 在外部构建上启用分叉 subagents;通过 --agent 启动的主线程 agent 会话会加载 agent frontmatter 中的 mcpServers;/model 的选择在重启后仍然保留,即使项目固定了不同的模型,且启动头部会显示固定来源;/resume 提供陈旧会话的摘要;默认并发启动 MCP(本地 + claude.ai);在插件安装/更新/刷新/自动更新时强制执行 blockedMarketplaces/strictKnownMarketplaces;Advisor Tool 实验性功能带有标签、了解更多链接,以及启用时的启动通知;cleanupPeriodDays 的保留期清理覆盖 ~/.claude/tasks/、~/.claude/shell-snapshots/、~/.claude/backups/;OTel user_prompt 事件包含 command_name/command_source(自定义/MCP 名称会被脱敏,除非设置 OTEL_LOG_TOOL_DETAILS=1);cost.usage/token.usage/api_request/api_error 包含 effort 属性;原生 macOS/Linux 构建通过 Bash 工具以内嵌的 bfs/ugrep 取代 Glob/Grep;Pro/Max 用户在 Sonnet 4.6 和 Opus 4.6 上的默认 effort 现为 high(原为 medium);修复——Opus 4.7 会话曾按 200K 窗口而非原生 1M 计算 /context,导致过早自动压缩。v2.1.118:vim 可视模式(v)和可视行模式(V),支持选区、操作符和视觉反馈;/cost 和 /stats 合并为 /usage(保留原有输入快捷方式);通过 /theme 或 ~/.claude/themes/*.json 使用命名主题(插件可附带 themes/ 目录);hooks 可通过 type: "mcp_tool" 直接调用 MCP 工具;DISABLE_UPDATES 环境变量阻止所有更新途径,包括手动执行 claude update(比 DISABLE_AUTOUPDATER 更严格);WSL 通过 wslInheritsWindowsSettings 策略继承 Windows 端的托管设置;autoMode.allow/soft_deny/environment 中的 $defaults 哨兵值可在内置列表之外追加自定义规则;自动模式的“不再询问”选择加入;claude plugin tag 创建带版本校验的发布 git 标签。v2.1.119:/config 设置(主题、编辑器模式、详细输出)持久化到 ~/.claude/settings.json,并遵循项目/本地/策略的优先级;prUrlTemplate 设置将页脚的 PR 徽章指向自定义代码审查 URL 而非 github.com;CLAUDE_CODE_HIDE_CWD 在启动 logo 中隐藏工作目录;--from-pr 接受 GitLab MR、Bitbucket PR 和 GitHub Enterprise PR 的 URL;--print 遵循 agent 的 tools:/disallowedTools: frontmatter;--agent <name> 对内置 agent 遵循 permissionMode;PowerShell 工具命令在权限模式下自动批准(与 Bash 一致);PostToolUse/PostToolUseFailure hook 输入包含 duration_ms(工具执行时间,不含权限提示和 PreToolUse hooks);subagent 和 SDK 的 MCP 服务器重新配置会并行连接服务器;安全——blockedMarketplaces 正确执行 hostPattern 和 pathPattern 条目;OTel tool_result 和 tool_decision 事件包含 tool_use_id;tool_result 包含 tool_input_size_bytes;状态行的 stdin JSON 包含 effort.level 和 thinking.enabled;Vertex AI 上默认禁用工具搜索(通过 ENABLE_TOOL_SEARCH 选择启用)。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  153. 关于近期 Claude Code 质量问题报告的最新说明。Anthropic 工程事后分析,2026年4月23日。涵盖三项相互独立、已于4月20日(v2.1.116)解决的质量回退,并于4月23日为所有订阅用户重置了用量限额:(1)推理强度默认值——2026年3月4日由 high 改为 medium 以减少 UI 卡顿;在运营方反馈称用户更看重更高的智能水平而非 UI 流畅度后,于4月7日回退。影响 Sonnet 4.6 和 Opus 4.6。(2)提示缓存清除思考内容的缺陷——一项本应在每个空闲会话中仅清除一次思考内容的缓存优化,却在该会话的后续每一轮都清除了思考内容,导致遗忘、重复以及用量限额消耗加快。生效时间为3月26日至4月10日,已在 v2.1.101 中修复。影响 Sonnet 4.6 和 Opus 4.6。(3)系统提示冗长度约束——4月16日添加,用于应对 Opus 4.7 过于健谈的问题;据 Anthropic 所述,约 3% 的编码质量下降是在 Opus 4.6 和 Opus 4.7 上测得的(Sonnet 4.6 也受影响,但降幅较小);已于4月20日在 v2.1.116 中回退。Anthropic 声明的缓解措施:更全面的发布前评估套件、更严格的系统提示变更管控、对影响智能表现的变更强制进行代码审查,以及渐进式推出。 ↩↩↩↩

  154. Claude Code 发布说明——v2.1.121(2026年4月28日 00:31 UTC)与 v2.1.122(2026年4月28日 22:05 UTC)的合并参考。v2.1.121:alwaysLoad MCP 服务器配置选项(跳过工具搜索延迟加载);MCP 启动自动重试 3 次;claude plugin prune 与 --prune 级联;/skills 支持输入即筛选;PostToolUse 的 hookSpecificOutput.updatedToolOutput 由仅限 MCP 扩展至所有工具;.claude/skills/、.claude/agents/、.claude/commands/ 免于 --dangerously-skip-permissions 提示;Vertex AI 基于 X.509 证书的 Workload Identity Federation(mTLS ADC);SDK mcp_authenticate 的 redirectUri;OTel 在 LLM 请求 span 中新增 stop_reason、gen_ai.response.finish_reasons 和 user_system_prompt(受 OTEL_LOG_USER_PROMPTS 控制);/terminal-setup 启用 iTerm2 剪贴板访问,以便在 tmux 中使用 /copy;标签页标题遵循 language 设置;CLAUDE_CODE_FORK_SUBAGENT=1 扩展至非交互式 claude -p;升级后启动更快(发布说明启动页移除了“最近活动”面板);claude.ai 连接器针对相同上游 URL 去重。v2.1.122:ANTHROPIC_BEDROCK_SERVICE_TIER 环境变量(default/flex/priority)以 X-Amzn-Bedrock-Service-Tier 形式发送;/resume 支持跨 GitHub、GHE、GitLab、Bitbucket 按 PR URL 搜索;/mcp 显示隐藏的连接器并提示移除重复项,同时澄清浏览器授权后的未授权提示信息;OTel 新增 claude_code.at_mention 日志事件,用于 @ 提及解析;api_request/api_error 上的数值属性以数字形式输出(此前为字符串)。两个版本中的高价值修复:/usage 约 2GB 内存泄漏、图片密集型会话中多 GB 的 RSS 增长、--resume 跳过损坏的转录行以及大型外部构建会话崩溃修复、CWD 被删除/移动时的 Bash 恢复、Bedrock 在应用推理配置文件上启用思考的修复、结构化输出时 Vertex/Bedrock 拒绝 output_config 额外输入、ToolSearch 遗漏会话启动后才连接的非阻塞 MCP 工具、较新模型上的图片缩放上限由 2576→2000 px、bash 模式下的 !exit/!quit 不再终止 CLI、tmux/GNOME/Windows Terminal/Konsole 上的回滚缓冲区重复、格式错误的 hooks 条目不再使整个 settings.json 失效。 ↩↩↩↩↩↩↩↩↩↩↩↩

  155. Claude Code v2.1.123 发布说明。2026年4月29日 03:29 UTC。仅含一项缺陷修复:“修复了在设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 时 OAuth 身份验证陷入 401 重试循环而失败的问题。” ↩

  156. 2026年5月6日最新版本线的合并验证:Claude Code v2.1.126 发布说明、Claude Code v2.1.128 发布说明、Claude Code v2.1.129 发布说明、Claude Code v2.1.131 发布说明、Claude Code CHANGELOG,以及 @anthropic-ai/claude-code 的 NPM 包元数据。v2.1.126 为 /model 新增网关模型发现、claude project purge、OAuth 代码粘贴回退、技能激活 OTel、Windows 上 PowerShell 作为主 shell 的行为,并更改了 --dangerously-skip-permissions 的受保护路径提示。v2.1.128 为 --plugin-dir 新增 zip 支持、MCP 工具计数与零工具可见性、控制台认证 --channels,修复了 EnterWorktree,并修复了插件/缓存/MCP/会话相关问题。v2.1.129 新增 --plugin-url、CLAUDE_CODE_FORCE_SYNC_OUTPUT、CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE、skillOverrides、通过 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 选择启用的网关模型发现,以及插件清单 themes/monitors 验证警告。v2.1.131 修复了 Windows 上的 VS Code 扩展激活问题和 Mantle 端点身份验证;其发布说明未宣布其他命令或配置新增项。 ↩↩↩↩↩

  157. 提高 Claude 用量限额并与 SpaceX 达成算力协议。Anthropic,2026年5月6日。三项变化:(1)Pro、Max、Team 以及按席位计费的 Enterprise 方案的 Claude Code 五小时速率限制翻倍;(2)取消 Pro 和 Max Claude Code 账户的高峰时段缩减;(3)Claude Opus 模型的 API 速率限制“大幅”提高,公告页面附有按层级划分的表格。算力保障:Anthropic 获得 SpaceX“Colossus 1 数据中心的全部算力”——“一个月内新增超过 300 兆瓦的容量(超过 220,000 块 NVIDIA GPU)”。Anthropic 还表示有意与 SpaceX 合作开发“数吉瓦级的轨道 AI 算力”。 ↩↩

  158. 面向金融服务的智能体。Anthropic,2026年5月5日。十个开箱即用的智能体模板:路演材料构建器、财报审阅器、KYC 筛查器、月末结账器,以及另外六个。每个模板都以插件形式在 Claude Cowork 和 Claude Code 中提供,并作为 Claude Managed Agents 的 cookbook 提供。Microsoft 365 加载项:Excel、PowerPoint 和 Word 中的 Claude,支持跨应用上下文;Outlook 集成即将推出。数据连接器合作伙伴包括 Dun & Bradstreet、Fiscal AI、Financial Modeling Prep、Guidepoint、IBISWorld、SS&C IntraLinks、Third Bridge 和 Verisk。Moody’s MCP 应用:可在 Claude 内访问超过 6 亿家公司的信用评级和数据。Claude Cowork Dispatch:为分析师提供语音和文本任务分配。Opus 4.7 在 Vals AI Finance Agent 基准测试中得分 64.37%。 ↩↩

  159. Claude Code v2.1.132 发布说明。2026年5月6日。为 Bash 工具子进程新增 CLAUDE_CODE_SESSION_ID 环境变量(与传递给 hooks 的 session_id 一致)。新增 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 环境变量,用于退出全屏备用屏幕渲染器,将对话保留在终端原生回滚缓冲区中。更新 /tui fullscreen 启动横幅,说明渲染器的更多优势(更低的内存占用、鼠标支持、选中即复制)。另有 20 余项修复,涵盖终端/输入处理(SIGINT、SSH 断连、终端模式、光标定位)、文本编辑与粘贴(emoji 和字素损坏、vim 操作符、转义序列、以 / 开头的粘贴后文本被吞)、UI/渲染(休眠后全屏模式空白、滚动速度、滚轮处理、自动补全弹窗)、会话管理(--resume 失败、emoji 截断、计划模式 --permission-mode 标志)、命令工具(/usage、/terminal-setup、/effort、/status、/login、/upgrade)、MCP 服务器集成(工具获取、授权显示、非协议数据、stdio MCP 服务器内存无限增长、tools/list 重试)、平台相关问题(Windows Terminal、JetBrains IDE、macOS 键盘、X11 Linux),以及设置 ENABLE_PROMPT_CACHING_1H 时 Bedrock+Vertex 的 400 错误。 ↩↩↩

  160. Claude Code v2.1.133 发布说明。2026年5月7日。新增 worktree.baseRef 设置(fresh | head)——并且根据发布说明:“默认值 fresh 会将 EnterWorktree 的基准改回 origin/<default>(自 2.1.128 起一直是本地 HEAD)——设置 worktree.baseRef: \"head\" 即可在新 worktree 中保留尚未推送的提交。”hooks 现在可通过 effort.level JSON 输入字段和 $CLAUDE_EFFORT 环境变量获取当前生效的 effort 级别;Bash 工具命令同样可以读取 $CLAUDE_EFFORT。新增 sandbox.bwrapPath 和 sandbox.socatPath 托管设置(Linux/WSL),用于指定自定义的 bubblewrap 和 socat 二进制文件位置。新增管理员层级的 parentSettingsBehavior 键('first-wins' | 'merge'),可让 SDK managedSettings(父层级)参与策略合并。修复了 subagents 无法通过 Skill 工具发现项目、用户或插件 skills 的问题。其他修复:并行会话中刷新令牌后出现 401 的竞态条件、驱动器根目录允许规则的作用域、MCP OAuth 代理与 mTLS 支持、Remote Control 的停止/中断操作能够完成取消、跨会话 /effort 泄漏,以及 --help 中列出 --remote-control。 ↩↩↩↩↩↩↩

  161. 在 Excel、PowerPoint、Word 和 Outlook 中与 Claude 协作。Anthropic,2026年5月7日。适用于 Excel、PowerPoint 和 Word 的 Claude 已正式发布;适用于 Outlook 的 Claude 面向所有付费方案开放公测。支持跨应用联动(“在 Excel 中调整一个假设,PowerPoint 中的图表和 Word 备忘录中的数字也会自动更新”)。Outlook 新增收件箱分类功能(“Claude……会按需要您回复的邮件、可以代您起草的邮件以及无关噪音对消息进行分类”)。所有付费方案的 Mac 和 Windows 用户均可使用。 ↩↩↩↩↩↩

  162. Claude Code v2.1.137 至 v2.1.139 发布说明。v2.1.137(2026年5月9日):“[VSCode] 修复了扩展在 Windows 上无法激活的问题。”v2.1.138(2026年5月9日):“内部修复。”v2.1.139(2026年5月11日):Agent View(claude agents)、/goal、命令 hook 的 args: string[]、PostToolUse 的 continueOnBlock、面向 MCP stdio 服务器的 CLAUDE_PROJECT_DIR、插件命令中的 ${CLAUDE_PROJECT_DIR} 插值、--print 模式下的 OpenTelemetry 活跃时间修复,以及相关的可靠性修复。另请参阅:Agent View 文档和 Goal 文档。 ↩↩↩

  163. Claude Code v2.1.140 发布说明。2026年5月12日。在 agent hook 输入中新增 subagent_type,并修复了以下问题:设置变更时 ConfigChange hooks 不触发;未配置其他设置时 disableAllHooks 无法禁用 hooks;allowManagedHooksOnly 与 disableAllHooks 在不同设置层级间无法正确组合;hooks 返回结果时权限对话框意外显示环境变量;设置更新后自定义样式被重置;Windows Git Bash 的原生包解析回退;以及 /scroll-speed 不生效。 ↩

  164. Claude Code v2.1.141 发布说明。2026年5月13日。新增:hook JSON 输出中的 terminalSequence,用于桌面通知、窗口标题和响铃;用于通过 HTTPS 克隆插件源的 CLAUDE_CODE_PLUGIN_PREFER_HTTPS;用于工作负载身份联合工作区范围限定的 ANTHROPIC_WORKSPACE_ID;用于 Agent View 目录筛选的 claude agents --cwd <path>;以及 /feedback 附加最近 24 小时或 7 天会话的选项。2026年5月14日的当前会话验证:claude --version 返回 2.1.141 (Claude Code),npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回的最新版本为 2.1.141。 ↩↩

  165. Claude Code v2.1.142 发布说明和 Claude Code CHANGELOG。2026年5月14日。为 claude agents 新增后台会话配置标志;Fast 模式默认切换至 Opus 4.7,并提供 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 作为固定旧模型的覆盖选项;当不存在 skills/ 目录时,将插件根目录下的 SKILL.md 文件作为 skills 呈现;在插件详情中显示插件提供的 LSP 服务器;在 /web-setup 中替换现有 GitHub App 连接前发出警告;修复远程 HTTP/SSE MCP 服务器的 MCP_TOOL_TIMEOUT;并解决了后台会话、守护进程、Agent View、插件缓存、插件建议以及响应式压缩方面的可靠性问题。2026年5月15日的当前会话验证:claude --version 返回 2.1.141 (Claude Code),npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回的最新版本为 2.1.142,time.modified 为 2026-05-14T22:54:49.491Z。 ↩

  166. Claude Code v2.1.143 发布说明、Claude Code 更新日志和 Claude Code CHANGELOG。2026年5月15日。新增插件依赖强制检查、插件上下文开销预估、worktree.bgIsolation: "none"、Agent View 派发标志的一致性、PowerShell 策略行为,以及针对 stop-hook 循环、/goal 评估器时机、后台会话、凭据启动、Agent View、颜色环境变量处理和插件提供的 agents 的可靠性修复。2026年5月18日的当前会话验证:claude --version 返回 2.1.142 (Claude Code),npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回的最新版本为 2.1.143,time.modified 为 2026-05-18T19:57:55.006Z。 ↩

  167. Claude Code v2.1.144 发布说明、Claude Code 更新日志和 Claude Code CHANGELOG。2026年5月19日。新增后台会话的 /resume 支持、后台 subagent 时长通知、插件最近更新时间显示、/model 的当前会话/默认行为、/usage-credits,以及针对启动时网络超时、终端显示错乱、macOS 后台会话启动、图片扩展名不匹配、MCP 分页与不支持的图片 MIME 类型、Agent View 交互、后台会话分离/恢复和 skill 重新加载导致文件描述符耗尽的可靠性修复。2026年5月19日的当前会话验证:claude --version 返回 2.1.144 (Claude Code),npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回的最新版本为 2.1.144,time.modified 为 2026-05-19T17:40:52.832Z。 ↩

  168. Claude Code v2.1.145 发布说明、Claude Code 更新日志和 Claude Code CHANGELOG。2026年5月19日。新增 claude agents --json、状态栏 JSON 中的 GitHub 仓库/PR 字段、更丰富的安装前插件发现、Agent View 等待输入标签页计数、全屏斜杠命令/@ 提及的鼠标交互、Stop/SubagentStop 的 background_tasks 和 session_crons 输入字段、OTEL 的 agent_id 和 parent_agent_id span 属性,并修复了权限提示绕过、MCP 提示验证错误、加载指示器/耗时显示冻结、Windows 跨项目恢复提示、Agent View 语音按键通话、任务列表排序、过期的市场横幅、PR 徽章刷新、Agent Teams 中非 ASCII 的队友名称、/review Classic Projects 错误、claude plugin validate、skill context: fork 循环以及 Read 工具读取过大内容失败等问题。2026年5月19日的当前会话验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回的最新版本为 2.1.145,time.modified 为 2026-05-19T22:20:44.083Z。 ↩

  169. Claude Code v2.1.147 发布说明与Claude Code CHANGELOG。2026年5月21日。新增默认关闭的 Workflow 工具,用于确定性的多智能体编排(CLAUDE_CODE_WORKFLOWS=1),新增可固定的 Agent View 后台会话,并以 /code-review [effort] --comment 取代 /simplify。此版本加固了 REPL 与 Workflow 沙箱;改进了自动更新器诊断、大型 diff 渲染和提示历史去重;并修复了企业登录限制、PowerShell 输出/规则、MCP 分页的 resources/list、resources/templates/list 与 prompts/list、Agent View 的 CJK 行渲染、粘贴文本的传递、插件组件计数、hook 条件匹配、无头/SDK 模式下的未知斜杠命令,以及图片被剥离引发的循环问题。2026年5月21日的当前会话验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回最新版本 2.1.147,time.modified 为 2026-05-21T20:38:35.053Z。 ↩↩

  170. Claude Code v2.1.148 发布说明、Claude Code v2.1.149 发布说明、Claude Code v2.1.150 发布说明与Claude Code CHANGELOG。v2.1.148(2026年5月22日)修复了一个 Bash 工具回归问题,该问题导致部分用户的每条命令都返回退出码 127。v2.1.149(2026年5月22日)新增 /usage 按类别的限额用量显示、/diff 键盘滚动、GFM 任务列表复选框渲染,以及企业版 allowAllClaudeAiMcps;同时修复了 PowerShell 权限绕过与权限分析缺口、git worktree 沙箱写入允许列表的作用范围、Bash find 在 macOS 上耗尽 vnode、托管设置导致的启动冻结、/ultraplan 与远程会话的无变更捕获失败、含空格的 otelHeadersHelper 路径、状态栏显示来自 skill/agent frontmatter 的 effort 级别、Ctrl+O 转录跟踪、/insights、Remote Control 会话重命名同步,以及 /feedback 在压缩前的上下文捕获。v2.1.150(2026年5月23日)仅为内部基础设施变更。2026年5月24日的当前会话验证:本地 claude --version 返回 2.1.144 (Claude Code),而 npm view @anthropic-ai/claude-code version dist-tags.latest time.modified --json 返回最新版本 2.1.150,time.modified 为 2026-05-23T04:03:10.243Z;GitHub 最新发布返回 v2.1.150,发布于 2026-05-23T04:03:51Z。 ↩

  171. Claude Code v2.1.172 发布说明、Claude Code v2.1.173 发布说明与Claude Code Changelog(规范版)。2026年6月10日至11日。v2.1.172(6月10日):subagent 可以生成自己的 subagent,最多 5 层(递归委派);未设置 AWS_REGION 时,AWS Bedrock 区域会从 ~/.aws 读取,/status 会显示解析出的来源;/plugin 新增市场搜索栏;claude_code.lines_of_code.count OTEL 指标新增 model 属性。修复:无额度时 1M 上下文会话卡住、图片处理错误、后台 subagent 卡住的状态、模型选择器/限制,以及团队记忆召回。v2.1.173(6月11日,UTC):带有 [1m] 后缀的 Fable 5 模型名称会被自动规范化/去除(Fable 5 默认已包含 1M 上下文,该后缀仅对 Opus/Sonnet 有意义,在此属于冗余);另有一项 Windows 修复,解决启动时误报“sandbox dependencies missing”警告的问题。验证:GitHub 发布 v2.1.172 与 v2.1.173,以及 code.claude.com/docs/en/changelog 上的规范 changelog 均确认 v2.1.173 为最新版本。 ↩↩↩

  172. Claude Code v2.1.174 发布说明、Claude Code v2.1.175 发布说明、Claude Code v2.1.176 发布说明与Claude Code Changelog(规范版)。2026年6月12日。v2.1.174: wheelScrollAccelerationEnabled 设置(在全屏模式下禁用鼠标滚轮滚动加速);/model 选择器将 Default 所解析到的模型系列单独显示为一行(Max/Team Premium/Enterprise 及按量付费 API 上为 Opus,Pro/Team 上为 Sonnet);当 ANTHROPIC_DEFAULT_SONNET_MODEL 固定为另一个 Sonnet 时,/model 选择器不再显示硬编码的 Sonnet 标签;VSCode 的 Account & usage 对话框(/usage)新增归因信息,显示过去 24 小时或 7 天内的缓存未命中、长上下文、subagents,以及按 skill/agent/plugin/MCP 的细分;修复了 Bedrock GovCloud(us-gov-*)推理配置前缀被推导为 global 而非 us-gov、后台会话继承另一会话的 ANTHROPIC_* 提供商环境变量、git commit 共同作者的模型名称归因、/advisor 预选了被阻止的 advisor 模型、skill 热重载重新发送整个列表,以及企业用量计费账户显示 Fable 5“正在消耗用量额度”横幅的问题。v2.1.175: enforceAvailableModels 托管设置——启用后,availableModels 允许列表也会约束 Default 模型(若 Default 解析到不被允许的模型,则回退到第一个允许的模型),且用户/项目设置不能再扩大托管的 availableModels 列表。v2.1.176: 会话标题以对话所用语言生成(设置 language 可固定为特定语言);footerLinksRegexes 设置,用于在页脚行中显示正则匹配的链接徽章(用户或托管设置);来自 awsCredentialExport 的 Bedrock 凭据将缓存至其 Expiration 为止,而非固定一小时;availableModels 的强制执行得到加固,别名选择无法再通过 ANTHROPIC_DEFAULT_*_MODEL 重定向到被阻止的模型,/fast 也会拒绝切换到允许列表之外的模型;对于没有 Opus 4.8 的组织,自动模式会从 Fable 5 回退到可用的最佳 Opus;针对 Read/Edit/Write 工具路径的 hook if 条件(Edit(src/**)、Read(~/.ssh/**)、Read(.env))现已正确匹配;修复 Linux 沙箱在设置文件为符号链接时的启动问题;/copy 与鼠标选择复制在通过 SSH 的 tmux 中可到达系统剪贴板;/cd 与 worktree 移动不再报告上一目录的 git 分支;另有大量 Remote Control、claude agents 与后台会话修复。2026年6月15日(PST)的当前会话验证:GitHub 发布 v2.1.174–v2.1.176 以及 code.claude.com/docs/en/changelog 上的规范 changelog 均确认 v2.1.176 为最新版本。 ↩↩↩↩↩↩

  173. Claude Code v2.1.178 发布说明与v2.1.179 发布说明,以及Claude Code Changelog(规范版)。2026年6月15日至16日。v2.1.178: Tool(param:value) 权限规则语法,可用 * 通配符匹配工具输入参数(例如 Agent(model:opus));嵌套 .claude/skills 中的 skills 会在处理该目录下的文件时加载,名称冲突时以 <dir>:<name> 区分;嵌套 .claude/ 中的 agents、workflows 与 output-styles 在冲突时解析为最接近当前工作目录的那个(项目范围的 workflow 保存会定位到最近的已有 .claude/workflows/);自动模式在启动 subagent 之前先用分类器评估其生成请求;压缩现在会在过载/可用性错误时遵循 --fallback-model 链;subagent disallowedTools 中的 MCP 服务器级规范(mcp__server、mcp__server__*、mcp__*)不再被静默忽略;/doctor 采用扁平树状布局;/bug 要求填写描述;workflow 提示关键字仅在明确的短语上触发;另有大量 subagent 转录、Remote Control、认证/凭据以及 claude agents 修复。v2.1.179: 在流式传输中途连接断开时保留部分响应;修复 WSL2 鼠标滚轮滚动(v2.1.172 回归)、沙箱 denyRead/allowRead glob 作用于大型目录树时导致 Linux 上 Bash 工具描述过于庞大、反馈调查的个位数捕获、欢迎屏幕促销信息堆叠、Ctrl+O 查看 subagent 转录,以及远程后台任务与插件加载的可靠性问题。v2.1.177: 仅为 CHANGELOG.md/feed.xml 的例行更新。2026年6月17日(PST)的当前会话验证:GitHub 发布 v2.1.177–v2.1.179 以及规范 changelog 均确认 v2.1.179 为最新版本。 ↩↩↩↩↩

  174. Claude Code v2.1.181 发布说明与v2.1.183 发布说明,以及Claude Code 更新日志(权威版本)。2026年6月17日至19日。v2.1.181:/config key=value 可直接在提示符中设置任意配置项(例如 /config thinking=false),适用于交互模式、-p 以及 Remote Control;sandbox.allowAppleEvents 为可选启用的设置项,允许沙箱命令在 macOS 上发送 Apple Events;CLAUDE_CLIENT_PRESENCE_FILE 环境变量指向一个标记文件,在您正在使用这台机器时抑制移动端推送通知;内置的 Bun 升级至 1.4;长段落改为逐行流式输出;思考过程中 API 连接中断会自动重试;subagent 面板空闲 30 秒后自动隐藏,且最多显示 5 行。v2.1.183:自动模式会拦截破坏性 git 命令(git reset --hard、git checkout -- .、git clean -fd、git stash drop),除非您明确要求丢弃工作;拦截对本会话中并非由代理创建的提交执行 git commit --amend;拦截 terraform destroy/pulumi destroy/cdk destroy,除非您明确指定了相应的 stack;已弃用/自动更新模型的警告会在 -p 模式下以及针对 agent frontmatter 中指定的模型输出到 stderr;attribution.sessionUrl 设置可从提交和 PR 中省略 claude.ai 会话链接;/config --help 会列出简写键;/config 界面支持 Enter/Space 切换,Esc 保存并关闭;移除了启动时的“setup issues”提示行。(v2.1.180 和 v2.1.182 未发布。)当前会话验证(2026年6月19日,PST):GitHub releases 与权威更新日志确认 v2.1.183 为最新版本。 ↩↩↩

  175. Claude Code v2.1.185 发布说明与v2.1.186 发布说明,以及Claude Code 更新日志(权威版本)。2026年6月20日至22日。v2.1.186:claude mcp login <name> 和 claude mcp logout <name> 可直接从 CLI 登录/登出 MCP 服务器,无需打开 /mcp,并支持 --no-browser stdin 重定向以便通过 SSH 完成认证;! bash 命令现在会触发 Claude 自动响应其输出("respondToBashCommands": false 可保留之前仅作为上下文的行为);Agent(type) 拒绝规则与 Agent(x,y) 允许类型限制现已对具名 subagent 的生成强制执行;后台 subagent 的权限提示现会显示在主会话中(标明发起请求的代理;按 Esc 仅拒绝该工具),不再自动拒绝;主回合结束后,后台代理运行期间 Esc/Ctrl+C 仍可响应;/review <pr> 使用与 /code-review medium 相同的审查引擎;/workflows 代理详情新增状态筛选(按 f);/plugin 的 Installed 页面新增 Skills 区块;新增 teammateMode: "iterm2"(当自动模式找不到 it2 CLI 时会给出警告);配置了 awsAuthRefresh 时,/login 新增“Claude Platform on AWS - refresh credentials”选项;skill frontmatter 的 display-name/default-enabled/fallback/metadata.* 接受 kebab-case、snake_case 和 camelCase,且格式错误的 SKILL.md YAML 会以空元数据加载正文,而不再静默失败;claude mcp get/claude mcp remove 在拼写错误时会提示最接近的已配置服务器名称;当 MEMORY.md 索引接近大小上限时会提醒代理进行压缩;CLAUDE_CODE_MAX_RETRIES 上限为 15(无人值守会话请使用 CLAUDE_CODE_RETRY_WATCHDOG)。修复:休眠唤醒后流式传输出现“Content block not found”/JSON 解析错误;退出时 subagent 转录的滚动溢出到主转录中;后台任务预览闪现原始工具名称;权限门控关闭时的 Chrome 标签页组隔离;后台摘要重复;Agent(type) 拒绝规则/Agent(x,y) 允许类型对具名生成未生效;~~strikethrough~~ 渲染为字面波浪号;Workflow agent({schema}) subagent 在 schema 校验反复失败时无限循环(现在 5 次后中止)。v2.1.185:流式停滞提示现改为“Waiting for API response · will retry in …”(原为“No response from API · Retrying in …”),并在静默 20 秒后触发,而非 10 秒。v2.1.184 未发布。当前会话验证(2026年6月23日,PST):GitHub releases v2.1.185–v2.1.186 与 code.claude.com/docs/en/changelog 的权威更新日志确认 v2.1.186 为最新版本。 ↩↩↩

  176. Claude Code v2.1.187 发布说明,以及Claude Code 更新日志(权威版本)。2026年6月23日。v2.1.187:sandbox.credentials 设置可阻止沙箱命令读取凭据文件和机密环境变量;组织配置的模型限制统一应用于 /model 选择器、--model、/model 和 ANTHROPIC_MODEL,选中受限模型时会显示“restricted by your organization’s settings”提示;全屏菜单(权限提示、/model、/config)支持鼠标点击选择;/install-github-app 将 GitHub Actions 工作流/密钥的设置改为可选;/btw 新增 ←/→ 键在之前的回答间切换;/plugin 会列出近期未使用的 plugins 以便清理;claude --help 现在会列出 --bg/--background 标志。修复:当原始 -p 运行未产生任何模型回合时,--resume 报“No conversation found”失败;--json-schema 与 workflow agent({schema}) 的结构化输出(成功后不再无限重复调用 StructuredOutput;后续回合能稳定返回结构化输出);远程 MCP 工具调用挂起 5 分钟后现在会报错中止;安装 agent-proxy CA 信任后 Remote 会话启动慢约 2.7 秒;在以逐字节扩展键事件传递粘贴内容的终端中,粘贴韩文/CJK 文本出现乱码;通过 Remote Control 执行 /update 时卡在启动信任对话框;回合结束却无结构化输出时,后台作业卡在“working”状态;导航到代理视图//bg//tui//update 后通道断开;代理停止通知的归属与措辞;恢复/分叉时的 subagent 深度跟踪;清理泄漏的代理 worktree 注册;macOS 上 Ghostty 全屏模式下 Cmd+点击打开 URL;/share 上传期间的 Esc/Ctrl-C/Ctrl-D;[VSCode] 扩展在恢复大型会话时无响应。当前会话验证(2026年6月23日,PST):GitHub releases 与 code.claude.com/docs/en/changelog 的权威更新日志确认 v2.1.187 为最新版本。 ↩↩↩

  177. Anthropic,“Introducing Claude Tag”,anthropic.com,2026年6月23日:Introducing Claude Tag。Claude Tag 是面向 Claude Enterprise 和 Team 客户的 Slack 原生代理:成员在频道中 @Claude 即可委派任务,代理会将任务分解为多个阶段并异步完成,再将结果发回频道;共享的单一 Claude 身份让团队成员可以交接进行中的工作;管理员可按频道限定工具、数据源和记忆的访问范围,并设置 token 消耗上限与活动日志;它运行在 Opus 4.8 上。Anthropic 称其产品团队约 65% 的代码变更经由内部版本完成。同期报道可资佐证:Fortune和TechCrunch,2026年6月23日。当前会话验证(2026年6月24日,PST):该发布已获多家独立媒体交叉证实;上述细节以 Anthropic 的公告及相关报道为准。 ↩↩↩↩

  178. Claude Code v2.1.191 发布说明 及 Claude Code 更新日志(权威版本)。2026年6月24日。v2.1.191:/rewind 支持将对话恢复到运行 /clear 之前的状态;沙盒网络权限对话框会在本会话内记住已允许的主机;流式响应期间 CPU 占用降低约 37%;减少了终端输出缓存导致的长会话内存增长。修复:从任务面板停止后台代理现已永久生效(不会复活);在流式输出过程中回看早先内容时,滚动不再跳回底部;/voice 在遇到组织策略限制时会给出说明,而非笼统的“不可用”;/login URL 在 Windows Terminal 中换行时不再被截断;通过 ssh/tmux 在全屏 Ghostty 中可用 Cmd+点击打开链接;claude agents 不再将内置斜杠命令(如 /usage)作为提示文本发送,并为粘贴的图片显示 [Image #N] 占位符;使用逗号分隔匹配器的 hooks(如 Bash,PowerShell)不再静默地永不触发;/permissions 中“最近拒绝”列表里的批准项在关闭后得以保留;代理面板不再越过溢出上限多跳一行;欢迎页不再在 80×24 的终端窗口中溢出;托管的 forceRemoteSettingsRefresh 现可通过 MDM/文件策略生效;提升了 MCP 服务器的可靠性。本会话验证于 2026年6月25日(PST):GitHub 发布页与 code.claude.com/docs/en/changelog 上的权威更新日志均确认 v2.1.191 为最新版本。 ↩↩

  179. Claude Code 更新日志(权威版本),2026年6月25日至26日(v2.1.192 与 v2.1.194 未发布)。v2.1.193(6月25日):新增 autoMode.classifyAllShell 设置,将所有 Bash/PowerShell 命令都交由自动模式分类器判断,而不再仅限于任意代码执行模式;自动模式的拒绝原因现已加入转录记录、拒绝提示弹窗以及 /permissions 的最近拒绝列表;新增 claude_code.assistant_response OpenTelemetry 日志事件,用于携带模型的响应文本,除非设置 OTEL_LOG_ASSISTANT_RESPONSES=1,否则内容会被脱敏——该变量未设置时会沿用 OTEL_LOG_USER_PROMPTS 的取值,因此已在记录提示内容的部署在升级后会开始收到响应内容(设置 OTEL_LOG_ASSISTANT_RESPONSES=0 可保持仅记录提示);bash 模式(!)下的文件路径实时自动补全;当 MCP 服务器需要身份验证时,启动时会给出提示并指向 /mcp;对空闲的后台 shell 命令进行自动内存压力回收(可用 CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 禁用);此外还修复了 /login 之后 /model 状态陈旧、后台化操作被误取消、恢复子代理时的幻影生成,以及 MCP headersHelper 在 401/403 时重新认证等问题。v2.1.195(6月26日):新增 CLAUDE_CODE_DISABLE_MOUSE_CLICKS 环境变量,可在全屏模式下禁用鼠标点击/拖动/悬停,同时保留滚轮滚动;带连字符标识符的 hook 匹配器(如 code-reviewer、mcp__brave-search)现在采用精确匹配而非子串匹配(若要匹配某个带连字符的 MCP 服务器的全部工具,请使用 mcp__brave-search__.*);另有语音听写修复(macOS 设备切换后无声;无空格分词语言的自动提交)、插件启用/授权同意修复,以及后台任务/代理守护进程的可靠性修复。本会话验证于 2026年6月30日(PST):code.claude.com/docs/en/changelog 上的权威更新日志确认 v2.1.195 为最新版本(其中并无 v2.1.196——某份 GitHub 摘要声称存在带有组织默认模型与可点击文件附件的“v2.1.196”,但与权威更新日志不符,故未采用)。 ↩↩↩↩

  180. Anthropic,规范模型文档,模型概览与隆重推出 Claude Sonnet 5,2026年6月30日。Claude Sonnet 5——模型 ID 为 claude-sonnet-5(无日期的固定快照);Claude API 别名 claude-sonnet-5;AWS Bedrock 为 anthropic.claude-sonnet-5;Google Cloud 为 claude-sonnet-5。100 万 token 上下文窗口;最大输出 128K(在 Message Batches API 上配合 output-300k-2026-03-24 beta 标头可达 300K);自适应思考(始终开启),不支持扩展思考;可靠知识截止日期为 2026年1月。定价为输入 $3/MTok、输出 $15/MTok,并提供 $2/$10 的首发优惠价至 2026年8月31日(Opus 4.8 为 $5/$25)。Anthropic 将其定位为“速度与智能的最佳组合”,性能“接近 Opus 4.8,但价格更低”,在智能体推理、工具调用、编码和知识工作方面较 Sonnet 4.6 有显著提升,不良行为发生率更低,而网络安全能力则远弱于 Opus 系列模型。在 Claude Code 和 Claude API 上,Sonnet 5 的 effort 参数默认为 high。本次会话核验于 2026年7月1日(PST):规格与定价已与 platform.claude.com 上的规范 Anthropic 模型文档以及 anthropic.com/news/claude-sonnet-5 的官方公告交叉核对。 ↩↩

  181. Claude Code 更新日志(规范版),2026年6月29日至7月2日。v2.1.196(6月29日):组织默认模型;可读的默认会话名称;可点击的文件附件;claude mcp list/get 不再启动由仓库自行批准的 .mcp.json 服务器(不受信任的工作区显示待批准状态);流式空闲看门狗默认开启,可通过 CLAUDE_ENABLE_STREAM_WATCHDOG=0 退出;/code-review 的查找器已合并(token 用量减少约 25%);非 Anthropic 的 ANTHROPIC_BASE_URL 下禁用 Remote Control;后台会话可靠性改进。v2.1.197(6月30日):Claude Sonnet 5 成为 Claude Code 的默认模型,原生支持 100 万 token 上下文窗口,并在 8月31日前享受每 MTok $2/$10 的促销价(公告)。v2.1.198(7月1日):subagent 默认在后台运行;Claude in Chrome 正式发布;后台 agent 在工作树中完成代码工作后会提交、推送并打开草稿 PR;Notification hook 事件 agent_needs_input/agent_completed;/dataviz skill;Claude Platform on AWS 可作为网关上游;Explore agent 继承会话模型(上限为 Opus);subagent 与压缩继承扩展思考配置;移除了 /agents 向导。v2.1.199(7月2日):堆叠的斜杠 skill 调用会加载所有前置 skill(最多 5 个);订阅用户遇到瞬时服务器 429 时自动重试;CLAUDE_CODE_RETRY_WATCHDOG 将非容量类重试默认值提高到 300,并解除 CLAUDE_CODE_MAX_RETRIES 的 15 次上限;大量后台 agent、subagent 错误报告和 hook stderr 方面的修复。核验说明:7月1日的指南更新记录了 v2.1.196 在当日核验时尚未出现在规范更新日志中;该条目此后已在那里发布,与早先的 GitHub 发布摘要一致。本次会话核验于 2026年7月3日(PST):规范更新日志确认 v2.1.199 为最新版本。 ↩↩↩↩↩↩

  182. Claude Code 更新日志(规范版)及 GitHub 发布页,2026年7月3日至6日。v2.1.200(7月3日):default 权限模式在 CLI、--help、VS Code 和 JetBrains 中统一改标为“Manual”,同时接受 --permission-mode manual 与 "defaultMode": "manual",原有的 default 配置值保持不变;AskUserQuestion 对话框默认不再自动继续(可通过 /config 选择启用空闲超时);此外修复了以下问题:disabledMcpServers/enabledMcpServers 为非数组时的启动崩溃、后台会话在睡眠/唤醒后停止、过期 daemon.lock 的处理、在产生任何输出之前就被速率限制切断的 subagent 现在能正常返回,以及 tmux 3.4+ 的同步输出闪烁。v2.1.201(7月3日):Claude Sonnet 5 会话不再使用对话中途的 system 角色来传递 harness 提醒。v2.1.202(7月6日):新增“Dynamic workflow size”/config 设置(小/中/大 agent 数量仅为建议值,并非强制上限);工作流派生的 agent 带有 workflow.run_id 和 workflow.name OpenTelemetry 属性;/review <pr> 恢复为快速的单轮审查(如需以指定 effort 进行多 agent 审查,请使用 /code-review <level> <pr#>);重复调用已加载的 skill 不再向上下文追加一份重复的指令副本;当服务器配置含有 url 但缺少 type 时,MCP 会给出更清晰的错误提示并建议使用 "type": "http";另有 Remote Control、多工作树仓库中按名称恢复的性能,以及安装器/更新器下载中途重试方面的修复。GitHub 发布时间戳:v2.1.200 与 v2.1.201 发布于 2026-07-03,v2.1.202 发布于 2026-07-06。本次会话核验于 2026年7月7日(PST):规范更新日志与 GitHub 发布页确认 v2.1.202 为最新版本。 ↩↩

  183. Claude Code 更新日志(规范版)及 GitHub 发布页,2026年7月7日至9日。v2.1.203(7月7日):处于 manual 权限模式时页脚显示灰色 ⏸ 标记;会话的附加工作目录会加入 MCP 的 roots/list,变更时发送 notifications/roots/list_changed;修复内容包括:后台会话丢失 shell 导出的 ANTHROPIC_BASE_URL(API 密钥被发送到默认端点并以 401 失败)、daemon 令牌过期的后台会话现可自动恢复、工作树隔离的 subagent 有时会在父检出目录中执行,以及 TaskStop/TaskOutput 找不到由其他 agent 派生的 agent。v2.1.204(7月8日):仅含错误修复——无头会话中 SessionStart hook 运行期间 hook 事件未能流式传输,可能导致远程工作进程在 hook 执行中途因空闲被回收。v2.1.205(7月9日):auto 模式阻止篡改会话记录文件;auto 模式在对无法从上下文解析的变量运行 rm -rf 之前会先询问;后台任务通知会明确说明未发生任何人工输入,防止记录中伪造的批准被执行;/doctor 升级为完整的设置体检,可诊断并修复问题,/checkup 为其别名;“Claude Browser”被保留为 MCP 服务器名称(与“Claude Preview”一样);agent 视图的行显示彩色状态词和由分类器撰写的标题,涉及已有 PR 的会话会在 claude agents 中链接该 PR;自动更新的下载改为流式写入磁盘(峰值内存降低约 400 MB)。本次会话核验于 2026年7月9日(PST):规范更新日志确认 v2.1.205 为最新版本。 ↩↩

  184. Claude Code v2.1.206 发布说明。2026年7月。v2.1.206:/login 支持通过 Anthropic 运营的公共网关端点进行身份验证;/commit-push-pr 自动允许向仓库配置的推送远程执行 git push——若设置了 remote.pushDefault 则使用它,否则使用唯一的远程——而不再仅限于 origin。本次指南更新已于 2026年7月17日对照 GitHub 发布页及 code.claude.com/docs/en/changelog 上的规范更新日志核验。 ↩↩↩↩

  185. Claude Code v2.1.207 发布说明。2026年7月。v2.1.207:在 AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 上,Auto Mode 不再需要通过 CLAUDE_CODE_ENABLE_AUTO_MODE 显式启用——管理员可通过 disableAutoMode 托管设置将其禁用;Bedrock、Vertex AI 和 Claude Platform on AWS 现默认使用 Claude Opus 4.8;autoMode 设置不再从仓库的 .claude/settings.local.json 读取(请使用 ~/.claude/settings.json);plugin 安全——shell 形式的 plugin 命令中拒绝 ${user_config.*} 插值(请使用 exec 形式或 $CLAUDE_PLUGIN_OPTION_<KEY> 环境变量),且 pluginConfigs 不再从项目级 .claude/settings.json 读取。本次指南更新已于 2026年7月17日对照 GitHub 发布页及 code.claude.com/docs/en/changelog 上的规范更新日志核验。 ↩↩↩↩↩↩↩

  186. Claude Code v2.1.208 发布说明、Claude Code 无障碍文档以及 Claude Code 企业启动器文档。2026年7月。v2.1.208:可通过 claude --ax-screen-reader、CLAUDE_AX_SCREEN_READER=1 或 "axScreenReader": true 设置启用屏幕阅读器模式,相关说明收录在新增的无障碍页面;processWrapper 设置 / CLAUDE_CODE_PROCESS_WRAPPER 环境变量会将 Claude Code 自行派生的所有进程交由一个包装可执行文件处理,以便与企业启动器集成;vimInsertModeRemaps 设置用于定义 vim 插入模式的按键重映射(例如 jj → Escape);在命令替换($(...)、反引号、<(...))内部的灾难性删除操作,例如 rm -rf ~,现在即使在 --dangerously-skip-permissions 和自动模式下也会弹出确认提示。本次指南更新已于2026年7月17日对照 GitHub 发布版本及 code.claude.com 文档页面核实。 ↩↩↩↩↩↩↩↩↩

  187. Claude Code v2.1.210 发布说明。2026年7月。v2.1.210:Claude Code 现在会在启动时对使用 Write(path)、NotebookEdit(path) 或 Glob(path) 形式的权限规则发出警告——写入侧的文件规则应使用 Edit(path)(它管辖所有写文件的工具),读取侧的规则应使用 Read(path)(它管辖所有读文件的工具,包括 Glob)。本次指南更新已于2026年7月17日对照 GitHub 发布版本及 code.claude.com/docs/en/changelog 上的权威变更日志核实。同一版本还将自动模式的权限分类器在外部会话中的默认模型改为 Claude Sonnet 5。 ↩↩↩↩↩

  188. Claude Code v2.1.211 发布说明。2026年7月。v2.1.211:--forward-subagent-text 标志和 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT 环境变量可将 subagent 的文本和思考输出纳入 --output-format stream-json;“始终允许”权限规则现在保存在仓库根目录,因此在某个工作树中授予的批准会跨会话保留,并对该仓库的所有工作树生效。本次指南更新已于2026年7月17日对照 GitHub 发布版本及 code.claude.com/docs/en/changelog 上的权威变更日志核实。 ↩↩↩

  189. Claude Code v2.1.212 发布说明。2026年7月。v2.1.212:/fork 现在会把对话复制到一个新的后台会话中,并在 claude agents 里拥有自己的一行,原先的会话内 fork 行为更名为 /subtask;新增 claude auto-mode reset 子命令,可用 --yes 跳过确认;按会话计的预算——WebSearch 调用和 subagent 派生各默认每会话 200 次,分别由 CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 和 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 控制,/clear 会重置 subagent 预算;运行超过 2 分钟的 MCP 工具调用会自动转入后台,阈值可通过 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 配置;Task 工具的 mode 参数已弃用并被忽略——subagent 继承父会话的权限模式;企业级 forceLoginMethod 设置现在也对 VS Code 扩展、SDK、claude setup-token 和 /install-github-app 强制生效(此前仅限终端)。本次指南更新已于2026年7月17日对照 GitHub 发布版本及 code.claude.com/docs/en/changelog 上的权威变更日志核实。 ↩↩↩↩↩↩↩↩

  190. Claude Code CHANGELOG,v2.1.214 条目。2026年7月。v2.1.214:单段式 dir/** 允许规则(例如 Edit(src/**))现在只匹配 <cwd>/dir,而不再匹配目录树中任意层级的 dir/——deny/ask 规则仍保持任意深度匹配,hook 的 if: 条件也获得同样的 cwd 作用域限定(需要任意深度时请写 **/dir/**);权限“失败即关闭”加固——修复了 Windows PowerShell 5.1 绕过问题,Bash 文件描述符重定向形式失败即关闭,超过 10,000 个字符的命令一律提示,[[ ]] 中的 zsh 下标/修饰符会提示,不安全的 help/man 变体不再自动批准,远程会话的提示在本地确认之前无法继续,docker/Podman 守护进程重定向标志(--url、--connection、--identity、远程模式)会提示,file -m/--magic-file/-f/--files-from 需要权限;新增 EndConversation 工具,用于在遇到高度辱骂性输入或越狱尝试时结束会话;SessionStart hooks 对 fork 出的会话报告来源为 "fork"(此前为 "resume");OTel 日志事件新增 message.uuid、client_request_id 和 tool_source 属性,CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 可配置 60 KB 的内容截断上限,subagentStatusLine 载荷包含推理强度。本次指南更新已于2026年7月21日对照 GitHub 原始变更日志核实。(v2.1.213 从未发布。) ↩↩↩↩↩↩↩↩

  191. Claude Code CHANGELOG,v2.1.215 条目。2026年7月。v2.1.215(仅一项变更):Claude 不再自行运行 /verify 和 /code-review skills——需要时请通过 /verify 或 /code-review 手动调用。本次指南更新已于2026年7月21日对照 GitHub 原始变更日志核实。 ↩↩

  192. Claude Code CHANGELOG,v2.1.216 条目。2026年7月。v2.1.216:新增 sandbox.filesystem.disabled 设置,可跳过文件系统隔离而保留网络出站控制;修复了长会话中消息规范化的二次方级变慢、OAuth 令牌轮换后自动模式出现 HTTP 401 拒绝、工作树隔离的 subagent 通过 git -C/--git-dir/GIT_DIR 把 git 重定向到共享检出目录,以及 .claude 符号链接写入重定向等问题;/rewind 拒绝符号链接/硬链接的恢复路径;/context 在上下文窗口溢出时发出警告;会话中途对 skill/命令的编辑无需重启即可出现在斜杠菜单中;/fork 的确认信息会显示新会话的名称和 claude attach id;云端会话在容器于回合中途重启后可恢复进行中的回合。本次指南更新已于2026年7月21日对照 GitHub 原始变更日志核实。 ↩↩↩

  193. Anthropic 研究:Claude 结束极少数特定对话的能力。2025年。这是 v2.1.214 以 EndConversation 工具形式引入 Claude Code 的对话结束能力的背景资料——该能力自2025年起已在 claude.ai 上部署,用于应对极少数持续辱骂或有害的交互。 ↩↩

  194. Claude Code CHANGELOG,v2.1.217 条目。2026年7月。v2.1.217:subagent 默认不再派生嵌套的 subagent——如需更深层级的嵌套,请设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH(这推翻了 v2.1.172 引入的递归派生默认行为);新增同时运行的 subagent 数量上限,默认 20,可用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 覆盖;--max-budget-usd 现在会停止后台 subagent——一旦达到上限,新的派生请求会被拒绝,正在运行的后台代理会被终止;提示输入框支持表情符号短代码自动补全(:heart: → ❤️),可通过 emojiCompletionEnabled 设置关闭。另有一批可靠性与隔离性修复:为后台会话隔离而对符号链接工作目录做规范化、受管 OTEL_EXPORTER_OTLP_ENDPOINT 统一管辖所有信号、转录写入失败警告、MCP 截断输出的内存泄漏、Windows 自动更新时的 claude.exe 恢复、Bedrock Opus 4.8 自动压缩、Claude Desktop 的企业 mTLS/TLS/OAuth/代理设置、--resume 遇到格式错误附件时的 TypeError、无法停止的后台 shell、花括号展开导致的 OOM、Remote Control 后加入者的提示、屏幕阅读器修复、ssh/tmux 中可点击的页脚 PR 徽章(FORCE_HYPERLINK=0 可退出)、登录过期警告从提前 5 天改为提前 3 天,以及 frontend-design plugin 的提示在整个生命周期内最多显示 3 次。本次指南更新已于2026年7月22日对照 GitHub 原始变更日志核实。 ↩↩↩↩↩↩↩

  195. Claude Code CHANGELOG,v2.1.218条目。2026年7月。v2.1.218:/code-review现以后台subagent的形式运行,审查工作不再占满对话,堆叠的斜杠命令仍是其审查目标;带有context: fork的skills默认在后台运行,各skill可通过新增的background: false frontmatter键单独选择退出;危险rm、后台&以及可疑Windows路径的检查不再弹出权限对话框,改由自动模式分类器裁定;启用自动模式的计划模式也不再对静态分析器无法证明为只读的Bash命令发出提示;agent frontmatter中的hooks要求agent文件所在的文件夹已接受工作区信任后才会运行;/deep-research仅在手动调用时启动。此外:左箭头丢弃确认与Esc从agent视图返回;无害的服务器托管功能/成本开关跳过设置审批提示;含:的agent名称被拒绝;skill与plugin frontmatter的布尔值接受yes/no/on/off/1/0;信任对话框会指明仓库根目录;改进了IDE交互的沙箱限制;Ctrl+B后台shell数量上限;Bedrock ARN支出计量;headless/SDK会话中压缩后的分叉会话谱系;修复Windows \u路径损坏;修复远程会话僵尸心跳。本次指南更新已于2026年7月24日对照原始GitHub变更日志核实:发布于2026-07-22T21:24Z的v2.1.218为npm最新版本。(归属更正,2026年7月25日:claude mcp list//mcp的HTTP状态与错误文本条目以及MCP隐藏空白字符警告最初被列在此处的v2.1.218之下;原始变更日志将二者均归入v2.1.219条目。已移至196。) ↩↩↩↩↩↩↩↩

  196. Claude Code CHANGELOG,v2.1.219与v2.1.220条目。2026年7月。v2.1.219(7月24日):新增Claude Opus 5(claude-opus-5)作为新的默认Opus模型,具备1M上下文,快速模式定价为每MTok $10/$50;新增sandbox.network.strictAllowlist设置,可在不提示的情况下为沙箱命令拒绝未列入允许列表的主机;新增DirectoryAdded hook,在/add-dir或SDK的register_repo_root控制请求于会话中途注册新工作目录后触发;在headless stream-json初始化事件中新增mcp_server_errors,列出被配置校验跳过的--mcp-config条目(终端运行时会打印启动警告);新增workflowSizeGuideline设置键,使建议性的动态工作流规模准则可从任意设置文件中设定,设定后/config中的对应行会隐藏;在stream-json中新增嵌套subagent转发,设置--forward-subagent-text后,深度2及以上生成的subagents会以生成它们的Agent tool_use id为键显示;将动态工作流的默认规模准则改为中等(目标为少于15个agents);将Opus 4.7从快速模式中移除,/fast现在适用于Opus 5和Opus 4.8;subagents现在默认可生成最多3层深度的嵌套subagents(此前为1层);设置CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1可禁用嵌套;更新claude-api skill,默认使用Claude Opus 5,并提供从Opus 4.8迁移的路径;当服务器连接失败时,claude mcp list和/mcp会显示HTTP状态和错误文本,并对含有隐藏前导或尾随空白字符的MCP配置值发出警告;托管MCP允许列表/拒绝列表中的${VAR}条目改为从启动环境和托管设置env解析,而非设置文件env;在运行中工作流的状态行里加入当前默认工作流规模;修复了以下问题:claude -p文本输出在回合因流式传输中途的API错误而中止时丢弃已生成的回答;Fable行显示过时的“Requires usage credits”标签;/model选择器将合并后的Opus行显示为单纯的“Opus”而非“Opus (1M context)”;新版本高亮覆盖范围超出最新模型的名称;GNU screen选中即复制时打印base64;Remote Control客户端在模型切换/重连/组织检查失败后保留过时的快速模式状态;Windows上的CLAUDE_CODE_GIT_BASH_PATH在路径并非bash/sh二进制文件时导致退出或被当作bash使用(现在会忽略并给出警告);Vim模式下在空提示符上按←无法从NORMAL模式返回agent视图;以及屏幕阅读器模式在每次按键时重写整个输入行;改进了“Remote Control is only available via api.anthropic.com”错误提示,使其指明导致该错误的设置;claude --teleport在不匹配时会显示当前检出指向的仓库。v2.1.220(7月25日):仅包含错误修复和可靠性改进,没有面向用户的功能、设置、命令或定价变更。本次指南更新已于2026年7月25日对照原始GitHub变更日志核实。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  197. Anthropic,正式推出Claude Opus 5,以及权威模型文档:模型概览和从Claude Opus 4.8迁移至Claude Opus 5。2026年7月。Claude Opus 5:模型ID为claude-opus-5(无日期的固定快照;Bedrock为anthropic.claude-opus-5,Google Cloud为claude-opus-5);“适用于复杂的agentic编码与企业级工作”;1M token上下文窗口,最大输出128K(在Message Batches API上配合output-300k-2026-03-24 beta标头可达300K);定价为每输入MTok $5,每输出MTok $25,“与Opus 4.8相同”;自适应思考支持,thinking.type: "enabled"扩展思考不支持;可靠知识截止日期为2026年5月,训练数据截止日期为2026年5月;effort参数“在Claude API和Claude Code上默认为high”,级别包括low、medium、high、xhigh、max。Anthropic表示,它是“Claude Max上的新默认模型,也是Claude Pro上最强的模型”,“以相同成本带来大幅提升的性能”,并且在最高推理强度下相比Opus 4.8“平均生成的token少26%”。迁移指南中的破坏性变更:(1)“在Claude Opus 4.8上,不带thinking字段的请求不启用思考;在Claude Opus 5上,同样的请求会以自适应思考运行”;(2)“您仍可通过thinking: {type: \"disabled\"}关闭思考,但仅限于high或更低的effort级别。将thinking: {type: \"disabled\"}与effort xhigh或max组合的请求会返回400错误”,且“对每个请求强制执行”。Claude Opus 4.8现已列入模型概览的旧版模型表中。各effort级别的可用性来自Effort:xhigh“可用于Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7和Claude Sonnet 5”;max还支持Claude Opus 4.6和Claude Sonnet 4.6;“Claude Opus 5支持全部五个effort级别”,并且“API默认值为high”。于2026年7月25日获取并核实。 ↩↩↩↩↩↩↩↩↩↩↩↩↩

  198. 快速模式(研究预览版),Anthropic平台文档。于2026年7月25日核实。“快速模式以溢价定价为Claude Opus 5和Claude Opus 4.8提供最高2.5倍的每秒输出token数。在请求中设置speed: \"fast\"并附带fast-mode-2026-02-01 beta标头即可启用。”支持的模型:Claude Opus 5(claude-opus-5)和Claude Opus 4.8(claude-opus-4-8),每输入MTok $10美元,每输出MTok $50美元,“在整个上下文窗口内按标准费率的倍数定价,包括输入超过200k token的请求”。仅在Claude API(包括Claude Managed Agents)上以研究预览版形式提供:“不适用于Amazon Bedrock、Google Cloud或Microsoft Foundry”,也不适用于AWS上的Claude Platform、Batch API或Priority Tier承诺。关于Opus 4.7:“快速模式不适用于Claude Opus 4.7。对claude-opus-4-7发出带speed: \"fast\"的请求会返回错误;与Claude Opus 4.6……不同,请求不会回退到标准速度。”关于Opus 4.6:请求“不会返回错误:它们以标准速度运行并按标准费率计费……且响应会报告usage.speed: \"standard\"”。与标准速度使用相同的权重和行为;提升体现在每秒输出token数上,而非首token延迟。拥有独立的速率限制,附带anthropic-fast-*-tokens-*标头;“在快速与标准速度之间切换会使提示缓存失效。” ↩↩↩↩↩↩↩↩↩↩↩

  199. Claude Code v2.1.221 发行说明与Claude Code v2.1.222 发行说明,2026年8月4日。v2.1.221:VSCode Focus 视图(Ctrl+Alt+F);Linux/WSL 上沙箱凭据文件支持 mode: "mask",采用哨兵副本与出口替换,macOS 则回退为 deny;后台会话支持提交/推送、仅在必要时创建草稿 PR、遵循 CLAUDE.md 中的 git 指令,并在运行结束时报告所在位置;/fork 会话获得独立的 worktree;/plugin install 目录刷新与重试;在安全的情况下立即激活插件;"." 可用作插件的 skills 路径;修复了 zsh [[ ]] 正则条件的权限绕过;修复了 PowerShell 带引号路径的权限问题;prompt-audit 子命令;Stats 中的缓存 token 明细;自动模式下的提示缓存复用。v2.1.222:Remote Control 自动启动仅限用户作用域;worktree 隔离的 git 修复扩展至所有会话类型中的文件编辑与 Bash;修复了后台任务的 PreToolUse 自动允许绕过;SendMessage 权限分类;移除了 ultraplan。当前会话于2026年8月5日(PST)验证:GitHub 的发布列表将 v2.1.222(发布于 2026-08-04T22:39:55Z)列为最新版本。 ↩↩↩↩↩↩↩↩

  200. Claude Code v2.1.223 发行说明,2026年8月6日。为 strictKnownMarketplaces 和 blockedMarketplaces 新增 "owner/*" 通配符条目;将 /review 设为 /code-review 的别名,并记住上次输入的强度级别(/code-review ultra 用于深度云端审查);扩展 CLAUDE_CODE_DISABLE_1M_CONTEXT,通过自动压缩将所有原生 1M 模型限制在 200K 并在启动时发出警告,同时为无法识别的模型 ID 新增 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT;安全修复涵盖特制命令导致的 Bash 权限绕过、审批对话框中的不可见 Unicode 命令填充、工作流脚本动态 import() 的沙箱逃逸,以及代理定义中的 bypassPermissions 忽略组织禁用策略的问题。当前会话于2026年8月6日(PST)验证:GitHub 的发布列表将 v2.1.223(发布于 2026-08-06T00:52:37Z)列为最新版本。 ↩↩↩↩↩

  201. Claude Code v2.1.224 发行说明,2026年8月7日。新增 claude self-hosted-runner(Team/Enterprise);macOS/Linux 上的跨会话 SendMessage,支持通过 ListAgents 发现,并新增 crossSessionInbound/dialogExpiry 设置;archive 插件源,可选 SHA-256 固定;沙箱凭据脱敏选项 extract/onExtractNoMatch、带 maskClaims 的 decode: "jwt",以及 awsPairs/sigv4(需要 network.tlsTerminate;仅限用户/托管/--settings 作用域);取消每个会话 200 个 subagents 的生成上限;修复了长路径导致的会话目录串扰、尾部斜杠导致的沙箱拒绝绕过,以及沙箱违规详情不可见的问题。当前会话于2026年8月7日(PST)验证:GitHub 的发布列表将 v2.1.224(发布于 2026-08-07T04:00:59Z)列为最新版本。 ↩↩↩↩↩↩↩

  202. Claude Code v2.1.225 发行说明与Claude Code v2.1.226 发行说明,2026年8月7日(PST;发布于 2026-08-08T01:09:26Z 和 2026-08-08T02:48:05Z UTC)。v2.1.225:可按名称向 Remote Control 会话跨机器发送 SendMessage,并以 name [ref] 形式列出;用量警告中包含网关支出上限详情;claude agents 工作区信任提示;修复了 OAuth token、钥匙串、自动模式连续阻止、跨会话消息暂存、self-hosted-runner 启动以及 Focus 视图的问题。v2.1.226:仅包含错误修复与可靠性改进。当前会话于2026年8月7日(PST)验证:GitHub 的发布列表将 v2.1.226 列为最新版本。 ↩↩↩

  203. 自动模式现已成为 Claude Code 在 Pro、Max 和 Team 方案中的默认设置,Anthropic,2026年8月7日;2026年8月14日已对照权限模式文档确认推出生效,该文档写道:“自2026年8月14日起,自动模式成为 Pro、Max 和 Team 方案上新会话的默认权限模式。您可以随时切换模式。您自行设置的默认值将保持不变,除非您接受一次性切换提示;由组织管理的默认值不受影响。”自2026年8月14日起对 Pro/Max/Team 生效。自动模式“将每一次工具调用都交由分类器处理,该分类器专门用于阻止不可逆、具有破坏性或指向您环境之外的操作。”研究依据:1,053 名付费测试者;自动模式拦截了 89% 的危险命令,而人工审核仅为 13.6%;用户会批准 97% 的权限提示。“从今天起,我们不再向 Pro、Max 和 Team 方案的 Claude Code 用户收取该分类器的额外开销费用。”Enterprise、Claude API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform 以及 Microsoft Foundry 仍需主动启用:“在接下来的一个月里,我们计划与云合作伙伴协作,将其设为上述所有平台的默认模式。”可通过 Shift+Tab 或桌面端的模式下拉菜单按会话退出;通过托管设置中的 defaultMode 固定;通过 disableAutoMode 在组织范围内禁用。 ↩↩↩↩↩↩

  204. Claude 如何标记 AI 生成的内容,Anthropic 帮助中心,发布于2026年8月11日;访问于2026年8月18日。此为以下内容的来源:双组件结构(文本水印 + 文件上的 C2PA“签名来源元数据”,适用于“例如 .svg、.png 或 .jpg”等文件)、统一的模型时间线(“2026年8月2日及之后发布的 Claude 模型将在发布时即支持机器可读标记”;现有模型:“我们也在努力为这些模型添加标记支持”)、产品列表(Claude Platform(API)、Claude、Claude Code、Claude Cowork、Claude Tag,“全球范围内凡提供 Claude 的地方”)、文件侧的剥离途径(格式转换、重新保存、截图;对文本而言则是大幅编辑/改写/翻译),以及检测的局限(“检测到 Claude 标记只能说明该内容可能经过 Claude 处理,仅凭这一点并不能确认完整的来源”;没有标记并不等于排除嫌疑)。 ↩↩↩↩↩↩

  205. Claude Code 发行说明 v2.1.239(8月21日)、v2.1.240 与 v2.1.241(8月22–23日,两者原文均仅为“错误修复与可靠性改进”),并于2026年8月24日与权威的 CHANGELOG.md 交叉核对(最新标题:2.1.241;npm 最新版 2.1.241)。v2.1.239 原文:“成本估算(/cost、状态行、--max-budget-usd)现已包含数据驻留工作区仅限美国推理的 1.1 倍溢价”;“新增 /claude-api upgrade,用于将 Python 项目从 anthropic 0.x 迁移到 1.x”;“Windows:跨会话消息传递现已可用”;插件“现在显示为 name@synced……且绝不会覆盖您自行安装的同名插件”;“ListAgents 现在会告知会话其自身的名称”;readline 按词移动快捷键“Alt+F 和 Ctrl/Option+→ 停在单词末尾,Alt+D 删除至该处(Ctrl+Y 可将其粘贴回来)”。/design 与 Remote Control 的状态来自第 34 周摘要:“/design skill 将 Claude Design 的画板工作流带入 CLI 和 Claude Code Desktop,基于 artifacts 构建……适用于 Pro、Max、Team 和 Enterprise。需要 v2.1.233 或更高版本”;“Remote Control 也已结束研究预览阶段。”两者均于2026年8月24日直接获取。 ↩↩↩↩↩

  206. Claude Code CHANGELOG,2.1.248、2.1.250 和 2.1.251 小节,获取于2026年8月30日。npm 于2026年8月27日 20:35 UTC 发布了 2.1.248,并于同日 22:27 UTC 发布了 2.1.250(其小节原文仅为“错误修复与可靠性改进”),2.1.251 则于2026年8月28日 15:34 UTC 发布(dist-tag latest:2.1.251);2.1.249 从未在 npm 上发布。2.1.248 原文:“新增 --restricted(或 CLAUDE_CODE_RESTRICTED=1):移除运行命令或代码的内置工具以及 WebFetch(除非在 --tools 中显式指定),将文件工具限制在工作目录之内,拒绝 bypassPermissions,并忽略用户、项目和本地设置文件”;“在 agent frontmatter 中新增 experimental.cacheTtl("5m" 或 "1h"):未配置 subagent TTL 设置时使用的按 agent 提示缓存 TTL”;“新增 claude self-hosted-runner --client-label <label>(或 SELF_HOSTED_RUNNER_CLIENT_LABEL),用于覆盖 runner 注册时使用的标签(默认:主机名)”;“新增服务器托管设置诊断:设置加载失败时显示启动警告,并在 /doctor 和 /status 中新增一行,说明加载失败的原因或未获取设置的原因(Bedrock/Vertex/第三方提供商、自定义 ANTHROPIC_BASE_URL)”;“为通过 AWS Marketplace 计费的 Enterprise 组织、自助式 Enterprise 以及 Enterprise 试用新增 /usage-credits,成员可据此向管理员申请更高的用量上限”;“新增跨会话消息传递(SendMessage / ListAgents),支持 Bedrock、Vertex 和 Foundry 上同一台机器的会话之间互通,以及遥测被禁用时的场景”;桌面端保留修复:“转录清理现在会保留桌面应用写入的会话,只要它们仍在应用中(除非组织策略管理保留期);新的 desktopSessionCleanupPeriodDays 设置为该豁免设定上限”;“改进托管设置:客户端超时、MCP 启动模式和流监视器(stream-watchdog)环境变量不再触发设置审批提示”;“更改 /loop:自定节奏的动态模式和无提示的自主默认模式现在始终可用,包括在 Bedrock/Vertex/Foundry 上”;“缩减了 Workflow 工具的提示占用:其描述现在约为 1k token 而非 5.7k,脚本编写参考已移入随附的 workflow-authoring skill”;以及上传修复:“修复了 /ultrareview 和本地播种的云会话会上传对 prod.env 类文件和 *.tfvars 文件的未提交编辑,或上传凭据文件的编辑器交换、临时和备份副本(例如 key.pem.tmp、id_rsa.swo)的问题;这些内容现在会留在您的机器上”。2.1.251 原文:“新增 PreModelSwitch 和 PostModelSwitch hook 事件(可阻止、确认或注解模型切换);SessionStart 恢复 hooks 现在会收到会话陈旧程度和预估的重新缓存成本”;“新增将前台 subagent 的工具调用和结果实时流式传输到 Remote Control 客户端(后台 subagents 为默认设置,仍只显示状态)”;“在 /usage 中新增支出上限(Spend limit)进度条,并为处于带支出上限的 Claude apps 网关之后的开发者新增 rate_limits.spend_limit 状态栏字段”;“在 /cost 中新增按会话的提示缓存行(命中率、未命中数、重新缓存的 token 数、热/冷),并为状态栏脚本新增对应的 prompt_cache 对象”;“在 claude --help 中新增 attach、logs、stop、respawn 和 rm;针对正在运行的后台会话,--resume 消息现在会给出确切的 claude attach <id> 命令”;“更改 Claude in Chrome,使浏览器操作始终经过 Claude Code 的权限检查,包括禁用遥测的会话(此前这类会话使用 Chrome 扩展自身的提示)”;“更改 CLAUDE_CODE_SUBAGENT_MODEL,使其设置默认 subagent 模型而非覆盖一切:agent 定义中的 model: 和每次生成时显式指定的模型现在优先于它”;“将按席位计费的 Enterprise 订阅的默认模型更改为 Opus 5,与其他高级套餐保持一致”;“更改 /effort,按模型保存您的默认 effort 级别,切换时每个模型都保留各自的设置”;“更改服务器托管设置:凡是终止沙盒 TLS、将沙盒流量路由至您自己的代理、注入凭据或削弱沙盒隔离的设置,均需经审批后方可生效”;“更改来自托管或项目设置的 ANTHROPIC_CUSTOM_HEADERS:当其设置凭据、组织/租户、路由或 API 行为标头(例如 Authorization、Host)时需要审批”;“更改项目级 .claude/settings.json 的 env,不再设置 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR 或 TMPDIR/TMP/TEMP;请改在 shell、用户或托管设置中设置它们”;“修复了管理员将组织用量额度上限设为 $0 时 Team 和 Enterprise 成员的 /usage-credits 问题:现在会提议向管理员申请,而不是提示已达上限”;安全修复原文:“修复了文件工具(Read、Write、Edit)会跟随权限检查之后在工作目录内被替换的符号链接的问题,这可能导致在已批准位置之外读写”;“修复了 marketplace 条目中声明的 plugin 命令可以指向 plugin 目录之外的问题;此类路径现在会以路径遍历错误被拒绝”;“修复了 Bash 权限检查会自动批准将算术表达式赋值给整数 shell 变量的命令(例如 OPTIND=1/0、RANDOM=2+2)的问题;这些命令现在会提示审批”;“修复了 Grep 和 Glob 对通过符号链接搜索路径访问的文件未应用 Read(...) 拒绝规则的问题”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  207. 模型配置,获取于2026年8月30日,“default 模型设置”小节。原文:“default 的行为取决于您的账户类型”;“Max、Team Premium、Enterprise 按量付费以及 Anthropic API:默认为 Opus 5”;“AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform:默认为 Opus 5”;“Pro、Team Standard 和 Enterprise 订阅席位:默认为 Sonnet 5”;“Microsoft Foundry:默认为 Sonnet 4.5”;“Enterprise 按量付费指按用量而非按订阅席位计费的 Enterprise 组织。”历史说明原文:“在 v2.1.219 之前,default 自 v2.1.154 起在 Anthropic API、Max、Team Premium 和 Enterprise 按量付费上解析为 Opus 4.8,自 v2.1.207 起在 AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上亦解析为 Opus 4.8。在 v2.1.207 之前,default 在 AWS 上的 Claude Platform 上解析为 Opus 4.7,在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Sonnet 4.5。”Enterprise 席位这一行是 CLI 已率先更新的唯一一处:v2.1.251 的 CHANGELOG(2026年8月28日)写道“将按席位计费的 Enterprise 订阅的默认模型更改为 Opus 5,与其他高级套餐保持一致”,比文档页面更新——本指南对席位报告 Opus 5,并注明文档滞后。 ↩↩↩↩↩↩↩↩↩

  208. Hooks 参考,获取于2026年8月30日。PreModelSwitch:“在 Claude Code 应用您或客户端请求的模型切换之前运行”;“PreModelSwitch 需要 Claude Code v2.1.251 或更高版本”;它会在 /model <name> 和选择器、/config 中的 Model 设置、会更改会话模型的快速模式切换,以及 SDK/Remote Control 的 set_model 或 apply_flag_settings 请求时运行,但不会“针对它自行做出的切换运行,例如自动模型回退或恢复会话时还原模型。这些变更只会到达 PostModelSwitch”;“Claude Code 会将 matcher 与会话即将切换到的模型的规范名称进行比较,忽略任何 [1m] 后缀”,而当它“无法确定目标的规范名称”时,“会运行每一个 PreModelSwitch hook,而不论 matcher 为何”;决策控制:退出码 2 或 decision: "block" 会取消切换,permissionDecision 接受 "allow"、"deny" 和 "ask";命令 hook 的默认超时在 UserPromptSubmit、PreModelSwitch 和 PostModelSwitch 上降低为 30 秒,并且“在 PreModelSwitch 上,因超时而被取消的 hook 会阻止模型切换。”PostModelSwitch:“在会话的模型更改之后运行”;“它无法阻止,因为模型已经更改”;它属于“Claude Code 将纯文本 stdout 作为 Claude 可见并可据此行动的上下文添加”的事件之一,并“随切换后的下一次请求”一同送达;其输入新增了 source 值 "auto" 和 "resume"。SessionStart 恢复字段:“当 source 为 "resume" 或 "fork" 且转录中至少包含一条来自 Claude 的响应时,SessionStart hooks 还会收到以下四个字段”;“这些字段需要 Claude Code v2.1.251 或更高版本”:seconds_since_last_response、context_tokens、prompt_cache_likely_expired、estimated_cache_write_usd。 ↩↩↩↩

  209. 状态行与CLI 参考,获取于2026年8月30日。状态行,rate_limits.spend_limit.used_percentage / resets_at:“在 Claude 应用网关之后,适用于您的支出限额已使用的百分比,以及其周期重置时的 Unix 纪元秒数。该百分比范围为 0 到 100,超出限额后可高于 100。需要 Claude Code v2.1.251 或更高版本”;“每个窗口(five_hour、seven_day、spend_limit)都可能各自缺失,一旦某个窗口的 resets_at 时间过去,Claude Code 便会将其移除。”prompt_cache:“该对象在主对话的第一个 API 响应之后出现。Claude Code 不会将 subagent 请求计入这些统计数据。需要 Claude Code v2.1.251 或更高版本”;“Claude Code 根据 API 响应中的缓存 token 计数来计算该值,因此适用于每一家提供商”;“Claude Code 在终端中显示相同的统计数据,位于 /usage 命令的 Prompt cache (main) 一行。”CLI 参考,--restricted:“当评估框架在共享机器上驱动 claude,且 Claude Code 不得运行命令或读取该机器的用户与项目设置时,请使用此选项。Claude Code 会移除运行命令或代码的内置工具以及 WebFetch,除非您在 --tools 中逐个指定它们(而非通过 default 预设)。它还会将内置文件工具限制在工作目录内,仅加载托管设置和 --settings,拒绝 bypassPermissions,并拒绝创建云端会话。需要 Claude Code v2.1.248 或更高版本。” ↩↩↩↩

  210. Johann Rehberger,“Breaking Claude Code Opus 5 Auto Mode”,Embrace The Red,2026年8月26日。该文是以下内容的来源:攻击链(HTTP 415 将代理从 WebFetch 推向 curl、归档解压、由代理自行编写的解码器,以及 base64 从解压目录导入攻击者的 struct.py);报告的结果(python3 C2 链为 5 次中 3 次;两种 claude -p 子进程配置分别为 5 次中 3 次和 5 次中 4 次,即原文所述的 60-80%),并附作者关于样本量较小的说明;关于清理操作被阻止的观察;Anthropic 的处置(以 Informative(信息性)结案,视为按设计工作;属于尽力而为的分类器而非安全保证;操作系统隔离与网络出口控制才是真正的边界);委托进行的 72 个场景评估报告为 0.00%,以及他认为这传达了相互矛盾的信息;并且——经由 Simon Willison 的 “Breaking Claude Code Opus 5 Auto Mode”(2026年8月27日,其 8 月 30 日的更新认同一位 Lobste.rs 读者的观点)——将该攻击链重新归类为“混淆环境攻击”而非经典的提示注入。 ↩↩↩↩↩↩

  211. Claude Code 发行说明 v2.1.257 与 v2.1.258(均为2026年9月1日)以及 v2.1.259(2026年9月2日),已于2026年9月3日与权威的 CHANGELOG 交叉核对。验证时的 npm dist-tag:latest 与 next 均为 2.1.259,stable 为 2.1.236;npm 已发布的版本从 2.1.252 直接跳到 2.1.257——2.1.253 至 2.1.256 从未发布,也没有 CHANGELOG 条目(与 2.1.244/2.1.249 的模式相同)——因此 2.1.258 说明中的“2.1.255 引入的回归”指的是一个未发布的内部构建,而 v2.1.257 是首个可安装且支持 Fable 5.1 的发行版。v2.1.257 各项的来源:Fable 5.1 支持及其网关注意事项(在 Claude 应用网关会话中,fable 与 best 别名目前仍解析为 Fable 5,因为尚未为 Fable 5.1 配置的网关会拒绝它——请改在 /model 中选择);timeFormat/timeZone;自动模式的“Containment Escape”(逃逸隔离)规则(云元数据凭据获取、出口规避和跨租户访问不会自动批准,除非环境将其标记为预期行为);CLAUDE_CODE_SUBAGENT_MODEL_FORCE;首次读取工作目录之外的文件前的一次性提示,以及 permissions.blockReadsOutsideWorkingDirectories;/effort s 与会话范围的 --effort;项目级/本地级的 defaultMode: "bypassPermissions" 被忽略;managedSourcesBehavior: "merge" 的细化(sandbox.credentials.awsPairs 与 sandbox.ripgrep 从设置了它们的最高优先级来源整体读取);Bash Read()/Edit() 拒绝规则覆盖 < file 输入重定向以及 tac、egrep 等读取命令;以及对 --add-dir、/add-dir 和 additionalDirectories 中网络路径(UNC 共享、/net/<host> 自动挂载)的拒绝。v2.1.258 修复的来源:未发布的 2.1.255 中引入的 macOS 12 启动回归,以及远程/计划会话在需要非空内容的请求上失败。v2.1.259 各项的来源:managedMcpServers;allowedMcpServers 的作用范围改为仅限用户添加的服务器;--permission-prompts none(任何本会触发提示的操作都会被自动拒绝,而当前权限模式仍照常决定);解析失败的托管设置会拒绝启动并指明来源;自定义命令和 skills 的 frontmatter model: 在交互式会话中得到遵循,而自动模式会保留会话模型,而不是在不受支持的 frontmatter 模型上运行一轮对话;claude plugin validate --json;以及 Bash Read() 拒绝规则覆盖范围扩展到选项值/操作数(--ignore-revs-file=.env、-f.env、@file 参数、git diff/git grep 操作数、cd DIR && cat FILE 复合命令,以及对包含被拒绝文件的目录执行 grep -r/cp -r 现在会询问)。设置文档尚未记录 timeFormat/timeZone 或 managedMcpServers,CLI 参考也尚未列出 --permission-prompts——在本次更新时,CHANGELOG 是这些内容的来源。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  212. Claude Code v2.1.260 发布说明,发布于2026年9月3日23:48 UTC(太平洋时间下午4:48;npm 发布更早,于22:32 UTC),当晚已与权威 CHANGELOG 交叉核对——距本指南 v2.97 轮次核实 v2.1.259 为 npm latest 仅过去数小时。核验时的 npm dist-tags:latest 与 next 均为 2.1.260,stable 为 2.1.236。回退条目原文:“回退了 2.1.259 中将 Read() 拒绝规则应用于 Bash 参数的改动;该改动在所有模式下都会依据 Read(./**/build/**) 规则拒绝 npm run build,并使 cd … && grep 即便在 auto 模式下也会弹出确认”——v2.1.257 对重定向与读取类命令的覆盖并未在回退中提及,因此依然有效。以下内容的来源:/diff 全屏差异面板(“新增了一个差异面板,在全屏模式下于对话旁边打开,以 Claude 编辑的形式显示您尚未提交的更改;用 /diff 切换显示”);路径含括号的权限修复(路径中带括号的规则“被当作无效规则丢弃或被 Bash 沙箱忽略,导致‘只读’文件夹仍可写入”;诸如未闭合的 [ 这类无法编译的模式不再“让每次文件编辑都以 Invalid regular expression 失败”,此类拒绝规则现在保护其字面拼写的路径;针对 Edit(C:\dir\(name)\**) 改进了设置错误提示,其中 \( 被解读为转义括号而非路径分隔符;Bash(ls) x 这类带尾随文本的规则会被报告为无效设置);围绕 Fable 5.1 发布的四项修复(/model 选择器会向可使用 Fable 5.1 的组织显示该模型,此前“只有手动输入 /model claude-fable-5-1 才会被接受”;提示缓存现在覆盖“工具结果之后附加的上下文,修复前这部分在每个工具调用回合都会作为未缓存输入重新发送”;会话中途更改 /effort 不再使提示缓存失效;model: fable 的代理会遵循 ANTHROPIC_DEFAULT_FABLE_MODEL 固定值上的 [1m] 标记,而不是“悄无声息地以 200K 上下文窗口运行”);自动压缩改进(“Opus 和 Fable 会话现在会在接近 1M token 上限前不久进行压缩,超大上下文的恢复性压缩也不再在 10 分钟时超时”);/cost 和状态栏 prompt_cache 字段新增的“可能的缓存未命中原因”一行(“例如工具定义或系统提示发生变化、闲置超过 TTL”);! bash 模式的例外(“在 ! bash 模式提示符下输入的命令改为在沙箱之外运行,即使开启了严格沙箱模式(sandbox.allowUnsandboxedCommands: false)也是如此,就像在您自己的终端中输入一样”);托管 CLAUDE.md 的变更(“托管的 CLAUDE.md(claudeMd)不再触发安全审批对话框;hooks、shell 命令、沙箱以及不安全的 env 设置仍需审批”);以及 Claude in Chrome 遵循“您所在组织的 Claude in Chrome 管理员设置;管理员将其关闭后,--chrome、/chrome 和浏览器工具将不可用”。严格沙箱模式的语义(allowUnsandboxedCommands: false 会完全忽略 dangerouslyDisableSandbox,每条命令都必须在沙箱中运行或列入 excludedCommands,/sandbox 的 Overrides 标签页将该状态标注为 Strict sandbox mode)来自沙箱文档,获取于2026年9月3日。 ↩↩↩↩↩↩↩↩↩↩↩↩

  213. Claude Developers(@ClaudeDevs)于2026年8月29日在 X 上发布的两条帖子:2093742321473065266,原文:“自9月14日起,我们将把 Pro、Max、Team 以及按席位计费的 Enterprise 方案在 Claude Code 中的标准每周限额永久提高 25%。在此之前,当前 50% 的提升将继续有效。”以及 2093742322525810912,原文:“与今天相比,这相当于 Claude Code 每周限额减少 17%。我们正在推进一些令人期待的变化,让您感觉从 Claude 获得更多,同时对用量拥有更高的可见性与控制力。”于2026年9月3日通过 syndication 端点获取(时间戳 2026-08-29T16:47Z)。150 到 125 的示例是本指南基于这两条声明的推算,并非 Anthropic 公布的数字。 ↩↩

  214. Claude Code v2.1.261 发布说明,发布于2026年9月4日19:58 UTC,当天已与权威 CHANGELOG 逐条交叉核对。核验时的 npm dist-tags:latest 与 next 均为 2.1.261,stable 为 2.1.236。快捷键变更原文:“提示符的按词编辑快捷键改为与 Bash 一致:Ctrl+W 向后删除到空白处,Alt+F 和 Alt+D 在词尾停下,标点作为分词符;keybindingFlavor 不再有任何效果。”以下内容的来源:/skill-doctor,它会显示哪些已加载的 skills 从未被使用以及它们占用了多少上下文,便于您裁剪;bashOutputMaxChars 与 taskOutputMaxChars 设置,它们可提高 Claude 在命令输出和后台任务输出被保存到文件之前以内联方式接收的字符数量,最高 128K 字符(这与 BASH_MAX_OUTPUT_LENGTH 是不同的机制,工具参考将后者定义为从命令工作输出文件回读的窗口,原文:它“设定 Claude Code 从工作文件回读到命令结果中的输出字符数:默认 30,000,硬上限 150,000”);auto 模式会把将内容打包进公共图表渲染器 URL 的链接(mermaid.live 之类,数据直接编码在 URL 中)视为上传,除非您主动要求,否则不再自动批准;以及 forceLoginMethod: "gateway" 会清除残留凭据,因此固定到网关的机器会忽略残留的 API 密钥或 claude.ai 登录并要求执行 /login,Bedrock、Vertex AI 和 Foundry 会话不受影响。 ↩↩↩↩↩↩↩

  215. Claude Code v2.1.265 发布说明,发布于2026年9月8日20:37 UTC,当天已与权威 CHANGELOG 逐条交叉核对(发布正文与 CHANGELOG 对应章节完全一致)。核验时的 npm dist-tags:latest 与 next 均为 2.1.265,stable 为 2.1.236;npm 上已发布的版本从 2.1.261 跳到 2.1.263 再到 2.1.265——2.1.262 和 2.1.264 从未发布(与 2.1.244/2.1.249/2.1.253-256 的情况相同)——而 2.1.263(9月6日发布)仅标注“错误修复与可靠性改进”。以下内容的来源:--plugin-dir 指向一个存放多个 plugins 的文件夹(“每个带有清单文件的子文件夹都会加载,运行期间新增或移除的子文件夹也会被识别”);两项提示缓存前缀修复,原文:“修复了恢复一个在前台生成的 subagent 时其工具列表和系统提示前缀发生变化、导致该代理的提示缓存无法复用的问题”以及“修复了代理队友和恢复后的 subagents 在后续回合中将 SubagentStart hook 上下文和预加载的 skills 移出提示前缀、导致提示缓存无法复用的问题”;非交互式会话(带 stream-json 输入的 -p、Agent SDK、云端会话)不再在每条新用户消息时重置 shell 工作目录,因此 cd 会跨回合保持;配置为 http 但仅支持旧版 HTTP+SSE 传输的 MCP 服务器现在会按 MCP 规范所述回退到 SSE;保存到磁盘的工具结果设有 1 GB 上限,且对话内预览会说明已保存文件是否被截断;托管设置中含有 forceLoginGatewayUrl 的机器从启动起就是 Claude apps 网关会话,与 forceLoginMethod: "gateway" 一样,残留的 claude.ai 登录或 API 密钥不会被使用;Claude apps 网关会话会将 OpenTelemetry 直接导出到网关托管设置在 OTEL_EXPORTER_OTLP_ENDPOINT 中指定的收集器,而不再经由网关中继(未指定收集器的会话仍使用中继),并且 Claude Desktop 和 Cowork 通过 Claude apps 网关发送的遥测数据新增了 user.email 和 user.groups,与终端会话保持一致;双键快捷键现在会等待第二个按键 3 秒,超时后显示提示,此前若第二个按键在一秒之后才到达(tmux 中常有此情况)则会静默取消;以及在提示中途输入的斜杠命令会以列表形式显示匹配项(非全屏模式下按 Tab 打开),而不是只给出单个建议,plugin 的 skill 也可以用其简短名称找到。 ↩↩↩↩↩↩↩↩↩↩↩

  216. Claude Code 发布说明 v2.1.266(2026年9月8日)、v2.1.267(9月9日)、v2.1.268(9月10日)、v2.1.269(9月11日)、v2.1.270(9月12日)、v2.1.271(9月14日)以及 v2.1.272(npm 发布于9月14日,GitHub release 发布于9月15日 00:42 UTC),每一份均已于2026年9月15日与权威 CHANGELOG 逐条交叉核对——全部七个版本的发布正文与其 CHANGELOG 章节完全一致。核对时(9月15日,约 13:15 太平洋时间)的 npm dist-tags:latest 2.1.272、next 2.1.273、stable 2.1.236;2.1.273(发布于9月15日 18:06 UTC)既无 GitHub release 也无 CHANGELOG 章节,因此本文不记录其内容;而 2.1.263 仍然只有“错误修复与可靠性改进”一句——始终没有补充任何内容。以下各项的来源(引文处为逐字引用):/output-style 的恢复(“新增 /output-style [name],用于列出并切换输出样式,包括通过 Remote Control 以及在云端和其他无头会话中使用”,v2.1.269);claude plugin eval(“针对 Claude Code 运行插件的评估套件,获得可评分、可复现的结果(JSON + HTML 报告)”,v2.1.269);Claude Code Remote 会话中的快速模式(“云端与自托管运行器:在组织允许的范围内,主机的快速模式设置或在会话中输入的 /fast 均会生效”,v2.1.271)以及 /fast off 的修复;maxEffortLevel 设置(“可置于顶层,或在 modelSettings 下按模型设置:在包括 Bedrock、Vertex 和 Foundry 在内的所有提供商上限制 effort 级别上限;用户仍可选择更低的级别”,v2.1.267);--system-prompt-snapshot off(v2.1.267);v2.1.267 的提示缓存稳定性批次修复(恢复会话时工具列表、工具描述与 MCP 公告被改写的问题;/model 切换时重新发送每个工具定义的问题,署名文本现改为一条对话备注;--system-prompt/--append-system-prompt 会话现只记录一次提示词与工具定义;会话中途加入的 MCP 与插件工具改为延迟定义);针对默认 effort 级别已固定的模型(Opus 4.7、Opus 4.8、Fable 5)的 effort: frontmatter 修复(v2.1.267);marketplace 反斜杠路径包含检查的修复(v2.1.267);任务跟踪工具的允许列表(“任务跟踪工具(TaskCreate/Get/Update/List、TodoWrite)现改为仅在 Claude 3.x、Opus 4.0–4.7、Sonnet 4.0–4.6、Haiku 4.5 上提供;在其他模型上请设置 CLAUDE_CODE_ENABLE_TODO_TOOLS=1”,v2.1.268);符号链接目录以及 env -C/eval 拒绝规则的修复(v2.1.268);WebFetch/Artifact 规则的拆分(“普通的 WebFetch 拒绝与询问规则不再适用于 Artifact 工具的读取和更新;如需拦截或把关,请使用 Artifact 规则(或 WebFetch(domain:claude.ai))”,v2.1.268);/plugin 的更改在关闭菜单时生效(v2.1.268);WebFetch 的 300 秒期限与 CLAUDE_CODE_WEBFETCH_DEADLINE_MS(v2.1.268);gatewayInternalNetworks、空 allow_cidrs 警告以及网关 pricing: 费率同步(v2.1.268),外加 multiplier 可高于 1、最大至 10(v2.1.271);${VAR} 与 git URL 的密钥防泄露修复(v2.1.268);claude auth status --json 中的 configDirectory(v2.1.268);第三方 ANTHROPIC_BASE_URL 的 HTTP 400 回归问题修复(v2.1.268);bashEditDiffEnabled(v2.1.269);署名提醒的修复(“修复了署名提醒覆盖 CLAUDE.md 或记忆规则中禁止提交与拉取请求署名的设置的问题;由托管设置指定的署名行仍然生效”,v2.1.269);环境变量 OTEL_METRICS_INCLUDE_REPOSITORY、CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS(1-256)、CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS(默认 3 秒)以及 CLAUDE_CODE_BG_TASKS_REPORT_RUNNING(v2.1.269);v2.1.247 键盘回归问题的修复以及通过 SSH 的 kitty 查询键盘支持(v2.1.269);Edit()/tee、Bash(tee:*) 以及前导 ! 的作用域修复(v2.1.269);启用沙箱的自动模式下 Bash、PowerShell 和 Monitor 的按命令 allowed_domains(v2.1.271);omitClaudeMd 代理 frontmatter 与 --agents JSON(v2.1.271);自动模式下内联 ! 与子代理交还机制的变更(v2.1.271);claude plugin install/update 的 --accept-command <sha256>(v2.1.271);--resume 在跨模型系列时保留 [1m](v2.1.271);无法读取的 managed-mcp.json 采取故障关闭(fail-closed)策略(v2.1.271);fmt/column、通配符展开、变量声明标志以及 blockReadsOutsideWorkingDirectories 检查器的修复(v2.1.271);以及 Markdown Artifact 渲染为带样式的文档页面,Artifact 监视数量上限提升至 10(v2.1.271)。v2.1.266 仅有一行(CLAUDE_CODE_USE_GATEWAY 回归问题修复),v2.1.270 也仅有一行(v2.1.269 git 提示回归问题修复),v2.1.272 则只有“错误修复与可靠性改进”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  217. Claude Code v2.1.273 发行说明,发布于2026年9月15日20:23 UTC,并已于2026年9月16日与权威 CHANGELOG 逐条核对:发行正文与 CHANGELOG 对应章节完全一致,各为64行。核验时的 npm dist-tags(9月16日,约10:00 PT):latest 为 2.1.273,next 为 2.1.273,stable 为 2.1.267,这是 stable 标签首次离开 2.1.236。以下各项的来源(引文均译自原文):deny 规则回退(“回退了 2.1.268 中的一项改动,该改动会在权限检查器无法分析的 Bash 命令行(eval、env -C)上检查 Read 和 Edit 的 deny 规则;time -p make build 之类的命令现在会重新提示,而不是被拒绝”);无法分析的命令与子 shell 修复(“修复了权限检查器无法完整分析的 Bash 命令在 permissions.blockReadsOutsideWorkingDirectories 下跳过提示的问题,以及绕过模式下子 shell 隐藏危险 rm 的问题”);记忆目录修复(“修复了 permissions.blockReadsOutsideWorkingDirectories:由仓库设置选定的记忆目录不再被加载进提示、被回忆、被索引或用于记忆提取”);网关分类器默认值(“暂时将 Bedrock、Vertex 和 Foundry 上的自动模式改为默认使用本地分类器;设置 CLAUDE_CODE_AUTO_MODE_SERVER=1 可改用平台的服务器端分类器”);提示头(“为 LLM 网关新增了 x-claude-code-request-class、x-claude-code-agent-type、x-claude-code-prev-tool-durations、x-claude-code-compaction 和 x-claude-code-context-compacted 请求头;通过 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 选择启用”);托管设置优先级修复(“修复了通过 MDM 或 managed-settings.json 设置的 allowManagedMcpServersOnly、deniedMcpServers 和 disableClaudeAiConnectors 在同时存在服务器托管设置时被忽略的问题”);上下文计量器修复(“修复了上下文计量器和自动压缩将 Advisor 工具轮次按约两倍于其真实上下文大小计算的问题,这曾导致自动压缩在真实窗口约一半时就触发”);提示缓存修复(“修复了 /login、/upgrade 和 /extra-usage 丢弃对话中先前思考内容的问题,该问题曾迫使下一次请求完整重写提示缓存”);遥测变更(“将 OTEL_LOG_TOOL_DETAILS=1 改为在成本和 token 指标上同时包含真实的 agent、skill、plugin 和 MCP 服务器名称”);/bug//feedback 数据最小化(“将 /bug 和 /feedback 报告改为仅包含最近一次 API 请求中的模型行为参数(模型、系统提示、工具),省略请求元数据和 CLAUDE_CODE_EXTRA_BODY 字段”);登录变更(“使用 Claude 账户登录时,现在也会请求访问您的 claude.ai plugins”);Remote Control 分叉(“新增了从 Claude 应用分叉以 claude --remote-control 或 /remote-control 启动的会话的功能;分叉会作为后台会话在您的计算机上运行”);以及 stream-json 修复(“修复了 SDK 和 --output-format stream-json 输出在 subagent 于运行中途被移至后台(例如通过 CLAUDE_AUTO_BACKGROUND_TASKS)后丢弃其剩余消息和最终报告的问题”)。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  218. Claude Code 发行说明 v2.1.274(发布于2026年9月17日00:12 UTC,108条要点)、v2.1.275(9月17日22:33 UTC,96条要点)和 v2.1.276(9月18日02:12 UTC,仅一行),均已于2026年9月17日与权威 CHANGELOG 逐条核对:三份发行正文与其 CHANGELOG 章节逐字节一致。核验时的 npm dist-tags(9月17日,约22:08 PT):latest 和 next 均为 2.1.276,stable 为 2.1.267。以下各项的来源(引文均译自原文):claude.ai 同步(“新增了将 claude.ai 账户上启用的 skills 和 plugins 同步到以该账户登录的终端会话的功能;可通过 syncClaudeAiSkills: false 或 syncClaudeAiPlugins: false 选择退出”,v2.1.275);立即发送键(“新增了立即发送键(ctrl+enter,或 ctrl+x ctrl+s),它会中断当前轮次并一次性发送所有排队消息;已发送和排队中的消息在模型接收之前显示为灰色”,v2.1.275);/plugin install <plugin> --marketplace <source>(“它会在安装插件之前主动提议添加该插件市场”,v2.1.275);npm 插件来源加固(“从 npm 来源安装的插件改为通过 npm pack --ignore-scripts 获取并进行完整性校验,因此包的安装脚本不再运行”,v2.1.275);已同步账户 skills 的 Write/Edit 结果(“现在会说明该更改未保存到您的账户,以及如何保存”,v2.1.275);标签页图标变更(“Artifact 工具改为在首次发布时要求提供一个单词的标签页图标,而非 emoji 网站图标”,v2.1.275);CLAUDE_CODE_MCP_STARTUP_WAIT_MS(“用于限制首个非交互式轮次等待 MCP 服务器连接的时长(0 = 不等待)”,v2.1.274);MCP 客户端默认值(“Bedrock、Vertex、Foundry 以及禁用遥测的安装改为默认使用 v2 MCP 客户端,并与直连 HTTP 服务器采用 MCP 2026-07-28 协商,与其他安装保持一致(选择退出:MCP_SDK_GENERATION=v1 或 MCP_PROTOCOL_NEGOTIATION=legacy)”,v2.1.274);旧版 HTTP+SSE 4xx 修复(“修复了配置为 http 且仅支持旧版 HTTP+SSE 的 MCP 服务器在以 422 或其他 4xx 错误响应首个请求时无法连接的问题”,v2.1.274);"type": "sdk" 跳过(“.mcp.json、设置、plugins 和 agent 文件中的 "type": "sdk" MCP 条目改为跳过并给出警告:只有 SDK 宿主应用才能注册进程内服务器”,v2.1.274);命名变更(“/status 的 GitHub 行改为显示‘Cloud sessions’,/web-setup、/ultrareview 和 teleport 消息改为使用‘cloud session’而非‘Claude Code on the web’”,v2.1.274);artifact 监视(“更改了本地会话中的 artifact 监视:在其他地方发布的新版本不再启动新一轮对话;Claude 会从之后的 Artifact 工具结果中得知”,v2.1.274);以及 v2.1.276 回归修复(“修复了当 ANTHROPIC_BASE_URL 指向代理或网关时所有请求均以 400 … Input tag 'advisor_20260301' 失败的问题(2.1.275 回归)”)。 ↩↩↩↩↩↩↩↩↩↩↩↩

  219. Claude Code 发行说明 v2.1.277(npm 发布于2026年9月18日16:22 UTC;GitHub 发行于18:06 UTC)和 v2.1.278(npm 发布于9月19日01:48 UTC;GitHub 发行于03:10 UTC),已于2026年9月21日与权威 CHANGELOG 核对。本指南中所有 v2.1.277 和 v2.1.278 条目的来源。关键引文:“新增 AGENTS.md 支持:在没有 CLAUDE.md 的项目中,Claude Code 会改为读取 AGENTS.md;可在 /config 的‘Project instructions’下更改(Bedrock、Vertex 和 Foundry 上尚不可用)”;“将 Claude API 和 Enterprise 用户以及 Bedrock、Vertex、Foundry 和网关上的自动模式改为默认使用服务器端分类器,该分类器不对分类器开销收费”;“在 /status 中新增 Auto mode server 行,显示本会话的自动模式分类器是否在服务器上运行”。于2026年9月21日获取的辅助文档:Memory 文档的 AGENTS.md 章节(加载矩阵、Project instructions 的取值、agents-md@builtin 的 pluginConfigs 位置、不会被读取的文件)和自动模式分类器请求费用(回退通知的文本及送达方式、/status 行的取值、网关透传,以及该变量的临时状态)。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  220. Claude Code v2.1.280 发行说明(npm 发布于2026年9月22日15:44 UTC;GitHub 发行于16:38 UTC),已于2026年9月22日和9月23日与权威 CHANGELOG 核对。本指南中所有 v2.1.280 条目的来源。9月23日的 npm dist-tags:latest 和 next 均为 2.1.280,stable 为 2.1.267;2.1.279 从未发布。关键引文:“新增 Claude Opus 5.5(claude-opus-5-5),现为默认 Opus 模型”,并附“1M 上下文,每百万 token $4/$20,缓存读取 $0.20/Mtok”;“将 Pro 和 Team Standard 套餐的默认模型从 Sonnet 改为 Opus,与 Max、Team Premium 和 Enterprise 保持一致”;“修复了安全检查无结果时自动模式不停顿地反复拒绝操作的问题;现在重试会退避,连续十次后该轮次将停止并显示消息”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  221. Anthropic 官方模型文档,获取于2026年9月22日:模型概览与Claude Code 模型配置文档。Claude Opus 5.5 的信息来源:Claude API ID 与别名为 claude-opus-5-5;Amazon Bedrock ID 为 anthropic.claude-opus-5-5,Google Cloud、Microsoft Foundry 以及 Claude Platform on AWS 的 ID 均为 claude-opus-5-5;定价为“输入 $4 / MTok,输出 $20 / MTok”;缓存读取按基础输入价格的 5% 计费(“提示缓存读取的费用为基础输入价格的 10%(Claude Fable 5.1 与 Claude Mythos 5.1 为 2.5%,Claude Opus 5.5 为 5%)”),即 $0.20/MTok;思考模式标注为“自适应(始终开启)”,与 Claude Fable 5.1 的标注相同,而 Claude Sonnet 5 则标注为“自适应”;默认 effort 为 medium(Claude Fable 5.1 与 Claude Sonnet 5 均为 high);上下文窗口为 1M token;最大输出为 128K token,且 Opus 5.5 被列入在 Message Batches API 上“通过 output-300k-2026-03-24 beta 请求头支持最多 300k 输出 token”的模型之列;可靠知识截止日期为2026年6月,训练数据截止日期为2026年6月,与 Claude Fable 5.1 持平;退役时间“不早于2027年9月22日”;概览页建议“大多数工作负载从 Claude Opus 5.5 入手”;以及 Claude Opus 5 现已与 Fable 5、Opus 4.8、4.7、4.6、4.5 和 Sonnet 4.6、4.5 一同列入旧版模型表。模型配置文档中按套餐划分的默认模型表原文如下:“Pro、Max、Team、Enterprise 与 Anthropic API:默认为 Opus 5.5”;“Claude Platform on AWS、Amazon Bedrock 与 Google Cloud 的 Agent Platform:默认为 Opus 5.5”;“Microsoft Foundry:默认为 Sonnet 4.5”;opus 别名表(Anthropic API、Claude Platform on AWS、Amazon Bedrock 与 Google Cloud 的 Agent Platform 均解析为 Opus 5.5;Microsoft Foundry 解析为 Opus 4.6);版本下限(“Opus 5.5 需要 Claude Code v2.1.280 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。”);以及历史说明(“在 v2.1.280 之前,default 在 Pro 与 Team Standard 上解析为 Sonnet 5,而自 v2.1.219 起,在 Max、Team Premium、Enterprise、Anthropic API、Claude Platform on AWS、Amazon Bedrock 与 Google Cloud 的 Agent Platform 上解析为 Opus 5。”)。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  222. Anthropic 平台文档,获取于2026年9月23日:Claude Opus 5.5 模型页面、迁移至 Claude Opus 5.5以及定价。Opus 5.5 定价的来源(每 MTok $4/$20,缓存读取 $0.20,“Claude Opus 5.5 上的缓存命中与刷新按基础输入价格的 0.05 倍计费”)、快速模式定价的来源(Opus 5.5 为 $8/$40;Opus 5 与 Opus 4.8 为 $10/$50),以及破坏性变更的来源:“四项破坏性变更会影响已在 Claude Opus 5 上运行的代码:思考无法关闭,强制工具调用会返回错误,思考块与模型及对话绑定,并且在 Claude API 与 Google Cloud 上不再接受早先的 computer_20251124 计算机使用工具。”迁移指南提供了 tool_choice 的细节(any 与 tool 会返回 400,包括在 token 计数端点上)、针对 computer_20251124 的 Bedrock 例外,以及将工具调用之间的文本作为 thinking 块返回这一变更。 ↩↩↩↩↩↩↩↩↩↩

  223. Claude Code 文档,获取于2026年9月23日:模型配置、快速模式、记忆、权限模式、自动模式分类器请求计费以及MCP。以下内容的来源:基于内容的回退(对 Fable 5.1、Fable 5 与 Opus 5.5 而言,“被标记为生物学相关的请求会在 Opus 5 上重新运行,被标记为网络安全相关的请求会在 Opus 4.8 上重新运行”);effort 默认值(Opus 5.5 上为 medium,顶层的 effortLevel 设置对其不生效);“在 Opus 5.5 或 Fable 系列模型上无法关闭思考”;Bedrock、Agent Platform 与 Foundry 上 Opus 4.8 及更高版本的 200K 上下文窗口,以及 Foundry 的 opus 解析为 Opus 4.6;快速模式的模型支持情况,以及自 v2.1.280 起 Opus 5.5 成为快速模式的默认模型;AGENTS.md 差异表、首次会话的注意事项,以及 v2.1.280 之前 /memory 与 /context 不会列出直接读取的 AGENTS.md 这一说明;内置的起始模式表(Pro、Max 与 Team 为自动模式;Enterprise、Console API 密钥与第三方提供商为手动模式);服务端检查清单(其中包含 Claude Platform on AWS);以及 Tool Search 在会话开始时仅加载工具名称与服务器说明。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  224. Claude Code v2.1.281 发行说明(npm 发布于2026年9月23日 17:01 UTC;GitHub 发行版于 19:19 UTC 发布;共 176 条要点,与权威的 CHANGELOG 中的 2.1.281 章节完全一致,该文件获取于2026年9月24日,其版本从 2.1.280 连续到 2.1.281,没有缺口)。本指南中所有 v2.1.281 条目的来源。9月24日的 npm dist-tag:latest 与 next 为 2.1.281,stable 为 2.1.273。关键引述:“将立即发送(ctrl+enter 或 ctrl+x ctrl+s)改为将正在运行的工具移至后台,而不是取消当前轮次”;“CLAUDE_CODE_AUTO_MODE_SERVER 现在也适用于直连 Anthropic API 的情况:0 表示退出服务端自动模式分类器(此时本地分类器会计入用量),1 表示选择加入”;“--dangerously-skip-permissions 与自动模式下危险 rm 命令的提示改为等待 2 分钟以获取回答,随后拒绝该命令并给出改写提示”;“在 settings.json 中新增 "attribution": false,用于隐藏所有提交与 PR 的署名”。/agents 向导的移除来自同一 CHANGELOG 的 2.1.198 章节:“移除了 /agents 向导;请让 Claude 创建或管理 subagents,或直接编辑 .claude/agents/。”自动模式分类器计费文档(获取于2026年9月24日)当时仍写着“直连 Anthropic API 时不会读取该变量”;到9月26日,该页面已改为“直连 Anthropic API 时,该变量需要 Claude Code v2.1.281 或更高版本。”同日的设置参考记录了 attribution 对象,并将 includeCoAuthoredBy 标记为已弃用;到9月26日,该页面也记录了 false 值。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  225. Claude Code v2.1.282 发行说明(npm 发布于2026年9月24日 15:56 UTC;GitHub 发行版于 18:38 UTC 发布;共 86 条要点,与权威的 CHANGELOG 中的 2.1.282 章节完全一致,获取于2026年9月26日)。本指南中所有 v2.1.282 条目的来源。关键引述:“自动模式改为在关闭遥测的情况下直连 Anthropic API 时默认使用服务端分类器(CLAUDE_CODE_AUTO_MODE_SERVER=0 可退出)”;“项目设置与本地设置改为忽略那些开启导出、设置其端点或捕获内容的 OpenTelemetry 变量,例如 CLAUDE_CODE_ENABLE_TELEMETRY 与 OTEL_LOG_*”;“新增 maxProseWidth 设置,用于限制 Claude 在宽终端中的正文宽度”;“新增 allowClaudeInChromeWithManagedMcp 托管设置,允许 claude --chrome 与独占的 managed-mcp.json 并行运行”;“当托管设置或 --settings 设定了 allowUnsandboxedCommands: false,或托管设置设定了 allowManagedDomainsOnly: true 时,sandbox.excludedCommands 改为忽略项目设置与本地设置中的条目”;“anthropic-skills 或 claude-ai 命名空间下的 skill 文件夹、命令文件与工作流命令不再加载”。 ↩↩↩↩↩↩↩

  226. Claude Code v2.1.283 发布说明(npm 于2026年9月25日 18:46 UTC 发布;GitHub 发布于 21:50 UTC;共94条条目,与权威 CHANGELOG 中的 2.1.283 章节完全一致,该 CHANGELOG 于2026年9月26日获取,覆盖 2.1.281 至 2.1.283,中间没有缺口)。本指南中所有 v2.1.283 条目的来源。9月26日的 npm dist-tags:latest 与 next 为 2.1.283,stable 为 2.1.274。关键引文:“在第三方提供商上运行或已关闭遥测的交互式会话,在未配置权限模式时改为以 auto 模式启动;permissions.defaultMode 仍可覆盖该行为”;“新增 deniedModels 托管设置,用于屏蔽特定模型,即使 availableModels 允许它们”;“新增 /doctor prompt-audit(亦可用 /checkup prompt-audit),用于审计您的 CLAUDE.md 文件、skills、agents 和命令中为旧模型编写的提示模式”;“在网关提示标头中新增 x-claude-code-prompt-id”;“在 Opus 已具备 1M 上下文窗口的情况下,/model 选择器的 Opus 行和默认模型的名称不再显示‘(1M context)’”;“撤销了 2.1.282 对 claude-ai 名称的保留”。 ↩↩↩↩↩↩↩↩↩↩↩

  227. Claude Code 文档,2026年9月26日获取。权限模式:“自 Claude Code v2.1.283 起,auto 模式是所有方案和提供商上交互式终端与 VS Code 会话的内置初始权限模式”;claude -p 和 Agent SDK 以 default 模式启动;“从 v2.1.282 起,不获取功能标志的会话(例如因为您关闭了遥测)在任何类型的会话中都默认向服务器询问。”Auto 模式分类器计费:“直接连接 Anthropic API 时,该变量需要 Claude Code v2.1.281 或更高版本。”设置参考:attribution“或设为 false 以隐藏所有署名。false 值需要 Claude Code v2.1.281 或更高版本”;maxProseWidth、deniedModels 和 availableModelsMatch 条目;“Claude Code 在 env 中忽略的变量”下的 OpenTelemetry 组。LLM 网关协议:“直接连接 Anthropic API:默认发送”。Skills:保留的 anthropic-skills 名称。设置参考现在还记录了 spinnerTipsOverride 的 tipsFile 和提示对象(“提示对象、tipsFile、label 以及 Scope 行的规则……需要 Claude Code v2.1.247 或更高版本”)以及 timeFormat 和 timeZone 键。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  228. Claude Code v2.1.284 发布说明(npm 于2026年9月28日 17:11 UTC 发布;GitHub 发布于 18:02 UTC;共100条条目,与权威 CHANGELOG 中的 2.1.284 章节完全一致,该 CHANGELOG 于2026年9月29日获取,覆盖 2.1.283 至 2.1.285,中间没有缺口)。本指南中所有 v2.1.284 条目的来源。关键引文:“新增 Claude Sonnet 5.5(claude-sonnet-5-5),现为 Anthropic API 上的默认 Sonnet 模型”;“交互式终端和 VS Code 会话在未配置权限模式时改为以 auto 模式启动,适用于所有方案和提供商;permissions.defaultMode 仍可覆盖该行为”;“Ultracode 改为 /effort 中的独立开关(按 Tab,或使用 /effort ultracode [on|off]):它不再强制 xhigh effort 级别,且在任何 effort 级别下都保持开启”;“在交互式终端中新增 /mcp reconnect all,可一次性重试所有连接失败或需要身份验证的 MCP 服务器”;“在 auto 模式读取工作目录之外内容前的提示中,新增‘是,但下次再次询问’选项”;“新增 effortSlider:decreaseEffort、increaseEffort 和 toggleUltracode 键绑定操作”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  229. Claude Code v2.1.285 发布说明(npm 于2026年9月29日 17:32 UTC 发布;GitHub 发布于 19:27 UTC;共136条条目,与权威 CHANGELOG 中的 2.1.285 章节完全一致,于2026年9月29日获取)。本指南中所有 v2.1.285 条目的来源。9月29日的 npm dist-tags:latest 与 next 为 2.1.285,stable 为 2.1.280。关键引文:“在第三方提供商上运行或已关闭遥测的 claude -p 和 Python Agent SDK 会话,在未配置权限模式时改为以 auto 模式启动,与交互式会话一致;--permission-mode 仍可覆盖该行为”;“新增 allowedProviders 托管设置,用于限制一台机器可使用的 API 提供商”;“新增 claude --desktop,可在当前目录打开 Claude 桌面应用,或配合 --continue / --resume <id> 打开某个会话”;“新增 CLAUDE_CODE_DISABLE_WEB_FETCH 环境变量,用于关闭 WebFetch 工具”;“后台 Bash 和 PowerShell 命令改为在时限到达后停止(即配合 run_in_background 使用的 timeout,默认 30 分钟,最长 2 小时)”;“使用自定义 ANTHROPIC_BASE_URL 的会话改为使用具备 1M 上下文窗口的模型的 1M 上下文窗口(Opus 4.7+、Sonnet 5+、Fable);如果您的网关止步于 200K,请运行 /autocompact 200k”;“沙箱设置已更改,项目设置无法再放宽或关闭管理员强制要求的沙箱”;“/config chrome=true 改为引导您前往 /config 面板,而不再默认启用 Chrome 中的 Claude”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  230. Anthropic 文档,2026年9月29日获取。模型配置:别名表写作“Anthropic API | Opus 5.5 | Sonnet 5.5”;“Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本”;effort 默认值为 high,“但 Opus 5.5 和 Sonnet 5.5 默认为 medium”;“在 Opus 5.5、Sonnet 5.5 或 Fable 模型上无法关闭思考”;对于 Sonnet 5.5,“被标记为网络安全类的请求会在 Sonnet 5 上重新运行。被标记为生物学类的请求以拒绝告终”;“通过 /effort 或 ultracode 设置开启或关闭 ultracode 不会改变 effort 级别”,而“--effort ultracode 标志……会将其开启,并同时把级别设为 xhigh”。Claude Sonnet 5.5 模型页面:2026年9月28日发布;1M 上下文,最大输出 128K;每 MTok $2/$10,缓存读取 $0.20;可靠知识截止日期为2026年6月;退役时间不早于2027年9月28日;相对 Sonnet 5 的五项破坏性变更。权限模式:“自 Claude Code v2.1.283 起,auto 模式是所有方案和提供商上交互式终端与 VS Code 会话的内置初始权限模式”;初始模式表仍将 claude -p 或 Agent SDK 列为 default。 ↩↩↩↩↩↩↩↩↩↩↩

  231. Claude Code v2.1.286 发布说明(npm 于2026年9月30日 17:14 UTC 发布;GitHub 发布于 19:10 UTC;共88条条目,与权威 CHANGELOG 中的 2.1.286 章节完全一致,该 CHANGELOG 于2026年10月1日获取,覆盖 2.1.285 至 2.1.287,中间没有缺口)。本指南中所有 v2.1.286 条目的来源。关键引文:“--bare 改为只连接命令行中指定的 MCP 服务器,不向模型发送任何系统提醒,也不启动任何后台任务”;“修复了当 Anthropic API 拒绝您的默认模型或模型别名所解析到的模型时每一轮都失败的问题:Claude Code 现在会在同一层级的上一代模型上重试一次”;“/hooks 改为打开一个按事件分组的已配置 hooks 列表”;“修复了 claude auth status 将 Console 登录所存储的 API 密钥报告为 claude.ai 的问题;现在报告为 api_key”;“插件安装改为拒绝属于 git 仓库或文件夹的 npm 来源,且仅从注册表软件包安装插件依赖”;“更改了失败的 API 请求的重试方式:现在一个上限覆盖整个模型调用,因此在默认重试设置下,一次失败的调用最多发送 14 个请求”。 ↩↩↩↩↩↩

  232. Claude Code v2.1.287 发布说明(npm 于2026年10月1日 16:59 UTC 发布;GitHub 发布时间为 18:00 UTC;共 106 条要点,与规范 CHANGELOG 的 2.1.287 章节完全一致,获取于2026年10月1日)。本指南中所有 v2.1.287 条目均以此为来源。10月1日的 npm dist-tags:latest 与 next 为 2.1.287,stable 为 2.1.285。关键引述:“Opus 4.7+ 和 Fable 在 Bedrock、Vertex、Foundry 以及 Claude apps 网关上默认改用 1M 上下文窗口,无需 [1m] 后缀(CLAUDE_CODE_DISABLE_1M_CONTEXT=1 可保持 200K)”;“新增 Claude Mods:插件现在可以修改更深层的行为”;“新增 You should know,这是一个内置 mod,由一个辅助代理为您把关,标记出您或 Claude 可能遗漏的事项”;“新增来自采用 2025-11-25 协议的 MCP 服务器的 URL 提示”;“MCP 服务器的 alwaysLoad: false 改为将该服务器的全部工具推迟到工具搜索之后再加载”;“设置 CLAUDE_AX_PREPARK_MS=50 可恢复该暂停”;“消息被标记后的自动模型切换改为保留您当前的 effort 级别,而不是采用新模型的默认值”;“对于 Claude Code 文件工具会直接拒绝的文件,整工具级的 Bash allow 规则和放行类 hooks 现在会对 shell 写入操作发出提示,而不是直接运行”;“在 OpenTelemetry 的 user_prompt 事件中新增 prompt_text”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  233. Claude Code 文档,获取于2026年10月1日。权限模式:对于 claude -p 或 Agent SDK,“在会获取功能标志的会话中为 default。在不获取功能标志的会话中,例如使用第三方提供商或关闭遥测时,自 Claude Code v2.1.285 起为 auto”。Mods 概览:“Mods 需要 Claude Code v2.1.287 或更高版本,并且默认启用”;“Mods 未经沙箱隔离”;自 v2.1.287 起忽略 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS;cc-plugin-you-should-know “默认禁用”。模型配置:回退之后,Claude Code “保留被标记请求所使用的 effort 级别,而不采用该模型的默认 effort”;“Opus 4.6 和 Sonnet 4.6 仅能通过其 [1m] 变体达到 1M”;网关 1M 段落以及 /autocompact 200k。Amazon Bedrock 和 Agent Platform:“若要为手动固定的模型启用它,请在模型 ID 后追加 [1m]。”环境变量:CLAUDE_AX_PREPARK_MS “默认值 0……在 v2.1.287 之前,默认值为 50”;CLAUDE_CODE_DISABLE_WEB_FETCH “WebSearch 工具仍然可用。需要 Claude Code v2.1.285 或更高版本”。无头模式:“在 v2.1.286 之前,这些限制只是部分生效”。Agent 视图:n:<text> 过滤器以及“内容恰好为 /stop 的回复会立即停止该会话。”设置参考:allowClaudeInChromeWithManagedMcp(“需要 Claude Code v2.1.282 或更高版本”)和 allowedProviders 条目。MCP 页面未列出 bareElicitationCapability。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  234. Claude Code 规范 CHANGELOG 的 2.1.288 章节,获取于2026年10月6日,以及同日读取的 @anthropic-ai/claude-code npm 注册表元数据:2.1.288 发布于2026年10月2日 18:30 UTC,2.1.289 发布于10月3日 20:12 UTC,2.1.290 发布于10月5日 18:12 UTC,2.1.291 发布于10月6日 03:32 UTC,2.1.292 发布于10月6日 17:10 UTC;dist-tags latest 与 next 为 2.1.292,stable 为 2.1.285。CHANGELOG 从 2.1.287 连续记录到 2.1.292,没有缺口。本指南中所有 v2.1.288 条目均以此为来源。关键引述:“claude project purge 改为 claude purge;旧名称仍然可用,并会打印一条提示”;“后台命令时间限制改为仅在无人值守会话(-p、Agent SDK、CI、云端)中生效;终端、桌面应用和 VS Code 会话不设限制”;“为 /code-review 新增 --max-findings <n>|all”;“新增 CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS 用于关闭结构化输出”;“客户端 auto 模式分类器改为忽略指向 Claude Sonnet 5.5 或 Opus 5.5 的 ANTHROPIC_DEFAULT_SONNET_MODEL 固定设置,转而使用 Claude Sonnet 5”;“请求现在会在 60 秒后超时(按服务器设置 requestTimeout)”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩

  235. Claude Code 规范 CHANGELOG 的 2.1.289、2.1.290 和 2.1.291 章节,获取于2026年10月6日。本指南中所有 v2.1.289、v2.1.290 和 v2.1.291 条目均以此为来源。关键引述:“修复了 2.1.290 中的一个回归问题:云端会话可能丢失对权限提示的回答”;“修复了 2.1.288 中的一个回归问题:退出时可能丢失会话的最后几条消息”;“交互式会话的 WebSearch 配额改为随时间补充(每小时 100 次调用;CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR 设置速率,0 表示关闭),而不是在 200 次调用后终止”;“Claude in Chrome 已调整,项目的设置文件不再能将其启用;请使用 --chrome、/chrome 或您的用户设置”;“Bash 工具在运行 pyright 之前改为先请求权限,该命令不再被视为只读命令”;“CLAUDE_CODE_DISABLE_ATTACHMENTS 已调整,代码仓库的 .claude/settings.json 或 .claude/settings.local.json 不再能设置它”;“新增面向队友的 agent.spawn、跨插件 hook 事件统一的 agent id,以及 $.agent.list() 中的 idle 和 waiting 状态”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  236. Claude Code 规范 CHANGELOG 的 2.1.292 章节,获取于2026年10月6日。本指南中所有 v2.1.292 条目均以此为来源。关键引述:“新增 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 环境变量,用于在重试过载(529)请求时为退避设置更长的基础延迟”;“为 Agent 工具新增 effort 参数”;“为 claude plugin install 新增 --marketplace <source>”;“本地(stdio)MCP 服务器连接在所有安装方式(包括 Bedrock、Vertex 和 Foundry)上默认改为协商协议版本 2026-07-28;MCP_PROTOCOL_NEGOTIATION=legacy 可选择退出”;“安全:修复了 PreToolUse hook 批准和 auto 模式会绕过网络(UNC)路径文件读取权限提示的问题”;“agent 名称改为最多允许 256 个字符”。 ↩↩↩↩↩↩↩↩↩↩

  237. Claude Code 文档,获取于2026年10月6日。环境变量:CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS“需要 Claude Code v2.1.288 或更高版本”;CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 仍为“(默认:200)”;没有 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 或 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR 的条目。CLI 参考和 Agent 视图:claude attach 和 claude logs 的部分会话名称需要 v2.1.290;列出了 claude purge。Claude 目录:“在 v2.1.288 之前,该命令为 claude project purge。”工具参考:“在 v2.1.288 之前,它适用于每个会话”(指后台命令时间限制)。代码审查:--max-findings“需要 Claude Code v2.1.288 或更高版本”。快捷键绑定:agents:find、agents:rename、agents:previousGroup、agents:nextGroup,v2.1.288。记忆:“路径范围规则在 Claude 使用 Read、Write 或 Edit 工具时触发”。MCP:stdio 协商仍被描述为“对 Claude Code v2.1.285 或更高版本,在 Claude Code 获取功能标志的会话中”开启。插件 CLI 参考:--marketplace 仅在 /plugin install 下列出;市场清单验证行为“需要 Claude Code v2.1.289 或更高版本”。Mods 参考:标注为“截至 v2.1.289”编写;列出了带 e.isTeammate 的 agent.spawn 以及 $.ui 的 selection。Sub-agents:effort 仅作为 frontmatter 字段记录;name 是“最多 256 个字符的唯一标识符”,名称“超过 256 个字符”的文件会被跳过并在调试日志中记录一条错误(10月6日晚些时候重新获取)。设置参考:claudeInChromeDefaultEnabled 的作用域为“全局配置”。命令:/claude-api 列出了 managed-agents-onboard。在 Chrome 中使用 Claude Code:“在 CLI 会话中运行 /chrome 并选择默认启用”;该页面未提及 v2.1.290 的项目设置变更。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  238. Claude Code 官方 CHANGELOG 的 2.1.293 至 2.1.296 各节,获取于2026年10月11日,以及同日读取的 @anthropic-ai/claude-code npm 注册表元数据:2.1.293 发布于2026年10月7日 17:18 UTC,2.1.294 发布于10月8日 03:42 UTC,2.1.295 发布于10月8日 18:22 UTC,2.1.296 发布于10月9日 16:58 UTC;dist-tags 中 latest 和 next 为 2.1.296,stable 为 2.1.287。GitHub 发布说明正文(发布于 18:10、05:03、19:48 和 19:28 UTC)分别包含 56、2、143 和 79 条要点,与 CHANGELOG 完全一致。本指南中每一项 v2.1.293 至 v2.1.296 内容的来源。关键引文:“新增 Claude Haiku 5.5(claude-haiku-5-5),现为 Anthropic API 上的默认 Haiku 模型”,具有“1M 上下文,每 Mtok $0.10/$0.50(超过 100K 的提示为 $0.50/$2.50)”;“为命令和 HTTP hooks 新增 onFailure: \"block\":无法启动、超时或以意外代码退出的 hook 会阻止该操作,而不是放行”;“将预先发送的 MCP 工具描述以及 MCP 服务器指令的默认上限从 2,048 个字符改为 4,096 个字符”;“模型通过工具搜索加载的 MCP 工具描述改为在 16,384 个字符处截断,而不是 2,048”;“将 subagents 改为最多从 skills 字段预加载 32 个 skills,每个仅加载一次”;“为 subagent frontmatter 和 --agents 定义新增 autoCompactWindow,使 subagent 可以比主对话的窗口更早自动压缩”;“更新了 /cost、状态栏、--max-budget-usd 和 SDK 的费用数字,将 Sonnet 5.5 缓存读取定价为每百万 token $0.10(原为 $0.20)”;“为 Read 工具新增 allow_large 选项”;“撤销了 2.1.281 中对自动模式拒绝消息的更改”;“修复了在托管设置将 forceLoginMethod 设为 gateway 但未设置 forceLoginGatewayUrl 的机器上,已保存的 Claude 应用网关登录被忽略的问题(2.1.295 中的回归)”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  239. Claude Haiku 5.5 模型概览、模型概览、定价页面,以及 Claude Code 的模型配置页面,获取于2026年10月11日。模型页面:“发布于2026年10月7日”;“上下文窗口:1M token · 最大输出:128K token”;输入“提示不超过 100,000 个 token 时为 $0.10 / MTok;提示超过 100,000 个 token 时为 $0.50 / MTok”,输出按同一分界为“$0.50 / MTok”和“$2.50 / MTok”,缓存读取为“$0.01 / MTok”和“$0.05 / MTok”;思考“自适应”,默认 effort 为 medium,可靠截止日期和训练截止日期均为“2026年6月”,退役时间“不早于2027年10月7日”;“同样的文本计为比 Claude Haiku 4.5 多约 30% 的 token”;Bedrock ID 为 anthropic.claude-haiku-5-5。定价页面:“请求的提示长度计入其全部输入 token,包括缓存读取和缓存写入。每个请求单独计价”;“Claude Opus 5.5 和 Claude Sonnet 5.5 上的缓存命中和刷新按基础输入价格的 0.05 倍计价”,“在 Claude Sonnet 5.5 上为 0.10 美元”。模型配置:别名表在 Anthropic API 上将 haiku 解析为 Haiku 5.5,而在 AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上解析为 Haiku 4.5;“Haiku 5.5 请使用 v2.1.293 或更高版本”;“一旦 haiku 解析为 Haiku 5.5,在 Haiku 4.5 上保存的会话将在 Haiku 5.5 上恢复”;“Haiku 模型始终可用且无法禁用,因此每位成员至少保留一个可用模型”。 ↩↩↩↩↩↩↩↩

  240. Claude Code 文档,获取于2026年10月11日。Hooks:onFailure 为“hook 失败时该操作的处理方式:\"continue\"(默认)或 \"block\"……需要 Claude Code v2.1.295 或更高版本”;它所计入的失败情形为“无法启动”、“退出代码不是 0 或 2”、“HTTP 错误”、“超时”和“输出无效”;“设置为 \"block\" 时,失败的效果与该事件上退出代码 2 的效果相同,但在 PermissionRequest 上则是拒绝该请求”;“该字段对以下项不起作用”:Stop、SubagentStop、TaskCompleted、TeammateIdle 以及后台(async、asyncRewake)命令 hooks。环境变量:CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS“起始延迟(毫秒),用于替代默认的 500……请给出 500 到 32000 之间的整数毫秒值……需要 Claude Code v2.1.292 或更高版本”;CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS“未设置时,等待没有上限。需要 Claude Code v2.1.295 或更高版本”;CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR“在交互式终端会话中默认为 100。在非交互式会话中默认为 0,即关闭补充”;CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS“Claude 使用 allow_large 参数进行的读取在上下文窗口有空间时可以超过此限制”;VERTEX_REGION_CLAUDE_HAIKU_5_5“在 v2.1.293 中新增”;没有 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 或 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 的条目。Sub-agents:skills 字段预加载“列表中最多前 32 个不同的名称”;每次调用的 effort 参数“会覆盖 effort 字段,并在 subagent 恢复时继续生效……需要 Claude Code v2.1.292 或更高版本”;autoCompactWindow 不在所列的 frontmatter 字段之中。状态栏:agentType“需要 Claude Code v2.1.293 或更高版本”。MCP:“Claude Code 默认会向 stdio 服务器请求该修订版本。若要让 stdio 通道服务器保持使用早期握手,请将 MCP_PROTOCOL_NEGOTIATION 设为 legacy,这会让所有服务器都保持使用早期握手。”插件 CLI 参考:claude plugin install 接受 --marketplace <source>,“需要 Claude Code v2.1.292 或更高版本”。Mods 参考:仍标注为“截至 v2.1.290”编写;没有 $.ui.notify 或 prompt.autocomplete 的条目。 ↩↩↩↩↩↩↩↩↩

  241. Claude Fable 5.1 模型概览与Claude Fable 与 Mythos 5.1 发布公告,Anthropic;2026年9月3日获取。以下内容的来源:2026年9月1日的发布日期;每百万 token 10 美元/50 美元的定价,缓存读取为每百万 token 0.25 美元(即输入价格的 0.025 倍,也就是 2.5%,而标准比例为 10%,这一费率仅 Fable 5.1 与 Mythos 5.1 享有),缓存写入按标准价格计费(5 分钟缓存每百万 token 12.50 美元,1 小时缓存每百万 token 20 美元);1M 上下文窗口与 128K 最大输出;始终开启的自适应思考,effort 默认为 high;可靠知识截止日期为 2026年6月,训练数据截止日期亦为 2026年6月;退役时间不早于 2027年9月1日;Bedrock ID anthropic.claude-fable-5-1;相对于 Fable 5 的三项破坏性变更(强制工具调用会返回错误、早期模型无法读取其思考块、编辑先前轮次会使思考块失效)以及五项增量变更(按消息设置 effort,测试版;轮次级系统消息,测试版;通过 display: "updates" 在工具调用之间推送进度更新,测试版;更便宜的缓存读取;内容来源信息);以及 Claude Mythos 5.1 作为 Project Glasswing 下规格相同、仅限邀请使用的模型。概览给出的最低版本要求——“Fable 5.1 需要 Claude Code v2.1.255 或更高版本”——指向的是一个未发布的内部构建;v2.1.257 为何才是您能安装的第一个版本,请参阅 211。模型概览,同次获取:Fable 5 现已列入旧版模型(Legacy models)表,与 Opus 4.8、4.7、4.6、4.5 以及 Sonnet 4.6、4.5 并列。 ↩↩↩↩↩

  242. 模型配置,2026年9月3日获取。原文:“除非您设置了 ANTHROPIC_DEFAULT_FABLE_MODEL,否则 fable 别名解析为 Fable 5.1。在 v2.1.255 之前,它解析为 Fable 5。”best 别名是“您可用范围内最新的 Fable 模型”。各套餐的默认模型未因此次发布而改变:高级套餐为 Opus 5,Pro 与 Team Standard 为 Sonnet 5。 ↩↩↩↩

  243. 设置与CLI 参考,2026年9月3日获取。设置页关于 permissions.defaultMode:auto 与 bypassPermissions 这两个值“在项目或本地设置中不生效”。CLI 参考页关于 --effort:该标志“覆盖”默认 effort,“仅对本次会话有效,不会持久保存”——所选值不再延续到会话结束之后。 ↩↩↩

  244. 托管设置,2026年9月3日获取。managedSourcesBehavior 的来源:默认仍为首个来源优先(first-wins);将其设为 “merge” 后会合并所有管理员来源,大多数键以优先级更高的来源为准,列表类型的键取各来源的并集,沙箱锁定项则取任一来源设置的最严格值;每个键只从设置了它且优先级最高的来源读取;此外,managedSourcesBehavior 是控制键而非策略键,因此仅设置了该键的来源不算提供了策略键。 ↩↩↩

  245. Claude Code CHANGELOG,2.1.247 一节,2026年8月27日获取。npm 于 2026年8月26日 18:02 UTC 发布了 2.1.247(dist-tag latest:2.1.247;2.1.244 仍未发布),GitHub 的 v2.1.247 发布随后于 23:06 UTC 推出,官方文档更新日志将该版本的日期记为 2026年8月26日。原文:“新增 SendFeedback 工具:当会话中出现问题时,Claude 可为您起草一份反馈报告,供您在 /feedback 中审阅并发送(可通过 feedbackDrafts 设置关闭)”;“为 spinnerTipsOverride 新增 {id, text, cooldownSessions, priority} 条目、tipsFile 和 label,使组织可以在内置提示之外轮播自己的提示”;“在 Bash 权限提示中新增一条指向自动模式的提示,并提供一键式‘是,并切换到自动模式’选项”;“新增 /claude-api cost-optimize,用于分析现有项目的 Claude API 开销,并以逐项可度量的方式调整各类成本杠杆(缓存、token 精简、批处理、effort、模型选择)”;“更新了 /claude-api 技能,加入 Admin API 相关内容(组织成员、邀请、工作区、API 密钥、速率限制报告、工作负载身份联合、CMEK)”;“将 Sonnet 5 的默认自动压缩窗口改为其完整的 1M 上下文,因此使用 1M 窗口的会话现在会在约 967K token 时自动压缩,而非约 934K”;“跨会话的对等消息现在默认折叠为一行 Message from @<sender>: <first line> 预览;按 Ctrl+O 可展开完整内容”。设置参考尚未记录 feedbackDrafts 或新的 spinnerTipsOverride 键;截至本次更新,CHANGELOG 是它们唯一的来源。 ↩↩↩↩↩↩↩↩↩

  246. Claude Code 发布说明 v2.1.235(8月18日)、v2.1.236(8月19日)、v2.1.237与v2.1.238(8月20日),已于 2026年8月20日与官方 CHANGELOG.md 交叉核对(最新标题:2.1.238)。以下行为均原文引自发布说明:spellcheck“使用您已安装的 aspell、hunspell 或 ispell”;ANTHROPIC_DEFAULT_MODEL“设定新会话启动时使用的模型,而 /model 的选择仍会覆盖它并在重启后保留(与 ANTHROPIC_MODEL 不同)”;Concise 风格“先给结果,省去开场白和过程叙述,但工作同样做得一丝不苟”;keybindingFlavor 设为 "readline" 时“提示符中的 Ctrl+W 会向前删除到上一个空白处,与 Bash 中一致”;headersHelper“运行一条生成 HTTP 请求头的命令(例如短期令牌)”,目录条目仅在安装/更新时执行,项目/插件/代理作用域则会剥离凭据环境变量;自动模式下“Monitor 允许规则在自动模式激活期间会被搁置”;macOS 沙箱“通配符读取拒绝规则(例如 **/.env)现在在允许读取的区域内优先生效……且无法通过重命名被拒绝的文件来绕过”。 ↩↩↩↩↩↩

  247. Claude Code 文档,获取于2026年8月26日。模型配置,effort 级别表:“Fable 5 | low、medium、high、xhigh、max”以及“Opus 5、Sonnet 5、Opus 4.8 和 Opus 4.7 | low、medium、high、xhigh、max”(不存在 min 级别);“/effort 菜单还提供 ultracode。Ultracode 是一项 Claude Code 设置,而非模型 effort 级别:它向模型发送 xhigh,并额外让 Claude 为实质性任务编排动态工作流”;“将 ultracode 传给 --effort 标志或 Agent SDK 的 effortLevel 值需要 Claude Code v2.1.203 或更高版本”;“持久化的 effortLevel 设置和 CLAUDE_CODE_EFFORT_LEVEL 环境变量不接受 ultracode。”自动模式配置:“运行 /permissions 并选择 Auto mode 选项卡。该选项卡需要 Claude Code v2.1.246 或更高版本,且仅在您的会话可使用自动模式时才会显示”;“Claude Code 将来自托管设置或 --settings 标志的条目显示为只读,并把您在该选项卡上所做的每项更改保存到 ~/.claude/settings.json”;“当您向某个部分添加第一条规则时,Claude Code 还会插入 "$defaults",以使内置规则继续生效。”权限:“把 * 放在子命令之后。在 git log --oneline main 中,git 是程序,log 是子命令……Bash(git log *) 只允许 git log 命令,而 Bash(git *) 允许所有 git 命令。对于 * 位于子命令之前的允许规则,例如 Bash(git * main),Claude Code 会在启动时发出警告。”错误:“Bash(git * main) 同样会批准 git -c core.fsmonitor=<script> diff main,其中 -c 会让 git 运行该命令所指定的程序”;修复方法:“将子命令之前的 * 替换为您真正想要的确切值:用 Bash(git checkout main) 代替 Bash(git * main)。”网页版 Claude Code:“网页版 Claude Code 目前处于研究预览阶段,面向 Pro、Max 和 Team 用户,以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户”;“在终端中运行 /web-setup,将本地的 gh CLI 令牌同步到您的 Claude 账户”;“Team 和 Enterprise 的所有者可以通过 claude.ai/admin-settings/claude-code 上的 Quick web setup 开关禁用 /web-setup”;“启用了零数据保留(Zero Data Retention)的组织无法使用 /web-setup 或其他云会话功能。”成本,/usage:“Loops:为近期运行过的、消耗最大的若干 /loop 或其他计划任务各列一行,按总 token 数排序,其余任务只显示数量。Claude Code 会报告每个任务的触发频率、运行次数、总 token 数和单次运行 token 数,以及上次运行时间。Claude Code 以任务的提示词作为行的键,因此您停止后重新创建的循环仍然只占一行。需要 Claude Code v2.1.242 或更高版本。” ↩↩↩↩↩↩↩↩↩↩

  248. Claude Code 文档,获取于2026年8月26日。托管设置,“Claude Code 使用哪个托管来源”:“当您的组织提供多个托管来源时,Claude Code 会使用其中第一个提供了至少一个策略键的来源,并忽略其余来源而不是将它们合并,仅‘从每个管理员来源读取的键’一节所涵盖的少数跨来源键除外”;“Claude Code 不会对跳过的来源显示任何警告。要查看它使用了哪个来源,请运行 /status”;顺序,优先级从高到低:“1. 远程设置,由 claude.ai 作为服务器托管设置下发,或由 Claude 应用网关下发……2. MDM 或操作系统级策略:macOS plist 或 HKLM 注册表键 3. 托管设置文件,即合并在一起的 managed-settings.d/*.json 和 managed-settings.json 4. HKCU 注册表,适用于 Windows,以及在 WSL 上当 HKLM 注册表或 Windows 托管设置文件开启了 wslInheritsWindowsSettings 且 HKCU 值也设置了该项时。”提示缓存:“除非您自行选择 TTL,否则 Claude Code 仅在 Claude 订阅且处于套餐所含用量范围内时才请求一小时 TTL”;按分桶列出的表格给出:主对话:一小时(订阅,套餐用量范围内)/ 五分钟(用量额度、API 密钥或云服务商),其他所有:“五分钟,但由服务器控制的辅助请求除外,它们获得一小时”/ 五分钟;“两个设置和两个环境变量都需要 Claude Code v2.1.242 或更高版本”;优先级:“1. FORCE_PROMPT_CACHING_5M=1,强制两个分桶都使用五分钟 2. 该分桶的环境变量 3. 该分桶的设置 4. ENABLE_PROMPT_CACHING_1H=1,为两个分桶都请求一小时 5. 该请求所属分桶的默认值。”设置参考,modelPicker:“作用范围:用户或托管。Claude Code 从托管设置、--settings 和用户设置中读取该键,并在项目设置和本地设置中忽略它,以免您克隆的仓库能够改写选择器的标签”;“类型:对象,包含一个由行组成的 options 数组和一个可选的 replaceBuiltInOptions 布尔值”;“availableModels 允许列表仍然适用于这些行”;“标签改变的是选择器显示的内容,而不是 Claude Code 运行的模型”;“需要 Claude Code v2.1.242 或更高版本”(本指南的示例复用了该页面自带的 Bedrock 行)。promptCacheTtl 和 subagentPromptCacheTtl:“作用范围:任意文件”;“类型:字符串,取值为 "5m"……"1h" 之一”;“需要 Claude Code v2.1.242 或更高版本。”设置示例中的提供商 ID 来自 Amazon Bedrock(“主模型 | Opus 5,例如 us-* 区域中的 us.anthropic.claude-opus-5”)、Google Cloud(“主模型 | claude-opus-5”)和 Microsoft Foundry(“export ANTHROPIC_DEFAULT_OPUS_MODEL=’claude-opus-4-8’”,即该页面提及的最新 Opus ID)。 ↩↩↩↩↩↩↩

  249. Claude Code CHANGELOG,2.1.246 和 2.1.245 两节,获取于2026年8月26日;npm 于2026年8月25日 04:45 UTC 发布 2.1.245,于 19:17 UTC 发布 2.1.246,二者各有对应的 GitHub 发布版本。2.1.246 原文:“为子命令之前带有通配符的 Bash 允许规则(例如 Bash(git * main))新增了启动警告,因为这类规则同样会匹配插入在子命令之前的选项”;“在 /permissions 中新增了 Auto mode 选项卡,用于查看和编辑自动模式分类器规则”;“改进了 /cd:新目录的项目设置、hooks、.mcp.json 服务器(需经过常规的批准提示)、skills 和 agents 现在会在切换后立即生效,而不必等到 --resume”;“改进了 subagent 结果:在 maxTurns 限制处停止的 subagent 现在会将其输出标记为部分结果返回,并附带通过 SendMessage 继续它的提示,而不再显示为已完成”;“/goal:空闲会话现在每个目标最多对长时间运行的后台工作发起三次检查;您的下一条消息允许再发起三次”;“修复了 Bash 权限检查,使其对带有悬空 && 或 || 运算符的格式错误命令始终要求批准”;“修复了发往 Anthropic 的遥测和指标请求携带为第三方网关(ANTHROPIC_BASE_URL)配置的 API 密钥的问题;现在凭据只会发送到其自身的主机”;“在回合结束的耗时行末尾添加了该回合的完成时间”。2.1.245 原文:“修复了在搭载 glibc 2.44 的 Linux 发行版(例如 Arch Linux、CachyOS 和 Fedora Rawhide)上启动时崩溃的问题”。 ↩↩↩↩↩↩↩↩↩

  250. Claude Code CHANGELOG,2.1.243 一节,于2026年8月26日获取。npm 于2026年8月24日 19:16 UTC 发布了 2.1.242,并于同日 23:10 UTC 发布了 2.1.243;2.1.242 没有对应的 CHANGELOG 小节,2.1.244 从未发布,而文档将 modelPicker、promptCacheTtl 以及 /usage 中 Loops 各行的最低版本固定为 v2.1.242。原文如下:“为 /usage 新增了 Loops 细分:每个循环的运行次数、总 token 数、每次运行的 token 数以及最近一次运行时间,便于发现失控或过于频繁的 /loop 任务”;“新增 modelPicker 设置:用一个有序、带标签的模型列表(任意 id 写法,包括 Vertex/Bedrock id)定制 /model 选择器,可追加到内置阵容之后或将其完全替换”;“新增 promptCacheTtl 和 subagentPromptCacheTtl 设置,使 API 密钥用户和云服务商用户可以在主对话上保持 1 小时的提示缓存,而 subagents 仍保持 5 分钟”;“新增 modelPricing 托管设置,使 /cost、状态行和遥测成本数据采用组织签约的按模型费率及折扣系数,而非标价”;“在 /login → Anthropic Console 下新增了无密钥登录方式:‘Sign in with your Console account’(推荐),与创建 API 密钥的选项并列,使不允许使用 API 密钥的组织也能登录”;“在 /status 中新增 Skipped sources 行,列出虽然存在但因更高优先级的托管来源处于生效状态而未被应用的托管设置来源(例如 managed-settings.json)”;“在 /mcp 和 /plugins 中,为身份验证由您的组织统一管理的 claude.ai 连接器添加了 managed 标记”;“新增提示,引导尚未为网页版 Claude Code 连接 GitHub 的 claude.ai 用户使用 /web-setup”;“在 /status 中新增一行,显示是否已为网页版 Claude Code(Pro/Max)连接 GitHub,未连接时指向 /web-setup”;“在 /tasks 和代理详情对话框中显示每个 subagent 所运行的模型(及 effort 级别)”;“改进了 /loop:Claude 无事可做的连续唤醒,现在会在终端中折叠为一行,而不再逐条打印”;“修复了在较旧的 GitHub CLI(不带 gh auth token)已完成身份验证的情况下,/web-setup 仍反复要求登录的问题”;“改进了原生安装和自动更新的下载体积:二进制文件现采用 zstd 压缩(Linux x64 上约 75 MB,而非 340 MB)”;“更改了跨会话消息收件箱套接字的行为:对 30 秒内未发送完整行的连接予以关闭;向其投递的脚本应在数据就绪后再建立连接”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  251. Anthropic 定价,于2026年8月26日获取。原文说明:“Claude Sonnet 5 每百万输入/输出 token $2/$10 的定价,在发布时曾宣布为截至2026年8月31日的推介价,现已成为标准价格。原定于2026年9月1日上调至每百万输入/输出 token $3/$15 的计划将不会执行。”定价表中 Claude Sonnet 5 的价格为输入 $2 / MTok、输出 $10 / MTok。Claude Code CHANGELOG,2.1.243:“更新了 /model 选择器和内置的 claude-api skill,将 Sonnet 5 每 Mtok $2/$10 的定价显示为标准标价,而非限时促销价”。模型配置中关于 sonnet[1m] 别名的说明:“当 sonnet 已解析为自带 1M 上下文窗口的 Sonnet 5 时无效;在 LLM 网关之后,则为 Sonnet 5 选择 1M 窗口”;以及:“在 Anthropic API 上,Sonnet 5 始终以 1M 上下文窗口运行。不存在 200K 变体,没有可供选择的 [1m] 后缀,任何套餐都无需使用额度。” ↩↩↩↩

  252. Claude 文本水印的工作原理,Anthropic,2026年8月14日。文中所有引语的出处:“未来的 Claude 模型生成的文本将包含水印”;现有模型在8月2日之前过渡期的状态(“我们也在努力为这些模型添加水印”);基于 SynthID-Text 的原理及随机源机制;对轻度编辑/完全重写的耐久性;译文自带水印;计划推出的检测 API;“Claude 很可能在某个阶段参与过该内容”以及无法区分撰写与编辑的局限;对质量无影响的声明。代码稀疏性细节(“对实际生成的代码影响微乎其微”,水印体现在注释等任意性选择中)来自 Anthropic,见 TechCrunch 8月15日的后续报道。监管触发因素:欧盟《人工智能法案》第50条,自2026年8月2日起对新推出的系统生效。 ↩↩↩↩↩↩

  253. Claude Code v2.1.234 发行说明,2026年8月17日。新增:claude.ai 用量限制重置后自动续接会话(可通过 /config → “Continue automatically at usage limit” 关闭)、CLAUDE_CODE_PROJECT_DIR_NAME、CLAUDE_CODE_GOAL_CHECKIN_MINUTES(默认 30;0 表示退出)并在出现不可恢复错误时由 /goal 自行清除、轮次中途可用的 /permissions 和 /add-dir、GitLab MR 页脚徽标、selection:clear、claude-api skill 上下文从约 200k 缩减至约 25k、在预批准文件访问中一律拒绝 NT 命名空间(\??\)路径,以及 Remote Control 的账户切换/effort 同步修复。本次会话于2026年8月17日(PST)验证:GitHub 的 releases 列表中最新发布为 v2.1.234(发布于 2026-08-17T20:20Z)。 ↩↩

  254. Claude Code v2.1.233 发行说明,2026年8月14日。新增:--worktree/claude agents 对 GitLab MR 的支持(!N)、可选启用的 forward_user_identity 网关设置、CLAUDE_CODE_TOOL_MEMORY_LIMIT(针对 Bash 命令的 Linux cgroup)、CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS;在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上默认移除待办/任务跟踪工具(可用 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 恢复);修复了 v2.1.232 在 Windows 上自动模式审批的回归问题,并回退了 v2.1.232 中 Cygwin 符号链接和输入重定向的权限变更,待推出范围更窄的版本;NTLM \??\ 路径验证修复、MCP v2 重连修复、Notification hook 与 Linux 空闲 CPU 修复、内置 skill 别名遮蔽修复。本次会话于2026年8月15日(PST)验证:GitHub 的 releases 列表中最新发布为 v2.1.233(发布于 2026-08-14T22:20:57Z)。 ↩↩

  255. Claude Code v2.1.231 与 v2.1.232 发行说明,2026年8月13日。v2.1.231:针对预注册客户端的 MCP OAuth 重定向 URI 修复。v2.1.232:subagent fork 默认开启并继承提示缓存;可通过 @ 提及活动会话,并以裸名称精确匹配进行 SendMessage 投递;每台机器唯一的会话名称;/config 中新增对话框过期和跨会话入站的设置行;GitLab 令牌系列脱敏、glab 凭据保护以及 GitLab plugin 市场;additionalMarketplaces/allowedMarketplaces 别名;网关桌面覆盖层 schema 验证和策略条目启动验证;/advisor 中加入 Fable 5;PowerShell、Cygwin 符号链接和嵌套 git 信任的安全修复。本次会话于2026年8月14日(PST)验证:GitHub 的 releases 列表中最新发布为 v2.1.232(发布于 2026-08-13T23:29:59Z)。 ↩↩↩↩

  256. Claude Code v2.1.228 发行说明,2026年8月11日。以修复为主的版本:TUI 重绘停滞、Windows git 发现、/tui 模型回退、跨会话收件箱初始化与内联消息显示、Remote Control /resume 历史泄露、自托管 runner 的 checkout hook 与清理缺口修复、记忆文件夹清理、plugin 缓存符号链接保护、市场整条目设置合并、延迟工具提醒去重;加固了从 claude.ai 同步的 skills(不得遮蔽命令/MCP、描述经过净化、禁止 !/@ 执行);Vertex 凭据快速失败;Write 工具在较新模型上采用与 Edit 相同的覆盖规则;从首次使用提示中移除了过时的自动模式成本说明。 ↩

  257. Claude Code v2.1.229 发布说明,2026年8月12日。新增 claude remote-control --continue、面向自托管运行器的服务器下发 hooks、网关流式传输的 SSE 保活 ping、带 mode: "link" 的插件市场 command 源、ListAgents 的 offline/cloud 标签、工作流扇出前缀错峰(CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0 可禁用)、沙箱域名列表对带方括号的 IPv6 采取失败即关闭策略、/commit-push-pr 危险标志提示、Windows 上必须指定 --base-dir、VSCode 会话分组以及可调整大小的 /btw。修复内容包括流式输出重复、窄终端 RangeError 崩溃、\\?\/UNC 路径崩溃、自动模式归属标头失败、网关拒绝 1M /model、MCP OAuth 127.0.0.1 重定向、GitHub Action 评审发布、IDE 诊断停滞。当前会话核验于2026年8月12日(PST):GitHub 发布列表显示 v2.1.229(发布于 2026-08-12T20:56:22Z)为最新版本。 ↩↩↩↩↩↩↩↩

  258. Claude Code v2.1.227 发布说明,2026年8月10日。错误修复与打磨版本:过期登录令牌上的订阅层级功能标志评估、claude-code-action 在 GitHub 托管运行器上配合 allowed_non_write_users 时的 Bash 失败、/tui 回退恢复、斜杠命令菜单高亮,以及事件循环停滞的减少。当前会话核验于2026年8月11日(PST):GitHub 发布列表显示 v2.1.227(发布于 2026-08-10T22:56:53Z)为最新版本。 ↩

  259. 向您的其他 Claude Code 会话发送消息,Anthropic Claude Code 文档。访问于2026年8月8日。以下内容的来源:投递结果(delivered/held/refused)、crossSessionInbound 语义及权限模式类别默认值、dialogExpiry 的五分钟默认值和 100 条暂存上限、接收端的四项限制、传输方式表和文件系统可见性规则、-p/裸模式下的套接字行为、各平台的自有子进程验证、CLAUDE_CODE_MESSAGING_SOCKET 导出时机、isolatePeerMachines 任一作用域为 true 即生效的语义、循环节流与 50 条未读消息上限、可用性(macOS/Linux/WSL 2;不支持原生 Windows;不支持 Bedrock/AWS 上的 Claude Platform/Google Agent Platform/Microsoft Foundry),以及对 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DO_NOT_TRACK 和 DISABLE_GROWTHBOOK 的功能标志依赖。 ↩↩↩↩↩↩↩↩↩↩↩↩

  260. Claude Code v2.1.190 发布说明 及 Claude Code 更新日志(权威版)。2026年6月24日。v2.1.190:仅包含错误修复与可靠性改进——没有面向用户的功能、设置、命令或定价变更。(v2.1.188 和 v2.1.189 未发布。)当前会话核验于2026年6月24日(PST):GitHub 发布列表和 code.claude.com/docs/en/changelog 上的权威更新日志确认 v2.1.190 为最新版本。 ↩

  261. Claude Code v2.1.170 发布说明、Claude Code 更新日志(权威版) 以及 Anthropic 新闻:Claude Fable 5。2026年6月9日。v2.1.170 使 Claude Fable 5 可在 Claude Code 中选用(执行 claude update 后使用 /model claude-fable-5)——这是高于 Opus 的新层级,模型 ID 为 claude-fable-5,1M 上下文/128K 输出,每百万 token $10/$50,配备安全分类器,遇到网络安全/生化/蒸馏类查询时回退至 Opus 4.8,并在2026年6月22日前逐步向订阅计划推出。Fable 5 与 Opus 4.8 共享相同的请求接口(仅支持自适应思考;已移除 temperature/top_p/top_k 和 budget_tokens),但新增一项破坏性变更——显式传入 thinking: {type: "disabled"} 会返回 HTTP 400,因此若要在不思考的情况下运行,请省略该参数。此版本还修复了从 VS Code 集成终端(或任何继承 Claude Code 环境变量的 shell)启动的会话无法保存转录且不在 --resume 下显示的问题。定价、上下文窗口和请求接口细节已与随附的 claude-api 模型目录(缓存于 2026-05-26)交叉核对。Claude Code 特有的 Fable 5 行为——fable/best 别名、完整的 low–max 推理强度范围(默认 high)、无法禁用的思考(会话开关/alwaysThinkingEnabled/MAX_THINKING_TOKENS=0 均无效)、claude-fable-5[1m] 扩展上下文变体,以及 ANTHROPIC_DEFAULT_FABLE_MODEL/DISABLE_PROMPT_CACHING_FABLE 配置——已于2026年6月10日对照 Claude Code 模型配置文档 核验。当前会话核验于2026年6月9日至10日(PST):GitHub 于6月9日(17:23Z)发布的 v2.1.170 确认为最新版本。 ↩↩↩↩

  262. Claude Code v2.1.169 发布说明 及 Claude Code 更新日志(权威版)。2026年6月8日。新增 --safe-mode 标志和 CLAUDE_CODE_SAFE_MODE 环境变量(启动时禁用 CLAUDE.md、plugins、skills、hooks 和 MCP 服务器,便于排查问题)、/cd 命令(将会话移至新的工作目录而不破坏提示缓存),以及 disableBundledSkills 设置和 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 环境变量(对模型隐藏内置 skills、工作流和内置斜杠命令)。另有约 20 项修复:换行行的上/下键导航、重连时及 IDE 类型配置上的企业 MCP 策略执行、使用 claude.ai 凭据时 30–50ms 的 macOS UI 停滞、claude -p 在 Windows 上的性能、Remote Control 重连、Windows Git Credential Manager 弹窗、自定义状态栏页脚提示、过期的远程会话提示、claude agents --json 遗漏被阻塞会话、TaskCreate 输入自动修复、更低的流式传输 CPU 占用、恢复 Vertex/Foundry 空闲超时、skill 标签对比度,以及后台会话标志在 retire→wake 过程中的保留。当前会话核验于2026年6月9日(PST):权威更新日志和 GitHub 发布列表确认 v2.1.169 为最新版本。 ↩↩↩

  263. Claude Code v2.1.166 发布说明、Claude Code v2.1.167 发布说明、Claude Code v2.1.168 发布说明 及 Claude Code 更新日志(权威版)。2026年6月6日。v2.1.166 新增 fallbackModel 设置(主模型过载/不可用时按顺序尝试最多三个回退模型),将 --fallback-model 扩展到交互式会话,并在遇到意外的不可重试 API 错误时用回退模型重试一轮;在拒绝规则的工具名位置支持 glob("*" 拒绝所有工具),而允许规则会拒绝非 MCP 的 glob;强化跨会话消息,使来自其他 Claude 会话经 SendMessage 转发的消息不再具有用户权限;使 MAX_THINKING_TOKENS=0、--thinking disabled 和按模型的思考开关能够在默认思考的模型上禁用思考;并让 claude update 在下载前先宣布目标版本,另有图像处理、远程会话稳定性和终端渲染(JetBrains、WezTerm/Ghostty)方面的修复。v2.1.167 和 v2.1.168(均为6月6日)仅为错误修复/可靠性版本,没有单独记录的面向用户变更。当前会话核验于2026年6月6日(PST):权威更新日志和 GitHub 发布列表确认 v2.1.168 为最新版本。 ↩↩↩↩↩

  264. Claude Code v2.1.163 发布说明与Claude Code 变更日志(权威版)。2026年6月4日;变更日志从 v2.1.160 直接跳至 v2.1.163,161/162 未曾发布。新增 requiredMinimumVersion/requiredMaximumVersion 托管设置(版本超出批准范围时拒绝启动)、带 --enabled/--disabled 筛选的 /plugin list、用于提供非错误反馈且让当前轮次继续进行的 Stop/SubagentStop hookSpecificOutput.additionalContext、/btw 的“按 c 复制”原始 markdown、skills 中的 \$ 字面美元符号转义,以及 stdio MCP 服务器在 --resume 时接收会话的 CLAUDE_CODE_SESSION_ID。修复内容包括:claude -p 在永不退出的后台命令上挂起、Bedrock/Vertex/Foundry 下 claude -p 在 CI=true 时要求提供 Anthropic 密钥、v2.1.154 的 $TMPDIR 回归问题导致 bazel/受 EDR 保护的 Go 无法运行、Windows 上 OneDrive/只读会话环境的 EEXIST 错误、组织托管的权限规则生效延迟、后台会话在更新过程中丢失任务、hook 的 if: "Bash(...)" 过度匹配 $()/$VAR,以及 ~ 路径拒绝规则未能拦截 $HOME 引用。2026年6月4日(PST)本会话验证:权威变更日志确认 v2.1.163 为最新版本。 ↩↩

  265. Claude Code v2.1.160 发布说明与Claude Code 变更日志(权威版)。2026年6月2日。新增在写入 shell 启动文件(.zshenv、.zlogin、.bash_login)和 ~/.config/git/ 之前弹出权限提示;acceptEdits 现在会在写入可授予代码执行权限的构建工具配置文件(.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/ 等)之前先行询问。对单个文件执行 grep/egrep/fgrep 现在即可满足“先读后改”检查。动态工作流的触发关键词由 workflow 更名为 ultracode(在提示输入框中以紫色高亮显示);“workflow”一词不再触发运行。移除了 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE(现为空操作)以及启动时的 JetBrains 插件安装建议。另有约 25 项修复:WSL 选中即复制改经 PowerShell 互操作而非 OSC 52 实现、claude agents 会话恢复时丢失聊天记录并重新运行原始提示、夜间退役的后台会话丢失对话、claude --bg 冷启动时的“socket missing”竞争条件、Windows 后台会话在 CPU 高负载下输入无响应、Apple Terminal/tmux 上的终端同步输出残影、claude agents 视图中的 CJK 输入法光标位置、Windows 超链接终端上 file:///C:/... 链接被改写、语音模式在非 ASCII 项目/分支名称下失效、第三方提供商上的自动模式不可用提示现在指向 CLAUDE_CODE_ENABLE_AUTO_MODE 而非归咎于模型、无法运行 xhigh 的模型不再提供 /effort ultracode 选项、SDK 下的模型未找到错误不再建议使用 --model、vim 中 v$ 复制后 p 的粘贴位置,以及后台会话拆除时先发 SIGTERM 再发 SIGKILL。2026年6月2日(PST)本会话验证:code.claude.com/docs/en/changelog 上的权威变更日志确认 v2.1.160 为最新发布版本。 ↩↩

  266. Claude Code v2.1.155 发布说明、Claude Code v2.1.156 发布说明、Claude Code v2.1.157 发布说明、Claude Code v2.1.158 发布说明、Claude Code v2.1.159 发布说明,以及Claude Code 变更日志(权威版)。v2.1.155 与 v2.1.156(2026年5月29日)发布了同一项 Opus 4.8 思考块变异修复,该问题曾表现为 API 错误。v2.1.157(2026年5月29日)让 .claude/skills/ 插件无需在市场注册即可自动加载,新增 claude plugin init <name> 脚手架,为 /plugin 提供参数自动补全,允许 EnterWorktree 在会话中途于 Claude 管理的 worktree 之间切换,在代理完成后保持后台 worktree 处于未锁定状态,以便 git worktree remove/prune 无需手动解锁即可生效,在 OTEL_LOG_TOOL_DETAILS=1 时于 tool_decision 遥测事件中包含 tool_parameters,并修复了以下问题:无法处理的图片导致崩溃(现改为文本占位符)、桌面 / IDE / SDK 界面在 auto/bypass 模式下的沙箱网络权限提示、后台会话停靠即退役、代理列表中按 Esc 取消“正在打开…”、后台 worktree 被 30 天保留清理孤立、--resume 的后台子代理报告、tmux + VS Code + Cursor + Windsurf 中的终端渲染 / 剪贴板、WSL 图片 / 截图 / 拖拽路径、长时间恢复对话的性能,以及 /terminal-setup 在集成终端中禁用 GPU 加速。v2.1.158(2026年5月30日)通过 CLAUDE_CODE_ENABLE_AUTO_MODE=1 在 Bedrock、Vertex 和 Foundry 上为 Opus 4.7 与 Opus 4.8 开放自动模式。v2.1.159(2026年5月31日)仅为内部基础设施更新,未宣布任何面向用户的变更。2026年5月31日(PST)本会话验证:code.claude.com/docs/en/changelog 上的权威变更日志确认了 v2.1.155–v2.1.159 条目;v2.1.159 确认为最新发布版本。 ↩↩↩↩

  267. Claude Code v2.1.151 发布说明、Claude Code v2.1.152 发布说明、Claude Code v2.1.153 发布说明、Claude Code v2.1.154 发布说明,以及Claude Code 变更日志(权威版)。v2.1.151(2026年5月23日)仅为内部基础设施更新。v2.1.152(2026年5月27日)引入 /code-review --fix 将修复直接应用到工作树、disallowed-tools skill/命令 frontmatter、/reload-skills、SessionStart hook 的 reloadSkills/sessionTitle 输出、MessageDisplay hook 事件、pluginSuggestionMarketplaces 托管设置、--fallback-model 会话中途切换、取消自动模式的选择加入要求、vim / 反向历史搜索,以及渲染、性能和可靠性修复。v2.1.153(2026年5月28日)为插件市场新增 skipLfs,让 /model 保存为新会话默认值(按 s 仅限当前会话,并以 modelPicker:thisSessionOnly 键绑定取代 modelPicker:setAsDefault),并将 COLUMNS/LINES 写入状态栏环境变量;macOS 后台代理会保留“隐私与安全性”授权;另有 25 项以上修复,涵盖有状态 MCP 的 tools/list 重连循环、自定义网关 OAuth 凭据泄露、子代理 MCP 策略强制执行、Windows 安装程序 / 更新通道修复,以及后台会话附加的可靠性。v2.1.154(2026年5月28日)将 Opus 4.8 设为默认模型,默认努力级别为 high,并新增 /effort xhigh 级别,引入可通过 /workflows 在后台编排数十至数百个代理的动态工作流,使 Opus 4.8 上的快速模式以 2 倍标准费率提供 2.5 倍速度,为除 Haiku/Sonnet/Opus 4.7 及更早版本之外的所有模型默认启用精简系统提示,将多选题提示收窄至确实无法自行决断的决策,将 /simplify 恢复为仅做清理的审查并与 /code-review --fix 的找 bug 流程分离,将 /effort 滑块标签改为“Faster”/“Smarter”(更快/更智能),新增 claude agents 的 ! <command> 后台 shell 会话以及 claude --bg --exec '<command>',允许插件声明 defaultEnabled: false,在 /plugin 的 Discover 中将建议插件固定到当前目录,使流式工具执行始终开启,向 stdio MCP 子进程环境传递 CLAUDE_CODE_SESSION_ID 和 CLAUDECODE=1,将未批准的 .mcp.json 服务器标记为 ⏸ Pending approval 而非自动连接,并弃用 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE(6月1日移除;请改用 /model claude-opus-4-6[1m] 再执行 /fast on)。2026年5月28日(PST)本会话验证:code.claude.com/docs/en/changelog 上的权威变更日志确认了 v2.1.151–v2.1.154 条目;v2.1.154 确认为最新发布版本。 ↩↩↩↩

  268. Claude Code CHANGELOG——2026年4月一致性审计中记录的 23 个环境变量的综合参考。OTel 导出器(OTEL_LOGS_EXPORTER、OTEL_METRICS_EXPORTER、OTEL_TRACES_EXPORTER)在 v2.1.85 中新增了 none 禁用处理。敏感字段门控:OTEL_LOG_TOOL_DETAILS(v2.1.85 tool_parameters)、OTEL_LOG_TOOL_CONTENT 和 OTEL_LOG_USER_PROMPTS(v2.1.101 选择启用,默认视为敏感)。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 会禁用发行说明获取(v2.0.17);设置后,v2.1.110 还会在无头模式/SDK 下停止用于自动生成标题的 Haiku 请求。API/模型:CLAUDE_CODE_EXTRA_BODY(v2.1.113 修复:Vertex/subagent 配合 output_config.effort 时不再返回 400)、CLAUDE_CODE_MAX_CONTEXT_TOKENS(早已存在;v2.1.98 修复了与 DISABLE_COMPACT 的交互问题)、CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS(v2.1.0)、CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK(v2.1.83)、ANTHROPIC_BETAS(v2.1.78 针对 Haiku 的修复)、ANTHROPIC_SMALL_FAST_MODEL(v0.2.125 起不再转义 Bedrock ARN 中的斜杠)。Plugins/MCP:CLAUDE_CODE_PLUGIN_CACHE_DIR(v2.1.72 修复了字面波浪号目录问题)、CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE(v2.1.90,离线友好)、CLAUDE_CODE_MCP_SERVER_NAME + CLAUDE_CODE_MCP_SERVER_URL(v2.1.85 headersHelper 上下文)。Shell/IDE:CLAUDE_CODE_SHELL_PREFIX(v1.0.61)、CLAUDE_CODE_GIT_BASH_PATH(v2.1.98,Windows)、CLAUDE_CODE_EXIT_AFTER_STOP_DELAY(v2.0.35 SDK 空闲)、CLAUDE_CODE_AUTO_CONNECT_IDE(v1.0.61)。企业:CLAUDE_CODE_PROXY_RESOLVES_HOSTS(v2.0.55 从默认开启改为选择启用)、CLAUDE_CODE_API_KEY_HELPER_TTL_MS(apiKeyHelper 刷新机制及 5 分钟默认值于 v0.2.74 加入;用于覆盖 TTL 的环境变量于 v0.2.117 加入)。另有:ENABLE_PROMPT_CACHING_1H_BEDROCK——ENABLE_PROMPT_CACHING_1H 的 Bedrock 专用别名;已在 v2.1.108 中弃用,但仍会生效并附带弃用提示。 ↩↩↩↩↩

  269. 配置沙盒化的 Bash 工具,Claude Code 文档,于2026年10月11日获取。默认值表:写入范围为“工作目录、每用户临时目录以及您添加的目录”;读取范围为“机器上的大部分内容,包括 ~/.ssh 和 ~/.aws/credentials 等凭据文件”;网络流量经由本地代理,其允许域名列表“初始为空”。沙盒之外:内置的文件和网页工具“转而遵循权限规则。denyRead 条目并不会阻止 Read 工具”;“命令 hooks、本地 MCP 服务器、plugin 监视器、LSP 服务器,以及状态行命令和 apiKeyHelper 等辅助命令,均以您的完整权限运行。”收窄读取范围:sandbox.filesystem.denyRead、allowRead 和 permissions.blockReadsOutsideWorkingDirectories。 ↩↩↩

  270. Claude Code 文档,于2026年10月13日重新获取。Mods 参考:仍标注“截至 v2.1.290”;tool.check 新增“e.agentId:当 subagent 或进程内团队成员发起调用时设置”以及“e.ceiling:对于组织设为 ask 的连接器工具,其值为 ask”,并注明“在 tool.check 上,e.agentId 和 e.ceiling 需要 Claude Code v2.1.290 或更高版本”;prompt.autocomplete 已列出(“用户在提示框中输入,且光标处恰好是一个词的结尾。e.token 即该词”);$.ui 命名空间列出了 resolve、invalidate、open、close、panes、focus、scroll、toast、status、log、notice、ask、copy、selection 和 blit,但没有 notify;没有 serverToolUses 或 $.tool.register 的条目。Hooks:“在 Claude Code v2.1.296 或更高版本中,工具事件、UserPromptSubmit、SessionStart、Stop 及其他若干事件上的每个命令 hook 在结束时都会留下一条记录,无论其输出了什么”;“在 Claude Code v2.1.296 或更高版本中,PowerShell 命令同样会收到来自 CLAUDE_ENV_FILE 的变量,但 PowerShell 从不执行该文件”。Claude 应用网关:“在没有托管设置的机器上,请让每位开发者将 forceLoginMethod 和 forceLoginGatewayUrl 添加到各自的用户设置文件 ~/.claude/settings.json 中”;“在 code 下,当 Code 标签页的条件成立时,它们同样会作用于 Code 标签页的会话。它们不会作用于 Cowork 或 Chat 会话。”环境变量和 Sub-agents:仍没有 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL、CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 或 autoCompactWindow 的条目。 ↩↩↩

  271. Claude Code 官方 CHANGELOG 的 2.1.299 小节,于2026年10月14日获取,以及同日读取的 @anthropic-ai/claude-code npm 注册表元数据:2.1.299 发布于2026年10月14日 00:23 UTC,2.1.300 发布于同日 14:27 UTC;dist-tags 为 latest 2.1.299、next 2.1.300、stable 2.1.287;npm 上没有 2.1.297 或 2.1.298,CHANGELOG 中也没有这两个版本或 2.1.300 的小节。GitHub 发布页(02:49 UTC)包含 190 条条目,与 CHANGELOG 完全一致。本指南中所有 v2.1.299 条目均以此为来源。关键引文:“在终端中新增了空闲压缩:超过 200K token 的对话若闲置约 54 分钟,会在其一小时提示缓存过期前被压缩,这样您的下一条消息就无需重新处理全部内容”;“新增 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS,用于更改空闲压缩的 200K token 下限;在 settings.json 中设置 \"idleCompaction\": false 可将其关闭。两者均需 v2.1.290 或更高版本”;“新增 CLAUDE_CODE_DISABLE_FILE_MENTIONS 环境变量:Claude 只会获得 @ 文件提及的路径,由其文件工具自行读取,而不是直接获得文件内容”;“MCP 允许规则现在只匹配其所指名的服务器:mcp__a 不再允许名为 a__b 或 a_ 的服务器;请使用服务器完整的规范化名称书写 mcp__<server>__*”;“agent 的 tools: 列表现在只接受所指名 MCP 服务器的工具;名称中包含 __ 的服务器应写作 mcp__<whole name>__*”;“来自 Anthropic 位于 api.anthropic.com 的第一方 MCP 服务器的工具描述和服务器指令,现在会完整传达给 Claude,而不再在 4,096 个字符处被截断”;“云会话和 Remote Control 的 MCP 连接器在不获取功能标志的安装上,现在默认协商 MCP 协议版本 2026-07-28;MCP_PROTOCOL_NEGOTIATION=legacy 可选择退出”;“UserPromptSubmit hooks 现在在 skill 或自定义斜杠命令展开之前运行,因此阻止提示的 hook 如今也会一并阻止其中内嵌的 shell 命令”;“turn.start mod hook 现在也能监听到 subagents 和团队成员的轮次,而不仅是主循环的;可通过 e.agentId(主循环上不存在)加以区分”;“修复了对并不执行 rm 的 shell -c 脚本弹出 rm 提示的问题。在 Claude Code 无法读取的脚本中于运行时拼出的 rm,现在不再触发提示,除非设置了 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1”;“为 claude self-hosted-runner orchestrator 新增 --shutdown-drain-sec:收到 SIGTERM 时停止轮询,并给进行中的轮询和正在运行的 spawn hooks 最多该秒数的时间来完成”;“为 claude plugin eval 新增 --disallow-tools 以及用例字段 disallowed_tools,用于将 Agent 等特定内置工具排除在评估运行之外”;“新增支持关闭 Claude Desktop 的 Code 标签页中的署名块:在 Claude 应用网关 code 策略的 env 中设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0”;“在 agent 视图中新增 /effort 和 /fast,用于设置新会话的初始配置;在该视图中单独输入 /model、/effort 或 /fast 现在会打开选择器”;“当 plugin hook 无法接收到操作或无法返回其判定时,该 hook 本可阻止的操作现在会被拒绝而非放行;已经运行的工具,其结果会被扣留”;“修复了 2.1.296 中的一个回归问题:云会话和无头会话在重启后恢复时若恰好收到新消息,可能会把已批准的工具调用执行两次”;“网络安全防护提示不再要求用户申请加入 Cyber Verification Program”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  272. Claude Code 文档,2026年10月14日获取。设置参考:idleCompaction,“阻止 Claude Code 在终端会话空闲时压缩长对话”;“对于满足其条件的对话,空闲压缩默认开启。如需关闭,请将 idleCompaction 设为 false。需要 Claude Code v2.1.290 或更高版本”。环境变量:CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS “以 token 计的上下文大小,达到该值后空闲压缩才会应用于对话(默认:200000)”,低于 100000 的值会被提升至 100000;CLAUDE_CODE_DISABLE_FILE_MENTIONS “需要 Claude Code v2.1.299 或更高版本”,在项目设置和本地设置中会被忽略;CLAUDE_CODE_ATTRIBUTION_HEADER “设为 0 可省略署名块”;CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS “自动重试之间指数退避的上限(以毫秒计),用以取代默认值 32000”;仍然没有 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 或 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT 的条目。Sub-agents:autoCompactWindow 现已列为 frontmatter 字段,“100000 到 1000000 之间的 token 数”;tools 和 disallowedTools “除精确的工具名称外,还接受 MCP 服务器级模式:mcp__<server> 或 mcp__<server>__*”。Mods 参考:仍为“截至 v2.1.290”;“在 skill.prompt 上,e.source、e.pluginName、e.path、e.frontmatter 和 e.frontmatterProblem 需要 Claude Code v2.1.299 或更高版本”;turn.start 已列入事件之中;没有 $.prompt.media、$.session.identity、tabular 或 serverToolUses。Plugin 评估:“在 v2.1.299 之前,此类运行会按其已产出的内容进行评分”;没有 --disallow-tools。MCP:限制列表仍写着“服务器指令,以及预先加载的工具的描述:4,096 个字符”,没有第一方例外;在 v2 运行时上,Claude Code “会询问 HTTP、stdio 和 claude.ai 连接器服务器是否支持较新的修订版,并对支持的服务器使用该版本”。权限:“允许规则只有在字面的 mcp__<server>__ 前缀之后才接受工具名通配符。服务器段不得含有通配符,这样规则才能指向您配置的某个特定服务器。”Hooks:对 CLAUDE_CODE_DISABLE_FILE_MENTIONS 有描述(“您匹配的 PreToolUse hooks 会运行”);没有说明 UserPromptSubmit 会在 skill 或命令展开之前运行。 ↩↩↩↩↩↩↩↩↩↩↩

  273. Claude Code 官方 CHANGELOG 的 2.1.300 一节,2026年10月14日(太平洋时间 21:40)获取,以及同一时间读取的 @anthropic-ai/claude-code 的 npm 注册表元数据:2.1.300 于 10月14日 14:27 UTC 发布;dist-tags 为 latest 2.1.300、next 2.1.300、stable 2.1.292(当天上午还是 2.1.287)。GitHub 发布版本(18:24 UTC)包含 88 个要点,与 CHANGELOG 完全相同。本指南中所有 v2.1.300 条目的来源。关键引文:“在 AWS 上的 Claude Platform 中新增了 /advisor;在您通过 /advisor、advisorModel 或 --advisor 选择之前不会运行任何 advisor,CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 可将其关闭”;“为 mod 的提示框装饰新增了 virtualText:绘制在提示框中、但绝不会进入草稿或已提交提示的文本”;“为 mods 新增了 $.ui.view({ agentId }):按您的要求在主视图中显示某个代理的转录,$.ui.view({}) 则返回原视图”;“新增了 prompt.change mod hook,当提示框文本在没有键入编辑的情况下发生变化时触发:调出历史条目、清空、撤销或插件填充”;“在 OpenTelemetry 的 api_request 事件中新增了 cache_creation_5m_tokens 和 cache_creation_1h_tokens,按生命周期拆分缓存写入”;“为 trace span 新增了 OpenTelemetry GenAI 语义约定属性,例如 gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name 和 error.type”;“更改为即使在遥测被禁用时,发往 api.anthropic.com 的大型请求也使用 gzip 压缩;设置 CLAUDE_CODE_GZIP_REQUEST_BODIES=0 可将其关闭”;“更改了 hooks:来自 PreToolUse 和 PermissionRequest hooks 的 updatedInput 现在会像 Claude 自身的输入一样接受验证:未知键会被丢弃,被工具拒绝的输入会导致调用被拒”;“移除了 claude remote-control 中原本无效的 --sandbox 和 --no-sandbox 标志;现在传入任一标志都会报错退出。如需沙箱化会话,请在设置中设置 sandbox.enabled”;“更改了本地会话转录,使其同时记录每个 API 请求的系统提示、工具和参数,这样您选择分享的转录就能精确复现请求”;“更改了退出行为,对在收到停止请求 1.5 秒后仍在运行的后台命令强制终止”;“修复了在后台命令仍在运行时退出,SessionEnd hooks 有时不会运行的问题”;“修复了 claude daemon stop --any 在卡住的后台服务仍在运行时却打印 "stopped" 的问题:现在它会等待、强制终止该服务,如果服务仍然存在则以退出码 1 报告”。 ↩↩↩↩↩↩↩↩↩↩↩

  274. Claude Code 文档,2026年10月14日获取。用 advisor 工具上报棘手决策:“advisor 工具为实验性功能,需要 Anthropic API。它在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用”;“advisor 会收到完整对话,包括每一次工具调用及其结果,并返回 Claude 在继续之前应用的指导”;“作为服务器工具在 Anthropic 的基础设施上于服务端运行,订阅账户和按 API 计费的账户均可使用”;“没有任何设置可以限制或强制 advisor 调用”;三种启用方式:“/advisor 命令”、“advisorModel 设置”、“--advisor 标志”;/advisor 的文本形式“需要 Claude Code v2.1.260 或更高版本”;“claude --help 中不会列出 --advisor”;配对行“Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更高版本、Sonnet 5.5”、“Sonnet 5.5 | Fable、Opus 5 或更高版本、Sonnet 5.5”、“Opus 5 或 Opus 5.5 | Fable、Opus 5 或更高版本”、“Fable 5.1 | Fable 5.1”;“Haiku 4.5 可以调用 advisor,但不能充当 advisor”;“Subagents 会继承已配置的 advisor,并针对其自身模型执行相同的配对检查”;“如果 API 拒绝 Claude Code 所附加的 advisor 配对,Claude Code 会在不带 advisor 的情况下重新发送该请求。对话会在没有 advisor 的情况下继续,因此您不会看到错误,也不会得到任何 advisor 调用”;费用:“advisor token 按 advisor 模型的输入和输出费率计费”、“advisor 用量计入您套餐的使用限额,但 Fable advisor 则从使用额度中扣费”;“切换 /advisor 会保持缓存前缀完好”;“advisor 模型自身对对话的读取不会被缓存”;要求包括“功能标志获取”,因此在设置了 DISABLE_TELEMETRY 时“advisor 保持关闭”;CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1:“/advisor 命令变为不可用,任何已配置的 advisorModel 都会被忽略。--advisor 标志会被接受但不起作用”;转录状态“Reviewed”、“Declined”、“Unavailable”。CLI 参考:--advisor <model> “使用模型别名 fable、opus 或 sonnet,或完整的模型 ID,为本次会话启用服务端 advisor 工具。在本次会话中优先于 advisorModel 设置”。设置参考:advisorModel “选择当 Claude 调用 advisor 工具时由哪个模型作答”。环境变量:CLAUDE_CODE_DISABLE_ADVISOR_TOOL,以及 CLAUDE_CODE_GZIP_REQUEST_BODIES “设为 0 可关闭发往 api.anthropic.com 的 Claude API、遥测以及工件发布请求体的 gzip 压缩”。Mods 参考:仍为“截至 v2.1.290”;“lent 需要 Claude Code v2.1.292 或更高版本,rewritten 需要 v2.1.300 或更高版本”;没有 virtualText、$.ui.view 或 prompt.change 条目。 ↩↩↩↩↩↩↩↩↩

  275. Claude Code 官方 CHANGELOG 的 2.1.301 与 2.1.302 两节,获取于2026年10月17日(15:40 PT),以及同时读取的 @anthropic-ai/claude-code npm 注册表元数据:2.1.301 发布于10月15日 14:34 UTC,2.1.302 发布于10月16日 16:48 UTC;dist-tags 为 latest 2.1.302、next 2.1.302、stable 2.1.292。GitHub 发布页 v2.1.301(19:22 UTC,51 条)和 v2.1.302(20:53 UTC,63 条)与 CHANGELOG 内容完全一致。本指南中所有 v2.1.301 与 v2.1.302 条目均以此为来源。关键引文,2.1.302:“未指定权限模式的 claude -p 与 Agent SDK 会话,在使用第三方提供商、关闭遥测或全新安装的情况下,现改为以 default 模式启动;--permission-mode auto 仍保持 auto”;“fork subagents(subagent_type: \"fork\")现在在 claude -p、Agent SDK、桌面应用和 VS Code 中默认开启,与终端中的既有行为一致;CLAUDE_CODE_FORK_SUBAGENT=0 可将其关闭,而 claude mcp serve 从不提供此功能”;“桌面应用和 VS Code 现在总是在后台运行主对话的 subagents,与终端行为一致,而不再由 Claude 自行选择;在 claude -p、Agent SDK、桌面应用和 VS Code 中,subagent 自身发起的 Agent 调用现在默认在前台运行”;“prompt hooks 与 agent hooks 现在同一事件最多同时运行 12 个,其余的排队等候”;“新增 CLAUDE_CODE_AUTO_MODE_MODEL,用于选择客户端 auto 模式分类器所使用的模型;它不会更改服务器端 auto 模式的模型”;“在 /config 中新增 Idle compaction 行,用于关闭或重新开启空闲压缩;空闲压缩后显示的提示现在会说明如何将其关闭”;“在 /design-sync 与 /design-login 中新增提示:独立版 Claude Design(claude.ai/design)将于2026年12月14日前关闭”;“修复了 Read 工具会将任意大小的图片文件,或名称形似图片的管道或设备,整个加载进内存的问题;超过 128 MB 的图片来源现在会被拒绝”;“改进了使用服务器端分类器的 auto 模式:对于长度超出安全检查上限的对话,现在会先进行压缩,而不是拒绝每一个受检的工具调用”。2.1.301:“新增 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS,使无人值守重试模式(CLAUDE_CODE_RETRY_WATCHDOG)在遇到重置时间过远的用量限制时直接结束请求,而不是一直等待”;“为 vim 模式新增 % 动作:跳转到匹配的括号,可单独使用,也可与 d/c/y 组合”;“为 mod 的 Input 新增 rows:终端中的多行文本框,按 Enter 提交,按 Shift+Enter 或在 Enter 前输入反斜杠则换行”;“为 OpenTelemetry 的 tool_decision 事件新增 classifier_verdict 与 permission_mode,以便区分 auto 模式分类器的判定与权限规则”;“在 OTEL_LOG_TOOL_DETAILS=1 时,为 OpenTelemetry 的 tool_decision 事件新增 classifier_category,指明分类器拦截所匹配的内置规则”;“修复了当您的组织无法使用最新 Fable 模型时,fable(及 best)模型别名在 Anthropic API 上报错的问题:Claude Code 现在会用上一代 Fable 模型重试一次”;“改进了切换到上下文窗口更小的模型的体验:对于新模型而言过长的对话,现在会先由先前的模型进行摘要”;“mod hook 的 .catch 处理程序现在仅在该 hook 抛出异常或超时时运行;由该 hook 自身调用之下所引发的事件,现在会跳过该 hook,也不会再触发其 .catch”;“mod 的 $.env.set 现在在变量设置或取消设置完成后以 {} 解析,若未执行写入则以 { deny } 解析并说明原因”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  276. Claude Code 文档,获取于2026年10月17日。交互模式:“% | 跳转到匹配的 ()、[] 或 {} 括号;当光标不在括号上时,从当前行的下一个括号开始。需要 Claude Code v2.1.301 或更高版本”以及“d%/c%/y% | 从光标处删除、更改或复制(yank)到 % 所跳转到的括号为止”。VS Code 页面列出了 LaTeX 数学公式渲染。仍停留在 2.1.302 之前规则上的有:权限模式表格(“claude -p 或 Agent SDK | 在获取功能标志的会话中为 default。在不获取的会话中,例如使用第三方提供商或关闭遥测时,Claude Code v2.1.285 或更高版本为 auto”);环境变量页面(CLAUDE_CODE_FORK_SUBAGENT“仅在交互式会话中默认开启。设为 1 可在 claude -p 和 Agent SDK 中一并开启,设为 0 则在所有类型的会话中关闭”);以及 subagents 页面(“在使用 -p 的非交互模式和 Agent SDK 中,fork 模式默认关闭,除非您手动开启”)。文档中完全未提及的内容:CLAUDE_CODE_AUTO_MODE_MODEL、CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS、tool_decision 的属性 classifier_verdict、permission_mode 和 classifier_category(监控页面一个都没有列出)、/config 的 Idle compaction 行、Claude Design 的关闭日期,以及 12 个 hooks 的上限(hooks:“所有匹配的 hooks 并行运行”)。mods 文档现已自成一节:概览、参考(“条目涵盖截至 v2.1.290 的 Claude Code CLI 与桌面应用,以及截至 v2.1.299 的 VS Code 扩展”)、事件(.catch:“当 guard 在 Bash 调用上抛出异常或超时时,Claude Code 会以同一事件调用该处理程序”,但未包含 v2.1.301 的重入规则)、API 和界面;此前脚注所引用的 plugins/mods-reference URL 现返回 404,而且这些新页面均未提及 Input 上的 rows、$.env.set、nothing-to-fork、virtualText、$.ui.view、prompt.change、$.prompt.media 或 $.session.identity。advisor 页面仍称该工具“在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用”。 ↩↩↩↩↩↩↩↩↩↩↩

  277. Claude Code 文档,获取于2026年10月21日。Hooks 参考:“JSON 对象支持三类字段:continue 等通用字段列于下表。所有事件都接受这些字段,但部分事件会将其丢弃,或将 systemMessage 投递到转录记录以外的位置。各事件的章节均有说明。terminalSequence 同样适用于这些事件,但“发出终端通知”一节所列的例外情况除外。顶层的 decision 和 reason 被部分事件用于阻止操作或提供反馈。hookSpecificOutput 是一个嵌套对象,供需要更精细控制的事件使用。它要求包含一个设置为事件名称的 hookEventName 字段。”通用字段表:continue“若为 false,Claude 在 hook 运行后完全停止处理。其优先级高于任何事件专属的决策字段”;stopReason“当 continue 为 false 时向用户显示的消息。该消息会保留在对话中,因此如果对话继续,Claude 能够看到它”;suppressOutput“无效:Claude Code 接受该字段但不会据此采取任何行动。成功运行的 hook 的 stdout 从不显示在转录记录中,而是记录到调试日志”;systemMessage“向用户显示的警告消息。在 Agent SDK 和 --output-format stream-json 输出中,它可能以 SDKInformationalMessage 的形式到达”;terminalSequence“一段由 Claude Code 代为发出的终端转义序列,例如桌面通知、窗口标题或响铃。仅限 OSC 0/1/2/9/99/777 和 BEL。如果值中包含允许列表之外的任何内容,该字段将被忽略。”“modifications”一词在该页面上仅出现在 ConfigChange 的说明文字中(“block unauthorized modifications to configuration files”),从未作为输出字段出现。退出码 0:“对于大多数事件,Claude Code 会将 stdout 写入调试日志,而不在转录记录中显示。例外是 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch,对于这些事件,Claude Code 会将纯文本 stdout 添加为 Claude 可见并可据以行动的上下文。”JSON 输出:“除 JSON 对象外,不要向 stdout 打印任何内容。对于非异步的 hook,那里出现的其他文本(例如您的 shell 配置文件在启动时回显的一行)会导致 Claude Code 无法将该对象读取为 JSON,而“Hook JSON 不生效”一节说明了如何找到并消除这些文本。”退出码 0 且带有 JSON:“Claude Code 会应用您的 hook 打印的所有 JSON 输出字段,除非这些字段阻止或拒绝该操作,否则操作照常进行。”其他退出码:“除非该 hook 属于失败即阻止操作的类型,否则这是一个非阻塞错误,因此您的 hook 并未阻止该操作。”;“要捕获 hook 的完整 stderr 而非通知中显示的第一行,请启用调试日志。”;并且在输出表中,任何其他退出码若配有“通过模式验证的 JSON 对象”,则为“成功。Claude Code 忽略退出码,仅由字段决定。对于失败即阻止操作的 hooks,此次运行则计为失败”。terminalSequence:“Claude Code 仅在交互式会话中、且仅当其界面显示在屏幕上时才写入该序列。在使用 -p 标志的非交互模式下以及在 Agent SDK 中,它会忽略该字段。” ↩↩↩↩

  278. Claude Code 官方 CHANGELOG,2.1.303 至 2.1.310 各节,获取于2026年10月23日(太平洋时间17:20),以及同时读取的 @anthropic-ai/claude-code npm 注册表元数据:2.1.303 发布于10月18日21:15 UTC,2.1.304 为10月19日19:47 UTC,2.1.305 为10月20日19:29 UTC,2.1.306 为10月21日02:28 UTC,2.1.307 为10月21日20:47 UTC,2.1.308 为10月22日04:19 UTC,2.1.309 为10月22日20:34 UTC,2.1.310 为10月23日21:20 UTC;dist-tags 中 latest 为 2.1.310、next 为 2.1.310、stable 为 2.1.308。GitHub 各发布版本分别包含 1、76、38、2、43、1、79 和 26 条条目,与 CHANGELOG 完全一致。本指南中所有 v2.1.303 至 v2.1.310 条目的来源。关键引文,2.1.304:“新增 /auto-mode-setup:一个引导式设置流程,读取您的项目和近期会话,让自动模式了解您的环境,现已同样适用于 Bedrock、Vertex、Foundry、Claude 应用网关以及禁用遥测的会话”;“新增 mod 的 tool.check 回答中的 decider: \"person\":只有权限对话框或宿主的回调才能批准该请求,在无人可问的情况下则以该 mod 给出的理由拒绝”;“在 Pro 和 Max 计划上新增一条警告:当恢复一个不活跃的对话会消耗您5小时用量限额中相当可观的一部分时予以提示”;“更改:在自定义 ANTHROPIC_BASE_URL 之后,工具搜索默认开启;网关返回 400 或 422 时会在不带该功能的情况下重试”;“更改 mod 的 settings.read hooks,使其接收每一层设置并重写合并后的设置,因此受管 mod 可以把组织的设置设为上限”;“更改 skill hooks:同一来源(一个仓库、您自己的文件夹或一个 plugin)的 skills 在每个会话中最多可注册 1,024 个 hooks 和 16,384 个匹配器字符”。2.1.305:“新增 sandbox.allowNestedUserNamespaces,使 Linux 上的沙箱命令可以创建用户命名空间(Chromium、rootless podman);这会让它们绕过沙箱的文件保护”;“新增 CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS,使无人值守重试模式(CLAUDE_CODE_RETRY_WATCHDOG)能够察觉在重置之前已被解除的用量限制”;“修复了在 Vertex、Bedrock 及其他提供商上,当端点或网关拒绝工具搜索时,以及在 ToolSearch 被禁止或未包含在 --tools 中的网关之后,所有请求都失败的问题(2.1.304 引入的回归):Claude Code 现在会在不带工具搜索的情况下重试”;“改进 /usage:每条警告现在都是一行指明其来源的修复建议,按 f 即可应用这些修复;同样的修复也出现在 VS Code 和 /doctor 中”;“更改 allowedMcpServers,不再过滤仅在 env 中使用 ${VAR} 的 managed-mcp.json stdio 服务器:您的允许列表遗漏的此类服务器现在会在升级后加载;请使用 deniedMcpServers 将其关闭”。2.1.307:“新增 /claude-api api-version,用于将 Claude API 代码迁移到 API 版本 2026-10-21”;“新增 claude_code.safety_event OpenTelemetry 事件,对应每一次被权限规则、自动模式、安全检查、hook 或沙箱阻止、提示或退回的工具调用”;“改进同时启动的 fork subagents:现在每个 fork 都会被告知哪一次启动属于自己,因此 fork 之间尝试接手彼此工作的可能性大大降低”;“[Code Review] 在 Code Review 中新增 @claude review stop(也可用 off 和 pause),用于结束拉取请求上的 @claude review always 订阅而不启动新的审查”。2.1.309:“修复了 macOS 和 Linux 上沙箱化的 Bash 命令在每条命令之前于沙箱外运行 shell 启动文件的问题”;“更改 sed -i,使其获得标准的 Bash 提示并按原样运行,而非模拟的文件编辑预览;与其他 Bash 编辑一样,它不再可由 /rewind 恢复”;“更改 claude ultrareview,使其要求工作区信任:在终端上会进行询问,否则拒绝;脚本可传入 --trust-workspace(该标志不接受值,请将 PR 编号或基准分支放在它前面),或设置 CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1”;“修复了读取超大嵌套 CLAUDE.md 下的文件后会话反复压缩的问题;超过大小限制的嵌套 CLAUDE.md 现在只加载其开头部分”;“更改工作树的创建与复用方式,使 git 不再按需获取对象,这适用于普通克隆以及配置了 Bash 沙箱的部分克隆;此类部分克隆会先行获取这些对象”。2.1.310:“在 Bedrock、Vertex 和 Foundry 上,以及在禁用遥测或非必要流量时,新增 Monitor 工具和 plugin 监视器;长时间的前台 sleep 在这些环境中现在也会被阻止”;“修复了在某些拒绝 effort-2025-11-24 beta 值或对话中途系统消息的网关和兼容服务器之后请求失败的问题;Claude Code 现在会在不带它们的情况下重试”;“Linux:改进 /sandbox 和沙箱启动警告,当 Ubuntu 的 AppArmor 对用户命名空间的限制阻止 bubblewrap 启动沙箱时,会指出该限制以及解除方法”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  279. Claude Code 文档,获取于2026年10月23日。现已写入文档:环境变量页面列出了 CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS、CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK(“请在启动 Claude Code 的环境中设置,而不是在设置文件的 env 中”)、CLAUDE_CODE_AUTO_COMPACT_WINDOW(“诸如 200k 这类带后缀的值需要 v2.1.304 或更高版本”)和 CLAUDE_CODE_AUTO_MODE_MODEL(“请使用完整的模型 ID”),并且现在对 CLAUDE_CODE_FORK_SUBAGENT 的说明是“控制 fork 模式,该模式默认开启”;设置参考列出了 sandbox.allowNestedUserNamespaces(“用户或托管”);auto mode 配置页面写有“使用 /auto-mode-setup 生成环境条目”;费用页面写道:“当 /usage 页脚显示诸如 f to fix 2 of 3 的提示时,按 f 即可让 Claude Code 执行其力所能及的建议。f 快捷键需要 Claude Code v2.1.305 或更高版本”;斜杠命令列出了 /claude-api api-version(“v2.1.307 或更高版本”)和 managed-agents-secure [<agent-id>];监控列出了 safety_event 和 classifier_verdict(“需要 Claude Code v2.1.301 或更高版本”);ultrareview页面记录了 --trust-workspace(“不接受任何值:请将 PR 编号或基础分支放在它之前”)以及 Error: Workspace not trusted 退出错误;代码审查页面列出了 Quick、Standard 和 Deep 三个级别;hooks页面载有 1,024 个 hook 与 16,384 个字符的上限;mods 参考将 e.isReadOnly 标注为“v2.1.304 或更高版本”;沙箱页面载有 Ubuntu AppArmor 配置文件;权限模式表格现在写为“claude -p 或 Agent SDK | default”,与 v2.1.302 一致。仍仅见于发布说明的内容有:decider: "person"、settings.read 层级、@claude review stop、sed -i 的变更、自定义基础 URL 下的工具搜索默认行为、Pro 和 Max 的恢复警告、--checkout-hook-timeout-min、multiagent_20261001、CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS、Claude Design 的截止日期,以及 mod 新增的 $.env.set、virtualText、$.ui.view 和 prompt.change;advisor页面仍称该工具“在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  280. 让 Claude 通过 Projects 协调持续进行的工作,Claude Code 文档,获取于2026年10月26日:“Projects 已在 Pro 和 Max 方案上进入公开测试,并正在逐步推出”;“Projects 尚未面向 Team 或 Enterprise 方案提供”;“项目指令:发送给每个新线程以及项目对话中 Claude 的文本,最多 16,000 个字符”;“新建项目的每个线程都在 Opus 上以高 effort 运行”;“强制执行的上限为所有项目合计每天 200 个新线程”;“两者都需要该计算机上安装 Claude Code v2.1.280 或更高版本”;以及“线程从您的仓库中获取哪些内容”表格。发布文章:Projects 重新设计:从文件夹到对话,Anthropic,2026年9月17日:“从今天起,更新后的 Projects 以测试版形式向部分在 Claude Code 中使用云会话的 Claude Pro 和 Max 订阅者开放”。截至 2.1.310 的官方 CHANGELOG 从未提及该功能。云会话页面列有“移动端:Claude 应用中的 Code 标签页”,而 Projects 页面则提到了 iOS 和 Android 版 Claude 移动应用。 ↩↩↩↩↩

  281. 在云端使用 Claude Code,Claude Code 文档,获取于2026年10月26日:“使用 --cloud 标志从命令行启动云会话”;“云端虚拟机克隆的是当前目录 GitHub 远程仓库的当前分支,而非您的本地检出,因此如有本地提交请先推送”;“旧的 --remote 写法仍可作为 --cloud 的已弃用别名使用”;“CLI 会将消息排入该会话的队列并退出,不会等待回复”;“--output-format stream-json 不支持与 --cloud <session-id> 搭配使用”;“--cloud 用于创建云会话。--remote-control 与之无关”。2.1.310 上的 claude --help 列出了 --cloud [description|session_id|url] Create a cloud session;该标志未出现在任何 CHANGELOG 条目中。 ↩↩↩↩↩

  282. 使用计划任务自动化工作,Claude Code 文档,获取于2026年10月26日:“创建计划任务(原名 routines),按计划、在 API 调用时或在 GitHub 事件触发时于云端运行”;“计划任务处于研究预览阶段”;“运行频率高于每小时一次的表达式会被拒绝”;每小时限额表格(每个账户每小时 100 次计划运行;对于 Run now、API 触发以及重新运行一次性任务,每个任务每小时 30 次);“/schedule 的别名 /routines”;“从 CLI 添加计划任务需要 Claude Code v2.1.225 或更高版本”;以及 Scheduled tasks (Was Routines) 开关。在 Claude Code Desktop 中安排周期性任务,同次获取:“仅在应用打开且计算机处于唤醒状态时触发”,以及 Cloud、Desktop 与 /loop 的对比表格。 ↩↩↩↩

  283. 将会话输出作为 artifacts 分享,Claude Code 文档,获取于2026年10月26日:“模板处于测试阶段。它们在 Pro、Max 和 Team 方案上默认开启”;“如果您的组织关闭了 Slides 模板,/slides 将不会显示”;“禁用 artifacts”表格(/config、"enableArtifact": false、已弃用的 "disableArtifact": true、CLAUDE_CODE_DISABLE_ARTIFACT=1、permissions.deny 中的 Artifact);“在项目和本地设置中遵循该键需要 Claude Code v2.1.242 或更高版本”。环境变量,同次获取:CLAUDE_CODE_ARTIFACT_AUTO_OPEN(“设为 0 可阻止 Claude Code 在发布新 artifact 时自动打开浏览器”)、CLAUDE_CODE_DISABLE_WORKFLOWS(“等同于 disableWorkflows 设置”)、CLAUDE_CODE_MAX_TURNS(“等同于传入 --max-turns,两者同时设置时以后者为准。非正整数的值会在启动时被拒绝”);该页面不再列出 CLAUDE_CODE_WORKFLOWS。设置参考,同次获取:disableWorkflows(“两者中无论哪一个将其关闭,另一个都无法再将其重新开启”)和 enableWorkflows(“默认:未设置,因此 workflows 默认开启,但 Pro 方案除外,该方案下默认关闭”;“在 /config 中显示为 Dynamic workflows”)。 ↩↩↩

  284. Claude Code CHANGELOG,v2.1.311 至 v2.1.317(提交时间为 2026-10-26T21:51Z、10-27T20:23Z、10-30T01:06Z、10-31T01:01Z 和 11-03T01:25Z)以及与之对应的 GitHub 发布版本 v2.1.311(2026-10-26T21:51:23Z)、v2.1.312(10-27T20:24:20Z)、v2.1.314(10-30T01:06:26Z)、v2.1.316(10-31T01:01:35Z)和 v2.1.317(11-03T01:25:46Z),每个版本均与其 CHANGELOG 对应章节完全一致;npm 发布时间来自 npm view @anthropic-ai/claude-code time:2.1.311 为 2026-10-26T19:47:57Z,2.1.312 为 10-27T18:36:10Z,2.1.314 为 10-30T00:12:56Z,2.1.315 为 10-30T21:05:24Z(无 CHANGELOG 条目,也无 GitHub 发布版本),2.1.316 为 10-31T00:42:05Z,2.1.317 为 11-02T23:57:53Z;2026-11-02 的 dist-tags:latest 与 next 为 2.1.317,stable 为 2.1.311。原文如下,2.1.311:“将交互式终端中的 ultrathink 改为通过 Anthropic 的 API 在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上以 xhigh 努力程度运行该轮;若在 Claude 工作期间输入,则会提升该轮余下部分的努力程度”。2.1.316:“自2026年10月30日起弃用 Opus 4.8 的快速模式,并将于2026年11月30日移除。移除后,Opus 4.8 上的快速模式请求将返回错误,且不会回退到标准 Opus 4.8。请迁移到 Opus 5.5 以保留提速效果”。2.1.314:“新增 permissions.blockWritesOutsideWorkingDirectories:Write、Edit 和 NotebookEdit 在所有权限模式下均拒绝工作目录之外的路径”。2.1.312:“将 prompt hooks 和 agent hooks 改为每个会话同时最多运行 24 个(含 subagents),外加最多 12 个等待时长已超过其事件超时的 hooks;不足 1 秒的 timeout 现在按 1 秒计”;“将 Claude Code 改为不再发送 claude_code.safety_event OpenTelemetry 事件”。2.1.317:“向 OTel 指标、事件和 span 新增 anthropic.plan、anthropic.seat_type、anthropic.provider 和 anthropic.custom_base_url”。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  285. Claude Code 文档,获取于2026年11月2日:使用快速模式加快响应速度(“Opus 4.8 的快速模式已于2026年10月30日弃用,并将于2026年11月30日移除。若在该日期之后您的模型仍为 Opus 4.8 且开启了快速模式,API 将拒绝您的请求”);模型配置(“在终端提示符中输入时,该词还可将该轮提升至 xhigh 努力程度。可以提升时,该词会显示为彩虹色。需要 Claude Code v2.1.311 或更高版本”);所有设置,涉及 permissions.blockWritesOutsideWorkingDirectories(“使 Write、Edit 和 NotebookEdit 工具在包括 bypassPermissions 在内的所有权限模式下均拒绝工作目录之外的路径”;“该键开启后,Claude Code 还会移除 EnterWorktree 和 ExitWorktree 工具”)、idleCompaction(默认开启,“在交互式终端会话中、在 VS Code 扩展的聊天面板中,或在桌面应用的 Code 标签页中,只要会话在您的机器上运行或通过 SSH 运行”)以及 disableRemoteControl(“Claude Code 会拒绝 claude remote-control、--remote-control 标志、自动启动以及会话内切换”);环境变量,涉及 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT、CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK、CLAUDE_CODE_SYNC_SKILLS、CLAUDE_CODE_TRANSCRIPT_LOCAL_GC、CLAUDE_CODE_SKIP_PROMPT_HISTORY、CLAUDE_CODE_DISABLE_CFC_PROMPT 和 FORCE_HYPERLINK(“在 v2.1.314 之前,false、no 和 off 反而会启用超链接”);该页面尚未列出 CLAUDE_CODE_DISABLE_ULTRATHINK、CLAUDE_CODE_SUBAGENT_EFFORT、CLAUDE_CODE_MODEL_CATALOG、CLAUDE_CODE_DISABLE_LOOPED_CROSS_CERT_DROP、CLAUDE_CODE_DISABLE_NESTED_SESSION_ID 或 OTEL_EXPORTER_OTLP_TIMEOUT;创建自定义 subagents(“CLAUDE_CODE_EFFORT_LEVEL 环境变量的优先级高于两者”);自托管环境参考(--hold-idle-file、--max-hold-min:“需要 Claude Code v2.1.311 或更高版本”);自托管环境(“在 Team 和 Enterprise 计划中处于公开测试阶段,且默认关闭”);配置服务器托管设置;Claude 应用网关配置(“policy_mode 需要网关服务器上的 Claude Code 为 v2.1.316 或更高版本”;identity_retention_days “默认为 90”);使用 Remote Control 从任意设备继续本地会话。10月26日至11月3日期间,code.claude.com 上有 137 个页面的站点地图 lastmod 发生了变动;Wayback CDX 索引显示,其中没有任何页面是在该时段内首次发布的。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩