Advanced Features 指南

当你已经会用 slash commands、memory、skills、MCP、hooks 和 subagents 之后，Claude Code 的高级能力会决定你能不能把它真正用到复杂项目和高自动化工作流里。

这部分不是“你必须一口气全会”，而是你要知道：

哪些高级能力最值得先学
哪些适合日常开发
哪些适合团队和自动化
哪些不该在没准备好的情况下乱开

这部分包含什么

主要包括：

planning mode
Ultraplan
extended thinking
Auto Mode
background tasks
TUI Mode
Monitor Tool
scheduled tasks
channels
permission modes
print mode / headless usage
session management
Agent Teams
remote / desktop / web sessions
worktrees
sandboxing
configuration

最推荐先掌握的四项

1. planning mode（规划模式）

复杂任务先规划再执行。

2. permission modes（权限模式）

明确 Claude 在本地到底能做多少事。

3. print mode（输出模式）

把 Claude Code 接进脚本、CI/CD 和自动化流程的关键入口。

4. background tasks（后台任务）

让耗时任务后台跑，不阻塞当前会话。

如果你不是重度用户，先掌握这四个就足够产生明显收益。

如果你已经开始频繁做多文件任务，下一步最值得补的是：

/ultraplan：把复杂规划交给云端起草，再决定在浏览器还是本地执行
Monitor Tool：让 Claude 盯住后台命令的事件流，而不是不断轮询

planning mode（规划模式）

planning mode 是什么

它是“两阶段工作流”：

先做计划
再按计划执行

适合：

多文件重构
新功能设计
架构调整
数据迁移
高风险变更

不太适合：

小 bug
单文件轻改
只问一个简单问题

常见入口

/plan Implement user authentication system

也可以通过权限模式进入只读规划状态：

claude --permission-mode plan

一个好的 planning mode 输出应该包含什么

分阶段计划
预计会改哪些文件
风险点
验证方式
用户需要确认的地方

如果 planning mode 只给你几句空话，那不是好计划。

v2.1.136 之后要特别注意：plan mode 现在会无条件阻止所有文件写入。即使你在 permissions.allow 里配过宽松的 Edit(...) 规则，也不能再绕过去。如果旧工作流依赖这种行为，现在必须先退出 plan mode，再做编辑。

v2.1.218+ 还要区分 shell 与写文件：当 Auto Mode 可用且默认开启的 useAutoModeDuringPlan 生效时，plan mode 会把 shell command 交给 classifier，而不是弹权限询问；获批命令可以运行，被拒命令会阻止。文件写入仍然无条件禁止。

Ultraplan（深度计划）

/ultraplan 会把“起草计划”这一步交给 Claude Code on the web 的云端会话来完成。你本地终端不用一直等着，等云端把 plan 草案写好后，再去浏览器审阅，并决定继续在云端执行，还是把计划带回本地终端落地。

你可以把它理解成：

/plan：更像本地规划模式
/ultraplan：更像云端起草 + 浏览器审阅 + 再决定执行位置

什么时候最值

高风险多文件修改
需要先看详细计划再放权
想让计划阶段和执行阶段彻底分开
需要把计划发给同事或团队成员一起看

使用门槛

需要 Claude Code on the web 账户
最好有一个可供云端克隆的 GitHub 仓库
目前不适用于 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry

三种进入方式

直接输入：

/ultraplan <prompt>

在普通请求里明确说要用 ultraplan。
先在本地做一轮 plan，再把草案交给 Ultraplan 深挖。

按上游 2026-04-11 的说明，首次调用 /ultraplan 时会自动创建 Claude Code on the web 环境，不需要再手工等容器预热。

你会看到的状态

状态	含义
`ultraplan`	Claude 正在云端研究代码并起草计划
`ultraplan needs your input`	云端会话有澄清问题，需要你去浏览器回应
`ultraplan ready`	计划已经准备好，可以在浏览器里审阅

审阅后怎么执行

当草案准备好后，你通常有两条路：

继续在云端执行 直接在浏览器里批准计划，让 Claude 在云端继续实现，并从 web 侧发起 PR。
把计划带回本地终端 适合你更想在本地环境里继续做实现、跑测试和手工检查。

如果你选择带回本地，常见分支是：

Implement here：就在当前终端继续做
Start new session：新开一个本地 session 再做
Cancel：先把计划存下来，稍后再继续

如果你当前开着 Remote Control，启动 Ultraplan 时它会断开，因为两者都会占用 Claude Code on the web 这个界面。

extended thinking（扩展思考）

extended thinking 的价值在于：让 Claude 对复杂问题多想一步，而不是急着下结论。

它特别适合：

架构对比
技术选型
高歧义问题
边界条件分析

