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

简而言之：Claude Code是一种代理式CLI，通过分层的权限、hooks、MCP集成和subagents系统读取代码库、执行命令并修改文件。掌握5个核心系统（配置、权限、hooks、MCP和subagents），即可实现事半功倍的生产力提升。为每项任务选择合适的模型层级——复杂推理使用Opus，常规工作使用Sonnet，快速探索使用Haiku；如果质量是唯一考量，也可以统一使用Opus。凡是必须始终执行的操作，都应使用hooks，而不是提示词。自2026年8月14日起，Auto模式已成为Pro、Max和Team新会话的默认权限模式（8月7日宣布，并于切换当日在线验证；自主操作由分类器审查——除非接受一次性切换提示，否则自行设置的defaultMode会继续生效；按Shift+Tab可切换任意会话；disableAutoMode可在整个组织范围内禁用该模式）。²⁰³ 默认模型取决于您的套餐：Max、Team Premium、Enterprise（自v2.1.251起按席位计算）以及Anthropic API默认使用Claude Opus 5，而Pro和Team Standard默认使用Sonnet 5——原生支持1M上下文，标准目录价为每百万Token 2/10美元（发布时的优惠价格现已永久保留：原定于9月1日的涨价不会实施）²²⁸²⁰⁷——v2.1.197中Sonnet 5全面成为默认模型（2026年6月30日）已成为历史；opus别名现在指向Claude Opus 5（v2.1.219及更高版本）。v2.1.198（7月1日）使subagents默认在后台运行，推动Chrome中的Claude正式发布，允许后台代理在完成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作为别名），并且默认不再让AskUserQuestion对话框自动继续；v2.1.202（7月6日）新增“动态工作流大小”/config控件，并将/review <pr>（快速单次审查）与/code-review <level> <pr#>分开——v2.1.223撤销了这项拆分：/review再次成为/code-review的别名，不带参数的/code-review会沿用上次的工作量级别；v2.1.203–205（7月7日至9日）强化了Auto模式——阻止篡改会话记录文件，对无法解析变量的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路径检查交由Auto模式分类器处理，而不是弹出权限对话框，并阻止代理frontmatter中的hooks在不受信任的文件夹中运行。¹⁹⁵ v2.1.219（7月24日）将Claude Opus 5（claude-opus-5）设为默认Opus模型——支持1M上下文、128K最大输出，每百万Token 5/25美元（与Opus 4.8相同），默认开启思考，effort默认为high，知识截止日期为2026年5月——并纠正了早期版本造成的两项事实：快速模式现在适用于Opus 5和Opus 4.8，每百万Token 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日）新增跨会话消息传递（macOS/Linux上通过SendMessage/ListAgents在不同会话间通信）、云会话的自托管运行器（Team/Enterprise）、支持SHA-256固定的archive plugin源、支持JWT/SigV4的沙箱凭据遮蔽、VSCode Focus视图、让/fork副本拥有各自的worktree，并移除了每个会话200个subagents的上限和ultraplan。^{199200201202196197198} v2.1.227–229（8月10日至12日）以修复为主，同时加入了一系列易用性改进：plugin市场新增command源（本地程序输出plugin目录，每个会话都会重新解析；mode: "link"会直接使用该目录），claude remote-control --continue可恢复最近的Remote Control会话，ListAgents会将断开连接的Remote Control对等端标记为offline，将云会话标记为cloud，/commit-push-pr不再自动批准危险的git标志（--force、--amend、--no-verify），Write工具在较新模型上采用与Edit相同的规则——覆盖本会话中尚未读取的文件，不再要求事先读取。^235233234 v2.1.232（8月13日）将subagent分叉设为默认行为（subagent_type: "fork"继承完整对话和提示缓存；交互式会话中的非队友生成操作会在后台运行），允许在提示词中通过@提及另一个正在运行的会话名称（Claude通过SendMessage路由消息；如果不带引用的名称只与一个活动会话完全匹配，现在无需确认引用即可送达），确保每台机器上的交互式会话名称唯一（采用name-word-word变体），将跨会话入站控制项显示为/config行，并实现GitLab功能对等——在沙箱中遮蔽9类GitLab Token，为glab CLI提供凭据保护，并使纯gitlab.com市场URL（包括嵌套子组）的克隆方式与GitHub一致。²³² v2.1.233（8月14日）将GitLab功能对等扩展至--worktree（MR URL在claude agents中显示为!N），为Bash命令增加Linux内存限制（CLAUDE_CODE_TOOL_MEMORY_LIMIT）和WebFetch缓存TTL调节项，并且默认关闭Opus 4.8、Sonnet 5、Fable 5及更新模型上的待办事项/任务跟踪工具（设置CLAUDE_CODE_ENABLE_TODO_TOOLS=1可恢复）——它还因Auto模式回归问题，撤销了v2.1.232中的部分Windows Bash权限更改。²³¹ v2.1.234（8月17日）使Claude Code能够在claude.ai使用限额重置后自动继续会话（可在/config中关闭：“达到使用限额时自动继续”），允许在轮次中途打开/permissions和/add-dir，新增CLAUDE_CODE_PROJECT_DIR_NAME以及/goal后台任务检查机制（CLAUDE_CODE_GOAL_CHECKIN_MINUTES），在已通过glab CLI认证的仓库页脚显示GitLab MR徽章（!N），并通过按需加载参考文档，将内置claude-api skill的上下文成本从约200k Token降至约25k Token。²³⁰ v2.1.235–238（8月18日至20日）新增内置“简洁”输出风格（结果优先，不使用开场白或过程叙述——可在/config的“输出风格”下选择）、ANTHROPIC_DEFAULT_MODEL环境变量（设置新会话的起始模型；与ANTHROPIC_MODEL不同，通过/model选择的模型仍会覆盖它并持久保存）、可选的spellcheck设置（通过已安装的aspell、hunspell或ispell为提示词中的拼写错误添加下划线）、keybindingFlavor设置（"readline"会像Bash一样，让Ctrl+W删除到前一个空白处；该设置已在v2.1.261中移除——readline现在是唯一行为）、plugin市场和项目.mcp.json中的headersHelper（由命令生成短期HTTP标头；目录条目辅助程序只会在安装/更新时运行，并会先显示其命令；项目/plugin/代理作用域的辅助程序则在文件夹信任对话框之后运行，且不会继承凭据环境变量）、跨会话SendMessage的notify_when_idle（另一项本地会话下次进入空闲状态时发出一次性通知），以及两项权限行为变更：Auto模式现在会将Monitor允许规则暂时搁置（Monitor命令与Bash一样接受分类器审查）；macOS沙箱通配符读取拒绝规则（**/.env）在允许读取区域内具有更高优先级，且无法通过重命名被拒绝的文件来绕过——Auto模式分类器现在还会在Bedrock、Vertex AI和Foundry上以及遥测关闭时使用Claude API默认值²²³（自v2.1.273起，这些网关“暂时”默认使用本地分类器——设置CLAUDE_CODE_AUTO_MODE_SERVER=1可选择使用平台的服务器端分类器²¹⁷）。v2.1.239（8月21日）新增/claude-api upgrade（将Python项目从anthropic 0.x迁移至1.x），将仅限美国推理的数据驻留工作区1.1倍溢价计入成本估算（/cost、状态行和--max-budget-usd），把跨会话消息传递引入Windows，将从claude.ai同步的plugins显示为name@synced（可通过claude plugin enable/disable管理，且绝不会覆盖同名的本地安装），让ListAgents显示会话自身名称和在线队友，将"readline"扩展至Bash单词级按键操作，降低/goal检查频率（30分钟→1小时→2小时），并在Bedrock/Vertex/Foundry上提供全屏渲染器；v2.1.240–241（8月22日至23日）为错误修复版本。同周的文档摘要标记了两项状态变化：/design——一项研究预览版skill，通过artifacts发布包含可编辑UI画板的画布（适用于Pro/Max/Team/Enterprise，需要v2.1.233及更高版本）——以及Remote Control退出研究预览阶段；运行claude remote-control的机器会在Claude应用中显示为设备卡片。²⁰⁵ 自v2.1.174–176（2026年6月12日）起，availableModels允许列表现在可以通过新的enforceAvailableModels托管设置约束默认模型（用户/项目设置无法扩展托管列表），会话标题会以对话使用的语言生成（可通过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的完整工作量范围，但无法关闭思考）；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个备用模型，glob "*"可用于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的能力，并移除了Auto模式的选择加入机制。^{162 163 164 165 166 167 168 169 170} [^180] ¹⁷¹

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？。本指南会随每个版本维护最新版本的验证依据；当前验证日期请参阅更新日志的最新一行。[^180]

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

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

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

