Documentation — Spybara

agent-sdk/agent-loop.md +7 −1

Details

216| 选项 | 它控制什么 | 默认值 |216| 选项 | 它控制什么 | 默认值 |

217| :- | :- | :- |217| :- | :- | :- |

218| 最大轮次（`max_turns` / `maxTurns`） | 最大工具使用往返次数 | 无限制 |218| 最大轮次（`max_turns` / `maxTurns`） | 最大工具使用往返次数 | 无限制 |

219| 最大预算（`max_budget_usd` / `maxBudgetUsd`） | 停止前的最大成本 | 无限制 |219| 最大预算（`max_budget_usd` / `maxBudgetUsd`） | 循环停止时的预估支出 | 无限制 |

220 220

221当达到任一限制时，SDK 返回一个 `ResultMessage`，包含相应的错误子类型（`error_max_turns` 或 `error_max_budget_usd`）。有关如何检查这些子类型，请参阅 [处理结果](#handle-the-result)，有关语法，请参阅 [`ClaudeAgentOptions`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/zh-CN/agent-sdk/typescript#options)。221当达到任一限制时，SDK 返回一个 `ResultMessage`，包含相应的错误子类型（`error_max_turns` 或 `error_max_budget_usd`）。有关如何检查这些子类型，请参阅 [处理结果](#handle-the-result)，有关语法，请参阅 [`ClaudeAgentOptions`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/zh-CN/agent-sdk/typescript#options)。

222 222

224 224

225使用 [流式输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)，当轮次在最大轮次限制处结束时，仍在队列中的消息保持排队。Claude Code 不会将其添加到该轮次的最后一次模型调用中。它为该消息启动新轮次，该轮次的最大轮次计数重新开始。预算总额继续在消息间累积，一旦支出达到 `maxBudgetUsd`，同一对话中的后续消息以 `error_max_budget_usd` 结果结束。[`/clear`](/docs/zh-CN/agent-sdk/cost-tracking) 会重新开始预算。225使用 [流式输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)，当轮次在最大轮次限制处结束时，仍在队列中的消息保持排队。Claude Code 不会将其添加到该轮次的最后一次模型调用中。它为该消息启动新轮次，该轮次的最大轮次计数重新开始。预算总额继续在消息间累积，一旦支出达到 `maxBudgetUsd`，同一对话中的后续消息以 `error_max_budget_usd` 结果结束。[`/clear`](/docs/zh-CN/agent-sdk/cost-tracking) 会重新开始预算。

226 226

227<h4 id="budget-headroom">

228 预算余量

229</h4>

230

231Claude Code 在模型响应到达后才将支出与 `max_budget_usd` / `maxBudgetUsd` 上限进行比较，因为每个响应的成本来自 API 随响应返回的 token 用量。达到上限的那个响应仍会完成，并计入 [`total_cost_usd`](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。因此，支出最多可能超出上限该响应的成本，再加上此时仍在运行的子代理在停止前产生的任何支出。设置上限时，请为此预留余量。

232

227<h3 id="effort-level">233<h3 id="effort-level">

228 努力级别234 努力级别

229</h3>235</h3>

agent-sdk/permissions.md +1 −1

Details

147 147

148<Warning>148<Warning>

149 **子代理继承：** 子代理在父会话的权限模式下运行，除非您在其[`AgentDefinition`](/docs/zh-CN/agent-sdk/typescript#agentdefinition)上设置 `permissionMode`，且父会话处于 `default`、`dontAsk` 或 `plan` 模式。即使这样，Claude Code 也永远不会应用 `"bypassPermissions"` 值。子代理仅在父会话本身处于 `bypassPermissions` 模式时才在该模式下运行。 `bypassPermissions` 异常需要 Claude Code v2.1.267 或更高版本。149 **子代理继承：** 子代理在父会话的权限模式下运行，除非您在其[`AgentDefinition`](/docs/zh-CN/agent-sdk/typescript#agentdefinition)上设置 `permissionMode`，且父会话处于 `default`、`dontAsk` 或 `plan` 模式。即使这样，Claude Code 也永远不会应用 `"bypassPermissions"` 值，并且仅当该子代理[可以使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时才会应用 `"auto"` 值。子代理仅在父会话本身处于 `bypassPermissions` 模式时才在该模式下运行。 `bypassPermissions` 异常需要 Claude Code v2.1.267 或更高版本。

150 150

151 子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 `bypassPermissions` 会授予它们完整的自主系统访问权限。[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用。151 子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 `bypassPermissions` 会授予它们完整的自主系统访问权限。[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用。

152</Warning>152</Warning>

agent-sdk/python.md +2 −1

Details

932| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。限定规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，针对[按书写形式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。限定规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，针对[按书写形式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

3327{3327{

3328 "url": str, # 要从中获取内容的 URL3328 "url": str, # 要从中获取内容的 URL

3329 "prompt": str, # 要在获取的内容上运行的提示词3329 "prompt": str, # 要在获取的内容上运行的提示词

3330 "offset": int | None, # 从页面开头跳过的字符数。需要 Python Agent SDK 0.2.164 或更高版本

3330}3331}

3331```3332```

3332 3333

agent-sdk/subagents.md +9 −2

Details

323 检测子代理调用323 检测子代理调用

324</h2>324</h2>

325 325

326Claude 通过 Agent 工具调用子代理。要检测何时调用子代理，请检查 `tool_use` 块，其中 `name` 为 `"Agent"`。来自子代理上下文内的消息包含 `parent_tool_use_id` 字段。326Claude 通过 Agent 工具调用子代理。要检测何时调用子代理，请检查 `tool_use` 块，其中 `name` 为 `"Agent"`。

327

328来自子代理上下文内的消息包含 `parent_tool_use_id` 字段。在 TypeScript 中，子代理生成的每条 assistant 消息和 user 消息还带有 [`agent_id`](/docs/zh-CN/agent-sdk/typescript#sdkassistantmessage)：即该子代理的[任务事件](/docs/zh-CN/agent-sdk/typescript#sdktaskstartedmessage)中的 `task_id`。`agent_id` 需要 TypeScript Agent SDK v0.3.292 或更高版本。

327 329

328<Note>330<Note>

329 该工具在 `tool_use` 块中显示为 `"Agent"`，但在 `system:init` 工具列表中显示为 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 块也将其命名为 `"Task"`。为了保持检测在不同 SDK 版本中的工作，请在 `block.name` 中匹配两个值。331 该工具在 `tool_use` 块中显示为 `"Agent"`，但在 `system:init` 工具列表中显示为 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 块也将其命名为 `"Task"`。为了保持检测在不同 SDK 版本中的工作，请在 `block.name` 中匹配两个值。

331 333

332消息结构在不同 SDK 中有所不同。在 Python 中，您可以通过 `message.content` 直接访问内容块。在 TypeScript 中，`SDKAssistantMessage` 包装 Claude API 消息，因此您通过 `message.message.content` 访问内容。334消息结构在不同 SDK 中有所不同。在 Python 中，您可以通过 `message.content` 直接访问内容块。在 TypeScript 中，`SDKAssistantMessage` 包装 Claude API 消息，因此您通过 `message.message.content` 访问内容。

333 335

334此示例遍历流式消息，记录何时调用子代理以及后续消息来自该子代理执行上下文内的时间。336此示例遍历流式消息，记录何时调用子代理以及后续消息来自该子代理执行上下文内的时间。TypeScript 版本还会为每条带有 `agent_id` 的子代理消息记录该 `agent_id`。

335 337

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414

408 if ("result" in message) {415 if ("result" in message) {

agent-sdk/typescript.md +27 −4

Details

571| `managedSettings` | `Settings` | `undefined` | 由您的宿主进程提供给所生成会话的策略层级设置。在部署了管理员托管设置的机器上，除非管理员优先级最高的托管源设置了 `parentSettingsBehavior: 'merge'`，否则 Claude Code 会忽略这些设置；并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时，永远不会合并它们。合并的值会经过一个仅限收紧的过滤器；[限制父级设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)介绍了过滤器允许的内容以及 `allowManaged*Only` 锁定。设置了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的宿主会改为直接从此负载中读取三个键：在 Claude Code v2.1.222 或更高版本中读取其[模型配置](/docs/zh-CN/model-config#restrict-model-selection)；在 v2.1.246 或更高版本中，当没有托管源设置 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 时读取该键；在 v2.1.247 或更高版本中读取其 `ENABLE_TOOL_SEARCH` env 条目 |571| `managedSettings` | `Settings` | `undefined` | 由您的宿主进程提供给所生成会话的策略层级设置。在部署了管理员托管设置的机器上，除非管理员优先级最高的托管源设置了 `parentSettingsBehavior: 'merge'`，否则 Claude Code 会忽略这些设置；并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时，永远不会合并它们。合并的值会经过一个仅限收紧的过滤器；[限制父级设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)介绍了过滤器允许的内容以及 `allowManaged*Only` 锁定。设置了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的宿主会改为直接从此负载中读取三个键：在 Claude Code v2.1.222 或更高版本中读取其[模型配置](/docs/zh-CN/model-config#restrict-model-selection)；在 v2.1.246 或更高版本中，当没有托管源设置 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 时读取该键；在 v2.1.247 或更高版本中读取其 `ENABLE_TOOL_SEARCH` env 条目 |

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

1561 parent_tool_use_id: string | null;1561 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1562 error?: SDKAssistantMessageError;

1563 aborted?: true;1563 aborted?: true;

1564 agent_id?: string;

1564 timestamp?: string;1565 timestamp?: string;

1565 context_usage?: SDKContextUsage;1566 context_usage?: SDKContextUsage;

1566 user_message_uuid?: string;1567 user_message_uuid?: string;

1580 1581

1581当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。1582当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。

1582 1583

1584`agent_id` 标识生成该消息的子代理，主线程消息中不包含此字段。其值等于该子代理的 [`task_started`](#sdktaskstartedmessage) 及其他任务事件上的 `task_id`，并且在子代理被[恢复](/docs/zh-CN/agent-sdk/subagents#resume-subagents)时保持不变。该字段需要 Agent SDK v0.3.292 或更高版本。

1585

1586请通过 `agent_id` 将子代理的消息与其任务事件进行匹配，而不是将消息的 `parent_tool_use_id` 与任务事件的 `tool_use_id` 配对。当某个工具调用恢复子代理时，任务事件携带的是该调用的 `tool_use_id`，而消息保留的是最初启动该子代理的工具调用的 `parent_tool_use_id`，因此两者不再匹配。

1587

1583Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的助手消息也携带 [`resume_reason`](#resume_reason)。1588Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的助手消息也携带 [`resume_reason`](#resume_reason)。

1584 1589

1585`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。1590`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。

1597 type: "user";1602 type: "user";

1598 uuid?: UUID;1603 uuid?: UUID;

1599 session_id?: string;1604 session_id?: string;

1605 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1606 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1607 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1608 parent_tool_use_id: string | null;

1636};1642};

1637```1643```

1638 1644

1645由子代理生成的用户消息（例如其自身某个工具调用的 `tool_result`）会携带 `agent_id`。请参阅 [`SDKAssistantMessage`](#sdkassistantmessage)，其中定义了该字段及其版本要求。

1646

1639在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其结构取决于对应 `tool_use` 块所指定的工具，因此该字段的类型为 `unknown`；内置结构列在[工具输出类型](#tool-output-types)下。以下结果需要超出其所列结构的额外处理：1647在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其结构取决于对应 `tool_use` 块所指定的工具，因此该字段的类型为 `unknown`；内置结构列在[工具输出类型](#tool-output-types)下。以下结果需要超出其所列结构的额外处理：

1640 1648

1641* `Agent` 工具：`tool_use_result` 为 [`AgentOutput`](#agent-2)。请据此进行渲染，而不是解析 `tool_result` 文本。`completed` 结果的 `content` 包含子代理的报告；对于通过 `SubagentHandback` 工具调用提交报告的子代理，则包含一条关于该交接的简短说明来代替报告。在 Claude Code v2.1.271 或更高版本的[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下，每个产生 `completed` 结果的子代理都以这种方式报告（[fork](/docs/zh-CN/sub-agents#fork-the-current-conversation) 除外），Claude 会以来自子代理的单独消息接收报告。1649* `Agent` 工具：`tool_use_result` 为 [`AgentOutput`](#agent-2)。请据此进行渲染，而不是解析 `tool_result` 文本。`completed` 结果的 `content` 包含子代理的报告；对于通过 `SubagentHandback` 工具调用提交报告的子代理，则包含一条关于该交接的简短说明来代替报告。在 Claude Code v2.1.271 或更高版本的[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下，每个产生 `completed` 结果的子代理都以这种方式报告（[fork](/docs/zh-CN/sub-agents#fork-the-current-conversation) 除外），Claude 会以来自子代理的单独消息接收报告。

1992 `SDKPartialAssistantMessage`2000 `SDKPartialAssistantMessage`

1993</h3>2001</h3>

1994 2002

1995流式部分消息（仅当 `includePartialMessages` 为 true 时）。`parent_tool_use_id` 字段始终为 `null`：流事件仅为主会话发出。对于子代理归因，使用完整消息，它们携带 `parent_tool_use_id`，或启用 [`forwardSubagentText`](#options) 以接收子代理文本和思考作为完整消息。2003流式部分消息（仅当 `includePartialMessages` 为 true 时）。

2004

2005`parent_tool_use_id` 字段始终为 `null`：流事件仅针对主会话发出。要进行子代理归属，请使用完整消息（它们携带 [`agent_id`](#sdkassistantmessage) 和 `parent_tool_use_id`），或启用 [`forwardSubagentText`](#options) 以完整消息的形式接收子代理的文本和思考内容。

1996 2006

1997```typescript theme={null}2007```typescript theme={null}

1998type SDKPartialAssistantMessage = {2008type SDKPartialAssistantMessage = {

3416type WebFetchInput = {3426type WebFetchInput = {

3417 url: string;3427 url: string;

3418 prompt: string;3428 prompt: string;

3429 offset?: number;

3419};3430};

3420```3431```

3421 3432

3422从 URL 获取内容并使用 AI 模型处理它。3433从 URL 获取内容并使用 AI 模型处理它。

3423 3434

3435`offset` 是从页面开头跳过的字符数。Claude 设置它以继续读取较长的页面。该字段需要 Agent SDK v0.3.290 或更高版本。

3436

3424<h3 id="websearch">3437<h3 id="websearch">

3425 WebSearch3438 WebSearch

3426</h3>3439</h3>

5775 task_type?: string;5788 task_type?: string;

5776 is_backgrounded?: boolean;5789 is_backgrounded?: boolean;

5777 spawn_depth?: number;5790 spawn_depth?: number;

5791 parent_task_id?: string;

5778 ambient?: boolean;5792 ambient?: boolean;

5779 uuid: UUID;5793 uuid: UUID;

5780 session_id: string;5794 session_id: string;

5792 5806

5793[恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents)始终报告 `is_backgrounded: true`，因为 Claude Code 会在后台运行每个恢复的子代理。当前台任务稍后移到后台时，Claude Code 会在 [`task_updated`](#sdktaskupdatedmessage) 消息中报告新的 `is_backgrounded` 值，而不是发送第二条 `task_started`。5807[恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents)始终报告 `is_backgrounded: true`，因为 Claude Code 会在后台运行每个恢复的子代理。当前台任务稍后移到后台时，Claude Code 会在 [`task_updated`](#sdktaskupdatedmessage) 消息中报告新的 `is_backgrounded` 值，而不是发送第二条 `task_started`。

5794 5808

5809`parent_task_id` 保存启动此任务的子代理的 `task_id`。使用它将每个任务归组到启动它的子代理之下。Claude Code 会在子代理、Bash 和 [Monitor](#monitor) 任务上设置它。该字段需要 Agent SDK v0.3.292 或更高版本。在以下情况下该字段不存在：

5810

5811* 任务由主线程启动

5812* Claude Code 不再跟踪父任务

5813* 任务由 [teammate](/docs/zh-CN/agent-teams) 或工作流中的 Agent 启动

5814

5815父任务可能是前台任务，也可能是已经结束的任务，因此请将无法识别的 ID 视为没有父任务。

5816

5795<h3 id="sdktaskprogressmessage">5817<h3 id="sdktaskprogressmessage">

5796 `SDKTaskProgressMessage`5818 `SDKTaskProgressMessage`

5797</h3>5819</h3>

5848 `SDKBackgroundTasksChangedMessage`5870 `SDKBackgroundTasksChangedMessage`

5849</h3>5871</h3>

5850 5872

5851每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description` 或 `ambient` 字段发生变化。5873每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description`、`ambient` 或 `parent_task_id` 字段发生变化。有关每个条目上的 `parent_task_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。

5852 5874

5853`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。5875`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。

5854 5876

5855相对于这些逐任务事件的顺序是未指定的，因此不要将这两个流相互关联。5877当任务结束时，其 [`task_updated`](#sdktaskupdatedmessage) 和 [`task_notification`](#sdktasknotificationmessage) 会先于将其从列表中移除的 `background_tasks_changed` 到达。除此之外，相对于这些逐任务事件的顺序是未指定的。

5856 5878

5857启动时不会发出任何内容。每当会话的 CLI 进程启动或重启时，请重置为空集合，并由下一次成员变化重新填充。5879启动时不会发出任何内容。每当会话的 CLI 进程启动或重启时，请重置为空集合，并由下一次成员变化重新填充。

5858 5880

5869 task_type: string;5891 task_type: string;

5870 subagent_type?: string;5892 subagent_type?: string;

5871 description: string;5893 description: string;

5894 parent_task_id?: string;

5872 ambient?: boolean;5895 ambient?: boolean;

5873 }[];5896 }[];

5874 uuid: UUID;5897 uuid: UUID;

agent-sdk/user-input.md +10 −5

Details

36 ```36 ```

37 37

38 ```typescript TypeScript theme={null}38 ```typescript TypeScript theme={null}

~~39 async function handleToolRequest(toolName, input, options) {~~39 import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";

41 const handleToolRequest: CanUseTool = async (toolName, input, options) => {

40 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }42 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

~~41 // 提示用户并返回允许或拒绝~~43 // 在此提示用户，然后返回允许或拒绝

~~42 }~~44 return { behavior: "deny", message: "User declined" };

45 };

43 46

44 const options = { canUseTool: handleToolRequest };47 const options = { canUseTool: handleToolRequest };

45 ```48 ```

440 // 在您的工具列表中包含 AskUserQuestion443 // 在您的工具列表中包含 AskUserQuestion

441 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],444 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

442 canUseTool: async (toolName, input) => {445 canUseTool: async (toolName, input) => {

443 // 在此处处理澄清问题446 // 批准每次调用的占位实现。"检测 AskUserQuestion"步骤会替换它。

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

444 }448 }

445 }449 }

446 })) {450 })) {

763 767

764 ```typescript TypeScript theme={null}768 ```typescript TypeScript theme={null}

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

770 import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";

766 import * as readline from "readline/promises";771 import * as readline from "readline/promises";

767 772

768 // 帮助程序在终端中提示用户输入773 // 帮助程序在终端中提示用户输入

783 }788 }

784 789

785 // 显示 Claude 的问题并收集用户答案790 // 显示 Claude 的问题并收集用户答案

786 async function handleAskUserQuestion(input: any) {791 async function handleAskUserQuestion(input: any): Promise<PermissionResult> {

787 const answers: Record<string, string> = {};792 const answers: Record<string, string> = {};

788 793

789 for (const q of input.questions) {794 for (const q of input.questions) {

agent-view.md +1 −1

Details

603 603

604在 git 仓库外，会话直接写入工作目录，彼此之间不隔离，因此请避免分派会编辑相同文件的并行会话。如果您使用其他版本控制系统，请配置 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。604在 git 仓库外，会话直接写入工作目录，彼此之间不隔离，因此请避免分派会编辑相同文件的并行会话。如果您使用其他版本控制系统，请配置 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。

605 605

606当 hook 在非 git 仓库的目录中失败时，Claude 会跳过该目录的隔离，并就地编辑工作目录。在 git 仓库内，Claude 在编辑前会将其移入 worktree 的会话，在该移动完成之前无法编辑共享检出中的文件。606当 hook 在非 git 仓库的目录中失败时，Claude 会跳过该目录的隔离，并就地编辑工作目录。在 git 仓库内，Claude 在编辑前会将其移入 worktree 的会话，在该移动完成之前无法对共享检出使用 `Edit`、`Write` 或 `NotebookEdit` 工具。

607 607

608要查找会话的 worktree 路径，请附加到会话并查看其工作目录。608要查找会话的 worktree 路径，请附加到会话并查看其工作目录。

609 609

claude-apps-gateway-config.md +1 −1

Details

1237 1237

1238CLI 将指标、日志和（启用时）跟踪发送到网关，网关将它们逐字中继到每个配置的目的地。导出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳过中继并让会话直接导出到您的收集器，[在策略中命名收集器](#export-directly-to-your-collector)。请参阅[监控使用](/docs/zh-CN/monitoring-usage)了解 CLI 发出的指标和事件。1238CLI 将指标、日志和（启用时）跟踪发送到网关，网关将它们逐字中继到每个配置的目的地。导出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳过中继并让会话直接导出到您的收集器，[在策略中命名收集器](#export-directly-to-your-collector)。请参阅[监控使用](/docs/zh-CN/monitoring-usage)了解 CLI 发出的指标和事件。

1239 1239

1240在通过 `/login` 登录的会话中，CLI 使用从网关颁发的 JWT 读取的已认证用户的身份为每个导出加盖时间戳：`user.id`、`user.email` 和 `user.groups` 属性。每个开发者的成本和使用归因因此无需开发者端配置即可工作。1240在通过 `/login` 登录的会话中，CLI 使用从网关颁发的 JWT 读取的已认证用户的身份为每个导出加盖时间戳：`user.id`、`user.email` 和 `user.groups` 属性。每个开发者的成本和使用归因因此无需开发者端配置即可工作。Claude Code 在开发者登录之前记录的事件[不携带此身份](/docs/zh-CN/monitoring-usage#standard-attributes)。

1241 1241

1242[Claude Desktop](#claude-desktop-overlay) 和通过网关登录的 Cowork 会话使用 `user.email` 和 `user.groups` 以及 `enduser.id` 为其遥测加盖时间戳，因此您可以使用一个关于 `user.email` 或 `user.groups` 的查询覆盖终端、Desktop 和 Cowork 使用。`user.groups` 是逗号分隔的 IdP 组列表。1242[Claude Desktop](#claude-desktop-overlay) 和通过网关登录的 Cowork 会话使用 `user.email` 和 `user.groups` 以及 `enduser.id` 为其遥测加盖时间戳，因此您可以使用一个关于 `user.email` 或 `user.groups` 的查询覆盖终端、Desktop 和 Cowork 使用。`user.groups` 是逗号分隔的 IdP 组列表。

1243 1243

claude-apps-gateway-on-aws.md +1 −1

Details

516 遥测516 遥测

517</h2>517</h2>

518 518

519网关为您提供每个开发者的使用指标，无需任何每台机器的 OTEL 配置。Claude Code 发出 OpenTelemetry (OTLP) 指标、日志和可选的跟踪；[监控使用情况](/docs/zh-CN/monitoring-usage)涵盖了 CLI 报告的所有内容。在通过 `/login` 登录的会话中，CLI 使用经过身份验证的 IdP 身份属性 `user.id`、`user.email` 和 `user.groups` 为每个导出加盖时间戳，因此使用情况按开发者汇总。519网关为您提供每个开发者的使用指标，无需任何每台机器的 OTEL 配置。Claude Code 发出 OpenTelemetry (OTLP) 指标、日志和可选的跟踪；[监控使用情况](/docs/zh-CN/monitoring-usage)涵盖了 CLI 报告的所有内容。在通过 `/login` 登录的会话中，CLI 使用经过身份验证的 IdP 身份属性 `user.id`、`user.email` 和 `user.groups` [标记每个导出](/docs/zh-CN/monitoring-usage#standard-attributes)，因此使用情况按开发者汇总。

520 520

521网关本身是一个经过身份验证的 OTLP 中继。将 [`telemetry.forward_to`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 与 `listen.public_url` 一起设置，它会将 OTEL 导出器设置推送到每个连接的客户端，并将其 OTLP 流量逐字转发到您列出的每个目标。每个目标独立选择指标、日志和跟踪，默认仅为指标；有关每个信号字段及其敏感性权衡，请参阅 [`telemetry` 参考](/docs/zh-CN/claude-apps-gateway-config#telemetry)。网关不缓冲、聚合或存储遥测数据，因此数据最终的位置完全由收集器的导出器配置决定。521网关本身是一个经过身份验证的 OTLP 中继。将 [`telemetry.forward_to`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 与 `listen.public_url` 一起设置，它会将 OTEL 导出器设置推送到每个连接的客户端，并将其 OTLP 流量逐字转发到您列出的每个目标。每个目标独立选择指标、日志和跟踪，默认仅为指标；有关每个信号字段及其敏感性权衡，请参阅 [`telemetry` 参考](/docs/zh-CN/claude-apps-gateway-config#telemetry)。网关不缓冲、聚合或存储遥测数据，因此数据最终的位置完全由收集器的导出器配置决定。

522 522

claude-projects.md +1 −1

Details

489* **例程**：当您在项目中要求计划工作时，Claude 创建一个[例程](/docs/zh-CN/routines)，作为该项目中的线程运行，并出现在其 **Routines** 标签页上。您在项目外创建的例程继续自己工作。489* **例程**：当您在项目中要求计划工作时，Claude 创建一个[例程](/docs/zh-CN/routines)，作为该项目中的线程运行，并出现在其 **Routines** 标签页上。您在项目外创建的例程继续自己工作。

490* **Remote Control**：[Remote Control](/docs/zh-CN/remote-control) 连接 claude.ai 到在您的机器上运行的 Claude Code 会话。当您在项目中要求 Claude 在您的计算机上运行线程时，项目[使用 Remote Control 来执行](#run-a-thread-on-your-own-computer)。490* **Remote Control**：[Remote Control](/docs/zh-CN/remote-control) 连接 claude.ai 到在您的机器上运行的 Claude Code 会话。当您在项目中要求 Claude 在您的计算机上运行线程时，项目[使用 Remote Control 来执行](#run-a-thread-on-your-own-computer)。

491* **本地会话和代理视图**：您在终端、IDE 或桌面应用的本地环境中启动的会话不能添加到项目中。[代理视图](/docs/zh-CN/agent-view)是用于跟踪多个本地会话并排的屏幕，您仍然启动每个会话并自己给它分配任务。491* **本地会话和代理视图**：您在终端、IDE 或桌面应用的本地环境中启动的会话不能添加到项目中。[代理视图](/docs/zh-CN/agent-view)是用于跟踪多个本地会话并排的屏幕，您仍然启动每个会话并自己给它分配任务。

492* **Worktrees**：一个[worktree](/docs/zh-CN/worktrees)为每个本地会话提供其自己的代码库工作副本，因此您机器上的并行会话不会相互覆盖。云线程不需要它们：每个线程将其代码库克隆到其自己的云沙箱中，并在其自己的分支上工作。492* **Worktrees**：一个 [worktree](/docs/zh-CN/worktrees) 为每个本地会话提供其自己的仓库工作副本。云线程不需要它们：每个线程将其仓库克隆到其自己的云沙箱中，并在其自己的分支上工作。

493* **代理团队**：一个[代理团队](/docs/zh-CN/agent-teams)是一个会话，为单个任务启动队友会话，在您的机器上或在云会话内，并以该任务结束。493* **代理团队**：一个[代理团队](/docs/zh-CN/agent-teams)是一个会话，为单个任务启动队友会话，在您的机器上或在云会话内，并以该任务结束。

494* **Subagents**：一个[subagent](/docs/zh-CN/sub-agents)在一个会话内运行，在其自己的上下文窗口中执行一个辅助任务，并向该会话返回摘要。项目的线程是 Claude 启动的整个会话，向项目对话报告，一个线程仍然可以为其自己的辅助任务使用 subagents。494* **Subagents**：一个[subagent](/docs/zh-CN/sub-agents)在一个会话内运行，在其自己的上下文窗口中执行一个辅助任务，并向该会话返回摘要。项目的线程是 Claude 启动的整个会话，向项目对话报告，一个线程仍然可以为其自己的辅助任务使用 subagents。

495* **claude.ai 聊天和 Cowork 中的 Projects**：[早期的 Projects 体验](https://support.claude.com/en/articles/9517075-what-are-projects)，对对话和参考文件进行分组，没有线程或协调员。这些项目继续按照今天的方式工作，直到重新设计的体验到达它们。495* **claude.ai 聊天和 Cowork 中的 Projects**：[早期的 Projects 体验](https://support.claude.com/en/articles/9517075-what-are-projects)，对对话和参考文件进行分组，没有线程或协调员。这些项目继续按照今天的方式工作，直到重新设计的体验到达它们。

cli-reference.md +1 −1

Details

107| `--json-schema` | 在 Agent 完成其工作流后获得与 JSON Schema 匹配的经过验证的 JSON 输出（仅限 print 模式）。请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。Claude Code 在 schema 无效时以错误退出，并接受 `format` 关键字作为注释而不进行客户端验证 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |107| `--json-schema` | 在 Agent 完成其工作流后获得与 JSON Schema 匹配的经过验证的 JSON 输出（仅限 print 模式）。请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。Claude Code 在 schema 无效时以错误退出，并接受 `format` 关键字作为注释而不进行客户端验证 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

109| `--max-budget-usd` | 在停止之前在 API 调用上花费的最大美元金额（仅限 print 模式）。Claude Code 根据其[客户端成本估算](/docs/zh-CN/agent-sdk/cost-tracking#estimates-not-billing)检查上限，该估算可能与您的账单不同。来自[子代理](/docs/zh-CN/sub-agents)的支出计入上限。当您使用 `--continue` 或 `--resume` 返回对话时，[从早期运行恢复的](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)总数不计入上限。一旦支出达到上限，生成另一个子代理会失败并显示 `Budget limit reached`，Claude Code 会停止仍在运行的后台子代理；上限执行行为需要 Claude Code v2.1.217 或更高版本 | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | 一旦 API 调用的估算支出达到此金额，即停止运行（仅限 print 模式）。Claude Code 根据其[客户端成本估算](/docs/zh-CN/agent-sdk/cost-tracking#estimates-not-billing)检查上限，该估算可能与您的账单不同。来自[子代理](/docs/zh-CN/sub-agents)的支出计入上限。支出可能超过上限，因此请[预留余量](/docs/zh-CN/agent-sdk/agent-loop#budget-headroom)。当您使用 `--continue` 或 `--resume` 返回对话时，[从早期运行恢复的](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)总数不计入上限。一旦支出达到上限，生成另一个子代理会失败并显示 `Budget limit reached`，Claude Code 会停止仍在运行的后台子代理；上限执行行为需要 Claude Code v2.1.217 或更高版本 | `claude -p --max-budget-usd 5.00 "query"` |

110| `--max-turns` | 限制 Agent 轮次数（仅限 print 模式）。达到限制时以错误退出。默认无限制。使用 `--input-format stream-json` 时，当限制结束某一轮次时仍在排队的消息会保持排队，并以其自己的限制启动新轮次 | `claude -p --max-turns 3 "query"` |110| `--max-turns` | 限制 Agent 轮次数（仅限 print 模式）。达到限制时以错误退出。默认无限制。使用 `--input-format stream-json` 时，当限制结束某一轮次时仍在排队的消息会保持排队，并以其自己的限制启动新轮次 | `claude -p --max-turns 3 "query"` |

111| `--mcp-config` | 从 JSON 文件或字符串加载 MCP 服务器（空格分隔）。当您使用 `-p` 传递此标志时，Claude Code 在运行第一轮之前等待仍待处理的服务器连接，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时时间，默认 30 秒；具有[缓存工具列表](/docs/zh-CN/mcp#managing-your-servers)的服务器跳过等待并在首次使用时连接。等待需要 Claude Code v2.1.221 或更高版本 | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | 从 JSON 文件或字符串加载 MCP 服务器（空格分隔）。当您使用 `-p` 传递此标志时，Claude Code 在运行第一轮之前等待仍待处理的服务器连接，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时时间，默认 30 秒；具有[缓存工具列表](/docs/zh-CN/mcp#managing-your-servers)的服务器跳过等待并在首次使用时连接。等待需要 Claude Code v2.1.221 或更高版本 | `claude --mcp-config ./mcp.json` |

112| `--model` | 使用[模型别名](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称为当前会话设置模型。覆盖 [`model`](/docs/zh-CN/settings-reference#model) 设置和 [`ANTHROPIC_MODEL`](/docs/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |112| `--model` | 使用[模型别名](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称为当前会话设置模型。覆盖 [`model`](/docs/zh-CN/settings-reference#model) 设置和 [`ANTHROPIC_MODEL`](/docs/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |

cloud-environments.md +3 −3

Details

307| | 在云端会话中可用 | 原因 |307| | 在云端会话中可用 | 原因 |

308| :- | :- | :- |308| :- | :- | :- |

309| 您的仓库的 `CLAUDE.md` | 是 | 克隆的一部分 |309| 您的仓库的 `CLAUDE.md` | 是 | 克隆的一部分 |

312| 您的仓库的 `.claude/rules/` | 是 | 克隆的一部分 |312| 您的仓库的 `.claude/rules/` | 是 | 克隆的一部分 |

313| 您的仓库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |313| 您的仓库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |

314| 在您的仓库的 `.claude/settings.json` 中声明的插件和市场 | 否 | 云端会话不会安装仓库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的插件，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的市场的插件 |314| 在您的仓库的 `.claude/settings.json` 中声明的插件和市场 | 否 | 云端会话不会安装仓库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的插件，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的市场的插件 |

575 575

576SessionStart hooks 在云端的行为与本地相同，但有以下注意事项：576SessionStart hooks 在云端的行为与本地相同，但有以下注意事项：

577 577

578* **每个会话一个存储库**：具有多个存储库的会话不会从任何存储库的 `.claude/settings.json` 加载 hooks，因此您在那里定义的 SessionStart hook 不会运行。请改为使用[设置脚本](#setup-scripts)为这些会话安装依赖项。578* **每个会话一个仓库**：在 Anthropic 托管环境中，具有多个仓库的会话不会从任何仓库的 `.claude/settings.json` 加载 hook，因此您在那里定义的 SessionStart hook 不会运行。请改为使用[设置脚本](#setup-scripts)为这些会话安装依赖项。对于自托管环境，请参阅[适用哪个仓库的设置](/docs/zh-CN/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)。

579* **没有仅云端的范围**：hooks 在本地和云会话中都运行。要跳过本地运行，请在 `CLAUDE_CODE_REMOTE` 环境变量不为 `true` 时提前退出，就像[依赖项安装脚本](#install-dependencies-with-a-sessionstart-hook)所做的那样。579* **没有仅云端的范围**：hooks 在本地和云会话中都运行。要跳过本地运行，请在 `CLAUDE_CODE_REMOTE` 环境变量不为 `true` 时提前退出，就像[依赖项安装脚本](#install-dependencies-with-a-sessionstart-hook)所做的那样。

580* **需要网络访问**：安装命令需要连接到包注册表。如果您的环境使用 **None** 网络访问，这些 hooks 会失败。**Trusted** 下的[默认允许列表](#default-allowed-domains)涵盖 npm、PyPI、RubyGems 和 crates.io。580* **需要网络访问**：安装命令需要连接到包注册表。如果您的环境使用 **None** 网络访问，这些 hooks 会失败。**Trusted** 下的[默认允许列表](#default-allowed-domains)涵盖 npm、PyPI、RubyGems 和 crates.io。

581* **代理兼容性**：在 Anthropic 托管环境中，所有出站流量都经过[安全代理](#security-proxy)，某些包管理器无法与此代理正确配合工作；Bun 是一个已知的例子。在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量改为经过您自己的网络边界。581* **代理兼容性**：在 Anthropic 托管环境中，所有出站流量都经过[安全代理](#security-proxy)，某些包管理器无法与此代理正确配合工作；Bun 是一个已知的例子。在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量改为经过您自己的网络边界。

desktop.md +1 −1

Details

396 使用会话并行工作396 使用会话并行工作

397</h3>397</h3>

398 398

399点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N**、在 Windows 上按 **Ctrl+N**，即可并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 可在侧边栏中循环切换会话。对于 Git 仓库，选择分支名称旁边的 **worktree** 选项，即可使用 [Git worktrees](/docs/zh-CN/worktrees) 为会话提供项目的独立隔离副本，这样一个会话中的更改在您提交之前不会影响其他会话。399点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N**、在 Windows 上按 **Ctrl+N**，即可并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 可在侧边栏中循环切换会话。对于 Git 仓库，选择分支名称旁边的 **worktree** 选项，即可使用 [Git worktrees](/docs/zh-CN/worktrees) 为会话提供项目的独立隔离副本。

400 400

401要同时查看两个会话，请在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。该会话会在第二个窗格中打开，与您已打开的会话并排显示。分屏处于活跃状态时，点击侧边栏中的另一个会话会替换当前具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 可关闭具有焦点的窗格并返回单个会话。401要同时查看两个会话，请在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。该会话会在第二个窗格中打开，与您已打开的会话并排显示。分屏处于活跃状态时，点击侧边栏中的另一个会话会替换当前具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 可关闭具有焦点的窗格并返回单个会话。

402 402

env-vars.md +2 −1

Details

204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您参与即自动继续。自动继续默认关闭；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置为 `0` 不会关闭超时，而是会立即关闭对话框。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。在 v2.1.200 之前，自动继续默认启用，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您参与即自动继续。自动继续默认关闭；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置为 `0` 不会关闭超时，而是会立即关闭对话框。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。在 v2.1.200 之前，自动继续默认启用，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。适用于希望从空白状态开始的 SDK 用户。这还会移除 `general-purpose`，即 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此后此类调用会失败并报错 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。适用于希望从空白状态开始的 SDK 用户。这还会移除 `general-purpose`，即 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此后此类调用会失败并报错 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间，以毫秒为单位。默认值为 `600000`（10 分钟）；如果您在流式监视器启用时提高了 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，详见[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)。计时器会在每个流式进度事件时重置；如果在该时间窗口内没有进度到达，Claude Code 会中止该子代理并向父级报告停滞 |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间，以毫秒为单位。在 Claude Code v2.1.286 或更高版本上还涵盖[工作流 Agent](/docs/zh-CN/workflows#when-an-agent-stalls-and-restarts)。默认 `600000`（10 分钟）；如果您在流式监视器启用时调高了 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，如[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述 |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（如 `50`）可以更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前进行压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（如 `50`）可以更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前进行压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台化。启用后，子代理运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本中，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台化](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台化。启用后，子代理运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本中，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台化](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |

210| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值为 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |210| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值为 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |

378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，恢复时自动继续所允许的最后一条会话记录消息的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示无界限，但最后一个请求因 API 错误而失败的轮次仅在该错误发生不到六小时时才会恢复。正值会限制所有轮次，包括上述轮次；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此项，以免针对旧会话记录重启时重新运行过时的提示词。当 Claude Code 重启一个从交互式会话继承对话的已崩溃 [agent view](/docs/zh-CN/agent-view) 会话时，会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，恢复时自动继续所允许的最后一条会话记录消息的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示无界限，但最后一个请求因 API 错误而失败的轮次仅在该错误发生不到六小时时才会恢复。正值会限制所有轮次，包括上述轮次；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此项，以免针对旧会话记录重启时重新运行过时的提示词。当 Claude Code 重启一个从交互式会话继承对话的已崩溃 [agent view](/docs/zh-CN/agent-view) 会话时，会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |

379| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 发送给 Claude 的继续消息，适用于 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续被中断的轮次而不是重新发送其提示词时，或您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时。默认为 `Continue from where you left off.`。空字符串会使用默认值 |379| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 发送给 Claude 的继续消息，适用于 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续被中断的轮次而不是重新发送其提示词时，或您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时。默认为 `Continue from where you left off.`。空字符串会使用默认值 |

380| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于评估框架、CI 作业或远程工作器等无人值守会话，请设置为 `1`。会无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度耗尽的 `429` 时，Claude Code 会立即失败，即使它来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，watchdog 会无限期重试这些错误。对于快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。watchdog 在两次尝试之间最多退避 5 分钟，或者当响应包含速率限制重置时间时等到限制重置，因此遇到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本上，它还会将其他瞬态错误（例如服务器错误、超时和连接断开）的默认重试次数提高到 300，约合三小时的退避时间，并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时移除其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |380| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于评估框架、CI 作业或远程工作器等无人值守会话，请设置为 `1`。会无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度耗尽的 `429` 时，Claude Code 会立即失败，即使它来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，watchdog 会无限期重试这些错误。对于快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。watchdog 在两次尝试之间最多退避 5 分钟，或者当响应包含速率限制重置时间时等到限制重置，因此遇到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本上，它还会将其他瞬态错误（例如服务器错误、超时和连接断开）的默认重试次数提高到 300，约合三小时的退避时间，并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时移除其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |

381| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | 设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，每个 API 请求等待 `429` 和 `529` 错误消退所花费的最长时间（毫秒）。用完该时间后，下一个此类错误将结束该请求。请以纯数字给出正整数，例如 `1800000` 表示 30 分钟。未设置时，等待没有限制。需要 Claude Code v2.1.295 或更高版本 |

381| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可在安全模式下启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆均不会加载，用于对损坏的配置进行故障排除。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 和策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |382| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可在安全模式下启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆均不会加载，用于对损坏的配置进行故障排除。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 和策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |

382| `CLAUDE_CODE_SCRIPT_CAPS` | 当设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时，用于限制特定脚本在每个会话中可被调用次数的 JSON 对象。键是与命令文本匹配的子字符串；值是整数调用上限。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此 `./scripts/deploy.sh $(evil)` 之类的 shell 展开技巧仍会计入上限。不会检测通过 `xargs` 或 `find -exec` 进行的运行时扇出；这是一项纵深防御控制 |383| `CLAUDE_CODE_SCRIPT_CAPS` | 当设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时，用于限制特定脚本在每个会话中可被调用次数的 JSON 对象。键是与命令文本匹配的子字符串；值是整数调用上限。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此 `./scripts/deploy.sh $(evil)` 之类的 shell 展开技巧仍会计入上限。不会检测通过 `xargs` 或 `find -exec` 进行的运行时扇出；这是一项纵深防御控制 |

383| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受不超过 20 的任意正值，包括低于 1 的小数值（例如 `0.5`），以便在已放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每格发送一个滚轮事件且不进行放大，请设置为 `3` 以与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在那里使用自己的滚动处理 |384| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受不超过 20 的任意正值，包括低于 1 的小数值（例如 `0.5`），以便在已放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每格发送一个滚轮事件且不进行放大，请设置为 `3` 以与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在那里使用自己的滚动处理 |

errors.md +1 −1

Details

4064 Marketplace 已从不同的来源添加4064 Marketplace 已从不同的来源添加

4065</h3>4065</h3>

4066 4066

4067您通过[`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)确认添加了 marketplace，Claude Code 从该来源获取的目录将自己命名为与您已从不同来源添加的 marketplace 相同。Claude Code 保留现有的 marketplace 而不是替换它，插件未安装。4067您在会话中或从 shell 中，通过[安装命令上的`--marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)指定了一个新的市场来源。Claude Code 从该来源获取的目录与您已从不同来源添加的市场同名。Claude Code 保留现有的市场而不是替换它，插件未安装。

4068 4068

4069```text theme={null}4069```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

glossary.md +1 −1

Details

511 Worktree isolation511 Worktree isolation

512</h3>512</h3>

513 513

514一个隔离模式，在 `.claude/worktrees/` 下的单独 git worktree 中运行 Claude，使用 `-w` 标志或 subagent 配置中的 `isolation: worktree` 启用。更改保留在单独分支的单独目录中，因此并行代理不会覆盖彼此的文件。514一个隔离模式，在 `.claude/worktrees/` 下的单独 git worktree 中运行 Claude，使用 `-w` 标志或子代理配置中的 `isolation: worktree` 启用。更改保留在单独目录中的单独分支上，因此每个并行 Agent 都各自编辑自己的文件副本。

515 515

516了解更多：[使用 git worktrees 运行并行会话](/docs/zh-CN/worktrees)516了解更多：[使用 git worktrees 运行并行会话](/docs/zh-CN/worktrees)

517 517

hooks.md +19 −8

Details

1237 SessionStart 决策控制1237 SessionStart 决策控制

1238</h4>1238</h4>

1239 1239

1240Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，您还可以返回以下事件专属字段：1240SessionStart hook 可以为 Claude 添加上下文、提供第一条用户消息、设置会话标题、监视文件以及重新加载 skill。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，为每项功能返回相应字段：

1241 1241

1242| 字段 | 描述 |1242| 字段 | 描述 |

1243| :- | :- |1243| :- | :- |

1244| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。关于文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |1244| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。关于文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |

1245| `initialUserMessage` | 用作会话第一条用户消息的字符串。适用于使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)，此时即使未提供提示词，它也会成为第一个轮次。如果提供了提示词，该提示词将作为下一个轮次跟随其后。与附加到现有轮次的 `additionalContext` 不同，此字段会创建轮次 |1245| `initialUserMessage` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)下，用作会话第一条用户消息的字符串。即使您未传入提示词，它也会成为第一轮。您传入的提示词会作为下一轮紧随其后 |

1246| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。可用于根据启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效；在 `"clear"` 和 `"compact"` 时被忽略 |1246| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。在 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效 |

1248| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，使 hook 安装的 skill 在同一会话中（从第一个提示词开始）即可使用 |1248| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录。请参阅[重新加载 hook 安装的 skill](#reload-skills-that-a-hook-installs) |

1249

1250以下输出添加上下文并为会话命名：

1249 1251

1250```json theme={null}1252```json theme={null}

1251{1253{

1257}1259}

1258```1260```

1259 1261

1260由于对于此事件，纯 stdout 已经会传达给 Claude，因此仅加载上下文的 hook 可以直接打印到 stdout，而无需构建 JSON。当您需要将上下文与 `sessionTitle` 等其他字段结合使用时，请使用 JSON 形式。1262仅添加上下文的 hook 可以直接打印内容而无需构建 JSON，因为 Claude Code 会将 SessionStart hook 的[纯文本 stdout](#exit-code-0) 添加到 Claude 的上下文中。

1263

1264如果您的插件的 SessionStart hook 提供 `initialUserMessage` 或 `sessionTitle`，请在会话开始前安装该插件。对于在 SessionStart hook 运行之后才完成安装的插件，Claude Code 会忽略这两个字段。

1265

1266<h4 id="reload-skills-that-a-hook-installs">

1267 重新加载 hook 安装的 skill

1268</h4>

1269

1270要使 SessionStart hook 安装的 skill 在同一会话中可用，请返回 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此如果不这样做，hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件在第一个提示词运行时可能缺失。

1261 1271

1262当 SessionStart hook 安装或更新 skill 时，请使用 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件否则只会在下一个会话中出现。此示例同步一个共享的 skill 仓库并请求重新扫描：1272此示例同步共享的 skill 仓库并请求重新扫描：

1263 1273

1264```bash theme={null}1274```bash theme={null}

1265#!/bin/bash1275#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1280echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1281```

1272 1282

1273仓库 URL 只是一个占位符；请将其替换为您自己的 skill 仓库。使用占位符时，clone 会失败并向 stderr 打印一条 `fatal:` 消息。以 0 退出的 SessionStart hook 的 stderr 仅供参考，因此 `reloadSkills` 请求仍然有效。1283仓库 URL 是占位符。请将其替换为您自己的 skill 仓库。

1274 1284

1275<h4 id="persist-environment-variables">1285<h4 id="persist-environment-variables">

1276 持久化环境变量1286 持久化环境变量

1860| :- | :- | :- | :- |1870| :- | :- | :- | :- |

1863 1874

1864<h5 id="websearch">1875<h5 id="websearch">

1865 WebSearch1876 WebSearch

4278异步 hooks 与同步 hooks 相比有额外的约束：4289异步 hooks 与同步 hooks 相比有额外的约束：

4279 4290

4280* Hook 输出在下一个对话轮次传递。如果会话空闲，响应等待直到下一个用户交互。例外：退出代码为 2 的 `asyncRewake` hook 即使在会话空闲时也会立即唤醒 Claude。4291* Hook 输出在下一个对话轮次传递。如果会话空闲，响应等待直到下一个用户交互。例外：退出代码为 2 的 `asyncRewake` hook 即使在会话空闲时也会立即唤醒 Claude。

4281* 每次执行创建一个单独的后台进程。同一异步 hook 的多个触发之间没有去重。4292* 每次执行创建一个单独的后台进程。

4282 4293

4283<h2 id="security-considerations">4294<h2 id="security-considerations">

4284 安全考虑4295 安全考虑

monitoring-usage.md +4 −0

Details

599 599

600在通过 `/login` 登录到[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)的会话中，CLI 会使用已认证身份标记导出：`user.id` 是 IdP 主体，`user.email` 是已登录的电子邮件，`user.groups` 以逗号分隔的字符串形式携带 IdP 组成员身份。每个导出还携带 `identity.source: gateway-oidc`。网关身份最后应用，因此通过 `OTEL_RESOURCE_ATTRIBUTES` 设置的 `user.*` 和 `identity.*` 键在这些会话上被忽略。600在通过 `/login` 登录到[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)的会话中，CLI 会使用已认证身份标记导出：`user.id` 是 IdP 主体，`user.email` 是已登录的电子邮件，`user.groups` 以逗号分隔的字符串形式携带 IdP 组成员身份。每个导出还携带 `identity.source: gateway-oidc`。网关身份最后应用，因此通过 `OTEL_RESOURCE_ATTRIBUTES` 设置的 `user.*` 和 `identity.*` 键在这些会话上被忽略。

601 601

602<Note>

603 Claude Code 在开发者登录之前记录的事件不携带网关身份。当 Claude Code 以未登录网关的状态打开会话时（例如在[网关结束登录](/docs/zh-CN/errors#cloud-gateway-session-expired)之后），登录前记录的启动事件会携带匿名 `user.id`，且不含 `identity.source`。这些事件包括 [`managed_settings_resolved`](#managed-settings-resolved-event)、[`plugin_loaded`](#plugin-loaded-event) 和 [`mcp_server_connection`](#mcp-server-connection-event)。

604</Note>

605

602对于通过网关连接的 Claude Desktop 和 Cowork 会话上的身份属性，请参阅[网关 `telemetry` 参考](/docs/zh-CN/claude-apps-gateway-config#telemetry)。606对于通过网关连接的 Claude Desktop 和 Cowork 会话上的身份属性，请参阅[网关 `telemetry` 参考](/docs/zh-CN/claude-apps-gateway-config#telemetry)。

603 607

604事件另外包括以下属性。这些永远不会附加到指标，因为它们会导致无限的基数：608事件另外包括以下属性。这些永远不会附加到指标，因为它们会导致无限的基数：

plugins/cli-reference.md +1 −0

Details

91| `-y, --yes` | 接受显示的安装命令，不出现 `Run this command now?` 提示。在 Claude Code 会话内运行命令时（例如从 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |91| `-y, --yes` | 接受显示的安装命令，不出现 `Run this command now?` 提示。在 Claude Code 会话内运行命令时（例如从 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |

92| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的显示安装命令。不能与 `-y` 组合使用。请参阅[接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |92| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的显示安装命令。不能与 `-y` 组合使用。请参阅[接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |

93| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |93| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |

94| `--marketplace <source>` | 从位于 `<source>` 的市场安装以裸名称指定的 `<plugin>`，如果您尚未添加该市场，则先添加它。请参阅[通过一条命令添加市场并安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.292 或更高版本 |

94 95

95在 shell 中运行 `claude plugin install --help`，可查看您的版本支持的所有选项。96在 shell 中运行 `claude plugin install --help`，可查看您的版本支持的所有选项。

96 97

plugins/install.md +20 −4

Details

189 189

190* **Scope**：默认为用户范围。传递 `--scope project` 或 `--scope local` 以更改它。190* **Scope**：默认为用户范围。传递 `--scope project` 或 `--scope local` 以更改它。

191* **When the plugins load**：它安装的插件在您下次启动 Claude Code 时加载，或当您在已打开的会话中运行 `/reload-plugins` 时加载。191* **When the plugins load**：它安装的插件在您下次启动 Claude Code 时加载，或当您在已打开的会话中运行 `/reload-plugins` 时加载。

192* **The marketplace must be added first**：在没有人打开交互式 Claude Code 会话的机器上，官方市场未注册，因此从它安装的脚本在安装前运行 `claude plugin marketplace add anthropics/claude-plugins-official`。192* **The marketplace on a new machine**：在还没有人打开过交互式 Claude Code 会话的机器上，官方市场未注册，因此从它安装的脚本在安装前运行 `claude plugin marketplace add anthropics/claude-plugins-official`。请参阅[从 shell 添加和安装](#add-and-install-from-your-shell)。

193 193

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 Add a marketplace and install in one command232 Add a marketplace and install in one command

233</h3>233</h3>

234 234

235要从您尚未添加的市场安装插件，请在 Claude Code 会话中运行 `/plugin install` 并使用 `--marketplace` 命名市场来源。需要 Claude Code v2.1.275 或更高版本。235要从您尚未添加的市场安装插件，请在安装命令中使用 `--marketplace` 命名市场来源，可以在会话中或从 shell 中执行。来源采用 [the same forms as `/plugin marketplace add`](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本地路径。单独给出插件名称，不带 `@marketplace` 后缀。

236

237<h4 id="add-and-install-in-a-session">

238 Add and install in a session

239</h4>

240

241在 Claude Code 会话中运行 `/plugin install`，并指定插件和来源。需要 Claude Code v2.1.275 或更高版本。在会话中，来源不能包含空格。

236 242

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246

241来源采用 [the same forms as `/plugin marketplace add`](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本地路径，除了它不能包含空格。单独给出插件名称，不带 `@marketplace` 后缀。

~~242~~

243如果您尚未添加该市场，Claude Code 显示它解析的来源并要求您在添加前确认。一旦添加了市场，插件的详细信息打开，您选择 [installation scope](#install-a-plugin)。如果来源与您已添加的市场匹配，Claude Code 跳过确认并在该市场中打开插件的详细信息。247如果您尚未添加该市场，Claude Code 显示它解析的来源并要求您在添加前确认。一旦添加了市场，插件的详细信息打开，您选择 [installation scope](#install-a-plugin)。如果来源与您已添加的市场匹配，Claude Code 跳过确认并在该市场中打开插件的详细信息。

244 248

249<h4 id="add-and-install-from-your-shell">

250 Add and install from your shell

251</h4>

252

253在 shell 中，无需启动会话，运行 `claude plugin install` 并指定插件和来源。需要 Claude Code v2.1.292 或更高版本。

254

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258

259shell 命令添加市场时没有确认步骤。您已从该来源添加的市场会被重用。新市场会经过与 `claude plugin marketplace add` 相同的 [organization policy checks](/docs/zh-CN/plugins/org#restrict-what-users-can-install) 后添加，并且即使您传递 `--scope project`，也会在您的用户设置中声明。

260

245<h3 id="add-a-private-marketplace">261<h3 id="add-a-private-marketplace">

246 Add a private marketplace262 Add a private marketplace

247</h3>263</h3>

plugins/mods/admin.md +1 −1

Details

142 142

143在 `hooks:` 行中，[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。143在 `hooks:` 行中，[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。

144 144

plugins/mods/api.md +10 −2

Details

140| 调用 | 用户看到的内容 |140| 调用 | 用户看到的内容 |

141| :- | :- |141| :- | :- |

145 145

146<h3 id="start-a-turn-from-a-background-job">146<h3 id="start-a-turn-from-a-background-job">

159 在会话之间发送和接收消息159 在会话之间发送和接收消息

160</h2>160</h2>

161 161

162mod 可以向您的另一个会话或此会话的子代理之一发送纯文本消息，并观察到达和离开的消息。`$.session.send({ to, text })` 发送一个，与 SendMessage 工具进行相同的传递。`to` 是 `{ sessionId }` 用于会话，`{ agentId }` 用于来自 `$.agent.list()` 的子代理，或接收消息来自的字符串地址。调用在消息排队后解析，带有 `{ isDelivered: true }`。当没有传递任何内容时，它使用 `{ isDelivered: false, reason }` 解析，`reason` 说明原因。162mod 可以向您的另一个会话、此会话的子代理之一或其 [agent team](/docs/zh-CN/agent-teams) 中的队友发送纯文本消息，还可以观察到达和离开的消息。

163

164要发送消息，请调用 `$.session.send({ to, text })`，它与 SendMessage 工具进行相同的传递。根据消息的接收者设置 `to`：

165

166* **您的另一个会话**：`{ sessionId }`

167* **子代理或队友**：`{ agentId }`，使用来自 `$.agent.list()` 的 id

168* **您收到的某条消息的发送者**：该消息来源的字符串地址

169

170调用在消息排队后解析，带有 `{ isDelivered: true }`。当没有传递任何内容时，它使用 `{ isDelivered: false, reason }` 解析，`reason` 说明原因。

163 171

164此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 `/ping` 命令（[注册为命令](#add-a-command)）：172此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 `/ping` 命令（[注册为命令](#add-a-command)）：

165 173

plugins/mods/events.md +2 −0

Details

281 281

282`result.usage` 保存 Claude API 为某个请求报告的 token 计数，以及作出回答的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。该 hook 也会针对子代理的请求运行，因此如果您只想处理主对话，请检查 `e.agentId`。282`result.usage` 保存 Claude API 为某个请求报告的 token 计数，以及作出回答的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。该 hook 也会针对子代理的请求运行，因此如果您只想处理主对话，请检查 `e.agentId`。

283 283

284要查看 API 在请求期间自行运行的工具调用（例如对 [advisor 工具](/docs/zh-CN/advisor)的调用），请读取 `result.serverToolUses`。Claude Code 不会运行这些调用，因此不会为它们触发任何 `tool.call` 或 `tool.check` hook。当响应中没有此类调用时，该字段不存在；该字段需要 Claude Code v2.1.290 或更高版本。

285

284<h3 id="hook-the-settings-hook-events">286<h3 id="hook-the-settings-hook-events">

285 处理设置 hook 事件287 处理设置 hook 事件

286</h3>288</h3>

plugins/mods/interface.md +11 −3

Details

10 10

11此地图显示 mod 可以在终端会话中的绘制位置：11此地图显示 mod 可以在终端会话中的绘制位置：

12 12

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在会话记录的右上角添加 toast，在会话记录中添加日志行，在输入框上方添加条带，以及在输入框下方添加状态栏。mod 可以重绘消息、工具调用行和加载指示器。输入框是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map.svg" />13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="全屏渲染模式下 Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在会话记录的右上角添加 toast，在会话记录中添加日志行，在输入框上方添加条带，以及在输入框下方添加状态栏。mod 可以重绘消息、工具调用行和加载指示器。输入框是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map.svg" />

14 14

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在会话记录的右上角添加 toast，在会话记录中添加日志行，在输入框上方添加条带，以及在输入框下方添加状态栏。mod 可以重绘消息、工具调用行和加载指示器。输入框是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map-dark.svg" />15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="全屏渲染模式下 Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在会话记录的右上角添加 toast，在会话记录中添加日志行，在输入框上方添加条带，以及在输入框下方添加状态栏。mod 可以重绘消息、工具调用行和加载指示器。输入框是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 16

17在较窄的终端中，窗格位于输入框上方而不是会话记录旁边。17在较窄的终端中，窗格位于输入框上方而不是会话记录旁边。

18 18

330 330

337 337

338要让命令在 Claude 工作时打开窗格，请在[注册命令](/docs/zh-CN/plugins/mods/api#add-a-command)时添加 `immediate: true`。如果不添加，在轮次进行期间输入的命令会等待轮次结束。338要让命令在 Claude 工作时打开窗格，请在[注册命令](/docs/zh-CN/plugins/mods/api#add-a-command)时添加 `immediate: true`。如果不添加，在轮次进行期间输入的命令会等待轮次结束。

339 339

340<h4 id="hold-toasts-behind-a-dialog">

341 在对话框后暂缓显示 toast

342</h4>

343

344当窗格是用户作答后即离开的对话框时，请向 `$.ui.open` 传递 `holdToasts: true`，这样在用户做决定时不会出现 toast。在终端中，只要该窗格是正在显示的窗格，暂缓就会持续，在此期间触发的 toast 会等到暂缓结束后再显示。

345

346除了您的 mod 通过 [`$.ui.toast`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn) 触发的 toast 外，Claude Code 还会暂缓其他 mod 的 toast 以及它自己的短时通知。对于保持打开的窗格，请不要设置该字段，以便用户能继续看到这些通知。

347

340<h4 id="when-a-pane-waits-for-a-wider-terminal">348<h4 id="when-a-pane-waits-for-a-wider-terminal">

341 当窗格等待更宽的终端时349 当窗格等待更宽的终端时

342</h4>350</h4>

plugins/mods/reference.md +2 −1

Details

209| [`$.ui`](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |209| [`$.ui`](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |

212| `$.agent` | `register`、`spawn`、`list` |212| `$.agent` | `register`、`spawn`、`list`。`list()` 返回此会话的子代理和队友，每项都带有 `status`，其值为 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed` 之一，其中 `idle` 和 `waiting` 需要 Claude Code v2.1.289 或更高版本。 |

214| [`$.prompt`](/docs/zh-CN/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 读取来自 `submit({ text })` 的文本时，前面会有一句指明您的 mod 为发送者的话。`submit({ text, asUser: true })` 将文本作为用户自己的话发送，不带那句话。 |214| [`$.prompt`](/docs/zh-CN/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 读取来自 `submit({ text })` 的文本时，前面会有一句指明您的 mod 为发送者的话。`submit({ text, asUser: true })` 将文本作为用户自己的话发送，不带那句话。 |

320| hook 的 `drop` 原因或 `config.set` 的 `deny` 原因 | 4,096 个字符。更长的原因会被截去末尾部分，drop 或 deny 仍然生效。截断需要 Claude Code v2.1.292 或更高版本；在更早的版本中，该 hook 会改为[失败](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。 |

320| 单个树中的文本 | 仅绘制前 100,000 个字符 |321| 单个树中的文本 | 仅绘制前 100,000 个字符 |

321| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |322| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |

plugins/mods/test.md +7 −2

Details

110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值，这会导致测试失败110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值，这会导致测试失败

111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它

112 112

113工具包还导出内存中的 mocks，为您回答整个命名空间。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 从以这些条目开始的存储中回答 `$.store`，`mock.env(on, { CI: 'true' })` 从这些变量中回答 `$.env.get`。`mock.clock` 返回一个您的测试可以推进的 mock 时钟，因此计时器的测试不会等待。`mock.store` 返回 nothing，因此要检查您的 mod 保存了什么，请自己编写两个 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那样。113工具包还导出现成的 mocks，用于时钟、存储、环境变量以及追加到对话中的行：

114

115* **`mock.clock(on)`**：回答 [`$.clock`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background)，并返回一个您的测试可以推进的 mock 时钟，因此计时器的测试不会等待。

116* **`mock.store(on, { count: 7 })`**：从以这些条目开始的存储中回答 `$.store`。它不返回任何内容，因此要检查您的 mod 保存了什么，请自己编写两个 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那样。

117* **`mock.env(on, { CI: 'true' })`**：从这些变量中回答 `$.env.get`。

118* **`mock.session(on)`**：返回一个 mock 会话，其 `appended()` 方法按从旧到新的顺序列出您的 mod 通过 [`$.session.append`](/docs/zh-CN/plugins/mods/reference#session) 添加的行；需要 Claude Code v2.1.293 或更高版本。

114 119

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 遵循测试工具包的规则121 遵循测试工具包的规则

168 查看 stub 返回的内容173 查看 stub 返回的内容

169</h3>174</h3>

170 175

171您的 mod 在测试中进行的每个 mods API 调用都需要一个 stub 来回答，除了工具包自己回答的少数几个：[`$.ui.invalidate`](/docs/zh-CN/plugins/mods/interface#redraw-when-something-changes) 和 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 调用。对于 `$.clock` 调用，使用 `mock.clock(on)`，否则您的 mod 的 `$.clock.now()` 会失败并显示 `no implementation for clock.now`。176您的 mod 在测试中进行的每个 mods API 调用都需要一个 stub 来回答，除了工具包自己回答的少数几个：[`$.ui.invalidate`](/docs/zh-CN/plugins/mods/interface#redraw-when-something-changes)、[`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 和 `$.session.append` 调用。对于 `$.clock` 调用，使用 `mock.clock(on)`，否则您的 mod 的 `$.clock.now()` 会失败并显示 `no implementation for clock.now`。

172 177

173此表列出了 mods 最常使用的。第一列是您的 mod 进行的调用或它使用 `next(e)` 传递的事件。第二列是传递给 `on` 的函数，使用该名称，因此 `$.store.get` 行变成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 标记您需要填写的文本：178此表列出了 mods 最常使用的。第一列是您的 mod 进行的调用或它使用 `next(e)` 传递的事件。第二列是传递给 `on` 的函数，使用该名称，因此 `$.store.get` 行变成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 标记您需要填写的文本：

174 179

plugins/mods/troubleshoot.md +15 −1

Details

209 绘图不出现或不响应209 绘图不出现或不响应

210</h2>210</h2>

211 211

212mod 已加载，其窗格、带或控件的行为不符合您的预期。212mod 已加载，其窗格、带、toast 或控件的行为不符合您的预期。

213 213

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 窗格或带为空或显示 Claude Code 的常规内容215 窗格或带为空或显示 Claude Code 的常规内容

247 247

248从命令或按钮打开窗格，或检查调用的 `isPlaced` 结果。请参阅 [在正确的时间打开窗格](/docs/zh-CN/plugins/mods/interface#open-a-pane-at-the-right-time)。248从命令或按钮打开窗格，或检查调用的 `isPlaced` 结果。请参阅 [在正确的时间打开窗格](/docs/zh-CN/plugins/mods/interface#open-a-pane-at-the-right-time)。

249 249

250<h3 id="a-toast-doesn’t-appear">

251 toast 不出现

252</h3>

253

254您的 mod 在交互式终端会话中调用了 [`$.ui.toast`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，但您没有看到该 toast。要确认调用已运行，请在[调试日志](#read-the-debug-log)中查找包含您的 mod 名称和 toast 文本的行，如 `$.ui.toast (first-mod): build finished`。然后检查以下原因：

255

256* **缺少该调用对应的行**：查找说明 Claude Code 拒绝该调用原因的行，如 `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`。

257* **某个窗格正在暂缓 toast**：您的 mod 或其他 mod 在打开当前显示的窗格时传递了 [`holdToasts`](/docs/zh-CN/plugins/mods/interface#hold-toasts-behind-a-dialog)。关闭该窗格即可结束暂缓。如果该窗格是您的且需要保持打开，请从其 `$.ui.open` 调用中移除 `holdToasts`，然后重新打开该窗格。

258* **toast 位于输入框下方**：在[经典渲染器](/docs/zh-CN/fullscreen#enable-fullscreen-rendering)中，请查看输入框下方的右侧。该处的 toast 是以 mod 名称开头的一行文字，而不是右上角的方框。

259* **您的 mod 发出了更新的 toast**：在经典渲染器中，来自您的 mod 的更新 toast 可能会取代正在显示或等待显示的 toast。调试日志中会有针对较早 toast 的另一行：如果该 toast 当时正在显示，该行以 `gave way, cut short` 结尾；如果它从未出现，则以 `gave way, unseen` 结尾。要同时显示两条消息，请将它们放在一个 toast 中。

260* **toast 在绘制前超时**：在全屏渲染中，Claude Code 一次最多绘制三个 toast，因此 toast 可能在绘制之前就已超时。调试日志中会有针对该 toast 的另一行，以 `left the stack, never drawn` 结尾。当您的 mod 同时发出多个 toast 时，请将这些消息放在一个 toast 中。

261

262在 v2.1.290 之前，如果某个 toast 是在 Claude Code 为您的 mod 显示上一个 toast 后两秒内发出的，Claude Code 会丢弃该 toast，且调试日志中针对被丢弃 toast 的行会显示 `within 2000ms of the last; dropped`。

263

250<h3 id="hotkeys-do-nothing">264<h3 id="hotkeys-do-nothing">

251 热键不起作用265 热键不起作用

252</h3>266</h3>

plugins/publish.md +1 −0

Details

129* 添加市场一次：`claude plugin marketplace add your-org/your-marketplace`，其中参数是 GitHub `owner/repo` 简写、URL 或路径129* 添加市场一次：`claude plugin marketplace add your-org/your-marketplace`，其中参数是 GitHub `owner/repo` 简写、URL 或路径

130* 安装插件：`claude plugin install deploy-helper@your-marketplace`130* 安装插件：`claude plugin install deploy-helper@your-marketplace`

131* 或从会话内同时执行两者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更高版本。请参阅[在一个命令中添加市场和安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)131* 或从会话内同时执行两者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更高版本。请参阅[在一个命令中添加市场和安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)

132* 或在 shell 中用一个命令同时执行两者：`claude plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.292 或更高版本

132 133

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 向用户发布更新135 向用户发布更新

plugins/troubleshooting.md +2 −2

Details

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165

166您运行了 `/plugin marketplace add <source>` 或 `claude plugin marketplace add <source>`，Claude Code 回复 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。166您运行了 `/plugin marketplace add <source>`、`claude plugin marketplace add <source>` 或 `claude plugin install <plugin> --marketplace <source>`，Claude Code 回复 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。

167 167

168Claude Code 接受以下形式之一的源：168Claude Code 接受以下形式之一的源：

169 169

568 `Marketplace "<name>" is already added from a different source`568 `Marketplace "<name>" is already added from a different source`

569</h3>569</h3>

570 570

571您通过 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command) 确认添加市场，Claude Code 从该源获取的目录与您已从不同源添加的市场具有相同的名称。Claude Code 保留现有市场而不是替换它，插件未安装。571您在会话中或从 shell 中，通过 [安装命令上的 `--marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command) 指定了一个新的市场源。Claude Code 从该源获取的目录与您已从不同源添加的市场具有相同的名称。Claude Code 保留现有市场而不是替换它，插件未安装。

572 572

573完整消息如下所示：573完整消息如下所示：

574 574

self-hosted-environments-configuration.md +16 −3

Details

403 403

404* 位于标准系统路径的企业作用域[托管 MCP 文件](/docs/zh-CN/managed-mcp)：Linux 运行器主机上为 `/etc/claude-code/managed-mcp.json`，macOS 主机上为 `/Library/Application Support/ClaudeCode/managed-mcp.json`。适用于只允许加载管理员列出的服务器的锁定机群。有关优先级规则，请参阅[使用 managed-mcp.json 进行独占控制](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json)。当运行器主机上存在此文件时，Claude Code 会跳过 Anthropic 控制平面下发给会话的 MCP 服务器（包括 claude.ai 连接器），并在会话子进程的 stderr 上以警告形式列出它们的名称，运行器会以 `debug` 日志级别记录这些警告。在 v2.1.229 之前，这些会话会在启动时退出并显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。404* 位于标准系统路径的企业作用域[托管 MCP 文件](/docs/zh-CN/managed-mcp)：Linux 运行器主机上为 `/etc/claude-code/managed-mcp.json`，macOS 主机上为 `/Library/Application Support/ClaudeCode/managed-mcp.json`。适用于只允许加载管理员列出的服务器的锁定机群。有关优先级规则，请参阅[使用 managed-mcp.json 进行独占控制](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json)。当运行器主机上存在此文件时，Claude Code 会跳过 Anthropic 控制平面下发给会话的 MCP 服务器（包括 claude.ai 连接器），并在会话子进程的 stderr 上以警告形式列出它们的名称，运行器会以 `debug` 日志级别记录这些警告。在 v2.1.229 之前，这些会话会在启动时退出并显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。

405* 运行器主机上[托管设置](/docs/zh-CN/managed-settings)中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 键：提供 HTTP 和 SSE 服务器，但不进行独占控制，因此来自其他来源的服务器仍会加载。需要 Claude Code v2.1.259 或更高版本。405* 运行器主机上[托管设置](/docs/zh-CN/managed-settings)中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 键：提供 HTTP 和 SSE 服务器，但不进行独占控制，因此来自其他来源的服务器仍会加载。需要 Claude Code v2.1.259 或更高版本。

406* `<repo>/.mcp.json`：项目作用域。将该文件提交到仓库；其中的服务器在云端会话中会被自动批准。406* `<repo>/.mcp.json`：项目作用域。将该文件提交到仓库；其中的服务器在云端会话中会被自动批准。在包含多个仓库的会话中，[最多只会加载一个仓库的该文件](#repository-settings-in-sessions-with-several-repositories)。

407 407

408当您的组织启用了连接器下发时，Anthropic 的控制平面会通过服务器提供的 MCP 配置，将您在 claude.ai 上配置的连接器下发到以交互方式创建的会话，请求经由 `api.anthropic.com` 路由。以编程方式创建的会话（例如 [CLI 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)）不会接收连接器下发；请改为通过本节列出的任何其他来源为它们提供 MCP 服务器。子进程的 OAuth 令牌不带有直接获取连接器的作用域，因此子进程本身不会尝试获取；下发由服务器驱动。408当您的组织启用了连接器下发时，Anthropic 的控制平面会通过服务器提供的 MCP 配置，将您在 claude.ai 上配置的连接器下发到以交互方式创建的会话，请求经由 `api.anthropic.com` 路由。以编程方式创建的会话（例如 [CLI 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)）不会接收连接器下发；请改为通过本节列出的任何其他来源为它们提供 MCP 服务器。子进程的 OAuth 令牌不带有直接获取连接器的作用域，因此子进程本身不会尝试获取；下发由服务器驱动。

409 409

542exit 0542exit 0

543```543```

544 544

545钩子在会话结束前提示 Claude 提交并推送，当目录不是 git 存储库或没有远程时保持沉默。545该 hook 在会话结束前提示 Claude 提交并推送，当目录不是 git 仓库或没有远程时保持沉默。对于包含多个仓库的会话，请参阅 [`$CLAUDE_PROJECT_DIR` 指向的内容](#repository-settings-in-sessions-with-several-repositories)。

546 546

547<h2 id="permissions-and-tool-approval">547<h2 id="permissions-and-tool-approval">

548 权限和工具批准548 权限和工具批准

571 571

572设置 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 可从其他路径获取初始内容，或将其指向空目录以禁用初始内容填充。572设置 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 可从其他路径获取初始内容，或将其指向空目录以禁用初始内容填充。

573 573

574仓库中提交的 `.claude/settings.json` 会作为项目设置叠加在其上。会话还会从运行器镜像中的标准系统路径读取 [`managed-settings.json`](/docs/zh-CN/settings#where-settings-live)。其中的键是否与[服务器托管设置](/docs/zh-CN/server-managed-settings)一起应用，取决于 [Claude Code 如何合并托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)：默认情况下，当您的组织下发了任何服务器托管的键时，会话会忽略运行器镜像中的该文件，但 [Claude Code 从每个管理员来源读取的键](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)除外，例如 `env` 块、沙箱锁定、沙箱二进制路径和 `forceRemoteSettingsRefresh`。请参阅[设置优先级](/docs/zh-CN/settings#settings-precedence)。574仓库中提交的 `.claude/settings.json` 会作为项目设置叠加在其上。在包含多个仓库的会话中，[最多只有一个仓库的文件生效](#repository-settings-in-sessions-with-several-repositories)。会话还会从运行器镜像中的标准系统路径读取 [`managed-settings.json`](/docs/zh-CN/settings#where-settings-live)。其中的键是否与[服务器托管设置](/docs/zh-CN/server-managed-settings)一起应用，取决于 [Claude Code 如何合并托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)：默认情况下，当您的组织下发了任何服务器托管的键时，会话会忽略运行器镜像中的该文件，但 [Claude Code 从每个管理员来源读取的键](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)除外，例如 `env` 块、沙箱锁定、沙箱二进制路径和 `forceRemoteSettingsRefresh`。请参阅[设置优先级](/docs/zh-CN/settings#settings-precedence)。

575 575

576当 Anthropic 的控制平面为会话提供 [Claude Code hook](/docs/zh-CN/hooks) 时，运行器会将它们与您自己的配置并行安装，而不是覆盖您的配置。需要 Claude Code v2.1.229 或更高版本。576当 Anthropic 的控制平面为会话提供 [Claude Code hook](/docs/zh-CN/hooks) 时，运行器会将它们与您自己的配置并行安装，而不是覆盖您的配置。需要 Claude Code v2.1.229 或更高版本。

577 577

583 583

584运行器对主机 `~/.claude/` 的快照不包含 `projects/` 目录。自动记忆的默认存储位置就在该目录下。如果您将记忆文件放在那里，运行器不会将它们填充到会话中，它们也不会启用自动记忆。584运行器对主机 `~/.claude/` 的快照不包含 `projects/` 目录。自动记忆的默认存储位置就在该目录下。如果您将记忆文件放在那里，运行器不会将它们填充到会话中，它们也不会启用自动记忆。

585 585

586<h3 id="repository-settings-in-sessions-with-several-repositories">

587 包含多个仓库的会话中的仓库设置

588</h3>

589

590在包含多个仓库的会话中，Claude Code 从会话启动所在的目录读取项目设置，因此最多只有一个仓库的 `.claude/settings.json` 作为项目设置生效。在其他仓库的文件中定义的 hook 不会运行，其中的拒绝规则不会生效，其 `env` 也不会被设置。

591

592* **`--capacity 1`（默认值）并使用内置检出**：会话在其仓库列表中的第一个仓库中启动。该仓库的 `.claude/settings.json` 作为项目设置生效，其 `.mcp.json` 会被加载，而其他仓库的则不会。

593* **`--capacity` 大于 1，或使用 [`checkout` hook](#checkout)**：会话在包含各检出内容的按会话目录中启动。没有任何仓库的 `.claude/settings.json` 作为项目设置生效，没有任何仓库的 `.mcp.json` 会被加载，并且 hook 命令中的 [`$CLAUDE_PROJECT_DIR`](/docs/zh-CN/hooks#reference-scripts-by-path) 是该目录，而不是某个检出目录。

594

595无论会话在何处启动，每个仓库的 `CLAUDE.md` 和 skill 都会被加载。运行器将每个仓库作为[附加目录](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)传递给 Claude Code，因此 Claude Code 还会从每个仓库的 `.claude/settings.json` 中读取 `enabledPlugins` 和 `extraKnownMarketplaces` 键。

596

597要在每个会话中运行某个 hook 或应用某条权限规则，请将其放在运行器主机上的 `~/.claude/settings.json` 中。无论会话在何处启动，运行器都会[将该主机文件填充到每个会话中](#how-each-session’s-config-is-assembled)。在 `Read` 或 `Edit` 规则中，请将路径写为以 `//` 开头的绝对路径或以 `~/` 开头的相对于主目录的[模式](/docs/zh-CN/permissions#read-and-edit)，因为其他模式会以设置来源或当前目录为锚点。

598

586<h3 id="repository-committed-permission-rules">599<h3 id="repository-committed-permission-rules">

587 仓库中提交的权限规则600 仓库中提交的权限规则

588</h3>601</h3>

server-managed-settings.md +5 −1

Details

87 87

88 由于 hooks 执行 shell 命令，交互式会话中的用户在 Claude Code 应用它们之前会看到[安全批准对话框](#security-approval-dialogs)。88 由于 hooks 执行 shell 命令，交互式会话中的用户在 Claude Code 应用它们之前会看到[安全批准对话框](#security-approval-dialogs)。

89 89

90 要配置 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器，使其了解您的组织信任的存储库、存储桶和域，以相同的方式传递 `autoMode` 块；有关 `autoMode` 条目如何影响分类器阻止的内容以及关于 `environment`、`allow`、`soft_deny` 和 `hard_deny` 字段的重要警告，请参阅[配置 auto mode](/docs/zh-CN/auto-mode-config)。90 要配置[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器，使其了解您的组织信任的存储库、存储桶和域，以相同的方式传递 `autoMode` 块；有关 `autoMode` 条目如何影响分类器阻止的内容以及关于 `environment`、`allow`、`soft_deny` 和 `hard_deny` 字段的重要警告，请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。

91 </Step>91 </Step>

92 92

93 <Step title="保存并部署">93 <Step title="保存并部署">

94 保存您的更改。Claude Code 客户端在下次启动或每小时轮询周期时接收更新的设置。94 保存您的更改。Claude Code 客户端在下次启动或每小时轮询周期时接收更新的设置。

96 编辑器会根据已发布的 Claude Code 设置 JSON schema 检查您的 JSON。如果在可解析的 JSON 中发现问题，它会显示警告并更改保存按钮的标签。当已保存设置时，标签为 **Update with errors**；当尚未保存任何设置时，标签为 **Add with errors**。该按钮仍然会保存，因为 schema 警告不会阻止保存。

98 该 schema [可能落后于最新版本](/docs/zh-CN/settings#edit-a-settings-file)，因此编辑器可能会标记[设置参考](/docs/zh-CN/settings-reference#all-settings)中已记录的键或值。Claude Code 会接收您保存的键和值，并在加载它们时运行[自己的验证](#invalid-entries-in-delivered-settings)。

95 </Step>99 </Step>

96</Steps>100</Steps>

97 101

settings.md +41 −41

Details

400 设置文件及其影响范围400 设置文件及其影响范围

401</h2>401</h2>

402 402

403Claude Code 从四个文件读取设置，组织也可以从 claude.ai 控制台提供托管设置。每个来源都有一个作用域：设置所适用的人员和项目范围，可能是仅限于您、项目中的所有人，或组织中的所有人。403Claude Code 从四个文件读取设置，组织也可以从 claude.ai 控制台提供托管设置。每个来源都有一个作用域：保存在其中的设置所适用的人员和项目范围，可能是仅限于您、项目中的所有人，或组织中的所有人。

404 404

405| 作用域 | 文件 | 影响范围 | 用途 |405| 作用域 | 文件 | 影响范围 | 用途 |

406| :- | :- | :- | :- |406| :- | :- | :- | :- |

411 411

412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。412在"文件"列中，`~/.claude` 是您主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。

413 413

414<span id="where-each-file-applies" />414<span id="where-each-file-applies" />

415 415

419 比较每个设置文件的作用域419 比较每个设置文件的作用域

420</h3>420</h3>

421 421

422假设你在机器上有三个项目：`website/`、`api/` 和 `acme-app/`，一个队友有他们自己的 `acme-app/` 克隆，你在 `acme-app/` 上启动了一个[云会话](#settings-in-cloud-sessions)。422假设您的机器上有三个项目：`website/`、`api/` 和 `acme-app/`，一位队友有自己的 `acme-app/` 克隆，并且您在 `acme-app/` 上启动了一个[云端会话](#settings-in-cloud-sessions)。

423 423

424下面的图表显示当你从这些文件夹启动 Claude Code 时，设置应用在哪些文件夹中。点击一个设置文件查看它到达的文件夹。424下图显示了当您从这些文件夹启动 Claude Code 时，设置会在哪些文件夹中生效。点击某个设置文件即可查看它覆盖到的文件夹。

425 425

426<SettingsScope />426<SettingsScope />

427 427

428* **`~/.claude/settings.json`**：你机器上的每个项目，以及队友机器上或云会话中都没有428* **`~/.claude/settings.json`**：您机器上的每个项目，而队友的机器上和云端会话中都不会生效

429* **`acme-app/.claude/settings.json`**：你的 `acme-app/`。只有当你将文件提交到版本控制时，它才会到达你队友的克隆和云会话；在此之前，它就像任何其他磁盘上的文件一样，其他人没有它429* **`acme-app/.claude/settings.json`**：您的 `acme-app/`。只有当您将该文件提交到版本控制后，它才会覆盖到队友的克隆和云端会话；在此之前，它只是您磁盘上的一个普通文件，其他人都没有它

430* **`acme-app/.claude/settings.local.json`**：仅你的 `acme-app/`。Claude Code 第一次写入文件时将其添加到你的全局 git 排除项中，因此它不会进入你的提交；如果你手动创建文件，[自己添加到 `.gitignore`](#keep-personal-settings-out-of-a-repository)430* **`acme-app/.claude/settings.local.json`**：仅您的 `acme-app/`。Claude Code 第一次写入该文件时会将其添加到您的全局 git 排除项中，因此它不会进入您的提交；如果您手动创建该文件，请[自行将其添加到 `.gitignore`](#keep-personal-settings-out-of-a-repository)

431* **托管设置**，无论是 `managed-settings.json` 文件、MDM 策略，还是来自 claude.ai 控制台的[服务器托管设置](/docs/zh-CN/server-managed-settings)：你的组织部署到的每台机器上的每个项目，或你使用组织账户登录的地方。只有服务器托管设置到达云会话431* **托管设置**，无论是 `managed-settings.json` 文件、MDM 策略，还是来自 claude.ai 控制台的[服务器托管设置](/docs/zh-CN/server-managed-settings)：您的组织部署到的每台机器上的每个项目，或您使用组织账户登录的每台机器上的每个项目。只有服务器托管设置会覆盖到云端会话

432 432

433<span id="which-files-you-have" />433<span id="which-files-you-have" />

434 434

435<h3 id="find-or-create-your-settings-files">435<h3 id="find-or-create-your-settings-files">

436 查找或创建你的设置文件436 查找或创建设置文件

437</h3>437</h3>

438 438

439安装 Claude Code 不会创建任何设置文件。如果你的机器或项目已经有一个，它来自以下来源之一：439安装 Claude Code 不会创建任何设置文件。如果您的机器或项目中已经有设置文件，它来自以下来源之一：

440 440

441* **托管**：你的组织部署它。你不创建或编辑它。441* **托管**：由您的组织部署。您无需创建或编辑它。

442* **共享项目**：已经使用 Claude Code 的项目可能已提交一个。如果没有，在项目文件夹中的 `.claude/settings.json` 创建一个。442* **共享项目**：已经使用 Claude Code 的项目可能已提交了该文件。如果没有，请在项目文件夹中的 `.claude/settings.json` 创建它。

443* **用户**和**项目本地**：自己创建它们，或让 Claude Code 创建它们。当你在 `/config` 菜单中更改存储在用户设置中的选项（如主题）时，它会写入 `~/.claude/settings.json`，当你在权限提示上给予常设批准（如对 Bash 命令的"是的，不要再问"）时，它会写入 `.claude/settings.local.json`。一些 `/config` 选项，包括**显示提示**，保存到 `.claude/settings.local.json` 而不是用户文件。443* **用户**和**项目本地**：您可以自行创建，也可以让 Claude Code 创建。当您第一次在 `/config` 菜单中更改存储在用户设置中的选项（例如主题）时，它会写入 `~/.claude/settings.json`；当您第一次在权限提示上给予常设批准（例如对 Bash 命令选择"Yes, and don't ask again"）时，它会写入 `.claude/settings.local.json`。少数 `/config` 选项（包括 **Show tips**）会保存到 `.claude/settings.local.json`，而不是用户文件。

444 444

445<Info>445<Info>

446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。要将主目录文件保存在其他地方，设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)；Claude Code 然后将你的设置、会话历史和 plugins 存储在那里。446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。要将主目录中的文件保存在其他位置，请设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)；Claude Code 随后会将您的设置、会话历史和插件存储在该位置。

447</Info>447</Info>

448 448

449Claude Code 还保留第五个文件 [`~/.claude.json`](/docs/zh-CN/claude-directory#ce-claude-json)，它为自己写入；你不需要编辑它。它保存你的登录会话、[MCP server](/docs/zh-CN/mcp) 配置、每个项目的状态（如信任决定），以及 `/config` 为你写入的[全局配置键](/docs/zh-CN/settings-reference#global-config-settings)。449Claude Code 还会保留第五个文件 [`~/.claude.json`](/docs/zh-CN/claude-directory#ce-claude-json)，由它自行写入；您无需编辑它。该文件保存您的登录会话、[MCP 服务器](/docs/zh-CN/mcp)配置、每个项目的状态（例如信任决定），以及 `/config` 为您写入的[全局配置键](/docs/zh-CN/settings-reference#global-config-settings)。

450 450

451<h3 id="share-settings-with-your-team">451<h3 id="share-settings-with-your-team">

452 与你的团队共享设置452 与团队共享设置

453</h3>453</h3>

454 454

455提交 `.claude/settings.json` 以便克隆仓库的每个人都获得相同的权限、hooks 和 plugins。每个队友仍然可以在他们自己的 `.claude/settings.local.json` 中为自己覆盖它，因此个人例外不需要提交。有关完整的团队文件，请参阅[团队的共享设置](/docs/zh-CN/settings-example#a-teams-shared-settings)。455提交 `.claude/settings.json`，以便克隆仓库的每个人都获得相同的权限、hook 和插件。每位队友仍可以在自己的 `.claude/settings.local.json` 中为自己覆盖它，因此个人例外无需提交。有关完整的团队文件，请参阅[团队的共享设置](/docs/zh-CN/settings-example#a-teams-shared-settings)。

456 456

457你提交的一些内容等待每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，少数键永远不会从仓库文件生效；[排查不适用的设置](#common-cases)涵盖两者。457您提交的部分内容要等到每位队友[信任该文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后才会生效，还有少数键永远不会从仓库文件中生效；[排查不生效的设置](#common-cases)涵盖了这两种情况。

458 458

459<span id="local-settings-file" />459<span id="local-settings-file" />

460 460

468 将个人设置保留在仓库之外468 将个人设置保留在仓库之外

469</h3>469</h3>

470 470

471要在一个项目中为自己更改设置而不为队友更改，请在项目内的 `.claude/settings.local.json` 中保存它。Claude Code 在提交的 `.claude/settings.json` 上应用该文件，因此如果你的团队文件设置 `"model": "claude-sonnet-5"` 而你想要 Opus，在你的本地文件中放入 `"model": "claude-opus-5-5"`，只有你的会话会改变。471要在某个项目中仅为自己更改设置而不影响队友，请将其保存在项目内的 `.claude/settings.local.json` 中。Claude Code 会在已提交的 `.claude/settings.json` 之上应用该文件，因此如果团队文件设置了 `"model": "claude-sonnet-5"` 而您想使用 Opus，请在本地文件中放入 `"model": "claude-opus-5-5"`，这样只有您的会话会发生变化。

472 472

473Claude Code 也会写入此文件，将其保留在你的提交之外，并应用其允许规则而无需信任步骤：473Claude Code 也会写入此文件，将其排除在您的提交之外，并且无需信任步骤即可应用其允许规则：

474 474

475* **Claude Code 也会写入它。** 当 Claude 要求运行 Bash 命令的权限，你选择"是的，不要再问"时，Claude Code 将该[权限批准](/docs/zh-CN/permissions#permission-system)保存为此处的 `allow` 规则。475* **Claude Code 也会写入它。** 当 Claude 请求运行 Bash 命令的权限而您选择"Yes, and don't ask again"时，Claude Code 会将该[权限批准](/docs/zh-CN/permissions#permission-system)作为 `allow` 规则保存在此处。

476* **除非你手动创建，否则你不需要 gitignore 它。** Claude Code 第一次在不已忽略它的 git 仓库中写入文件时，它会将 `**/.claude/settings.local.json` 添加到你的全局 git 排除文件中，因此该文件在每个仓库中都不会进入你的提交。该文件是 `core.excludesFile`（当你的全局 git 配置将其设置为绝对路径或 `~` 前缀路径时）；否则是 `$XDG_CONFIG_HOME/git/ignore`，或当 `XDG_CONFIG_HOME` 未设置时是 `~/.config/git/ignore`。如果你手动创建了文件，Claude Code 还没有写入它，请自己添加到 `.gitignore`。476* **您无需自行将其加入 gitignore，除非您是手动创建的。** Claude Code 第一次在尚未忽略该文件的 git 仓库中写入它时，会将 `**/.claude/settings.local.json` 添加到您的全局 git 排除文件中，因此该文件在每个仓库中都不会进入您的提交。当您的全局 git 配置将 `core.excludesFile` 设置为绝对路径或以 `~` 开头的路径时，该排除文件就是 `core.excludesFile`；否则为 `$XDG_CONFIG_HOME/git/ignore`，或在未设置 `XDG_CONFIG_HOME` 时为 `~/.config/git/ignore`。如果您手动创建了该文件且 Claude Code 尚未写入它，请自行将其添加到 `.gitignore`。

477* **当文件保持未跟踪时，其允许规则不等待信任。** 因为文件是你的而不是仓库的，Claude Code 应用其 `allow` 规则而无需它对提交文件要求的[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)步骤。如果文件被 git 跟踪，信任步骤也适用于它；请参阅[当你的本地设置文件需要信任](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)。477* **只要文件保持未跟踪状态，其允许规则就无需等待信任。** 由于该文件属于您而不属于仓库，Claude Code 会应用其 `allow` 规则，而无需经过已提交文件所要求的[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)步骤。如果该文件被 git 跟踪，信任步骤同样适用于它；请参阅[本地设置文件何时需要信任](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)。

478 478

479<span id="where-claude-code-looks-for-each-file" />479<span id="where-claude-code-looks-for-each-file" />

480 480

483<span id="local-allow-rules-dont-wait-for-workspace-trust" />483<span id="local-allow-rules-dont-wait-for-workspace-trust" />

484 484

485<h4 id="where-claude-code-keeps-the-local-file-in-a-git-repository">485<h4 id="where-claude-code-keeps-the-local-file-in-a-git-repository">

486 Claude Code 在 git 仓库中保留本地文件的位置486 Claude Code 在 git 仓库中保存本地文件的位置

487</h4>487</h4>

488 488

489当 Claude 要求运行 Bash 命令的权限，你选择"是的，不要再问"时，Claude Code 将该批准保存为 `.claude/settings.local.json` 中的 `allow` 规则。如果你在 git 仓库的子目录中启动 Claude Code，它会在仓库根目录读取和写入该文件，并在整个仓库中应用批准。在[worktree](/docs/zh-CN/worktrees) 中，它使用主检出根目录处的文件。489当 Claude 请求运行 Bash 命令的权限而您选择"Yes, and don't ask again"时，Claude Code 会将该批准作为 `allow` 规则保存在 `.claude/settings.local.json` 中。如果您在 git 仓库的子目录中启动 Claude Code，它会在仓库根目录读取和写入该文件，并在整个仓库中应用该批准。在 [worktree](/docs/zh-CN/worktrees) 中，它使用主检出根目录下的文件。

490 490

491两条规则限定根位置：491有两条规则对根目录位置加以限定：

492 492

493* **当文件与 `.claude/settings.json` 保持在一起时**：在 git 仓库之外，当仓库根是你的主目录时，在 Windows 上，或当仓库根或其 `.git` 或 `.claude` 条目不由你的用户拥有时。493* **文件改为与 `.claude/settings.json` 放在一起的情况**：在 git 仓库之外、仓库根目录是您的主目录时、在 Windows 上，或者仓库根目录或其 `.git` 或 `.claude` 条目不归您的用户所有时。

494* **文件中的路径不在仓库根处锚定**：以 `/` 开头的权限规则或相对沙箱路径[在会话的主工作目录处锚定](/docs/zh-CN/permissions#read-and-edit)。494* **文件中的路径不以仓库根目录为锚点**：以 `/` 开头的权限规则或相对沙箱路径改为[以会话的主工作目录为锚点](/docs/zh-CN/permissions#read-and-edit)。

495 495

496在 v2.1.211 之前，Claude Code 将文件保留在启动目录中。它仍然读取早期版本在根文件旁边留下的文件；当两者设置相同的键时，根的值适用，两个文件的权限规则都适用。Agent SDK 的 [`resolveSettings()`](/docs/zh-CN/agent-sdk/typescript#resolvesettings) 助手始终从启动目录读取文件。496在 v2.1.211 之前，Claude Code 将该文件保存在启动目录中。它仍会读取早期版本留在那里的文件，并与根目录文件一同读取；当两者设置了相同的键时，以根目录文件的值为准，而两个文件中的权限规则都会生效。Agent SDK 的 [`resolveSettings()`](/docs/zh-CN/agent-sdk/typescript#resolvesettings) 辅助函数始终从启动目录读取该文件。

497 497

498Claude Code 从会话的[主工作目录](/docs/zh-CN/permissions#working-directories)读取共享的 `.claude/settings.json`，因此要使用在仓库根处提交的文件，请从那里启动 Claude Code。在你[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后，Claude Code 改为从新目录读取两个项目文件，按相同规则放置本地文件。从你移动到的目录读取它们需要 Claude Code v2.1.246 或更高版本。498Claude Code 从会话的[主工作目录](/docs/zh-CN/permissions#working-directories)读取共享的 `.claude/settings.json`，因此要使用提交在仓库根目录的文件，请从那里启动 Claude Code。在您[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后，Claude Code 会改为从新目录读取这两个项目文件，并按相同规则放置本地文件。从您移动到的目录读取它们需要 Claude Code v2.1.246 或更高版本。

499 499

500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />

501 501

508<span id="settings-your-organization-manages" />508<span id="settings-your-organization-manages" />

509 509

510<h3 id="check-what-your-organization-enforces">510<h3 id="check-what-your-organization-enforces">

511 检查你的组织强制执行的内容511 检查组织强制执行的内容

512</h3>512</h3>

513 513

514如果你的组织管理 Claude Code，某些设置是为你决定的，你在自己的文件中放入的任何内容都不会改变它们。要查看哪些，运行 `/status`：`Setting sources` 行命名适用于你的托管来源。托管设置在这台机器上 Claude Code 运行的任何地方都适用；[开发人员可以更改的内容](/docs/zh-CN/managed-settings#what-a-developer-can-change)涵盖本地管理员权限和 Claude Code 以外的工具。514如果您的组织管理 Claude Code，某些设置已由组织为您决定，您在自己的文件中放入的任何内容都无法更改它们。要查看是哪些设置，请运行 `/status`：`Setting sources` 行会列出适用于您的托管来源。托管设置在这台机器上 Claude Code 运行的任何位置都会生效；[开发人员可以更改的内容](/docs/zh-CN/managed-settings#what-a-developer-can-change)介绍了本地管理员权限以及 Claude Code 以外的工具。

515 515

516托管设置通过托管设置页面上的[交付机制](/docs/zh-CN/managed-settings#delivery-mechanisms)到达你，最常见的是：516托管设置通过托管设置页面上介绍的[交付机制](/docs/zh-CN/managed-settings#delivery-mechanisms)送达您，最常见的是：

517 517

518* [服务器托管设置](/docs/zh-CN/server-managed-settings)，Claude Code 从 claude.ai 管理控制台或自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 获取518* [服务器托管设置](/docs/zh-CN/server-managed-settings)，由 Claude Code 从 claude.ai 管理控制台或自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 获取

519* MDM 或操作系统级别的策略，以及系统目录中的 `managed-settings.json` 文件519* MDM 或操作系统级别的策略，以及系统目录中的 `managed-settings.json` 文件

520* 嵌入主机（如 Claude Desktop），通过 SDK `managedSettings` 选项；请参阅[从嵌入主机控制策略](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)520* 嵌入主机（例如 Claude Desktop），通过 SDK `managedSettings` 选项提供；请参阅[从嵌入主机控制策略](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)

521 521

522在在 Claude Desktop 应用中在你的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude Code 不会从 claude.ai 管理控制台获取服务器托管设置，它读取部署到你的设备的策略，除非你的组织的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)涵盖 Cowork 和云会话。522在 Claude Desktop 应用中于您的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude Code 不会从 claude.ai 管理控制台获取服务器托管设置，并且会读取部署到您设备上的策略，除非您组织的 Claude Desktop 配置设置了 `requireCoworkFullVmSandbox`。[策略的生效位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)介绍了 Cowork 和云端会话的情况。

523 523

524如果你是管理员，[为你的组织设置 Claude Code](/docs/zh-CN/admin-setup) 介绍了选择要强制执行的内容，[部署托管设置](/docs/zh-CN/managed-settings)涵盖交付以及如何确认策略生效。524如果您是管理员，[为组织设置 Claude Code](/docs/zh-CN/admin-setup) 将引导您选择要强制执行的内容，[部署托管设置](/docs/zh-CN/managed-settings)介绍了交付方式以及如何确认策略已生效。有关 claude.ai 管理控制台中托管设置编辑器可能显示的警告，请参阅[配置服务器托管设置](/docs/zh-CN/server-managed-settings#configure-server-managed-settings)。

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 更改设置527 更改设置

809 809

810[云会话](/docs/zh-CN/claude-code-on-the-web)在[云环境](/docs/zh-CN/cloud-environments)中运行在您的存储库的新克隆上，而不是在您的机器上。这改变了哪些设置到达它：810[云会话](/docs/zh-CN/claude-code-on-the-web)在[云环境](/docs/zh-CN/cloud-environments)中运行在您的存储库的新克隆上，而不是在您的机器上。这改变了哪些设置到达它：

811 811

812* **共享项目设置** (`.claude/settings.json`)：在一个存储库的会话中读取，因为该文件是克隆的一部分，会话在其中启动。在那里提交设置以在这些会话中应用它。具有多个存储库的会话在克隆上方启动，因此从每个存储库的 `.claude/settings.json` 仅读取 `enabledPlugins` 和 `extraKnownMarketplaces` 键，而不是权限规则、hooks、`env` 或其他键。这些两个键声明的市场和插件仍然[不在云会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。812* **共享项目设置**（`.claude/settings.json`）：在只有一个仓库的会话中会被读取，因为该文件是克隆的一部分，且会话在其中启动。将设置提交到该文件中，即可在这些会话中应用。在 Anthropic 托管的环境中，包含多个仓库的会话会在各克隆的上层目录启动，并且只从每个仓库的 `.claude/settings.json` 中读取 `enabledPlugins` 和 `extraKnownMarketplaces` 这两个键，而不会读取权限规则、hook、`env` 或其他键。这两个键所声明的市场和插件仍然[不会在云端会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。对于自托管环境，请参阅[应用哪个仓库的设置](/docs/zh-CN/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)。

813* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。813* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。

814* **托管设置**：您设备上的 `managed-settings.json` 文件或 MDM 配置文件不会到达云会话。您组织的[服务器管理设置](/docs/zh-CN/server-managed-settings)会；[表面覆盖](/docs/zh-CN/model-config#surface-coverage)列出哪些云会话接收它们。[自托管环境](/docs/zh-CN/self-hosted-environments)也读取其运行器镜像中的托管设置文件。[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说该文件何时适用。814* **托管设置**：您设备上的 `managed-settings.json` 文件或 MDM 配置文件不会到达云会话。您组织的[服务器管理设置](/docs/zh-CN/server-managed-settings)会；[表面覆盖](/docs/zh-CN/model-config#surface-coverage)列出哪些云会话接收它们。[自托管环境](/docs/zh-CN/self-hosted-environments)也读取其运行器镜像中的托管设置文件。[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说该文件何时适用。

815* **`/config`**：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将键提交到该存储库的 `.claude/settings.json`。815* **`/config`**：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将键提交到该存储库的 `.claude/settings.json`。

skills.md +2 −0

Details

94| `migrate` | 将您现有的 Claude API 代码更新到更新的模型 | 早于 v2.1.221 |94| `migrate` | 将您现有的 Claude API 代码更新到更新的模型 | 早于 v2.1.221 |

96| `managed-agents-onboard` | 逐步完成创建新的托管代理 | 早于 v2.1.221 |96| `managed-agents-onboard` | 逐步完成创建新的托管代理 | 早于 v2.1.221 |

97| `managed-agents-onboard <url>` | 构建该 URL 所指页面描述的 Managed Agent，例如 [Managed Agents 文档](https://platform.claude.com/docs/en/managed-agents/overview)中的某个页面 | v2.1.290 或更高版本 |

98| `managed-agents-onboard <quickstart-name>` | 构建 Console 的某个快速入门模板，例如 `deep-researcher`。如果您提供的单个词不是模板名称，Claude 会列出有效的名称 | v2.1.290 或更高版本 |

sub-agents.md +3 −1

Details

609主对话的权限模式决定 Claude Code 是否使用您设置的值：609主对话的权限模式决定 Claude Code 是否使用您设置的值：

610 610

611* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。611* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。

612* 当主对话在 `default`、`dontAsk` 或 `plan` 模式时，subagent 在您设置的权限模式中运行，除了 `bypassPermissions`。声明 `bypassPermissions` 的 subagent 改为保持主对话的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。612* 当主对话处于 `default`、`dontAsk` 或 `plan` 模式时，子代理会在您设置的权限模式下运行。在以下情况下，它会改为保持主对话的权限模式：

613 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。

614 * 您设置了 `auto`，但子代理[无法使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，例如某个设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)，或子代理的模型不支持自动模式。

613 615

614`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：616`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：

615 617

tools-reference.md +1 −1

Details

666 666

667* WebFetch 拒绝 `localhost` 和任何其他没有点的主机名，例如裸露的内网名称，在发出请求之前。它返回的[错误](/docs/zh-CN/errors#webfetch-cannot-fetch-localhost)告诉 Claude 通过 Bash 使用 `curl` 到达本地服务器。667* WebFetch 拒绝 `localhost` 和任何其他没有点的主机名，例如裸露的内网名称，在发出请求之前。它返回的[错误](/docs/zh-CN/errors#webfetch-cannot-fetch-localhost)告诉 Claude 通过 Bash 使用 `curl` 到达本地服务器。

668* HTTP URL 会自动升级到 HTTPS。668* HTTP URL 会自动升级到 HTTPS。

669* 大型页面在处理前会被截断到固定的字符限制。669* WebFetch 每次调用最多读取页面内容的 100,000 个字符。在 Claude Code v2.1.290 或更高版本上，对于更长的页面，结果会告知 Claude 有多少内容未被读取，以便 Claude 可以获取下一部分。

670* WebFetch 默认缓存每个响应 15 分钟，所以重复获取同一 URL 会快速返回。在 Claude Code v2.1.233 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-CN/env-vars#variables) 以更改 WebFetch 保留每个响应的时长。670* WebFetch 默认缓存每个响应 15 分钟，所以重复获取同一 URL 会快速返回。在 Claude Code v2.1.233 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-CN/env-vars#variables) 以更改 WebFetch 保留每个响应的时长。

671* 一个页面如果在五分钟内未完成下载，包括 WebFetch 跟随的任何重定向，则会因截止期限错误而失败。在 Claude Code v2.1.268 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/zh-CN/env-vars#variables) 以更改限制，或设置为 `0` 以移除它。671* 一个页面如果在五分钟内未完成下载，包括 WebFetch 跟随的任何重定向，则会因截止期限错误而失败。在 Claude Code v2.1.268 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/zh-CN/env-vars#variables) 以更改限制，或设置为 `0` 以移除它。

672* 当 URL 重定向到不同的主机时，WebFetch 返回一个文本结果，命名原始 URL 和重定向目标，而不是跟随它。Claude 然后使用第二个 WebFetch 调用获取新 URL。672* 当 URL 重定向到不同的主机时，WebFetch 返回一个文本结果，命名原始 URL 和重定向目标，而不是跟随它。Claude 然后使用第二个 WebFetch 调用获取新 URL。

ultrareview.md +6 −6

Details

56 审查拉取请求56 审查拉取请求

57</h3>57</h3>

58 58

~~59要审查 GitHub 拉取请求而不是本地分支，请传递 PR 编号：~~59要审查 `github.com` 上的拉取请求而不是本地分支，请传递 PR 编号：

60 60

61```text theme={null}61```text theme={null}

62/code-review ultra 123462/code-review ultra 1234

64 64

65该命令也接受 `#1234`、`PR 1234` 和粘贴的 PR URL；粘贴的 URL 必须指向您当前目录中的存储库。65该命令也接受 `#1234`、`PR 1234` 和粘贴的 PR URL；粘贴的 URL 必须指向您当前目录中的存储库。

66 66

67在 PR 模式下，云沙箱直接从主机克隆拉取请求，而不是捆绑您的本地工作树。PR 模式适用于 `github.com` 上的存储库以及 Owner 已连接到 Claude Code 的 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例。67PR 模式需要 `github.com` 上的仓库。对于 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例上的仓库，请运行不带 PR 编号的 `/code-review ultra` 来审查您的本地分支。

68 68

~~69对于 `github.com` 上的存储库，沙箱使用连接到您的 Claude 账户的 GitHub 账户进行克隆，因此该账户必须能够读取 PR 的存储库。~~69在 PR 模式下，云沙箱从 `github.com` 克隆拉取请求，而不是上传您的工作树。它使用连接到您的 Claude 账户的 GitHub 账户，因此该账户需要对仓库具有读取权限。

70 70

71运行 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 将您的 GitHub CLI 登录连接到您的 Claude 账户。71运行 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 将您的 GitHub CLI 登录连接到您的 Claude 账户。

72 72

74 将发现发布到拉取请求74 将发现发布到拉取请求

75</h3>75</h3>

76 76

77在 Claude Code v2.1.227 或更高版本上，当您在 `github.com` 上审查拉取请求时，您可以让 Claude 将完成的发现作为来自您自己 GitHub 账户的单个纯文本评论发布到 PR。该评论不是审查或批准，并以"由 Claude Code 生成"的说明结尾。当您审查分支或 GitHub Enterprise Server 拉取请求时，Claude Code 仅在您的会话中显示发现。77在 Claude Code v2.1.227 或更高版本上，当您在 `github.com` 上审查拉取请求时，您可以让 Claude 将完成的发现作为来自您自己 GitHub 账户的单个纯文本评论发布到 PR。该评论不是审查或批准，并以"由 Claude Code 生成"的说明结尾。当您审查分支时，Claude Code 仅在您的会话中显示发现。

78 78

79Claude Code 永远不会发布，除非您在该运行中选择，`--no-post` 是默认值。发布是您为每次运行做出的选择：79Claude Code 永远不会发布，除非您在该运行中选择，`--no-post` 是默认值。发布是您为每次运行做出的选择：

80 80

106当 Claude Code 的文本超过一个单词且不是分支名称或 PR 引用时，它将您的文本视为说明。它将单个单词读取为分支名称或 PR 引用，因此拼写错误的分支名称会从[针对不同的基础进行审查](#review-against-a-different-base)获得最接近分支的错误，而不是使用说明启动。如果您的文本将 PR 引用与其他单词结合，如 `check PR 123 again`，Claude Code 也不会启动；它会要求您重新运行仅使用 PR 编号来审查该 PR，或不使用引用来审查您的当前分支。106当 Claude Code 的文本超过一个单词且不是分支名称或 PR 引用时，它将您的文本视为说明。它将单个单词读取为分支名称或 PR 引用，因此拼写错误的分支名称会从[针对不同的基础进行审查](#review-against-a-different-base)获得最接近分支的错误，而不是使用说明启动。如果您的文本将 PR 引用与其他单词结合，如 `check PR 123 again`，Claude Code 也不会启动；它会要求您重新运行仅使用 PR 编号来审查该 PR，或不使用引用来审查您的当前分支。

107 107

108<Tip>108<Tip>

109 如果您的存储库太大而无法捆绑，Claude Code 会提示您改用 PR 模式。推送您的分支并打开草稿 PR，然后运行 `/code-review ultra <PR-number>`。109 如果您的仓库太大而无法捆绑，Claude Code 会提示您改用 PR 模式。对于 `github.com` 上的仓库，推送您的分支并打开草稿 PR，然后运行 `/code-review ultra <PR-number>`。

110</Tip>110</Tip>

111 111

112<h3 id="diff-limits-and-fallbacks">112<h3 id="diff-limits-and-fallbacks">

173claude ultrareview origin/main173claude ultrareview origin/main

174```174```

175 175

176不带参数时，该子命令会审查当前分支与默认分支之间的 diff；当不存在合并基准时，会执行与 `/code-review ultra` 相同的[回退到整个仓库审查](#diff-limits-and-fallbacks)。传入 PR 编号可审查对应的 Pull Request，传入基准分支则以该分支为基准进行审查；[基准分支的处理方式](#review-against-a-different-base)与交互式命令一致。176不带参数时，该子命令会审查当前分支与默认分支之间的 diff；当不存在合并基准时，会执行与 `/code-review ultra` 相同的[回退到整个仓库审查](#diff-limits-and-fallbacks)。传入 PR 编号可[审查 `github.com` 上的 Pull Request](#review-a-pull-request)，传入基准分支则以该分支为基准进行审查；[基准分支的处理方式](#review-against-a-different-base)与交互式命令一致。

177 177

178运行该子命令即表示您同意回退到整个仓库审查，并同意计费和条款确认提示，因此运行会直接开始，无需等待输入。只有您亲自运行才算作同意。如果改由 Claude 替您运行该子命令（例如通过 Bash 工具），Claude Code 会拒绝执行整个仓库审查。178运行该子命令即表示您同意回退到整个仓库审查，并同意计费和条款确认提示，因此运行会直接开始，无需等待输入。只有您亲自运行才算作同意。如果改由 Claude 替您运行该子命令（例如通过 Bash 工具），Claude Code 会拒绝执行整个仓库审查。

179 179

workflows.md +27 −1

Details

354 354

355主体是带有顶级 `await` 的纯 JavaScript。`agent()` 生成一个子代理，`pipeline()` 为列表中的每个项目运行一个，`parallel()` 同时运行一组代理任务并等待所有任务完成。355主体是带有顶级 `await` 的纯 JavaScript。`agent()` 生成一个子代理，`pipeline()` 为列表中的每个项目运行一个，`parallel()` 同时运行一组代理任务并等待所有任务完成。

356 356

357如果您在运行中途停止 `agent()` 调用或它遇到不可恢复的 API 错误，则 `agent()` 调用解析为 `null`。`pipeline()` 在结果数组中保留每个 `null`，这就是为什么示例以 `.filter(Boolean)` 结尾以删除这些条目。357如果您在运行中途停止 `agent()` 调用或它遇到不可恢复的 API 错误，则 `agent()` 调用解析为 `null`。`pipeline()` 在结果数组中保留每个 `null`，这就是为什么示例以 `.filter(Boolean)` 结尾以删除这些条目，其中包括[每次尝试都停滞的 Agent](#when-an-agent-stalls-and-restarts) 所占的位置。

358 358

359在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，您的脚本传递给 `agent()` 的提示不会计为您的请求，当分类器审查该子代理的操作时，因为 Claude Code 将其标记为脚本计算的文本。359在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，您的脚本传递给 `agent()` 的提示不会计为您的请求，当分类器审查该子代理的操作时，因为 Claude Code 将其标记为脚本计算的文本。

360 360

463* 限制在 24 小时内重置。每周限制可能重置得更远。463* 限制在 24 小时内重置。每周限制可能重置得更远。

464* 运行还没有等待过两次。当它第三次达到限制时，代理会失败。464* 运行还没有等待过两次。当它第三次达到限制时，代理会失败。

465 465

466<h3 id="when-an-agent-stalls-and-restarts">

467 当 Agent 停滞并重启时

468</h3>

469

470如果某个 Agent 的输出停止到达足够长的时间，它会使用相同的提示词重新开始。在 [`/workflows`](#watch-the-run) 中，其名称会添加 `(retry 1)` 后缀，其详细信息会显示 `attempt 2 (stalled)`。重启是自动的，因此您无需执行任何操作。

471

472新的尝试在开始时不带有停滞尝试的会话记录。停滞尝试已更改的文件保持更改状态，其消耗的 token 仍计入运行的总量。停滞窗口是 Claude Code 在结束尝试之前等待 Agent 输出的时长。Agent 等待其自身工具调用或等待[用量限制重置](#when-a-run-hits-your-usage-limit)所花费的时间不计入停滞窗口。

473

474一个 Agent 最多重启五次，包括您使用 `r` 请求的任何重启。如果第六次尝试也停滞，`agent()` 调用会失败，错误的开头会说明原因：

475

476* `agent stalled on all 6 attempts`：每次尝试在整个窗口内都没有输出。如果 Agent 的工作使其保持静默这么长时间，请延长窗口

477* `agent lost its reply on all 6 attempts`：每次尝试的响应流都变为静默，Claude Code 放弃了等待。延长停滞窗口没有帮助，因为[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs)先结束了响应，而 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置该看门狗的超时时间

478* `agent abandoned after 6 attempts`：各次尝试以不同方式结束，错误会按顺序列出这些方式

479

480要在窗口结束前给 Agent 更多时间来产生输出：

481

482* **单个 Agent**：在其 `agent()` 调用中以毫秒为单位传入 `stallMs`，例如 `agent(prompt, { stallMs: 1800000 })` 表示 30 分钟

483* **所有 Agent**：设置 [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables)，它也适用于工作流之外的子代理

484

485失败后运行是否继续取决于您的脚本如何调用该 Agent：

486

487* **在 [`parallel()` 或 `pipeline()`](#what-the-saved-script-looks-like) 内部**：运行继续，用 `null` 代替该 Agent 的结果

488* **直接 await**：运行以该错误结束

489

490要重试，请要求 Claude 重新启动工作流。[暂停后恢复](#resume-after-a-pause)介绍了哪些内容会再次运行。

491

466<h3 id="cost">492<h3 id="cost">

467 成本493 成本

468</h3>494</h3>

worktrees.md +1 −1

Details

104* **Git 重定向**：Claude Code 阻止将 git 重定向到主检出的 Bash 或 Monitor 命令。重定向可以通过 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 变量，或在运行 git 之前 `cd` 到主检出来进行。104* **Git 重定向**：Claude Code 阻止将 git 重定向到主检出的 Bash 或 Monitor 命令。重定向可以通过 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 变量，或在运行 git 之前 `cd` 到主检出来进行。

105* **命令形状**：当 Claude Code 无法从命令文本验证命令运行的任何 git 保持在 worktree 内时，它会阻止 Bash 或 Monitor 命令。例如，当命令名称在运行时计算、语法无法解析，或当诸如 `${!name}` 或 `${ command; }` 之类的扩展可能运行文本中未明确说明的命令时，就会发生这种情况。Claude Code 告诉 Claude 如何重写被拒绝的命令，例如将其分割成普通的单独命令。您无法关闭此检查。105* **命令形状**：当 Claude Code 无法从命令文本验证命令运行的任何 git 保持在 worktree 内时，它会阻止 Bash 或 Monitor 命令。例如，当命令名称在运行时计算、语法无法解析，或当诸如 `${!name}` 或 `${ command; }` 之类的扩展可能运行文本中未明确说明的命令时，就会发生这种情况。Claude Code 告诉 Claude 如何重写被拒绝的命令，例如将其分割成普通的单独命令。您无法关闭此检查。

106 106

107这些检查读取编辑所针对的路径、命令运行所在的目录以及命令的文本。它们都不会跟踪 shell 命令写入了哪些文件，因此，在主检出中写入文件但并未在那里运行 git 的命令（例如 `cp` 或 shell 重定向）不会被这些检查拒绝。Claude Code 会像对待任何其他 shell 命令一样对待该命令，因此它是直接运行还是向您发出提示，取决于您的[权限模式](/docs/zh-CN/permission-modes)和规则。107这些检查读取编辑所针对的路径、命令运行所在的目录以及命令的文本。它们都不会跟踪 shell 命令写入了哪些文件，因此，在主检出中写入文件但并未在那里运行 git 的命令（例如 `cp` 或 shell 重定向）不会被这些检查拒绝。Claude Code 会像对待任何其他 shell 命令一样，依据您的[权限](/docs/zh-CN/permissions)和[沙箱隔离](/docs/zh-CN/sandboxing)设置来处理该命令。

108 108

109检查适用于您启动 Claude Code 的存储库。它们也涵盖链接的 worktree 链接自的主检出。对于 PowerShell 命令，Claude Code 仅应用工作目录检查。109检查适用于您启动 Claude Code 的存储库。它们也涵盖链接的 worktree 链接自的主检出。对于 PowerShell 命令，Claude Code 仅应用工作目录检查。

110 110

Documentation 2026-10-08 22:58 UTC to 2026-10-09 12:57 UTC