对中国用户来说，一个实用理解是： 不是所有问题都要更长思考，但复杂问题最好别让 Claude 秒答。

这轮上游纠正了一个容易误传的点：不要再把 /think 当成有效 slash command。如果你想让某一次回答更深地推理，可以在 prompt 里直接写 ultrathink；它影响的是这一轮回答，不会永久改变当前 session 的 effort level。

如果你要调 session 级别的思考强度，用 /effort。如果你只是想切换是否显示更详细的推理 transcript，注意 Ctrl+O 更偏 verbose 显示切换；Option+T / Alt+T 才是 extended thinking 的开关入口。

Auto Mode（自动模式）

Auto Mode 属于更偏自动化、也更需要谨慎的能力。

它适合：

明确受控的自动化环境
已经知道自己在放开什么权限
你对项目风险边界比较清楚

它不适合：

你还没搞清 permission modes 差异
你还不确定项目里哪些操作是危险的

新手建议先不要把 Auto Mode 作为默认。

当前要求要看清

从 v2.1.219+ 的当前口径看，Auto Mode 面向所有 plans，但仍受组织策略、模型和 provider 资格限制。Team / Enterprise 默认可用；管理员可在 managed settings 中把 permissions.disableAutoMode 设为 "disable" 来关闭。

Anthropic API 与 Claude Platform on AWS：支持 Opus 5、Opus 4.6+、Sonnet 4.6+ 和 Fable 5
Bedrock、Vertex AI、Microsoft Foundry 与已登录的 Claude apps gateway session：支持 Opus 5、Sonnet 5、Opus 4.7+ 和 Fable 5
Sonnet 4.5、Opus 4.5、Haiku 与 claude-3 系列不支持 Auto Mode

从 v2.1.207 起，上述 provider 不再需要 CLAUDE_CODE_ENABLE_AUTO_MODE=1。这个旧环境变量仍会被接受以兼容历史脚本，但已经不产生效果；后台 classifier 使用 Sonnet 4.6，会产生额外 token 成本。

需要恢复 Auto Mode 默认配置时，v2.1.212+ 可以运行：

claude auto-mode reset
claude auto-mode reset --yes

第一条会请求确认，--yes 用于跳过确认。看到旧资料时，优先核对当前版本和组织策略，不要继续复制旧的 opt-in 环境变量。

不想使用后台分类器时的替代方案：一次性权限种子脚本

如果你不想用“后台分类器 + 自动判定”这套模式，上游提供了一种更务实的替代方案：

直接用一次性脚本把一组 更保守的安全权限基线 写进 ~/.claude/settings.json

脚本位置：

09-advanced-features/setup-auto-mode-permissions.py

典型用法

# 先预览会加什么，不落盘
python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run

# 写入保守基线
python3 09-advanced-features/setup-auto-mode-permissions.py

# 按需再放开能力
python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests
python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages
python3 09-advanced-features/setup-auto-mode-permissions.py --include-gh-read --include-gh-write

这组权限默认包含什么

类别	示例
Core read-only tools	`Read()`、`Glob()`、`Grep()`、`Agent()`、`WebSearch()`、`WebFetch()`
Local inspection	`Bash(git status:)`、`Bash(git log:)`、`Bash(git diff:)`、`Bash(cat:)`
Optional edits	`Edit()`、`Write()`、`NotebookEdit(*)`
Optional test/build	`Bash(pytest:)`、`Bash(cargo test:)`、`Bash(make:*)`
Optional git writes	`Bash(git add:)`、`Bash(git commit:)`、`Bash(git stash:*)`
Optional packages	`Bash(npm install:)`、`Bash(pip install:)`
Optional GitHub CLI	`Bash(gh pr view:)`、`Bash(gh pr create:)`

它和旧的 `auto-adapt-mode` 有什么不同

旧思路：

通过 hook 动态学习你批准过什么

现在的新思路：

一次性写入一组明确的规则
再通过命令行参数按需增加范围

这对中文用户尤其有帮助，因为它更容易解释清楚：

现在到底开了哪些权限
哪些是默认安全基线
哪些是你主动额外放开的

`autoMode.hard_deny`：无条件阻断的自动模式黑名单

从 v2.1.136+ 开始，autoMode.hard_deny 用来定义“无论模型怎么判断用户意图，都绝不允许”的动作。

{
  "autoMode": {
    "hard_deny": ["Bash(rm -rf /:*)", "Bash(git push --force*)"]
  }
}

它和 soft_deny 的区别是：

soft_deny：模型仍可能结合上下文判断是否放行
hard_deny：直接阻断，不跟分类器讨价还价

如果你在团队里推 auto mode，这个设置比“口头提醒大家别乱用危险命令”靠谱得多。

