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

简而言之：Claude Code 是一个代理式 CLI，可读取您的代码库、运行命令并编辑文件，由配置、权限、hooks、MCP 和 subagents 这 5 个系统共同管理。凡是每次都必须运行的任务，请使用 hooks，而非提示词。

当前状态（CLI v2.1.292，2026年10月6日；npm latest 和 next 均为 2.1.292，stable 为 2.1.285）：²³⁴

• 默认模型：Claude Opus 5.5（claude-opus-5-5），适用于 Pro、Max、Team、Enterprise、Anthropic API，以及 AWS、Amazon Bedrock 和 Google Cloud Agent Platform 上的 Claude Platform。Microsoft Foundry 是例外：其默认模型为 Sonnet 4.5，opus 别名则指 Opus 4.6。²²¹
• Opus 5.5 概览：每百万 token 的输入/输出价格为 $4/$20，缓存读取价格为 $0.20；在 Anthropic API 上默认提供 1M 上下文，自 v2.1.287 起，Bedrock、Agent Platform 和 Foundry 也默认提供 1M 上下文；默认采用 medium 推理强度，且无法关闭思考功能。快速模式的价格为 $8/$40。任务无需 Opus 时，Sonnet 5.5（$2/$10；自 v2.1.284 起，在 Anthropic API 上对应 sonnet）是更经济的选择。^{220222223228232}
• 自动模式是所有套餐和提供商中交互式终端与 VS Code 会话的初始权限模式（v2.1.283-284）；而 claude -p 和 Agent SDK 会话默认以手动模式启动，除非传入 --permission-mode auto（v2.1.302 撤销了 v2.1.285 中第三方提供商及关闭遥测时默认以自动模式启动的改动）。²⁷⁵ 对于 Enterprise 和 Claude API 账户、AWS、Bedrock、Agent Platform 和 Foundry 上的 Claude Platform，以及通过网关连接的场景，其安全检查均在服务器上免费运行；其他情况下，则回退到需要计费的本地检查。^{219227228229230}
• AGENTS.md：自 v2.1.277 起，如果项目没有 CLAUDE.md，系统会将 AGENTS.md 作为项目指令读取；但无法获取功能标志的环境（如 Bedrock）以及安装或升级后的首次会话除外。²¹⁹²²³

各版本的发布历史请参阅更新日志。

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

能否高效使用 Claude Code，关键在于以下 5 个核心系统。掌握这些系统，Claude Code 便能成为事半功倍的效率倍增器：

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

核心要点

• 5 个系统决定使用成效：配置层级、权限、hooks、MCP 和 subagents 控制着从行为到自动化的一切。
• 将工作交给委派层：subagents 将探索过程隔离在干净的上下文窗口中，仅返回摘要，从而避免上下文膨胀。
• Hooks 可保证执行，提示词则不能：对于无论模型如何表现、每次都必须运行的代码检查、格式化和安全检查，请使用 hooks。
• 模型分级可在不牺牲质量的前提下降低成本：将 subagent 的探索任务分配给成本较低的模型，把 Opus 留给真正需要架构推理的任务；如果质量是唯一考量，也可以统一使用 Opus。
• MCP 将 Claude 接入您的工具链：数据库、GitHub、Sentry 以及 3,000 多项集成，让 Claude 的能力不再局限于读取文件和执行 bash 命令。

数月以来，我在生产代码库、CI/CD 流水线和企业部署环境中不断探索 Claude Code 的能力边界。本指南凝练了这些经验，力求成为我初次使用时求之不得的完整参考。每项功能均包含实际语法、真实配置示例，以及那些容易让资深用户踩坑的边界情况。

选择适合您的路径

如何使用本指南

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

使用浏览器的 Ctrl+F / Cmd+F 搜索特定标志、命令或配置键。文末的快速参考卡汇总了所有主要命令，便于快速浏览。

相关深度解析

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

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或更高版本”，已于2026年8月7日验证）；推荐的原生安装程序不依赖Node。支持macOS / Linux / Windows 10+。Claude Pro、Max、Team或Enterprise订阅，或者按token计费的Anthropic API密钥，均可满足使用需求。有关各平台的具体说明、故障排除方法以及原生二进制文件安装方式（自v2.1.113起成为默认方式），请参阅如何安装Claude Code？。本指南会随每个版本维护最新版本的验证依据；当前验证日期请参阅更新日志的最新一行。²⁶⁷

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

在深入了解各项功能之前，首先需要理解Claude Code的架构如何影响您的每项操作。该系统分为3层：

┌─────────────────────────────────────────────────────────┐
│                    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 tokens⁹¹；使用Opus 4.6或扩展上下文模型时为1M tokens）。上下文填满后，Claude会逐渐遗忘先前的决策，输出质量也会随之下降。此层按token产生费用。

委派层：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. Slash Commands
15. Skills如何运作？
16. Plugin系统
17. 记忆如何运作？
18. 图像与多模态输入
19. 语音模式
20. Git集成如何运作？
21. 如何在IDE中使用Claude Code？
22. 高级使用模式
23. 远程与后台Agents [研究预览]
24. Chrome中的Claude
25. Slack中的Claude Code [研究预览]
26. Web版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 内存和有效的互联网连接。⁹² 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

平台支持矩阵

安装、更新与卸载速览

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

自 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 已修复此回归问题。²¹⁸

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 凭据登录。²⁵⁰

Claude Pro 或 Max 订阅

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

企业平台

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

# 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 回合。²¹⁷²²⁶ 通过自定义基础 URL 或 Bedrock 等第三方提供商连接时，这些标头默认关闭，需设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 才会启用。网关协议文档还指出，直接连接到 Anthropic API 时会默认发送这些标头，而设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=0 则会在所有连接上停止发送。²²⁷

验证

claude doctor

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

身份验证管理（v2.1.41+）

无需进入 REPL 即可管理身份验证：⁹⁰

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 间接指向其他位置、导致配置目录不明确时，此字段尤其有用。²¹⁶

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

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

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

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

输出格式选项：

stream-json 中的 subagent 文本（v2.1.211+）： 默认情况下，stream-json 输出仅包含主会话的事件——subagents 内部完成的工作以摘要形式呈现。--forward-subagent-text 标志（或 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1）还会将 subagent 的文本和思考输出转发到流中，让执行框架和日志管道能够实时观察委派工作的进展，而非只能看到最终报告。¹⁸⁸

嵌套 subagents 现在也会转发（v2.1.219）。 最初只有深度为 1 的 subagents 会显示。现在，深度为 2 及更深层级生成的 subagents 也会出现在转发流中，并分别以创建它的 Agent 调用的 tool_use ID 作为键。这样，管道便能重建委派树，而非只看到扁平的文本列表。这与同一版本默认恢复深度为 3 的嵌套生成能力相辅相成：若无此改动，3 个层级中将有 2 个不可见。¹⁹⁶

转入后台的 subagents 不再失去消息（v2.1.273）： 当 subagent 在运行途中转入后台时（例如由 CLAUDE_AUTO_BACKGROUND_TASKS 触发），SDK 和 stream-json 输出不再遗漏该 subagent 的剩余消息和最终报告。²¹⁷

卡住的 -p 运行现在会报错退出（v2.1.277）： claude -p 和 Agent SDK 会话遇到内部错误时，以前可能会一直挂起而不返回结果——对管道而言，这是最糟糕的故障模式，因为只能依靠外部超时终止运行。现在它们会报告错误并以代码 1 退出，因此下方的退出代码表再次构成完整约定。同一版本还会让无头会话在退出时保存成本和用量总计：恢复无头会话（claude -p --resume、SDK 或 VS Code 扩展窗口重新加载）时，会话总计不再从零开始，从而避免在多次恢复的无头运行中低估成本。²¹⁹

退出代码：

控制 -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；并拒绝创建云会话。²⁰⁶²⁰⁹

--permission-prompts none（v2.1.259）： 这是无人值守主机的配套选项。任何会触发权限提示的操作都会被自动拒绝，而当前启用的权限模式（包括自动模式）仍会继续自行作出所有无需人工介入的决定。请勿将其与 --permission-prompt-tool 混为一谈；后者会将权限提示委派给 MCP 工具，而不是直接拒绝。CLI 参考文档尚未列出这一新标志；应以 CHANGELOG 为准。²¹¹

非交互会话中的 cd 可跨轮次保持生效（v2.1.265）： 接收 stream-json 输入的 -p 会话、Agent SDK 会话和云会话，不再在每条新用户消息到来时重置 shell 工作目录——在一轮中执行的 cd，下一轮仍然有效。²¹⁵

--system-prompt-snapshot off（v2.1.267）： 默认情况下，对话会在每次请求中复用已记录的系统提示词。此标志则会在每次请求时重新渲染系统提示词，适合迭代提示词文本：每次运行都会采用最新修改，而不是使用快照；代价是牺牲快照原本用于保障的提示词缓存稳定性。²¹⁶

--bare 严格遵守其限制（v2.1.286）： --bare 现在只连接命令行中指定的 MCP 服务器，不向模型发送任何系统提醒，也不启动后台任务；达到超时时间的 shell 命令会停止，而不会转入后台。无头模式文档指出，在 v2.1.286 之前，这些限制仅部分生效，并建议在脚本化调用和 SDK 调用中使用 --bare。²³¹²³³

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'

会话管理

会话会保留对话历史，以便后续继续处理。对于跨多个会话的复杂工作，会话持久化至关重要：

# 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。²⁶²²⁴⁹

关联 PR 的会话（v2.1.27+，自 v2.1.119+ 起扩展）： 启动与特定拉取请求或合并请求关联的会话。自 v2.1.119 起，除了 github.com，--from-pr 还接受 GitLab MR、Bitbucket PR 和 GitHub Enterprise PR URL：⁷⁴¹⁵²

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 徽标可通过 prUrlTemplate 设置指向自定义代码审查 URL（v2.1.119+）——当团队需要从 PR 跳转至独立的审查工具时，此功能尤为实用。¹⁵²

/resume 接受 PR URL（v2.1.122+）。 现在，将 PR URL 粘贴到 /resume 搜索框中，即可找到最初创建该 PR 的会话——支持 github.com、GitHub Enterprise、gitlab.com（包括自托管 GitLab）和 bitbucket.org。¹⁵⁴

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

# 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 保留下来。¹⁸⁹ 自 v2.1.214 起，以分叉方式启动的会话会将 SessionStart hook 的来源报告为 "fork"（此前为 "resume"），以便按来源匹配的 hooks 区分二者。¹⁹⁰ v2.1.216 将 /fork 确认信息精简为一行，显示新会话名称及其 claude attach ID。¹⁹² 自 v2.1.221 起，分叉会话会创建自己的 worktree，而不是在原会话的检出目录中工作——探索替代方案的分叉不再与主会话中尚未提交的文件发生冲突，从而消除了将副本用于实验时的一大隐患。¹⁹⁹ v2.1.232 还将分叉设为 subagents 的默认行为：subagent_type: "fork" subagent 会继承完整对话和提示词缓存；交互式会话中的非队友 agent 默认也会在后台生成。²⁵⁵

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

计划模式

计划模式将 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 会提供 3 个选项： - “是，清除上下文并自动接受编辑”（Shift+Tab）——使用完整上下文容量重新开始执行计划 - “是，并手动批准编辑”——保留上下文，由您批准每项更改 - “是，自动接受编辑”——保留上下文，由 Claude 执行，无需逐项批准编辑

获批后自动清除上下文是推荐的工作流程。这样可为计划提供全新的上下文窗口，显著提高计划执行的一致性——不受旧对话干扰，Claude 能更长时间地紧扣目标。

适合使用计划模式的情况： - 涉及架构决策的新功能实施 - 希望先审查方案的多文件重构 - 应先探索再修改的陌生代码库 - 存在多种可行方案且希望参与决策的任何任务

专家提示： 在计划模式中投入的时间越多，Claude 成功实施的可能性就越高。计划模式实际上提供了零风险的探索过程——没有危险的工具调用，也不会产生无效编辑。不妨充分利用。

屏幕阅读器模式（v2.1.208）

Claude Code 提供专用的屏幕阅读器模式，可调整终端 UI 以适配辅助技术。可通过以下 3 种方式之一启用：¹⁸⁶

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

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

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

Anthropic 在官方文档新增的无障碍页面中介绍了此模式及其交互方式。¹⁸⁶

每行输出前不再暂停（v2.1.287）： 屏幕阅读器模式现在会直接写入新增或变更的行，不再先将光标停在行首。CLAUDE_AX_PREPARK_MS 用于设置该暂停时长（单位为毫秒）；其默认值现为 0（此前为 50），如需恢复原行为，请设置 CLAUDE_AX_PREPARK_MS=50。同一版本还修复了一系列屏幕阅读器问题，包括搜索框中的光标偏离已输入文本，以及编辑批准提示中未显示变更行等。²³²²³³

配置系统深入解析

Claude Code 采用分层配置系统。理解这一层级结构至关重要：较高层级会覆盖较低层级，而企业设置根本无法绕过。

配置层级

在提示符中设置配置：/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 则保存并关闭（此前为撤销更改）。¹⁷⁴

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
  }
}

当团队拥有庞大的 skills 库、又希望收紧运行时暴露范围时，skillOverrides 便十分有用。off 会让某个 skill 同时对模型和斜杠选择器隐藏；user-invocable-only 保留按名称调用的能力，但将其排除在模型选择之外；name-only 则只显示 skill 名称，不显示完整描述。¹⁵⁶

新增设置（v2.1.174–176）：

