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上下文，8月31日前享受$2/$10的推广价格；只需执行一次/model opus即可切换到Opus（从v2.1.219开始，该别名会启用Claude Opus 5）。v2.1.198（7月1日）让subagents默认在后台运行，推动Chrome版Claude正式发布，允许后台代理完成工作树代码后提交、推送并创建草稿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.223撤销了这一拆分：/review再次成为/code-review的别名，直接执行/code-review则会沿用上次的工作强度级别；v2.1.203–205（7月7日至9日）强化了自动模式——禁止篡改转录文件，对包含无法解析变量的rm -rf操作先行询问，并在后台任务通知中明确说明未发生人工输入（因此无法根据转录中伪造的批准执行操作）——同时将/doctor升级为完整的诊断与修复检查工具（别名为/checkup）。^181182183 v2.1.217（7月21日）改变了嵌套subagents的策略——subagents默认不再生成自己的subagents（3天后，v2.1.219又一次推翻了这一默认设置，恢复为最多3层；详见下文）；默认最多同时运行20个subagents（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS），而且达到上限后，--max-budget-usd现在确实会停止后台subagents。¹⁹⁴ v2.1.218（7月22日）将/code-review移至后台subagent运行——审查工作不再占用对话上下文——默认在后台运行使用context: fork的skills（可以在各skill中通过background: false选择退出），让/deep-research仅在显式调用时启动，将危险rm、后台&和可疑Windows路径检查交由自动模式分类器处理，而不再弹出权限对话框，并阻止代理frontmatter hooks从不受信任的文件夹运行。¹⁹⁵ v2.1.219（7月24日）将Claude Opus 5（claude-opus-5）设为默认Opus模型——支持1M上下文、最大128K输出，价格为每MTok $5/$25（与Opus 4.8相同），默认启用思考，effort默认为high，知识截止时间为2026年5月——同时纠正了早期版本中的两项调整：快速模式现在适用于Opus 5和Opus 4.8，价格为每MTok $10/$50（基础价格的2倍；Opus 4.7则完全退出快速模式），并且嵌套subagents默认再次启用，最多3层（设置CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1可禁用嵌套）。同一版本还新增了DirectoryAdded hook事件、sandbox.network.strictAllowlist设置、包含动态工作流的workflowSizeGuideline设置键（现在默认采用中等规模指引，建议少于15个代理），以及stream-json中的嵌套subagent转发功能。v2.1.220（7月25日）仅包含错误修复和可靠性改进。v2.1.221–226（8月4日至7日）新增跨会话消息传递（您的会话之间可使用SendMessage/ListAgents，支持macOS/Linux）、云端会话的自托管运行器（Team/Enterprise）、采用SHA-256固定版本的archive plugin源、支持JWT/SigV4的沙盒凭据屏蔽、VSCode Focus视图，以及让/fork副本拥有各自独立的工作树——同时移除了每个会话200个subagents的上限和ultraplan。^{199200201202196197198} 截至v2.1.174–176（2026年6月12日），新的enforceAvailableModels托管设置允许availableModels允许列表限制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日），subagents可以递归生成自己的subagents，最多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的完整工作强度范围，但无法禁用思考）；Opus 4.8仍是默认代理模型。截至v2.1.169（2026年6月8日），--safe-mode（以及CLAUDE_CODE_SAFE_MODE）可以启动禁用所有自定义项的干净会话，以便排查问题；/cd可以在不破坏提示词缓存的情况下将会话移至新的工作目录；disableBundledSkills则会对模型隐藏内置skills和斜杠命令。截至v2.1.166（2026年6月6日），fallbackModel设置可在主模型过载时依次切换至最多3个备用模型；通配符"*"可用于MCP拒绝规则；MAX_THINKING_TOKENS=0 / --thinking disabled能够彻底关闭默认启用思考的模型所具备的思考功能。截至v2.1.154（2026年5月28日），Opus 4.8成为新默认模型，默认使用高工作强度，并新增/effort xhigh级别；动态工作流通过/workflows在后台编排数十乃至数百个代理；Opus 4.8的快速模式以2倍标准价格提供2.5倍速度；除Haiku/Sonnet/Opus 4.7及更早版本外，精简系统提示词现已成为所有模型的默认选择；/simplify恢复为仅执行代码清理审查（与/code-review --fix分开）；claude agents支持通过! <command>生成后台shell会话；plugins可以声明defaultEnabled: false；流式工具执行始终启用；stdio MCP服务器会在环境变量中收到CLAUDE_CODE_SESSION_ID和CLAUDECODE=1。v2.1.153为plugin应用市场新增skipLfs，让/model保存为默认模型（按s则仅对当前会话生效），并将COLUMNS/LINES加入状态栏环境变量。v2.1.152引入/code-review --fix（将发现的问题修复至工作树）、skill frontmatter中的disallowed-tools、/reload-skills、新的MessageDisplay hook事件、SessionStart hook的reloadSkills/sessionTitle输出、pluginSuggestionMarketplaces托管设置，以及会话中途切换--fallback-model的能力，同时移除了自动模式的选择启用机制。^{162 163 164 165 166 167 168 169 170 211 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搜索特定标志、命令或配置键。文末的快速参考卡汇总了所有主要命令，便于快速浏览。

相关深度解析

以下博客文章深入探讨了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内存，并需要稳定的互联网连接。⁹² 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 中的 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 也会出现在转发流中。每个 subagent 都以生成它的 Agent 调用的 tool_use id 作为键，因此管道能够重建委派树，而不再只能看到扁平的文本列表。这与同一版本恢复默认支持深度为 3 的嵌套生成直接配套：若无此功能，3 个层级中会有 2 个不可见。¹⁹⁶

退出代码：

控制 -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 延续。¹⁸⁹ 从 v2.1.214 开始，以分支形式启动的会话会将 SessionStart hook 来源报告为 "fork"（此前为 "resume"），因此按来源匹配的 hooks 能够区分二者。¹⁹⁰ v2.1.216 将 /fork 确认信息精简为一行，其中显示新会话的名称及其 claude attach id。¹⁹² 从 v2.1.221 开始，分支会话会创建自己的 worktree，而不再使用原会话的检出目录。因此，派去探索替代方案的分支不会再与主会话中尚未提交的文件发生冲突，消除了复制会话进行实验时的一大隐患。¹⁹⁹

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 在官方文档新增的无障碍页面中介绍了该模式及其交互方式。¹⁸⁶

配置系统深度解析

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 UI；该命令适用于交互模式、-p和远程控制会话。/config --help（v2.1.183）会列出可用的简写键。v2.1.183还调整了交互式/config UI：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": "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"
  },
  "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可在模型和斜杠命令选择器中隐藏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模式）。¹⁸⁶