Auto Mode 现在还有内置意图保护

从 v2.1.183+ 起，除了你自己配置的 autoMode.hard_deny，Claude Code 还会默认拦住一批破坏性命令，除非你在当前 session 明确要求它这么做。

典型例子包括：

git reset --hard、git checkout -- .、git clean -fd、git stash drop
不是本轮 agent 创建的 commit 上执行 git commit --amend
terraform destroy、pulumi destroy、cdk destroy

这属于内置 intent-based protection，不需要你手工把这些命令都塞进 hard_deny。但团队里仍建议把真正不可接受的组织规则写进 autoMode.hard_deny，两层保护不要混为一谈。

从 v2.1.218+ 起，针对 filesystem root 或 home 的删除（包括 command / process substitution 里的 rm -rf /、rm -rf ~）也交给 classifier 判定，不再另开 permission dialog。这里仍然不是“自动放行”，而是改由分类器按意图批准或拒绝。

`autoMode.classifyAllShell`：让所有 shell 命令都过分类器

从 v2.1.193+ 起，可以用 autoMode.classifyAllShell 让所有 Bash / PowerShell 命令都经过 Auto Mode 分类器。这个开关适合更严格的团队环境：不是只检查看起来危险的命令，而是让每条 shell 命令都先被分类。

{
  "autoMode": {
    "classifyAllShell": true
  }
}

同一版本还会在 Auto Mode 拒绝动作时显示 denial reason。你可以在 transcript、拒绝 toast，以及 /permissions 里的 recently-denied 列表看到原因，方便判断是规则太严、命令写法不清楚，还是任务本身需要先让用户确认。

autoMode.classifyAllShell、Bash、PowerShell、/permissions 都是配置或界面标识，不要翻译成中文 key。

明确不会自动加进去的危险操作

脚本明确不会帮你加入这些类型：

rm -rf
sudo
force push
git reset --hard
DROP TABLE
kubectl delete
terraform destroy
npm publish
curl | bash
生产环境 deploy

如果你想要“更自动化”，请先明确你是真的需要，而不是只是觉得方便。

background tasks（后台任务）

background tasks 适合这些场景：

长时间运行的任务
不想阻塞当前对话
需要并行推进的工作
希望 Claude 先把耗时命令挂起来，自己继续做别的

典型例子包括：

本地开发服务器
长时间测试
构建流程
日志持续输出

如果你已经会用 background tasks，下一步就很值得把 Monitor Tool 一起学掉。

TUI Mode（全屏终端模式）

这是上游在 v2.1.110 明确加进文档的新能力，适合：

tmux
iTerm2 分屏
你想让 Claude Code 在终端里更稳定地全屏显示

最直接的用法：

/tui
claude --tui

如果你经常在终端里长时间工作，这个模式比普通输出更稳，也更不容易闪。

另外：

/focus 更适合做“只看重点输出”的切换
Ctrl+O 现在更偏向普通 / verbose transcript 切换

Markdown 任务清单复选框渲染

v2.1.149+ 的富文本渲染支持 GitHub-Flavored Markdown 任务清单复选框。也就是说，像下面这样的内容会显示成复选框：

- [ ] 待确认
- [x] 已完成

这对计划、验收清单和 code review checklist 很实用。注意 - [ ] / - [x] 这类 Markdown 语法本身不要中文化改写。

Monitor Tool（监控工具）

Monitor Tool 是上游最近更明确写进文档的新重点。它的核心价值是：

Claude 不需要再每隔几十秒 sleep 一下去轮询
而是直接盯住后台命令的 stdout 事件流
一旦匹配到事件，就立刻唤醒当前会话

简单说： 它适合“等某件事发生”这种场景，比低效轮询更省 token，也更及时。

它为什么值得学

后台安静时几乎不消耗额外 token
有事件发生时，Claude 能第一时间反应
很适合日志、测试输出、服务启动、错误监控

两种最常见用法

1. 持续流过滤

适合一直往外吐日志的命令：

tail -F server.log | grep --line-buffered -E "ERROR|FATAL"

2. 定时查询后只在有变化时输出

适合没有原生事件流、只能自己轮询的接口：

last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  gh api "repos/owner/repo/issues/123/comments?since=$last" || true
  last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  sleep 30
done

一个很容易踩的坑

如果你是把流接到 grep 上，记得一定带：

grep --line-buffered

不然 grep 可能会缓冲输出，看起来像“明明有事件，Claude 却迟迟没反应”。

scheduled tasks（定时任务）

scheduled tasks 适合：

周期性检查
定时重复 prompt
简单提醒
固定时间执行的轻量任务