• availableModels / enforceAvailableModels（托管设置，v2.1.175+）：availableModels 允许列表限制会话可选择的模型。设置 enforceAvailableModels: true 后，允许列表还会约束 Default 模型：若 Default 会解析为不允许的模型，则回退到第一个允许的模型；同时，用户或项目设置不能再扩大托管的 availableModels 列表。配套修复（v2.1.176）堵住了别名选择可能经由 ANTHROPIC_DEFAULT_*_MODEL 重定向到被屏蔽模型的漏洞，/fast 也不再允许切换到允许列表之外的模型。¹⁷² 自 v2.1.187 起，组织可以在 /model 选择器、--model、/model 和 ANTHROPIC_MODEL 上统一强制执行模型限制，选择受限模型时会显示“restricted by your organization’s settings”提示。¹⁷⁶
• language（v2.1.176 改进）：除设置回复语言外，会话标题现在默认以对话所用语言生成；如需固定标题语言，请设置 language。¹⁷²
• footerLinksRegexes（v2.1.176）：在页脚行中显示按正则匹配的链接徽章，可通过用户设置或托管设置配置。¹⁷²
• wheelScrollAccelerationEnabled（v2.1.174）：设为 false 可在全屏模式下禁用鼠标滚轮滚动加速。¹⁷²

新增设置（v2.1.207–v2.1.212）：

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

新增设置（v2.1.217）：

• emojiCompletionEnabled（v2.1.217）：在提示输入框中自动补全 emoji 短代码：输入 :heart: 即可插入 ❤️，输入 :hea 这类片段则会给出建议。默认开启；设为 false 可禁用。¹⁹⁴

新增设置（v2.1.219）：

• sandbox.network.strictAllowlist（v2.1.219）：对沙箱命令访问不在允许列表中的主机时直接拒绝，不再弹出提示，而非显示权限对话框。参见沙箱模式。¹⁹⁶
• workflowSizeGuideline（v2.1.219）：可在任意设置文件（用户、项目或托管）中设定 Dynamic workflow 规模的建议准则，而不必只通过 /config 设置。Dynamic workflow 默认采用 medium 准则（“aim for fewer than 15 agents”）；当某个设置文件已提供该值时，/config 中的对应行会自动隐藏。这只是建议，而非强制上限。参见 Subagents。¹⁹⁶

新增设置（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 允许列表依然对每一行生效，而标签只改变选择器中显示的内容，不改变实际运行的模型。²⁵⁰²⁴⁸
• promptCacheTtl / subagentPromptCacheTtl（任意设置文件，v2.1.242+）：按请求类别分别设为 "5m" 或 "1h"，这样 API 密钥用户和云服务商用户就能让主对话保持一小时缓存，而 subagents 仍保持五分钟。参见缓存策略。²⁵⁰²⁴⁸
• modelPricing（托管设置，v2.1.243+）：组织按合同约定的各模型费率和折扣系数，/cost、状态栏和遥测成本数据将使用这些费率，而非标价。参见查看费用。²⁵⁰

新增设置（v2.1.247）： - feedbackDrafts（v2.1.247）：用于控制新增的 SendFeedback 工具。会话中出现问题时，Claude 可以起草一份反馈报告，供您审阅后通过 /feedback 发送；如需关闭起草功能，请使用此设置。请参阅斜杠命令中的 /feedback 一行。²⁴⁵ - spinnerTipsOverride 结构扩展（v2.1.247）：提示条目现在除了纯字符串之外，还可以是 {id, text, cooldownSessions, priority} 对象；该对象新增了 tipsFile 和 label 键，组织可以将自有提示与内置提示一同轮换展示（上文示例展示的即为扩展后的结构）。设置参考文档现已收录这些新键。²⁴⁵²²⁷

较新的设置（v2.1.248–251）：

• desktopSessionCleanupPeriodDays（v2.1.248）：限定由桌面端写入的会话可免于记录清理的最长期限。与这个选项相比，随之发布的修复更值得关注：Claude Desktop 和 Cowork 的会话过去会在 cleanupPeriodDays（默认 30 天）后消失；现在只要会话仍在应用中，清理就会保留它们，除非组织策略接管了保留期限。²⁰⁶
• 项目 env 限制（v2.1.251）：项目级 .claude/settings.json 中的 env 块不能再设置 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR 或 TMPDIR/TMP/TEMP，请改在 shell、用户设置或托管设置中配置。这样，克隆下来的仓库就无法改变 Claude Code 写入配置文件和临时文件的位置。²⁰⁶

较新的设置（v2.1.257-259）：

• timeFormat / timeZone（v2.1.257）：控制 Claude Code 显示时间的方式，包括每轮结束时的完成时间和记录中的时间戳。timeFormat 可取 12 小时制、24 小时制、24 小时制 UTC，或显式的 strftime 格式；timeZone 用于指定时区。²¹¹ 设置参考文档现已收录这两个键。²²⁷
• permissions.blockReadsOutsideWorkingDirectories（v2.1.257）：直接拒绝读取会话工作目录之外的文件。未启用此设置时，auto mode 现在会在会话首次进行此类读取前询问一次（请参阅自动模式）。²¹¹ v2.1.273 补上了两处缺口：检查器无法完整分析的 Bash 命令会弹出确认，而不再跳过检查；在此设置下，由仓库设置指定的记忆目录不会被加载、调取或索引。²¹⁷
• managedMcpServers / managedSourcesBehavior：托管作用域的键，详见企业部署，分别用于组织向所有用户提供 MCP 服务器（v2.1.259），以及选择性地合并多个托管来源（v2.1.257 中完善）。²¹¹²⁴⁴

较新的设置（v2.1.261）：

• bashOutputMaxChars / taskOutputMaxChars（v2.1.261）：提高 Claude 以内联方式接收的命令输出（以及后台任务输出）上限，超出部分保存到文件，最高可达 128K 个字符。这与 BASH_MAX_OUTPUT_LENGTH 环境变量的机制不同：后者设置的是从命令的工作输出文件回读的窗口大小（默认 30,000 个字符，上限 150,000）；而这两个键决定的是内联与持久化到文件之间的阈值。超过阈值后，输出会写入一个文件，Claude 可按需读取，而不会被截断。²¹⁴ 自 v2.1.265 起，持久化一侧也有了上限：保存到磁盘的工具结果最多 1 GB，对话中的预览会注明已保存的文件是否被截断。²¹⁵ 任务这一半已在 v2.1.277 中废弃：已弃用的 TaskOutput 工具被移除，Claude 改用 Read 读取后台任务的输出文件，taskOutputMaxChars 和 TASK_MAX_OUTPUT_LENGTH 也不再生效。bashOutputMaxChars 不受影响。²¹⁹

较新的设置（v2.1.267-269）：

• maxEffortLevel（v2.1.267）：限制用户可选择的 effort 级别上限，可在顶层设置，也可在 modelSettings 下按模型设置，适用于所有提供商，包括 Bedrock、Vertex 和 Foundry。用户仍可选择低于上限的级别；它是 /effort 在管理员一侧的补充。²¹⁶
• advisorModel：已保存的 advisor 模型（fable、opus、sonnet 或完整 ID），由 /advisor 写入用户设置；--advisor 可在单个会话中覆盖它，CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 则会关闭该工具。请参阅Advisor 工具。²⁷⁴
• sandbox.allowNestedUserNamespaces（v2.1.305）：允许 Linux 和 WSL2 上的沙盒命令创建用户命名空间（用于 Chromium、rootless podman）。这会让这些命令得以绕过沙盒的文件保护，因此该键只从用户设置或托管设置中读取。请参阅沙盒模式。²⁷⁸[^287]
• bashEditDiffEnabled（v2.1.269）：当 Bash 工具执行文件编辑时，工具结果会附带该命令所改动文件的 diff，让对话中能看到 sed 式编辑的实际效果。²¹⁶

较新的设置（v2.1.275）：

• syncClaudeAiSkills / syncClaudeAiPlugins（v2.1.275）：在 claude.ai 账户中启用的 skills 和 plugins，现在会同步到使用该账户登录的终端会话中。将任一键设为 false，即可让终端会话只使用本地的 skills 和 plugins。请参阅 Skills 和插件系统。²¹⁸

较新的设置（v2.1.282-283）：

• maxProseWidth（v2.1.282）：在宽终端中限制 Claude 正文的显示宽度。段落、标题、列表和引用块会在指定列数内换行，表格和代码块则保持全宽。取值为整数列数，最小为 40。²²⁵²²⁷
• deniedModels / availableModelsMatch（托管，v2.1.283）：deniedModels 可屏蔽特定模型，即使 availableModels 允许使用它们也不例外。像 "opus" 这样的系列别名会屏蔽整个系列；"claude-opus-5" 同样会屏蔽 Opus 5.5（若只屏蔽 Opus 5，请写 "claude-opus-5-0"）。默认情况下，"claude-opus-5" 之类的 availableModels 条目也会放行在其基础上延伸的后续版本；设置 availableModelsMatch: "exact" 后，每个条目只放行其所指定的版本，新版本在列入之前将一直被屏蔽。Claude Code 只从托管设置中读取这两个键。²²⁶²²⁷
• allowClaudeInChromeWithManagedMcp（托管，v2.1.282）：允许 claude --chrome 与独占式的 managed-mcp.json 同时运行；Chrome 被屏蔽时显示的错误信息现在会注明该键。²²⁵ 设置参考文档现已收录此键：它只从设备自身的托管设置中读取，且针对 claude-in-chrome 的 deniedMcpServers 条目仍会屏蔽该服务器。²³³

较新的设置（v2.1.285）：

• allowedProviders（托管，v2.1.285）：限定一台机器可使用的 API 提供商：Anthropic API、自定义端点、Bedrock、Mantle、Vertex AI、Foundry、AWS 上的 Claude Platform，或 Cloud 网关。²²⁹ 设置参考文档已收录此键；当服务器托管设置也下发了一份列表时，来自机器自身管理来源的列表仍然有效，因此会话只能使用同时出现在两份列表中的提供商。²³³

设置速查：最常被搜索的选项

如果您是来按名称查找某个特定设置的，这里就是简明索引。每个条目都注明了其发布版本，以及（如有归属作用域）所属的作用域：

各主题的官方文档在哪里？

本指南是一本实战手册，而非权威参考文档。如需查阅 Anthropic 某个子系统的官方页面，请参阅以下位置（本指南的每个章节也都附有各自的交叉链接）：

环境变量参考

身份验证与 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_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]

行为控制：

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_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 会收到通知。²²⁹ 自 v2.1.288 起，该限制仅适用于无人值守会话（-p、Agent SDK、CI 和云端会话）；终端、桌面应用和 VS Code 会话中的后台命令不受时间限制。工具参考文档对此予以确认：”Before v2.1.288, it applied in every session.”²³⁴²³⁷

网络与代理：

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+)[^279][^280]
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 导出器与敏感字段管控：²⁶⁸

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 会话不会显示提示，因此升级后请确认您的收集器仍能收到数据。²²⁵²²⁷

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 控制。¹⁵⁴

v2.1.122+ 事件级变更：api_request 和 api_error 日志事件中的数值属性现以数字（原为字符串）形式输出，修复了对 schema 做严格类型校验的下游 OTel 收集器的问题。新增的 claude_code.at_mention 日志事件会在 Claude Code 解析 @ 提及时触发。¹⁵⁴

v2.1.300 属性：api_request 事件将缓存写入拆分为 cache_creation_5m_tokens 和 cache_creation_1h_tokens；trace 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。²⁷³

v2.1.301 和 v2.1.302 属性：tool_decision 事件携带 classifier_verdict 和 permission_mode，从而可以区分 auto mode 分类器的决定与权限规则的决定；启用 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。监控文档尚未列出这三个属性。²⁷⁵²⁷⁶

v2.1.307 事件：每当工具调用被权限规则、auto mode、安全检查、hook 或沙箱阻止、要求确认或退回时，都会触发 claude_code.safety_event；除回合结束事件外，该事件均带有 tool_use_id。监控文档已列出该事件，现在也列出了 classifier_verdict（v2.1.301+）。²⁷⁸[^287]

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。¹⁷⁹

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

v2.1.265 网关遥测：当网关的托管设置在 OTEL_EXPORTER_OTLP_ENDPOINT 中指定了收集器时，Claude apps 网关会话现在会将 OpenTelemetry 直接导出到该收集器，不再经由网关中继；未指定收集器的会话仍使用中继。同一版本还为 Claude Desktop 和 Cowork 经 Claude apps 网关发送的遥测添加了 user.email 和 user.groups，与终端会话保持一致。²¹⁵

v2.1.280 hook 遥测：hook_execution_complete OTel 事件现在携带 hook 输出大小，以及被保存到文件的超大输出数量。²²⁰

v2.1.287 prompt_text：user_prompt 事件现在携带 prompt_text，它是 prompt 的副本，供会嵌套带点键名的后端使用。凡是您的管道丢弃或遮蔽 prompt 的地方，请对 prompt_text 做同样处理。²³²

API / 模型控制：²⁶⁸

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：²⁶⁸

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：²⁶⁸

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+)

企业 / 认证：²⁶⁸

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支持在多个层级灵活切换模型。

可用模型

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测试版请求头时最高可达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。²²⁸²³⁰