核心层：您的主对话。每条消息、每次文件读取和每项工具输出都会占用共享窗口中的上下文（标准为200K tokens⁹¹；使用Opus 4.6或扩展上下文模型时为1M tokens）。上下文填满后，Claude会逐渐遗忘先前的决策，输出质量也会随之下降。此层按token产生费用。

委派层：Subagents使用全新的上下文启动，专注完成特定工作，然后返回摘要。探索结果不会让主对话变得臃肿，只有结论会返回。探索任务可交由成本较低的模型层级处理；如果质量比成本更重要，也可以始终使用主模型。

扩展层：MCP用于连接外部服务（数据库、GitHub、Sentry）。无论模型行为如何，hooks都能确保shell命令得到执行。Skills封装领域专业知识，供Claude自动应用。Plugins则将这些能力打包分发。

关键洞见：大多数用户完全在核心层中工作，只能眼看上下文日益膨胀、成本不断攀升。熟练用户会将探索和专业任务交给委派层，根据自身工作流配置扩展层，并仅使用核心层进行统筹协调和最终决策。

目录

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

如何安装 Claude Code？

系统要求

Claude Code 可在 macOS 13+、Ubuntu 20.04+/Debian 10+ 和 Windows 10+（原生环境或 WSL）上运行。系统最低需要 4 GB 内存和有效的互联网连接。⁹² 使用 Bash、Zsh 或 Fish 可获得最佳 Shell 兼容性。

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

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

平台支持矩阵

安装、更新和卸载速览

便于快速查阅——在一个屏幕中查看所有方法、命令和版本检查方式。以下小节将介绍各种方法的具体细节和故障排除方式。

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

安装方法

原生安装（推荐）

原生二进制文件无需依赖 Node.js，可提供最简洁的使用体验：

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

# Homebrew alternative
brew install --cask claude-code

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

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

如需安装特定版本：

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

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

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

NPM 安装（已弃用）

注意： 从 v2.1.15 开始，通过 npm 安装时会显示弃用通知。现在推荐使用原生二进制文件进行安装。请使用 claude install 完成迁移。

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

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

切勿使用 sudo 安装 npm 软件包。这会引发权限问题，令后续操作错综复杂。

从现有安装迁移

如果已有基于 npm 的旧版安装，请迁移到原生二进制文件：

claude install

身份验证选项

Claude Code 支持 3 种身份验证方式，各有不同的取舍：

Claude Console（API 计费）

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

Claude Pro 或 Max 订阅

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

企业平台

AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 均可利用现有的云计费关系提供企业级访问权限。Bedrock 设置向导（v2.1.92+）： 登录屏幕上的交互式向导将引导您完成 AWS 身份验证、区域选择、凭据验证和模型固定。¹³⁷ Vertex AI 设置向导（v2.1.98+）： Google Cloud 也提供相应的向导，引导您完成 GCP 身份验证、项目与区域配置、凭据验证和模型固定。¹⁴² Vertex AI mTLS 工作负载身份联合（v2.1.121+）： Vertex AI 现在支持基于 X.509 证书的工作负载身份联合（mTLS 应用默认凭据）——通过客户端证书签发短期 GCP 令牌，无需服务账户 JSON。¹⁵⁴ 操作系统 CA 证书信任（v2.1.101+）： 企业 TLS 代理现在默认可用——Claude Code 会信任操作系统证书存储。设置 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

网关提示标头（v2.1.273，需选择启用）： 设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 后，Claude Code 会添加 5 个请求标头，供 LLM 网关进行路由和观测——x-claude-code-request-class、x-claude-code-agent-type、x-claude-code-prev-tool-durations、x-claude-code-compaction 和 x-claude-code-context-compacted。²¹⁷

验证

claude doctor

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

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

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

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

从 v2.1.268 起，claude auth status --json 会包含 configDirectory，即 CLI 实际读取的配置目录。当 CLAUDE_CONFIG_DIR 间接指定目录而导致位置不明确时，此字段尤为实用。²¹⁶

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

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

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 个不可见。¹⁹⁶

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

退出代码：

控制 -p 模式下的智能体行为：

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

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

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

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

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

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

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

受限模式（v2.1.248+）：--restricted（或 CLAUDE_CODE_RESTRICTED=1）专为在共享计算机上驱动 claude 的评估运行框架而设计。它会移除用于运行命令或代码的内置工具以及 WebFetch，除非您在 --tools 中逐一指定它们——default 预设不算；将内置文件工具的访问范围限制在工作目录内；仅加载托管设置和 --settings（忽略用户、项目和本地设置文件）；拒绝 bypassPermissions；并拒绝创建云会话。²⁰⁶²⁰⁹

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

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

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

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"

使用 /cd 移动正在运行的会话（v2.1.169+；自 v2.1.246 起配置立即生效）：/cd path 可以更改工作目录，而不会破坏提示词缓存。从 v2.1.246 开始，新目录中的项目设置、hooks、.mcp.json 服务器（仍需经过常规批准提示）、skills 和 agents 会在移动后立即生效，无需等待 --resume。²³⁹²²⁶

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

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

如果您在会话期间通过 gh pr create 创建 PR，会话也会自动与其关联，便于日后继续处理特定 PR。通过 prUrlTemplate 设置（v2.1.119+），页脚中的 PR 徽章可以指向自定义代码审查 URL；如果您的团队会从 PR 跳转到独立的审查工具，此功能会很实用。¹⁵²

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

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

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

# Name current session
> /rename auth-refactor

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

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

注意：--session-id 要求使用有效的 UUID（例如 550e8400-e29b-41d4-a716-446655440000）。如需使用人类可读的会话名称，请改用 /rename 和 --resume。

/fork 会生成后台会话；/subtask 则用于会话内分叉（v2.1.212）。现在，/fork 命令会将当前对话复制到一个新的后台会话中——该会话会在 claude agents 中拥有自己的条目。因此，您可以让副本探索另一种方案，同时主会话继续运行。原来的行为——在当前会话内分叉——则以新名称 /subtask 保留下来。¹⁸⁹ 从 v2.1.214 开始，以分叉方式启动的会话会将 SessionStart hook 来源报告为 "fork"（此前为 "resume"），让按来源匹配的 hooks 能够区分二者。¹⁹⁰ v2.1.216 将 /fork 的确认信息精简为一行，其中显示新会话的名称及其 claude attach id。¹⁹² 从 v2.1.221 开始，分叉会话会创建自己的 worktree，不再使用原会话的检出目录。这样一来，探索替代方案的分叉就不会再与主会话中未提交的文件发生冲突，消除了发送副本进行实验时的一大隐患。¹⁹⁹ v2.1.232 也将分叉设为 subagents 的默认行为：subagent_type: "fork" subagent 会继承完整对话和提示词缓存；在交互式会话中生成的非队友 agent，现在默认在后台运行。²³²

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

Plan 模式

Plan 模式会将 Claude 限制为只读探索——不得编辑文件、执行 bash 或进行破坏性操作。Claude 会设计实施方案，将其写入计划文件，并等待您的批准后再执行任何操作。

进入 Plan 模式：

# 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 进入 Plan 模式（复杂任务会自动进入，也可通过 Shift+Tab 进入）
2. 使用只读工具探索代码库：Read、Glob、Grep、WebSearch、WebFetch
3. 将计划写入 .claude/plans/{session-slug}.md
4. 使用 ExitPlanMode 退出 Plan 模式，并提交计划供您审查
5. 您可以批准、要求修改或拒绝计划

Plan 模式下可用的工具：Read、Glob、Grep、LS、WebSearch、WebFetch、AskUserQuestion。编辑工具（Edit、Write、Bash、NotebookEdit）均被禁用。

计划获批后（v2.1.32+）：Claude 会提供3个选项： - “是，清除上下文并自动接受编辑”（Shift+Tab）——使用完整的全新上下文开始执行计划 - “是，并手动批准编辑”——保留上下文，由您批准每项更改 - “是，自动接受编辑”——保留上下文，Claude 执行时无需逐项批准编辑

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

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

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

屏幕阅读器模式（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 采用分层配置系统。理解其层级结构至关重要，因为较高层级会覆盖较低层级，而企业设置完全无法绕过。

配置层级

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

从 v2.1.181 开始，/config key=value 可直接在提示中设置任意配置项，例如 /config thinking=false，无需打开交互式 /config UI；该命令适用于交互模式、-p 和 Remote Control 会话。/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-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-5",
    "vertex": "claude-opus-5",
    "foundry": "claude-opus-4-8"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

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

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