如果你还没掌握 print mode、permission modes 和 background tasks，先别急着把 scheduled tasks 配得太复杂。

permission modes（权限模式）

permission modes 决定 Claude 在本地能做什么，以及什么时候会请求你确认。

常见模式

manual（v2.1.200+ 的交互默认名称；default 仍是可接受的 alias）
acceptEdits
plan
dontAsk
bypassPermissions
auto

如何理解

模式	适合什么
`manual`	日常安全使用；读取文件不提示，其他操作按规则询问
`acceptEdits`	希望编辑流畅一些
`plan`	只想分析，不想改
`dontAsk`	只运行预先批准的工具，其他请求自动拒绝，不弹确认
`bypassPermissions`	可信环境中的强自动化
`auto`	所有动作都可执行，但会经过后台 safety classifier 检查

从 v2.1.200+ 起，CLI、--help、VS Code 和 JetBrains 中原来的交互 default 模式统一显示为 manual。兼容性没有被切断：--permission-mode manual 与 --permission-mode default 都能用，settings 中也兼容旧值；新配置应写规范形式 "permissions": {"defaultMode": "manual"}。settings key 是 permissions.defaultMode，不存在 permissions.mode。v2.1.203+ 起，处于 Manual 时 footer 会显示灰色 ⏸ badge。

从 v2.1.160 起，即使处在 acceptEdits，Claude Code 在写入 shell 启动文件和可能执行命令的构建配置前仍会提示确认。例如 .zshenv、.zlogin、.bash_login、~/.config/git/、.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/。

这点对自动化很重要：acceptEdits 只是减少普通编辑确认，不代表可以静默修改会影响命令执行链路的配置。

`--dangerously-skip-permissions` 变得更“锋利”了

从 v2.1.121 到 v2.1.126，--dangerously-skip-permissions / bypassPermissions 对更多路径写入不再弹确认，包括：

.claude/skills/
.claude/agents/
.claude/commands/
.claude/
.git/
.vscode/
shell 配置文件

灾难性删除命令仍会被拦住，但这不代表它适合日常项目默认打开。对中文用户来说，最稳的原则是：只在可丢弃 sandbox、临时实验仓库或你完全理解风险的自动化环境里使用。

一个常见误区

很多人以为权限模式只是“麻烦不麻烦”。其实它决定的是：

风险控制
自动化强度
你是否还能及时拦住错误操作

print mode / headless usage（输出模式 / 无头用法）

claude -p 是 Claude Code 进入自动化世界的关键入口。

适合：

shell 脚本
CI/CD
一次性任务
管道输入
结构化输出

例如：

claude -p "Run tests and summarize failures"
cat error.log | claude -p "Explain this error"

`!` bash 命令现在会触发回复

在交互式 session 里用 ! 直接执行 shell 命令时，v2.1.186+ 起命令输出会自动发给 Claude，并让 Claude 根据输出继续回应。

如果你想回到旧行为，也就是“只把输出放进上下文，不立刻要 Claude 回答”，在 settings.json 里设置：

{
  "respondToBashCommands": false
}

respondToBashCommands 是 settings key，不要翻译。这个开关适合你把 !npm test、!pytest 当成临时上下文采集，而不是每次都希望 Claude 立刻分析时使用。

从 v2.1.193+ 起，! bash mode 支持 live file-path autocomplete。也就是说你在输入 !cat src/...、!pytest tests/... 这类命令时，可以直接在 prompt 里补全路径，少一点复制粘贴和输错目录的概率。

Safe Mode：先隔离自定义配置

如果 Claude Code 行为突然很怪，先别急着怀疑项目代码。v2.1.169+ 提供了 --safe-mode：

claude --safe-mode
CLAUDE_CODE_SAFE_MODE=1 claude

它会禁用 CLAUDE.md、plugins、skills、hooks 和 MCP servers，用来判断问题到底来自你的自定义配置，还是 Claude Code 本身。它是排障工具，不是日常默认启动方式。

Session Recap（会话回顾）

上游从 v2.1.108 起补充了 session recap 的说明。简单说：

你离开一段时间再回来
Claude 可以先给你一段简短回顾
让你不用翻半天历史消息找上下文

最常见入口：

/recap

如果你经常在多个 session 间切换，这个能力会很省脑子。

如果你的组织开启了 OpenTelemetry，上游从 v2.1.136+ 起允许用 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1 重新打开 Anthropic 的会话质量问卷；默认仍是关闭。

从 v2.1.193+ 起，Claude Code 还会发出 claude_code.assistant_response OpenTelemetry log event，用于把模型回复文本纳入 telemetry pipeline。这个事件名和 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 一样属于可执行 / 观测标识，不要翻译。

Push Notifications（推送通知）