模型页面列出了API代码从Sonnet 5迁移时的5项破坏性变更：使用between_tools时会关闭前置思考；强制使用工具会返回错误；思考块与模型及对话绑定；Claude API和Google Cloud不接受computer_20251124；顾问工具不接受Opus 4.8、Opus 4.7和Sonnet 5作为顾问。工具调用之间的文本也会在thinking块中返回，因此，以流式方式显示这些文本的界面会停止显示内容，直到将display设置为可返回文本的值。²³⁰

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测试版请求头时最高可达300K）。始终开启的自适应思考——模型概览表将其与Fable一样标注为“自适应（始终开启）”，而非Opus 5默认开启但可关闭的模式。effort默认为medium（Opus 5默认为high），v2.1.280也相应调整了设置沿用规则：在/effort改为按模型设置之前保存的思考力度，不再应用于Opus 5.5等新发布的模型；在您选择力度之前，模型使用自身的默认值。可靠知识截止日期：2026年6月（训练数据也截至2026年6月），与Fable 5.1并列为当前所有模型中最新。最早于2027年9月22日退役。需要Claude Code v2.1.280或更高版本。²²⁰²²¹

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

1. 无法禁用思考。 thinking: {type: "disabled"}和thinking: {type: "enabled", budget_tokens: N}均返回400错误。请移除thinking字段，改为选择思考力度。
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. Claude API和Google Cloud会拒绝computer_20251124。 请改为声明computer_toolset_20260801工具集；Bedrock仍保留旧工具。 还有一项变更不会导致任何请求失败，但会改变响应结构：模型在工具调用之间输出的文本会以thinking块返回，在默认的display设置下，这些块为空。以流式方式展示这类说明文本的界面会停止显示内容，直到将其设置为display: "updates"（beta）或"summarized"。²²²

Claude Code中基于内容的模型回退。 Opus 5.5运行时配有安全分类器，最常标记的是生物学和网络安全内容。当分类器标记某个请求时，Claude Code会改用另一个模型重新执行请求，并显示提示：被标记为生物学相关的请求转交Opus 5，被标记为网络安全相关的请求转交Opus 4.8。此后，会话会一直使用回退模型，直到您通过/model切换回来。在/config中关闭消息被标记时切换模型（switchModelsOnFlag: false），即可改为每次切换前询问。²²³ 从v2.1.287起，切换时会保留当前的推理强度，而不采用回退模型的默认值。因此，使用Opus 5.5默认值medium的会话切换到Opus 4.8后仍会保持medium，尽管Opus 4.8的默认值是high。²³²²³³

Claude Opus 5（2026年7月；上一代Opus档位）： 从v2.1.219（2026年7月24日）起，直到v2.1.280将Opus 5.5设为默认Opus模型之前，Opus 5一直是Opus档位的模型，也是opus别名指向的模型；以下介绍的是它在2026年7月发布时的情况。Anthropic将其描述为Opus 4.8的直接替代升级：输入价格同为$5/MTok，输出价格同为$25/MTok，“以相同成本大幅提升性能”，而且在最高推理强度下，使用的token数量比Opus 4.8平均减少约26%。它曾是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月）——从发布之日起，直到Fable 5.1于2026年9月1日推出（知识截止时间为2026年6月），它一直是当时所有Claude模型中知识最新的模型。²⁴¹ 随着Opus 5推出，Opus 4.8被移入文档的旧版模型表，与4.7和4.6并列——仍可使用，但不再是推荐的默认选择。¹⁹⁷

将运行框架从Opus 4.8迁移到Opus 5时的两项破坏性变更：¹⁹⁷

1. 默认开启思考。 在Opus 4.8上，不含thinking字段的请求运行时不会进行思考；在Opus 5上，同样的请求会启用自适应思考。max_tokens仍然是总输出量的硬性上限，涵盖思考内容和响应文本。因此，对于此前未启用思考的工作负载，请重新检查输出额度是否充足。传入thinking: {type: "disabled"}可恢复原有行为，但须遵守下一项限制。
2. 禁用思考时，推理强度最高只能设为high。 将thinking: {type: "disabled"}与xhigh或max推理强度组合使用，会返回400。此检查对每个请求分别执行——即使同一对话中的前几轮请求已被接受，在禁用思考时将推理强度提高到xhigh仍会遭到拒绝。

具体到Claude Code：Opus 5的effort默认值为high（与Claude API上的默认值相同），并支持全部档位：low、medium、high、xhigh、max。Anthropic官方迁移指南建议，在模型能力比token开销更重要的场景中测试max推理强度。快速模式支持Opus 5，输入和输出价格分别为每MTok $10和$50（参见快速模式）。¹⁹⁷¹⁹⁸

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-256从未发布到npm——v2.1.257（9月1日）才是首个可安装且支持该模型的版本。模型ID：claude-fable-5-1（Bedrock：anthropic.claude-fable-5-1）。它与Fable 5处于同一档位，每token价格相同：输入$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模型中最新，随后于2026年9月22日被Opus 5.5（知识截止时间为2026年6月）追平，Sonnet 5.5也于9月28日达到同一水平。停用时间不早于2027年9月1日。从v2.1.301起，如果组织无法使用最新的Fable模型，fable和best会改用上一代Fable模型重试一次，而不是直接报错。²⁷⁵

相较于Fable 5，有三项破坏性变更：强制使用工具会返回错误，较早的模型无法读取它的思考块，编辑先前轮次会使思考块失效。另有五项新增功能或改进：按消息设置推理强度（beta）、仅在当前轮次生效的系统消息（beta）、工具调用之间的进度更新（display: "updates"，beta）、更低的缓存读取费用，以及内容来源信息。Claude Mythos 5.1是规格相同的同一模型，仅通过Project Glasswing受邀开放。随着此次发布，Fable 5被移入文档的旧版模型表，与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日）： 发布后的首个版本修复了四处问题。对于有权使用Fable 5.1的组织，/model选择器现在会显示该模型——修复前，只有输入完整命令/model claude-fable-5-1才能选择它。Fable 5.1的提示词缓存现在也涵盖附加在工具结果之后的上下文；此前，这些内容会在每个工具调用轮次中作为未缓存的输入重新发送，悄然削弱了0.025倍缓存读取费率在长时间智能体会话中的成本优势，而这恰恰是该费率旨在惠及的场景。在会话中途更改/effort也不再使提示词缓存失效。此外，配置为model: fable的智能体现在会遵循ANTHROPIC_DEFAULT_FABLE_MODEL所固定模型中的[1m]标记，而不再悄然使用200K上下文窗口运行。²¹²

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参数。²⁶¹ 具体到Claude Code：Fable 5与Opus 5一样，支持完整的推理强度档位（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 xhigh），开箱即用的默认模型也不再取决于您的套餐——除Microsoft Foundry外，所有由Anthropic运营的套餐均默认使用Opus 5.5；如果需要最高能力上限，请通过/model fable主动选择Fable档位——截至v2.1.257，该档位对应Fable 5.1。^{261197207242220221}

Opus 4.7（2026年4月16日）： 上一代旗舰模型，目前仍全面可用。提供1M token上下文窗口，按标准价格计费——长上下文不额外加价。最大输出为128K，仅支持自适应思考（已移除扩展思考），并新增xhigh推理强度档位，建议将其作为编程和智能体工作负载的起始设置。¹⁴⁵ 可靠知识截止日期：2026年1月。训练数据截止日期：2026年1月。模型ID：claude-opus-4-7。定价与Opus 4.6相同，输入/输出每百万token为$5/$25；5分钟缓存写入为$6.25，1小时缓存写入为$10，缓存读取为$0.50，均按每百万token计费。¹⁴⁴ 在SWE-Bench上，Opus 4.7解决的生产环境任务数量是Opus 4.6的3倍；在CursorBench上得分为70%（4.6为58%）；在Anthropic包含93项任务的内部编程基准测试中，解决率提升了13%。¹⁴⁴ 它采用了新的分词器——同一文本的token数量预计约为原来的1至1.35倍；请相应提高max_tokens的余量，并调整上下文压缩的触发阈值。¹⁴⁵ 视觉功能支持最高2,576像素/375万像素的图像，并采用1:1像素坐标。¹⁴⁵

Opus 4.7编程基准测试（2026年4月）：¹⁵¹

各套餐的默认模型（Claude Code）：²⁰⁷²²¹

自v2.1.280（2026年9月22日）起，默认模型不再按套餐区分：所有由Anthropic运营的套餐及第一方提供商均默认使用Opus 5.5，唯一保留的例外是Microsoft Foundry。此前这里最关键的问题——“我使用哪种套餐？”——已不再影响答案。

Opus 4.7中Messages API的不兼容变更（调用方可感知）：¹⁴⁵

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

任务预算（测试版请求头task-budgets-2026-03-13）允许您通过output_config.task_budget向模型提供整个智能体循环的token用量目标；最低为20K token。¹⁴⁵

Opus 4.6（旧版）： 仍可通过claude-opus-4-6使用，提供1M上下文窗口和128K最大输出。若要提升智能体编程表现，可以考虑迁移至Opus 4.7。Opus 4.6最初于2026年2月5日发布。⁷⁹¹⁴⁴ 自v2.1.117（2026年4月22日）起，Pro和Max订阅用户使用Opus 4.6及Sonnet 4.6时，默认推理强度为high（此前为medium）；Opus 4.7仍为xhigh。这一调整恢复了模型在3月4日至4月7日推理强度下调后受损的智能表现；4月23日的复盘报告记录了这次下调。¹⁵²¹⁵³

Sonnet 5（2026年6月30日；上一代Sonnet档位）： 从v2.1.197起，Anthropic API上的sonnet别名选择此模型，直到v2.1.284将其改为Sonnet 5.5。发布时，Anthropic将其定位为“速度与智能的最佳结合”。Anthropic表示，其性能接近Opus 4.8，但价格更低；相较于Sonnet 4.6，它在智能体推理、工具使用、编程和知识工作方面均有显著提升，同时不良行为的整体发生率更低，网络安全能力也明显弱于Opus系列模型（这种安全权衡使其得以发布，未受到出口管制的阻碍）。模型ID：claude-sonnet-5（不带日期的固定快照）。提供1M token上下文窗口，最大输出为128K（在Batches API中使用output-300k-2026-03-24测试版请求头，最高可达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显示为标准标价，而非限时优惠。²⁵¹ 这一价格比Opus 5.5的$4/$20低50%（比Opus 5此前的$5/$25低60%）。在Claude Code中，Sonnet 5的effort参数默认为high（如需更改，请显式设置）。使用/model claude-sonnet-5可选择此模型。¹⁸⁰²³⁰

v2.1.197（2026年6月30日）将Sonnet 5设为Claude Code的默认模型，适用于当时的新会话。它一直是标准档位（Pro、Team Standard）的默认模型，直到2026年9月22日，v2.1.280将这些套餐的默认模型改为Opus。Sonnet 5已不再是Claude Code中任何套餐的默认模型；自v2.1.284起，Anthropic API上的/model sonnet也改为选择Sonnet 5.5。使用/model claude-sonnet-5或ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5可继续使用Sonnet 5。请参阅上方套餐表。^{181207220221228}

Sonnet 4.6（2026年2月17日，现已由Sonnet 5取代）： 均衡型模型；曾取代Sonnet 4.5，成为claude.ai和Claude Cowork的默认模型。⁹³ 定价与Sonnet 4.5相同（输入/输出每百万token为$3/$15）。智能体搜索表现有所提升，同时消耗的token更少。支持扩展思考、自适应思考和1M token上下文窗口（测试版）。最大输出为64K（v2.1.77中的上限为128K）。¹¹⁹ 知识截止日期：2025年8月（可靠知识），2026年1月（训练数据）。模型ID：claude-sonnet-4-6。 Claude Mythos Preview（2026年4月7日）：面向防御性网络安全工作的前沿模型研究预览版，通过Project Glasswing提供。¹³⁹仅限受邀用户使用，尚未全面开放。Anthropic表示，出于安全权衡，Opus 4.7在网络安全方面的能力被刻意设计得比Mythos更弱。同时，Anthropic已在https://claude.com/form/cyber-use-case推出网络安全验证计划，为需要更高访问权限的正规安全研究人员提供申请渠道。¹⁴⁶

这些价格差异为何重要：一次典型的编码会话会消耗50K–200K输入token和10K–50K输出token。按Haiku 5.5针对不超过100K token的提示词所采用的费率计算，每次会话约为$0.01–$0.05。按Opus 5.5的$4/$20费率计算，同样的会话需要$0.40–$1.80，约为前者的40倍（未计入提示词缓存折扣）。任务不需要Opus时，请使用Sonnet或Haiku。¹²²²

各模型的适用场景

Haiku：适合执行探索任务、简单文件搜索和快速问答的subagents。按不超过100K token的提示词费率计算，其成本约为Opus 5.5的1/40（提示词超过100K时为1/8），响应也更快。非常适合无需深度推理的后台任务。

Sonnet：注重成本时，日常开发的主力模型——自v2.1.284起，Anthropic API上的Sonnet 5.5与Sonnet 5一样，价格为$2/$10²²⁸——而自v2.1.280将Pro和Team Standard切换到Opus后，Sonnet已不再是任何套餐的默认模型（原生支持1M上下文，标准标价为每百万token $2/$10；原定于9月1日的涨价已取消）。^181251207220这里需要理解的变化是：Sonnet如今需要您主动选择，选择它的理由很直接——同样支持1M上下文，每token成本只有Opus 5.5的一半。它能胜任大多数编码任务：实现功能、修复缺陷、编写测试和代码审查。历史说明：长期以来，包括本文在内的多处资料都称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成本、更短的响应延迟，或更经济地运行subagents时，请使用Sonnet。