• axScreenReader（v2.1.208）：持久启用屏幕阅读器模式（请参阅屏幕阅读器模式）。¹⁸⁶
• processWrapper（v2.1.208）：让Claude Code为自身启动的每个进程都通过包装器可执行文件运行——专为企业启动器设计（请参阅企业部署）。¹⁸⁶
• autoMode来源限制（v2.1.207）：不再从代码仓库的.claude/settings.local.json读取autoMode设置，请改在~/.claude/settings.json中配置。此举堵住了克隆的代码仓库携带自动模式配置的途径。¹⁸⁵

较新的设置（v2.1.217）：

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

较新的设置（v2.1.219）：

• sandbox.network.strictAllowlist（v2.1.219）：对于沙箱命令访问不在允许列表中的主机，直接拒绝且不发出提示，不再弹出权限对话框。请参阅沙箱模式。¹⁹⁶
• workflowSizeGuideline（v2.1.219）：可从任意设置文件（用户、项目或托管设置）设定建议性的Dynamic工作流规模准则，而不再只能通过/config配置。Dynamic工作流默认采用中等准则（“目标是少于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-5      # What the `opus` alias resolves to (Opus 5 since v2.1.219)
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 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_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

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
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               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
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_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属性：现在，LLM请求span会发出stop_reason、gen_ai.response.finish_reasons和user_system_prompt。由于user_system_prompt可能包含个人身份信息（PII），仅在设置OTEL_LOG_USER_PROMPTS=1后才会发出。¹⁵⁴