• availableModels / enforceAvailableModels（托管，v2.1.175+）：availableModels 允许列表会限制会话可选择的模型。启用 enforceAvailableModels: true 后，该允许列表还会约束 Default 模型——如果 Default 最终解析为不允许的模型，则回退到第一个允许的模型；用户或项目设置也无法再扩展托管的 availableModels 列表。配套修复（v2.1.176）堵住了别名选择通过 ANTHROPIC_DEFAULT_*_MODEL 重定向到被阻止模型的漏洞；现在，若目标模型不在允许列表中，/fast 也会拒绝切换。¹⁷² 从 v2.1.187 开始，组织可以直接对 /model 选择器、--model、/model 和 ANTHROPIC_MODEL 全面实施模型限制——选择受限模型时，会显示“受您组织的设置限制”的消息。¹⁷⁶
• 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 个 agent”）；当设置文件提供该值时，/config 中的对应行会自动隐藏。这只是建议，并非强制上限。请参阅Subagents。¹⁹⁶

较新的设置（v2.1.242–243）：

• modelPicker（用户或托管，v2.1.242+）：使用按顺序排列且带标签的模型列表定制 /model 选择器。其值是一个包含 options 数组的对象（每一行都必须包含 model，还可包含可选的 label 和 description；model 会按原样采用，因此别名、Anthropic ID，以及 Bedrock/Vertex/Foundry/网关 ID 均可使用），并可包含可选的 replaceBuiltInOptions 布尔值（默认值为 false，会将这些行追加到内置模型阵容之后；设为 true 时，则只显示您定义的行、Default，以及会话当前正在运行的模型）。Claude Code 会从托管设置、--settings 和用户设置中读取该键，但忽略项目和本地设置中的该键，因此克隆的仓库无法为选择器重新设置标签；设置了该键的最高优先级来源将提供完整模型阵容。availableModels 允许列表仍适用于每一行；标签只会改变选择器中的显示内容，不会改变实际运行的模型。²²⁷²²⁵
• promptCacheTtl / subagentPromptCacheTtl（任意文件，v2.1.242+）：可为每个请求存储桶设置 "5m" 或 "1h"，这样 API 密钥用户和云提供商用户便可让主对话保留 1 小时缓存，同时让 subagents 维持 5 分钟缓存。请参阅缓存策略。²²⁷²²⁵
• modelPricing（托管，v2.1.243+）：组织约定的各模型费率和折扣乘数，供 /cost、状态行及遥测成本数据使用，以取代目录价格。请参阅查看成本。²²⁷

较新的设置（v2.1.247）： - feedbackDrafts（v2.1.247）：控制新的 SendFeedback 工具——当会话出现问题时，Claude 可以起草反馈报告，供您审核并通过 /feedback 发送；可通过此设置关闭起草功能。请参阅 Slash Commands 中的 /feedback 行。²²² - spinnerTipsOverride 结构扩展（v2.1.247）：提示条目现在除纯字符串外，还可以是 {id, text, cooldownSessions, priority} 对象；该对象新增了 tipsFile 和 label 键，因此组织可以将自定义提示与内置提示一同轮换显示（上面的示例展示了扩展后的结构）。设置文档尚未记录这些新键——目前唯一的来源是 CHANGELOG。²²²

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

• desktopSessionCleanupPeriodDays（v2.1.248）：限制桌面端写入的会话可免于转录清理的最长时间。与此设置一同发布的修复比该选项本身更重要：Claude Desktop 和 Cowork 会话过去会在 cleanupPeriodDays（默认30天）后消失；现在，只要这些会话仍在应用中，清理功能便会保留它们，除非组织策略另行管理保留期限。²⁰⁶
• 项目级 env 限制（v2.1.251）：项目级 .claude/settings.json 中的 env 块无法再设置 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR 或 TMPDIR/TMP/TEMP——请改在 shell、用户设置或托管设置中配置这些变量，以免克隆的仓库重定向 Claude Code 写入配置文件和临时文件的位置。²⁰⁶

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

• timeFormat / timeZone（v2.1.257）：控制 Claude Code 显示时间的方式，包括每轮结束时的完成时间和转录时间戳。timeFormat 接受12小时制、24小时制、UTC 24小时制或明确的 strftime 模式；timeZone 用于指定时区。设置文档尚未记录这两项——其来源是 CHANGELOG。²¹¹
• permissions.blockReadsOutsideWorkingDirectories（v2.1.257）：直接拒绝读取会话工作目录之外的文件。若未启用此项，自动模式现在会在会话首次进行此类读取前询问一次（请参阅 Auto Mode）。²¹¹ v2.1.273 弥补了两个缺口：当检查器无法完整分析 Bash 命令时，会提示确认而不是跳过检查；启用此设置后，也不会加载、召回或索引由仓库设置指定的内存目录。²¹⁷
• managedMcpServers / managedSourcesBehavior：托管范围的键，详见 Enterprise Deployment——前者供组织为每位用户提供 MCP 服务器（v2.1.259），后者用于选择性合并多个托管来源（在 v2.1.257 中得到完善）。²¹¹²²¹

较新的设置（v2.1.261）：

• bashOutputMaxChars / taskOutputMaxChars（v2.1.261）：分别提高 Claude 能够以内联方式接收的命令输出和后台任务输出量，超出部分会保存到文件，最高可设为128K字符。这与 BASH_MAX_OUTPUT_LENGTH 环境变量采用不同机制；后者设置从命令工作输出文件中回读的窗口大小（默认30,000个字符，上限150,000个）。这些键控制内联输出与持久化文件之间的阈值——超过阈值后，输出会写入文件，供 Claude 按需读取，而不会被截断。²¹⁴ 自 v2.1.265 起，持久化内容也有上限：保存到磁盘的工具结果最大为 1 GB，如果保存的文件被截断，对话内预览会明确提示。²¹⁵

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

• maxEffortLevel（v2.1.267）：限制用户可选择的工作量级别——既可在顶层设置，也可在 modelSettings 下按模型设置——并适用于所有提供商，包括 Bedrock、Vertex 和 Foundry。用户仍可选择低于上限的级别；这是 /effort 在管理员侧的配套设置。²¹⁶
• bashEditDiffEnabled（v2.1.269）：当 Bash 工具执行文件编辑时，工具结果会包含该命令所更改文件的差异，因此对话能够显示 sed 式编辑的实际效果。²¹⁶

设置速查：搜索最多的选项

如果您是为查找某个特定设置而来到这里，以下是简明索引。每个条目均标明其发布版本；若该设置仅属于特定范围，也会注明相应范围：

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

模型配置：

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5           # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
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               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_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]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send five x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted) for LLM gateways (opt-in; v2.1.273+)[^253]
CLAUDE_CODE_AUTO_MODE_SERVER=1                  # Use the platform's server-side auto-mode classifier on Bedrock/Vertex/Foundry; since v2.1.273 the local classifier is the default there "for now"[^253]

行为控制：

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=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_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

工具配置：

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

网络和代理：

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; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^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_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry 导出器与敏感字段控制：²⁴¹

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

v2.1.121+ LLM-request span 属性：stop_reason、gen_ai.response.finish_reasons 和 user_system_prompt 现在会随 LLM-request span 一同发出。由于 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 payload 包含 subagent 的推理强度，因此自定义状态行可以同时呈现模型和推理强度；此外，新的 CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 环境变量可用于配置 OTel 内容属性的 60 KB 截断上限。¹⁹⁰

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

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，定价为每百万 token $10/$50（请参阅快速模式）。¹⁹⁷¹⁹⁸

Claude Fable 5.1（2026年9月1日）： Fable 层级的新旗舰；自 v2.1.257 起，fable别名会解析至该模型（除非ANTHROPIC_DEFAULT_FABLE_MODEL固定为其他模型）；best现在表示“您可用的最新 Fable 模型”。最低版本要求需要稍加解释：模型配置文档称该别名在 v2.1.255 中完成切换，模型页面则称 Fable 5.1“需要 Claude Code v2.1.255 或更高版本”，但 2.1.253 至 2.1.256 从未发布至 npm——v2.1.257（9月1日）是首个可安装且包含该模型的版本。模型 ID：claude-fable-5-1（Bedrock：anthropic.claude-fable-5-1）。其层级和每 token 价格与 Fable 5 相同——输入为每百万 token $10，输出为每百万 token $50，1M 上下文，最大输出 128K，始终启用自适应思考，effort默认为high——但有一项定价变更对长时间代理式会话至关重要：缓存读取费用为每百万 token $0.25，即输入价格的 0.025 倍（2.5%），而非标准的 10%；仅 Fable 5.1 和 Mythos 5.1 采用该费率，缓存写入价格保持标准不变（5 分钟缓存为 $12.50，1 小时缓存为 $20）。可靠知识截止日期：2026年6月（训练数据同样截至2026年6月）——是所有当前 Claude 模型中知识最新的模型。最早退役日期为2027年9月1日。与 Fable 5 相比有三项破坏性变更：强制使用工具会返回错误、早期模型无法读取其思考块，以及编辑先前轮次会使思考块失效。另有五项新增变更：按消息设置推理强度（beta）、仅在当前轮次生效的系统消息（beta）、工具调用之间的进度更新（display: "updates"，beta）、更便宜的缓存读取，以及内容来源信息。Claude Mythos 5.1 是规格相同的同一模型，仅通过 Project Glasswing 邀请使用。该模型发布后，Fable 5 与 Opus 4.8/4.7/4.6/4.5 和 Sonnet 4.6/4.5 一同移入文档的旧版模型表。发布说明中还指出一项网关注意事项：在 Claude 应用网关会话中，fable和best目前仍会解析至 Fable 5——尚未配置 5.1 的网关会拒绝该模型——因此需要在/model中明确选择 Fable 5.1；请注意，在 v2.1.260 之前，/model选择器不会列出 Fable 5.1，因此必须输入完整命令/model claude-fable-5-1才能明确选择它（请参阅下方同批发布的修复）。套餐默认模型保持不变：高级套餐使用 Opus 5，Pro 和 Team Standard 使用 Sonnet 5。^211218219