Opus：深度推理档模型——自v2.1.280起，opus别名指向Claude Opus 5.5（每百万token $4/$20，1M上下文，effort默认为medium），且从该版本起，所有套餐的初始模型都改为Opus。因此，真正需要决定的是何时切换到其他模型：架构决策、棘手的调试、复杂系统理解、安全分析，以及需要长程规划的智能体任务，应继续使用Opus；如果任务足够常规，token价格减半比额外的推理能力更重要，则切换到/model sonnet。²²⁰²²¹（从v2.1.219到v2.1.278，opus别名指向价格为$5/$25的Opus 5。）¹⁹⁷本段其余内容描述的是Opus 4.7于2026年4月16日发布时的情况，作为历史记录保留。¹⁴⁴¹⁴⁷Opus 4.7在SWE-Bench上解决的生产任务数量是Opus 4.6的3倍，在CursorBench上的得分为70%（此前为58%），并在包含93项任务的内部编码基准测试中将解决率提升了13%。¹⁴⁴Claude Code在Opus 4.7上默认采用xhigh推理强度，可通过/effort调整（v2.1.111+）。¹⁴⁶¹⁴⁷Max订阅用户通过Anthropic API使用Opus 4.7时，无需设置--enable-auto-mode即可使用自动模式；其他套餐或提供商的可用性则取决于具体套餐和管理员设置。¹⁴⁶1M上下文按标准价格计费，不收取长上下文溢价。值得了解的行为变化：Opus 4.7会更严格地按字面遵循指令，根据任务复杂度调整回复长度，默认运行更少的subagents，并采用更直接的语气，减少以肯定用户为主的措辞。如果提示词中包含强制模型汇报中途进展或反复核查的辅助指令，不妨尝试移除。¹⁴⁵

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后，只显示这些条目、默认选项和当前会话所用的模型。此设置键会忽略项目设置和本地设置，availableModels允许列表仍会对条目进行筛选。Claude Code会移除无法提供服务的条目，将暂时无法选择的条目置灰并注明原因；如果没有任何条目可用，则恢复为内置列表。²⁵⁰²⁴⁸

{
  "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的默认模型，不再覆盖所有模型设置：智能体定义中的model:以及每次启动时显式指定的模型，其优先级都高于该环境变量。²⁰⁶自v2.1.257起，可通过CLAUDE_CODE_SUBAGENT_MODEL_FORCE主动恢复旧行为：它会将CLAUDE_CODE_SUBAGENT_MODEL指定的模型（未设置时则使用主对话的模型）应用于所有subagents，忽略每次启动时选择的模型和智能体定义中的model:。²¹¹

备用模型链（v2.1.166+）：fallbackModel设置最多可配置3个备用模型，在主模型过载或不可用时依次尝试。--fallback-model标志此前只能在会话中途切换时使用，现在也可从启动时起应用于交互式会话。²⁶³

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

当API返回意外且不可重试的错误时，Claude Code现在也会先使用备用模型重试当前轮次一次，再报告失败。这样，主模型的暂时性问题就能通过平稳降级处理，而不会直接中断当前轮次。²⁶³自v2.1.286起，当Anthropic API拒绝默认配置或别名解析出的模型时，Claude Code会使用同档位的上一代模型重试一次，避免每一轮都失败。如果因模型被拒绝或通过--fallback-model重试而切换到不支持快速模式的模型，则以标准速度运行。²³¹

自v2.1.178起，上下文压缩也遵循备用模型链——如果主模型在压缩过程中出现过载或不可用，压缩步骤会回退到配置的fallbackModel/--fallback-model链，而不会导致当前轮次失败。对于长时间自主运行的任务，这弥补了此前的一处缺口：原本可以恢复的压缩操作，不再因模型的暂时性错误而导致会话中断。¹⁷³

扩展上下文

对于大型代码库或长会话，请启用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]

哪些情况下后缀才有效（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应用网关也采用相同行为：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上下文窗口，不收取长上下文溢价。¹⁴⁸900K token请求与9K token请求采用相同的每token费率。提示词缓存和批处理折扣在整个上下文窗口范围内均按标准费率适用。 能否使用[1m]变体取决于订阅计划：Max、Team和Enterprise包含具有1M上下文的Opus 4.6，而所有订阅计划（包括Max）使用具有1M上下文的Sonnet 4.6都需要额外用量额度。²³³（自2026年3月13日发布的v2.1.75起，具有1M上下文的Opus成为Max、Team和Enterprise的默认模型。）¹¹⁷¹⁴⁷ API和按量付费用户可按标准每token费率使用完整的1M上下文。¹⁴⁷

要在模型选择器中禁用1M上下文变体，请设置CLAUDE_CODE_DISABLE_1M_CONTEXT=1。从v2.1.223起，此变量的作用范围发生了变化：它通过自动压缩将所有原生支持1M窗口的模型限制在200K，而不再仅针对固定的已知变体列表；如果自动压缩未能将会话实际限制在200K，启动时会显示警告。如果您为某个模型系列设置此变量以保持成本可预测，那么新发布的1M模型从上线当天起也会受此限制，不会再出现限制悄然失效的情况。同一版本还调整了自动压缩行为：对于无法识别的模型ID，会话会保持在假定的上下文窗口内，不再任其超出；对于注册了自定义ID且实际窗口更大的网关，可设置CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1恢复旧行为。²⁰⁰ 从v2.1.287起，在Bedrock、Vertex、Foundry和Claude应用网关上，此变量也用于将Opus 4.7及后续版本和Fable限制在200K，因为这些平台已默认启用1M上下文。²³²

从v2.1.247起，Sonnet 5默认按完整的1M上下文窗口执行自动压缩：使用1M窗口的会话现在约在967K tokens时自动压缩，而非此前的约934K。²⁴⁵ v2.1.260将临近窗口上限才自动压缩的行为扩展到其余1M模型：Opus和Fable会话现在也会在接近1M tokens上限时压缩，而且超大上下文的恢复性压缩不再于10分钟后超时。²¹²

自定义基础URL也可使用1M窗口（v2.1.285）。 通过自定义ANTHROPIC_BASE_URL连接的会话，现在会使用模型本身支持的1M上下文窗口（Opus 4.7及后续版本、Sonnet 5及后续版本、Fable）。如果您的网关上限为200K，请运行/autocompact 200k。²²⁹²³³

从v2.1.271起，--resume会保留[1m]窗口：恢复会话时，即使其模型系列与配置的默认模型不同，也不会再丢失[1m]后缀。²¹⁶

v2.1.273修复了上下文用量计和自动压缩将顾问工具轮次计为实际上下文大小约2倍的问题——此前，自动压缩会在用量达到实际窗口约一半时触发。²¹⁷

查看当前模型

> /status

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

模型选择器标签（v2.1.51+）： /model选择器现在会为固定版本显示易读的标签（例如“Sonnet 4.6”），而非原始模型ID；有更新版本可用时，还会显示升级提示。⁹⁸ v2.1.219修复了合并后的Opus行仅显示“Opus”而非“Opus（1M上下文）”的问题，并将新版本高亮范围缩小到最新模型的名称本身，确保高亮标示实际发布的模型，而非列表中任意一段内容。¹⁹⁶ v2.1.283在Opus已具备1M上下文窗口的情况下，移除了Opus行和默认模型名称中的“（1M上下文）”；窗口大小本身没有变化。²²⁶

快速模式（v2.1.36+）

快速模式可显著提高同一模型的输出速度，并不会切换到更便宜的模型。在会话中使用/fast即可切换。⁸⁶

> /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或Claude Platform on AWS。此功能尚未全面开放：请联系您的客户经理或加入候补名单。^196198223

远程会话（v2.1.271）： 快速模式现在也适用于Claude Code Remote会话，包括云端会话和自托管运行器。可以沿用主机的快速模式设置，也可以直接在会话中输入/fast；两种方式都要求所在组织允许使用快速模式。同一版本还修复了/fast off：组织禁用快速模式时，该命令现在会关闭快速模式，而不再回复“快速模式不可用”。²¹⁶

定价（快速模式）：^198222223

Opus 4.7的陷阱（v2.1.219）。 不支持快速模式的模型，其行为并不一致。向claude-opus-4-7发送包含speed: "fast"的请求，现在会返回错误，不会静默回退到标准速度。Opus 4.6是一个需要留意的例外：它接受speed: "fast"，但仍以标准速度运行，按标准费率计费，并报告usage.speed: "standard"。如果您的运行框架固定使用4.7，并依赖快速模式请求静默降级，那么这些请求现在会直接失败；请将固定模型改为Opus 5.5、Opus 5或Opus 4.8。¹⁹⁸

适合使用快速模式的情况： - 围绕小幅改动快速迭代，且延迟是主要瓶颈 - 生成测试、样板代码或重复性代码，速度比成本更重要 - 按顺序处理一系列类似任务

不适合使用快速模式的情况： - 长时间运行的智能体任务（整个运行过程的成本仍会翻倍） - 后台subagents任务（无人等待输出） - 需要控制预算的会话

快速模式包含完整的1M上下文窗口（v2.1.50+）。整个上下文统一按固定倍数计费，包括输入超过200K tokens的请求，无需额外支付长上下文附加费；此倍率还会与提示缓存和数据驻留的计费倍率叠加。⁹⁶¹⁹⁸

运行注意事项。 快速模式有独立的速率限制，与标准Opus限制分开计算；超限时会返回带有retry-after的429响应（anthropic-fast-*-tokens-*响应头会报告剩余额度）。在快速模式和标准模式之间切换会使提示缓存失效：不同速度的请求不共享缓存前缀，因此在会话中途切换/fast会导致一次缓存未命中。快速模式不适用于Batch API，也不能与Priority Tier用量承诺搭配使用。¹⁹⁸

专家提示： 快速模式不宜与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

顾问工具（实验性）

顾问工具允许Claude在任务的关键节点咨询第二个模型，通常是能力更强的模型：例如确定方案之前、错误反复出现时，或宣布工作完成之前。顾问作为服务器工具，在Anthropic的基础设施上运行，接收包含所有工具调用及结果的完整对话，并返回指导意见，由Claude采纳后继续执行。是否调用由Claude决定；您可以在提示中要求咨询顾问，但目前没有限制调用次数或强制调用的设置。此功能处于实验阶段，在Anthropic API上向订阅账户和按API计费的账户开放，并于v2.1.300开始支持Claude Platform on AWS（文档页面仍将该平台列为不支持）。通过网关使用时，请求必须完整送达Anthropic API；此外，此功能需要获取功能开关配置，因此DISABLE_TELEMETRY等变量会使其保持关闭。²⁷³²⁷⁴ 启用方式。共有3种方式：在会话中运行/advisor <model>，将选择保存到用户设置的advisorModel中（单独运行/advisor会在终端中打开选择器，并在-p、SDK、桌面端和Remote Control会话中显示当前顾问；这些会话自v2.1.260起支持文本形式的命令；/advisor off可将其关闭）；在设置文件中添加"advisorModel": "opus"；或使用claude --advisor <model>，仅对单次会话生效。这个标志未列在--help中，优先级高于设置；如果模型搭配无效，程序会在启动时退出。可用别名为fable、opus和sonnet，也可以使用完整的模型ID。CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1会移除该命令、忽略相关设置，并使该标志不产生任何效果。²⁷⁴

模型搭配、费用与界面显示。顾问模型的等级必须等于或高于主模型：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可以调用顾问，但不能担任顾问。低于主模型等级的顾问不会被挂接，系统会发出通知说明；被API拒绝的顾问则会被静默移除，在本次对话剩余期间不再使用。subagents会继承顾问，并接受相同的搭配检查，同时遵循availableModels允许列表。每次调用按顾问模型的输入和输出费率计费，或计入套餐限额。但在Fable使用用量额度计费的套餐中，Fable顾问也会消耗用量额度，前提是已通过/model fable完成一次性授权。切换顾问开关会保留主模型的提示缓存；顾问自身读取对话的内容始终不会缓存。在会话记录中，Advising行会显示已审阅、已拒绝或不可用，按Ctrl+O可查看指导意见。Mods可在turn.step的serverToolUses中看到顾问调用（v2.1.290）。²⁷⁴

推理强度控制（v2.1.111+，Opus 4.7）

Opus 4.7引入了新的推理强度调节功能，用于权衡速度与智能水平。在会话中使用/effort：

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

按模型保存（v2.1.251+）：/effort现在会按模型保存默认推理强度，因此切换模型时，每个模型都保留自己的设置。在Opus上惯用的xhigh不再沿用到Haiku上（CHANGELOG：“已将/effort改为按模型保存默认推理强度，因此切换模型时，每个模型都会保留自己的设置”）。max仅对当前会话生效的例外规则仍然适用。²⁰⁶ v2.1.284滑块按键：effortSlider:decreaseEffort、increaseEffort和toggleUltracode快捷键操作允许您在keybindings.json中重新绑定滑块的方向键和Tab键。²²⁸ v2.1.257改进了两种调节方式：/effort支持使用s进行仅对当前会话生效的选择，与/model的约定一致；--effort标志现在也仅作用于当前会话。它只会在该会话中解除对新模型默认推理强度的锁定，不再永久解除（CLI参考文档说明：它会“覆盖”默认值，“仅对本次会话生效，不会持久保存”）。²¹¹²⁴³

Max上的自动模式（v2.1.111+）

自动模式是所有套餐和服务提供商的交互式终端及VS Code会话内置的初始权限模式（v2.1.283-284）。从v2.1.285起，它也适用于第三方服务提供商或关闭遥测时的claude -p和Python Agent SDK会话，直到v2.1.302撤回了这一变更；此前，自2026年8月14日起（8月7日宣布），它已成为Pro、Max和Team的默认模式。有关公告中的研究数据、退出自动模式的方法，以及仍以手动模式启动的会话，请参阅权限模式。^{203226227228229}