这是 v2.1.110 远程控制相关能力里比较值得注意的一项：

当 Remote Control 开启
并且 /config 里打开了 push 相关选项
Claude 可以在长任务完成或需要你介入时给手机发通知

对中国用户来说，可以把它理解成：
不是“消息提醒功能”，而是“长任务别一直守着”的补充能力。

`Remote Control` / `/schedule` / claude.ai connectors 在 API key 模式下会一起被关掉

从 v2.1.139 开始，如果设置了下面任一项：

ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN
apiKeyHelper

print mode 使用建议

任务尽量清晰明确
一开始先用小任务试
不要直接上高权限全自动流程
需要 JSON 输出时，先确认消费端怎么解析

Channels / 外部事件通道

Channels 是 Research Preview 能力，可以把外部服务的事件推送进当前 Claude Code 会话。

常见来源包括：

Discord
Telegram
iMessage
Webhooks

对中国用户来说，一个简单理解是： 不是 Claude 主动轮询外部系统，而是外部事件直接推到你的会话里。

如果你还在早期上手阶段，知道它存在就够了；等你真的要做实时通知流，再重点看权限和网络环境。

session management（会话管理）

session 管理能力在任务复杂后会非常重要。

高频场景：

恢复之前的工作
给当前任务命名
从当前 session 分叉实验

常见操作：

/resume：无参数时打开历史 session picker，并将选中的 session 作为后台 session 恢复（v2.1.212+）
/rename
/fork [prompt]：复制当前对话为独立后台 session；新旧 session 之后各自推进，不回传结果（v2.1.212+）
/subtask <task>：启动继承完整对话的 forked subagent，完成后把结果回传当前对话（v2.1.212+）
/branch [name]：切换到当前对话的副本，原对话保留
claude -c
claude -r "session-name"

/fork 只在 v2.1.77 到 v2.1.161 之间曾是 /branch 的 alias；从 v2.1.161 到 v2.1.211，它执行的是如今 /subtask 承担的 forked-subagent 行为。关闭 agent view 时，/subtask 不可用，/fork 会保留旧行为。如果你不命名 session，后期会越来越难管理。

Output Styles（输出风格）

Output Styles 改变 Claude 每轮回答的角色、语气和默认格式，不是项目知识库。项目约定仍应写进 CLAUDE.md，任务流程则更适合 skill。

内建风格包括：

Default：默认的软件工程工作方式
Proactive：更主动执行并做合理假设，但不会改变 permission mode
Explanatory：在步骤间解释实现选择和代码模式
Learning：协作式学习，并留下少量 TODO(human) 让你参与实现

从 /config 的 Output style 选择，或直接设置：

{
  "outputStyle": "Explanatory"
}

独立的 /output-style 已在 v2.1.91 移除（v2.1.73 起弃用）。更改 system prompt 后，应在新 session 或 /clear 后使用。自定义风格放在 ~/.claude/output-styles/ 或项目 .claude/output-styles/；如果只是改变表达方式但仍要保留编码指令，在 frontmatter 写 keep-coding-instructions: true。

Status Line（状态栏）

/statusline 可配置终端底部状态栏。Claude Code 会把 session、model、cost、context、repo 和 worktree 等字段组成 JSON，从 stdin 传给你的 command：

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

脚本可读取 model.id、effort.level、context_window.used_percentage、cost.total_cost_usd、workspace.project_dir 等字段。项目里的 status-line command 需要 workspace trust；脚本还会收到 COLUMNS 和 LINES，可按终端尺寸调整输出。

屏幕阅读器模式

从 v2.1.208+ 起，Claude Code 提供纯文本渲染模式，减少全屏 TUI 对 screen reader 的干扰。以下三种入口效果相同：

claude --ax-screen-reader
export CLAUDE_AX_SCREEN_READER=1

也可以在 settings 中设置 "axScreenReader": true。--ax-screen-reader、CLAUDE_AX_SCREEN_READER 和 axScreenReader 都是可执行标识，不要翻译。

Agent Teams（代理团队）

Agent Teams 是实验性能力，默认关闭。它和 subagents 的区别在于：

subagents：主 Claude 委派一个子任务，等结果回来
Agent Teams：多个 Claude Code 实例协作，每个成员有自己的上下文窗口，还能直接通信

如果你想开启它，常见方式是：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

它更适合：

大型重构
多模块并行推进
需要团队成员之间直接交换信息的复杂任务

如果你只是刚学到 subagents，这一块先知道就行，不必急着上。

dynamic workflows（动态工作流）

v2.1.154+ 增加了 /workflows，用于查看正在运行和已经完成的 dynamic workflows。