Fable 5.1 同批发布修复（v2.1.260，9月3日）： 发布后的首个版本修复了四处问题。对于有权使用 Fable 5.1 的组织，/model选择器现在会显示该模型——修复前，只有完整输入/model claude-fable-5-1时才会接受该模型。Fable 5.1 的提示词缓存现在会覆盖工具结果之后附加的上下文；此前，这部分内容会在每一轮工具调用中作为未缓存输入重新发送——恰好在缓存读取费率为 0.025 倍所针对的长时间代理式会话中，悄无声息地削弱了其经济优势。会话期间更改/effort不再使提示词缓存失效。此外，当ANTHROPIC_DEFAULT_FABLE_MODEL固定值带有[1m]标记时，model: fable代理现在会遵循该标记，不再无提示地使用 200K 上下文窗口运行。²¹²

Claude Fable 5（2026年6月9日；自2026年9月1日起为旧版模型）： 一个高于 Opus的新模型层级——这是 Anthropic能力和智能水平最高的模型，在几乎所有测试过的基准上均达到当前最佳水平，并且能够在数百万 token 的上下文中保持连贯。Fable 5 是经过安全处理、可供通用场景使用的“Mythos 级”前沿模型：它随附安全分类器，遇到网络安全、生物化学和模型蒸馏查询时会回退至 Opus 4.8（Claude Mythos 5 是同一个模型，但为获授权的研究人员移除了这些保护措施）。自 v2.1.170（2026年6月9日）起，可以在 Claude Code中选择该模型——运行claude update，然后运行/model fable（这是短别名，自 v2.1.257 起会解析至 Fable 5.1——如今如需选择 Fable 5，请使用/model claude-fable-5）——并在2026年6月22日前逐步向各订阅套餐开放（现已全部完成）。模型 ID：claude-fable-5。Fable 5默认包含 1M 上下文窗口，因此无需使用[1m]后缀——并且自 v2.1.173（2026年6月11日）起，claude-fable-5[1m]模型名称会自动规范化为claude-fable-5，即移除后缀（该后缀仅对 Opus/Sonnet 有意义，因为它们需要通过[1m]启用 1M 上下文）；最大输出为 128K。输入价格为每百万 token $10，输出为每百万 token $50，约为 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一样，支持完整的effort等级（low/medium/high/xhigh/max，默认为high）。Fable 5的thinking无法关闭——会话thinking开关、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），开箱即用的默认模型则取决于您的订阅计划——高级计划使用Opus 5，Pro/Team Standard使用Sonnet 5；如果需要极致能力，请通过/model fable明确选择Fable层级——从v2.1.257起，这意味着Fable 5.1。^238197207219

Opus 4.7（2026年4月16日）：上一代旗舰模型，目前仍然完全可用。1M token上下文窗口，采用标准定价，不收取长上下文溢价。最大输出为128K，仅支持adaptive thinking（已移除extended thinking），并新增xhigh effort等级，建议将其作为编码和agentic工作负载的起点。¹⁴⁵可靠知识截止时间：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%。¹⁴⁴它采用新的tokenizer——相同文本的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调用方的重大变更：¹⁴⁵

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

任务预算（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。在2026年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（在Batches API中配合output-300k-2026-03-24 beta标头可达300K），仅支持adaptive thinking。可靠知识截止时间：2026年1月。定价：每MTok输入/输出$2/$10，目前已成为标准标价。Anthropic发布时宣布，$2/$10是持续至2026年8月31日的推广价格，随后又决定保留该价格：定价页面明确表示，原定于9月1日上调至$3/$15的计划“将不会实施”；v2.1.243也更新了/model选择器和内置的claude-api skill，将$2/$10显示为标准标价，而非限时促销价。²²⁸这比Opus 5的$5/$25低60%。在Claude Code中，Sonnet 5的effort参数默认为high（如需更改，请明确设置）。可通过/model sonnet（或/model claude-sonnet-5）选择该模型。¹⁸⁰ v2.1.197（2026年6月30日）曾将Sonnet 5设为Claude Code中新会话的默认模型；如今，它仍是标准层级（Pro、Team Standard）的默认模型，而高级计划及Anthropic API则默认使用Opus 5——请参阅上方的订阅计划表。¹⁸¹²⁰⁷

Sonnet 4.6（2026年2月17日，现已由Sonnet 5取代）：均衡型模型；在claude.ai和Claude Cowork中取代Sonnet 4.5成为默认模型。⁹³定价与Sonnet 4.5相同（每MTok $3/$15）。它在消耗更少token的同时，提高了agentic搜索性能。支持extended thinking、adaptive thinking和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的1/5，响应速度也更快。非常适合无需深度推理的后台任务。 Sonnet：在注重成本的日常开发中担当主力，也是标准层级、Pro 和 Team Standard 的默认模型（原生支持 1M 上下文，标准标价为每 MTok 2/10 美元；原定于9月1日实施的涨价已取消）。^181228207 可处理大多数编码任务，包括实现功能、修复 bug、编写测试和代码审查。历史说明：长期以来，包括本文在内，都将 v2.1.197（2026年6月30日）描述为 Sonnet 5 在所有层级成为默认模型；但模型配置文档按套餐区分的说明显示，从 v2.1.154 起，premium/API 的默认模型解析为 Opus 4.8，从 v2.1.219 起则解析为 Opus 5。因此，所谓“所有层级”实际上仅指标准层级。Sonnet 4.6 在2026年6月之前一直承担 Sonnet 的角色。^93147207 当您需要更低的 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.6 相比，Opus 4.7 在 SWE-Bench 上解决的生产任务多出 3 倍，在 CursorBench 上得分为 70%（对比 58%），并在包含 93 项任务的内部编码基准测试中将解决率提高了 13%。¹⁴⁴ 在 Opus 4.7 上，Claude Code 的 effort 默认为 xhigh，可通过 /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-5"
}

自定义选择器本身（modelPicker，v2.1.242+）：用户设置文件或托管设置文件可以按您指定的顺序和标签，列出 /model 提供的模型，而不再只能使用内置模型列表。每一行都指定一个 model（可以使用 --model 接受的任何写法，包括 Vertex 和 Bedrock ID），还可选择指定 label 和 description；将 replaceBuiltInOptions 设为 true 后，只会显示这些行、默认模型以及当前会话使用的模型。此键会忽略项目设置和本地设置，availableModels 允许列表仍会过滤这些行。Claude Code 会移除无法提供服务的行，将您暂时无法选择的行置灰并说明原因；如果没有任何行通过筛选，则回退到内置模型列表。²²⁷²²⁵

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

专门针对 subagents：

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

自 v2.1.251 起，CLAUDE_CODE_SUBAGENT_MODEL 用于设置 subagent 的默认模型，而不再覆盖所有配置：智能体定义中的 model: 和每次生成时显式指定的模型优先级更高。²⁰⁶ 自 v2.1.257 起，CLAUDE_CODE_SUBAGENT_MODEL_FORCE 可选择恢复原有行为：它会将 CLAUDE_CODE_SUBAGENT_MODEL（若未设置，则使用主对话模型）应用于所有 subagent，忽略每次生成时选择的模型以及智能体定义中的 model:。²¹¹

回退模型链（v2.1.166+）：当主模型过载或不可用时，fallbackModel 设置可以配置最多 3 个按顺序尝试的回退模型。--fallback-model 标志此前仅用于会话中途切换，现在从启动开始也适用于交互式会话。²⁴⁰

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

当 API 返回意外的不可重试错误时，Claude Code 现在还会使用回退模型重试当前轮次一次，再向用户显示失败信息。这样，主模型的瞬时故障可以平稳降级，而不会直接丢失当前轮次。²⁴⁰

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

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

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

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

检查当前模型

