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

简而言之：Claude Code 是一款智能体式 CLI，通过由权限、hooks、MCP 集成和 subagents 构成的分层系统读取代码库、执行命令并修改文件。掌握5个核心系统（配置、权限、hooks、MCP 和 subagents），即可事半功倍。为每项任务选择合适的模型层级——Opus 用于复杂推理，Sonnet 用于常规工作，Haiku 用于快速探索；如果质量是唯一考量，也可以统一使用 Opus。凡是必须始终执行的操作，都应使用 hooks，而不是提示词。截至 v2.1.197（2026年6月30日），Claude Sonnet 5 已成为 Claude Code 的默认模型——原生支持 1M 上下文，推广价格为 $2/$10，有效期至8月31日；只需执行一次 /model opus 即可切换到 Opus（自 v2.1.219 起，该别名会使用 Claude Opus 5）；v2.1.198（7月1日）使 subagents 默认在后台运行，推动 Chrome 中的 Claude 正式发布，允许后台 agents 在完成 worktree 代码后提交、推送并创建草稿 PR，并为后台会话触发 Notification hook（agent_needs_input/agent_completed）；v2.1.199（7月2日）可加载最多5个堆叠的 slash-skill 调用，并为订阅用户自动重试暂时性的 429 错误；v2.1.200（7月3日）在 CLI、--help、VS Code 和 JetBrains 中将 default 权限模式重命名为“Manual”（配置值保持不变，同时接受 manual 作为别名），并使 AskUserQuestion 对话框默认不再自动继续；v2.1.202（7月6日）新增“Dynamic workflow size” /config 控件，并让 /review <pr> 恢复为快速的单次审查，同时将多智能体审查移至 /code-review <level> <pr#>；v2.1.203–205（7月7日至9日）增强了 auto mode 的安全性——阻止篡改会话记录文件；针对无法解析变量的 rm -rf 操作先行询问；后台任务通知会明确指出未发生人工输入（因此无法执行会话记录中伪造的批准）——并将 /doctor 升级为完整的诊断与修复检查工具（别名为 /checkup）。^181182183 v2.1.217（7月21日）改变了 nested subagents 的策略——subagents 默认停止生成自己的 subagents（3天后，v2.1.219 又一次推翻了这项默认设置，将深度恢复为3；详见下文）；默认最多并发运行20个 subagents（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS）；达到上限后，--max-budget-usd 现在会真正停止后台 subagents。[^211] v2.1.218（7月22日）将 /code-review 移至后台 subagent——审查工作不再占用您的对话上下文——默认在后台运行 context: fork skills（可在各项 skill 中设置 background: false 选择退出），仅在显式调用时启动 /deep-research，将危险 rm、后台 & 和可疑 Windows 路径检查交给 auto-mode 分类器处理，而不再使用权限对话框，并阻止 agent frontmatter hooks 从不受信任的文件夹运行。¹⁸⁶ v2.1.219（7月24日）将 Claude Opus 5（claude-opus-5）设为默认 Opus 模型——拥有 1M 上下文、128K 最大输出、每 MTok $5/$25 的价格（与 Opus 4.8 相同），默认启用 thinking，effort 默认为 high，知识截止日期为2026年5月——并修正了早期版本引入的两项变化：fast mode 现在适用于 Opus 5 和 Opus 4.8，价格均为每 MTok $10/$50（基础价格的2倍，同时 Opus 4.7 已完全从 fast mode 中移除）；nested subagents 再次默认启用，深度为3（设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可禁用嵌套）。同一版本还新增了 DirectoryAdded hook 事件、sandbox.network.strictAllowlist 设置和 workflowSizeGuideline 设置键；dynamic workflows 现在默认采用中等规模准则（目标是少于15个 agents）；stream-json 也支持转发 nested-subagent。v2.1.220（7月25日）仅包含错误修复和可靠性改进。^187188189 自 v2.1.174–176（2026年6月12日）起，availableModels 允许列表现在可通过新的 enforceAvailableModels 托管设置限制 Default 模型（用户或项目设置无法扩大托管列表）；会话标题将以您的对话语言生成（可使用 language 设置固定语言）；该版本还新增了 footerLinksRegexes 和 wheelScrollAccelerationEnabled 设置、VSCode /usage 归因对话框，并修复了 hook if 条件无法匹配 Read/Edit/Write 路径模式的问题。¹⁷² 自 v2.1.173（2026年6月11日）起，带有 [1m] 后缀的 Fable 5 模型名称会自动规范化并移除该后缀——Fable 5 默认已包含 1M 上下文，因此无需该后缀（它仅对 Opus/Sonnet 有意义）。自 v2.1.172（2026年6月10日）起，sub-agents 可以递归生成自己的 sub-agents，最深可达5层——该默认设置一直延续至 v2.1.216，并在 v2.1.217 中关闭（详见上文）——当未设置 AWS_REGION 时，Bedrock 会从 ~/.aws 读取区域（/status 会显示来源）；/plugin 新增市场搜索栏；claude_code.lines_of_code.count OTEL 指标新增 model 属性。自 v2.1.170（2026年6月9日）起，Claude Fable 5——高于 Opus 的新模型层级——在执行 claude update 后，可通过 /model fable 在 Claude Code 中选择（它支持完整的 low–max effort 范围，但无法禁用 thinking）；Opus 4.8 仍是智能体任务的默认模型。自 v2.1.169（2026年6月8日）起，--safe-mode（以及 CLAUDE_CODE_SAFE_MODE）会启动一个禁用所有自定义项的干净会话，以便排查问题；/cd 可将会话移至新的工作目录，同时不破坏提示词缓存；disableBundledSkills 会对模型隐藏内置 skills 和 slash commands。自 v2.1.166（2026年6月6日）起，fallbackModel 设置可在主模型过载时串联最多3个备用模型；glob "*" 可用于 MCP 拒绝规则；MAX_THINKING_TOKENS=0 / --thinking disabled 可在默认启用 thinking 的模型上将其彻底关闭。自 v2.1.154（2026年5月28日）起，Opus 4.8 成为新的默认模型，默认采用 high effort，并新增 /effort xhigh 层级；dynamic workflows 通过 /workflows 在后台编排数十到数百个 agents；Opus 4.8 的 Fast mode 以2倍标准价格换取2.5倍速度；除 Haiku/Sonnet/Opus 4.7 及更早版本外，所有模型现在默认使用精简 system prompt；/simplify 恢复为仅执行清理的审查（与 /code-review --fix 分开）；claude agents 接受 ! <command> 以生成后台 shell 会话；plugins 可声明 defaultEnabled: false；始终启用流式工具执行；stdio MCP 服务器会在 env 中收到 CLAUDE_CODE_SESSION_ID 和 CLAUDECODE=1。v2.1.153 为 plugin 市场新增 skipLfs，使 /model 保存为默认模型（按 s 可仅应用于当前会话），并将 COLUMNS/LINES 加入状态栏 env。v2.1.152 引入 /code-review --fix（将发现的问题修复到工作树）、skill frontmatter 中的 disallowed-tools、/reload-skills、新的 MessageDisplay hook 事件、SessionStart hook 的 reloadSkills/sessionTitle 输出、pluginSuggestionMarketplaces 托管设置和会话期间的 --fallback-model 切换，并移除了 auto-mode 的选择加入机制。^{162 163 164 165 166 167 168 169 170 191 171}

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 搜索特定 flag、命令或配置键。末尾的快速参考卡简明汇总了所有主要命令，便于快速查阅。

相关深度文章