v2.1.122+事件级变更：api_request和api_error日志事件中的数值属性现在以数字而非字符串形式发出，修复了下游OTel收集器对schema进行严格类型检查时的问题。当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截断上限。¹⁹⁰

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 仍然是总输出的硬性上限——包括思考内容和响应文本。因此，对于此前无需思考即可运行的任何工作负载，都应重新检查 token 余量。传递 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（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 参数。²⁰⁵

具体到 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（默认使用 high 强度，最困难的任务可使用 /effort xhigh）；自 v2.1.197 起，Sonnet 5 一直是开箱即用的默认模型。如果追求能力上限，请有意识地通过 /model fable 选择 Fable 5。²⁰⁵¹⁹⁷

Opus 4.7（2026年4月16日）：上一代旗舰模型，目前仍可正常使用。1M token 上下文窗口采用标准定价，没有长上下文溢价。最大输出为 128K，仅支持自适应思考（已移除扩展思考），并新增 xhigh 强度等级，建议将其作为编码和智能体工作负载的起点。¹⁴⁵可靠知识截止日期：2026年1月。训练数据截止日期：2026年1月。模型 ID：claude-opus-4-7。定价与 Opus 4.6 相同，输入/输出价格为每 MTok $5/$25；5 分钟缓存写入为 $6.25，1 小时缓存写入为 $10，缓存读取为每 MTok $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向模型提供贯穿完整智能体循环的token目标；最低为20K tokens。¹⁴⁵

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时，默认effort为high（此前为medium）；Opus 4.7仍为xhigh。这一调整恢复了模型智能，此前3月4日至4月7日的effort降级已记录在4月23日的事后分析中。¹⁵²¹⁵³

Sonnet 5（2026年6月30日）：当前的Sonnet层级，定位为“速度与智能的最佳结合”。Anthropic称其性能接近Opus 4.8，但价格更低。与Sonnet 4.6相比，它在智能体推理、工具使用、编程和知识工作方面均有显著提升，同时不良行为的总体发生率更低，网络安全能力则远弱于Opus模型（正是这一安全权衡使其得以在不受出口管制限制的情况下发布）。模型ID：claude-sonnet-5（无日期的固定快照）。1M token上下文窗口，128K最大输出（在Batches API中配合output-300k-2026-03-24 beta标头时最高可达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的同时，提升了智能体搜索性能。支持扩展思考、自适应思考以及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输入tokens和10K-50K输出tokens。使用Haiku时，每次会话的成本为0.10-0.45美元。使用Opus时，同一会话的成本为0.50-2.25美元，高出5倍。仅将Opus用于真正棘手的问题。¹

各模型的适用场景

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

Sonnet：注重成本时，日常开发的主力模型。能够处理大多数编程任务：实现功能、修复错误、编写测试和代码审查。与Sonnet 4.5相比，Sonnet 4.6提供更强的智能体搜索能力和更高的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：深度推理层级——自v2.1.219起，opus别名会选择Claude Opus 5（输入/输出每MTok分别为5美元/25美元、1M上下文，effort默认为high）。¹⁹⁷ 下段描述的是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，可通过/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标志（此前仅用于会话中途切换）现在也会从启动时起应用于交互式会话。²⁰⁷

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

当API返回意外且不可重试的错误时，Claude Code现在还会先使用备用模型重试该轮一次，然后才显示失败。因此，短暂的主模型故障可以平稳降级，而不会直接丢弃该轮。²⁰⁷