> /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）：快速模式适用于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。访问权限受到限制：请联系您的客户经理或加入候补名单。¹⁹⁶¹⁹⁸

远程会话（v2.1.271）：快速模式现已覆盖Claude Code Remote会话，包括云会话和自托管运行器。系统会采用主机的快速模式设置，也可以在会话中输入/fast；两种方式都仅在组织允许使用快速模式时生效。同一版本还修复了/fast off：当组织禁用快速模式时，该命令现在会关闭快速模式，而不再回复“Fast mode unavailable”。²¹⁶

定价（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"。如果您的运行框架固定使用4.7，并依赖快速模式请求静默降级，那么这些请求现在会直接失败；请将固定版本迁移至Opus 5或4.8。¹⁹⁸

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

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

快速模式包含完整的100万token上下文窗口（v2.1.50及更高版本）。整个上下文统一采用固定倍数计价，包括输入token超过20万的请求，不再额外收取长上下文附加费；该倍数还会与提示词缓存和数据驻留的价格倍数叠加。⁹⁶¹⁹⁸

运维注意事项。快速模式拥有独立于标准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

按模型保存（v2.1.251及更高版本）：/effort现在会分别为每个模型保存默认推理强度，因此切换模型时，每个模型都会保留自己的设置——在Opus上惯用的xhigh不会再跟随您切换到Haiku（CHANGELOG：“已将/effort改为按模型保存默认推理强度，因此切换模型时，每个模型都会保留自己的设置”）。max仅适用于当前会话的例外规则仍然有效。²⁰⁶ v2.1.257进一步完善了这两项调节功能：/effort现在接受s，可进行仅限当前会话的选择，与/model的惯例保持一致；--effort标志现在也仅作用于当前会话——它只会在该会话中解除新模型对默认推理强度的保留，而不会永久更改（CLI参考文档指出，它会“覆盖”默认值，“仅适用于当前会话且不会持久保存”）。²¹¹²²⁰

Max上的Auto Mode（v2.1.111及更高版本）

自2026年8月14日起，Auto Mode成为Pro、Max和Team计划的默认权限模式（于8月7日宣布）——有关公告中的研究数据、退出方式以及仍需主动选择启用的计划和网关，请参阅权限模式。²⁰³它最初是--dangerously-skip-permissions更安全的替代方案，最先通过Anthropic API向使用Opus 4.7的Max订阅者开放。¹⁴⁶一个独立的分类器模型——截至v2.1.210为Claude Sonnet 5——会在执行前审查每项操作，检查其是否符合意图且安全。¹⁸⁷ 注意（v2.1.111及更高版本）：--enable-auto-mode标志已移除；如需以Auto Mode启动会话，请改用--permission-mode auto。在Auto Mode的大部分生命周期中，Pro均被排除在外，而8月14日的默认启用将终结这一限制。Bedrock／Vertex／Foundry（v2.1.158及更高版本）：在这些网关上，可以通过CLAUDE_CODE_ENABLE_AUTO_MODE=1为Opus 4.7和Opus 4.8主动启用Auto Mode。[^181] 从v2.1.207起，不再需要主动启用：Auto Mode可在AWS Bedrock、Google Vertex AI和Microsoft Foundry上直接使用；希望将其关闭的管理员可使用disableAutoMode托管设置。同一版本还使Bedrock、Vertex AI和AWS上的Claude Platform默认使用Claude Opus 4.8，并停止从仓库的.claude/settings.local.json读取autoMode设置——请改在~/.claude/settings.json中配置自动模式规则。¹⁸⁵从v2.1.247起，Bash权限提示中会显示一条指向自动模式的提示，并提供只需按一次键即可选择的“Yes, and switch to auto mode”选项。²²²从v2.1.273起，Bedrock、Vertex AI和Foundry上的自动模式“目前”默认使用本地分类器——设置CLAUDE_CODE_AUTO_MODE_SERVER=1可改用平台的服务器端分类器。这与v2.1.236的分类器默认值说明涉及不同维度的状态变化：本地与服务器端之分属于运行机制，而早期版本从未公开这一机制。²¹⁷ Auto Mode不是什么：它不是安全边界。 下文的大部分措施都是在加固分类器，而分类器并非沙箱。2026年8月26日，提示词注入研究员Johann Rehberger公布了一条针对auto mode下Claude Code Opus 5的有效攻击链。他报告称，在小样本测试中，攻击成功率为60%至80%——主要攻击链会生成隔离的python3子进程，5次运行中有3次成功；另一种变体的载荷会生成无头claude -p实例，其两种配置分别在5次运行中成功3次和4次。他也特别指出，这些只是小样本结果，并不能代表普遍的攻击成功率。²¹⁰ 这条攻击链值得深入理解，因为其中每一步单独看来都合情合理：服务器以HTTP 415响应WebFetch，促使代理回退到curl；下载的归档文件被解压到暂存目录，其中包含一份清单、7条采用Base85/zlib编码的数据记录、一个原生二进制文件和一个struct.py；Claude拒绝运行不受信任的二进制文件，随后编写自己的Python解码器，并从该目录内运行；解码器导入base64，base64再导入struct，而Python会优先解析到攻击者的struct.py。整个过程中没有任何指令显得明显恶意——注入只需让受攻击的路径看起来像是完成任务最合理的方式。Rehberger还报告称，在少数运行中，Claude发现系统已遭入侵后试图终止恶意软件进程，但auto mode拒绝了清理命令。²¹⁰ 他将这一发现与Anthropic宣传过的一项数据相对照：一项委托第三方开展的评估报告称，在72种场景中分别运行10次后，auto mode下Opus 5的提示词注入攻击成功率为0.00%。他的攻击链并未包含在该测试集中，因此0.00%的基准测试结果和确实有效的代码执行攻击链可以同时成立；在他看来，这两种说法并不相容。²¹⁰ 还要注意其分类：Simon Willison在8月30日的更新中赞同一位读者的观点，即这并非典型的提示词注入——模型从未读取并遵循攻击者的指令——而是一次环境混淆攻击。²¹⁰

Anthropic以“Informative”结论关闭了报告，认定该行为符合设计预期。Rehberger转述的官方立场，正是您在设计防护方案时应当采用的前提：auto mode是一种尽力而为的分类器，并非安全保证；由多个单独看来无害的步骤精心组合而成的注入链，不属于分类器理应捕获的范围；真正的遏制边界是操作系统级隔离和网络出口控制。²¹⁰ 这并不否定下文的加固措施，而是理解这些措施的正确框架。Auto mode可以减少需要您回应的提示数量，并阻止文档中列明的破坏性操作；但它无法让处理不受信任输入的会话变得安全。如果会话将接触可能受攻击者影响的内容——抓取的页面、下载的归档文件、issue文本、第三方MCP服务器——真正能够限制损害范围的，是模型之外的控制措施：容器或虚拟机、受限的网络出口、对代理实际行为的监控，以及一个不存放您不愿失去的SSH密钥和云凭据的主目录。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
    ]
  }
}

通过/permissions编辑分类器规则（v2.1.246）。 运行/permissions并打开Auto mode选项卡；只有当前会话可使用auto mode时，该选项卡才会出现。它会列出分类器从各个作用域读取的allow、soft_deny、hard_deny和environment条目，并显示每个部分的内置规则是否生效；来自托管设置或--settings的条目为只读，所有更改都会保存到~/.claude/settings.json。首次向某个部分添加规则时，系统还会插入"$defaults"，确保内置规则继续生效。您可以分别切换各部分的内置规则（某个部分至少要有一条自定义规则，才能关闭其内置规则），而environment会作为单个文档在编辑器中打开。²²⁶²²⁴

选择“不再询问”（v2.1.118+）。 Auto Mode的启用提示现在提供“Don’t ask again”选项，频繁使用者无需通过脚本传递标志，即可不再显示说明。

破坏性命令防护措施（v2.1.183）。 除非您在会话中明确要求，否则auto mode现在会强制阻止一系列不可逆命令：当您并未要求丢弃本地工作时，阻止破坏性git操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；当相应提交并非由代理在当前会话中创建时，阻止git commit --amend；除非您指定了具体stack，否则阻止基础设施拆除操作（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 mode现在会阻止篡改会话记录文件——审计记录本身不允许代理触碰；在对无法根据上下文解析的变量运行rm -rf之前，系统会请求确认，从而防止rm -rf $DIR中$DIR未知这一类事故；此外，后台任务通知现在会明确说明没有发生任何人工输入，因此会话记录中伪造的“用户已批准”文本无法再被冒充为有效批准并据此执行操作。¹⁸³ 第3项是一种值得牢记的提示词注入防御措施：批准必须通过批准通道传入，而执行框架现在明确落实了这一假设。