以下博文深入探讨了 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 18+；推荐的原生安装器不依赖Node。支持macOS / Linux / Windows 10+。Claude Pro、Max、Team或Enterprise订阅，或按token付费的Anthropic API密钥，均可覆盖使用需求。有关平台细节、故障排查和原生二进制路径（自v2.1.113起默认），请参阅如何安装Claude Code？。本指南中的最新发布证据已对照v2.1.154核验。¹⁹¹

Claude Code如何工作：心智模型

在深入功能之前，先了解Claude Code的架构如何影响您使用它时的一切操作。系统分为三层运行：

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   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会以干净的上下文启动，执行聚焦任务，然后返回摘要。探索结果不会膨胀您的主对话；只有结论会返回。可将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. Memory如何工作？
18. 图像和多模态输入
19. 语音模式
20. Git集成如何工作？
21. 如何在我的IDE中使用Claude Code？
22. 高级使用模式
23. 远程和后台Agents [RESEARCH PREVIEW]
24. Chrome中的Claude
25. Slack中的Claude Code [RESEARCH PREVIEW]
26. Web上的Claude Code [RESEARCH PREVIEW]
27. 性能优化
28. 如何调试问题？
29. 企业部署
30. 键盘快捷键参考
31. 最佳实践
32. Workflow Recipes
33. 迁移指南
34. 面向特定受众的指导
35. 快速参考卡片
36. Changelog
37. References

如何安装Claude Code？

系统要求

Claude Code可在macOS 13+、Ubuntu 20.04+/Debian 10+以及Windows 10+（原生或WSL）上运行。系统至少需要4 GB内存，并需要稳定的互联网连接。⁹² Shell兼容性方面，Bash、Zsh或Fish效果最佳。

对于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

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密钥，但可以监控使用情况。

Claude Pro或Max订阅

使用您的claude.ai账户凭据。订阅在单一月度计划下涵盖网页界面和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。¹⁵⁴ OS CA证书信任（v2.1.101+）： 企业TLS代理现已默认可用——Claude Code信任操作系统证书存储。设置CLAUDE_CODE_CERT_STORE=bundled可仅使用捆绑的CA。¹⁴³

# 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

验证

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

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

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 中的 subagents 文本（v2.1.211+）： 默认情况下，stream-json 输出仅包含主会话的事件——subagents 内部完成的工作会以摘要形式呈现。--forward-subagent-text 标志（或 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1）还会将 subagents 的文本和思考输出转发到数据流中，使运行框架和日志管道能够实时观察委派工作的执行过程，而非只能看到最终报告。[^205]

嵌套 subagents 现在也会转发（v2.1.219）。 最初只有深度为 1 的 subagents 会显示。如今，深度为 2 及更深层级生成的 subagents 也会出现在转发的数据流中，并分别以生成它的 Agent 调用的 tool_use ID 作为键。这样一来，管道便可重建委派树，而不是只能看到扁平的文本列表。这与同一版本默认恢复深度为 3 的嵌套生成机制相辅相成：如果没有这项转发功能，三个层级中将有两个不可见。¹⁸⁷

退出代码：

在 -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-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

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

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"

与 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 保留下来。[^206] 自 v2.1.214 起，以分支形式启动的会话会将 SessionStart hook 来源报告为 "fork"（此前为 "resume"），因此按来源匹配的 hooks 能够区分二者。[^207] v2.1.216 将 /fork 的确认信息精简为一行，其中显示新会话的名称及其 claude attach ID。[^209]

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

获批后自动清除上下文是推荐的工作流程。它为计划提供全新的上下文窗口，能够显著提高计划遵循度——不受旧对话干扰，Claude 可以更长时间地按计划执行。

适合使用计划模式的场景： - 涉及架构决策的新功能实现 - 希望先审阅方案的多文件重构 - 需要先探索再修改的陌生代码库 - 存在多种可行方案并希望参与决策的任何任务

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

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

Claude Code 提供专用的屏幕阅读器模式，可调整终端 UI 以适配辅助技术。可通过以下三种方式中的任意一种启用：[^203]

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

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

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

Anthropic 官方文档新增了无障碍页面，用于说明该模式及其交互方式。[^203]

配置系统深度解析

Claude Code采用分层配置系统。理解其层级关系至关重要，因为较高层级会覆盖较低层级，而且企业设置完全无法绕过。

配置层级

专家提示：在共享项目中，使用.claude/settings.local.json保存个人偏好设置（并将其添加到.gitignore）。使用.claude/settings.json保存纳入版本控制的团队级配置。

从提示中设置配置：/config key=value（v2.1.181）

自v2.1.181起，/config key=value可直接从提示中以内联方式设置任意配置，例如/config thinking=false，无需打开交互式/config界面；此功能适用于交互式、-p和Remote Control会话。/config --help（v2.1.183）会列出可用的简写键。v2.1.183还调整了交互式/config界面：Enter和Space现在都能切换所选设置，Esc则保存并关闭（此前会还原更改）。¹⁷⁴

settings.json完整参考

以下完整配置展示了所有主要选项：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "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": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

当团队拥有庞大的skills库，但希望更严格地控制运行时暴露范围时，skillOverrides十分实用。使用off可同时在模型和slash picker中隐藏skill；使用user-invocable-only可保留按名称调用的能力，同时将其从模型选择范围中移除；使用name-only则仅显示skill名称，不显示完整描述。¹⁵⁶

较新的设置（v2.1.174–176）：

• availableModels / enforceAvailableModels（托管，v2.1.175+）：availableModels允许列表会限制会话可以选择的模型。设置enforceAvailableModels: true后，允许列表还会约束默认模型：如果默认模型最终解析为被禁止的模型，则回退到第一个获准模型；用户或项目设置也无法再扩大托管的availableModels列表。配套修复（v2.1.176）堵住了别名选择可通过ANTHROPIC_DEFAULT_*_MODEL重定向至被阻止模型的漏洞，/fast现在也会拒绝切换到允许列表之外的模型。¹⁷² 自v2.1.187起，组织可以直接在/model选择器、--model、/model和ANTHROPIC_MODEL中强制执行模型限制。选择受限模型时，会显示“受到您所在组织的设置限制”消息。¹⁷⁶
• 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模式）。[^203]
• axScreenReader（v2.1.208）：持久启用屏幕阅读器模式（请参阅屏幕阅读器模式）。[^203]
• processWrapper（v2.1.208）：让Claude Code为自身启动的每个进程都通过包装器可执行文件运行——专为企业启动器而设计（请参阅企业部署）。[^203]
• autoMode来源限制（v2.1.207）：不再从仓库的.claude/settings.local.json读取autoMode设置，请改在~/.claude/settings.json中进行配置。这样可以防止克隆的仓库夹带自动模式配置。¹⁸⁵

较新的设置（v2.1.217）：

• emojiCompletionEnabled（v2.1.217）：在提示输入框中自动补全表情符号短代码——输入:heart:可插入❤️，输入:hea等不完整代码则会显示建议。默认启用；设为false可将其禁用。[^211]

较新的设置（v2.1.219）：

• sandbox.network.strictAllowlist（v2.1.219）：拒绝沙盒命令访问允许列表之外的主机，且不显示提示，而不是弹出权限对话框。请参阅沙盒模式。¹⁸⁷
• workflowSizeGuideline（v2.1.219）：可从任意设置文件（用户、项目或托管设置）配置建议性的Dynamic workflow规模准则，而不再只能通过/config配置。Dynamic workflows默认采用中等准则（“目标是少于15个agents”）；当设置文件提供该值时，/config中的对应行会自动隐藏。这只是建议，并非强制上限。请参阅Subagents。¹⁸⁷