自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 tokens的请求与包含9K tokens的请求采用相同的每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。自v2.1.223起，该变量的作用范围有所调整：它会通过自动压缩，将所有原生窗口为1M的模型限制在200K，而不再局限于固定的已知变体列表；如果自动压缩实际上未能将会话限制在200K，启动时还会显示警告。如果您为了确保某个模型系列的成本可预测性而设置此变量，那么新1M模型发布当日便会自动受其约束，不会悄然失效。同一版本还会让自动压缩将使用无法识别的模型ID的会话保持在推定的上下文窗口内，而不会任其超出该窗口；对于注册了自定义ID且实际窗口更大的网关，可设置CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1恢复原有行为。²⁰⁰

检查当前模型

> /status

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

模型选择器标签（v2.1.51+）：对于固定版本，/model选择器现在会显示易于理解的标签（例如“Sonnet 4.6”），而非原始模型ID；如有更新版本，还会显示升级提示。⁹⁸ v2.1.219修复了合并后的Opus行，使其显示为普通的“Opus”，而非“Opus（1M上下文）”；同时将新版本高亮范围缩小到最新模型的名称，确保高亮准确标示实际发布的内容，而不是列表中随意截取的一部分。¹⁹⁶

快速模式（v2.1.36+）

快速模式可让同一模型显著加快输出；它不会切换到成本更低的模型。可在会话期间使用/fast切换。⁸⁶

> /fast            # Toggle fast mode on/off

支持的模型（截至v2.1.219）：快速模式适用于Claude Opus 5和Claude Opus 4.8。v2.1.219取消了Opus 4.7的快速模式支持，而Sonnet、Haiku和Fable从未支持此功能。它仍然只在Claude API（包括Claude Managed Agents）中作为研究预览版提供，不适用于Amazon Bedrock、Google Cloud、Microsoft Foundry或AWS上的Claude Platform。访问权限受限：请联系您的客户经理或加入候补名单。¹⁹⁶¹⁹⁸

定价（Opus 5／Opus 4.8快速模式）：¹⁹⁸

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

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

不应使用快速模式的场景： - 长时间运行的agentic任务（整个运行过程的成本仍会翻倍） - 后台subagent工作（无人等待输出） - 注重预算的会话

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

运行说明。快速模式拥有独立于标准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

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

Opus 4.7引入了新的工作量调节选项，可调整速度与智能之间的取舍。在会话期间使用/effort：

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

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

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

保留默认规则的同时添加自定义规则（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+）。自动模式的选择启用提示现在提供“不再询问”选项，常用用户无需编写标志脚本即可隐藏说明。¹⁵² 破坏性命令防护规则（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，系统会先征求确认，从而防止 rm -rf $DIR 中 $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）。 过去有3项检查会通过权限对话框中断自动模式：危险的 rm、后台 & 和可疑的 Windows 路径。现在这些检查不再弹出对话框，而是交由自动模式分类器裁决。因此，安全审查照常进行，同时不必每次命中都让您介入。同一版本还将此机制扩展到搭配自动模式的计划模式：静态分析器无法确认只读的 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，建议升级。

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五小时速率限制提高了一倍，取消了 Pro 和 Max 账户的高峰时段额度缩减，并“大幅”提高了Claude Opus 模型的API速率限制。其算力保障来自 SpaceX Colossus 1 协议：“当月内新增超过300兆瓦的算力（超过220,000块 NVIDIA GPU）。”¹⁵⁷

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

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

1M 上下文定价（2026年4月）：Opus 4.7、Opus 4.6、Sonnet 4.6 和 Mythos Preview 均以每百万 token 的标准费率提供1M 上下文，不收取长上下文溢价。¹⁴⁸这是近期统一调整后的结果；此前关于 Opus 4.6 或 Sonnet 4.6 在输入 token 超过200K后，输入费用按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 计费外，部分工具还会产生单独费用：⁹

这些费用在代理循环中会积少成多。一次包含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，并停止正在运行的后台代理（此前后台代理不受预算限制）¹⁹⁴
5. 使用计划模式进行探索：不执行操作，就不会意外触发高成本操作
6. 主动压缩：上下文越小，token 越少
7. 限制输出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 对非紧急工作使用批量API：输入和输出 token 均享受五折优惠

监控使用情况

• 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 (high effort default; /effort xhigh for harder)
                  │         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