一个独立的分类器模型会在每项操作执行前进行审查，检查操作是否符合您的意图且安全；自v2.1.210起，该模型为Claude Sonnet 5。¹⁸⁷ 使用--permission-mode auto可以自动模式启动会话；v2.1.111已移除旧的--enable-auto-mode标志。

可用范围的扩展历程：

• 选择退出： CLAUDE_CODE_AUTO_MODE_SERVER=0会保留本地分类器，其请求计入用量；设为1则选择启用服务器检查。在v2.1.281之前，直接连接Anthropic API时不会读取该变量；v2.1.281起，这类连接也会应用该变量。自动模式计费文档现已注明，直接连接时需要v2.1.281或更高版本才能使用该变量。²²⁴²²⁷文档称此变量为临时变量。若未设置该变量，设置CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1也会停止服务器检查。
• 服务器检查无法应用于会话时： 最常见的原因是网关或代理移除了请求中的safeguards字段、丢弃了响应中的safeguard_results，或改写了工具使用ID。Claude Code会显示一次性通知（“此会话不符合条件”），在能够识别网关时指出其名称，并在该会话的剩余时间内改用自身的计费分类器请求。在-p模式下，通知会写入stderr，stream-json输出则会发出一条system警告。Pro、Max和Team会话不会看到此通知。网关端的修复方法是原样透传请求字段和响应键。
• 检查会话： /status会显示一行自动模式服务器状态：服务器检查负责决定会话操作时显示Enabled，回退后则显示Disabled。²¹⁹

自动模式并非安全边界。 下文大部分措施是在加固分类器，而分类器不是沙箱。2026年8月26日，提示注入研究员Johann Rehberger公布了一条针对自动模式下Claude Code Opus 5的有效攻击链，报告称在小样本测试中，攻击成功率为60–80%：启动隔离python3子进程的主要攻击链在5次运行中成功了3次；另一个变体的载荷会启动无界面的claude -p实例，其两种配置分别在5次运行中成功了3次和4次。他本人也提醒，这些只是小样本结果，并非通用的攻击成功率测量。²¹⁰这条攻击链值得了解，因为其中每一步单独看来都合情合理：服务器对WebFetch返回HTTP 415，使智能体转而使用curl；下载的归档被解压到临时目录，其中包含一份清单、7条经Base85/zlib编码的数据记录、一个原生二进制文件和一个struct.py；Claude拒绝运行不可信的二进制文件，随后却自行编写了Python解码器，并在该目录内运行；解码器导入base64，base64又导入struct，而Python优先解析到了攻击者的struct.py。整个过程中没有哪条指令显然带有恶意——注入只需让受攻击者操控的路径成为完成任务最合理的方式。Rehberger还报告称，在少数几次运行中，Claude发现系统遭入侵后试图终止恶意软件进程，但自动模式拒绝了清理命令。²¹⁰他将整个发现与Anthropic曾宣传的一个数字对照：一项受委托开展的第三方评估对72个场景各运行了10次，报告称Opus 5在自动模式下的提示注入攻击成功率为0.00%。他的攻击链并不在这组场景中，因此，0.00%的基准测试结果与有效的代码执行攻击链可以同时成立；但在他看来，这两种信息并不相容。²¹⁰还需注意对此攻击的定性：Simon Willison在8月30日的更新中认同一位读者的观点，即这并非经典的提示注入——模型从未读取并遵循攻击者的指令——而是一种环境混淆攻击。²¹⁰

Anthropic将该报告标记为Informative并关闭，认为此行为符合设计预期。Rehberger转述的立场应成为设计防护措施的依据：自动模式是尽力而为的分类器，并非安全保证；攻击者蓄意将单独看来无害的步骤串成注入攻击链，超出了分类器预期的检测范围；真正的遏制边界是操作系统级隔离与网络出站控制。²¹⁰这与下文的加固措施并不矛盾，而是理解它们的正确前提。自动模式减少了需要您回应的提示，并阻止文档中列出的一组破坏性操作；它并不能确保处理不可信输入的会话安全。如果会话会接触受攻击者影响的内容——抓取的页面、下载的归档、议题文本、第三方MCP服务器——真正能限制损害的控制措施都在模型之外：容器或虚拟机、受限的网络出站访问、对智能体实际行为的监控，以及不存放您不愿泄露的SSH密钥和云凭据的主目录。自动模式批准了某项操作，并不能证明该操作安全。

添加自定义规则，同时保留默认规则（v2.1.118+）。 早期版本中的autoMode.allow、autoMode.soft_deny和autoMode.environment只能二选一：定义自己的列表，就会失去内置安全规则。$defaults哨兵值解决了这个问题——它会在您放置的位置原地展开为内置列表，让您可以在其前后添加自定义规则：¹⁵²

// .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并打开自动模式选项卡；只有当前会话支持自动模式时，才会显示该选项卡。它列出了分类器读取的所有作用域中的allow、soft_deny、hard_deny和environment条目，并显示各部分的内置规则是否生效；来自托管设置或--settings的条目为只读，所有更改都会保存到~/.claude/settings.json。向某个部分添加首条规则时，系统还会插入"$defaults"，确保内置规则继续生效。各部分的内置规则可以分别开关，但必须先添加至少一条自定义规则，才能关闭该部分的内置规则。environment会作为一份完整文档在编辑器中打开。²⁴⁹²⁴⁷

启用提示中的“不再询问”选项（v2.1.118+）。 自动模式的启用提示现在提供“不再询问”选项，经常使用的用户无需编写脚本设置标志，即可隐藏说明提示。¹⁵²

破坏性命令防护（v2.1.183）。 自动模式现在会强制阻止一组不可逆命令，除非您在会话中明确要求执行：未要求丢弃本地工作时，阻止破坏性git操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；提交并非由智能体在当前会话中创建时，阻止git commit --amend；未指明具体堆栈时，阻止基础设施销毁操作（terraform destroy、pulumi destroy、cdk destroy）。这些防护专门针对会悄然导致工作丢失或环境被销毁的操作，缩小了分类器判断失误可能造成的影响范围——智能体仍可执行这些操作，但必须得到您的明确指示，不能自行决定。¹⁷⁴

对每条shell命令进行分类（v2.1.193）。 默认情况下，自动模式分类器只审查符合任意代码执行模式的shell命令；常规命令会跳过审查。新增的autoMode.classifyAllShell设置则会将所有Bash/PowerShell命令交由分类器审查。如果希望逐一核查每次shell调用，可以接受少量延迟，换取更严密的防护。同一版本还会在会话记录、拒绝操作的浮动提示以及/permissions的近期拒绝记录中显示自动模式的拒绝原因，因此命令被阻止时，现在会说明缘由。¹⁷⁹

另外3条加固规则（v2.1.205）。 自动模式现在会阻止篡改会话记录文件——智能体无权修改审计记录本身；对无法从上下文解析的变量执行rm -rf前，会先请求确认——防止在$DIR未知时执行rm -rf $DIR这类事故；后台任务通知现在会明确说明没有发生任何人工输入，因此，会话记录中伪造的“用户已批准”文本无法被包装成有效授权并据此执行。¹⁸³第3条是一项值得牢记的提示注入防御原则：批准必须通过批准通道传入，而运行框架现在已明确声明这一前提。 命令替换无法掩盖灾难性操作（v2.1.208）。 rm -rf ~ 这类灾难性删除操作，即使藏在 $(...)、反引号或进程替换（<(...)）中，现在也会触发确认提示——即使在 --dangerously-skip-permissions 和自动模式下也不例外。将破坏性命令包裹在替换表达式中，再也无法绕过安全防护。¹⁸⁶

重置自动模式状态：claude auto-mode reset（v2.1.212）。 新增子命令，可从终端重置自动模式状态；传入 --yes 可跳过确认提示：¹⁸⁹

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

减少弹窗，审查照旧（v2.1.218）。 此前，危险 rm、后台 & 和可疑 Windows 路径这 3 项检查会弹出权限对话框，打断自动模式；现在改由自动模式分类器裁定，不再弹窗。安全审查仍会执行，但无需每次命中都由您介入。同一版本还将此行为扩展到启用自动模式的计划模式：对于静态分析器无法证明为只读的 Bash 命令，不再回退到对话框，而是交由分类器判断。¹⁹⁵

隔离逃逸规则（v2.1.257）。 分类器的禁止自动批准列表新增“隔离逃逸”规则：获取云元数据凭据、规避网络出站限制和跨租户访问等操作，除非环境将其标记为预期行为，否则不再自动批准。应结合上文的限制说明理解这项变化：这是分类器的持续加固，又增加了一类有文档记录的拒绝操作，并未改变自动模式的本质。²¹¹

首次读取工作目录外的文件时提示确认（v2.1.257）。 自动模式现在会在会话首次读取工作目录外的文件前询问一次；自 v2.1.284 起，该提示还提供是，但下次再次询问选项。²²⁸ 配套的 permissions.blockReadsOutsideWorkingDirectories 设置会将提示改为拒绝，直接阻止此类读取。²¹¹ v2.1.273 将这两种行为扩展到检查器无法看清的情况：对于无法完整分析的 Bash 命令，会提示确认，而非跳过检查；启用阻止设置后，由仓库设置指定的记忆目录也不再被加载到提示词中，不再用于记忆召回、索引或记忆提取。²¹⁷

图表渲染器 URL 视为上传（v2.1.261）。 将内容嵌入公共图表渲染器 URL 的链接，例如把数据编码到 URL 本身的 mermaid.live 式链接，现在只有在您明确要求时才会自动批准。分类器将这类链接视为上传：嵌入的数据随 URL 传递，页面打开后，渲染器网站自身的脚本便可读取这些数据。mermaid.live 式链接将载荷放在 URL 片段中，浏览器会将其交给页面的 JavaScript，而非随网络请求发送。仍应结合上文的限制说明理解：这是分类器加固过程中封堵的又一条数据外泄通道，并非新增安全边界。²¹⁴

为分类器的两种失败情形设置停止条件（v2.1.280）。 在此版本之前，自动模式无法处理安全检查未返回可用结论的情况。从操作者的角度看，这两处缺陷表现相同：当前轮次陷入空转，为永远无法获批的操作持续消耗 token。v2.1.280 为两种情况分别设置了终止状态。

服务器审查覆盖更多命令（v2.1.281）。 当分类器审查在服务器端运行时，只读命令和在沙箱中运行的 shell 命令现在也需等待审查；若审查判定存在问题，这些命令便会被阻止。拒绝消息也有所调整，让 Claude 将拒绝理解为针对操作结果，而不仅限于那条具体命令。在新进程中恢复会话后，分类器可以复用之前的提示词缓存，无需重新写入。此外，/insights 新增自动模式建议，可估算自动模式原本能够处理近期会话中的多少次权限提示。²²⁴

无人值守会话不再一直等待 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 变量后接顶层目录名、由工作目录派生的变量，或仅由反斜杠组成的目标。²²⁴ 自 v2.1.299 起，不运行 rm 的 shell -c 脚本不再触发提示；对于在 Claude Code 无法读取的脚本中于运行时构造的 rm，仅当设置了 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 时才会提示。²⁷¹

内联 ! shell 命令不再交由分类器审查；subagents 的结果交回则纳入审查（v2.1.271）。 这是两项机制调整，并未新增拒绝类别。skills 或斜杠命令中的内联 ! shell 命令现在遵循默认模式的权限规则，而非交由分类器处理；若没有规则能够裁定该命令，则将其作为需经审查的工具调用运行。此外，subagents 现在通过专门的结果交回调用向调用方报告，由安全分类器审查该调用，而不再事后审查其最后一条消息。检查点从交接之后移到了交接当时。²¹⁶

v2.1.309 和 v2.1.310 的新增内容

Claude Code 2.1.309 于 2026年10月22日发布（npm 发布时间为 UTC 20:34；GitHub 发布时间为 UTC 22:18，共 79 条），2.1.310 于 10月23日发布（npm 发布时间为 UTC 21:20；GitHub 发布时间为 UTC 23:39，共 26 条），两者均与权威 CHANGELOG 完全一致。npm 的 latest 和 next 均为 2.1.310，stable 则从 2.1.292 升至 2.1.308；后者的发行说明全文只有“错误修复与可靠性改进”一句。2.1.303（10月18日）的说明也是同一句话。2.1.302 至 2.1.310 之间没有遗漏任何版本。²⁷⁸

沙箱和权限修复（v2.1.309）。 macOS 和 Linux 上的沙箱化 Bash 命令不再于每次执行前在沙箱外运行 shell 启动文件；在 macOS 上，如果通过符号链接访问 denyWrite 通配模式中的文件夹，该模式会应用于路径的真实位置；沙箱化命令和自动接受的编辑不再能修改通过 --mcp-config 传入的 MCP 配置文件；Linux 上的写入拒绝限制不再因后台命令在会话结束后继续运行而解除；对于设置中排除在沙箱之外的命令，如果沙箱已启用却无法运行，现在向沙箱写入允许列表中的路径写入前会先询问，并拒绝在此情况下回退为无沙箱运行。Bash 权限检查不再信任由重定向可能失败的命令所设置的变量；在 git 之前执行经过封装或带前缀的 cd 时会提示确认；子 shell 内的 Bash 重定向也会受到 Edit(path) 拒绝规则约束。worktree 隔离防护会拒绝更多带区域设置前缀的命令和 zsh 算术命令；配置档案存储的写保护对通过符号链接访问的配置目录同样生效。sed -i 现在会显示标准 Bash 提示，并按原命令执行，不再模拟为文件编辑预览；与其他 Bash 编辑一样，其改动也不再能通过 /rewind 还原。请参阅沙箱模式。²⁷⁸ 信任、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替换引用。嵌套的CLAUDE.md超过大小限制时，现在只加载开头部分，避免会话在读取其目录下的文件后反复压缩。若--add-dir文件夹中的某个skill与其他skill同名，会以<folder>:<name>的名称提供；/verify和/code-review也能找到嵌套软件包自身的skill。分屏窗格中的智能体队友会继承主智能体的工具拒绝规则和--tools规则；对于通过/code-review --fix、subagent或shell命令修改了检查点所跟踪文件的轮次，/rewind现在也会将其列出。²⁷⁸