你可以把 dynamic workflows 理解成“更可控的多代理编排”：适合把几十个甚至上百个后台 subagents 按 fan-out、pipeline、并行阶段等方式组织起来，用在大规模审查、迁移、全仓扫描这类任务上。

对中文用户来说，先记住两个入口就够了：

/workflows：查看 workflow 运行记录
ultracode：不是模型 effort level，而是会发送 xhigh 并让 Claude 编排 dynamic workflows 的会话级模式

从 v2.1.160 起，dynamic workflows 的触发关键词是 ultracode；只写裸词 workflow 不再触发运行。文档、prompt 模板和团队 SOP 里如果还写“说 workflow 就会启动”，需要改成新口径。

从 v2.1.219+ 起，dynamic workflows 默认采用 medium size guideline，目标少于 15 个 agents。可在 /config 的 Dynamic workflow size 中选其他规模或 unrestricted，也可以在 settings 中写 workflowSizeGuideline。它是 Claude 力求遵守的建议，不是像 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 那样的硬上限；settings 已设置该 key 时，/config 会隐藏对应行。

如果你的任务只是普通单文件修复，不需要急着用它；它更适合“覆盖面很大、需要确定性拆分”的工程任务。

remote / web / desktop（远程 / Web / 桌面）

这些能力适合：

在多台机器间切换
在本地和云端之间接力
用 desktop 做更好的可视化 diff 或会话管理

对于新手，先知道它们存在即可。真正要用时，再重点看网络和权限环境。

worktrees（工作树）

worktrees 特别适合：

多分支并行方案
大任务拆成多个实验方向
和 planning mode / agent workflows 配合

如果你已经开始同时试两三种实现路线，worktrees 会非常有价值。

`worktree.baseRef`：worktree 到底从哪里分支

从 v2.1.133 开始，可以通过 worktree.baseRef 控制 claude --worktree 是从远端默认分支还是本地 HEAD 开新分支：

"fresh"：默认值，从 origin/<default-branch> 开始，忽略你本地还没 push 的提交
"head"：从你当前本地 HEAD 开始，保留未推送的本地状态

{
  "worktree": { "baseRef": "head" }
}

如果你在 v2.1.128 那段时间习惯了“worktree 自动继承我本地未推送改动”，这轮需要特别注意默认值已经回到更保守的 "fresh"。

`EnterWorktree`：在 session 中切换 worktree

从 v2.1.157 起，EnterWorktree 可以在同一个 session 中切换 Claude 管理的 worktree。Claude 管理的 worktree 在 agent 结束后也会保持 unlocked，方便你用 git worktree remove 或 git worktree prune 做后续清理。

`worktree.bgIsolation`：后台 session 要不要单独 worktree

从 v2.1.143 开始，还能控制后台 session（例如 /bg、claude --bg、Agent View 派发）是默认单独开 worktree，还是用 "none" 直接改当前前台工作副本。

sandboxing（沙箱）

sandboxing 的核心不是“更麻烦”，而是“更安全地控制 Claude 的能力范围”。

适合：

风险敏感环境
企业环境
希望限制文件系统或网络访问

不适合：

你还没搞清当前工具链本身怎么跑

如果你在 Linux / WSL 上把 bubblewrap 或 socat 装在非标准路径，上游还新增了两个设置可显式指定：

sandbox.bwrapPath
sandbox.socatPath

v2.1.181+ / v2.1.187+ 又补了两个更细的 sandbox 设置：

sandbox.allowAppleEvents：macOS 上显式允许 sandboxed commands 发送 Apple Events
sandbox.credentials：阻止 sandboxed commands 读取 credential files 和 secret environment variables

v2.1.216+ 新增 sandbox.filesystem.disabled：跳过文件系统隔离，但继续执行网络出口限制。它适合“文件 sandbox 会破坏工具链、但仍必须限制网络访问”的场景，只允许从 user settings、managed settings 或 --settings 提供；project settings 不能开启。

v2.1.219+ 新增 sandbox.network.strictAllowlist：sandboxed command 访问不在 allowlist 中的 host 时直接拒绝，不再弹出询问。需要“未列入即拒绝”的企业网络边界时再启用。

如果你在公司设备或含有生产凭证的机器上跑自动化，优先关注 sandbox.credentials；这些都不是“中文化字段”，必须按原 key 写。

configuration 与环境变量

高级能力很多都会回到配置层，例如：

permission mode
thinking effort
channels
auto mode
plugins
MCP

所以你最终还是会需要理解：

settings 文件
CLI flags
环境变量

如果你想长期高效使用 Claude Code，这一步绕不过去。

本目录的 config-examples.json 提供 11 组可解析示例。最外层 name / description 是中文索引信息，真正可复制到 settings.json 的内容位于每组 config 中；其中 key、permission rule、hook event 和模型 ID 都保持原样。

