Documentation — Spybara

agent-sdk/hooks.md +10 −10

Details

24 </Step>24 </Step>

25 25

26 <Step title="SDK 收集已注册的 hooks">26 <Step title="SDK 收集已注册的 hooks">

27 SDK 检查为该事件类型注册的 hooks。这包括您在 `options.hooks` 中传递的回调 hooks 和来自设置文件的 shell 命令 hooks，当相应的 [`settingSources`](/zh-CN/agent-sdk/typescript#setting-source) 或 [`setting_sources`](/zh-CN/agent-sdk/python#setting-source) 条目启用时（默认 `query()` 选项就是这样）。27 SDK 检查为该事件类型注册的 hooks。这包括您在 `options.hooks` 中传递的回调 hooks 和来自设置文件的 shell 命令 hooks，当相应的 [`settingSources`](/zh-CN/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/zh-CN/agent-sdk/python#settingsource) 条目启用时（默认 `query()` 选项就是这样）。

28 </Step>28 </Step>

29 29

30 <Step title="匹配器过滤哪些 hooks 运行">30 <Step title="匹配器过滤哪些 hooks 运行">

225 225

226每个 hook 回调接收三个参数：226每个 hook 回调接收三个参数：

227 227

228* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状（例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`）。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hook-input) 和 [Python](/zh-CN/agent-sdk/python#hook-input) SDK 参考中的完整类型定义。228* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状（例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`）。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整类型定义。

229 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。229 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。

230 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们仅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。230 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们仅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。

231* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。231* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。

236您的回调返回一个具有两类字段的对象：236您的回调返回一个具有两类字段的对象：

237 237

238* **顶级字段**控制对话：`systemMessage` 将消息注入到对话中，对模型可见，`continue`（Python 中的 `continue_`）确定代理在此 hook 后是否继续运行。238* **顶级字段**控制对话：`systemMessage` 将消息注入到对话中，对模型可见，`continue`（Python 中的 `continue_`）确定代理在此 hook 后是否继续运行。

239* **`hookSpecificOutput`** 控制当前操作。内部的字段取决于 hook 事件类型。对于 `PreToolUse` hooks，这是您设置 `permissionDecision`（`"allow"`、`"deny"` 或 `"ask"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。在 TypeScript SDK 中，`permissionDecision` 也接受 `"defer"` 以结束查询并[稍后恢复](/zh-CN/hooks#defer-a-tool-call-for-later)；此值在 Python SDK 中不可用。对于 `PostToolUse` hooks，您可以设置 `additionalContext` 以将信息附加到工具结果，或设置 `updatedToolOutput` 以在 Claude 看到之前完全替换工具的输出。239* **`hookSpecificOutput`** 控制当前操作。内部的字段取决于 hook 事件类型。对于 `PreToolUse` hooks，这是您设置 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。返回 `"defer"` 结束查询，以便您可以[稍后恢复它](/zh-CN/hooks#defer-a-tool-call-for-later)。对于 `PostToolUse` hooks，您可以设置 `additionalContext` 以将信息附加到工具结果，或设置 `updatedToolOutput` 以在 Claude 看到之前完全替换工具的输出。

240 240

241返回 `{}` 以允许操作而不进行更改。SDK 回调 hooks 使用与 [Claude Code shell 命令 hooks](/zh-CN/hooks#json-output) 相同的 JSON 输出格式，其中记录了每个字段和事件特定的选项。对于 SDK 类型定义，请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#sync-hook-json-output) 和 [Python](/zh-CN/agent-sdk/python#sync-hook-json-output) SDK 参考。241返回 `{}` 以允许操作而不进行更改。SDK 回调 hooks 使用与 [Claude Code shell 命令 hooks](/zh-CN/hooks#json-output) 相同的 JSON 输出格式，其中记录了每个字段和事件特定的选项。对于 SDK 类型定义，请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#synchookjsonoutput) 和 [Python](/zh-CN/agent-sdk/python#synchookjsonoutput) SDK 参考。

242 242

243<Note>243<Note>

244 当多个 hooks 或权限规则适用时，**deny** 优先于 **defer**，**defer** 优先于 **ask**，**ask** 优先于 **allow**。如果任何 hook 返回 `deny`，操作将被阻止，无论其他 hooks 如何。244 当多个 hooks 或权限规则适用时，**deny** 优先于 **defer**，**defer** 优先于 **ask**，**ask** 优先于 **allow**。如果任何 hook 返回 `deny`，操作将被阻止，无论其他 hooks 如何。

326</CodeGroup>326</CodeGroup>

327 327

328<Note>328<Note>

329 使用 `updatedInput` 时，您还必须包括 `permissionDecision: 'allow'`。始终返回新对象而不是改变原始 `tool_input`。329 使用 `updatedInput` 时，您还必须包括 `permissionDecision: 'allow'` 以自动批准修改的输入，或 `permissionDecision: 'ask'` 以将其显示给用户。使用 `'defer'` 时，`updatedInput` 会被忽略。始终返回新对象而不是改变原始 `tool_input`。

330</Note>330</Note>

331 331

332### 添加上下文并阻止工具332### 添加上下文并阻止工具

489 489

490### 跟踪子代理活动490### 跟踪子代理活动

491 491

492使用 `SubagentStop` hooks 监控子代理何时完成其工作。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hook-input) 和 [Python](/zh-CN/agent-sdk/python#hook-input) SDK 参考中的完整输入类型。此示例在每次子代理完成时记录摘要：492使用 `SubagentStop` hooks 监控子代理何时完成其工作。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整输入类型。此示例在每次子代理完成时记录摘要：

493 493

494<CodeGroup>494<CodeGroup>

495 ```python Python theme={null}495 ```python Python theme={null}

621 621

622### 将通知转发到 Slack622### 将通知转发到 Slack

623 623

624使用 `Notification` hooks 从代理接收系统通知并将其转发到外部服务。通知针对特定事件类型触发：`permission_prompt`（Claude 需要权限）、`idle_prompt`（Claude 等待输入）、`auth_success`（身份验证完成）和 `elicitation_dialog`（Claude 提示用户）。每个通知包括一个带有人类可读描述的 `message` 字段，以及可选的 `title`。624使用 `Notification` hooks 从代理接收系统通知并将其转发到外部服务。通知针对特定事件类型触发：`permission_prompt`（Claude 需要权限）、`idle_prompt`（Claude 等待输入）、`auth_success`（身份验证完成）、`elicitation_dialog`（Claude 提示用户）、`elicitation_response`（用户回答了引导）和 `elicitation_complete`（引导已关闭）。每个通知包括一个带有人类可读描述的 `message` 字段，以及可选的 `title`。

625 625

626此示例将每个通知转发到 Slack 频道。它需要一个 [Slack 传入 webhook URL](https://api.slack.com/messaging/webhooks)，您可以通过将应用添加到您的 Slack 工作区并启用传入 webhooks 来创建：626此示例将每个通知转发到 Slack 频道。它需要一个 [Slack 传入 webhook URL](https://api.slack.com/messaging/webhooks)，您可以通过将应用添加到您的 Slack 工作区并启用传入 webhooks 来创建：

627 627

727* 检查您的匹配器模式是否与工具名称完全匹配727* 检查您的匹配器模式是否与工具名称完全匹配

728* 确保 hook 在 `options.hooks` 中的正确事件类型下728* 确保 hook 在 `options.hooks` 中的正确事件类型下

729* 对于非工具 hooks，如 `Stop` 和 `SubagentStop`，匹配器匹配不同的字段（请参阅[匹配器模式](/zh-CN/hooks#matcher-patterns)）729* 对于非工具 hooks，如 `Stop` 和 `SubagentStop`，匹配器匹配不同的字段（请参阅[匹配器模式](/zh-CN/hooks#matcher-patterns)）

730* 当代理达到 [`max_turns`](/zh-CN/agent-sdk/python#claude-agent-options) 限制时，hooks 可能不会触发，因为会话在 hooks 可以执行前结束730* 当代理达到 [`max_turns`](/zh-CN/agent-sdk/python#claudeagentoptions) 限制时，hooks 可能不会触发，因为会话在 hooks 可以执行前结束

731 731

732### 匹配器未按预期过滤732### 匹配器未按预期过滤

733 733

769 };769 };

770 ```770 ```

771 771

772* 您还必须返回 `permissionDecision: 'allow'` 以使输入修改生效772* 您还必须返回 `permissionDecision: 'allow'` 或 `'ask'` 以使输入修改生效

773 773

774* 在 `hookSpecificOutput` 中包括 `hookEventName` 以识别输出针对的 hook 类型774* 在 `hookSpecificOutput` 中包括 `hookEventName` 以识别输出针对的 hook 类型

775 775

776### Python 中不可用会话 hooks776### Python 中不可用会话 hooks

777 777

778`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中注册为 SDK 回调 hooks，但在 Python SDK 中不可用（`HookEvent` 省略了它们）。在 Python 中，它们仅作为[shell 命令 hooks](/zh-CN/hooks#hook-events) 在设置文件中定义（例如 `.claude/settings.json`）。要从您的 SDK 应用程序加载 shell 命令 hooks，请使用 [`setting_sources`](/zh-CN/agent-sdk/python#setting-source) 或 [`settingSources`](/zh-CN/agent-sdk/typescript#setting-source) 包括适当的设置源：778`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中注册为 SDK 回调 hooks，但在 Python SDK 中不可用（`HookEvent` 省略了它们）。在 Python 中，它们仅作为[shell 命令 hooks](/zh-CN/hooks#hook-events) 在设置文件中定义（例如 `.claude/settings.json`）。要从您的 SDK 应用程序加载 shell 命令 hooks，请使用 [`setting_sources`](/zh-CN/agent-sdk/python#settingsource) 或 [`settingSources`](/zh-CN/agent-sdk/typescript#settingsource) 包括适当的设置源：

779 779

780<CodeGroup>780<CodeGroup>

781 ```python Python theme={null}781 ```python Python theme={null}

agent-sdk/modifying-system-prompts.md +431 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 修改系统提示词

7> 在 `claude_code` 预设和自定义系统提示词之间进行选择，并通过 CLAUDE.md、输出样式、追加或完全自定义提示词来自定义行为。

9系统提示词定义了 Claude 的行为、能力和响应风格。从用于 CLI 或 IDE 类编码工具的 `claude_code` 预设开始，其中人类观察并指导工作。为具有不同界面、身份或权限模型的代理编写自己的提示词。

11本页涵盖：

13* [系统提示词如何工作](#how-system-prompts-work)，包含一个决策表，用于在预设、带有 `append` 的预设和自定义提示词之间进行选择

14* [自定义代理行为](#customize-agent-behavior)，使用 CLAUDE.md 文件、输出样式、`append` 或自定义字符串

15* [比较四种方法](#compare-the-four-approaches)，按持久性、范围和它们保留的内容进行比较

16* [组合方法](#combine-approaches)，将自定义方法分层组合在一起

18## 系统提示词的工作原理

20系统提示词是初始指令集，它塑造了 Claude 在整个对话中的行为方式。Agent SDK 有三个起点：

22* **最小默认值**：当你在 TypeScript 中不设置 `systemPrompt` 或在 Python 中不设置 `system_prompt` 时，SDK 使用最小提示词，涵盖工具调用但省略了 Claude Code 的编码指南、响应风格和项目上下文。这与 `claude -p` 不同，后者默认使用完整的 Claude Code 提示词。如果你从 CLI 迁移并想要匹配的行为，请设置 `claude_code` 预设。

23* **`claude_code` 预设**：Claude Code CLI 使用的完整系统提示词，包含工具使用说明、代码风格和格式化指南、响应语气和详细程度规则、安全和安全指令，以及关于工作目录和环境的上下文。在 TypeScript 中设置 `systemPrompt: { type: "preset", preset: "claude_code" }`，或在 Python 中设置 `system_prompt={"type": "preset", "preset": "claude_code"}`，可选择使用 `append` 在末尾添加你自己的指令。

24* **自定义字符串**：你自己编写的提示词。SDK 仅发送你提供的内容。

26### 决定起点

28决定因素是你的代理与 Claude Code 的相似程度：一个在存储库中运行的编码代理，有人类观看流式输出并指导工作。你的产品离这个越远，你就越想编写自己的提示词。

30| 你正在构建 | 使用 | 你获得的内容 |

31| :--------------------------------------------------- | :------------------------- | :-------------------------------------------- |

32| 一个 CLI 或类似 IDE 的编码工具，其中人类观看和指导，Claude Code 的默认值是你想要的 | `claude_code` 预设 | 完整的 Claude Code 提示词：工具指导、安全规则、终端友好的响应、存储库约定感知 |

33| 相同类型的工具，加上产品特定的规则，如编码标准、输出格式或域上下文 | `claude_code` 预设加 `append` | 上述所有内容，加上你的指令添加在预设之后。没有任何内容被删除，所以这是风险最低的自定义 |

34| 具有不同表面、身份或权限模型的代理，或非编码代理 | 自定义提示词字符串 | 仅你编写的内容。你负责替换你的代理仍然需要的工具指导和安全指令 |

35| 一个薄工具调用循环，没有代理角色，你在用户提示词中提供所有行为 | 无 `systemPrompt` 选项 | 最小默认值：工具调用支持，仅此而已 |

37"不同于 Claude Code" 通常意味着以下之一：

39* **不同的表面**：输出不是由触发它的人在终端中读取的。聊天 UI、结构化输出消费者和非编码自动化各自需要一个与其输出呈现和审查方式相匹配的提示词。无人值守的编码自动化，如修复 lint 错误或审查差异的 CI 作业，仍然适合预设，因为工作本身就是预设为之编写的。

40* **不同的身份**：代理不应该将自己呈现为 Claude Code。支持机器人、数据分析助手或任何特定领域的代理需要自己的名称、范围和角色。

41* **不同的权限模型**：代理自主运行，无需人类批准每一步，或在一组狭窄的资源上运行。Claude Code 的提示词假设人类在循环中，可以访问完整的工具集。

42* **非编码任务**：Claude Code 提示词的大部分是编码指导。对于研究、内容或运营代理，该指导与你实际需要的指令竞争。

44[比较表](#compare-the-four-approaches)显示了每种自定义方法保留的内容。

46## 自定义 agent 行为

48输出样式、`append` 和自定义提示词字符串各自直接改变系统提示词。CLAUDE.md 采用不同的方式：SDK 读取它并将其内容作为项目上下文注入到对话中，而不是注入到系统提示词中，因此它与你选择的任何系统提示词一起塑造行为。[Skills](/zh-CN/agent-sdk/skills)、[hooks](/zh-CN/agent-sdk/hooks) 和 [permissions](/zh-CN/agent-sdk/permissions) 也在系统提示词之外塑造行为，并在各自的页面上介绍。

50### CLAUDE.md 文件用于项目级指令

52CLAUDE.md 文件为 Claude 提供持久的项目上下文和指令。SDK 将其内容注入到对话中，而不是注入到系统提示词中，因此它们可以与任何系统提示词配置一起工作。关于在 CLAUDE.md 中放什么、在哪里放置它以及如何编写有效的指令，请参阅 [Claude 如何记住你的项目](/zh-CN/memory)。本节涵盖 SDK 特定的内容：CLAUDE.md 如何加载。

54当匹配的设置源被启用时，SDK 读取 CLAUDE.md：`'project'` 从工作目录加载 `CLAUDE.md` 或 `.claude/CLAUDE.md`，`'user'` 加载 `~/.claude/CLAUDE.md`。默认 `query()` 选项启用两个源，因此 CLAUDE.md 会自动加载。如果你在 TypeScript 中显式设置 `settingSources` 或在 Python 中设置 `setting_sources`，请包含你需要的源。CLAUDE.md 加载由设置源控制，而不是由 `claude_code` 预设控制。

56#### 使用 SDK 加载 CLAUDE.md

58要加载 CLAUDE.md，请设置 `settingSources` 以包含你的 CLAUDE.md 所在的级别。下面的示例加载项目级 CLAUDE.md 以及 `claude_code` 预设，因此 Claude 既有完整的编码 agent 提示词，也有你的项目约定：

60<CodeGroup>

61 ```typescript TypeScript theme={null}

62 import { query } from "@anthropic-ai/claude-agent-sdk";

64 const messages = [];

66 for await (const message of query({

67 prompt: "Add a new React component for user profiles",

68 options: {

69 systemPrompt: {

70 type: "preset",

71 preset: "claude_code" // 使用 Claude Code 的系统提示词

72 },

73 settingSources: ["project"] // 从项目加载 CLAUDE.md

74 }

75 })) {

76 messages.push(message);

77 }

79 // 现在 Claude 可以访问来自 CLAUDE.md 的项目指南

80 ```

82 ```python Python theme={null}

83 from claude_agent_sdk import query, ClaudeAgentOptions

85 messages = []

87 async for message in query(

88 prompt="Add a new React component for user profiles",

89 options=ClaudeAgentOptions(

90 system_prompt={

91 "type": "preset",

92 "preset": "claude_code", # 使用 Claude Code 的系统提示词

93 },

94 setting_sources=["project"], # 从项目加载 CLAUDE.md

95 ),

96 ):

97 messages.append(message)

99 # 现在 Claude 可以访问来自 CLAUDE.md 的项目指南

100 ```

101</CodeGroup>

102

103CLAUDE.md 在项目的所有会话中持久存在，通过 git 与你的团队共享，并自动发现而无需代码更改。如果你传递空的 `settingSources` 数组，则不会加载。

104

105### 输出样式用于持久配置

106

107输出样式是保存的配置，可以修改 Claude 的系统提示词。它们存储为 markdown 文件，可以在会话和项目中重复使用。

108

109#### 创建输出样式

110

111输出样式是一个 markdown 文件，其 frontmatter 中有 `name` 和 `description`，后面是提示词内容。将其保存到 `~/.claude/output-styles/` 以获得在每个项目中可用的用户级样式，或保存到你的存储库中的 `.claude/output-styles/` 以获得可以提交和与你的团队共享的项目级样式。

112

113下面的示例定义了一个代码审查角色。将其保存为 `~/.claude/output-styles/code-reviewer.md` 以在项目中可用：

114

115```markdown ~/.claude/output-styles/code-reviewer.md theme={null}

116---

117name: Code Reviewer

118description: Thorough code review assistant

119---

120

121You are an expert code reviewer.

122

123For every code submission:

1241. Check for bugs and security issues

1252. Evaluate performance

1263. Suggest improvements

1274. Rate code quality (1-10)

128```

129

130#### 激活输出样式

131

132创建后，通过以下方式激活输出样式：

133

134* **CLI**：运行 `/config` 并选择输出样式

135* **设置**：在 `.claude/settings.local.json` 中设置 `outputStyle`

136* **TypeScript SDK**：将 `options.outputStyle` 设置为样式的名称

137

138Python SDK 没有以编程方式选择输出样式的选项。对于无法写入 `.claude/settings.local.json` 的仅代码部署，请改用 `append` 或自定义提示词字符串。

139

140**SDK 用户注意：** 当你在选项中包含 `settingSources: ['user']` 或 `settingSources: ['project']`（TypeScript）/ `setting_sources=["user"]` 或 `setting_sources=["project"]`（Python）时，输出样式会被加载。

141

142### 追加到 `claude_code` 预设

143

144你可以使用带有 `append` 属性的 Claude Code 预设来添加自定义指令，同时保留所有内置功能。

145

146<CodeGroup>

147 ```typescript TypeScript theme={null}

148 import { query } from "@anthropic-ai/claude-agent-sdk";

149

150 const messages = [];

151

152 for await (const message of query({

153 prompt: "Help me write a Python function to calculate fibonacci numbers",

154 options: {

155 systemPrompt: {

156 type: "preset",

157 preset: "claude_code",

158 append: "Always include detailed docstrings and type hints in Python code."

159 }

160 }

161 })) {

162 messages.push(message);

163 if (message.type === "assistant") {

164 console.log(message.message.content);

165 }

166 }

167 ```

168

169 ```python Python theme={null}

170 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

171

172 messages = []

173

174 async for message in query(

175 prompt="Help me write a Python function to calculate fibonacci numbers",

176 options=ClaudeAgentOptions(

177 system_prompt={

178 "type": "preset",

179 "preset": "claude_code",

180 "append": "Always include detailed docstrings and type hints in Python code.",

181 }

182 ),

183 ):

184 messages.append(message)

185 if isinstance(message, AssistantMessage):

186 print(message.content)

187 ```

188</CodeGroup>

189

190#### 改进跨用户和机器的提示词缓存

191

192默认情况下，两个使用相同 `claude_code` 预设和 `append` 文本的会话，如果从不同的工作目录运行，仍然无法共享提示词缓存条目。这是因为预设在你的 `append` 文本之前在系统提示词中嵌入了每个会话的上下文：工作目录、它是否是 git 存储库、平台、活跃的 shell、操作系统版本和自动记忆路径。该上下文中的任何差异都会产生不同的系统提示词和缓存未命中。CLAUDE.md 内容不会影响系统提示词缓存，因为 SDK 将其注入到对话中，而不是系统提示词。

193

194要使系统提示词在会话中相同，请在 TypeScript 中设置 `excludeDynamicSections: true`，或在 Python 中设置 `"exclude_dynamic_sections": True`。每个会话的上下文移动到第一条用户消息中，只在系统提示词中保留静态预设和你的 `append` 文本，以便相同的配置在用户和机器之间共享缓存条目。

195

196<Note>

197 `excludeDynamicSections` 需要 `@anthropic-ai/claude-agent-sdk` v0.2.98 或更高版本，或 Python 的 `claude-agent-sdk` v0.1.58 或更高版本。它仅适用于预设对象形式，当 `systemPrompt` 是字符串时无效。

198</Note>

199

200以下示例将共享的 `append` 块与 `excludeDynamicSections` 配对，以便从不同目录运行的 agent 群可以重复使用相同的缓存系统提示词：

201

202<CodeGroup>

203 ```typescript TypeScript theme={null}

204 import { query } from "@anthropic-ai/claude-agent-sdk";

205

206 for await (const message of query({

207 prompt: "Triage the open issues in this repo",

208 options: {

209 systemPrompt: {

210 type: "preset",

211 preset: "claude_code",

212 append: "You operate Acme's internal triage workflow. Label issues by component and severity.",

213 excludeDynamicSections: true

214 }

215 }

216 })) {

217 // ...

218 }

219 ```

220

221 ```python Python theme={null}

222 from claude_agent_sdk import query, ClaudeAgentOptions

223

224 async for message in query(

225 prompt="Triage the open issues in this repo",

226 options=ClaudeAgentOptions(

227 system_prompt={

228 "type": "preset",

229 "preset": "claude_code",

230 "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",

231 "exclude_dynamic_sections": True,

232 },

233 ),

234 ):

235 ...

236 ```

237</CodeGroup>

238

239**权衡：** 工作目录、git 存储库标志、平台、活跃的 shell、操作系统版本和自动记忆路径仍然会到达 Claude，但作为第一条用户消息的一部分，而不是系统提示词。用户消息中的指令比系统提示词中的相同文本的权重略低，因此在推理当前目录或自动记忆路径时，Claude 可能会更少地依赖它们。当跨会话缓存重复使用比最大化权威环境上下文更重要时，启用此选项。

240

241对于非交互式 CLI 模式中的等效标志，请参阅 [`--exclude-dynamic-system-prompt-sections`](/zh-CN/cli-reference)。

242

243### 自定义系统提示词

244

245你可以提供自定义字符串作为 `systemPrompt` 以完全用你自己的指令替换默认值。

246

247<CodeGroup>

248 ```typescript TypeScript theme={null}

249 import { query } from "@anthropic-ai/claude-agent-sdk";

250

251 const customPrompt = `You are a Python coding specialist.

252 Follow these guidelines:

253 - Write clean, well-documented code

254 - Use type hints for all functions

255 - Include comprehensive docstrings

256 - Prefer functional programming patterns when appropriate

257 - Always explain your code choices`;

258

259 const messages = [];

260

261 for await (const message of query({

262 prompt: "Create a data processing pipeline",

263 options: {

264 systemPrompt: customPrompt

265 }

266 })) {

267 messages.push(message);

268 if (message.type === "assistant") {

269 console.log(message.message.content);

270 }

271 }

272 ```

273

274 ```python Python theme={null}

275 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

276

277 custom_prompt = """You are a Python coding specialist.

278 Follow these guidelines:

279 - Write clean, well-documented code

280 - Use type hints for all functions

281 - Include comprehensive docstrings

282 - Prefer functional programming patterns when appropriate

283 - Always explain your code choices"""

284

285 messages = []

286

287 async for message in query(

288 prompt="Create a data processing pipeline",

289 options=ClaudeAgentOptions(system_prompt=custom_prompt),

290 ):

291 messages.append(message)

292 if isinstance(message, AssistantMessage):

293 print(message.content)

294 ```

295</CodeGroup>

296

297## 比较四种方法

298

299这四种自定义方法在存储位置、共享方式以及从 `claude_code` 预设保留的内容方面有所不同。

300

302| --------- | --------- | -------- | -------------------- | ------------------ |

303| **持久性** | 每个项目文件 | 保存为文件 | 仅会话 | 仅会话 |

304| **可重用性** | 每个项目 | 跨项目 | 代码重复 | 代码重复 |

305| **管理** | 在文件系统上 | CLI + 文件 | 在代码中 | 在代码中 |

306| **默认工具** | 保留 | 保留 | 保留 | 丢失（除非包含） |

307| **内置安全** | 维护 | 维护 | 维护 | 必须添加 |

308| **环境上下文** | 自动 | 自动 | 自动 | 必须提供 |

309| **自定义级别** | 仅添加 | 替换默认 | 仅添加 | 完全控制 |

310| **版本控制** | 与项目一起 | 是 | 与代码一起 | 与代码一起 |

311| **范围** | 项目特定 | 用户或项目 | 代码会话 | 代码会话 |

312

313"带有追加"是指在 TypeScript 中使用 `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }`，或在 Python 中使用 `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}`。CLAUDE.md 不会改变系统提示本身：SDK 将其内容作为项目上下文注入到对话中。

314

315## 用例和最佳实践

316

317### 何时使用 CLAUDE.md

318

319使用 CLAUDE.md 来存储应该应用于项目中每个会话的指令，无论该会话使用哪个系统提示词：编码标准、常见命令、架构上下文和团队约定。CLAUDE.md 被提交到你的存储库，因此它与它描述的代码保持同步。有关完整指导，请参阅 [何时添加到 CLAUDE.md](/zh-CN/memory#when-to-add-to-claude-md)。

320

321当启用 `project` 设置源时，CLAUDE.md 文件会加载，这对默认的 `query()` 选项是这样的。如果你显式设置 `settingSources`（TypeScript）或 `setting_sources`（Python），请包含 `'project'` 以继续加载项目级 CLAUDE.md。

322

323### 何时使用输出样式

324

325输出样式用于你想在 CLI 和 SDK 中重复使用的角色，而无需更改应用程序代码。因为它们作为文件存在于 `.claude/output-styles` 中，同一个角色可从 CLI 中的 `/config` 和加载匹配设置源的任何 SDK 会话中获得。

326

327**最适合：**

328

329* 跨会话的持久行为更改

330* 团队共享配置

331* 专门的助手，如代码审查者、数据科学家或 DevOps 助手

332* 需要版本控制的复杂提示词修改

333

334**示例：**

335

336* 创建专用的 SQL 优化助手

337* 构建安全聚焦的代码审查者

338* 开发具有特定教学法的教学助手

339

340### 何时使用带有追加的 `systemPrompt`

341

342当 `claude_code` 预设已经适合你的产品，而你只需要添加额外指令时，使用 `append`。你保留预设的工具指导、安全规则和编码约定，而无需重新实现它们。

343

344**最适合：**

345

346* 添加特定的编码标准或偏好

347* 自定义输出格式

348* 添加特定领域的知识

349* 修改响应详细程度

350* 增强 Claude Code 的默认行为而不失去工具指令

351

352### 何时使用自定义 `systemPrompt`

353

354当你的代理的表面、身份或权限模型与 Claude Code 的不同时，使用自定义提示词，如 [决定起点](#decide-on-a-starting-point) 中所述。你定义完整的指令集，包括你的代理需要的任何工具指导和安全规则。

355

356**最适合：**

357

358* 完全控制 Claude 的行为

359* 专门的单会话任务

360* 测试新的提示词策略

361* 不需要默认工具的情况

362* 构建具有独特行为的专门代理

363

364## 组合方法

365

366这些方法可以组合使用。持久化的输出样式或 CLAUDE.md 设置长期行为，而 `append` 在不触及保存配置的情况下在顶部分层会话特定的指令。

367

368### 将输出样式与会话特定的添加组合

369

370下面的示例假设代码审查员输出样式已经处于活动状态。`append` 块在角色的基础上分层会话特定的焦点区域，因此单个审查会话可以优先考虑 OAuth 和令牌存储，而无需更改保存的输出样式：

371

372<CodeGroup>

373 ```typescript TypeScript theme={null}

374 import { query } from "@anthropic-ai/claude-agent-sdk";

375

376 // 假设"Code Reviewer"输出样式处于活动状态（通过 /config 或设置）

377 // 添加会话特定的焦点区域

378 const messages = [];

379

380 for await (const message of query({

381 prompt: "Review this authentication module",

382 options: {

383 systemPrompt: {

384 type: "preset",

385 preset: "claude_code",

386 append: `

387 For this review, prioritize:

388 - OAuth 2.0 compliance

389 - Token storage security

390 - Session management

391 `

392 }

393 }

394 })) {

395 messages.push(message);

396 }

397 ```

398

399 ```python Python theme={null}

400 from claude_agent_sdk import query, ClaudeAgentOptions

401

402 # 假设"Code Reviewer"输出样式处于活动状态（通过 /config 或设置）

403 # 添加会话特定的焦点区域

404 messages = []

405

406 async for message in query(

407 prompt="Review this authentication module",

408 options=ClaudeAgentOptions(

409 system_prompt={

410 "type": "preset",

411 "preset": "claude_code",

412 "append": """

413 For this review, prioritize:

414 - OAuth 2.0 compliance

415 - Token storage security

416 - Session management

417 """,

418 }

419 ),

420 ):

421 messages.append(message)

422 ```

423</CodeGroup>

424

425## 另请参阅

426

427* [输出样式](/zh-CN/output-styles)：为 CLI 创建、管理和共享输出样式，包括文件格式和存储位置

428* [Claude 如何记住您的项目](/zh-CN/memory)：CLAUDE.md 中应放入的内容、放置位置以及如何编写有效的项目说明

429* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript)：完整的 `Options` 类型，包括 `systemPrompt`、`settingSources` 和 `outputStyle`

430* [Python SDK 参考](/zh-CN/agent-sdk/python)：完整的 `ClaudeAgentOptions` 类型，包括 `system_prompt` 和 `setting_sources`

431* [Settings](/zh-CN/settings)：`settings.json` 参考，包括输出样式和其他配置的存储位置

agent-sdk/typescript.md +13 −12

Details

396| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |396| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |

398| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 为代理结果定义输出格式。请参阅[结构化输出](/zh-CN/agent-sdk/structured-outputs)了解详情 |398| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 为代理结果定义输出格式。请参阅[结构化输出](/zh-CN/agent-sdk/structured-outputs)了解详情 |

399| `outputStyle` | `string` | `undefined` | 要为会话激活的[输出样式](/zh-CN/output-styles)的名称。该样式必须存在于加载的 `settingSources` 位置，例如 `.claude/output-styles/`。请参阅[激活输出样式](/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style) |

411| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置。请参阅[使用 Claude Code 功能](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |412| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置。请参阅[使用 Claude Code 功能](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

474#### 方法475#### 方法

475 476

476| 方法 | 描述 |477| 方法 | 描述 |

477| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |478| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

479| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件检查点](/zh-CN/agent-sdk/file-checkpointing) |480| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/zh-CN/agent-sdk/file-checkpointing) |

587| `prompt` | 是 | 代理的系统提示 |588| `prompt` | 是 | 代理的系统提示 |

588| `model` | 否 | 此代理的模型覆盖。接受别名，如 `'sonnet'`、`'opus'`、`'haiku'`、`'inherit'`，或完整的模型 ID。如果省略或 `'inherit'`，使用主模型 |589| `model` | 否 | 此代理的模型覆盖。接受别名，如 `'sonnet'`、`'opus'`、`'haiku'`、`'inherit'`，或完整的模型 ID。如果省略或 `'inherit'`，使用主模型 |

589| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |590| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |

590| `skills` | 否 | 要预加载到代理上下文中的技能名称数组 |591| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |

591| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |592| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |

592| `maxTurns` | 否 | 停止前的最大代理轮次数（API 往返） |593| `maxTurns` | 否 | 停止前的最大代理轮次数（API 往返） |

593| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |594| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |

726 | "default" // 标准权限行为727 | "default" // 标准权限行为

727 | "acceptEdits" // 自动接受文件编辑728 | "acceptEdits" // 自动接受文件编辑

728 | "bypassPermissions" // 绕过所有权限检查729 | "bypassPermissions" // 绕过所有权限检查

729 | "plan" // 规划模式 - 仅读取工具730 | "plan" // Plan Mode - 仅读取工具

730 | "dontAsk" // 不提示权限，如果未预先批准则拒绝731 | "dontAsk" // 不提示权限，如果未预先批准则拒绝

731 | "auto"; // 使用模型分类器批准或拒绝每个工具调用732 | "auto"; // 使用模型分类器批准或拒绝每个工具调用

732```733```

860 861

861### `SdkPluginConfig`862### `SdkPluginConfig`

862 863

863SDK 中加载插件的配置。864SDK 中加载 plugins 的配置。

864 865

865```typescript theme={null}866```typescript theme={null}

866type SdkPluginConfig = {867type SdkPluginConfig = {

870```871```

871 872

872| 字段 | 类型 | 描述 |873| 字段 | 类型 | 描述 |

873| :----- | :-------- | :----------------------- |874| :----- | :-------- | :----------------------------- |

876 877

877**示例：**878**示例：**

883];884];

884```885```

885 886

886有关创建和使用插件的完整信息，请参阅[plugins](/zh-CN/agent-sdk/plugins)。887有关创建和使用 plugins 的完整信息，请参阅[Plugins](/zh-CN/agent-sdk/plugins)。

887 888

888## 消息类型889## 消息类型

889 890

agent-sdk/user-input.md +47 −1

Details

12 12

13对于澄清问题，Claude 生成问题和选项。您的角色是向用户呈现这些问题，并返回他们的选择。您不能向此流程添加自己的问题；如果您需要自己询问用户某些内容，请在应用程序逻辑中单独进行。13对于澄清问题，Claude 生成问题和选项。您的角色是向用户呈现这些问题，并返回他们的选择。您不能向此流程添加自己的问题；如果您需要自己询问用户某些内容，请在应用程序逻辑中单独进行。

14 14

15回调可以无限期地保持待处理状态。执行保持暂停状态，直到您的回调返回，SDK 仅在查询本身被取消时才取消等待。如果用户可能需要比您的进程能够合理保持运行的时间更长的时间来响应，TypeScript SDK 支持 [`defer` hook 决定](/zh-CN/hooks#defer-a-tool-call-for-later)，它允许进程退出并稍后从持久化会话恢复；此选项在 Python SDK 中不可用。15回调可以无限期地保持待处理状态。执行保持暂停状态，直到您的回调返回，SDK 仅在查询本身被取消时才取消等待。如果用户可能需要比您的进程能够合理保持运行的时间更长的时间来响应，请返回 [`defer` hook 决定](/zh-CN/hooks#defer-a-tool-call-for-later)，它允许进程退出并稍后从持久化会话恢复。

16 16

17本指南向您展示如何检测每种类型的请求并做出适当的响应。17本指南向您展示如何检测每种类型的请求并做出适当的响应。

18 18

232 232

233* **批准**：让工具按 Claude 请求的方式执行233* **批准**：让工具按 Claude 请求的方式执行

234* **批准并进行更改**：在执行前修改输入（例如，清理路径、添加约束）234* **批准并进行更改**：在执行前修改输入（例如，清理路径、添加约束）

235* **批准并记住**：回显建议的权限规则，以便匹配的调用在下次跳过提示

235* **拒绝**：阻止工具并告诉 Claude 原因236* **拒绝**：阻止工具并告诉 Claude 原因

236* **建议替代方案**：阻止但指导 Claude 朝向用户想要的方向237* **建议替代方案**：阻止但指导 Claude 朝向用户想要的方向

237* **完全重定向**：使用[流输入](/zh-CN/agent-sdk/streaming-vs-single-mode)向 Claude 发送全新指令238* **完全重定向**：使用[流输入](/zh-CN/agent-sdk/streaming-vs-single-mode)向 Claude 发送全新指令

297 </CodeGroup>298 </CodeGroup>

298 </Tab>299 </Tab>

299 300

301 <Tab title="批准并记住">

302 用户批准并且不想再被询问此类调用。第三个回调参数携带 `suggestions`，一个现成的 [`PermissionUpdate`](/zh-CN/agent-sdk/typescript#permissionupdate) 条目数组。在 `updatedPermissions` 中回显其中一个以应用它。带有 `localSettings` 目标的建议会将规则写入 `.claude/settings.local.json`，以便将来的会话跳过匹配调用的提示。

303

304 Python 示例需要 `claude-agent-sdk` 0.1.80 或更高版本。

305

306 <CodeGroup>

307 ```python Python theme={null}

308 async def can_use_tool(tool_name, input_data, context):

309 choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

310

311 if choice == "always":

312 persist = [

313 s for s in context.suggestions if s.destination == "localSettings"

314 ]

315 return PermissionResultAllow(

316 updated_input=input_data, updated_permissions=persist

317 )

318 if choice == "once":

319 return PermissionResultAllow(updated_input=input_data)

320 return PermissionResultDeny(message="User declined")

321 ```

322

323 ```typescript TypeScript theme={null}

324 canUseTool: async (toolName, input, { suggestions = [] }) => {

325 const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

326

327 if (choice === "always") {

328 const persist = suggestions.filter(

329 (s) => s.destination === "localSettings"

330 );

331 return {

332 behavior: "allow",

333 updatedInput: input,

334 updatedPermissions: persist

335 };

336 }

337 if (choice === "once") {

338 return { behavior: "allow", updatedInput: input };

339 }

340 return { behavior: "deny", message: "User declined" };

341 };

342 ```

343 </CodeGroup>

344 </Tab>

345

300 <Tab title="拒绝">346 <Tab title="拒绝">

301 用户不希望发生此操作。阻止工具并提供说明原因的消息。Claude 会看到此消息并可能尝试不同的方法。347 用户不希望发生此操作。阻止工具并提供说明原因的消息。Claude 会看到此消息并可能尝试不同的方法。

302 348

agent-teams.md +2 −0

Details

129Use Sonnet for each teammate.129Use Sonnet for each teammate.

130```130```

131 131

132队友默认不继承负责人的 `/model` 选择。要更改在提示未指定模型时使用的模型，在 `/config` 中设置**默认队友模型**。选择\*\*默认（负责人的模型）\*\*以让队友遵循负责人的当前模型。

133

132### 要求队友的计划批准134### 要求队友的计划批准

133 135

134对于复杂或有风险的任务，你可以要求队友在实施前进行规划。队友在只读计划模式下工作，直到负责人批准他们的方法：136对于复杂或有风险的任务，你可以要求队友在实施前进行规划。队友在只读计划模式下工作，直到负责人批准他们的方法：

agent-view.md +35 −16

Details

38 </Step>38 </Step>

39 39

40 <Step title="调度一个会话">40 <Step title="调度一个会话">

~~41 在输入框中输入提示并按 `Enter`。一个新会话启动并显示为一行，显示它是否正在工作、等待你或已完成。重复以并行运行尽可能多的会话。~~41 在输入框中输入提示并按 `Enter`。一个新会话启动并显示为一行，显示它是否正在工作、等待你或已完成。重复以并行运行多个会话。每个会话独立使用你的订阅配额，所以在一次调度多个会话之前，请查看[限制](#limitations)。

42 </Step>42 </Step>

43 43

44 <Step title="窥视和回复">44 <Step title="窥视和回复">

58 58

59运行 `claude agents` 打开 agent view。它接管整个终端并列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动和上次更改的时间。59运行 `claude agents` 打开 agent view。它接管整个终端并列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动和上次更改的时间。

60 60

61列表对你的机器是全局的，包括每个后台会话，无论它在哪个项目或 worktree 中工作。你在其他终端中打开的交互式会话不会出现，直到你 [后台它们](#from-inside-a-session)，[subagents](/zh-CN/sub-agents) 在会话内运行不会列为单独的行。61该列表涵盖你的 [配置目录](#how-background-sessions-are-hosted) 下的每个后台会话，无论它在哪个项目或 worktree 中工作，因此在一个存储库中启动的会话和在不同 worktree 中启动的另一个会话都一起出现。你在其他终端中打开的交互式会话不会出现，直到你 [后台它们](#from-inside-a-session)，[subagents](/zh-CN/sub-agents) 在会话内运行不会列为单独的行。

62 62

63```text theme={null}63```text theme={null}

64Pinned64Pinned

65 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m65 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

66 66

67Ready for review67Ready for review

~~68 ∙ jump physics github.com/anthropics/example/pull/2048 2h~~68 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h

69 69

70Needs input70Needs input

71 ✻ power-up design needs input: double jump or wall climb? 1m71 ✻ power-up design needs input: double jump or wall climb? 1m

80 … 6 more80 … 6 more

81```81```

82 82

~~83图标告诉你会话的状态：~~83每行的图标传达两个信号。指示器告诉你会话的状态，图标的形状告诉你底层进程是否仍在运行。状态如下：

84 84

~~85| 图标 | 状态 | 含义 |~~85| 指示器 | 状态 | 含义 |

~~86| :- | :--- | :------------------------------ |~~86| :-- | :--- | :------------------------------ |

87| 动画 | 工作中 | Claude 正在积极运行工具或生成响应 |87| 动画 | 工作中 | Claude 正在积极运行工具或生成响应 |

88| 黄色 | 需要输入 | Claude 等待你的输入，通常是权限决定或答案 |88| 黄色 | 需要输入 | Claude 等待你的输入，通常是权限决定或答案 |

89| 暗淡 | 空闲 | 会话等待输入但不被特定问题阻止 |89| 暗淡 | 空闲 | 会话等待输入但不被特定问题阻止 |

91| 红色 | 失败 | 任务以错误结束 |91| 红色 | 失败 | 任务以错误结束 |

92| 灰色 | 已停止 | 会话被 `Ctrl+X` 或 `claude stop` 停止 |92| 灰色 | 已停止 | 会话被 `Ctrl+X` 或 `claude stop` 停止 |

93 93

94图标的形状告诉你底层进程是否仍在运行。`✻` 或动画 `✽` 当 Claude 工作时，意味着会话是活跃的，你可以立即回复。`∙` 意味着进程已退出，但你仍然可以窥视、回复或附加：Claude 从中断处重新启动会话。`✢` 是一个 [`/loop`](/zh-CN/commands) 会话在迭代之间休眠，行显示其运行计数和下一次迭代的倒计时。94图标的形状告诉你底层进程是否仍在运行。`✻` 或动画 `✽`（当 Claude 工作时）意味着会话是活跃的，你可以立即回复。`∙` 意味着进程已退出，但你仍然可以窥视、回复或附加：Claude 从中断处重新启动会话。`✢` 是一个 [`/loop`](/zh-CN/commands) 会话在迭代之间休眠，行显示其运行计数和下一次迭代的倒计时。

95 95

96后台会话不需要任何打开的终端来继续工作。一个单独的 [监督进程](#how-background-sessions-are-hosted) 运行它们，所以你可以关闭 agent view、关闭你的 shell 或启动一个新的交互式会话，你的调度工作继续进行。96后台会话不需要任何打开的终端来继续工作。一个单独的 [监督进程](#how-background-sessions-are-hosted) 运行它们，所以你可以关闭 agent view、关闭你的 shell 或启动一个新的交互式会话，你的调度工作继续进行。

97 97

98会话在磁盘上持久化：关闭你的终端或自动更新不会丢失它们，重新打开 `claude agents` 显示它们全部。如果你的机器休眠或关闭，运行中的会话停止；用 `claude respawn --all` 重新启动它们。98会话在磁盘上持久化：关闭你的终端或自动更新不会丢失它们，重新打开 `claude agents` 显示它们全部。如果你的机器休眠或关闭，运行中的会话停止；用 `claude respawn --all` 重新启动它们。

99 99

100每行中的单行摘要由你配置的 [Haiku-class 模型](/zh-CN/model-config) 生成，所以行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。每个摘要是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的 [数据使用条款](/zh-CN/data-usage) 计费和处理。100每行中的单行摘要由你配置的 [Haiku-class 模型](/zh-CN/model-config) 生成，所以行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒刷新一次，加上每个回合结束时刷新一次。每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的 [数据使用条款](/zh-CN/data-usage) 计费和处理。

101 101

102当会话打开拉取请求时，行显示 PR 链接和其 CI 检查的状态指示器。对于大多数任务，这行是你收集工作的方式：当其检查通过时审查和合并拉取请求。102当会话打开拉取请求时，状态点出现在行的右边缘，在支持超链接的终端中链接到拉取请求。当会话打开了多个拉取请求时，计数出现在点之前，颜色反映最需要关注的那个。

103

104| 点的颜色 | 拉取请求状态 |

105| :--- | :------------ |

106| 黄色 | 等待检查或审查，或检查失败 |

107| 绿色 | 检查通过且没有审查阻止 |

108| 紫色 | 已合并 |

109| 灰色 | 草稿或已关闭 |

110

111对于大多数任务，这行是你收集结果的地方：当点变绿时审查和合并拉取请求。

103 112

104### 窥视和回复113### 窥视和回复

105 114

119 128

120分离永远不会停止后台会话：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都让它运行。要从内部结束会话，运行 `/stop`。129分离永远不会停止后台会话：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都让它运行。要从内部结束会话，运行 `/stop`。

121 130

122一旦你使用了 agent view，在空提示上按 `←` 从任何 Claude Code 会话工作，不仅仅是你附加的会话。它打开 agent view，你的当前会话预选，所以你可以在不离开终端的情况下切换会话。131一旦你调度或后台了会话，在空提示上按 `←` 从任何 Claude Code 会话工作，不仅仅是你从 agent view 附加的会话。它后台当前会话并打开 agent view，该会话预选，所以你可以在不离开终端的情况下切换会话。你可以在 `/config` 中关闭此快捷键。

123 132

124### 组织列表133### 组织列表

125 134

181 190

182输入 `/` 调度一个 [skill](/zh-CN/skills)。将重复任务打包为 skill 让你从 agent view 多次启动相同的工作流而无需重新输入提示。在空输入上按 `Tab` 浏览每个可调度的 subagent，或在显示建议时应用突出显示的建议。191输入 `/` 调度一个 [skill](/zh-CN/skills)。将重复任务打包为 skill 让你从 agent view 多次启动相同的工作流而无需重新输入提示。在空输入上按 `Tab` 浏览每个可调度的 subagent，或在显示建议时应用突出显示的建议。

183 192

193当相同的 `@name` 同时匹配 subagent 和同级存储库时，subagent 优先。不带 `@` 的首字形式也适用于任何 subagent 名称，所以以匹配你的某个 subagent 名称的单词开头的提示会调度该 subagent。当你想要明确指定时，使用 `@` 形式。

194

184#### 调度到特定目录195#### 调度到特定目录

185 196

186新会话在你打开 agent view 的目录中运行。要针对不同的目录：197新会话在你打开 agent view 的目录中运行。要针对不同的目录：

191 202

192当 agent view 按目录分组时，突出显示的行的目录成为调度目标，所以你可以滚动到一个组并在不重新输入路径的情况下调度到它。203当 agent view 按目录分组时，突出显示的行的目录成为调度目标，所以你可以滚动到一个组并在不重新输入路径的情况下调度到它。

193 204

194#### 在 worktree 中隔离文件编辑

~~195~~

196从 agent view 调度的会话默认共享你的工作目录，所以两个代理编辑相同的文件可能会冲突。要防止这种情况，Claude Code 阻止从 agent view 调度的会话写入文件，直到它移动到隔离的 [git worktree](/zh-CN/worktrees)。当它需要编辑文件时，Claude 自动处理这个。worktree 在项目目录内的 `.claude/worktrees/` 下创建，当你删除会话时删除。删除会话也删除其 worktree，所以在删除前合并或推送你想保留的更改。

~~197~~

198要使 subagent 始终在其自己的 worktree 中运行，无论如何启动，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)。

~~199~~

200### 从会话内部205### 从会话内部

201 206

202运行 `/background` 或其别名 `/bg` 分离当前对话并保持其运行。传递提示如 `/bg run the test suite and fix any failures` 在分离前发送一个更多指令。207运行 `/background` 或其别名 `/bg` 分离当前对话并保持其运行。传递提示如 `/bg run the test suite and fix any failures` 在分离前发送一个更多指令。

225 claude stop 7c5dcf5d stop this session230 claude stop 7c5dcf5d stop this session

226```231```

227 232

233### 文件编辑如何隔离

234

235每个后台会话，无论是从 agent view、`/bg` 还是 `claude --bg` 启动，都在你的工作目录中启动，但被阻止在那里写入文件。当会话需要编辑文件时，Claude 自动将其移动到 `.claude/worktrees/` 下的隔离 [git worktree](/zh-CN/worktrees) 中，所以并行会话可以读取相同的检出但每个都写入自己的。当会话已经在 worktree 内、工作目录不是 git 存储库或写入工作目录外时，该块不适用。

236

237当你删除会话时，worktree 被删除，所以在删除前合并或推送你想保留的更改。要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。

238

239要使 subagent 始终在其自己的 worktree 中运行，无论如何启动，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)。

240

241### 权限模式和设置

242

243调度的会话从它运行的目录读取其 [settings](/zh-CN/settings) 和 [permission mode](/zh-CN/permissions)，就像你在那里启动了 `claude` 一样。从 agent view 输入调度不传递权限模式，所以会话使用该目录设置中的 `defaultMode` 或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。

244

245要从 shell 设置模式，用 `claude --bg` 传递 `--permission-mode`。以这种方式使用 `bypassPermissions` 或 `auto` 被拒绝，直到你通过交互式运行 `claude` 一次接受该模式，因为这些模式让你没有看到的会话无需批准就能行动。

246

228## 从 shell 管理会话247## 从 shell 管理会话

229 248

230每个后台会话有一个短 ID，你可以从 shell 使用。这些命令对于脚本编写或当你不想打开 agent view 时很有用。249每个后台会话有一个短 ID，你可以从 shell 使用。这些命令对于脚本编写或当你不想打开 agent view 时很有用。

claude-directory.md +6 −3

Details

1465单击文件名以在上面的浏览器中打开该节点。1465单击文件名以在上面的浏览器中打开该节点。

1466 1466

1467| 文件 | 范围 | 提交 | 作用 | 参考 |1467| 文件 | 范围 | 提交 | 作用 | 参考 |

1468| --------------------------------------------------- | ----- | -- | ----------------------------- | ----------------------------------------------------------------------- |1468| --------------------------------------------------- | ----- | -- | ----------------------------- | ------------------------------------------------------------------ |

1470| [`rules/*.md`](#ce-rules) | 项目和全局 | ✓ | 主题范围的指令，可选择路径门控 | [Rules](/zh-CN/memory#organize-rules-with-claude/rules/) |1470| [`rules/*.md`](#ce-rules) | 项目和全局 | ✓ | 主题范围的指令，可选择路径门控 | [Rules](/zh-CN/memory#organize-rules-with-claude/rules/) |

1473| [`.mcp.json`](#ce-mcp-json) | 仅项目 | ✓ | 团队共享的 MCP 服务器 | [MCP 范围](/zh-CN/mcp#mcp-installation-scopes) |1473| [`.mcp.json`](#ce-mcp-json) | 仅项目 | ✓ | 团队共享的 MCP 服务器 | [MCP 范围](/zh-CN/mcp#mcp-installation-scopes) |

1474| [`.worktreeinclude`](#ce-worktreeinclude) | 仅项目 | ✓ | Gitignored 文件以复制到新的 worktrees | [Worktrees](/zh-CN/common-workflows#copy-gitignored-files-to-worktrees) |1474| [`.worktreeinclude`](#ce-worktreeinclude) | 仅项目 | ✓ | Gitignored 文件以复制到新的 worktrees | [Worktrees](/zh-CN/worktrees#copy-gitignored-files-into-worktrees) |

1476| [`commands/*.md`](#ce-commands) | 项目和全局 | ✓ | 单文件提示；与 skills 相同的机制 | [Skills](/zh-CN/skills) |1476| [`commands/*.md`](#ce-commands) | 项目和全局 | ✓ | 单文件提示；与 skills 相同的机制 | [Skills](/zh-CN/skills) |

1477| [`output-styles/*.md`](#ce-output-styles) | 项目和全局 | ✓ | 自定义系统提示部分 | [输出样式](/zh-CN/output-styles) |1477| [`output-styles/*.md`](#ce-output-styles) | 项目和全局 | ✓ | 自定义系统提示部分 | [输出样式](/zh-CN/output-styles) |

1497| `~/.claude/` 下的路径 | 内容 |1497| `~/.claude/` 下的路径 | 内容 |

1498| -------------------------------------------- | -------------------------------------------------------------------------------- |1498| -------------------------------------------- | -------------------------------------------------------------------------------- |

1500| `projects/<project>/<session>/subagents/` | [Subagent](/zh-CN/sub-agents) 对话记录，当父会话记录过期时被删除 |

1512以下路径不受自动清理覆盖，并无限期保留。1513以下路径不受自动清理覆盖，并无限期保留。

1513 1514

1514| `~/.claude/` 下的路径 | 内容 |1515| `~/.claude/` 下的路径 | 内容 |

1515| ------------------ | ----------------------------- |1516| ---------------------- | ---------------------------------------------------------------------------------- |

1519| `remote-settings.json` | [服务器管理的设置](/zh-CN/server-managed-settings)的缓存副本，用于您的组织。仅在您的组织配置了这些设置时才存在。在每次启动时刷新。 |

1519 1521

1520其他小缓存和锁定文件根据您使用的功能而出现，可以安全删除。1522其他小缓存和锁定文件根据您使用的功能而出现，可以安全删除。

1575| `~/.claude/remote-settings.json` | 无。在下次启动时重新获取。 |

1573| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/paste-cache/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/tasks/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 没有面向用户的内容 |1576| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/paste-cache/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/tasks/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 没有面向用户的内容 |

1575 1578

cli-reference.md +3 −1

Details

124 124

125`--system-prompt` 和 `--system-prompt-file` 互斥。附加标志可以与任一替换标志组合。125`--system-prompt` 和 `--system-prompt-file` 互斥。附加标志可以与任一替换标志组合。

126 126

127对于大多数用例，使用附加标志。附加保留 Claude Code 的内置功能，同时添加您的要求。仅当您需要对系统提示进行完全控制时，才使用替换标志。127根据 Claude Code 的默认身份是否仍然适合您的任务来选择。当 Claude 应该保持编码助手身份同时遵循您的额外规则时，使用附加标志：每次调用的指令、输出格式或 `-p` 脚本的域上下文。附加保留默认工具指导、安全指令和编码约定，因此您只需提供不同的部分。当表面、身份或权限模型与 Claude Code 的不同时，使用替换标志，例如管道中没有人监视的非编码代理。替换会删除整个默认提示，包括工具指导和安全指令，因此您需要对任务仍然需要的任何内容负责。

128

129这些标志仅适用于当前调用。对于可以在项目中切换和共享的持久化角色，请使用 [输出样式](/zh-CN/output-styles)。对于 Claude 应该始终遵循的项目约定，请使用 [CLAUDE.md](/zh-CN/memory)。[Agent SDK 系统提示指南](/zh-CN/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 更深入地涵盖了相同的决策。

128 130

129## 另请参阅131## 另请参阅

130 132

commands.md +1 −0

Details

106| `/schedule [description]` | 创建、更新、列出或运行 [routines](/zh-CN/routines)，这些 routines 在 Anthropic 管理的云基础设施上执行。Claude 会以对话方式引导您完成设置。别名：`/routines` |106| `/schedule [description]` | 创建、更新、列出或运行 [routines](/zh-CN/routines)，这些 routines 在 Anthropic 管理的云基础设施上执行。Claude 会以对话方式引导您完成设置。别名：`/routines` |

107| `/scroll-speed` | 交互式调整鼠标滚轮[滚动速度](/zh-CN/fullscreen#mouse-wheel-scrolling)，使用标尺，您可以在对话框打开时滚动以预览更改。仅在[全屏渲染](/zh-CN/fullscreen)中可用，在 JetBrains IDE 终端中不可用 |

108| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |109| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |

109| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |110| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |

data-usage.md +2 −2

Details

33* **否**：拒绝而不发送任何内容33* **否**：拒绝而不发送任何内容

34* **不再询问**：拒绝并停止此后续在未来会话中出现34* **不再询问**：拒绝并停止此后续在未来会话中出现

35 35

36除非您明确选择**是**，否则不会上传任何内容。具有[零数据保留](/zh-CN/zero-data-retention)的组织，或组织政策禁用产品反馈的组织，永远不会看到此后续。您对此调查的回应（包括评分提示后提交的会话记录）不会影响您的数据训练偏好，也不能用于训练我们的 AI 模型。36除非您明确选择**是**，否则不会上传任何内容。具有[零数据保留](/zh-CN/zero-data-retention)的组织，或组织政策禁用产品反馈的组织，或设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的组织，永远不会看到此后续。您对此调查的回应（包括评分提示后提交的会话记录）不会影响您的数据训练偏好，也不能用于训练我们的 AI 模型。

37 37

38要禁用这些调查，请设置 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。当设置 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用。要控制频率而不是禁用，请在您的设置文件中将 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置为 `0` 到 `1` 之间的概率。38要禁用这些调查，请设置 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。当设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用。具有阻止非必要流量但通过其自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)捕获调查响应的组织可以通过设置 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1` 来选择重新启用调查。然后调查仅将评分记录到配置的收集器。记录共享后续和所有其他 Anthropic 绑定的反馈流量保持禁用。要控制频率而不是禁用，请在您的设置文件中将 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置为 `0` 到 `1` 之间的概率。

39 39

40### 数据保留40### 数据保留

41 41

env-vars.md +6 −3

Details

49| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Bedrock API 密钥（请参阅 [Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |49| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Bedrock API 密钥（请参阅 [Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

53| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --remote`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |53| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --remote`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |

54| `CLAUDECODE` | 在 Claude Code 生成的 shell 环境中设置为 `1`（Bash 工具、tmux 会话）。在 [hooks](/zh-CN/hooks) 或[状态行](/zh-CN/statusline)命令中未设置。用于检测脚本何时在 Claude Code 生成的 shell 内运行 |54| `CLAUDECODE` | 在 Claude Code 生成的 shell 环境中设置为 `1`（Bash 工具、tmux 会话）。在 [hooks](/zh-CN/hooks) 或[状态行](/zh-CN/statusline)命令中未设置。用于检测脚本何时在 Claude Code 生成的 shell 内运行 |

81| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |81| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |

82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留。 |82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留。 |

84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新启用。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |

86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |

87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Bedrock、Vertex 或 Foundry 上运行 |87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Bedrock、Vertex 或 Foundry 上运行 |

96| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |96| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |

97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |

98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |

99| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |

99| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |100| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |

100| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |101| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |

102| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 设置为 `1` 以在 Claude Opus 4.7 上运行[快速模式](/zh-CN/fast-mode)而不是 Opus 4.6。设置此变量后，`/fast` 切换到 Opus 4.7；没有它，`/fast` 继续使用 Opus 4.6 |

101| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |103| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |

102| `CLAUDE_CODE_ENABLE_TASKS` | 设置为 `1` 以在非交互模式（`-p` 标志）中启用任务跟踪系统。任务在交互模式中默认启用。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |104| `CLAUDE_CODE_ENABLE_TASKS` | 设置为 `1` 以在非交互模式（`-p` 标志）中启用任务跟踪系统。任务在交互模式中默认启用。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |

103| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用 OpenTelemetry 数据收集以获取指标和日志。在配置 OTel 导出器之前需要。请参阅[监控](/zh-CN/monitoring-usage) |105| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用 OpenTelemetry 数据收集以获取指标和日志。在配置 OTel 导出器之前需要。请参阅[监控](/zh-CN/monitoring-usage) |

119| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口。 |121| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口。 |

124| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |

124| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |127| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |

202| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |205| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |

203| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |206| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |

205| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟，包括代理和 Vertex AI）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |208| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟并发送 beta 标头，在 Vertex AI 或不支持 `tool_reference` 的代理上请求失败）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |

206| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退到 [`--fallback-model`](/zh-CN/cli-reference#cli-flags)。默认情况下，仅 Opus 模型触发回退 |209| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退到 [`--fallback-model`](/zh-CN/cli-reference#cli-flags)。默认情况下，仅 Opus 模型触发回退 |

fast-mode.md +47 −14

Details

4 4

5# 使用快速模式加快响应速度5# 使用快速模式加快响应速度

6 6

~~7> 通过切换快速模式在 Claude Code 中获得更快的 Opus 4.6 响应。~~7> 通过切换快速模式在 Claude Code 中获得更快的 Opus 响应。

8 8

9<Note>9<Note>

10 快速模式处于[研究预览](#research-preview)阶段。该功能、定价和可用性可能会根据反馈而改变。10 快速模式处于[研究预览](#research-preview)阶段。该功能、定价和可用性可能会根据反馈而改变。

11</Note>11</Note>

12 12

13快速模式是 Claude Opus 4.6 的高速配置，使模型速度提高 2.5 倍，但每个令牌的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。13快速模式是 Claude Opus 的高速配置，使模型速度提高 2.5 倍，但每个令牌的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。

14 14

15快速模式不是一个不同的模型。它使用相同的 Opus 4.6，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。15快速模式不是一个不同的模型。它使用 Claude Opus，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。快速模式在 Opus 4.6 和 Opus 4.7 上受支持。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17<Note>17<Note>

18 快速模式需要 Claude Code v2.1.36 或更高版本。使用 `claude --version` 检查您的版本。18 快速模式需要 Claude Code v2.1.36 或更高版本。使用 `claude --version` 检查您的版本。

21需要了解的内容：21需要了解的内容：

22 22

23* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。也可通过 Claude Code VS Code 扩展中的 `/fast` 使用。23* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。也可通过 Claude Code VS Code 扩展中的 `/fast` 使用。

~~24* Opus 4.6 快速模式定价从 \$30/150 MTok 开始。快速模式在所有计划上享受 50% 折扣，直到太平洋时间 2 月 16 日晚上 11:59。~~24* 默认情况下，`/fast` 在 Opus 4.6 上运行。要改为在 Opus 4.7 上运行快速模式，请设置 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 环境变量。

25* 快速模式定价在 Opus 4.6 和 Opus 4.7 上都是 \$30/150 MTok。

25* 可供订阅计划（Pro/Max/Team/Enterprise）上的所有 Claude Code 用户和 Claude 控制台使用。26* 可供订阅计划（Pro/Max/Team/Enterprise）上的所有 Claude Code 用户和 Claude 控制台使用。

26* 对于订阅计划（Pro/Max/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过额外使用提供，不包含在订阅速率限制中。27* 对于订阅计划（Pro/Max/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过额外使用提供，不包含在订阅速率限制中。

27 28

28本页涵盖如何[切换快速模式](#toggle-fast-mode)、其[成本权衡](#understand-the-cost-tradeoff)、[何时使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每个会话选择加入](#require-per-session-opt-in)和[速率限制行为](#handle-rate-limits)。29本页涵盖如何[切换快速模式](#toggle-fast-mode)、[在 Opus 4.7 上使用快速模式](#use-fast-mode-on-opus-4-7)、[成本权衡](#understand-the-cost-tradeoff)、[何时使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每个会话选择加入](#require-per-session-opt-in)和[速率限制行为](#handle-rate-limits)。

29 30

30## 切换快速模式31## 切换快速模式

31 32

40 41

41启用快速模式时：42启用快速模式时：

42 43

~~43* 如果您使用的是不同的模型，Claude Code 会自动切换到 Opus 4.6~~44* 如果您使用的是不同的模型，Claude Code 会自动切换到快速模式模型：默认为 Opus 4.6，或在设置 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 时为 Opus 4.7。

44* 您将看到确认消息："Fast mode ON"45* 您将看到确认消息："Fast mode ON"

45* 快速模式处于活动状态时，提示旁边会出现一个小的 `↯` 图标46* 快速模式处于活动状态时，提示旁边会出现一个小的 `↯` 图标

46* 随时再次运行 `/fast` 以检查快速模式是否打开或关闭47* 随时再次运行 `/fast` 以检查快速模式是否打开或关闭

47 48

~~48当您再次使用 `/fast` 禁用快速模式时，您仍然保持在 Opus 4.6 上。模型不会恢复到您之前的模型。要切换到不同的模型，请使用 `/model`。~~49当您再次使用 `/fast` 禁用快速模式时，您仍然保持在快速模式运行的同一 Opus 版本上。模型不会恢复到您之前的模型。要切换到不同的模型，请使用 `/model`。

51## 在 Opus 4.7 上使用快速模式

53<Note>

54 Opus 4.7 上的快速模式需要 Claude Code v2.1.139 或更高版本。

55</Note>

57Claude Opus 4.7 的快速模式处于研究预览阶段。它以与 Opus 4.6 快速模式相同的 2.5 倍速度和相同的价格运行，没有其他行为变化。

59<Note>

60 在 2026 年 5 月 14 日，Opus 4.7 成为默认的快速模式模型。在此之前，通过设置 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1` 选择加入。

61</Note>

63要选择加入，在启动 Claude Code 之前设置 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`。设置了该变量后，`/fast` 在 Opus 4.7 上运行。没有它，`/fast` 继续在 Opus 4.6 上运行。

65您可以将该变量设置为 shell 导出：

67```bash theme={null}

68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1

69```

71或在任何 Claude Code [设置文件](/zh-CN/settings#settings-files)中，包括用户、项目和托管设置，以限定选择加入的范围：

73```json theme={null}

74{

75 "env": {

76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"

77 }

78}

79```

81Opus 4.6 的快速模式仍然可与 Opus 4.7 一起使用。两者共享相同的快速模式速率限制池：任一模型上的使用都会从相同的限制中扣除。

49 82

50## 了解成本权衡83## 了解成本权衡

51 84

~~52快速模式的每个令牌定价高于标准 Opus 4.6：~~85快速模式的每个令牌定价高于标准 Opus：

53 86

54| 模式 | 输入 (MTok) | 输出 (MTok) |87| 模式 | 输入 (MTok) | 输出 (MTok) |

~~55| ------------------------ | --------- | --------- |~~88| --------------- | --------- | --------- |

~~56| Opus 4.6 上的快速模式 (\<200K) | \$30 | \$150 |~~89| Opus 4.6 上的快速模式 | \$30 | \$150 |

~~57| Opus 4.6 上的快速模式 (>200K) | \$60 | \$225 |~~90| Opus 4.7 上的快速模式 | \$30 | \$150 |

58 91

~~59快速模式与 1M 令牌扩展上下文窗口兼容。~~92快速模式定价在整个 1M 令牌上下文窗口中是固定的。

60 93

61当您在对话中途切换到快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入令牌价格。这比从一开始就启用快速模式的成本更高。94当您在对话中途切换到快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入令牌价格。这比从一开始就启用快速模式的成本更高。

62 95

125 158

126## 处理速率限制159## 处理速率限制

127 160

128快速模式与标准 Opus 4.6 有单独的速率限制。当您达到快速模式速率限制或用完额外使用额度时：161快速模式与标准 Opus 有单独的速率限制。Opus 4.6 和 Opus 4.7 的快速模式共享相同的速率限制池：任一模型上的使用都会从相同的限制中扣除。当您达到快速模式速率限制或用完额外使用额度时：

129 162

1301. 快速模式自动回退到标准 Opus 4.61631. 快速模式自动回退到同一 Opus 版本上的标准速度

1312. `↯` 图标变灰以指示冷却1642. `↯` 图标变灰以指示冷却

1323. 您继续以标准速度和定价工作1653. 您继续以标准速度和定价工作

1334. 冷却过期时，快速模式自动重新启用1664. 冷却过期时，快速模式自动重新启用

fullscreen.md +2 −0

Details

93 93

94值 `3` 与 `vim` 和类似应用程序中的默认值匹配。该设置接受 1 到 20 的值。94值 `3` 与 `vim` 和类似应用程序中的默认值匹配。该设置接受 1 到 20 的值。

95 95

96要交互式地调整滚动速度，请运行 `/scroll-speed`。该对话框显示一个标尺，您可以在其打开时滚动，以便您可以立即感受到变化。按 `←` 和 `→` 来调整，按 `r` 重置为自动检测的默认值，按 `Enter` 保存。该命令写入与 `CLAUDE_CODE_SCROLL_SPEED` 环境变量设置相同的值，持久化到 `~/.claude/settings.json`。该命令在 JetBrains IDE 终端中不可用。

96### JetBrains IDE 终端中的滚动98### JetBrains IDE 终端中的滚动

97 99

98在 JetBrains IDE 终端中，Claude Code 应用其自己的滚动处理并忽略 `CLAUDE_CODE_SCROLL_SPEED`。终端以比其他模拟器高得多的速率发送滚动事件，因此在其他地方调整的乘数会在这里超出。100在 JetBrains IDE 终端中，Claude Code 应用其自己的滚动处理并忽略 `CLAUDE_CODE_SCROLL_SPEED`。终端以比其他模拟器高得多的速率发送滚动事件，因此在其他地方调整的乘数会在这里超出。

glossary.md +1 −1

Details

174 174

175### Output style175### Output style

176 176

177一个配置，修改 Claude 的系统提示以改变响应行为、语气或格式。Output styles 关闭默认系统提示的软件工程特定部分，与 [CLAUDE.md](#claude-md) 不同，后者作为系统提示后的用户消息传递。内置样式包括 Default、Explanatory 和 Learning。177一个配置，修改 Claude 的系统提示以改变响应行为、语气或格式。Output styles 关闭默认系统提示的软件工程特定部分，与 [CLAUDE.md](#claude-md) 不同，后者作为系统提示后的用户消息传递。内置样式包括 Default、Proactive、Explanatory 和 Learning。

178 178

179了解更多：[Output styles](/zh-CN/output-styles)179了解更多：[Output styles](/zh-CN/output-styles)

180 180

hooks.md +83 −21

Details

70 {70 {

71 "type": "command",71 "type": "command",

72 "if": "Bash(rm *)",72 "if": "Bash(rm *)",

~~73 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"~~73 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",

74 "args": []

74 }75 }

75 ]76 ]

76 }77 }

307除了[通用字段](#common-fields)外，命令 hooks 还接受这些字段：308除了[通用字段](#common-fields)外，命令 hooks 还接受这些字段：

308 309

309| 字段 | 必需 | 描述 |310| 字段 | 必需 | 描述 |

310| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |311| :------------ | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

311| `command` | 是 | 要执行的 shell 命令 |312| `command` | 是 | 要执行的 shell 命令。与 `args` 一起，要直接生成的可执行文件。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |

313| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |

312| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅[在后台运行 hooks](#run-hooks-in-the-background) |314| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅[在后台运行 hooks](#run-hooks-in-the-background) |

313| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。暗示 `async`。Hook 的 stderr，或 stdout（如果 stderr 为空），作为系统提醒显示给 Claude，以便它可以对长时间运行的后台失败做出反应 |315| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。暗示 `async`。Hook 的 stderr，或 stdout（如果 stderr 为空），作为系统提醒显示给 Claude，以便它可以对长时间运行的后台失败做出反应 |

314| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"`（默认）或 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell |316| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"`（默认）或 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell。设置 `args` 时被忽略 |

317

318<a id="exec-form-and-shell-form" />

319

320##### Exec 形式和 shell 形式

321

322当设置 `args` 时，命令 hook 以 exec 形式运行，当省略 `args` 时以 shell 形式运行。每当 hook 引用[路径占位符](#reference-scripts-by-path)时设置 `args`，因为每个元素作为一个参数传递，不带引号。当您需要 shell 功能（如管道或 `&&`）时，或当两个问题都不适用时，省略 `args`。

323

324**Exec 形式**在存在 `args` 时运行。Claude Code 在 `PATH` 上解析 `command` 作为可执行文件，并直接使用 `args` 作为参数向量生成它。没有 shell，因此每个 `args` 元素恰好是一个参数，完全按照编写的方式，路径占位符如 `${CLAUDE_PLUGIN_ROOT}` 被替换为 `command` 和每个 `args` 元素中的纯字符串。特殊字符如撇号、`$` 和反引号逐字通过，因为没有 shell 来解释它们。在任何平台上都不会发生 shell 标记化。

325

326**Shell 形式**在省略 `args` 时运行。`command` 字符串被传递给 shell：在 macOS 和 Linux 上为 `sh -c`，在 Windows 上为 Git Bash，或在未安装 Git Bash 时为 PowerShell。设置 `shell` 字段以显式选择。shell 标记化字符串，展开变量，并解释管道、`&&`、重定向和 glob。

327

328<Note>

329 在 Windows 上，exec 形式需要 `command` 解析为真实可执行文件，如 `.exe`。npm、npx、eslint 和其他工具在 `node_modules/.bin` 中安装的 `.cmd` 和 `.bat` 垫片不是可执行文件，不能在没有 shell 的情况下生成。要在 exec 形式中运行它们，直接使用 `node` 调用底层脚本，例如 `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`。`node` 加脚本路径模式在每个平台上都有效，因为 `node.exe` 是真实二进制文件。要按名称运行 `.cmd` 或 `.bat` 垫片，请使用 shell 形式。

330</Note>

331

332此示例运行与插件捆绑的 Node 脚本。Exec 形式将解析的脚本路径作为一个参数传递，不带引号：

333

334```json theme={null}

335{

336 "type": "command",

337 "command": "node",

338 "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]

339}

340```

341

342等效的 shell 形式需要引号来处理包含空格或特殊字符的路径：

343

344```json theme={null}

345{

346 "type": "command",

347 "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"

348}

349```

350

351两种形式都支持相同的[路径占位符](#reference-scripts-by-path)，并且都将它们作为环境变量 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 导出到生成的进程上，因此脚本可以读取 `process.env.CLAUDE_PLUGIN_ROOT`，无论它是如何启动的。插件 hooks 另外替换 `${user_config.*}` 值；请参阅[用户配置](/zh-CN/plugins-reference#user-configuration)。

352

353<Note>

354 在 exec 形式中，`command` 仅是可执行文件名或路径。如果 `command` 是没有路径分隔符的裸名称，并且与 `args` 一起包含空格，Claude Code 会记录警告，因为生成会失败：没有名为 `node script.js` 的可执行文件。将额外的令牌移到 `args` 中。包含空格的绝对路径，如 `C:\Program Files\nodejs\node.exe`，是单个有效的可执行文件，不会触发警告。

355</Note>

315 356

316#### HTTP hook 字段357#### HTTP hook 字段

317 358

397| `prompt` | 是 | 要发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符 |438| `prompt` | 是 | 要发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符 |

398| `model` | 否 | 用于评估的模型。默认为快速模型 |439| `model` | 否 | 用于评估的模型。默认为快速模型 |

399 440

400所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串去重，HTTP hooks 按 URL 去重。处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。441所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串和 `args` 去重，HTTP hooks 按 URL 去重。处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。

401 442

402### 按路径引用脚本443### 按路径引用脚本

403 444

404使用环境变量按项目或插件根目录引用 hook 脚本，无论 hook 运行时的工作目录如何：445使用这些占位符按项目或插件根目录引用 hook 脚本，无论 hook 运行时的工作目录如何：

405 446

406* `$CLAUDE_PROJECT_DIR`：项目根目录。用引号包装以处理包含空格的路径。447* `${CLAUDE_PROJECT_DIR}`：项目根目录。

407* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与[插件](/zh-CN/plugins)捆绑的脚本。在每次插件更新时更改。448* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与[插件](/zh-CN/plugins)捆绑的脚本。在每次插件更新时更改。

408* `${CLAUDE_PLUGIN_DATA}`：插件的[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)，用于应该在插件更新后保留的依赖项和状态。449* `${CLAUDE_PLUGIN_DATA}`：插件的[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)，用于应该在插件更新后保留的依赖项和状态。

409 450

451对于任何引用路径占位符的 hook，优先使用[exec 形式](#exec-form-and-shell-form)。Exec 形式将每个 `args` 元素作为一个参数传递，不带 shell 标记化，因此包含空格或特殊字符的路径不需要引号。在 shell 形式中，用双引号包装每个占位符。

452

410<Tabs>453<Tabs>

411 <Tab title="项目脚本">454 <Tab title="项目脚本">

412 此示例使用 `$CLAUDE_PROJECT_DIR` 在任何 `Write` 或 `Edit` 工具调用后从项目的 `.claude/hooks/` 目录运行样式检查器：455 此示例使用 `${CLAUDE_PROJECT_DIR}` 在任何 `Write` 或 `Edit` 工具调用后从项目的 `.claude/hooks/` 目录运行样式检查器：

413 456

414 ```json theme={null}457 ```json theme={null}

415 {458 {

420 "hooks": [463 "hooks": [

421 {464 {

422 "type": "command",465 "type": "command",

423 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"466 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",

467 "args": []

424 }468 }

425 ]469 ]

426 }470 }

446 {490 {

447 "type": "command",491 "type": "command",

448 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",492 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",

493 "args": [],

449 "timeout": 30494 "timeout": 30

450 }495 }

451 ]496 ]

529使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：574使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：

530 575

531| 字段 | 描述 |576| 字段 | 描述 |

532| :----------- | :--------------------------------------------------------------------------------------------------------------------------------- |577| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

534| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。 |579| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。 |

580

581仅[`SessionStart`](#sessionstart) hooks 接收 `model` 字段。没有 `$CLAUDE_MODEL` 环境变量。Hook 进程继承父环境，因此如果您在 shell 中设置了 `$ANTHROPIC_MODEL`，它可以读取该值，但当您在会话期间使用 `/model` 切换模型时，该值不会改变。

535 582

536例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收：583例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收：

537 584

1153| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈现的问题，每个都有 `question` 字符串、短 `header`、`options` 数组和可选的 `multiSelect` 标志 |1200| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈现的问题，每个都有 `question` 字符串、短 `header`、`options` 数组和可选的 `multiSelect` 标志 |

1154| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到选定的选项标签。多选答案用逗号连接标签。Claude 不设置此字段；通过 `updatedInput` 提供它以以编程方式回答 |1201| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到选定的选项标签。多选答案用逗号连接标签。Claude 不设置此字段；通过 `updatedInput` 提供它以以编程方式回答 |

1155 1202

1203##### ExitPlanMode

1204

1205呈现一个计划并要求用户在 Claude 离开[Plan Mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的字面 `tool_input` 仅携带 `allowedPrompts`。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。

1206

1207| 字段 | 类型 | 示例 | 描述 |

1208| :--------------- | :----- | :------------------------------------------ | :------------------------------------------------------- |

1211| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 可选。Claude 请求实现计划的基于提示的权限，每个都有 `tool` 名称和描述操作类别的 `prompt` |

1212

1213在 `PostToolUse` 中，`tool_response` 是一个对象，具有 `plan` 和 `filePath` 字段，保存批准的计划，加上内部状态标志。读取 `tool_response.plan` 以获取计划内容，而不是从磁盘重新读取文件。

1214

1156#### PreToolUse 决定控制1215#### PreToolUse 决定控制

1157 1216

1158`PreToolUse` hooks 可以控制工具调用是否继续。与使用顶级 `decision` 字段的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 对象内返回其决定。这给了它更丰富的控制：四个结果（允许、拒绝、询问或延迟）加上在执行前修改工具输入的能力。1217`PreToolUse` hooks 可以控制工具调用是否继续。与使用顶级 `decision` 字段的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 对象内返回其决定。这给了它更丰富的控制：四个结果（允许、拒绝、询问或延迟）加上在执行前修改工具输入的能力。

1595 1654

1596### SubagentStart1655### SubagentStart

1597 1656

1598当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤（内置代理如 `general-purpose`、`Explore`、`Plan` 或来自 `.claude/agents/` 的自定义代理名称）。1657当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤。对于内置代理，这是代理名称，如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。

1599 1658

1600#### SubagentStart 输入1659#### SubagentStart 输入

1601 1660

1650}1709}

1651```1710```

1652 1711

1653SubagentStop hooks 使用与[Stop hooks](#stop-decision-control)相同的决定控制格式。1712SubagentStop hooks 使用与[Stop hooks](#stop-decision-control)相同的决定控制格式。它们不支持 `additionalContext`。返回 `decision: "block"` 和 `reason` 保持 subagent 运行并将 `reason` 作为其下一个指令传递给 subagent。要在 subagent 返回后向父会话注入上下文，请改用 `Agent` 工具上的[`PostToolUse`](#posttooluse) hook。

1654 1713

1655### TaskCreated1714### TaskCreated

1656 1715

1904 "hooks": [1963 "hooks": [

1905 {1964 {

1906 "type": "command",1965 "type": "command",

1907 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-config-change.sh"1966 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh"

1908 }1967 }

1909 ]1968 ]

1910 }1969 }

2393```2452```

2394 2453

2395| 字段 | 必需 | 描述 |2454| 字段 | 必需 | 描述 |

2396| :-------- | :- | :------------------------------------------------------------------------------------- |2455| :---------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------- |

2397| `type` | 是 | 必须是 `"prompt"` |2456| `type` | 是 | 必须是 `"prompt"` |

2398| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |2457| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |

2399| `model` | 否 | 用于评估的模型。默认为快速模型 |2458| `model` | 否 | 用于评估的模型。默认为快速模型 |

2400| `timeout` | 否 | 超时（秒）。默认值：30 |2459| `timeout` | 否 | 超时（秒）。默认值：30 |

2460| `continueOnBlock` | 否 | 当提示返回 `ok: false` 时，将原因反馈给 Claude 并继续转轮而不是停止。默认值：`false`。在生成的 `decision: "block"` 上实现为 `continue: true`。有关每个事件的行为，请参阅[响应架构](#response-schema) |

2401 2461

2402### 响应架构2462### 响应架构

2403 2463

2411```2471```

2412 2472

2413| 字段 | 描述 |2473| 字段 | 描述 |

2414| :------- | :-------------------------------- |2474| :------- | :---------------------------------------------------- |

2415| `ok` | `true` 允许，`false` 阻止。请参阅下面的每个事件行为 |2475| `ok` | `true` 允许。`false` 产生 `decision: "block"`。请参阅下面的每个事件行为 |

2417 2477

2418`ok: false` 时发生的情况取决于事件：2478`ok: false` 时发生的情况取决于事件：

2419 2479

2420* `Stop` 和 `SubagentStop`：原因被反馈给 Claude 作为其下一条指令，转轮继续2480* `Stop` 和 `SubagentStop`：原因被反馈给 Claude 作为其下一条指令，转轮继续

2421* `PreToolUse`：工具调用被拒绝，原因作为工具错误返回给 Claude，等同于命令 hook 的 `permissionDecision: "deny"`2481* `PreToolUse`：工具调用被拒绝，原因作为工具错误返回给 Claude，等同于命令 hook 的 `permissionDecision: "deny"`

2422* `PostToolUse`、`PostToolBatch`、`UserPromptSubmit` 和 `UserPromptExpansion`：转轮结束，原因在聊天中显示为警告行，等同于从命令 hook 返回 `"continue": false`2482* `PostToolUse`：默认情况下转轮结束，原因在聊天中显示为警告行。设置 `continueOnBlock: true` 以将原因反馈给 Claude 并继续转轮

2483* `PostToolBatch`、`UserPromptSubmit` 和 `UserPromptExpansion`：转轮结束，原因显示为警告行。这些事件在 `decision: "block"` 上结束转轮，无论 `continue` 如何

2423* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作为工具错误返回给 Claude，类似于 `PreToolUse`2484* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作为工具错误返回给 Claude，类似于 `PreToolUse`

2424* `PermissionRequest`：`ok: false` 无效。要从 hook 拒绝批准，请使用[命令 hook](#command-hook-fields)，返回 `hookSpecificOutput.decision.behavior: "deny"`2485* `PermissionRequest`：`ok: false` 无效。要从 hook 拒绝批准，请使用[命令 hook](#command-hook-fields)，返回 `hookSpecificOutput.decision.behavior: "deny"`

2425 2486

2578 "hooks": [2639 "hooks": [

2579 {2640 {

2580 "type": "command",2641 "type": "command",

2581 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",2642 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",

2643 "args": [],

2582 "async": true,2644 "async": true,

2583 "timeout": 3002645 "timeout": 300

2584 }2646 }

2615* **验证和清理输入**：永远不要盲目信任输入数据2677* **验证和清理输入**：永远不要盲目信任输入数据

2616* **始终引用 shell 变量**：使用 `"$VAR"` 而不是 `$VAR`2678* **始终引用 shell 变量**：使用 `"$VAR"` 而不是 `$VAR`

2617* **阻止路径遍历**：检查文件路径中的 `..`2679* **阻止路径遍历**：检查文件路径中的 `..`

2618* **使用绝对路径**：为脚本指定完整路径，使用 `"$CLAUDE_PROJECT_DIR"` 作为项目根目录2680* **使用绝对路径**：为脚本指定完整路径。在 exec 形式中，使用 `${CLAUDE_PROJECT_DIR}` 且路径无需引用。在 shell 形式中，将其包装在双引号中

2619* **跳过敏感文件**：避免 `.env`、`.git/`、密钥等2681* **跳过敏感文件**：避免 `.env`、`.git/`、密钥等

2620 2682

2621## Windows PowerShell 工具2683## Windows PowerShell 工具

hooks-guide.md +2 −2

Details

895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

896 echo $? # 检查退出代码896 echo $? # 检查退出代码

897 ```897 ```

898* 如果你看到"command not found"，使用绝对路径或 `$CLAUDE_PROJECT_DIR` 来引用脚本898* 如果你看到"command not found"，使用绝对路径或 `${CLAUDE_PROJECT_DIR}` 来引用脚本。为了完全避免 shell 引用，添加 `"args": []` 来切换到 [exec 形式](/zh-CN/hooks#exec-form-and-shell-form)，它直接生成脚本而不使用 shell

899* 如果你看到"jq: command not found"，安装 `jq` 或使用 Python/Node.js 进行 JSON 解析899* 如果你看到"jq: command not found"，安装 `jq` 或使用 Python/Node.js 进行 JSON 解析

900* 如果脚本根本没有运行，使其可执行：`chmod +x ./my-hook.sh`900* 如果脚本根本没有运行，使其可执行：`chmod +x ./my-hook.sh`

901 901

926 926

927Claude Code 显示 JSON 解析错误，即使你的 hook 脚本输出有效的 JSON。927Claude Code 显示 JSON 解析错误，即使你的 hook 脚本输出有效的 JSON。

928 928

929当 Claude Code 运行 hook 时，它生成一个 shell，该 shell 源你的配置文件（`~/.zshrc` 或 `~/.bashrc`）。如果你的配置文件包含无条件的 `echo` 语句，该输出会被添加到你的 hook 的 JSON 前面：929当 Claude Code 运行 shell 形式的命令 hook（没有 `args` 的）时，它在 macOS 和 Linux 上生成 `sh -c`，或在 Windows 上生成 Git Bash。这个 shell 是非交互式的，但 Git Bash 和某些配置（例如 `BASH_ENV` 指向 `~/.bashrc`）仍然会源你的配置文件。如果该配置文件包含无条件的 `echo` 语句，输出会被添加到你的 hook 的 JSON 前面：

930 930

931```text theme={null}931```text theme={null}

932Shell ready on arm64932Shell ready on arm64

interactive-mode.md +7 −4

Details

9## 键盘快捷键9## 键盘快捷键

10 10

11<Note>11<Note>

~~12 键盘快捷键可能因平台和终端而异。按 `?` 查看您的环境中可用的快捷键。~~12 键盘快捷键可能因平台和终端而异。在[全屏渲染](/zh-CN/fullscreen)中，在转录查看器中按 `?` 查看可用的快捷键。

13 13

14 **macOS 用户**：Option/Alt 键快捷键（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在终端中将 Option 配置为 Meta：14 **macOS 用户**：Option/Alt 键快捷键（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在终端中将 Option 配置为 Meta：

15 15

23### 常规控制23### 常规控制

24 24

25| 快捷键 | 描述 | 上下文 |25| 快捷键 | 描述 | 上下文 |

26| :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |26| :------------------------------------------- | :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |

30| `Ctrl+G` 或 `Ctrl+X Ctrl+E` | 在默认文本编辑器中打开 | 在默认文本编辑器中编辑您的提示或自定义响应。`Ctrl+X Ctrl+E` 是 readline 原生绑定。在 `/config` 中打开"在外部编辑器中显示最后响应"以在您的提示上方将 Claude 的上一个回复作为 `#` 注释上下文预置；保存时会删除注释块 |30| `Ctrl+G` 或 `Ctrl+X Ctrl+E` | 在默认文本编辑器中打开 | 在默认文本编辑器中编辑您的提示或自定义响应。`Ctrl+X Ctrl+E` 是 readline 原生绑定。在 `/config` 中打开"在外部编辑器中显示最后响应"以在您的提示上方将 Claude 的上一个回复作为 `#` 注释上下文预置；保存时会删除注释块 |

39| `Esc` | 中断 Claude | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止完成的工作 |

86 87

87### 转录查看器88### 转录查看器

88 89

~~89当转录查看器打开时（使用 `Ctrl+O` 切换），这些快捷键可用。`Ctrl+E` 可以通过 [`transcript:toggleShowAll`](/zh-CN/keybindings) 重新绑定。~~90当转录查看器打开时（使用 `Ctrl+O` 切换），这些快捷键可用。在[全屏渲染](/zh-CN/fullscreen)中，按 `?` 显示查看器内的完整快捷键参考面板。`Ctrl+E` 可以通过 [`transcript:toggleShowAll`](/zh-CN/keybindings) 重新绑定。

90 91

91| 快捷键 | 描述 |92| 快捷键 | 描述 |

92| :----------------- | :---------------------------------------------------------------------------------------------------------------- |93| :----------------- | :---------------------------------------------------------------------------------------------------------------- |

94| `?` | 切换键盘快捷键帮助面板。需要[全屏渲染](/zh-CN/fullscreen) |

95| `{` / `}` | 跳转到上一个或下一个用户提示，如 vim 段落运动。需要[全屏渲染](/zh-CN/fullscreen) |

93| `Ctrl+E` | 切换显示所有内容 |96| `Ctrl+E` | 切换显示所有内容 |

94| `[` | 将完整对话写入终端的原生滚动缓冲区，以便 `Cmd+F`、tmux 复制模式和其他原生工具可以搜索它。需要[全屏渲染](/zh-CN/fullscreen#search-and-review-the-conversation) |97| `[` | 将完整对话写入终端的原生滚动缓冲区，以便 `Cmd+F`、tmux 复制模式和其他原生工具可以搜索它。需要[全屏渲染](/zh-CN/fullscreen#search-and-review-the-conversation) |

95| `v` | 将对话写入临时文件并在 `$VISUAL` 或 `$EDITOR` 中打开它。需要[全屏渲染](/zh-CN/fullscreen) |98| `v` | 将对话写入临时文件并在 `$VISUAL` 或 `$EDITOR` 中打开它。需要[全屏渲染](/zh-CN/fullscreen) |

llm-gateway.md +5 −1

Details

42Claude Code 在每个 API 请求上包含以下请求头：42Claude Code 在每个 API 请求上包含以下请求头：

43 43

44| 请求头 | 描述 |44| 请求头 | 描述 |

~~45| :------------------------- | :-------------------------------------------------------------- |~~45| :------------------------------ | :--------------------------------------------------------------------------------------------- |

47| `X-Claude-Code-Agent-Id` | 发出请求的子代理或队友的标识符。您的代理可以使用此标识符将 API 成本归属于会话内的各个并行子代理，而无需解析请求体。仅在由进程内子代理或队友发出的请求中出现。 |

48| `X-Claude-Code-Parent-Agent-Id` | 生成发出请求的代理的代理的标识符。将此与 `X-Claude-Code-Agent-Id` 一起使用，以在您的代理中跨嵌套代理归属 API 成本。仅当请求代理本身由另一个代理生成时才出现。 |

50两个代理 ID 请求头都是每次生成的临时标识符，而不是持久的用户或设备 ID。

47 51

48Claude Code 还会在系统提示前面添加一个简短的归属块，其中包含客户端版本和从对话派生的指纹。Anthropic API 在处理前会删除此块，因此不会影响第一方提示缓存。如果您的网关实现了自己的提示缓存（以完整请求体为键），请设置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-CN/env-vars) 以省略它。52Claude Code 还会在系统提示前面添加一个简短的归属块，其中包含客户端版本和从对话派生的指纹。Anthropic API 在处理前会删除此块，因此不会影响第一方提示缓存。如果您的网关实现了自己的提示缓存（以完整请求体为键），请设置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-CN/env-vars) 以省略它。

49 53

mcp.md +35 −219

Details

6 6

7> 了解如何使用 Model Context Protocol 将 Claude Code 连接到您的工具。7> 了解如何使用 Model Context Protocol 将 Claude Code 连接到您的工具。

8 8

~~9export const MCPServersTable = ({platform = "all"}) => {~~

~~10 const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs';~~

~~11 const [servers, setServers] = useState([]);~~

~~12 const [loading, setLoading] = useState(true);~~

~~13 const [error, setError] = useState(null);~~

~~14 useEffect(() => {~~

~~15 const fetchServers = async () => {~~

~~16 try {~~

~~17 setLoading(true);~~

~~18 const allServers = [];~~

~~19 let cursor = null;~~

~~20 do {~~

~~21 const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers');~~

~~22 url.searchParams.set('version', 'latest');~~

~~23 url.searchParams.set('visibility', 'commercial');~~

~~24 url.searchParams.set('limit', '100');~~

~~25 if (cursor) {~~

~~26 url.searchParams.set('cursor', cursor);~~

~~27 }~~

~~28 const response = await fetch(url);~~

~~29 if (!response.ok) {~~

~~30 throw new Error(`Failed to fetch MCP registry: ${response.status}`);~~

~~31 }~~

~~32 const data = await response.json();~~

~~33 allServers.push(...data.servers);~~

~~34 cursor = data.metadata?.nextCursor || null;~~

~~35 } while (cursor);~~

~~36 const transformedServers = allServers.map(item => {~~

~~37 const server = item.server;~~

~~38 const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({});~~

~~39 const worksWith = meta.worksWith || [];~~

~~40 const availability = {~~

~~41 claudeCode: worksWith.includes('claude-code'),~~

~~42 mcpConnector: worksWith.includes('claude-api'),~~

~~43 claudeDesktop: worksWith.includes('claude-desktop')~~

~~44 };~~

~~45 const remotes = server.remotes || [];~~

~~46 const httpRemote = remotes.find(r => r.type === 'streamable-http');~~

~~47 const sseRemote = remotes.find(r => r.type === 'sse');~~

~~48 const preferredRemote = httpRemote || sseRemote;~~

~~49 const remoteUrl = preferredRemote?.url || meta.url;~~

~~50 const remoteType = preferredRemote?.type;~~

~~51 const isTemplatedUrl = remoteUrl?.includes('{');~~

~~52 let setupUrl;~~

~~53 if (isTemplatedUrl && meta.requiredFields) {~~

~~54 const urlField = meta.requiredFields.find(f => f.field === 'url');~~

~~55 setupUrl = urlField?.sourceUrl || meta.documentation;~~

~~56 }~~

~~57 const urls = {};~~

~~58 if (!isTemplatedUrl) {~~

~~59 if (remoteType === 'streamable-http') {~~

~~60 urls.http = remoteUrl;~~

~~61 } else if (remoteType === 'sse') {~~

~~62 urls.sse = remoteUrl;~~

~~63 }~~

~~64 }~~

~~65 let envVars = [];~~

~~66 if (server.packages && server.packages.length > 0) {~~

~~67 const npmPackage = server.packages.find(p => p.registryType === 'npm');~~

~~68 if (npmPackage) {~~

~~69 urls.stdio = `npx -y ${npmPackage.identifier}`;~~

~~70 if (npmPackage.environmentVariables) {~~

~~71 envVars = npmPackage.environmentVariables;~~

~~72 }~~

~~73 }~~

~~74 }~~

~~75 return {~~

~~76 name: meta.displayName || server.title || server.name,~~

~~77 description: meta.oneLiner || server.description,~~

~~78 documentation: meta.documentation,~~

~~79 urls: urls,~~

~~80 envVars: envVars,~~

~~81 availability: availability,~~

~~82 customCommands: meta.claudeCodeCopyText ? {~~

~~83 claudeCode: meta.claudeCodeCopyText~~

~~84 } : undefined,~~

~~85 setupUrl: setupUrl~~

~~86 };~~

~~87 });~~

~~88 setServers(transformedServers);~~

~~89 setError(null);~~

~~90 } catch (err) {~~

~~91 setError(err.message);~~

~~92 console.error('Error fetching MCP registry:', err);~~

~~93 } finally {~~

~~94 setLoading(false);~~

~~95 }~~

~~96 };~~

~~97 fetchServers();~~

~~98 }, []);~~

~~99 const generateClaudeCodeCommand = server => {~~

100 if (server.customCommands && server.customCommands.claudeCode) {

101 return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http');

102 }

103 const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-');

104 if (server.urls.http) {

105 return `claude mcp add ${serverSlug} --transport http ${server.urls.http}`;

106 }

107 if (server.urls.sse) {

108 return `claude mcp add ${serverSlug} --transport sse ${server.urls.sse}`;

109 }

110 if (server.urls.stdio) {

111 const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => `--env ${v.name}=YOUR_${v.name}`).join(' ') : '';

112 const baseCommand = `claude mcp add ${serverSlug} --transport stdio`;

113 return envFlags ? `${baseCommand} ${envFlags} -- ${server.urls.stdio}` : `${baseCommand} -- ${server.urls.stdio}`;

114 }

115 return null;

116 };

117 if (loading) {

118 return <div>Loading MCP servers...</div>;

119 }

120 if (error) {

121 return <div>Error loading MCP servers: {error}</div>;

122 }

123 const filteredServers = servers.filter(server => {

124 if (platform === "claudeCode") {

125 return server.availability.claudeCode;

126 } else if (platform === "mcpConnector") {

127 return server.availability.mcpConnector;

128 } else if (platform === "claudeDesktop") {

129 return server.availability.claudeDesktop;

130 } else if (platform === "all") {

131 return true;

132 } else {

133 throw new Error(`Unknown platform: ${platform}`);

134 }

135 });

136 return <>

137 <style jsx>{`

138 .cards-container {

139 display: grid;

140 gap: 1rem;

141 margin-bottom: 2rem;

142 }

143 .server-card {

144 border: 1px solid var(--border-color, #e5e7eb);

145 border-radius: 6px;

146 padding: 1rem;

147 }

148 .command-row {

149 display: flex;

150 align-items: center;

151 gap: 0.25rem;

152 }

153 .command-row code {

154 font-size: 0.75rem;

155 overflow-x: auto;

156 }

157 `}</style>

~~158~~

159 <div className="cards-container">

160 {filteredServers.map(server => {

161 const claudeCodeCommand = generateClaudeCodeCommand(server);

162 const mcpUrl = server.urls.http || server.urls.sse;

163 const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;

164 return <div key={server.name} className="server-card">

165 <div>

166 {server.documentation ? <a href={server.documentation}>

167 <strong>{server.name}</strong>

168 </a> : <strong>{server.name}</strong>}

169 </div>

~~170~~

171 <p style={{

172 margin: '0.5rem 0',

173 fontSize: '0.9rem'

174 }}>

175 {server.description}

176 </p>

~~177~~

178 {server.setupUrl && <p style={{

179 margin: '0.25rem 0',

180 fontSize: '0.8rem',

181 fontStyle: 'italic',

182 opacity: 0.7

183 }}>

184 Requires user-specific URL.{' '}

185 <a href={server.setupUrl} style={{

186 textDecoration: 'underline'

187 }}>

188 Get your URL here

189 </a>.

190 </p>}

~~191~~

192 {commandToShow && !server.setupUrl && <>

193 <p style={{

194 display: 'block',

195 fontSize: '0.75rem',

196 fontWeight: 500,

197 minWidth: 'fit-content',

198 marginTop: '0.5rem',

199 marginBottom: 0

200 }}>

201 {platform === "claudeCode" ? "Command" : "URL"}

202 </p>

203 <div className="command-row">

204 <code>

205 {commandToShow}

206 </code>

207 </div>

208 </>}

209 </div>;

210 })}

211 </div>

212 </>;

213};

~~214~~

215Claude Code 可以通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)（一个用于 AI 工具集成的开源标准）连接到数百个外部工具和数据源。MCP 服务器为 Claude Code 提供对您的工具、数据库和 API 的访问权限。9Claude Code 可以通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)（一个用于 AI 工具集成的开源标准）连接到数百个外部工具和数据源。MCP 服务器为 Claude Code 提供对您的工具、数据库和 API 的访问权限。

216 10

217当您发现自己从另一个工具（如问题跟踪器或监控仪表板）复制数据到聊天中时，请连接一个服务器。连接后，Claude 可以直接读取和操作该系统，而不是从您粘贴的内容中工作。11当您发现自己从另一个工具（如问题跟踪器或监控仪表板）复制数据到聊天中时，请连接一个服务器。连接后，Claude 可以直接读取和操作该系统，而不是从您粘贴的内容中工作。

227* **自动化工作流**："创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会议。"21* **自动化工作流**："创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会议。"

228* **对外部事件做出反应**：MCP 服务器也可以充当[频道](/zh-CN/channels)，将消息推送到您的会话中，因此当您不在时，Claude 可以对 Telegram 消息、Discord 聊天或 webhook 事件做出反应。22* **对外部事件做出反应**：MCP 服务器也可以充当[频道](/zh-CN/channels)，将消息推送到您的会话中，因此当您不在时，Claude 可以对 Telegram 消息、Discord 聊天或 webhook 事件做出反应。

229 23

230## 流行的 MCP 服务器24## 查找和构建 MCP 服务器

231 25

232以下是一些您可以连接到 Claude Code 的常用 MCP 服务器：26在 [Anthropic Directory](https://claude.ai/directory) 中浏览已审核的连接器。Directory 连接器使用与 Claude Code 相同的 MCP 基础设施，因此您可以使用 `claude mcp add` 添加列出的任何远程服务器。

233 27

234<Warning>28<Warning>

235 使用第三方 MCP 服务器需自担风险 - Anthropic 尚未验证所有这些服务器的正确性或安全性。29 在连接每个服务器之前，请验证您信任该服务器。获取外部内容的服务器可能会使您面临 [提示注入风险](/zh-CN/security#protect-against-prompt-injection)。

236 请确保您信任正在安装的 MCP 服务器。

237 使用可能获取不受信任内容的 MCP 服务器时要特别小心，因为这些可能会使您面临提示注入风险。

238</Warning>30</Warning>

239 31

240<MCPServersTable platform="claudeCode" />32要构建您自己的服务器，请参阅 [MCP 服务器指南](https://modelcontextprotocol.io/docs/develop/build-server) 了解协议基础知识，以及 [Claude 连接器构建文档](https://claude.com/docs/connectors/building) 了解身份验证、测试和 Directory 提交。

241 33

242<Note>34您也可以使用官方的 [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) 让 Claude 为您搭建服务器。

243 **需要特定的集成？** [在 GitHub 上查找数百个更多 MCP 服务器](https://github.com/modelcontextprotocol/servers)，或使用 [MCP SDK](https://modelcontextprotocol.io/quickstart/server) 构建您自己的服务器。35

244</Note>36<Steps>

37 <Step title="安装 plugin">

38 在 Claude Code 会话中，运行：

40 ```

41 /plugin install mcp-server-dev@claude-plugins-official

42 ```

44 然后运行 `/reload-plugins` 在当前会话中激活它。

45 </Step>

47 <Step title="运行构建 skill">

48 ```

49 /mcp-server-dev:build-mcp-server

50 ```

52 Claude 会询问您的用例，并搭建一个远程 HTTP 或本地 stdio 服务器。

53 </Step>

54</Steps>

245 55

246## 安装 MCP 服务器56## 安装 MCP 服务器

247 57

287 97

288Stdio 服务器作为您机器上的本地进程运行。它们非常适合需要直接系统访问或自定义脚本的工具。98Stdio 服务器作为您机器上的本地进程运行。它们非常适合需要直接系统访问或自定义脚本的工具。

289 99

100Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR`，指向项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。您的服务器也可以调用 MCP `roots/list` 请求，该请求返回启动 Claude Code 的目录。

101

102此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 `.mcp.json` `command` 或 `args` 中通过 `${VAR}` 扩展引用它需要一个默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}`，不需要默认值。

103

290```bash theme={null}104```bash theme={null}

291# 基本语法105# 基本语法

292claude mcp add [options] <name> -- <command> [args...]106claude mcp add [options] <name> -- <command> [args...]

404**插件 MCP 功能**：218**插件 MCP 功能**：

405 219

406* **自动生命周期**：在会话启动时，启用的插件的服务器会自动连接。如果您在会话期间启用或禁用插件，请运行 `/reload-plugins` 以连接或断开其 MCP 服务器220* **自动生命周期**：在会话启动时，启用的插件的服务器会自动连接。如果您在会话期间启用或禁用插件，请运行 `/reload-plugins` 以连接或断开其 MCP 服务器

407* **环境变量**：对插件相对路径使用 `${CLAUDE_PLUGIN_ROOT}`，对[持久状态](/zh-CN/plugins-reference#persistent-data-directory)使用 `${CLAUDE_PLUGIN_DATA}`，该状态在插件更新后仍然存在221* **环境变量**：对插件相对路径使用 `${CLAUDE_PLUGIN_ROOT}`，对[持久状态](/zh-CN/plugins-reference#persistent-data-directory)使用 `${CLAUDE_PLUGIN_DATA}`，该状态在插件更新后仍然存在，以及对稳定项目根目录使用 `${CLAUDE_PROJECT_DIR}`

408* **用户环境访问**：访问与手动配置的服务器相同的环境变量222* **用户环境访问**：访问与手动配置的服务器相同的环境变量

409* **多种传输类型**：支持 stdio、SSE 和 HTTP 传输（传输支持可能因服务器而异）223* **多种传输类型**：支持 stdio、SSE 和 HTTP 传输（传输支持可能因服务器而异）

410 224

644 458

645许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。459许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。

646 460

461当服务器响应 `401 Unauthorized` 和指向其授权服务器的 `WWW-Authenticate` 标头时，Claude Code 将远程服务器标记为需要身份验证。任何返回该响应的自定义服务器都会获得与任何其他远程服务器相同的 `/mcp` 身份验证流程。

462

647<Steps>463<Steps>

648 <Step title="添加需要身份验证的服务器">464 <Step title="添加需要身份验证的服务器">

649 例如：465 例如：

1137 953

1138### 配置工具搜索954### 配置工具搜索

1139 955

1140工具搜索默认启用：MCP 工具被延迟并按需发现。在 Vertex AI 上默认禁用，它不接受工具搜索 beta 标头，以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，因为大多数代理不转发 `tool_reference` 块。显式设置 `ENABLE_TOOL_SEARCH` 以选择加入。此功能需要支持 `tool_reference` 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持工具搜索。956工具搜索默认启用：MCP 工具被延迟并按需发现。在 Vertex AI 上默认禁用，它不接受工具搜索 beta 标头，以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，因为大多数代理不转发 `tool_reference` 块。如果您的代理转发 `tool_reference` 块，请显式设置 `ENABLE_TOOL_SEARCH` 以覆盖回退。此功能需要支持 `tool_reference` 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持工具搜索。

1141 957

1142使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：958使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：

1143 959

1144| 值 | 行为 |960| 值 | 行为 |

1145| :--------- | :--------------------------------------------------------------------- |961| :--------- | :----------------------------------------------------------------------------------------- |

1146| （未设置） | 所有 MCP 工具被延迟并按需加载。在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载 |962| （未设置） | 所有 MCP 工具被延迟并按需加载。在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载 |

memory.md +16 −0

Details

272 </Step>272 </Step>

273</Steps>273</Steps>

274 274

275`claudeMd` 键让你将托管 CLAUDE.md 内容直接放入 `managed-settings.json` 中，而不是部署单独的文件。

276

277**范围**：机器上的每个 Claude Code 会话，在每个存储库中。对于存储库特定的指导，改为提交项目 CLAUDE.md。

278

279**优先级**：与托管 CLAUDE.md 文件相同。在用户和项目 CLAUDE.md 之前加载。

280

281**在哪里被遵守**：仅托管和策略设置。在用户、项目或本地设置中设置 `claudeMd` 无效。

282

283下面的示例直接在托管设置文件中添加行为指令：

284

285```json theme={null}

286{

287 "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."

288}

289```

290

275托管 CLAUDE.md 和 [托管设置](/zh-CN/settings#settings-files) 服务于不同的目的。使用设置进行技术强制，使用 CLAUDE.md 进行行为指导：291托管 CLAUDE.md 和 [托管设置](/zh-CN/settings#settings-files) 服务于不同的目的。使用设置进行技术强制，使用 CLAUDE.md 进行行为指导：

276 292

277| 关注点 | 配置在 |293| 关注点 | 配置在 |

monitoring-usage.md +136 −6

Details

174| `agent_id` | 发出请求的子代理或队友的标识符。在主会话中不存在 | |

175| `parent_agent_id` | 生成此代理的代理的标识符。对于主会话和直接从其生成的代理不存在 | |

446* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一448* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

447* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在449* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

448* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。450* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。

451* `agent.name`：发出请求的子代理类型。内置代理名称和来自官方市场插件的代理按原样出现。其他用户定义的代理名称被替换为 `"custom"`。当请求不是由命名子代理类型发出时不存在。

452* `skill.name`：对请求活跃的技能，由 Skill 工具、`/` 命令设置或由生成的子代理继承。内置、捆绑、用户定义和官方市场插件技能名称按原样出现。第三方插件技能名称被替换为 `"third-party"`。当没有技能活跃时不存在。

453* `plugin.name`：当活跃技能或子代理由插件提供时的拥有插件。官方市场插件名称按原样出现。第三方插件名称被替换为 `"third-party"`。当技能和子代理都没有拥有插件时不存在。

454* `marketplace.name`：拥有插件安装来源的市场。仅为官方市场插件发出。否则不存在。

449 455

450#### 令牌计数器456#### 令牌计数器

451 457

459* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一465* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

460* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在466* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

461* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅 [成本计数器](#cost-counter)。467* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅 [成本计数器](#cost-counter)。

468* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`：请求的技能、插件和代理归属。有关定义和编辑行为，请参阅 [成本计数器](#cost-counter)。

462 469

463#### 代码编辑工具决策计数器470#### 代码编辑工具决策计数器

464 471

647* `tool_use_id`：此工具调用的唯一标识符。与传递给 hooks 的 `tool_use_id` 匹配，允许在 OTel 事件和 hook 捕获的数据之间进行关联。654* `tool_use_id`：此工具调用的唯一标识符。与传递给 hooks 的 `tool_use_id` 匹配，允许在 OTel 事件和 hook 捕获的数据之间进行关联。

648* `decision`：`"accept"` 或 `"reject"`655* `decision`：`"accept"` 或 `"reject"`

649* `source`：决策来源：656* `source`：决策来源：

650 * `"config"`：基于项目设置、企业托管策略、`--allowedTools` 或 `--disallowedTools` 标志、活跃权限模式或因为工具本身是安全的，自动决策而不提示。657 * `"config"`：基于项目设置、用户个人设置中的允许规则、企业托管策略、`--allowedTools` 或 `--disallowedTools` 标志、活跃权限模式、来自同一交互式 CLI 会话中较早提示的会话范围授予或因为工具本身是安全的，自动决策而不提示。事件不指示这些来源中的哪一个匹配。

651 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 返回了决策。658 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 返回了决策。

652 * `"user_permanent"`：当用户在提示时选择"始终允许"时发出，将规则保存到其个人设置。也为与该保存规则匹配的后续调用发出。视为接受。659 * `"user_permanent"`：当用户在权限提示时选择"是，并且不要再问..."时发出，将允许规则保存到其个人设置。在交互式 CLI 中，仅为该选择本身发出；与保存规则匹配的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，初始选择和后续规则匹配都发出 `"user_permanent"`。视为接受。

653 * `"user_temporary"`：当用户在提示时选择"是"或"是，仅此会话"时发出，不保存规则。也为同一会话中与该会话范围允许匹配的后续调用发出。视为接受。660 * `"user_temporary"`：当用户在权限提示时选择"是"，或在文件编辑或读取提示上选择"...仅在此会话期间"选项时发出。在交互式 CLI 中，仅为该选择本身发出；与该会话范围允许匹配的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，选择和后续匹配都发出 `"user_temporary"`。视为接受。

654 * `"user_abort"`：当用户关闭权限提示而不回答时发出。视为拒绝。661 * `"user_abort"`：当用户关闭权限提示而不回答时发出。视为拒绝。

655 * `"user_reject"`：当用户选择"否"时发出，或调用与其个人设置中的拒绝规则匹配。视为拒绝。662 * `"user_reject"`：当用户选择"否"时发出，或调用与其个人设置中的拒绝规则匹配。视为拒绝。

656 663

741* `plugin.version`：在市场条目中声明时的插件版本。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含748* `plugin.version`：在市场条目中声明时的插件版本。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

742* `marketplace.name`：插件安装来源的市场。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含749* `marketplace.name`：插件安装来源的市场。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

743 750

751#### 插件已加载事件

752

753在会话开始时为每个启用的插件记录一次。使用此事件来清点您的整个队伍中哪些插件处于活跃状态，作为记录安装操作本身的 `plugin_installed` 的补充。

754

755**事件名称**：`claude_code.plugin_loaded`

756

757**属性**：

758

759* 所有 [标准属性](#standard-attributes)

760* `event.name`：`"plugin_loaded"`

761* `event.timestamp`：ISO 8601 时间戳

762* `event.sequence`：单调递增的计数器，用于在会话内排序事件

763* `plugin.name`：插件的名称。对于官方市场外和内置捆绑的插件，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`

764* `marketplace.name`：插件安装来源的市场（已知时）。在与 `plugin.name` 相同的条件下编辑为 `"third-party"`

765* `plugin.version`：来自插件清单的版本。仅当名称未被编辑且清单声明版本时才包含

766* `plugin.scope`：插件的来源类别：`"official"`、`"org"`、`"user-local"` 或 `"default-bundle"`

767* `enabled_via`：插件如何被启用的方式：`"default-enable"`、`"org-policy"`、`"seed-mount"` 或 `"user-install"`

768* `plugin_id_hash`：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算整个队伍中加载了多少个不同的第三方插件，而无需记录其名称

769* `has_hooks`：插件是否贡献 hooks

770* `has_mcp`：插件是否贡献 MCP 服务器

771* `skill_path_count`：插件声明的技能目录数

772* `command_path_count`：插件声明的命令目录数

773* `agent_path_count`：插件声明的代理目录数

774

744#### 技能激活事件775#### 技能激活事件

745 776

746当调用技能时记录，无论 Claude 是通过 Skill 工具调用它还是您将其作为 `/` 命令运行。777当调用技能时记录，无论 Claude 是通过 Skill 工具调用它还是您将其作为 `/` 命令运行。

793* `total_retry_duration_ms`：所有尝试的总实际时钟时间824* `total_retry_duration_ms`：所有尝试的总实际时钟时间

794* `speed`：`"fast"` 或 `"normal"`825* `speed`：`"fast"` 或 `"normal"`

795 826

827#### Hook 已注册事件

828

829在会话开始时为每个配置的 hook 记录一次。使用此事件来清点您的整个队伍中哪些 hooks 处于活跃状态，作为每次执行 `hook_execution_start` 和 `hook_execution_complete` 事件的补充。

830

831**事件名称**：`claude_code.hook_registered`

832

833**属性**：

834

835* 所有 [标准属性](#standard-attributes)

836* `event.name`：`"hook_registered"`

837* `event.timestamp`：ISO 8601 时间戳

838* `event.sequence`：单调递增的计数器，用于在会话内排序事件

839* `hook_event`：hook 事件类型，例如 `"PreToolUse"` 或 `"PostToolUse"`

840* `hook_type`：hook 实现类型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

841* `hook_source`：hook 定义的位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

842* `hook_matcher`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：hook 配置中的匹配器字符串（设置时）

843* `plugin.name`（当 `hook_source` 是 `"pluginHook"` 时）：贡献插件的名称。对于官方市场外和内置捆绑的插件，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`

844* `plugin_id_hash`（当 `hook_source` 是 `"pluginHook"` 时）：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算不同的贡献插件数而无需记录其名称

845

796#### Hook 执行开始事件846#### Hook 执行开始事件

797 847

798当一个或多个 hooks 开始为 hook 事件执行时记录。848当一个或多个 hooks 开始为 hook 事件执行时记录。

855* `post_tokens`：压缩后的近似令牌计数905* `post_tokens`：压缩后的近似令牌计数

856* `error`：压缩失败时的错误消息906* `error`：压缩失败时的错误消息

857 907

908#### 反馈调查事件

909

910当显示或回答会话质量调查时记录。请参阅 [会话质量调查](/zh-CN/data-usage#session-quality-surveys) 了解调查收集的内容以及如何控制它们。

911

912**事件名称**：`claude_code.feedback_survey`

913

914**属性**：

915

916* 所有 [标准属性](#standard-attributes)

917* `event.name`：`"feedback_survey"`

918* `event.timestamp`：ISO 8601 时间戳

919* `event.sequence`：单调递增的计数器，用于在会话内排序事件

920* `event_type`：调查生命周期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`

921* `appearance_id`：唯一 ID，链接为一个调查实例发出的事件

922* `survey_type`：哪个调查产生了事件。`"session"` 是"Claude 做得怎么样？"评分提示

923* `response`：用户在 `responded` 事件上的选择

924* `enabled_via_override`：当设置了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/zh-CN/env-vars) 时为 `true`。作为布尔值而不是字符串发出。在 `session` 调查事件上存在。过滤此属性以确认覆盖在整个队伍中应用

925

858## 解释指标和事件数据926## 解释指标和事件数据

859 927

860导出的指标和事件支持一系列分析：928导出的指标和事件支持一系列分析：

862### 使用情况监控930### 使用情况监控

863 931

864| 指标 | 分析机会 |932| 指标 | 分析机会 |

865| ------------------------------------------------------------- | -------------------------- |933| ------------------------------------------------------------- | --------------------------------------------------------------------- |

874 942

875* 跟踪团队或个人的使用趋势943* 跟踪团队或个人的使用趋势

876* 识别高使用会话以进行优化944* 识别高使用会话以进行优化

945* 通过 `skill.name`、`plugin.name` 和 `agent.name` 属性将支出归属于特定技能、插件或子代理类型

877 946

878<Note>947<Note>

879 成本指标是近似值。有关官方计费数据，请参阅您的 API 提供商（Claude 控制台、Amazon Bedrock 或 Google Cloud Vertex）。948 成本指标是近似值。有关官方计费数据，请参阅您的 API 提供商（Claude 控制台、Amazon Bedrock 或 Google Cloud Vertex）。

910 979

911**性能监控**：跟踪 API 请求持续时间和工具执行时间以识别性能瓶颈。980**性能监控**：跟踪 API 请求持续时间和工具执行时间以识别性能瓶颈。

912 981

982## 审计安全事件

983

984OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件都携带身份属性，将工具调用、MCP 活动和权限决策与触发它们的用户联系起来，OTLP 日志导出器可以将这些事件传递到任何具有 OTLP 接收器的安全信息和事件管理 (SIEM) 平台或转发到您的 SIEM 的 OpenTelemetry Collector。

985

986### 将属性操作归属于用户

987

988每个事件上的 [标准属性](#standard-attributes) 包括已认证用户的身份：`user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`（使用 Claude 账户登录时），加上安装范围的 `user.id` 和每会话的 `session.id`。

989

990MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户。

991

992当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置：

993

994```bash theme={null}

995export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

996```

997

998### 审计 MCP 活动

999

1000要使用完整的调用详情捕获 MCP 服务器活动，启用日志导出器并设置 `OTEL_LOG_TOOL_DETAILS=1`。每个 MCP 操作然后产生结构化事件，携带服务器名称、工具名称和调用参数以及标准身份属性：

1001

1002| 事件 | 它为 MCP 记录的内容 |

1003| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |

1004| `mcp_server_connection` | 服务器连接、断开连接和连接失败，带有 `server_name`、`transport_type`、`server_scope` 和错误详情 |

1005| `tool_result` | 每个 MCP 工具调用，带有 `tool_name` 和 `mcp_server_scope`，包含 `mcp_server_name` 和 `mcp_tool_name` 的 `tool_parameters` 有效负载，以及包含调用参数的 `tool_input` 有效负载 |

1006| `tool_decision` | 调用是否被允许或拒绝，以及决策是来自配置、hook 还是用户 |

1007

1008没有 `OTEL_LOG_TOOL_DETAILS`，`tool_result` 事件仍然携带 `tool_name` 和 `mcp_server_scope` 但省略 `mcp_server_name`/`mcp_tool_name` 分解和参数，`mcp_server_connection` 事件省略 `server_name` 和错误消息。

1009

1010### 将安全问题映射到事件

1011

1012构建检测规则时，查找您想要监控的信号并查询您的后端以获取相应的事件和属性：

1013

1014| 信号 | 事件 | 关键属性 |

1015| ----------------- | ----------------------------------------- | ---------------------------------------------------------- |

1016| 工具调用被允许或拒绝，以及通过什么 | `tool_decision` | `decision`、`source`、`tool_name` |

1017| 权限模式升级 | `permission_mode_changed` | `from_mode`、`to_mode`、`trigger` |

1018| 策略 hook 阻止了操作 | `hook_execution_complete` | `hook_event`、`num_blocking` |

1019| 登录、登出和身份验证失败 | `auth` | `action`、`success`、`error_category` |

1020| MCP 服务器连接或失败 | `mcp_server_connection` | `status`、`server_name`、`error_code` |

1021| 插件已安装及其来源 | `plugin_installed` | `plugin.name`、`marketplace.name`、`marketplace.is_official` |

1022| 运行的命令和触及的文件 | `tool_result` 带 `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`、`tool_input` |

1023

1024Claude Code 仅发出原始事件流。异常检测、基线化、跨会话关联和警报是您的 SIEM 或可观测性后端的责任。

1025

1026### 将事件发送到 SIEM

1027

1028将 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 指向您的 SIEM 的 OTLP 接收器，或指向转发到您的 SIEM 的本机摄取 API 的 OpenTelemetry Collector。以下托管设置示例仅导出事件，启用了完整的工具详情用于 MCP 和 Bash 审计：

1029

1030```json theme={null}

1031{

1032 "env": {

1033 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

1034 "OTEL_LOGS_EXPORTER": "otlp",

1035 "OTEL_LOG_TOOL_DETAILS": "1",

1036 "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",

1037 "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",

1038 "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"

1039 }

1040}

1041```

1042

913## 后端考虑事项1043## 后端考虑事项

914 1044

915您选择的指标、日志和跟踪后端决定了您可以执行的分析类型：1045您选择的指标、日志和跟踪后端决定了您可以执行的分析类型：

953 1083

954## 安全和隐私1084## 安全和隐私

955 1085

956* OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅[数据使用](/zh-CN/data-usage#telemetry-services)1086* OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅 [数据使用](/zh-CN/data-usage#telemetry-services)

957* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号1087* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号

958* 通过 OAuth 认证时，`user.email` 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段1088* 通过 OAuth 认证时，`user.email` 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段

959* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`1089* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`

output-styles.md +7 −3

Details

14 14

15Claude Code 的**默认**输出样式是现有的系统提示，旨在帮助你高效地完成软件工程任务。15Claude Code 的**默认**输出样式是现有的系统提示，旨在帮助你高效地完成软件工程任务。

16 16

~~17还有两种额外的内置输出样式，专注于教你了解代码库和 Claude 的运作方式：~~17还有三种额外的内置输出样式：

19* **Proactive**：Claude 立即执行，做出合理的假设而不是暂停进行常规决策，并倾向于行动而非规划。这应用了与[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)相同的指导，而不改变你的权限模式，因此你仍然会在工具运行前看到权限提示。

18 20

19* **Explanatory**：在帮助你完成软件工程任务的同时提供教育性的"Insights"。帮助你理解实现选择和代码库模式。21* **Explanatory**：在帮助你完成软件工程任务的同时提供教育性的"Insights"。帮助你理解实现选择和代码库模式。

20 22

88 90

89### 输出样式 vs. CLAUDE.md vs. --append-system-prompt91### 输出样式 vs. CLAUDE.md vs. --append-system-prompt

90 92

91输出样式完全"关闭"了 Claude Code 默认系统提示中特定于软件工程的部分。CLAUDE.md 和 `--append-system-prompt` 都不会编辑 Claude Code 的默认系统提示。CLAUDE.md 将内容作为用户消息添加到 Claude Code 默认系统提示\_之后\_。`--append-system-prompt` 将内容附加到系统提示。93根据 Claude 是否应该停止充当编码助手或保持其默认角色并学习更多内容来选择。输出样式用你自己的角色和声音替换 Claude Code 系统提示中的软件工程部分，因此当 Claude 应该采用不同的身份（如写作编辑或数据分析助手）时，请使用一种。CLAUDE.md 和 `--append-system-prompt` 都保持 Claude Code 的默认身份并添加到它，因此当 Claude 应该保持编码助手身份同时遵循你的项目约定或额外说明时，请使用它们。

95机制也不同。输出样式直接编辑系统提示。CLAUDE.md 在系统提示之后将其内容作为用户消息添加。`--append-system-prompt` 将内容附加到系统提示的末尾，而不删除任何内容。

92 96

93### 输出样式 vs. [Agents](/zh-CN/sub-agents)97### 输出样式 vs. [Agents](/zh-CN/sub-agents)

94 98

95输出样式直接影响主代理循环，仅影响系统提示。Agents 被调用来处理特定任务，可以包括额外的设置，如要使用的模型、可用的工具以及有关何时使用代理的一些上下文。99使用输出样式来改变主对话在每个会话中的响应方式。当你想要一个单独作用域的辅助工具，由主对话委派给它时，使用 [subagent](/zh-CN/sub-agents)。输出样式仅影响主代理循环的系统提示。Agents 处理特定任务，可以携带自己的模型、工具和关于何时调用它们的上下文。

96 100

97### 输出样式 vs. [Skills](/zh-CN/skills)101### 输出样式 vs. [Skills](/zh-CN/skills)

98 102

permission-modes.md +29 −1

Details

128 128

129再次按 `Shift+Tab` 离开 plan mode 而不批准计划。129再次按 `Shift+Tab` 离开 plan mode 而不批准计划。

130 130

131### 审查并批准计划

132

131当计划准备好时，Claude 呈现它并询问如何继续。从该提示您可以：133当计划准备好时，Claude 呈现它并询问如何继续。从该提示您可以：

132 134

133* 批准并在 auto mode 中启动135* 批准并在 auto mode 中启动

136* 继续规划并提供反馈138* 继续规划并提供反馈

137* 使用 [Ultraplan](/zh-CN/ultraplan) 进行基于浏览器的审查进行细化139* 使用 [Ultraplan](/zh-CN/ultraplan) 进行基于浏览器的审查进行细化

138 140

139每个批准选项也提供首先清除规划上下文的选项。141批准计划会退出 plan mode 并将会话切换到每个批准选项描述的权限模式，因此 Claude 开始编辑。要再次规划，使用 `Shift+Tab` 循环回到 plan mode，或在下一个提示前加上 `/plan`。

142

143按 `Ctrl+G` 在您的默认文本编辑器中打开提议的计划并在 Claude 继续之前直接编辑它。当启用 [`showClearContextOnPlanAccept`](/zh-CN/settings#available-settings) 时，每个批准选项也提供首先清除规划上下文的选项。

144

145接受计划也会根据计划内容自动命名会话，除非您已经使用 `--name` 或 `/rename` 设置了名称。

146

147### 将 plan mode 设置为默认值

148

149要使 plan mode 成为项目的默认值，请在 `.claude/settings.json` 中设置 `defaultMode`：

150

151```json theme={null}

152{

153 "permissions": {

154 "defaultMode": "plan"

155 }

156}

157```

140 158

141## 使用 auto mode 消除提示159## 使用 auto mode 消除提示

142 160

146 164

147Auto mode 让 Claude 执行而无需权限提示。一个单独的分类器模型在操作运行前审查操作，阻止任何超出您请求范围的操作、针对无法识别的基础设施的操作，或似乎由 Claude 读到的恶意内容驱动的操作。165Auto mode 让 Claude 执行而无需权限提示。一个单独的分类器模型在操作运行前审查操作，阻止任何超出您请求范围的操作、针对无法识别的基础设施的操作，或似乎由 Claude 读到的恶意内容驱动的操作。

148 166

167Auto mode 还指示 Claude 立即执行并最小化澄清问题。要在保持权限提示的同时获得该行为，请改为设置[主动输出风格](/zh-CN/output-styles)。

168

149<Warning>169<Warning>

150 Auto mode 是研究预览版。它减少提示但不保证安全。将其用于您信任一般方向的任务，而不是作为敏感操作审查的替代品。170 Auto mode 是研究预览版。它减少提示但不保证安全。将其用于您信任一般方向的任务，而不是作为敏感操作审查的替代品。

151</Warning>171</Warning>

256 276

257`--dangerously-skip-permissions` 标志等同。277`--dangerously-skip-permissions` 标志等同。

258 278

279在 Linux 和 macOS 上，当以 root 身份或在 `sudo` 下运行时，Claude Code 拒绝以此模式启动：

280

281```text theme={null}

282--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

283```

284

285在识别的沙箱内自动跳过该检查。要在容器中自主运行，请使用 [dev container](/zh-CN/devcontainer) 配置，该配置以非 root 用户身份运行 Claude Code。

286

259<Warning>287<Warning>

260 `bypassPermissions` 不提供针对提示注入或意外操作的保护。对于没有提示的后台安全检查，请改为使用 [auto mode](#eliminate-prompts-with-auto-mode)。管理员可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableBypassPermissionsMode` 设置为 `"disable"` 来阻止此模式。288 `bypassPermissions` 不提供针对提示注入或意外操作的保护。对于没有提示的后台安全检查，请改为使用 [auto mode](#eliminate-prompts-with-auto-mode)。管理员可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableBypassPermissionsMode` 设置为 `"disable"` 来阻止此模式。

261</Warning>289</Warning>

permissions.md +5 −1

Details

28 28

29规则按顺序评估：**deny -> ask -> allow**。第一个匹配的规则获胜，因此 deny 规则始终优先。29规则按顺序评估：**deny -> ask -> allow**。第一个匹配的规则获胜，因此 deny 规则始终优先。

30 30

31<Note>

32 权限规则由 Claude Code 强制执行，而不是由模型强制执行。您的提示或 `CLAUDE.md` 中的说明会影响 Claude 尝试执行的操作，但它们不会改变 Claude Code 允许的操作。要授予或撤销访问权限，请使用 `/permissions`、此处描述的规则、[权限模式](/zh-CN/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。

33</Note>

31## 权限模式35## 权限模式

32 36

33Claude Code 支持多种权限模式来控制工具的批准方式。请参阅[权限模式](/zh-CN/permission-modes)了解何时使用每种模式。在您的[设置文件](/zh-CN/settings#settings-files)中设置 `defaultMode`：37Claude Code 支持多种权限模式来控制工具的批准方式。请参阅[权限模式](/zh-CN/permission-modes)了解何时使用每种模式。在您的[设置文件](/zh-CN/settings#settings-files)中设置 `defaultMode`：

153 157

154 * **限制 Bash 网络工具**：使用 deny 规则阻止 `curl`、`wget` 和类似命令，然后对允许的域使用带有 `WebFetch(domain:github.com)` 权限的 WebFetch 工具158 * **限制 Bash 网络工具**：使用 deny 规则阻止 `curl`、`wget` 和类似命令，然后对允许的域使用带有 `WebFetch(domain:github.com)` 权限的 WebFetch 工具

155 * **使用 PreToolUse hooks**：实现一个 hook 来验证 Bash 命令中的 URL 并阻止不允许的域159 * **使用 PreToolUse hooks**：实现一个 hook 来验证 Bash 命令中的 URL 并阻止不允许的域

156 * 通过 CLAUDE.md 指示 Claude Code 关于您允许的 curl 模式160 * **添加 CLAUDE.md 指导**：在 `CLAUDE.md` 中描述您允许的 curl 模式。这会影响 Claude 尝试的内容，但不会强制执行边界，因此请将其与上述选项之一配对

157 161

158 请注意，仅使用 WebFetch 不会阻止网络访问。如果允许 Bash，Claude 仍然可以使用 `curl`、`wget` 或其他工具来访问任何 URL。162 请注意，仅使用 WebFetch 不会阻止网络访问。如果允许 Bash，Claude 仍然可以使用 `curl`、`wget` 或其他工具来访问任何 URL。

159</Warning>163</Warning>

plugins.md +6 −0

Details

299claude --plugin-dir ./my-plugin299claude --plugin-dir ./my-plugin

300```300```

301 301

302该标志也接受插件目录的 `.zip` 存档，这需要 Claude Code v2.1.128 或更高版本。

303

304```bash theme={null}

305claude --plugin-dir ./my-plugin.zip

306```

307

302当 `--plugin-dir` 插件与已安装的市场插件同名时，本地副本在该会话中优先。这让你可以测试已安装的插件的更改，而无需先卸载它。由托管设置强制启用的市场插件是唯一的例外，无法被覆盖。308当 `--plugin-dir` 插件与已安装的市场插件同名时，本地副本在该会话中优先。这让你可以测试已安装的插件的更改，而无需先卸载它。由托管设置强制启用的市场插件是唯一的例外，无法被覆盖。

303 309

304当你对插件进行更改时，运行 `/reload-plugins` 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers。测试你的插件组件：310当你对插件进行更改时，运行 `/reload-plugins` 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers。测试你的插件组件：

plugins-reference.md +77 −17

Details

42* Claude 可以根据任务上下文自动调用它们42* Claude 可以根据任务上下文自动调用它们

43* Skills 可以在 SKILL.md 旁边包含支持文件43* Skills 可以在 SKILL.md 旁边包含支持文件

44 44

~~45有关完整详情，请参阅[Skills](/zh-CN/skills)。~~45有关完整详情，请参阅 [Skills](/zh-CN/skills)。

46 46

47### Agents47### Agents

48 48

76* Agents 可以由用户手动调用76* Agents 可以由用户手动调用

77* Plugin agents 与内置 Claude agents 一起工作77* Plugin agents 与内置 Claude agents 一起工作

78 78

~~79有关完整详情，请参阅[Subagents](/zh-CN/sub-agents)。~~79有关完整详情，请参阅 [Subagents](/zh-CN/sub-agents)。

80 80

81### Hooks81### Hooks

82 82

97 "hooks": [97 "hooks": [

98 {98 {

99 "type": "command",99 "type": "command",

100 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"100 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"

101 }101 }

102 ]102 ]

103 }103 }

106}106}

107```107```

108 108

109Plugin hooks 响应与[用户定义的 hooks](/zh-CN/hooks)相同的生命周期事件：109Plugin hooks 响应与 [用户定义的 hooks](/zh-CN/hooks) 相同的生命周期事件：

110 110

111| Event | When it fires |111| Event | When it fires |

112| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |112| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

190 想要使用 LSP plugins？从官方市场安装它们：在 `/plugin` Discover 选项卡中搜索"lsp"。本部分记录了如何为官方市场未涵盖的语言创建 LSP plugins。190 想要使用 LSP plugins？从官方市场安装它们：在 `/plugin` Discover 选项卡中搜索"lsp"。本部分记录了如何为官方市场未涵盖的语言创建 LSP plugins。

191</Tip>191</Tip>

192 192

193Plugins 可以提供[Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers，在处理代码库时为 Claude 提供实时代码智能。193Plugins 可以提供 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers，在处理代码库时为 Claude 提供实时代码智能。

194 194

195LSP 集成提供：195LSP 集成提供：

196 196

273 273

274Plugins 可以声明后台 monitors，Claude Code 在 plugin 激活时自动启动。每个 monitor 为会话的生命周期运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，以便 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视本身。274Plugins 可以声明后台 monitors，Claude Code 在 plugin 激活时自动启动。每个 monitor 为会话的生命周期运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，以便 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视本身。

275 275

276Plugin monitors 使用与[Monitor tool](/zh-CN/tools-reference#monitor-tool)相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，在与[hooks](#hooks)相同的信任级别上无沙箱运行，并在 Monitor tool 不可用的主机上跳过。276Plugin monitors 使用与 [Monitor tool](/zh-CN/tools-reference#monitor-tool) 相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，在与 [hooks](#hooks) 相同的信任级别上无沙箱运行，并在 Monitor tool 不可用的主机上跳过。

277 277

278<Note>278<Note>

279 Plugin monitors 需要 Claude Code v2.1.105 或更高版本。279 Plugin monitors 需要 Claude Code v2.1.105 或更高版本。

289[289[

290 {290 {

291 "name": "deploy-status",291 "name": "deploy-status",

292 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",292 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",

293 "description": "Deployment status changes"293 "description": "Deployment status changes"

294 },294 },

295 {295 {

301]301]

302```302```

303 303

304要内联声明 monitors，请将 `plugin.json` 中的 `experimental.monitors` 设置为相同的数组。要从非默认路径加载，请将 `experimental.monitors` 设置为相对路径字符串，例如 `"./config/monitors.json"`。Monitors 是一个[实验性组件](#experimental-components)。304要内联声明 monitors，请将 `plugin.json` 中的 `experimental.monitors` 设置为相同的数组。要从非默认路径加载，请将 `experimental.monitors` 设置为相对路径字符串，例如 `"./config/monitors.json"`。Monitors 是一个 [实验性组件](#experimental-components)。

305 305

306**必需字段：**306**必需字段：**

307 307

317| :----- | :---------------------------------------------------------------------------------------------------------- |317| :----- | :---------------------------------------------------------------------------------------------------------- |

319 319

320`command` 值支持与 MCP 和 LSP server 配置相同的[变量替换](#environment-variables)：`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${user_config.*}` 和环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自己的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。320`command` 值支持与 MCP 和 LSP server 配置相同的 [变量替换](#environment-variables)：`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${CLAUDE_PROJECT_DIR}`、`${user_config.*}` 和环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自己的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

321 321

322在会话中途禁用插件不会停止已在运行的 monitors。它们在会话结束时停止。322在会话中途禁用插件不会停止已在运行的 monitors。它们在会话结束时停止。

323 323

324### Themes324### Themes

325 325

326Plugins 可以提供颜色主题，这些主题与内置预设和用户的本地主题一起出现在 `/theme` 中。主题是 `themes/` 中的 JSON 文件，具有 `base` 预设和稀疏的 `overrides` 颜色令牌映射。Themes 是一个[实验性组件](#experimental-components)。326Plugins 可以提供颜色主题，这些主题与内置预设和用户的本地主题一起出现在 `/theme` 中。主题是 `themes/` 中的 JSON 文件，具有 `base` 预设和稀疏的 `overrides` 颜色令牌映射。Themes 是一个 [实验性组件](#experimental-components)。

327 327

328```json theme={null}328```json theme={null}

329{329{

540 540

541### 环境变量541### 环境变量

542 542

543Claude Code 提供两个变量用于引用 plugin 路径。两者都在 skill 内容、agent 内容、hook 命令、monitor 命令以及 MCP 或 LSP server 配置中出现的任何地方进行内联替换。两者也都作为环境变量导出到 hook 进程和 MCP 或 LSP server 子进程。543Claude Code 提供三个变量用于引用路径。所有这些变量都在 skill 内容、agent 内容、hook 命令、monitor 命令以及 MCP 或 LSP server 配置中出现的任何地方进行内联替换。所有这些变量也都作为环境变量导出到 hook 进程和 MCP 或 LSP server 子进程。

544 544

545**`${CLAUDE_PLUGIN_ROOT}`**：plugin 安装目录的绝对路径。使用此路径引用与 plugin 捆绑的脚本、二进制文件和配置文件。当 plugin 更新时，此路径会更改。前一个版本的目录在更新后约七天内保留在磁盘上以进行清理，但应将其视为临时的，不要在此处写入状态。545**`${CLAUDE_PLUGIN_ROOT}`**：plugin 安装目录的绝对路径。使用此路径引用与 plugin 捆绑的脚本、二进制文件和配置文件。在 hook 命令中，使用[执行形式](/zh-CN/hooks#exec-form-and-shell-form)与 `args` 以便路径作为一个参数传递，无需引用。在 shell 形式的 hooks 和 monitor 命令中，用双引号包装它，如 `"${CLAUDE_PLUGIN_ROOT}"`。当 plugin 更新时，此路径会更改。前一个版本的目录在更新后约七天内保留在磁盘上以进行清理，但应将其视为临时的，不要在此处写入状态。

546 546

547当 plugin 在会话中期更新时，hook 命令、monitors、MCP servers 和 LSP servers 继续使用前一个版本的路径。运行 `/reload-plugins` 以将 hooks、MCP servers 和 LSP servers 切换到新路径；monitors 需要会话重启。547当 plugin 在会话中期更新时，hook 命令、monitors、MCP servers 和 LSP servers 继续使用前一个版本的路径。运行 `/reload-plugins` 以将 hooks、MCP servers 和 LSP servers 切换到新路径；monitors 需要会话重启。

548 548

549**`${CLAUDE_PLUGIN_DATA}`**：用于 plugin 状态的持久目录，在更新后保留。使用此目录用于已安装的依赖项，如 `node_modules` 或 Python 虚拟环境、生成的代码、缓存以及任何应在 plugin 版本之间保留的其他文件。首次引用此变量时，目录会自动创建。549**`${CLAUDE_PLUGIN_DATA}`**：用于 plugin 状态的持久目录，在更新后保留。使用此目录用于已安装的依赖项，如 `node_modules` 或 Python 虚拟环境、生成的代码、缓存以及任何应在 plugin 版本之间保留的其他文件。首次引用此变量时，目录会自动创建。

550 550

551**`${CLAUDE_PROJECT_DIR}`**：项目根目录。这是 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的相同目录。使用此路径引用项目本地脚本或配置文件。用引号包装以处理包含空格的路径，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。MCP servers 也可以调用 MCP `roots/list` 请求，该请求返回启动 Claude Code 的目录。

552

551```json theme={null}553```json theme={null}

552{554{

553 "hooks": {555 "hooks": {

556 "hooks": [558 "hooks": [

557 {559 {

558 "type": "command",560 "type": "command",

559 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"561 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

560 }562 }

561 ]563 ]

562 }564 }

629 631

630已安装的 plugins 无法引用其目录外的文件。遍历 plugin 根目录外的路径（例如 `../shared-utils`）在安装后将不起作用，因为这些外部文件不会被复制到缓存中。632已安装的 plugins 无法引用其目录外的文件。遍历 plugin 根目录外的路径（例如 `../shared-utils`）在安装后将不起作用，因为这些外部文件不会被复制到缓存中。

631 633

632### 使用外部依赖634### 使用符号链接在市场内共享文件

635

636如果您的 plugin 需要与同一市场的其他部分共享文件，您可以在 plugin 目录中创建符号链接。当 plugin 被复制到缓存中时，符号链接的处理方式取决于其目标的解析位置：

637

638* **在 plugin 自己的目录内：** 符号链接在缓存中被保留为相对符号链接，因此它在运行时继续解析到复制的目标。

639* **在同一市场内的其他位置：** 符号链接被解引用。目标的内容被复制到缓存中以替代它。这允许元 plugin 的 `skills/` 目录链接到市场中其他 plugins 定义的技能。

640* **在市场外：** 符号链接出于安全考虑被跳过。这防止 plugins 从任意主机文件（如系统路径）拉入缓存。

633 641

634如果您的 plugin 需要访问其目录外的文件，您可以在 plugin 目录中创建指向外部文件的符号链接。符号链接在缓存中被保留而不是解引用，并在运行时解析到其目标。以下命令在插件目录内创建指向共享实用程序位置的链接：642对于使用 `--plugin-dir` 安装或从本地路径安装的 plugins，只有解析到 plugin 自己目录内的符号链接被保留。所有其他的都被跳过。

643

644以下命令创建从市场 plugin 内部到由同级 plugin 定义的共享技能的链接。在 Windows 上，从提升的命令提示符使用 `mklink /D` 或启用开发者模式：

635 645

636```bash theme={null}646```bash theme={null}

637ln -s /path/to/shared-utils ./shared-utils647ln -s ../../shared-plugin/skills/foo ./skills/foo

638```648```

639 649

640这在保持缓存系统安全优势的同时提供了灵活性。650这在保持缓存系统安全优势的同时提供了灵活性。

877 887

888### plugin details

889

890显示 plugin 的组件清单和预计令牌成本。输出列出 plugin 贡献的所有组件，分组为 Skills（技能和命令）、Agents、Hooks 和 MCP servers，以及它为每个会话添加多少令牌的估计。

891

892```bash theme={null}

893claude plugin details <name>

894```

895

896**参数：**

897

898* `<name>`：Plugin 名称或 `plugin-name@marketplace-name`

899

900**选项：**

901

902| 选项 | 描述 | 默认值 |

903| :----------- | :----- | :-- |

904| `-h, --help` | 显示命令帮助 | |

905

906输出为每个组件显示两个成本数字：

907

908* **Always-on：** plugin 的列表文本（如技能描述、agent 描述和命令名称）添加到每个会话的令牌，无论是否有任何组件触发。

909* **On-invoke：** 组件触发时的成本令牌。按组件显示，而不是作为 plugin 总计，因为典型会话仅调用组件的子集。

910

911此示例显示具有两个技能的 plugin 的输出外观：

912

913```

914security-guidance 1.2.0

915 Real-time security analysis for Claude Code sessions

916 Source: security-guidance@claude-code-marketplace

917

918Component inventory

919 Skills (2) scan-dependencies, review-changes

920 Agents (0)

921 Hooks (1) (harness-only — no model context cost)

922 MCP servers (0)

923

924Projected token cost

925 Always-on: ~180 tok added to every session

926

927Per-component (rounded)

928 component always-on on-invoke

929 scan-dependencies ~100 ~2400

930 review-changes ~80 ~1800

931

932 On-invoke cost is paid each time a skill or agent fires.

933 Token counts are estimates and may differ from actual usage.

934```

935

936always-on 总计通过您的活跃模型的 `count_tokens` API 计算。按组件的数字按比例从该总计缩放。如果 API 无法访问，该命令会回退到基于字符的估计。

937

878### plugin tag938### plugin tag

879 939

880为当前目录中的 plugin 创建发布 git 标签。从 plugin 的文件夹内运行。请参阅[标记 plugin 发布](/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)。940为当前目录中的 plugin 创建发布 git 标签。从 plugin 的文件夹内运行。请参阅[标记 plugin 发布](/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

938 998

9391. 检查脚本是否可执行：`chmod +x ./scripts/your-script.sh`9991. 检查脚本是否可执行：`chmod +x ./scripts/your-script.sh`

9402. 验证 shebang 行：第一行应该是 `#!/bin/bash` 或 `#!/usr/bin/env bash`10002. 验证 shebang 行：第一行应该是 `#!/bin/bash` 或 `#!/usr/bin/env bash`

9413. 检查路径是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`10013. 检查路径是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`

9424. 手动测试脚本：`./scripts/your-script.sh`10024. 手动测试脚本：`./scripts/your-script.sh`

943 1003

944**Hook 未在预期事件上触发**：1004**Hook 未在预期事件上触发**：

quickstart.md +4 −4

Details

279 279

280<AccordionGroup>280<AccordionGroup>

281 <Accordion title="对您的请求要具体">281 <Accordion title="对您的请求要具体">

282 不要说：'修复错误'282 不要说："修复错误"

283 283

284 尝试：'修复登录错误，用户输入错误凭证后看到空白屏幕'284 尝试："修复登录错误，用户输入错误凭证后看到空白屏幕"

285 </Accordion>285 </Accordion>

286 286

287 <Accordion title="使用分步说明">287 <Accordion title="使用分步说明">

307 </Accordion>307 </Accordion>

308 308

309 <Accordion title="使用快捷方式节省时间">309 <Accordion title="使用快捷方式节省时间">

310 * 按 `?` 查看所有可用的快捷键310 * 输入 `/` 查看所有命令和 skills

311 * 使用 Tab 进行命令补全311 * 使用 Tab 进行命令补全

312 * 按 ↑ 查看命令历史312 * 按 ↑ 查看命令历史

313 * 输入 `/` 查看所有命令和 skills313 * 按 `Shift+Tab` 循环切换权限模式

314 </Accordion>314 </Accordion>

315</AccordionGroup>315</AccordionGroup>

316 316

routines.md +2 −0

Details

318 318

319Routines 可以使用您连接的 MCP connectors 在每次运行期间读取和写入外部服务。例如，分类支持请求的例程可能从 Slack 频道读取并在 Linear 中创建问题。319Routines 可以使用您连接的 MCP connectors 在每次运行期间读取和写入外部服务。例如，分类支持请求的例程可能从 Slack 频道读取并在 Linear 中创建问题。

320 320

321Connectors 是您账户上的 [claude.ai integrations](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。您在 CLI 中使用 `claude mcp add` 本地添加的 MCP 服务器存储在您的机器上而不是您的 claude.ai 账户上，因此它们不会出现在 connectors 列表中。要在例程中使用其中一个服务器，请在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 处将其添加为 connector，或在提交的 [`.mcp.json`](/zh-CN/mcp#project-scope) 中声明它，以便它是克隆存储库的一部分。

322

321创建例程时，默认情况下包括您当前连接的所有 connectors。删除不需要的任何内容以限制 Claude 在运行期间可以访问的工具。您也可以直接从例程表单添加 connectors。323创建例程时，默认情况下包括您当前连接的所有 connectors。删除不需要的任何内容以限制 Claude 在运行期间可以访问的工具。您也可以直接从例程表单添加 connectors。

322 324

323要在例程表单外管理或添加 connectors，请访问 claude.ai 上的 **Settings > Connectors** 或在 CLI 中使用 `/schedule update`。325要在例程表单外管理或添加 connectors，请访问 claude.ai 上的 **Settings > Connectors** 或在 CLI 中使用 `/schedule update`。

security.md +1 −1

Details

85 85

86Claude Code 允许用户配置 Model Context Protocol (MCP) servers。允许的 MCP servers 列表在您的源代码中配置，作为 Claude Code 设置的一部分，工程师将其检入源代码控制。86Claude Code 允许用户配置 Model Context Protocol (MCP) servers。允许的 MCP servers 列表在您的源代码中配置，作为 Claude Code 设置的一部分，工程师将其检入源代码控制。

87 87

88我们鼓励编写您自己的 MCP servers 或使用来自您信任的提供商的 MCP servers。您能够为 MCP servers 配置 Claude Code 权限。Anthropic 不管理或审计任何 MCP servers。88我们鼓励编写您自己的 MCP servers 或使用来自您信任的提供商的 MCP servers。您能够为 MCP servers 配置 Claude Code 权限。Anthropic 在将连接器添加到 [Anthropic Directory](https://claude.ai/directory) 之前，会根据其 [列表标准](https://claude.com/docs/connectors/building/review-criteria) 审查连接器，但不对任何 MCP server 进行安全审计或管理。

89 89

90## IDE 安全性90## IDE 安全性

91 91

settings.md +3 −1

Details

179| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

180| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |180| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |

181| `claudeMd` | （仅 Managed 设置）CLAUDE.md 风格的说明，作为组织管理的内存注入。仅在 managed 或策略设置中设置时被尊重，在用户、项目和本地设置中被忽略。请参阅[组织范围的 CLAUDE.md](/zh-CN/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

181| `claudeMdExcludes` | 加载[内存](/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |182| `claudeMdExcludes` | 加载[内存](/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |

182| `cleanupPeriodDays` | 非活跃时间超过此期间的会话在启动时被删除（默认：30 天，最少 1 天）。设置为 `0` 会被拒绝并显示验证错误。也控制[孤立 subagent worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除的年龄截止。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量，或在非交互模式（`-p`）中使用 `--no-session-persistence` 标志或 `persistSession: false` SDK 选项。 | `20` |183| `cleanupPeriodDays` | 非活跃时间超过此期间的会话在启动时被删除（默认：30 天，最少 1 天）。设置为 `0` 会被拒绝并显示验证错误。也控制[孤立 subagent worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除的年龄截止。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量，或在非交互模式（`-p`）中使用 `--no-session-persistence` 标志或 `persistSession: false` SDK 选项。 | `20` |

253</Note>254</Note>

254 255

255| 键 | 描述 | 示例 |256| 键 | 描述 | 示例 |

256| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |257| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |

258| `autoInstallIdeExtension` | 从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。默认：`true`。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。您也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-CN/env-vars) 环境变量 | `false` |259| `autoInstallIdeExtension` | 从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。默认：`true`。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。您也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-CN/env-vars) 环境变量 | `false` |

261| `teammateDefaultModel` | [agent team](/zh-CN/agent-teams) 队友的默认模型，当生成提示未指定时。设置为模型别名（如 `"sonnet"`），或 `null` 以继承主导的当前 `/model` 选择。在 `/config` 中显示为**默认队友模型** | `"sonnet"` |

260 262

261### Worktree 设置263### Worktree 设置

262 264

vs-code.md +4 −2

Details

233</Note>233</Note>

234 234

235| 命令 | 快捷键 | 描述 |235| 命令 | 快捷键 | 描述 |

236| --------- | ----------------------------------------------------- | ---------------------------------------------------------------- |236| ---------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |

238| 在边栏中打开 | - | 在左侧边栏中打开 Claude |238| 在边栏中打开 | - | 在左侧边栏中打开 Claude |

239| 在终端中打开 | - | 在终端模式下打开 Claude |239| 在终端中打开 | - | 在终端模式下打开 Claude |

241| 在新窗口中打开 | - | 在单独的窗口中打开新对话 |241| 在新窗口中打开 | - | 在单独的窗口中打开新对话 |

242| 新对话 | `Cmd+N`（Mac）/ `Ctrl+N`（Windows/Linux） | 开始新对话。需要 Claude 获得焦点且 `enableNewConversationShortcut` 设置为 `true` |242| 新对话 | `Cmd+N`（Mac）/ `Ctrl+N`（Windows/Linux） | 开始新对话。需要 Claude 获得焦点且 `enableNewConversationShortcut` 设置为 `true` |

243| 重新打开已关闭的会话 | `Cmd+Shift+T`（Mac）/ `Ctrl+Shift+T`（Windows/Linux） | 重新打开最近关闭的 Claude 会话选项卡。当最后关闭的选项卡不是 Claude 会话时，回退到 VS Code 的正常重新打开已关闭编辑器。使用 `enableReopenClosedSessionShortcut` 禁用 |

244| 显示日志 | - | 查看扩展调试日志 |245| 显示日志 | - | 查看扩展调试日志 |

245| 登出 | - | 登出您的 Anthropic 账户 |246| 登出 | - | 登出您的 Anthropic 账户 |

307### 扩展设置308### 扩展设置

308 309

309| 设置 | 默认值 | 描述 |310| 设置 | 默认值 | 描述 |

310| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |311| ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

318| `enableReopenClosedSessionShortcut` | `true` | 使用 Cmd/Ctrl+Shift+T 重新打开最近关闭的 Claude 会话选项卡。当最后关闭的选项卡不是 Claude 会话时，快捷键会运行 VS Code 的正常重新打开关闭编辑器命令。 |

Documentation 2026-05-11 23:00 UTC to 2026-05-12 22:57 UTC