命令替换无法再掩盖灾难性操作（v2.1.208）。 即使rm -rf ~等灾难性删除命令隐藏在$(...)、反引号或进程替换（<(...)）中，现在也会触发提示——而且即使处于--dangerously-skip-permissions和auto mode下，提示依然会出现。将破坏性命令包裹在替换语法中，已无法再蒙混过关、绕过安全防护。¹⁸⁶

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

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

减少对话框，审查力度不变（v2.1.218）。 过去有3项检查会在auto mode中弹出权限对话框并中断流程：危险的rm、后台运行符&以及可疑的Windows路径。现在它们不再弹出对话框，而是交由auto mode分类器裁决。因此，安全审查仍会照常进行，但无需您对每次命中都亲自介入。同一版本还将这一机制扩展到启用auto的plan mode：静态分析器无法确认只读的Bash命令不再触发提示，而是由分类器判断，无需回退到对话框。¹⁹⁵

遏制逃逸规则（v2.1.257）。 分类器的“绝不自动批准”列表新增了“Containment Escape”规则：除非环境将其标记为预期行为，否则系统将不再自动批准获取云元数据凭据、规避网络出口限制以及跨租户访问等操作。请结合上文所述的限制来理解这项规则：它只是分类器的持续加固措施——新增了一类文档明确规定的拒绝项，并未改变auto mode的本质。²¹¹ 首次读取工作目录以外的文件时提示（v2.1.257）。 在 auto 模式下，会话首次读取工作目录以外的文件前，系统现在会询问一次。配套的 permissions.blockReadsOutsideWorkingDirectories 设置可将提示改为直接拒绝——此类读取会被完全阻止。²¹¹ v2.1.273 将这两种行为扩展到检查器无法识别的情况：如果检查器无法完整分析某条 Bash 命令，系统会发出提示，而非跳过检查；启用阻止设置后，由仓库设置选定的 memory 目录也不会再被载入提示、调用、索引或用于 memory 提取。²¹⁷

图表渲染器 URL 视为上传（v2.1.261）。 如果链接将内容打包进公共图表渲染器的 URL（类似 mermaid.live，数据直接编码在 URL 中），除非这是您明确要求的操作，否则系统不再自动批准。分类器会将此类链接视为上传：打包后的数据通过 URL 本身传输，页面打开后，渲染器网站自身的脚本便可读取这些数据——类似 mermaid.live 的链接将载荷放在 URL 片段中，浏览器会把它交给页面的 JavaScript，而不是随网络请求发送。其定位与上述注意事项相同：这是强化分类器时封堵的又一条数据外泄通道，并非新的边界。²¹⁴

内联 ! shell 不再经过分类器；subagent 回传则纳入分类器（v2.1.271）。 这两项属于机制调整，而非新增拒绝类别。skill 或 slash command 中的内联 ! shell 命令现在遵循默认模式的权限规则，而非分类器规则——如果没有规则可判定某条命令，则会将其作为需审核的工具调用执行。与此同时，subagent 现在通过专用的回传调用向调用方报告，安全分类器会审核这次调用；不再是在事后审核其最后一条消息——检查点从交接之后移到了交接本身。²¹⁶

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 和 headless 会话现在会从环境中读取 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，建议升级。

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

Anthropic 宣布为 Claude 生成的内容提供机器可读标记。此举源于《欧盟人工智能法案》第 50 条（对于新推出的 AI 系统，自 2026年8月2日起强制执行）。该系统包含两个组件：生成文本中的不可见统计水印，以及依据 C2PA 开放标准写入 .svg、.png 和 .jpg 等生成文件的签名溯源元数据。²²⁹²⁰⁴ 新闻标题常常模糊了一个关键细节：两个组件遵循相同的模型时间表。 根据支持页面，“2026年8月2日或之后推出的 Claude 模型将在发布时支持机器可读标记”——在该日期之前推出的模型，即目前的全部产品阵容（Fable 5、Opus 5、Sonnet 5、Haiku 4.5），适用欧盟法律的过渡期；Anthropic 表示“也正努力为这些模型添加标记支持”。²⁰⁴ 目前通过 Claude Code 生成的任何内容，无论文本还是文件，都不带标记；未来模型的输出则会在所有使用界面中带有标记，包括 Claude Platform（API）、claude.ai、Claude Code、Claude Cowork、Claude Tag 以及各类云网关，因为标记在模型层面实现。还有一点值得特别说明，因为一则广泛传播的帖子恰好颠倒了事实：您在当前模型中察觉到的任何风格或行为变化，都不可能由水印引起——当前任何模型均未启用水印。

其工作原理是采用 Google DeepMind SynthID-Text 的一种变体。当 Claude 在语义等效的选项间选择词语时，水印会改变“用于选词的随机性来源”——不会添加任何字符，也不涉及后处理；根据 Anthropic 的内部测试，“水印不会影响内容、创意水平或可读性”。²²⁹ Claude Code 用户最关心的是：代码中带有稀疏水印。 可正常运行的代码几乎没有任意选择的余地，因此水印会集中在仍有发挥空间之处，例如注释和命名；据 Anthropic 称，这“对实际生成的代码几乎没有影响”。²²⁹ 水印的持久性具有概率性，并且因组件而异：对于文本，轻微编辑“可能不会彻底移除水印”，完整重写则会将其移除，而由 Claude 生成的译文会带有自己的新水印；对于文件元数据，格式转换、重新保存和截图均可能移除 C2PA 签名。²⁰⁴ 检测 API 已在规划中；阳性结果只能证明“Claude 可能曾在某个环节参与过内容的生成或处理”，但明确无法区分“此内容由 Claude 编写”和“此内容由 Claude 大幅编辑”。此外，根据支持页面的说明，未检测到水印同样无法证明任何事情。任何客户层级均未提及可选择退出该机制。²²⁹²⁰⁴

Claude Code 的费用是多少？

了解并控制成本，是持续使用Claude Code的关键。另请参阅模型选择了解模型能力，并参考决策框架，为每项任务选择合适的模型。

查看费用

> /cost

输出：

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

订阅用户可以在/cost中查看按模型划分的用量和缓存命中明细，清楚了解哪些模型消耗了 token，以及有多少内容由缓存提供（v2.1.92+）。¹³⁷

使用合同费率而非公开定价（modelPricing，托管设置，v2.1.243+）：采用协商后按模型计费费率或折扣系数的组织，可以通过托管设置modelPricing部署这些费率。此后，/cost、状态栏和遥测成本数据将使用合同费率，而非公开定价，使开发者看到的数字与组织实际支付的费用一致。²²⁷自v2.1.271起，系数也可以高于1，最高为10，供需要对内部团队加价计费的组织使用。²¹⁶

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

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

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

v2.1.273让对话上下文得以延续：/login、/upgrade和/extra-usage此前会丢弃对话中较早的思考内容，迫使下一次请求完整重写提示缓存。²¹⁷

订阅方案

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

自2026年9月14日起实施的每周限制（8月29日公布）：自5月提升以来一直生效的临时每周限额上调50%，将于9月14日结束。此后，Pro、Max、Team和按席位计费的Enterprise方案将永久采用较提升前基准高25%的限额。Anthropic对这一变化给出的计算结果是：“与当前相比，Claude Code的每周限额将减少17%。”如果您当前的每周上限是150个单位，9月14日后将变为125个单位。此次公告不涉及5小时限制，5月实施的翻倍政策仍然有效。如果您会运行长时间无人值守的会话，请立即按较低上限规划用量：达到重置时间时自动继续的开关（v2.1.234）和/usage是需要重点关注的两项控制功能。²¹³

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在输入 token 超过200K后，按2倍输入价格和1.5倍输出价格计费的说明已不再适用。旧版Opus 4.5及更早模型仍采用原有的定价结构。

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

提示缓存可以显著降低重复输入的成本：缓存写入按基础价格的1.25倍（5分钟缓存）或2倍（1小时缓存）计费，但缓存读取仅按0.1倍计费，可节省90%；且仅在Claude Fable 5.1和Mythos 5.1上，读取价格可降至0.025倍（Fable 5.1为$0.25/MTok），可节省97.5%。²¹⁸对于具有重复上下文的RAG系统和代码助手，缓存可将成本降低88%至95%。

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

多账户政策⁵²

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

允许的情况：

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

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

实际案例：2026年1月，重度用户Jeffrey Emanuel（@doodlestein）的22个Max账户被自动标记并暂时封禁。Anthropic员工Thariq（@trq212）在确认其用途合理后，于4小时内解决了此问题。如果您需要跨多个账户广泛使用Claude Code，分别处理工作和个人项目，这正是该服务支持的使用方式，但请勿试图钻系统空子。

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

成本影响因素

实际成本示例