环境变量参考

身份验证和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

模型配置：

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
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_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
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

行为控制：

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
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+)
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=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
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+)[^206]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200; /clear resets the budget; v2.1.212+)[^206]
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_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                    # Bash output limit
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_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

网络和代理：

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
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

界面和终端：

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
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[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
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_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
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+)
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+)
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.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日志事件中的数值属性现在以数字形式发出（此前为字符串），修复了下游OTel收集器对架构进行严格类型检查时的问题。Claude Code解析@提及时，现在会触发新的claude_code.at_mention日志事件。¹⁵⁴

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截断上限。[^207]

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+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
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+)

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

可用模型

将工具框架从Opus 4.8迁移至Opus 5时存在两项破坏性变更：¹⁸⁸

1. 默认开启思考。在Opus 4.8中，未包含thinking字段的请求会在不进行思考的情况下运行；在Opus 5中，同样的请求会启用自适应思考。max_tokens仍是总输出量（思考内容加响应文本）的硬性上限，因此，对于此前无需思考即可运行的任何工作负载，都应重新检查余量。传入thinking: {type: "disabled"}可恢复旧行为，但仍受下一项限制。
2. 禁用思考时，effort最高只能设为high。将thinking: {type: "disabled"}与xhigh或max effort组合使用会返回400。此项检查按请求执行——即使同一对话中的先前轮次已获接受，在禁用思考的情况下将effort提高至xhigh仍会被拒绝。

具体到Claude Code：Opus 5的effort默认为high（与Claude API一致），并提供完整的级别序列：low、medium、high、xhigh、max。Anthropic自己的迁移指南建议：如果模型能力比token支出更重要，请测试max effort。快速模式以每MTok $10/$50的价格支持Opus 5（请参阅快速模式）。¹⁸⁸¹⁸⁹

Claude Fable 5（2026年6月9日）：这是一个位于Opus之上的新模型层级——Anthropic最强大、最智能的模型，在其接受测试的几乎所有基准上均达到业界领先水平，并且能够在包含数百万token的上下文中保持连贯。Fable 5是可供一般用途安全使用的“Mythos级”前沿模型：它随附安全分类器，遇到网络、生物化学和模型蒸馏查询时会回退至Opus 4.8（Claude Mythos 5是同一模型，但为获授权研究人员移除了这些防护措施）。从v2.1.170（2026年6月9日）起，可在Claude Code中选择该模型——运行claude update，然后执行/model fable（短别名；/model claude-fable-5和best别名也会选择该模型）——并将在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参数。[^186]

具体到Claude Code：与Opus 5一样，Fable 5支持完整的effort级别（low/medium/high/xhigh/max，默认为high）。Fable 5无法关闭思考——会话思考开关、alwaysThinkingEnabled设置和MAX_THINKING_TOKENS=0均不起作用；它始终采用自适应推理。完整的fable系列配置接口与Opus的配置项相呼应：ANTHROPIC_DEFAULT_FABLE_MODEL可固定fable别名解析到的模型（适用于Bedrock/Vertex/Foundry）；DISABLE_PROMPT_CACHING_FABLE可让Fable不使用提示词缓存；企业网关还会根据内容自动回退。/model opus现在会选择Opus 5（默认使用high effort，最困难的任务可使用/effort xhigh）；自v2.1.197起，Sonnet 5已成为开箱即用的默认模型。如需追求绝对性能上限，请有针对性地通过/model fable选择Fable 5。[^186]¹⁸⁸

Opus 4.7（2026年4月16日）：上一代旗舰模型，目前仍完全可用。1M token上下文窗口采用标准定价，不收取长上下文溢价。最大输出为128K，仅支持自适应思考（已移除扩展思考），并新增xhigh effort级别，建议将其作为编码和智能体式工作负载的起点。¹⁴⁵可靠知识截止日期：2026年1月。训练数据截止日期：2026年1月。模型ID：claude-opus-4-7。定价与Opus 4.6相同，每MTok输入/输出为$5/$25，5分钟缓存写入为$6.25，1小时缓存写入为$10，缓存读取为$0.50。¹⁴⁴在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 px/3.75 MP的图像，并采用1:1像素坐标。¹⁴⁵

Opus 4.7编码基准（2026年4月）：¹⁵¹

各计划的默认模型（Claude Code）：¹⁴⁷

Opus 4.7中Messages API的破坏性变更（调用方可见）：¹⁴⁵ - 扩展思考的budget_tokens已被移除。请改用thinking: {type: "adaptive"}。自适应思考默认关闭；未设置thinking字段的请求将不启用思考。 - 将temperature、top_p或top_k设为非默认值会返回HTTP 400。请省略这些参数，改用提示词引导模型。 - 默认情况下，响应中不会包含思考内容。设置thinking.display: "summarized"可恢复可见的推理内容（如果您的产品会向用户流式传输思考过程，则必须设置此项）。

任务预算（beta标头task-budgets-2026-03-13）允许通过output_config.task_budget向模型建议完整agentic循环的目标token数；最低为20K token。¹⁴⁵

Opus 4.6（旧版）：仍可通过claude-opus-4-6使用，提供1M上下文和最大128K输出。若需获得更出色的agentic编程能力，建议迁移至Opus 4.7。Opus 4.6最初于2026年2月5日发布。⁷⁹¹⁴⁴ 自v2.1.117（2026年4月22日）起，Pro和Max订阅用户使用Opus 4.6和Sonnet 4.6时，默认effort为high（此前为medium）；Opus 4.7仍默认为xhigh。这一调整恢复了模型智能水平，此前在4月23日的事后分析中记录了3月4日至4月7日期间的effort下调。¹⁵²¹⁵³

Sonnet 5（2026年6月30日）：当前的Sonnet级别，定位为“速度与智能的最佳结合”。Anthropic表示，其性能接近Opus 4.8，但价格更低。与Sonnet 4.6相比，它在agentic推理、工具使用、编程和知识工作方面均有显著提升，同时总体不良行为发生率更低，网络安全能力则远弱于Opus系列模型（正是这种安全性取舍，使其得以在不受出口管制限制的情况下发布）。模型ID：claude-sonnet-5（无日期的固定快照）。上下文窗口为1M token，最大输出为128K（使用output-300k-2026-03-24 beta标头时，在Batches API上最高可达300K），仅支持自适应思考。可靠知识截止日期：2026年1月。定价：每MTok输入/输出分别为3美元/15美元；截至2026年8月31日，首发优惠价为2美元/10美元——比Opus 4.8的5美元/25美元低约40%。在Claude Code中，Sonnet 5的effort参数默认为high（如需更改，请显式设置）。可使用/model sonnet（或/model claude-sonnet-5）选择该模型。¹⁸⁰ 自v2.1.197（2026年6月30日）起，Sonnet 5成为Claude Code中新会话的默认模型，取代Opus 4.8成为开箱即用的默认选择；Opus仍可正常选择。¹⁸¹

Sonnet 4.6（2026年2月17日发布，现已被Sonnet 5取代）：均衡型模型；取代Sonnet 4.5，成为claude.ai和Claude Cowork的默认模型。⁹³ 定价与Sonnet 4.5相同（每MTok输入/输出分别为3美元/15美元）。在减少token消耗的同时，提升了agentic搜索性能。支持扩展思考、自适应思考和1M token上下文窗口（beta）。最大输出为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——这是一项安全性取舍；同时已在https://claude.com/form/cyber-use-case开放Cyber Verification Program，供需要更高级别访问权限的合法安全研究人员申请。¹⁴⁶