v2.1.310。 Monitor工具和plugin监视器现已支持Bedrock、Vertex和Foundry，也能在禁用遥测或非必要流量时工作；这些环境现在也会阻止长时间的前台休眠。如果网关或兼容服务器拒绝effort-2025-11-24测试版值或对话中途的系统消息，请求会移除这些内容后重试。出现“提示词过长”错误后，压缩操作不再保留过多base64或SVG等高密度文本；当cleanupPeriodDays非常大时，后台清理不再删除近期文件，例如粘贴的图片；文件读取提示会显示符号链接的目标位置；自动模式在首次读取工作目录之外的内容前，会在提示中说明哪些情况下阻止此类读取会导致shell命令请求权限；非交互式会话压缩超大对话记录时占用的内存更少；在Ubuntu上，/sandbox和启动警告会指出AppArmor对用户命名空间的限制，并说明解除方法；mod的Image可在开启allow-passthrough和focus-events的tmux中绘制，也可在启用全屏渲染的kitty、Ghostty和iTerm2 3.5+中绘制；非交互式会话中的MCP工具调用若在服务器的信息征询尚未得到回应时超时，会告知Claude不要重复调用。Enterprise自定义角色新增云会话和Remote Control权限。²⁷⁸

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时，即使缺少该会话的环境变量，也不再报告“未登录”；在包含大量MCP工具的会话中，API错误不再被替换为“提示词过长”，也不会引发不必要的压缩。2.1.308（10月22日04:19 UTC）的发布说明仅有一条可靠性改进，该版本随后成为stable版本。²⁷⁸

遥测与API skill。 每当工具调用被权限规则、自动模式、安全检查、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智能体的设置与Anthropic发布的安全指南进行对照，不作任何修改。该skill现在基于multiagent_20261001构建Managed Agents subagent团队，并默认启用动态工作流（v2.1.309）。²⁷⁸[^287]

修复与行为变化。 将CLAUDE_CODE_DISABLE_1M_CONTEXT与带有[1m]后缀的别名（例如opus[1m]）一起使用时，不再出现找不到模型的错误；通过自定义ANTHROPIC_BASE_URL网关或在Foundry上运行时，不再发送prompt-caching-scope测试版请求头；因macOS登录钥匙串锁定而无法连接的MCP服务器现在会说明原因，解锁后再次运行即可连接，无需重新登录；HTTP MCP工具调用不再因连接在调用中途关闭而发送两次，现在仅重试只读或幂等工具；修复了读取大量PDF页面或图片的轮次中出现的“自动压缩反复触发”错误；无法解析的工具调用最多会重试两次，之后才以错误结束该轮次；同时启动的fork subagents会分别获知哪次启动对应自身；/permissions > 最近被拒绝的操作会显示被拒绝的shell命令；axScreenReader设置及设置中env块内的CLAUDE_AX_SCREEN_READER，仅在来自用户设置、托管设置或--settings指定的设置时生效（自2.1.305起）；自托管运行器的检出hooks默认会在30分钟后停止（使用--checkout-hook-timeout-min配置，0表示不设限制）。Code Review新增@claude review stop（也支持off和pause），用于结束@claude review always订阅。²⁷⁸

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日）的发布说明仅有一条可靠性改进。²⁷⁸

自动模式设置与/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条目。²⁷⁸[^287]

设置与环境。 sandbox.allowNestedUserNamespaces（v2.1.305）允许Linux上的沙箱命令创建用户命名空间（用于Chromium、无根模式的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会禁用工具搜索后重试。在allowManagedPermissionRulesOnly下，Claude Desktop按路径挂载的plugins不再保留其allowed-tools。截至10月23日，除工具搜索默认开启这一项外，上述变化均已写入文档。²⁷⁸[^287]

Mods、skills与hooks。 mod的tool.check事件携带e.isReadOnly，其响应可设置decider: "person"，使批准只能通过权限对话框或宿主回调完成；settings.read hooks会接收各层设置，并重写合并后的设置；对话记录会用一行内容指出哪个plugin跳过了您的某个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不再在退出时未经询问就删除worktree及其分支；对已挂载驱动器或其顶层文件夹执行rm -r会触发安全提示；Code Review新增审查级别（快速、标准、深入），并提供审查GitHub组织中所有仓库的选项。在Opus 5.5上，/fast对话框移除了“（研究预览）”标签。²⁷⁸

v2.1.302的新变化

Claude Code 2.1.302于2026年10月16日发布：npm于UTC时间16:48发布该版本，GitHub版本随后于UTC时间20:53发布，包含与权威CHANGELOG相同的63条更新。npm的latest和next均指向此版本，stable仍停留在2.1.292。它紧接2.1.301（10月15日，51条更新），中间没有跳过任何版本。10月17日获取的文档已包含2.1.301中的vim移动命令和VS Code数学公式渲染功能，但尚未收录以下任何更新，因此各项均以CHANGELOG为依据。²⁷⁵²⁷⁶

claude -p和SDK重新默认以手动模式启动。 未指定权限模式的claude -p或Agent SDK会话，在使用第三方提供商、关闭遥测或全新安装的情况下，现在均以default（手动）模式启动；指定--permission-mode auto仍会使用自动模式。这撤销了v2.1.285中此类会话默认以自动模式启动的规则。交互式终端和VS Code会话保持原有行为：所有套餐和提供商均使用自动模式。权限模式文档仍描述v2.1.285的行为。请参阅权限模式。²⁷⁵²⁷⁶

Fork subagents与后台运行的默认行为。 claude -p、Agent SDK、桌面应用和VS Code现已默认启用Fork subagents（subagent_type: "fork"），与终端此前的行为一致；设置CLAUDE_CODE_FORK_SUBAGENT=0可将其关闭，claude mcp serve则始终不提供此功能。桌面应用和VS Code现在与终端一样，始终在后台运行主对话的subagents，不再由Claude决定；而在claude -p、SDK、桌面应用和VS Code中，subagent自身发起的Agent调用默认在前台运行。提示词hooks和agent hooks现在针对同一事件最多并发运行12个，其余排队等待。环境变量和subagents文档仍称fork模式仅在交互式会话中启用。请参阅什么是subagents？。²⁷⁵²⁷⁶

自动模式与上下文压缩。 CLAUDE_CODE_AUTO_MODE_MODEL用于选择客户端自动模式分类器使用的模型，不会更改服务器端自动模式的模型。使用服务器端分类器时，如果对话过长，无法完成安全检查，现在会压缩对话，而不再拒绝每一次接受检查的工具调用。/config新增空闲压缩选项，可关闭或重新开启空闲压缩；空闲压缩完成后的提示也会说明如何关闭此功能。已修复在压缩过程中中止轮次时出现的“提示词过长”错误。当网关为Opus 4或4.1添加前缀，例如anthropic/claude-opus-4-1时，/autocompact和/effort现在会将设置保存到正确的模型。²⁷⁵

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条目。²⁷⁵

值得关注的修复。 Read工具不再将任意大小的图像，或名称类似图像的管道、设备，全部载入内存：现在会拒绝超过128 MB的图像源。会话中途添加的工具，通过ToolSearch或在压缩后重新加载时，不再导致提示词缓存未命中。claude plugin及其他子命令会等待队列中的设置或配置写入完成后再退出，因此更改不再丢失，也不会残留为.tmp文件。当git默认使用reftable引用格式时，plugins市场不再每次刷新都重新克隆，git plugins也不再将版本显示为“unknown”；在git 2.56或更高版本中，即使残留的.git文件指向不存在的目录，工作树隔离也能正常工作。协商使用2026-07-28协议版本、但未提供resultType、ttlMs或cacheScope的MCP服务器，现在也会显示其工具。回复通过用量额度计费后，将跳过提示词建议。会话中途切换至Vertex或Bedrock后，请求不再因“diagnostics: Extra inputs are not permitted”而失败。安装大量plugins时的启动速度有所提升，Windows上的改善尤为明显；在Windows上，也不再拒绝向exFAT或FAT32驱动器写入文件。²⁷⁵

云端会话与Claude Tag。 例行任务页面会显示横幅，说明上次运行未能启动的原因，例如触及组织的云端会话并发上限；“回退到此处”适用于每条消息（自托管运行器需要v2.1.246或更高版本）；中途失败的运行不再于1小时后从头重复执行；云端会话在新进程中恢复后，费用和用量也不再从零开始累计。Claude Tag管理设置重新划分为“捆绑包”“连接器”“skills与plugins”和“频道”选项卡；Slack中附加的HEIC、SVG、TIFF和BMP图像现在会以文件形式传递给Claude；对于按角色限制使用权限的组织，管理员角色现在也会获准在Slack中使用Claude Tag。²⁷⁵

v2.1.301的新功能

Claude Code 2.1.301于2026年10月15日发布（npm发布时间为UTC时间14:34；UTC时间19:22发布的GitHub版本包含与权威CHANGELOG相同的51条更新）。npm的latest于次日更新为2.1.302，因此这里将两个版本一并介绍。²⁷⁵

无人值守重试新增用量上限等待时限。 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS可让无人值守重试模式（CLAUDE_CODE_RETRY_WATCHDOG）在触及用量上限且距重置时间过久时终止请求，不再持续等待；环境变量参考将其与CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS并列介绍。运维人员还需关注以下变化：切换到上下文窗口较小的模型时，如果对话超出新模型的容量，现在会由原模型生成摘要，不再未经询问就消耗用量额度生成摘要；当组织无法使用最新Fable模型时，fable和best别名会使用上一版Fable模型重试1次；通过LLM网关进行对话时，如果响应中的模型名称与请求的模型不同，也不再反复触发压缩。²⁷⁵

遥测、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模式。²⁷⁵²⁷⁶

值得关注的修复。 退出时，如果WorktreeCreate hook创建的工作树可能包含尚未推送的提交，系统不再未经询问就将其移除。搜索程序失败时，Grep和Glob会报告错误，不再显示“无匹配结果”。参数名称过多或过长的skills和命令不再卡顿数秒：现在只补全前64个名称，每个名称最多64个字符。Read工具不再将.xlsm、.parquet、.epub和.heic等二进制文件作为文本读取。执行/rewind后，会再次向模型列出skills。在工具调用的权限检查期间，如果轮次中途发送的消息打断了该调用，系统不再向模型报告该调用被您拒绝。在vim模式中按Esc不再丢弃已输入的AskUserQuestion回答：自由文本输入框支持NORMAL模式，只有在该模式下按Esc才会取消。磁盘已满时，现在会报错并指出具体磁盘，不再显示具有误导性的“请运行/login”。当托管设置限制MCP服务器时，从Slack启动的自托管运行器仍可附加仓库（可使用deniedMcpServers禁用这些工具）。VS Code可渲染回复中的LaTeX数学公式，包括$$和\[ ... \]块，并在Pro和Max的用量上限横幅中显示“获取更多用量”链接。²⁷⁵

v2.1.300的新功能

Claude Code 2.1.300于2026年10月14日发布，距2.1.299发布仅数小时：npm于UTC时间14:27以next标签发布该版本，GitHub版本随后于UTC时间18:24发布，包含与权威CHANGELOG相同的88条更新。到当晚，npm的latest和next均已指向2.1.300，stable则从2.1.287更新为2.1.292。中间没有跳过任何版本。²⁷³ 顾问工具现已支持AWS上的Claude Platform。 /advisor现已可在AWS上的Claude Platform中使用；只有通过/advisor、advisorModel或--advisor选定顾问后，顾问才会运行，设置CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1可关闭此工具。截至10月14日，顾问文档页面仍将AWS上的Claude Platform列为不支持的提供商。该工具允许Claude在需要决策时咨询另一个模型，早于本次版本发布便已推出，详见顾问工具。²⁷³²⁷⁴

Mods与遥测。 Mods新增virtualText提示框装饰（显示在提示框中，但绝不会进入草稿的文本）、用于在主视图中显示智能体对话记录的$.ui.view({ agentId })（$.ui.view({})可返回）、用于从右向左排列的行的Text属性dir，以及用于监听提示框中非键入编辑所引起变化的prompt.change hook（例如调出历史记录、清空、撤销或由plugin填入内容）；agent.spawn现在可以改写工作流智能体的prompt和model，此前只能拒绝启动该智能体。Mods参考文档将next.error.cause中的rewritten原因标注为自v2.1.300起提供。OpenTelemetry的api_request事件将缓存写入拆分为cache_creation_5m_tokens和cache_creation_1h_tokens，跟踪跨度包含gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name和error.type等GenAI语义约定属性。被mod的prompt.submit hook改写或丢弃的提示词，不再作为用户键入的内容记录在user_prompt事件中。本地对话记录现在还会保存每个API请求的系统提示词、工具和参数，因此分享的对话记录可以精确复现请求（请参阅Mods和遥测）。²⁷³²⁷⁴