成本节省要点：使用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——达到上限后，系统将拒绝新的生成请求，并停止正在运行的后台代理（此前后台代理不受预算限制）¹⁹⁴
5. 使用规划模式进行探索：不执行操作，即可避免意外触发高成本操作
6. 主动压缩：上下文越小，token 越少
7. 限制输出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 为非紧急工作使用批量API：输入和输出 token 均享受50%折扣
9. 分析项目的Claude API支出：/claude-api cost-optimize（v2.1.247+）可分析现有项目的Claude API支出，并逐项衡量和调整成本杠杆（缓存、token 管理、批处理、思考强度和模型选择）；该命令面向您使用API构建的应用，而非Claude Code会话本身²²²

监控用量

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

后台 Token 用量

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

通常每个会话低于$0.04。

Claude Code Analytics 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 默认使用 Opus 5，Pro 和 Team Standard 默认使用 Sonnet 5；/model opus 可将 Sonnet 会话升级为 Opus 5。^181197207 对于 subagents，可降级使用 Haiku。如果觉得 Sonnet 的回答流于表面，则升级到 Opus。使用 agent teams（v2.1.32+）时，Opus 可以协调多个代理，并行处理不同的子任务。⁷⁹

Command、Skill、Subagent 还是 Agent Team？

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

Hook 还是 Prompt？

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

何时使用扩展思考？

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

在会话期间使用 Alt+T 切换。更高的思考预算会增加成本；建议从最低值开始，仅在回答显得仓促时再逐步提高。

Opus 4.6 自适应思考：Opus 4.6 会根据问题的复杂程度自动调整思考深度。对于大多数任务，无需明确控制思考预算——Opus 会针对复杂问题加大思考力度，同时快速处理简单问题。如果您希望强制进行更深入的分析，手动切换思考模式主要适用于 Sonnet。

应该选择哪种执行界面？

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Teams、Subagents 与并行会话

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

应该选择哪种 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 用于切换当前会话的快速模式。它仍使用同一个模型——Opus 5 或 Opus 4.8；截至 v2.1.219，快速模式仅支持这两个模型——但会优化输出速度。它不会切换到成本更低的模型，而且按每 MTok 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 notebook

修改工具首次运行时，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 重新启用。

自 2026年8月14日起，Auto 模式成为 Pro、Max 和 Team 的开箱即用默认模式——该变更于 8月7日公布，并在切换当日由官方权限模式文档确认上线。当前文档还补充了两个值得注意的适用范围细节：默认模式适用于新会话；而且“您自行设置的默认值会保持不变，除非接受一次性切换提示；由组织管理的默认值也不会改变。”这些方案的新会话会以 auto 模式启动，该模式“会将每次工具调用交由分类器处理，重点阻止不可逆、破坏性或针对您环境之外的操作。”Anthropic 对此次切换给出的依据是：在一项包含 1,053 名测试者的研究中，auto 模式识别出了 89% 的危险命令，而人工审核仅识别出 13.6%；同时，用户会批准 97% 的权限提示，这正是人工审核在实践中效果不佳的原因。自公告发布起，Pro/Max/Team 不再对分类器产生的 token 开销计费。按一次 Shift+Tab（或使用桌面端模式下拉菜单）即可切回；可在设置中通过 defaultMode 固定其他默认模式；组织管理员则可通过托管设置 disableAutoMode 完全禁用 auto 模式。Enterprise、Claude API、AWS 上的 Claude Platform、Bedrock、Google Cloud 的 Agent Platform 和 Foundry 目前仍需主动启用——Anthropic 计划在“未来一个月内”将默认模式扩展至这些平台。²⁰³关于 auto 模式不作出哪些保证，以及研究人员展示的绕过方法如何促使 Anthropic 作出说明，请参阅Max 上的 Auto 模式。

即使在 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 更安全的替代方案。每次执行操作之前，独立的分类器模型——自 v2.1.210 起为 Claude Sonnet 5（最初为 Sonnet 4.6）——都会进行审核，检查操作是否符合用户意图且足够安全。¹²⁴¹⁸⁷

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

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

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

# 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 模式不再要求主动启用（v2.1.152），无需环境标志即可在 Bedrock/Vertex/Foundry 上运行（v2.1.207），并自 2026年8月14日起成为 Pro/Max/Team 的开箱即用默认模式。[^180]¹⁸⁵²⁰³

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

defaultMode 的作用域限制（v2.1.257）：项目的 .claude/settings.json 或 .claude/settings.local.json 无法再设置 defaultMode: "bypassPermissions"——该值在这些文件中会被忽略，与既有的 "auto" 限制相同。文档现已明确说明：permissions.defaultMode 的 auto 和 bypassPermissions 值“不会从项目或本地设置中生效”——请在用户或托管设置中配置，或在每个会话中使用 --permission-mode。因此，克隆的仓库无法携带一个让会话以绕过权限模式启动的设置文件。（上例使用任何作用域均可设置的 acceptEdits；本指南此前也从未记录既有的 auto 限制——现在两项限制均已明确记载。）²¹¹²²⁰

权限规则语法

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

Bash 命令模式：

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

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

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

请将 * 放在子命令之后。Claude Code 会按原样匹配第一个 * 之前的全部内容，因此正是这些词决定了规则的限制范围：Bash(git log *) 仅允许 git log 命令，而在 Bash(git * main) 中，* 会代替子命令及其之前的所有选项。其中包括 -c，该选项可让 git 运行您指定的程序，因此 Bash(git * main) 也会批准 git -c core.fsmonitor=<script> diff main。自 v2.1.246 起，如果允许规则在子命令之前使用通配符，无论该规则位于设置文件、托管设置还是 --allowedTools/--settings 值中，Claude Code 都会在启动时发出警告。修复方法是填写确切的预期值，例如用 Bash(git checkout main) 代替 Bash(git * main)。²²⁶²²⁴