这些价格差异为何重要：一次典型的编程会话会消耗50K至200K输入token和10K至50K输出token。使用Haiku时，每次会话成本为0.10至0.45美元。使用Opus时，同一会话成本为0.50至2.25美元，高出5倍。请仅将Opus用于真正棘手的问题。¹

每种模型的适用场景

Haiku：适合执行探索、简单文件搜索和快速问答的subagents。其成本约为Opus的五分之一，响应速度也更快。非常适合无需深度推理的后台任务。

Sonnet：注重成本时的日常开发主力。可处理大多数编程任务，包括实现功能、修复错误、编写测试和代码审查。与Sonnet 4.5相比，Sonnet 4.6提供更强的agentic搜索能力和更高的token效率，同时支持自适应思考，并以标准价格提供1M上下文窗口。⁹³ 自Opus 4.7发布（2026年4月16日）起，Claude Code仅在Max和Team Premium计划中默认使用Opus；Pro、Team Standard、Enterprise和API账户仍默认使用Sonnet 4.6，直至Enterprise和API于2026年4月23日切换至Opus 4.7。¹⁴⁷ 当您需要成本更低的token、更短的延迟或更经济的subagent时，请使用Sonnet。

Opus：截至2026年4月16日的旗舰级别，也是Max和Team Premium计划的默认模型。¹⁴⁴¹⁴⁷ 应将成本更高的推理能力用在物有所值的场景中：架构决策、棘手的调试、理解复杂系统、安全分析以及长周期agentic工作。Opus 4.7在SWE-Bench上解决的生产任务数量是Opus 4.6的3倍；CursorBench得分为70%（后者为58%）；在一项包含93个任务的内部编程基准测试中，解决率提高了13%。¹⁴⁴ Claude Code在Opus 4.7上默认使用xhigh effort，可通过/effort调整（v2.1.111及以上版本）。¹⁴⁶¹⁴⁷ Max订阅用户可通过Anthropic API在Opus 4.7上使用Auto Mode，无需设置--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-4-5-20250929"
}

专用于subagents：

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

备用模型链（v2.1.166及以上版本）：当主模型过载或不可用时，fallbackModel设置可配置最多3个备用模型，并按顺序尝试。--fallback-model标志此前仅用于会话中途切换，现在从启动开始也适用于交互式会话。[^184]

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

当API返回意外且不可重试的错误时，Claude Code现在还会使用备用模型重试该轮一次，之后才会呈现失败。因此，主模型的临时问题会平稳降级，而不会直接丢失该轮。[^184]

自v2.1.178起，压缩也会遵循备用模型链——如果主模型在压缩过程中出现过载或不可用，压缩步骤会转而使用已配置的fallbackModel/--fallback-model链，而不是导致该轮失败。对于长时间自主运行而言，这弥补了此前的缺口：原本可恢复的压缩操作不会再因临时模型错误而中断会话。¹⁷³

扩展上下文

对于大型代码库或长时间会话，请启用1M token上下文：

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

也可在会话中启用：

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

Opus 4.7、Opus 4.6和Sonnet 4.6均以标准价格提供完整的1M token上下文窗口，不收取长上下文溢价。¹⁴⁸ 900K token请求与9K token请求采用相同的单token费率计费。在整个上下文窗口内，提示缓存和批处理折扣均按标准费率计算。

在Max、Team和Enterprise订阅中，Opus会自动包含1M上下文，无需使用[1m]后缀（自v2.1.75，即2026年3月13日起默认启用）。¹¹⁷¹⁴⁷ Pro用户可通过额外用量使用1M上下文。API和按量付费用户均可以标准单token费率完整使用1M上下文。¹⁴⁷

要在模型选择器中禁用1M上下文变体，请设置CLAUDE_CODE_DISABLE_1M_CONTEXT=1。

查看当前模型

> /status

该命令会显示当前模型、账户信息、已应用的设置及其他会话状态。 模型选择器标签（v2.1.51+）： /model 选择器现在会为固定版本显示易于理解的标签（例如“Sonnet 4.6”），而非原始模型 ID；如有更新版本可用，还会显示升级提示。⁹⁸ v2.1.219 修复了合并后的 Opus 行仅显示为普通“Opus”、而非 “Opus（1M 上下文）”的问题，并将新版本高亮范围缩小至最新模型的名称，确保高亮准确标示实际发布的内容，而非列表中的任意片段。¹⁸⁷

Fast Mode（v2.1.36+）

Fast mode 可让同一模型显著加快输出；它不会切换到更便宜的模型。在会话期间使用 /fast 切换此模式。⁸⁶

> /fast            # Toggle fast mode on/off

适用模型（截至 v2.1.219）： fast mode 适用于 Claude Opus 5 和 Claude Opus 4.8。v2.1.219 已将 Opus 4.7 从 fast mode 中移除，该功能也从未支持 Sonnet、Haiku 或 Fable。它仍然仅作为 research preview 在 Claude API（包括 Claude Managed Agents）中提供，不支持 Amazon Bedrock、Google Cloud、Microsoft Foundry 或 AWS 上的 Claude Platform。访问权限受限：请联系您的客户经理或加入候补名单。¹⁸⁷¹⁸⁹

定价（Opus 5 / Opus 4.8 fast mode）：¹⁸⁹

Opus 4.7 的陷阱（v2.1.219）。 不受支持的模型并非表现一致。向 claude-opus-4-7 发出包含 speed: "fast" 的请求，现在会返回错误，不会悄然回退到标准速度。Opus 4.6 是一个值得注意的例外：它接受 speed: "fast"，但仍以标准速度运行、按标准费率计费，并报告 usage.speed: "standard"。如果您的工具链固定使用 4.7，并依赖 fast-mode 请求静默降级，那么这些请求现在会直接失败；请将固定版本迁移至 Opus 5 或 4.8。¹⁸⁹

适合使用 fast mode 的场景： - 快速迭代小型改动，且延迟是主要瓶颈 - 生成测试、样板代码或重复性代码，且速度比成本更重要 - 按顺序处理一系列相似任务

不适合使用 fast mode 的场景： - 长时间运行的智能体任务（整个运行过程的成本仍会翻倍） - 后台 subagent 工作（无人等待输出） - 注重预算的会话

Fast mode 包含完整的 1M 上下文窗口（v2.1.50+）。整个上下文统一按固定倍数计费，包括输入 token 超过 200K 的请求，不会额外收取长上下文附加费；该倍数还会与提示缓存和数据驻留的价格倍数叠加。⁹⁶¹⁸⁹

操作说明。 Fast mode 有独立的速率限制，与标准 Opus 限制分开计算；超出限制会返回带有 retry-after 的 429（anthropic-fast-*-tokens-* 响应头会报告剩余容量）。在 fast 与标准模式之间切换会使提示缓存失效——不同速度的请求不会共享已缓存的前缀，因此在会话中途切换 /fast 会导致缓存未命中。Fast mode 不适用于 Batch API，也不能与 Priority Tier 承诺用量搭配使用。¹⁸⁹

专家提示： Fast mode 无法与 opusplan 搭配使用（opusplan 已经混合使用 Opus 和 Sonnet；fast mode 只影响 Opus 阶段）。当延迟比成本更重要时使用它；执行自主任务或批量工作时应将其禁用。/fast 需要额外用量；Team/Enterprise 管理员可能需要先启用该功能（v2.1.37 修复）。若要彻底禁用，请设置 CLAUDE_CODE_DISABLE_FAST_MODE=1。自 v2.1.218 起，当通过 /config model=<x> 或 Remote Control 切换模型并导致 fast-mode 状态改变时，Claude Code 会发出通知；v2.1.219 还修复了 Remote Control 客户端在切换、重新连接或组织检查失败后仍保留过期 fast-mode 状态的问题。^86149186187