运行与行为变更。 发往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和git配置变量，例如SSL_CERT_FILE。在Cowork云端会话中，PermissionRequest hook的setMode会被忽略，其余批准内容仍然生效。当forceLoginGatewayUrl指定由Anthropic运营、且为会话主机名提供服务的网关时，Claude Desktop的Code选项卡会应用托管设置；claude gateway在启动时遇到无法使用的desktop:策略键则会停止。/sandbox选项的文字改为“对命令启用沙箱”。VS Code新增claudeCode.attachSelection，可避免将编辑器中选中的内容附加到消息中。在Slack中，管理员允许后，Claude Tag可以在Slack Connect频道中回复。²⁷³

值得关注的修复。 在后台命令仍在运行时退出，SessionEnd hooks也会执行；ENABLE_TOOL_SEARCH=auto不再于对话中途关闭；被forceLoginOrgUUID拒绝的登录不再留下该组织的已存储令牌；无界面会话和SDK会话在压缩后恢复时，会保留压缩过程中留下的消息及摘要；当API拒绝MCP工具的输入模式时，对话不再每轮都因400错误而失败（改为发送不带参数的工具）；智能体hooks会遵循其model设置；当标签或分支的名称与提交ID相似时，--worktree会话会从正确的提交启动，并且可以在reftable仓库中重新打开；claude daemon stop --any会等待服务停止，强制终止卡住的服务，若服务仍然存在则以退出码1退出；Cowork云端会话中的Write和Edit不再针对您本机上的路径报告成功；无法读取组织策略时，云端会话不再每轮都卡住5分钟；自托管运行器也不再因无人读取其输出而冻结。²⁷³

v2.1.299的新变化

Claude Code 2.1.299于2026年10月14日发布（npm发布时间为UTC 00:23；UTC 02:49发布的GitHub版本包含与权威CHANGELOG相同的190条更新）。2.1.297和2.1.298从未发布，因此这里没有遗漏版本。npm的latest一直指向2.1.299，直到当天稍晚2.1.300被设为最新版本（请参阅v2.1.300的新变化）。²⁷¹²⁷³ 建议从2.1.296升级：本版本修复了该版本引入的两项回归问题。一是在Cowork和claude.ai云端会话中，若消息在其UserPromptSubmit或mod的prompt.submit hooks运行期间被停止，Edit和Retry会失败；二是云端或无界面会话在重启后恢复时，若恰好收到新消息，可能将已批准的工具调用执行两次。

空闲压缩（v2.1.299）。 终端对话达到200K或更多token，并空闲约54分钟后，现在会在1小时提示词缓存到期前进行压缩，避免下一条消息重新处理整个上下文。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；此变量不能通过项目设置或本地设置配置（请参阅环境变量参考）。²⁷¹²⁷² v2.1.302在/config中新增了空闲压缩一行，用于关闭或重新开启此功能，空闲压缩后的通知也会说明操作方法。²⁷⁵

权限与MCP。 mcp__a这样的允许规则现在仅匹配名为a的服务器，不再匹配a__b或a_；请使用服务器规范化后的完整名称编写mcp__<server>__*。名称中含有__的服务器也应以同样方式列入智能体的tools:列表，该条目现在仅会引入对应服务器的工具。针对规范化名称中包含双下划线的服务器，拒绝规则和询问规则重新生效。来自Anthropic在api.anthropic.com提供的第一方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时才会提示确认。²⁷¹

Hooks与mods。 UserPromptSubmit hooks会在skill或自定义斜杠命令展开前运行，因此阻止提示词的hook也会阻止其中嵌入的shell命令。Skill自身前置元数据中的UserPromptSubmit hook则会从调用该skill之后的下一条提示词开始运行。如果无法将操作传递给plugin hook，或无法接收其返回结果，现在会拒绝该操作，不再放行；若工具已执行，则会暂扣其结果。对于mods，turn.start hook现在也会接收subagents和团队成员的轮次事件（通过e.agentId区分），skill.prompt会收到skill的前置元数据、来源、plugin名称和文件路径（mods参考文档将这些标注为自v2.1.299起提供）；$.prompt.media允许托管设置中的mod通过其prompt.submit hook读取附加的图片或文档；$.session.identity()会报告会话的登录方式；Text支持size、weight、mono和tabular，Box支持具名间距档位（bold已弃用，改用weight）；session.append新增queue入口；恢复subagent或团队成员时会触发agent.spawn，并设置resume。被远程关闭的mods会在轮次之间卸载；当组织对Claude Code实施管理时，/plugin和claude plugin validate会列出被跳过的hooks名称（请参阅Mods）。²⁷¹²⁷² 命令、界面与操作。 /usage 会针对最高推理强度、工作流、常驻上下文和大型工具结果发出提醒。在代理视图中，/effort 和 /fast 用于设置新会话的初始配置；不带参数的 /model、/effort 或 /fast 会打开选择器；速览面板会为使用 --safe-mode 启动的会话显示安全模式提示行。计划模式可使用绕过权限检查功能，因此在大多数编辑前不会询问时，会显示一次性提示。claude plugin eval 支持 --disallow-tools 和测试用例字段 disallowed_tools；如果运行因 API 错误结束，则得分为 0，且测试套件判定为失败。claude self-hosted-runner orchestrator --shutdown-drain-sec 为正在进行的轮询和启动 hooks 留出时间，以便在收到 SIGTERM 时完成。如果通过 Claude apps 网关访问，在 code 或 cli 策略的 env 中设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 可移除归属信息块。在 Cowork 云会话中，PermissionRequest hook 不再能在自动模式下批准 shell 命令或 subagents；对于已批准站点上的 Claude in Chrome 操作，若安全分类器将其标记为有风险，系统会向您询问，而非直接拒绝。退出时显示的恢复命令使用会话 ID 来指定会话；非交互式会话中的 /btw 会在 11 分钟后超时；本地会话可监视的已发布制品数量从 10 个增至 25 个；网络安全防护通知也不再要求您申请加入 Cyber Verification Program。²⁷¹

值得关注的修复。 通过自定义 ANTHROPIC_BASE_URL 建立的流式连接现在会等待数据 300 秒，而非在 180 秒时中止；发往 Anthropic 的功能标志、启动、快速模式、配置档案和服务器托管设置请求不再携带第三方网关的 API 密钥；/usage 和状态行不再显示超过 100% 的使用率；夏令时结束后，在重复出现的那一小时内，定时任务和循环不再每轮结束后都重复触发；使用 --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 的情况时，会阻止调用，而非在失败后放行。²⁷¹

v2.1.293-v2.1.296 新增功能

2026年10月7日至10月9日共发布了 4 个版本。npm 的 latest 和 next 均为 2.1.296；stable 从 2.1.285 更新至 2.1.287。²³⁸ 此次更新的重点是新模型：Claude Haiku 5.5 在 v2.1.293 中推出，成为 Anthropic API 上 haiku 所选择的模型（请参阅可用模型）。如果您通过托管设置登录 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.20 美元更正为 0.10 美元。预先发送的 MCP 工具描述和 MCP 服务器指令，其默认长度上限从 2,048 个字符提高至 4,096 个字符。Subagent 的 frontmatter 和 --agents 定义支持 autoCompactWindow，使 subagent 能比主对话更早进行自动压缩。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 可让所有工作流代理使用同一个模型，其他 subagents 则保留各自的模型；CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 可为 529 错误退避设置更长的最大延迟。Read 工具支持 allow_large，使 Claude 能在上下文空间充足时，通过一次调用读取超过常规大小限制的文本文件。托管设置中的 PreToolUse hooks 若以 "continue": false 拒绝工具调用，以及托管的 prompt hooks 若阻止工具调用，现在都会在拒绝调用的同时结束当前轮次。--debug 会指出自定义代理文件中无法识别的 frontmatter 字段，并记录每个命令 hook 的命令、plugin、结果和耗时。Claude apps 网关在 managed.policies[] 下新增 code 键，其设置与 cli 相同，也适用于 Claude Desktop 的 Code 选项卡。在按 ← 将会话转入后台的过程中启动的轮次或 ! 命令，现在会被停止，不再在不可见的状态下继续执行。文档随后也补充了其中两项：hooks 参考文档注明，每个 hook 对应的 --debug 日志行始于 v2.1.296；Claude apps 网关文档介绍了 code 策略键。截至10月14日，sub-agents 和 env-vars 文档也已收录 autoCompactWindow 和 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS；截至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 参数，系统会移除该参数后重新发送请求，而非直接失败。在已连接的后台会话的空闲提示符处按 Ctrl+C，不会影响待触发的 /loop 唤醒，因此连按两次会断开连接，而循环继续运行；按 Esc 则会停止循环。未获取任何功能标志的安装默认使用 MCP 协议 2026-07-28 与 claude.ai 连接器协商。/copy 提供引用文本选项；claude -p 会在最后一轮结束后，通过 stderr 说明正在等待什么；mods 新增 $.ui.notify。在 xhigh 和 max 推理强度下，网页搜索和 agent hook 评估不再耗时明显增加。²³⁸²⁴⁰

v2.1.294（10月8日）。 针对以指令形式编写的 prompt 和 agent hooks，修复了两项问题：类似“阻止满足以下条件的命令……”的 hook 不再放行本应阻止的操作；对于类似“如果构建失败，则继续执行”的 Stop 和 SubagentStop hooks，评估逻辑已调整，以降低 Claude 提前停止的可能性。²³⁸

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 秒后重试。²³⁸²⁴⁰

v2.1.288-v2.1.292 新增功能

2026年10月2日至10月6日共发布了 5 个版本。npm 的 latest 和 next 均为 2.1.292；stable 仍为 2.1.285。²³⁴ 如果您使用的是 2.1.288、2.1.289 或 2.1.290，建议升级：v2.1.291 修复了 2.1.288 引入的回归问题，即退出时可能丢失会话末尾的消息；同时修复了 2.1.290 引入的回归问题，即云会话可能丢失对权限提示的回答。²³⁵ v2.1.292（10月6日）。 设置CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS可延长过载（529）请求重试时的退避基础延迟；环境变量文档现已注明默认值为500毫秒，允许范围为500至32000。Agent工具接受effort参数，因此Claude可以按您指定的推理强度运行subagent；subagents文档现已说明这一按次调用的参数，它会覆盖frontmatter字段，并在恢复subagent时继续生效，而CLAUDE_CODE_EFFORT_LEVEL的优先级高于两者。claude plugin install --marketplace <source>可通过一条shell命令添加市场并从中安装。本地（stdio）MCP服务器现在在所有安装环境中均默认协商使用2026-07-28版协议，包括Bedrock、Vertex和Foundry；可通过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构建Console快速入门模板，例如deep-researcher。多项默认限制有所收紧：项目设置不再能启用Chrome中的Claude；仓库的.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设置。²³⁵²³⁷

v2.1.290，团队与网关。 Claude应用网关的登录批准页面新增“拒绝”按钮，支持的最低PostgreSQL版本从14降至11。在自托管运行器上，claude --environment <id>通过当前的Sessions API创建会话。如果某个文件夹替换了同名的已跟踪文件，而暂存内容会删除该文件夹中的文件，claude --teleport和/teleport会拒绝应用该暂存内容；--channels中继会忽略重复的回复ID，避免误批准其他提示。在Slack中，!fast将线程切换到快速模式，!fast off则切换回来。VS Code默认显示消息时间戳（可通过Claude Code：显示消息时间戳设置关闭）。²³⁵

v2.1.289（10月3日）。 Mods新增用于团队成员的agent.spawn，在各类plugin hook事件中使用统一的代理ID，并在$.agent.list()中提供空闲和等待状态；claude plugin validate不再跳过文件夹中同时包含市场清单的plugin；沙盒自动允许机制下的两个Bash拒绝规则漏洞已修复。²³⁵²³⁷

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），避免一直挂起。在自动模式下，如果对话长度超出客户端分类器的处理范围，系统会压缩对话，而不是对每次工具调用都弹出提示；客户端分类器会忽略通过ANTHROPIC_DEFAULT_SONNET_MODEL固定指定的Claude Sonnet 5.5或Opus 5.5，改用Claude Sonnet 5。Mods新增$.ui.selection()；未配备GitHub CLI的云端会话新增内置gh api；在空白输入框中按向上键，可恢复被Ctrl+C清除的草稿。²³⁴²³⁷

v2.1.105–v2.1.114中的新增命令¹⁴⁶¹⁵⁰

会话回顾（v2.1.108+）

这项新增的会话级功能会在您返回已暂停的会话时呈现上下文。默认启用，可通过/config或CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0关闭。模型还可通过Skill工具调用内置斜杠命令（/init、/review、/security-review），进一步扩展了subagent/skill模式。¹⁴⁶

推送通知（v2.1.110+）

当Remote Control启用“由Claude决定何时推送”选项时，Claude现在可自行判断，并通过新增的推送通知工具发送移动端推送通知。此功能与现有的Remote Control移动端/网页端配合使用。¹⁴⁶ /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上，同一变量用于在逐步推出期间控制启用或禁用。¹⁴⁶

权限模式自动批准（v2.1.119+）。 PowerShell工具命令现在可像Bash命令一样，在权限模式下获得自动批准。PowerShell(Get-*:*)等允许规则和现有模式语法现在可让只读操作跳过确认提示，使其操作体验与团队在Linux/macOS上已有的体验保持一致。¹⁵²

减少权限确认：只读Bash（v2.1.111+）