值得注意的 settings

setting	用途
`askUserQuestionTimeout`	给无人回答的 `AskUserQuestion` 设置空闲超时并自动继续。`v2.1.200+` 默认不再自动继续；只有显式配置这个 key 才恢复定时行为
`enableArtifact`	按用户启用或禁用 Artifact tool（`v2.1.196+`）
`permissions.disableAutoMode`	在 managed settings 中设为 `"disable"`，关闭 Team / Enterprise 默认可用的 Auto Mode
`axScreenReader`	设为 `true` 后启用纯文本 screen reader 渲染模式（`v2.1.208+`）
`sandbox.filesystem.disabled`	跳过 filesystem isolation，但保留 network isolation（`v2.1.216+`）
`sandbox.network.strictAllowlist`	非 allowlist host 直接拒绝，不弹权限询问（`v2.1.219+`）
`emojiCompletionEnabled`	控制 prompt 输入框的 emoji shortcode 自动补全，例如 `:heart:`（`v2.1.217+`）
`workflowSizeGuideline`	dynamic workflow 的建议规模；默认 medium，目标少于 15 个 agents（`v2.1.219+`）

这些 key 名不要翻译。askUserQuestionTimeout、enableArtifact、axScreenReader 和 workflowSizeGuideline 可用于常规 settings；permissions.disableAutoMode 是管理员使用的 managed setting。

`/config` 可以直接写 `key=value`

从 v2.1.181+ 起，除了打开交互菜单，你也可以在 prompt 里直接写：

/config thinking=false
/config --help

/config --help 会列出可用 shorthand keys。key=value 形式在普通交互、-p 和 Remote Control 场景里都能用；它适合临时调整单个设置，少走一层菜单。

常见环境变量里，最近更值得注意的是：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
CLAUDE_CODE_NEW_INIT=1
ENABLE_PROMPT_CACHING_1H=1（把 prompt cache TTL 从默认 5 分钟拉长到 1 小时）
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1（终端能力自动检测失误时，强制同步输出）
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1（让 Homebrew / WinGet 安装具备后台升级能力）
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1（在设置了 ANTHROPIC_BASE_URL 时，显式开启网关 /v1/models 发现）
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1（退出全屏 alternate-screen 渲染，保留普通终端滚动历史）
CLAUDE_CLIENT_PRESENCE_FILE（指向一个本机 marker file，在你人在电脑前时抑制 mobile push notifications）
CLAUDE_CODE_MAX_RETRIES（控制 API retry 次数；v2.1.186+ 起最多 15 次）
CLAUDE_CODE_RETRY_WATCHDOG（适合无人值守 session 的 retry 控制，不建议一味抬高 CLAUDE_CODE_MAX_RETRIES）
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT（覆盖 remote MCP tool 5 分钟无响应 abort 的默认值，适合排查长时间挂起的 MCP 调用）
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION（每个 session 的 WebSearch 调用上限，默认 200；v2.1.212+）
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION（每个 session 的 subagent spawn 上限，默认 200；/clear 会重置预算）
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS（同时运行的 subagents 上限，默认 20；v2.1.217+）
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH（允许嵌套 spawn 的最大深度；v2.1.219+ 默认 3，设为 1 可禁用嵌套）
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS（MCP tool call 自动转后台的阈值，默认 120000 毫秒）
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH（OpenTelemetry content attribute 的截断上限，默认 60 KB；v2.1.214+）
FORCE_HYPERLINK=0（关闭 footer 里的可点击 PR badge 链接；v2.1.217+）
CLAUDE_AX_SCREEN_READER=1（启用纯文本 screen reader 渲染模式）

这里还有两个这轮很值得知道的行为修正：

ENABLE_PROMPT_CACHING_1H=1 在 v2.1.129 修复了一个回退 bug；之前某些场景会悄悄退回 5 分钟 TTL
/context 从 v2.1.129 起不再把 ASCII 可视化直接塞进对话上下文，而是只在界面里显示，这样每次调用大概能少吃掉约 1.6k token

如果你在 SDK / 企业策略场景里工作，这轮还有个更偏管理员的设置值得知道：

parentSettingsBehavior：控制 SDK 的 managedSettings 和父进程 settings 发生冲突时，是保持旧的 "first-wins"，还是改为深度 "merge"
enforceAvailableModels：从 v2.1.175+ 起，托管策略可以强制 availableModels 也约束 Default model。若用户当前默认模型不在 allowlist 里，Claude Code 会回退到允许列表里的第一个模型；用户级或项目级 settings 不能把托管策略的模型范围放宽。