工作强度控制（v2.1.111+，Opus 4.7）

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

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

Max 上的 Auto Mode（v2.1.111+）

Auto Mode 是 --dangerously-skip-permissions 更安全的替代方案。Max 订阅者可通过 Anthropic API 在 Opus 4.7 上使用，无需指定 --enable-auto-mode。¹⁴⁶ Sonnet-4.6 分类器会在执行前审查每项操作，检查其是否符合意图并确保安全。注意（v2.1.111+）： --enable-auto-mode 标志已被移除；请改用 --permission-mode auto 以 Auto Mode 启动会话。Auto Mode 不适用于 Pro；根据 Anthropic 的权限模式文档，它默认直接在 Anthropic API 上提供。Bedrock/Vertex/Foundry（v2.1.158+）： 在这些网关上，Opus 4.7 和 Opus 4.8 的 Auto Mode 改为通过 CLAUDE_CODE_ENABLE_AUTO_MODE=1 选择启用。¹⁹⁰ 自 v2.1.207 起，无需再选择启用： Auto Mode 可在 AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 上运行，无需设置 CLAUDE_CODE_ENABLE_AUTO_MODE；希望禁用该功能的管理员可使用 disableAutoMode 托管设置。同一版本还使 Bedrock、Vertex AI 和 AWS 上的 Claude Platform 默认使用 Claude Opus 4.8，并停止从仓库的 .claude/settings.local.json 读取 autoMode 设置——请改在 ~/.claude/settings.json 中配置 Auto Mode 规则。¹⁸⁵

在不丢失默认规则的情况下添加自定义规则（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
    ]
  }
}

“不再询问”选择启用项（v2.1.118+）。 Auto Mode 选择启用提示现在提供“不再询问”选项，方便经常使用该功能的用户关闭说明提示，无需通过脚本设置标志。¹⁵²

破坏性命令防护措施（v2.1.183）。 除非您在会话中明确要求，否则 Auto Mode 现在会强制阻止一组不可逆命令：在您未要求丢弃本地工作时执行破坏性 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）。 默认情况下，Auto Mode 分类器只审查匹配任意代码执行模式的 shell 命令；常规命令会跳过审查。新的 autoMode.classifyAllShell 设置会改为让所有 Bash/PowerShell 命令都经过分类器审查。当您希望每次 shell 调用均接受检查时，可以牺牲少许延迟，换取更严密的安全保障。同一版本还会在对话记录、拒绝通知和 /permissions 的近期拒绝记录中显示 Auto Mode 拒绝原因，因此命令被阻止时，系统现在会说明具体原因。¹⁷⁹ 另外3条加固规则（v2.1.205）。 auto模式现在会阻止篡改会话记录文件——审计轨迹本身属于代理不可触碰的禁区；对于使用无法根据上下文解析的变量执行的rm -rf，它会先征求许可——从而避免未知$DIR引发rm -rf $DIR这类事故；此外，后台任务通知现在会明确说明尚未发生任何人工输入，因此无法再通过在记录中伪造“用户已批准”一行来冒充有效批准并付诸执行。¹⁸³ 第3条是值得牢记的提示词注入防御措施：批准必须通过批准通道传达，而运行框架现在明确规定了这一前提。

命令替换无法再掩盖灾难性操作（v2.1.208）。 rm -rf ~等灾难性删除操作现在即使隐藏在$(...)、反引号或进程替换（<(...)）中，也会触发确认提示——而且即使处于--dangerously-skip-permissions和auto模式下，提示仍会出现。将破坏性命令封装在替换表达式中，再也无法蒙混过关、绕开安全防线。[^203]

重置auto模式状态：claude auto-mode reset（v2.1.212）。 新增的子命令可从终端重置auto模式状态；传入--yes可跳过确认提示：[^206]

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

减少对话框，审查力度不变（v2.1.218）。 过去有3项检查会通过权限对话框中断auto模式——危险的rm、后台运行符&和可疑的Windows路径——现在不再弹出对话框，而是交由auto模式分类器裁决。因此，安全审查仍会照常进行，但不会每次命中都打断您的操作。同一版本还将这一机制扩展至结合auto的plan模式：对于静态分析器无法证明为只读的Bash命令，不再弹出提示，而是由分类器判断，不再回退到对话框。

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

推送通知（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+）

带有glob参数的只读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式导航，以及全屏视口滚动功能：

Subagent停滞超时（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，建议升级。

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

订阅方案

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

速率限制翻倍（2026年5月6日）： 在 Code with Claude SF 活动期间，Anthropic 将 Pro、Max、Team 和按席位计费的 Enterprise 方案中 Claude Code 的 5 小时速率限制提高了一倍，取消了 Pro 和 Max 账户在高峰时段的用量缩减，并“大幅”提高了 Claude Opus 模型的 API 速率限制。其算力保障来自 SpaceX Colossus 1 合作协议：“当月内新增超过 300 兆瓦的算力（超过 220,000 块 NVIDIA GPU）。”¹⁵⁷

API Token 定价（2026年4月）¹¹⁴⁴

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

1M 上下文定价（2026年4月）： Opus 4.7、Opus 4.6、Sonnet 4.6 和 Mythos Preview 均以标准每百万 token 费率提供 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%。对于需要反复使用上下文的 RAG 系统和代码助手，缓存可降低 88% 至 95% 的成本。

批量 API 为夜间测试套件等非紧急任务提供 50% 的折扣，并在 24 小时内完成处理。

多账户政策⁵²

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

允许的情况：

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

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

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

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

成本影响因素

实际成本示例

节省成本的要点： 使用 Haiku 承担探索型 subagents 任务、使用 Sonnet 负责实现，相较于所有任务均使用 Sonnet，通常可降低 40% 至 50% 的成本。

团队成本管理

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

隐性工具费用

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

这些费用在 agent 循环中会逐渐累积。一个包含 100 次迭代的 Bash 调试周期，仅调用开销就会额外消耗约 24,500 个输入 token。

节省成本的策略

1. 为 subagents 使用 Haiku：大多数探索任务无需使用 Sonnet
2. 启用提示词缓存：默认已启用，但请确认未被禁用
3. 设置最大轮数：claude --max-turns 5 可防止对话失控
4. 设置费用上限：claude --max-budget-usd 5 会在支出达到上限时强制停止会话。从 v2.1.217 起，此上限也适用于后台 subagents——达到上限后，系统会拒绝启动新的 subagents，并停止正在运行的后台 agents（此前后台 agents 不受预算限制）[^211]
5. 使用规划模式进行探索：不执行操作，就不会意外触发高成本操作
6. 主动压缩上下文：上下文越小，token 越少
7. 限制输出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 对非紧急工作使用批量 API：输入和输出 token 均享 50% 折扣

监控用量

• 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"

使用场景： - 开发者生产力分析（会话、commit、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 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

经验法则：对于Max和Team Premium，默认使用Opus 4.7。对于Pro/Team Standard/Enterprise/API，默认使用Sonnet 4.6（Enterprise + Anthropic API将于2026年4月23日切换至Opus 4.7）。¹⁴⁷处理subagents时可降级至Haiku。如果Sonnet的回答流于表面，则升级至Opus。使用智能体团队（v2.1.32+）时，Opus可以协调多个智能体并行处理不同的子任务。⁷⁹