带有通配符参数的只读 Bash 命令模式（例如 ls *.ts、cat src/*.md）以及以 cd <project-dir> && 开头的命令不再触发权限提示。¹⁴⁶配合 /less-permission-prompts 使用，日常工作流程中的中断将显著减少。

分布式追踪（v2.1.110+）

SDK 和无界面会话现在会从环境变量中读取 TRACEPARENT 和 TRACESTATE，将 Claude Code 的运行接入分布式追踪。配合 OTEL_LOG_RAW_API_BODIES=1（v2.1.111+），可将完整的 API 请求和响应正文作为 OpenTelemetry 日志事件输出，便于调试。¹⁴⁶

原生二进制分发（v2.1.113+）¹⁵⁰

v2.1.113 更改了 CLI 的启动方式：claude 现在通过针对各平台的可选依赖项启动原生 Claude Code 二进制程序，不再运行捆绑的 JavaScript。安装和更新命令保持不变，团队无需修改部署脚本。

提示词编辑器快捷键（v2.1.113+）¹⁵⁰

提示词编辑器新增了适用于多行输入的 readline 风格导航，以及全屏视口滚动功能：

subagents 停滞超时（v2.1.113+）¹⁵⁰

subagents 在流式传输过程中停滞时，现在会在 10 分钟后终止并报告明确的错误，不再无提示地挂起。配合 CLAUDE_STREAM_IDLE_TIMEOUT_MS（v2.1.84+），可更全面地处理流式 API 调用中的进程卡死问题。

v2.1.114 稳定性修复¹⁵⁰

v2.1.114（2026年4月18日）仅包含一项修复：agent-teams 中的队友请求工具权限时，权限对话框可能崩溃。如果您使用 Agent Teams，建议升级。

内容标记：文本水印与 C2PA 文件元数据（2026年8月）

为响应《欧盟人工智能法案》第 50 条（自2026年8月2日起对新推出的 AI 系统生效），Anthropic 宣布为 Claude 生成的内容添加机器可读标记。该系统包含两个组成部分：生成文本中的不可见统计水印，以及按照 C2PA 开放标准附加到 .svg、.png、.jpg 等生成文件上的签名来源元数据。²⁵²²⁰⁴新闻标题容易模糊一个细节：这两个组成部分遵循相同的模型适用时间表。支持页面指出，“在2026年8月2日或之后推出的 Claude 模型将在发布时支持机器可读标记”。在该日期之前推出的模型，也就是当时的全部现有模型（Fable 5、Opus 5、Sonnet 5、Haiku 4.5），适用欧盟法律的过渡期；Anthropic 表示“也在努力为这些模型添加标记支持”。²⁰⁴

这份名单反映的是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 的模型页面和新功能页面，均未提及标记。^2412222308月之前发布的模型，其输出无论是文本还是文件，都不带标记；较新模型的输出则会带有标记，覆盖所有使用渠道——Claude Platform（API）、claude.ai、Claude Code、Claude Cowork、Claude Tag 以及云网关——因为标记是在模型层面实现的。由此可以得出一个值得明确说明的结论，因为某个广泛传播的帖子恰好说反了：如果您察觉到某个8月之前发布的模型出现了风格或行为变化，那不可能是水印造成的，因为这些模型尚未启用标记。

工作原理：采用 Google DeepMind 的 SynthID-Text 的一种变体。当 Claude 在语义等价的选项之间进行选择时，水印会改变“用于选择词语的随机性来源”。它不添加字符，也不进行后处理。据 Anthropic 的内部测试，“水印对内容、创造力水平或可读性均无影响”。²⁵²

Claude Code 用户会关心的是：代码带有稀疏水印。可正常运行的代码留给任意选择的空间很小，因此标记主要集中在有选择余地的地方，例如注释和命名。Anthropic 称其“对实际生成代码的影响可以忽略不计”。²⁵²标记能否保留具有概率性，而且因组成部分而异：对于文本，轻度编辑“可能不会完全去除水印”，彻底重写则会去除水印，而由 Claude 生成的译文会带有新的独立标记；对于文件元数据，格式转换、重新保存和截图都可能移除 C2PA 签名。²⁰⁴检测 API 已列入计划。检测结果为阳性，只能证明“Claude 很可能曾在某个环节参与处理该内容”，并且明确无法区分“这是 Claude 写的”和“这是 Claude 大幅编辑过的”。支持页面还指出，没有标记同样不能证明任何事情。目前未提及任何客户级别可以选择退出。²⁵²²⁰⁴

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+）。¹³⁷

使用合约费率而非标价（modelPricing，托管设置，v2.1.243+）：已协商各模型费率或折扣系数的组织，可以通过托管设置modelPricing进行部署。此后，/cost、状态栏和遥测成本数据将使用这些费率，而非标价，使开发者看到的数字与组织实际支付的费用一致。²⁵⁰ 自v2.1.271起，系数也可以高于1，最高为10，适用于向内部团队收取加价费率的组织。²¹⁶

单会话提示缓存行（v2.1.251+）：/cost会为当前会话增加一行提示缓存统计信息，包括命中率、未命中次数、重新缓存的 token 数，以及缓存处于热态还是冷态；状态栏脚本中也会提供对应的prompt_cache对象。该对象会在主对话首次收到API响应后出现，不统计subagents请求，并根据API响应中的缓存 token 数计算，因此适用于所有提供商。/usage的Prompt cache (main)行会显示相同统计信息。²⁰⁶²⁰⁹ 自v2.1.260起，/cost行和状态栏的prompt_cache对象还会指出缓存未命中的可能原因，例如工具定义或系统提示发生变化，或者会话闲置时间超过缓存 TTL。²¹²

智能体流量不再破坏自身的缓存前缀（v2.1.265）：两项修复堵住了委派工作中的提示缓存漏洞。恢复以前台方式生成的subagent时，不再改变其工具列表和系统提示前缀；智能体队友和恢复的subagents在后续轮次中，也不再将SubagentStart hook上下文及预加载的skills移出提示前缀。这两个缺陷都会破坏提示缓存复用：一旦前缀改变，其后的所有内容都会作为未缓存输入重新发送。而这恰恰发生在缓存经济效益最重要的长时间智能体会话中（与v2.1.260针对Fable 5.1工具调用轮次修复的问题属于同一种故障模式）。²¹⁵

v2.1.267缓存稳定性批量修复：一次发布包含约10项修复，针对的都是同一种故障模式：某些内容在对话过程中改写了提示前缀，导致其后的所有内容均作为未缓存输入重新发送。恢复的会话不再改写工具列表、重新渲染工具描述，也不会在连接器重新连接之前改写先前的MCP工具公告；使用/model切换模型时，不再重新发送每项工具定义（提交和 PR 归属文本现以对话备注的形式加入，并在模型变化时更新）；通过--system-prompt或--append-system-prompt启动的subagents和会话，只记录一次系统提示与工具定义；会话进行期间出现的MCP和plugin工具，会以延迟定义的形式进入不含ToolSearch的会话，而不会改写工具列表。这批修复将v2.1.260和v2.1.265的改进延伸到了会话恢复、模型切换及MCP重新连接场景。²¹⁶

v2.1.273继续保持上下文连贯：/login、/upgrade和/extra-usage此前会丢弃对话中较早的思考内容，迫使下一个请求完全重写提示缓存。²¹⁷

v2.1.277又堵住了3处前缀泄漏：当SessionStart hook输出内容时，通过/clear后继续的会话（重启、--continue、--resume）会丢失首条消息的一部分，从而导致提示缓存完全未命中；恢复的subagents和队友会重新渲染已经加载的MCP工具定义，破坏该智能体的提示缓存；恢复或重新启动后，对话中先前记录的附件会被重新渲染，造成扩展思考内容丢失和提示缓存未命中。这与v2.1.265至v2.1.267批次属于同一种故障模式：某些内容改写前缀，导致其后的所有内容以未缓存形式重新发送。修复范围现已覆盖SessionStart输出、恢复后智能体的MCP定义，以及已记录的附件。²¹⁹

v2.1.280又增加了2项修复：当Claude正在工作时，从宿主应用（Claude Desktop、VS Code、SDK）切换模型，不再导致下一条提示缓存未命中；恢复的分支subagent会重新发送其最初使用的工具列表，而不是重新构建列表，后者此前会破坏该智能体的提示缓存。²²⁰

v2.1.281又增加了3项修复：在权限提示待处理期间重启并恢复会话时，不再发送与重启前不同的历史记录，后者此前会破坏该位置之后的提示缓存；会话中途断开连接或在恢复后仍处于连接状态的MCP服务器，在工具搜索关闭时（例如位于代理或网关之后）不再损耗缓存；恢复的会话不再以变化后的形式重新发送先前轮次，后者可能导致API丢弃对话中已有的推理内容。²²⁴

订阅方案

速率限制（2025年8月）：Anthropic为付费订阅用户引入了每周速率限制。Max订阅用户达到速率限制后，可以按标准API费率购买额外用量。¹⁴

速率限制翻倍（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）。”¹⁵⁷

自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是两项关键控制手段。²¹³

API Token定价（2026年10月）^1144222239

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

1M上下文定价（2026年4月）：Opus 4.7、Opus 4.6、Sonnet 4.6和Mythos Preview均以标准每MTok费率提供1M上下文，不收取长上下文溢价。¹⁴⁸ 这是近期统一后的定价；关于Opus 4.6或Sonnet 4.6在输入超过200K token 后按2倍输入价格和1.5倍输出价格计费的旧说明，现已不再适用。旧版Opus 4.5及更早模型仍沿用各自原有的定价结构。

数据驻留定价：通过inference_geo指定仅在美国境内进行推理，会使所有 token 价格乘以1.1，包括缓存读取和写入（适用于Opus 4.6及更新模型）。¹⁴⁸

提示缓存可以显著降低重复输入的成本：缓存写入价格为基础价格的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%）。²⁴¹²²² 对于包含重复上下文的RAG系统和代码助手，缓存可将成本降低88%至95%。

批量API为非紧急任务提供50%的折扣，处理时间为24小时，例如夜间测试套件。

多账户政策⁵²

可以拥有多个Claude账户吗？可以，但必须用于正当用途。只要用途各不相同，Anthropic明确允许使用多个账户。

允许的情况：

技术限制： - 同一个电话号码最多可以验证3个账户 - 明确支持从同一IP/网络订阅多个付费账户 - 各账户完全独立；无法在账户之间转移聊天记录或项目

禁止的行为（依据使用政策）： - 被封禁后创建账户以逃避封禁 - 跨账户协同实施恶意活动以逃避检测 - 使用多个账户规避速率限制或免费层级额度

现实案例：2026年1月，资深用户Jeffrey Emanuel（@doodlestein）的22个Max账户被自动标记并暂时封禁。Anthropic员工Thariq（@trq212）在确认其用途正当后，于4小时内解决了该问题。如果您在多个账户中大量使用Claude Code处理工作与个人项目，这正是该服务所支持的使用方式，但请勿试图钻系统空子。

如有疑问：请联系Anthropic支持团队，以书面形式确认您的具体配置是否合规。

成本影响因素

实际成本示例

以上按标价计算（提示不超过100K token 时，Haiku 5.5为$0.10/$0.50；Sonnet 5.5为$2/$10；Opus 5.5为$4/$20，均为每MTok价格），尚未计入提示缓存折扣。

节省成本的要点：使用Haiku执行探索型subagents任务、使用Sonnet进行实现，与所有任务均使用Sonnet相比，通常可以节省40%至50%的成本。

团队成本管理

按团队规模建议的TPM/RPM：

隐性工具费用

除按 token 计费外，部分工具还会产生额外费用：⁹

这些费用在智能体循环中会积少成多。使用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——达到上限后，系统会拒绝生成新的subagents，并停止正在运行的后台智能体（此前后台智能体不受预算约束）¹⁹⁴
5. 使用计划模式进行探索：不执行操作，就不会意外触发高成本操作
6. 主动压缩：上下文越小，消耗的 token 越少
7. 限制输出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 对非紧急工作使用批量API：输入和输出 token 均享受50%折扣
9. 分析项目的Claude API支出：/claude-api cost-optimize（v2.1.247+）会分析现有项目的Claude API支出，并逐项衡量和调整成本杠杆（缓存、token精简、批处理、effort、模型选择）。该命令面向您使用API构建的应用，而非Claude Code会话本身²⁴⁵

监控用量

• Claude Console：platform.claude.com（需要Admin或Billing角色）
• 工作区限制：为每个工作区设置支出上限
• Bedrock/Vertex：使用云平台原生的成本监控功能
• LiteLLM：配合第三方提供商，按用户进行详细追踪

后台Token用量

部分操作会在后台消耗 token： - 为/resume汇总对话 - /cost和/status命令 - 自动压缩

通常每个会话不超过$0.04。

Claude Code分析API（Team/Enterprise）⁴⁶

通过Admin API，以编程方式访问组织的Claude Code用量分析和生产力指标。

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

要求： - Admin API密钥（sk-ant-admin...） - Team或Enterprise方案 - Admin、Billing或Developer角色

可用指标：

请求示例：

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起，默认模型不再跟随您的套餐——除Microsoft Foundry外，每个会话都从Opus 5.5开始。因此，以前的“升级到Opus”策略如今正好相反：当任务不需要复杂推理时，使用/model sonnet降档即可将token价格减半。^{181197207220221} 对于subagents，可降至Haiku。如果降档后的回答显得浅薄，则继续使用Opus。借助agent teams（v2.1.32及更高版本），Opus可以协调多个agent，并行处理不同的子任务。⁷⁹

Command、skill、subagent还是agent team？

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还是prompt？

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

Agent teams、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