`fallbackModel`：最多三个 fallback models

如果主模型过载或临时不可用，可以配置最多三个 fallback models，Claude Code 会按顺序尝试：

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

从 v2.1.166+ 起，--fallback-model 也适用于交互式 session，不再只限 print mode。需要注意：认证失败、限流、请求过大和传输错误不会走 fallback；这类问题要先修凭证、额度、输入大小或网络。

effort level 这轮要纠正的一个误解

上游这次把模型和 effort level 的关系又更新了一轮，核心变化是 Claude Opus 5：

Opus 5（claude-opus-5、1M context）：low / medium / high / xhigh / max，默认 high
Sonnet 5、Opus 4.8：low / medium / high / xhigh / max，默认 high
Opus 4.7：low / medium / high / xhigh / max，默认 xhigh
Opus 4.6、Sonnet 4.6：low / medium / high / max
Haiku 4.5：不支持 effort levels

ultracode 也容易误解：它不是一个模型 effort level，而是会发送 xhigh 并让 Claude 编排 dynamic workflows 的会话级能力。

对中文用户来说，一个最简单的记法是：

Opus 5 是当前默认 Opus 模型，默认 effort 为 high
需要更重推理时再显式选 xhigh 或 max
不要把 Haiku 4.5 写成支持 effort levels

Opus 5 的 safety-classifier fallback

这和主模型过载时使用的 fallbackModel 不是同一机制。v2.1.219+ 中，Opus 5 请求被 cybersecurity classifier 标记时会改用 Opus 4.8 重跑；被 biology classifier 标记时直接拒绝，不会切换 fallback。做渗透测试、CTF、安全审查或生物相关代码时，需要把这种模型变化或拒绝算进验证预期。

switchModelsOnFlag（默认 true）控制被标记时是否自动切换。设为 false 后，Claude Code 会暂停并让你选择切换模型或修改 prompt；/config 中显示为 Switch models when a message is flagged。

{
  "switchModelsOnFlag": false
}

中国用户特别注意

1. 自动化前先看网络

如果你要用：

claude -p
remote / web / desktop
MCP
plugins

先确认：

API 访问
GitHub 连通性
npm / uv / Python 依赖下载
公司代理和证书环境

2. 先理解权限，再追求自动化

很多人会一开始就想“全自动”，但权限模式没搞清时，这很容易出事。

3. Windows / WSL 差异要提前确认

高级特性里很多命令和脚本默认更贴近 Unix 生态。

新版 Windows 体验有两个变化值得知道：

Git for Windows / Git Bash 不再是硬前提；没有 Git Bash 时，Claude Code 可以使用 PowerShell 作为 shell tool
开启 PowerShell tool 后，PowerShell 会成为主 shell；检测范围也覆盖 Microsoft Store、MSI 未进 PATH、以及 .NET global tool 安装的 PowerShell 7

如果你的团队里同时有人用 macOS、Windows、WSL，示例脚本最好明确写出预期 shell。

4. `Ctrl+R` 搜索范围变了

从 v2.1.129 起，Ctrl+R 默认会搜 所有项目里的所有 prompts，不再只看当前项目。如果你在 picker 里只想缩到当前项目，再按一次 Ctrl+S 即可切换范围。

5. `--channels` 不再强依赖 OAuth

v2.1.128+ 之后，--channels 不只支持 Pro / Max 的 OAuth 登录，也能和 API key（console auth）一起工作。

6. 团队管理员现在可以禁用 Remote Control

如果你在 Team / Enterprise 环境里，需要强制本地执行、不允许 remote control，上游新增了 disableRemoteControl：

{
  "disableRemoteControl": true
}

这个设置应该放在受管策略层，而不是普通用户自己的本地设置里。对企业场景来说，它是组织级禁用，不是个人偏好开关。

常见坑

1. 把 advanced features 全当成“酷炫功能”

它们本质上是控制力、风险边界和自动化能力，不只是花哨选项。

2. 还没理解权限就开高自动化

这会让“让 Claude 帮忙”很快变成“让 Claude 瞎动”。

3. print mode 用得太重太快

建议从日志解释、测试摘要、静态分析这种低风险任务开始。

4. session 不命名

长任务一多，后面很难找回。

故障排查

如果高级功能“看起来有、实际上跑不起来”，优先检查：

权限模式是否合适
当前命令是否应该用交互模式还是 print mode
环境变量是否齐全
远程或外部服务是否可访问
当前是否受网络、代理、公司策略影响

最佳实践

先掌握 planning mode、permission modes、print mode、background tasks
先小范围试自动化，再逐渐放权
高风险任务优先用 plan / checkpoints / worktrees 保护自己
中国用户优先排除网络和 shell 环境问题