文件拒绝规则可穿透重定向；针对参数的扩展上线后在一天内撤回（v2.1.257-260）。Bash 命令中的 Read(...) 和 Edit(...) 拒绝规则会覆盖输入重定向（< file）以及 tac、egrep 等读取命令（v2.1.257）——这是 v2.1.232 的输入重定向检查在 v2.1.233 中撤回时所承诺的较窄版本，且目前仍然有效。v2.1.259 将相同保护扩展至隐藏在选项值和操作数中的文件路径（--ignore-revs-file=.env、-f.env、@file 参数、git diff 和 git grep 操作数、cd DIR && cat FILE 复合命令；当对包含被拒文件的目录执行 grep -r/cp -r 时也会先询问），但 v2.1.260 在次日撤回了该扩展：在存在 Read(./**/build/**) 规则时，它会在所有模式下拒绝 npm run build，还会导致 cd ... && grep 即使处于 auto 模式也触发提示。这是参数级覆盖范围的第三次反复——v2.1.232 推出、v2.1.233 撤回；v2.1.257 推出并保留重定向与读取命令子集；v2.1.259 扩展至参数；v2.1.260 又撤回该扩展。因此截至 v2.1.260，拒绝规则能够捕获重定向和读取命令，但无法捕获隐藏在任意命令参数中的路径——这一状态由 v2.1.260 确立并延续至今；之后的变更是针对具体绕过方式的定点修复，而非第四次整体调整（见下一段）。²¹¹²¹²

撤回后的定点修复，以及第二次小范围撤回（v2.1.268-273）。参数扩展的撤回仍然有效；以下变更修复了具体的绕过方式，其中一项后来也被撤回。v2.1.268：对于以真实位置表示的路径，针对符号链接系统目录的 deny 和 ask 规则（macOS 上的 /etc、/tmp、/var；Linux 上的 /bin）现会生效；Bash 命令也不再忽略以符号链接形式写出的拒绝规则——这两项修复均继续有效。同一版本还规定：当同一行中存在权限检查器无法分析的 env -C、eval 或类似命令时，该命令无法再规避 Read 或 Edit 拒绝规则——但 v2.1.273 恰好撤回了这项检查：“time -p make build 等命令现在会再次触发提示，而不是被拒绝。”v2.1.269：Edit() 拒绝规则和写入路径检查现会覆盖 Bash tee 命令写入的文件；Bash(tee:*) 允许规则不再覆盖工作目录以外的目标；以 ! 开头的 deny 或 ask 规则仅在写入该规则的设置来源内生效（单独的 ! 否定会被忽略）。v2.1.271 修复了检查器本身：即使 fmt、column 等命令所读取的文件位于检查器无法识别的选项之后，也会受到检查；当通配符出现在模式或选项值中时（例如 grep -v dir/* file），其展开得到的文件也会受到检查；shell 变量声明标志无法再歪曲实际运行的命令；包含两次目录切换、子 shell 或 cd+git 链的命令，在 bypass 和 auto 模式下也无法再绕过 permissions.blockReadsOutsideWorkingDirectories 提示。v2.1.273 在撤回上述检查的同时带来了 3 项定点修复：无法分析的 Bash 命令不再跳过 permissions.blockReadsOutsideWorkingDirectories 提示；隐藏在子 shell 中的危险 rm 不再于 bypass 模式中跳过确认；仓库设置所选择的记忆目录不再基于该设置进行加载、回忆或索引。对于检查器无法分析的 Bash 命令行，最终规则可以直截了当地概括为：拒绝规则会触发提示而非直接拒绝，blockReadsOutsideWorkingDirectories 也会触发提示而非跳过。²¹⁶²¹⁷

文件操作模式：

{
  "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 持续有效——无需再在每个并行检出中重复批准同一命令。¹⁸⁸

含括号的路径和格式错误的模式会安全失败（v2.1.260）。文件权限规则获得了 3 项解析修复，其中第一项属于安全修复。路径中包含括号的 Edit/Write/Read 规则——例如 Next.js 路由组 Edit(src/app/(admin)/**)——此前会因无效而被丢弃或被 Bash 沙箱忽略，导致管理员认为只读的文件夹仍可写入；现在这些规则会正常生效。对于包含无法编译模式（例如未闭合的 [）的文件拒绝规则，此前会导致所有文件编辑均以 Invalid regular expression 失败；现在该规则会保护其字面表示的路径。此外，对于 Edit(C:\dir\(name)\**) 这样的规则，由于 \( 会被解读为转义括号而非路径分隔符，设置错误现在会建议一种含义明确的写法。同一版本也不再静默忽略右括号后仍有文本的规则（Bash(ls) x 从未匹配任何内容）；现在会将其报告为无效设置。²¹²

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 生成强制生效：通过 workflow、--agents 或 agent team 启动特定具名 agent 时，Agent(agent_type) 拒绝规则和 Agent(x,y) 允许类型限制现会生效，而不再仅适用于匿名的 Task 式生成。生成操作会在启动时被阻止，从而堵住具名 agent 绕过约束规则的缺口。¹⁷⁵

WebFetch 模式：

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

自 v2.1.268 起，普通 WebFetch deny 和 ask 规则不再应用于 Artifact 工具的读取和更新操作——若要阻止或控制这些操作，请编写 Artifact 规则或 WebFetch(domain:claude.ai)。²¹⁶

其他目录

将 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.221 起，凭据文件在 allow/deny 之外新增第三种模式：mode: "mask"（Linux 和 WSL）。沙箱命令读取文件时，获得的是一份包含哨兵值的副本——可以替换整个文件，也可以只替换由 extract 正则表达式捕获的片段——沙箱代理则会在出站时将其替换为真实值。命令可以正常工作（可通过代理完成身份验证），但机密从未出现在其环境中。这正是应对提示注入命令搜寻 token 时所需的特性。在无法使用代理替换机制的 macOS 上，mask 会回退为 deny，因此为 Linux CI 编写的配置会安全降级，而不会悄然暴露文件。¹⁹⁹

v2.1.224 将遮蔽范围扩展到静态文件内容之外。extract 和 onExtractNoMatch 可处理结构化环境变量值；带有 maskClaims 的 decode: "jwt" 可遮蔽 JWT 内的指定 claim，而非整个 token，使命令仍能读取 token 的路由元数据，同时让敏感 claim 保持为哨兵值；awsPairs/sigv4 则会在代理处重新签署 AWS SigV4 请求，从而让遮蔽功能可用于 AWS CLI——否则被遮蔽的密钥无法通过签名验证。所有这些功能都要求启用 network.tlsTerminate，而且仅接受来自用户、托管或 --settings 作用域的配置——仓库无法携带悄然改道您凭据的遮蔽配置。²⁰¹

自 v2.1.216 起，sandbox.filesystem.disabled 设置可跳过文件系统隔离，同时保留网络出站控制——适用于文件系统牢笼导致构建工具故障，但仍希望对出站流量强制实施域名允许列表的情况。¹⁹²

自 v2.1.219 起，sandbox.network.strictAllowlist 设置会直接拒绝不在允许列表中的主机，而不显示提示。默认情况下，沙箱命令访问 allowedDomains 之外的主机时会触发权限提示；启用 strictAllowlist 后，连接会被直接拒绝。对于无人值守的运行——CI、后台 agents、通宵循环——应优先使用此设置，因为无人响应的提示只会造成停滞，而且“遇到意外出站时询问我”本就不是合适的策略。它完善了网络控制三要素：allowedDomains 指定允许的目标，deniedDomains（见下文）从宽泛的允许范围中排除例外，而 strictAllowlist 决定其他目标是触发询问还是直接失败。¹⁹⁶v2.1.229 还收紧了域名列表语法：IPv6 字面量必须置于方括号中（[::1]:443），含义模糊的写法会按失败关闭原则处理，且 /doctor 会标记这些写法。²³⁴v2.1.236 又增加了两项强化措施：在 macOS 上，通配符读取拒绝规则（例如 **/.env）现在会在允许读取区域内优先生效，覆盖匹配目录中的内容，且无法通过重命名被拒文件来绕过；启用 auto 模式时，Monitor 允许规则会被搁置——Monitor 命令将接受与 Bash 命令相同的分类器审核。auto 模式分类器本身现在也会在 Bedrock、Vertex AI 和 Foundry 上，以及禁用遥测时，采用与 Claude API 相同的默认设置，包括基于严重程度评分的分类。²²³v2.1.273 更改了这些网关上的默认机制：auto 模式目前会默认使用本地分类器，设置 CLAUDE_CODE_AUTO_MODE_SERVER=1 可改为使用平台的服务器端分类器。²¹⁷

Auto 模式中的单命令 allowed_domains（v2.1.271）：启用沙箱后，auto 模式中的 Bash、PowerShell 和 Monitor 命令可携带各自的 allowed_domains——命令所需的主机会与命令一同接受审核，并且仅对该命令开放；其他主机则会被拒绝。出站权限不再是整个会话范围的授权：每条命令分别声明目标，而审核也精确覆盖命令与目标的组合。²¹⁶

严格沙箱模式与 ! 例外（sandbox.allowUnsandboxedCommands，v2.1.260）。本指南此前尚未提及的一项设置：默认情况下，沙箱内执行失败的命令可以通过 dangerouslyDisableSandbox 逃生口在沙箱外重试，但仍需经过常规权限流程。sandbox.allowUnsandboxedCommands: false——在 /sandbox 的 Overrides 选项卡中显示为 Strict sandbox mode——会关闭该逃生口：参数将被忽略，每条命令都必须在沙箱内运行，除非列入 excludedCommands。自 v2.1.260 起，即使启用严格沙箱模式，您在 ! bash 模式提示符中亲自输入的命令也会在沙箱外运行，“就像在自己的终端中输入一样”——严格模式约束的是 Claude 运行的内容，而非您亲自输入的内容。若您的威胁模型依赖 ! 命令继续受牢笼限制，则这种保障已不复存在。²¹²

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

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

安全说明（v2.1.34+）：此前，当启用 autoAllowBashIfSandboxed 时，通过 sandbox.excludedCommands 或 dangerouslyDisableSandbox 排除在沙箱之外的命令可能绕过 Bash ask 权限规则；该问题已在 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、workflow 或输出样式名称冲突时，以最靠近工作目录的定义为准；保存项目作用域的 workflow 时，则以最近的现有 .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 中的权限失败关闭强化：¹⁹⁰

一个版本集中修复了多项权限检查缺口，并统一采用失败关闭原则——分析器无法确定时便会提示：

• 修复 Windows PowerShell 5.1 绕过。此前，在 PowerShell 5.1 会话中运行的命令可能绕过权限检查。
• Bash 文件描述符重定向按失败关闭处理。对于 bash 与权限分析器采用不同方式解析的重定向形式，现在会先提示，而不是直接运行。
• 超过 10,000 个字符的命令始终触发提示。此前可能误判超长命令；现在绝不会自动运行。
• [[ ]] 中的 zsh 下标和修饰符会触发提示。[[ ]] 比较中的变量下标和修饰符此前被视为惰性文本；由于它们可以执行代码，现在需要批准。
• 不安全的 help/man 变体不再自动批准。某些调用可以借读取文档之名运行不安全选项、命令替换或反斜杠路径。
• 远程会话提示顺序。远程会话中的权限提示无法再于本地确认对话框之前继续。
• docker 守护进程重定向标志会触发提示。携带 --url、--connection、--identity 或 Podman 远程模式的 docker 命令（包括 Podman 的 docker shim）此前可在不提示的情况下运行——这些标志会让命令连接完全不同的守护进程。
• 当指定写入位置时，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 都会触发格式化工具，无一例外。对于合规、安全和团队标准，确定性优于概率性。⁴

可用事件