Command、Skill、Subagent还是智能体团队？

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

Hook还是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

智能体团队、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

应该选择哪种Hook类型？

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

何时使用/fast？

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

/fast用于切换当前会话的快速模式。它仍使用同一模型——截至v2.1.219，快速模式仅支持Opus 5和Opus 4.8——但优化了输出速度。它不会切换到成本更低的模型；按每百万token 10美元/50美元计费，也并不更便宜。¹⁸⁷¹⁸⁹

权限系统如何运作？

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

权限层级

只读工具（自动批准）： - Read——读取文件内容 - Glob——按模式查找文件 - Grep——搜索文件内容 - WebSearch——搜索互联网 - LSP——代码智能功能（转到定义、查找引用、悬停文档）¹⁸

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

修改工具（需要批准）： - Edit——修改现有文件 - Write——创建新文件 - Bash——执行shell命令 - WebFetch——获取URL内容 - NotebookEdit——修改Jupyter笔记本

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

EndConversation工具（v2.1.214）。Claude Code现在具备与Claude自2025年以来在claude.ai上已有的相同对话终止能力：在极少数输入极具侮辱性或持续尝试越狱的情况下，Claude可通过内置的EndConversation工具直接结束会话。这是一项抵御滥用并保障模型福祉的措施，并非工作流功能——正常的开发会话不会触发它。[^207][^210]

权限模式

自v2.1.200起，default模式标记为“Manual”。此次更名涵盖CLI、--help、VS Code和JetBrains；配置值并未改变，因此"defaultMode": "default"仍然有效，同时现在也接受--permission-mode manual和"defaultMode": "manual"作为别名。其行为完全相同——每种工具首次使用时提示——只是标签不再将其描述为“碰巧默认启用的模式”，而是准确体现其手动批准模式的性质。在同一版本中，AskUserQuestion对话框默认不再自动继续；subagent提出问题后会等待您的回答，而不会在超时后继续执行。若要重新启用空闲超时，可通过/config进行配置。

即使在acceptEdits模式下，代码执行配置文件现在也会触发提示（v2.1.160）。acceptEdits会自动批准普通编辑，但自v2.1.160起，在写入可能允许静默执行命令的文件前会暂停并请求批准：shell启动文件（.zshenv、.zlogin、.bash_login）、~/.config/git/以及构建工具配置（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/等）。原因在于，编辑其中任何文件都可能使下一次shell启动、安装或提交变为执行途径。因此，即使处于通常会直接放行编辑的可信项目模式，这些文件仍须经过审慎把关。这与现有针对.claude/、.git/和.vscode/的写入保护采用相同威胁模型，只是扩展到了更广泛的“编辑即执行”文件类别。[^182]

Auto Mode（v2.1.85+）：这是--dangerously-skip-permissions更安全的替代方案。一个独立的分类器模型（Sonnet 4.6）会在执行前审核每项操作，检查它是否符合用户意图并且安全。¹²⁴

工作方式： - 工作目录中的只读操作和文件编辑会自动批准 - 自定义允许/拒绝规则会优先判定 - 其他所有操作都交由分类器评估 - 如果遭到阻止，Claude会自动尝试替代方案

默认自动阻止：curl | bash、向主分支强制推送、生产环境部署/迁移、大规模删除云端资源、IAM/权限变更，以及向外部发送敏感数据。¹²⁵

熔断机制：连续阻止3次或单个会话内累计阻止20次后，将暂停Auto Mode并恢复手动提示。¹²⁵

# Enable at startup
claude --enable-auto-mode

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

可用范围：首先面向Team计划用户推出，随后支持Enterprise和API。需要Sonnet 4.6或Opus 4.6。¹²⁴

YOLO模式（v2.0.68+）：如需在没有任何安全分类器的情况下完全自主运行，请使用--dangerously-skip-permissions标志。该标志会批准所有操作：文件编辑、bash命令以及全部工具调用。其中“dangerous”一词绝非危言耸听。对于大多数使用场景，建议改用Auto Mode。⁵⁴

claude --dangerously-skip-permissions

通过CLI设置模式：

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

在会话期间切换：

Shift+Tab  # Cycles through modes

在settings.json中：

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

权限规则语法

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

Bash命令模式：

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

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

重要限制：Bash模式仅匹配前缀，不支持正则表达式。Bash(curl http:*)这样的模式不会匹配curl -X GET http://...，因为选项位于URL之前。如需可靠阻止，应拒绝整个命令：Bash(curl:*)。

文件操作模式：

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

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