经验法则：在Anthropic API端，Sonnet 5始终是默认模型（v2.1.197+）；使用/model opus可升级至Opus 5。¹⁸¹¹⁹⁷ 对于subagents，可降级使用Haiku。当Sonnet的回答流于表面时，则升级至Opus。使用agent teams（v2.1.32+）时，Opus可协调多个agents并行处理不同的子任务。⁷⁹

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.

何时使用Extended Thinking？

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

应该使用哪种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用于切换当前会话的fast mode。它仍使用同一模型——截至v2.1.219，fast mode仅支持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工具直接终止会话。这是一项抵御滥用并保护模型福祉的措施，而非工作流功能——正常的开发会话不会触发它。¹⁹⁰¹⁹³

权限模式

自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/的写入保护采用相同的威胁模型，只是范围扩展到了更广泛的“编辑即执行”文件。²⁰⁹

Auto Mode（v2.1.85+）：这是比--dangerously-skip-permissions更安全的替代方案。独立的分类器模型——自v2.1.210起为Claude Sonnet 5（最初为Sonnet 4.6）——会在执行前审查每项操作，确认其符合用户意图且安全无虞。¹²⁴¹⁸⁷

工作原理： - 自动批准只读操作和对工作目录内文件的编辑 - 优先解析自定义允许/拒绝规则 - 其他所有操作均交由分类器评估 - 如果操作被阻止，Claude会自动尝试其他方案

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

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

# Enable at startup
claude --permission-mode auto

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

Auto mode自v2.1.152起不再需要选择启用，并且自v2.1.207起可在Bedrock、Vertex和Foundry上运行，无需设置环境变量标志。²¹¹¹⁸⁵

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:条件在此版本中也采用了相同的cwd作用域规则（请参阅匹配器）。¹⁹⁰

请使用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）。请迁移所有旧规则，以消除警告并明确表达意图。¹⁸⁷

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

MCP工具模式：

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

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

自v2.1.166起，拒绝规则也允许在工具名称位置使用glob：在工具名称位置单独使用"*"即可拒绝所有工具，从而先阻止一切，再仅放行少量指定工具。相比之下，允许规则会拒绝非MCP的glob——无法以同样方式广泛允许所有工具，因而保持了严格受限的默认安全策略。²⁰⁷

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

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

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

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

自v2.1.186起，这些Agent(...)规则也适用于按名称生成subagent：当通过工作流、--agents或agent team启动特定命名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

也可以在设置中配置：