单层级dir/**允许规则现在仅匹配<cwd>/dir（v2.1.214）——请审核现有规则。在v2.1.214之前，Edit(src/**)这样的允许规则会自动批准对目录树中任何名为src的目录执行写入——包括vendor/src/、packages/foo/src/等所有此类目录。现在，它只匹配工作目录正下方的src目录。如果依赖旧版的任意深度匹配行为，请将规则改写为Edit(**/src/**)。deny和ask规则仍保留任意深度匹配行为——此次更改只会缩小自动批准范围，绝不会缩小阻止范围。升级后，不再静默匹配的规则会表现为新增权限提示，而不是报错。因此，请检查所有采用单层级形式编写的允许规则。本版本还对hook的if:条件应用了相同的当前工作目录作用域规则（请参阅匹配器）。[^207]

请使用Edit(path)/Read(path)，不要使用Write(path)/NotebookEdit(path)/Glob(path)（v2.1.210）。对于针对Write(path)、NotebookEdit(path)或Glob(path)编写的权限规则，Claude Code现在会在启动时显示警告。规范形式是实际控制文件访问的两类规则：Edit(path)涵盖所有文件写入工具（包括Write和NotebookEdit），Read(path)涵盖所有文件读取工具（包括Glob）。请迁移所有旧版规则，以消除警告并清晰表达规则意图。[^204]

“Always allow”现在保存至仓库根目录（v2.1.211）。通过“Always allow”提示选项创建的权限规则，现在会写入仓库根目录，而不是当前worktree。因此，在一个worktree中授予的批准会跨会话生效，并适用于该仓库的所有worktree——无需再在每个并行检出中重复批准同一命令。[^205]

MCP工具模式：

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

使用通配符语法mcp__server__*，可以允许或拒绝来自特定MCP服务器的所有工具。³²通配符语法便于快速启用可信服务器的全部工具，或阻止不可信来源的整个服务器。

自v2.1.166起，拒绝规则也可在工具名称位置使用glob：在工具名称槽位中使用裸"*"可拒绝所有工具，以便先阻止一切，再单独放行一小部分工具。相比之下，允许规则会拒绝非MCP的glob——无法以同样方式广泛允许所有工具，从而维持严格受限的默认安全策略。[^184]

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

除了工具名称，规则还可匹配工具的输入参数，并使用*作为值的通配符：

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

Agent(model:opus)会阻止生成任何使用Opus层级的subagent——被拒绝的是生成操作本身，而不只是通过提示要求避免使用它。这将权限控制从“使用哪个工具”深入到“如何调用工具”，形成确定性规则，而非仅依赖提示要求。它可与托管设置enforceAvailableModels配合使用：允许列表定义会话中存在哪些模型层级，而Tool(model:...)规则则限制subagent如何从中选择。¹⁷³

自v2.1.186起，这些Agent(...)规则也会对具名subagent的生成操作强制执行：当启动特定具名agent时（通过工作流、--agents或agent团队），Agent(agent_type)拒绝规则和Agent(x,y)允许类型限制同样适用，而不再只适用于匿名的Task式生成。生成操作会在启动时被阻止，从而弥补具名agent可能绕过相关约束规则的缺口。¹⁷⁵

WebFetch模式：

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

其他目录

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

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

对于monorepo，或Claude需要引用同级目录中的代码时，其他目录必不可少。

沙箱模式

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

> /sandbox

或者在设置中配置：

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

自v2.1.187起，sandbox.credentials设置会阻止沙箱内的命令读取凭据文件和机密环境变量，为防范沙箱命令窃取机密提供纵深防御。¹⁷⁶

自v2.1.216起，sandbox.filesystem.disabled设置可跳过文件系统隔离，同时保留网络出站控制——当文件系统隔离环境导致构建工具失效，但仍希望对出站流量强制执行域名允许列表时，此设置十分实用。[^209]

自v2.1.219起，sandbox.network.strictAllowlist设置会直接拒绝未列入允许列表的主机，且不显示提示。默认情况下，沙箱命令连接allowedDomains之外的主机时会触发权限提示；启用strictAllowlist后，连接将直接遭到拒绝。对于无人值守运行——CI、后台agent、通宵循环——应优先采用此设置，因为无人回答的提示只会造成停滞，而且“询问我是否允许意外出站连接”本就不适合作为此类场景的策略。它补全了网络控制三要素：allowedDomains定义允许访问的对象，deniedDomains（见下文）从宽泛的允许范围中排除例外，而strictAllowlist则决定其他所有连接是触发询问还是直接失败。¹⁸⁷

启用沙箱后： - 文件系统访问仅限项目目录 - 网络访问受到控制 - 某些命令不受沙箱限制 - 如果autoAllowBashIfSandboxed为true，则自动允许Bash命令

专家提示：沙箱模式非常适合让Claude处理不可信代码库。探索陌生项目或希望增加一层保护时，建议启用该模式。Anthropic的内部测试发现，沙箱可将权限提示减少84%。³⁸沙箱使用操作系统级原语（macOS seatbelt、Linux bubblewrap）隔离文件系统和网络，因此即使提示注入得逞，其影响也会被完全限制在沙箱内。Anthropic已将沙箱运行时开源，供构建自有agent的团队使用。⁸²

安全说明（v2.1.34+）：此前，通过sandbox.excludedCommands或dangerouslyDisableSandbox排除在沙箱之外的命令，在启用autoAllowBashIfSandboxed时可能绕过Bash询问权限规则；此问题已在v2.1.34中修复。⁸⁷自v2.1.38起，沙箱模式会阻止写入.claude/skills，防止提示注入修改skill定义。⁸⁸v2.1.77新增allowRead沙箱文件系统设置，可在denyRead区域内重新允许读取访问——当您希望阻止目录树的大部分区域，但将特定子目录列入白名单时，此功能非常实用。¹¹⁹

.claude/ agent配置豁免（v2.1.121+）：--dangerously-skip-permissions不再为写入.claude/skills/、.claude/agents/和.claude/commands/显示提示。¹⁵⁴

嵌套.claude/解析（v2.1.178）：处理某个目录下的文件时，嵌套.claude/skills目录中的skills现在会自动加载，不再仅从仓库根目录加载；若名称冲突，可通过<dir>:<name>访问嵌套skill，从而使两者均保持可用。项目其余部分也采用相同的解析方式——当嵌套.claude/目录中的agent、工作流或输出样式名称发生冲突时，距离工作目录最近的定义优先；保存项目作用域的工作流时，则以距离最近的现有.claude/workflows/为目标。对于monorepo或仓库嵌套仓库的场景，这使各软件包的专属工具能够根据上下文激活，摆脱单一扁平全局界面的限制。¹⁷³

自定义bubblewrap和socat路径（v2.1.133+）：托管设置sandbox.bwrapPath和sandbox.socatPath允许管理员将Linux/WSL部署指向非标准的bubblewrap和socat二进制文件位置。当发行版将这些工具安装在$PATH之外，或组织使用自行提供的强化版本时，此功能十分实用。¹⁶⁰

v2.1.113中的安全加固：¹⁵⁰

• sandbox.network.deniedDomains会阻止特定主机，即使范围更广的allowedDomains通配符原本允许访问这些主机。利用此阻止列表，可以切断对pastebin、文件投递站点或已知恶意主机的访问，而无需改写整套允许策略。若希望允许列表之外的所有连接都被静默拒绝而非触发提示，可将其与sandbox.network.strictAllowlist（v2.1.219，见上文）配合使用。
• 包装命令拒绝规则。Bash拒绝规则现在可匹配由env、sudo、watch、ionice、setsid及类似exec包装器封装的命令。Bash(rm:*)等规则现在可以捕获env rm -rf、sudo rm -rf及类似的绕过形式。
• Bash(find:*)允许规则不再自动批准find -exec或find -delete。这些标志会执行命令和删除文件，因此Claude Code会将其交由常规权限流程处理。
• macOS删除保护。Bash(rm:*)允许规则现在会将/private/etc、/private/var、/private/tmp和/private/home视为危险的删除目标。/var、/etc和/tmp是指向/private/的符号链接，因此此前的规则形式遗漏了这些规范路径下的目标。

v2.1.214中的权限故障闭锁加固：[^207]

该版本集中修复了一批权限检查缺口，且统一采用故障闭锁原则——分析器无法确定安全性时，就会触发提示：

• 修复Windows PowerShell 5.1绕过问题。此前，在PowerShell 5.1会话中运行的命令可能绕过权限检查。
• Bash文件描述符重定向采用故障闭锁。对于bash与权限分析器解析结果不一致的重定向形式，现在会触发提示，而不是直接运行。
• 超过10,000个字符的命令始终触发提示。此前可能错误判断超长命令；现在绝不会自动运行。
• [[ ]]中的zsh下标和修饰符会触发提示。[[ ]]比较中的变量下标和修饰符此前被视为惰性文本；它们可以执行代码，因此现在需要批准。
• 不安全的help/man变体不再自动批准。某些调用可能以阅读文档为幌子，运行不安全选项、命令替换或包含反斜杠的路径。
• 远程会话提示顺序。远程会话中的权限提示无法再先于本地确认对话框继续执行。
• docker守护进程重定向标志会触发提示。携带--url、--connection、--identity或Podman远程模式的docker命令（包括Podman的docker兼容层）此前无需提示即可运行——这些标志会将命令指向完全不同的守护进程。
• 当指定写入位置时，file不再享有只读免审待遇。file -m/--magic-file和-f/--files-from现在需要获得权限，不再作为只读操作自动放行。

Hooks 如何工作？

Hooks 会在 Claude Code 工作流的特定节点执行确定性的 shell 命令。与通过提示要求 Claude 执行操作不同，无论模型如何表现，hooks 都能保证执行。它们对于落实团队标准和自动处理重复任务至关重要。有关涵盖 command、prompt 和 agent hooks 的“应该选择哪种 Hook 类型？”决策树，请参阅决策框架。

为什么使用 hooks 而不是提示：要求 Claude“编辑文件后始终运行 Prettier”有时有效。但 Claude 可能会忘记、优先追求速度，或认为改动“太小”而不必执行。Hooks 可以保证执行：每次 Edit 或 Write 都会触发格式化工具，无一例外。对于合规、安全和团队标准，确定性方案优于概率性方案。⁴

可用事件

SessionStart 的 source 值。SessionStart hook 输入包含 source 字段，用于说明会话的启动方式："startup"、"resume"、"clear" 或 "compact"。从 v2.1.214 起，以分支形式创建的会话会报告 source: "fork"，而不再是 "resume"——这是 hook 侧为配合 v2.1.212 中 /fork 转为后台运行所做的改动。如果 SessionStart hook 会根据 source 进行分支处理（例如，仅在 "resume" 时重新注入上下文），请更新其匹配列表，将 "fork" 也纳入其中。[^207]

Hook 配置

在 settings.json 或专用 hooks.json 中定义 hooks：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

匹配器

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

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

使用 | 匹配多个工具（Edit|Write）。从 v2.1.191 起，以逗号分隔的匹配器（例如 Bash,PowerShell）也能正确触发；早期版本会悄然忽略这类匹配器，导致使用逗号匹配器的 hook 从不运行。¹⁷⁸ 从 v2.1.195 起，包含连字符标识符的匹配器（例如 code-reviewer、mcp__brave-search）会进行精确匹配，不再意外执行子字符串匹配，因此不会再因非目标工具仅包含该字符串而误触发。若要匹配某个名称含连字符的 MCP 服务器提供的所有工具，请使用 mcp__brave-search__.* 之类的显式模式。¹⁷⁹

从 v2.1.214 起，Hook 的 if: 路径条件以 cwd 为作用域。影响权限允许规则的同一项单路径段作用域变更（请参阅权限规则语法）也适用于 hook 的 if: 条件：dir/** 之类的条件现在只匹配 <cwd>/dir，而不再匹配目录树中所有的 dir/。如需恢复任意深度匹配，请使用 **/dir/**。[^207]

Hook 输入/输出协议

Hooks 通过 stdin 接收 JSON：

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

Hook 事件增强（v2.1.69+）：从 subagent 或 --agent 会话触发时，所有 hook 事件现在都会包含 agent_id 和 agent_type 字段；状态栏 hook 命令还会包含 worktree 字段。¹¹⁰

Stop/SubagentStop hooks（v2.1.47+）会额外接收 last_assistant_message 字段，其中包含 Claude 的最终响应文本，因此 hooks 无需解析会话记录文件即可检查输出：

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

无需阻止即可提供柔性反馈（v2.1.163+）：Stop 和 SubagentStop hooks 可以在其 JSON 输出中返回 hookSpecificOutput.additionalContext，向 Claude 提供反馈并让当前轮次继续，同时不会将响应标记为 hook 错误。在此之前，Stop hook 唯一真正有效的手段是以退出码 2 阻止操作（这会被视为错误，并计入连续阻止次数上限）；additionalContext 则增加了一条引导通道，用于传达“您遗漏了这些内容，请继续”等指导，而不会干扰循环。[^183]

退出码控制行为： - 0：成功：操作继续。在详细模式（Ctrl+O）中显示 stdout。对于 UserPromptSubmit 和 SessionStart，stdout 会添加到上下文中。 - 2：阻止性错误：操作停止。Stderr 会作为错误消息反馈给 Claude。 - 1、3 等：非阻止性错误：操作继续。在详细模式中将 stderr 显示为警告。

若需高级控制，hooks 可以输出 JSON：

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

PreToolUse 决策控制（首选格式）：PreToolUse hooks 使用 hookSpecificOutput 实现更丰富的控制：支持三种结果（允许、拒绝、询问），还可以修改工具输入并注入上下文：⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

注意：对于 PreToolUse，顶层 decision 和 reason 字段已弃用。请改用 hookSpecificOutput.permissionDecision 和 hookSpecificOutput.permissionDecisionReason。其他事件（PostToolUse、Stop 等）仍使用顶层 decision。⁸⁹

UserPromptSubmit 会话标题（v2.1.94+）：UserPromptSubmit hooks 可以通过 hookSpecificOutput.sessionTitle 设置会话标题。¹⁴⁰

异步 Hooks（2026年1月）

Hooks 现在可以在后台运行，而不会阻塞 Claude Code 的执行。请在 hook 配置中添加 async: true：⁸¹

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

适合使用异步 hooks 的场景： - 不应拖慢会话的通知（Slack、电子邮件、Pushover） - 可在后台运行的日志记录和遥测 - 非关键的后处理（分析、备份）

不应使用异步 hooks 的场景： - 格式化（必须在下次编辑前完成） - 验证（失败时必须阻止操作） - 任何需要修改工具输入或输出的 hook

基于 Prompt 和 Agent 的 Hooks（v2.1.32+）

除了 shell command hooks（type: "command"）之外，Claude Code 还支持两种由 LLM 驱动的 hook 类型，它们使用 AI 推理而非脚本来评估条件。⁸⁹

Prompt hooks（type: "prompt"）会向快速 Claude 模型发送单轮提示。模型返回 { "ok": true } 表示允许，或返回 { "ok": false, "reason": "..." } 表示阻止：

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

HTTP hooks（type: "http"）会将事件的 JSON 输入作为 POST 请求发送到 URL，并接收返回的 JSON。它们适用于 webhooks、外部通知服务或基于 API 的验证（v2.1.63+）：¹⁰⁴

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

HTTP hooks 使用与 command hooks 相同的决策格式（返回包含 decision 和 reason 的 JSON）。启用沙箱时，请求会通过沙箱网络代理路由。SessionStart/Setup 事件不支持 HTTP hooks。

Agent hooks（type: "agent"）会启动具有工具访问权限（Read、Grep、Glob）的 subagent，以执行多轮验证。当检查工作需要查看实际文件或测试输出时，请使用这类 hooks：

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

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

MCP 工具 Hooks（v2.1.118+）

Hooks 现在可以通过 type: "mcp_tool" 直接调用 MCP 工具，无需再封装一个调用服务器的 Bash 子进程。¹⁵²

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

这与用户已经配置的 MCP 服务器相得益彰：凡是能从 /mcp 访问的工具，现在都可以由 hook 调用。

PostToolUse Hooks 中的 duration_ms（v2.1.119+）

PostToolUse 和 PostToolUseFailure hook 输入现在包含 duration_ms，即工具执行所用时间，不包括权限提示和 PreToolUse hooks。¹⁵²此字段适用于检测慢速工具、记录审计日志以及收集各工具的延迟指标：

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

所有工具均支持 updatedToolOutput（v2.1.121+）

在 v2.1.118 中，MCP Tool Hooks 可以通过 hookSpecificOutput.updatedToolOutput 替换工具输出。从 v2.1.121 起，同一字段适用于任何 PostToolUse hook，包括内置工具（Bash、Read、Edit、Glob、Grep 等）、subagent 工具以及 MCP 工具。适用场景包括：从任意工具输出中隐去敏感内容、为下游使用方规范化结构，以及在 agent 读取结果之前注入元数据。¹⁵⁴

Hook 环境变量

Hooks 可以访问用于解析路径的环境变量：⁸⁹

从 SessionStart 持久化环境变量：

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

HTTP hook 安全性（v2.1.51+）：在请求头中插入环境变量的 HTTP hooks 现在必须明确提供 allowedEnvVars 列表，以防止通过请求头值泄露任意环境变量。启用沙箱时，HTTP hooks 也会通过沙箱网络代理路由，从而强制执行域名允许列表。SessionStart/Setup 事件不支持 HTTP hooks。⁹⁸

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

Hook 工作区信任（v2.1.51+）：statusLine 和 fileSuggestion hook 命令现在必须先接受工作区信任，才能在交互模式下执行，从而消除一项潜在安全风险。⁹⁸

实用 Hook 示例

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

记录所有 bash 命令：

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

阻止访问敏感文件：

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

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

代码更改后运行测试：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}