{
  "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设置会阻止sandbox中的命令读取凭据文件和机密环境变量，为防止此类命令窃取机密信息提供纵深防御。¹⁷⁶

自v2.1.221起，凭据文件除了允许和拒绝之外，又增加了第三种模式：mode: "mask"（Linux和WSL）。当sandbox中的命令读取该文件时，它会获得一个哨兵副本——可以是整个文件，也可以只是由extract正则表达式捕获的片段——随后sandbox代理会在出站时替换为真实值。命令仍能正常运行（可通过代理完成身份验证），但机密信息绝不会出现在其环境中。这正是防范提示词注入命令搜寻令牌时所需的特性。在macOS上，由于代理替换机制不可用，mask会回退至deny。因此，为Linux CI编写的配置会以安全方式降级，而不会在不知不觉中暴露文件。¹⁹⁹

v2.1.224将掩码功能扩展到静态文件内容之外。extract和onExtractNoMatch可处理结构化环境变量值；搭配maskClaims使用decode: "jwt"时，可以只遮蔽JWT中的指定声明，而非整个令牌。这样，命令仍可读取令牌的路由元数据，同时敏感声明会保持为哨兵值；awsPairs/sigv4则会在代理处重新签署AWS SigV4请求，这是掩码功能能够与AWS CLI配合使用的关键——否则，经过掩码处理的密钥将无法通过签名验证。所有这些功能都要求启用network.tlsTerminate，并且仅接受来自用户、托管或--settings作用域的配置——仓库无法附带一份掩码配置，在您不知情的情况下重新路由凭据。²⁰¹

自v2.1.216起，sandbox.filesystem.disabled设置可以跳过文件系统隔离，同时保留网络出口控制。当文件系统隔离环境导致构建工具无法正常运行，但仍希望对出站流量强制实施域名允许列表时，此设置十分有用。¹⁹²

自v2.1.219起，sandbox.network.strictAllowlist设置会直接拒绝未列入允许列表的主机，而不发出提示。默认情况下，当sandbox中的命令访问allowedDomains以外的主机时，会触发权限提示；启用strictAllowlist后，连接将直接被拒绝。对于无人值守的运行场景——CI、后台agent、夜间循环——应当采用此设置，因为无人响应的提示只会导致任务停滞，而且“遇到异常出站请求时询问我”本就不是合适的策略。至此，网络控制的三项机制完整到位：allowedDomains规定允许访问的目标，deniedDomains（见下文）从宽泛的允许规则中排除例外，而strictAllowlist决定其他所有请求是询问还是失败。¹⁹⁶

在sandbox中： - 文件系统访问限制在项目目录内 - 网络访问受到控制 - 某些命令不受sandbox限制 - 如果autoAllowBashIfSandboxed为true，则自动允许Bash命令

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

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

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

嵌套.claude/解析（v2.1.178）：当您处理某个目录下的文件时，嵌套.claude/skills目录中的skills现在会自动加载，而不再仅从仓库根目录加载；如有重名，嵌套skill可通过<dir>:<name>访问，因此两者均可继续使用。项目中的其他部分也采用相同的解析方式——如果agent、工作流或输出样式名称在嵌套.claude/目录间发生冲突，则以距离工作目录最近的定义为准；保存项目作用域的工作流时，目标也是最近的现有.claude/workflows/。对于monorepo或仓库嵌套仓库的项目结构，这使每个软件包都能拥有按上下文激活的专属工具，而不必共用单一、扁平的全局工具界面。¹⁷³

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

v2.1.113中的安全强化：¹⁵⁰

• sandbox.network.deniedDomains可阻止特定主机，即使范围更广的allowedDomains通配符原本允许访问它们。利用阻止列表，无需重写整个允许策略，即可切断对文本粘贴站点、文件投递站点或已知恶意主机的访问。如果希望允许列表之外的所有目标都被静默拒绝而不是触发提示，请将其与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中的权限默认拒绝强化：¹⁹⁰

此版本集中修复了一批权限检查漏洞，并统一采用默认拒绝原则——分析器无法确定安全性时，就会发出提示：

• 修复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 都能保证执行。它们对于落实团队标准和自动化重复任务至关重要。有关涵盖命令、提示和 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"。¹⁹⁰

Hook 配置

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

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

匹配器

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

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

使用 | 匹配多个工具（Edit|Write）。自 v2.1.191 起，逗号分隔的匹配器（例如 Bash,PowerShell）也能正确触发——早期版本会将其静默丢弃，导致使用逗号匹配器的 hook 从不运行。¹⁷⁸ 自 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/**。¹⁹⁰

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 新增了一条引导通道，可用于给出“您遗漏了这些内容，请继续”的指导，同时避免与循环机制相互冲突。²⁰⁸

退出代码控制行为： - 0：成功：操作继续。stdout 会在详细模式（Ctrl+O）下显示。对于 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

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

除 shell 命令 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。这些 hooks 适用于 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 使用与命令 hooks 相同的决策格式（返回包含 decision 和 reason 的 JSON）。启用沙箱后，请求会通过沙箱网络代理路由。SessionStart/Setup 事件不支持此类 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
INPUT=$(cat)
DUR=$(jq -r '.duration_ms' <<<"$INPUT")
FILE=$(jq -r '.tool_input.file_path // "?"' <<<"$INPUT")
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $FILE" >&2
fi

适用于所有工具的 updatedToolOutput（v2.1.121+）

在 v2.1.118 中，MCP 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 也会通过沙箱网络代理路由，从而强制执行域名允许列表。HTTP hooks 不支持 SessionStart/Setup 事件。⁹⁸

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