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 +5 −2

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) |

987```987```

988 988

989* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时时间，以毫秒为单位。默认 `600000`。适用于主循环和所有子代理。989* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时时间，以毫秒为单位。默认 `600000`。适用于主循环和所有子代理。

990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避时间。对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它会无限期重试瞬时容量错误，并且在 Claude Code v2.1.199 或更高版本上，将其他瞬时错误的默认值提高到 `300` 并移除此变量的上限。990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口。

991

992 对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它会无限期重试瞬时容量错误，并且在 Claude Code v2.1.199 或更高版本上，将其他瞬时错误的默认值提高到 `300` 并移除此变量的上限。

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞监视器。当流监视器开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。当流监视器关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。993* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞监视器。当流监视器开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。当流监视器关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。

992 994

993 计时器在每个流事件时重置。停滞时，Claude Code 中止子代理并向父 Agent 报告停滞。对于后台子代理，它也会将任务标记为失败并附加任何部分结果。995 计时器在每个流事件时重置。停滞时，Claude Code 中止子代理并向父 Agent 报告停滞。对于后台子代理，它也会将任务标记为失败并附加任何部分结果。

3327{3329{

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

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

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

3330}3333}

3331```3334```

3332 3335

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 +30 −5

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 服务器配置 |

631```631```

632 632

633* `API_TIMEOUT_MS`：Anthropic 客户端上的每请求超时时间，以毫秒为单位。默认值为 `600000`。适用于主循环和所有子代理。633* `API_TIMEOUT_MS`：Anthropic 客户端上的每请求超时时间，以毫秒为单位。默认值为 `600000`。适用于主循环和所有子代理。

634* `CLAUDE_CODE_MAX_RETRIES`：API 最大重试次数。默认值为 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 时间窗口，因此最坏情况下的实际耗时约为 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避时间。对于需要等待较长中断时间的无人值守运行，请设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它会无限期重试暂时性容量错误，并且在 Claude Code v2.1.199 或更高版本中，会将其他暂时性错误的默认重试次数提高到 `300`，并取消此变量的上限。634* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认值为 `10`，上限为 `15`。每次重试都有各自的 `API_TIMEOUT_MS` 时间窗口。

635

636 对于需要挺过较长中断的无人值守运行，请设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它会无限期重试临时性容量错误，并且在 Claude Code v2.1.199 或更高版本上，会将其他临时性错误的默认重试次数提高到 `300`，并取消此变量的上限。

635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞看门狗。当流看门狗开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，除非您调高该变量，否则合计为 `600000`。当流看门狗关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞看门狗。当流看门狗开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，除非您调高该变量，否则合计为 `600000`。当流看门狗关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。

636 638

637 每个流事件都会重置计时器。发生停滞时，Claude Code 会中止该子代理并向父级报告停滞。对于后台子代理，它还会将该任务标记为失败并附上任何部分结果。639 每个流事件都会重置计时器。发生停滞时，Claude Code 会中止该子代理并向父级报告停滞。对于后台子代理，它还会将该任务标记为失败并附上任何部分结果。

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

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

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

1566 agent_id?: string;

1564 timestamp?: string;1567 timestamp?: string;

1565 context_usage?: SDKContextUsage;1568 context_usage?: SDKContextUsage;

1566 user_message_uuid?: string;1569 user_message_uuid?: string;

1580 1583

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

1582 1585

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

1587

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

1589

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

1584 1591

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

1597 type: "user";1604 type: "user";

1598 uuid?: UUID;1605 uuid?: UUID;

1599 session_id?: string;1606 session_id?: string;

1607 agent_id?: string;

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

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

1602 parent_tool_use_id: string | null;1610 parent_tool_use_id: string | null;

1636};1644};

1637```1645```

1638 1646

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

1648

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

1640 1650

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 会以来自子代理的单独消息接收报告。1651* `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`2002 `SDKPartialAssistantMessage`

1993</h3>2003</h3>

1994 2004

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

2006

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

1996 2008

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

1998type SDKPartialAssistantMessage = {2010type SDKPartialAssistantMessage = {

3416type WebFetchInput = {3428type WebFetchInput = {

3417 url: string;3429 url: string;

3418 prompt: string;3430 prompt: string;

3431 offset?: number;

3419};3432};

3420```3433```

3421 3434

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

3423 3436

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

3438

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

3425 WebSearch3440 WebSearch

3426</h3>3441</h3>

5775 task_type?: string;5790 task_type?: string;

5776 is_backgrounded?: boolean;5791 is_backgrounded?: boolean;

5777 spawn_depth?: number;5792 spawn_depth?: number;

5793 parent_task_id?: string;

5778 ambient?: boolean;5794 ambient?: boolean;

5779 uuid: UUID;5795 uuid: UUID;

5780 session_id: string;5796 session_id: string;

5792 5808

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

5794 5810

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

5812

5813* 任务由主线程启动

5814* Claude Code 不再跟踪父任务

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

5816

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

5818

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

5796 `SDKTaskProgressMessage`5820 `SDKTaskProgressMessage`

5797</h3>5821</h3>

5848 `SDKBackgroundTasksChangedMessage`5872 `SDKBackgroundTasksChangedMessage`

5849</h3>5873</h3>

5850 5874

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

5852 5876

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

5854 5878

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

5856 5880

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

5858 5882

5869 task_type: string;5893 task_type: string;

5870 subagent_type?: string;5894 subagent_type?: string;

5871 description: string;5895 description: string;

5896 parent_task_id?: string;

5872 ambient?: boolean;5897 ambient?: boolean;

5873 }[];5898 }[];

5874 uuid: UUID;5899 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 +9 −6

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

825| `claude daemon logs` | 跟踪 supervisor 的日志文件 [`~/.claude/daemon.log`](#where-state-is-stored)，在新行到达时将其打印出来，直到您按下 `Ctrl+C` |825| `claude daemon logs` | 跟踪 supervisor 的日志文件 [`~/.claude/daemon.log`](#where-state-is-stored)，在新行到达时将其打印出来，直到您按下 `Ctrl+C` |

826| `claude daemon stop --any` | 停止 supervisor 进程及其托管的后台会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。下一个 `claude agents` 或 `claude --bg` 启动一个新的 supervisor |826| `claude daemon stop --any` | 停止 supervisor 进程及其托管的后台会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。下一个 `claude agents` 或 `claude --bg` 启动一个新的 supervisor |

827 827

828`claude attach` 和 `claude logs` 可以使用运行中会话名称的一部分代替 ID，例如 `claude logs "auth refactor"`。传递名称需要 Claude Code v2.1.290 或更高版本。828`claude attach` 和 `claude logs` 可以使用会话名称的一部分代替 ID，例如 `claude logs "auth refactor"`。传递名称需要 Claude Code v2.1.290 或更高版本。

829 829

830<h3 id="list-sessions-as-json">830<h3 id="list-sessions-as-json">

831 将会话列为 JSON831 将会话列为 JSON

979 打开会话说它没有保存的会话记录979 打开会话说它没有保存的会话记录

980</h3>980</h3>

981 981

982已停止的会话[从另一个对话后台处理](#from-inside-a-session)并在其第一个回复完成之前停止，没有任何可恢复的内容：在该第一个回复完成之前，对话仍然只存在于它被后台处理的会话中。`claude attach` 拒绝打开它，显示 `This session has no saved transcript`。982当您打开一个[从另一个对话后台处理](#from-inside-a-session)的会话，且该会话在运行自己的轮次之前就已停止时，Claude Code 会恢复那个对话。如果 Claude Code 找不到该对话，则会拒绝打开该会话：

983 983

984在 Agent 视图中，打开该行会在列表下显示 `Press enter again to restart this session fresh`。在同一行上再次按 `Enter` 来使用空对话重新启动会话，或从 shell 运行 `claude respawn <id>`。984* `claude attach` 打印 `This session has no saved transcript`。

985* Agent 视图在列表下方显示 `Press enter again to restart this session fresh`。

985 986

986原始对话完整无损；使用 `claude --resume` 恢复它或继续在其中工作。有关详细信息，请参阅[错误参考](/docs/zh-CN/errors#this-session-has-no-saved-transcript)。987在同一行上再次按 `Enter` 来使用空对话重新启动会话，或从 shell 运行 `claude respawn <id>`。

988

989有关详细信息，请参阅[错误参考](/docs/zh-CN/errors#this-session-has-no-saved-transcript)。

987 990

988<h3 id="the-terminal-host-died-or-the-session-stopped-responding">991<h3 id="the-terminal-host-died-or-the-session-stopped-responding">

989 终端主机已死亡或会话停止响应992 终端主机已死亡或会话停止响应

1095 1098

1096| 版本 | 更改 |1099| 版本 | 更改 |

1097| - | - |1100| - | - |

1098| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以使用正在运行的会话名称的一部分来代替 ID。 |1101| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以使用会话名称的一部分来代替 ID。 |

1099| v2.1.290 | `/model`、`/effort`、`/rename` 和 `/usage` 作为[窥视回复](#peek-and-reply)发送给正在工作的会话时会立即运行。 |1102| v2.1.290 | `/model`、`/effort`、`/rename` 和 `/usage` 作为[窥视回复](#peek-and-reply)发送给正在工作的会话时会立即运行。 |

1100| v2.1.290 | 无法投递的[窥视回复](#peek-and-reply)如果以 `/` 开头，或者在会话进程运行期间回答的是带有预定义选项的问题，则不再被保存以待下次重启时发送。 |1103| v2.1.290 | 无法投递的[窥视回复](#peek-and-reply)如果以 `/` 开头，或者在会话进程运行期间回答的是带有预定义选项的问题，则不再被保存以待下次重启时发送。 |

1101| v2.1.288 | `Ctrl+F` 按名称查找会话，`Alt+↑` / `Alt+↓` 在组标题之间跳转。这两者以及 `Ctrl+R` 都可以[重新绑定](/docs/zh-CN/keybindings#agents-actions)。 |1104| v2.1.288 | `Ctrl+F` 按名称查找会话，`Alt+↑` / `Alt+↓` 在组标题之间跳转。这两者以及 `Ctrl+R` 都可以[重新绑定](/docs/zh-CN/keybindings#agents-actions)。 |

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 +3 −3

Details

29| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出。JSON 包含一个 `configDirectory` 字段，命名 CLI 使用的 [配置目录](/docs/zh-CN/claude-directory)。该字段需要 Claude Code v2.1.268 或更高版本。JSON 的 `authMethod` 字段取值为 `none`、`claude.ai`、`oauth_token`、`api_key`、`api_key_helper` 或 `third_party` 之一 | `claude auth status` |29| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出。JSON 包含一个 `configDirectory` 字段，命名 CLI 使用的 [配置目录](/docs/zh-CN/claude-directory)。该字段需要 Claude Code v2.1.268 或更高版本。JSON 的 `authMethod` 字段取值为 `none`、`claude.ai`、`oauth_token`、`api_key`、`api_key_helper` 或 `third_party` 之一 | `claude auth status` |

30| `claude agents` | 打开 [agent view](/docs/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话，或使用 `--json` 将活动会话打印为 JSON 数组以供脚本使用（`--json --all` 也包括已完成的后台会话）。传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以设置 [分派会话的默认值](/docs/zh-CN/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如顶级 `claude` 命令。打开 agent view 需要交互式终端 | `claude agents --json` |30| `claude agents` | 打开 [agent view](/docs/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话，或使用 `--json` 将活动会话打印为 JSON 数组以供脚本使用（`--json --all` 也包括已完成的后台会话）。传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以设置 [分派会话的默认值](/docs/zh-CN/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如顶级 `claude` 命令。打开 agent view 需要交互式终端 | `claude agents --json` |

32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 通过从用户设置文件中删除 `autoMode` 部分来恢复默认 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 配置。在写入前提示确认；传递 `-y`/`--yes` 以跳过提示。来自 [托管设置](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的规则仍然适用。需要 Claude Code v2.1.212 或更高版本。请参阅 [检查默认值和您的有效配置](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 通过从用户设置文件中删除 `autoMode` 部分来恢复默认 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 配置。在写入前提示确认；传递 `-y`/`--yes` 以跳过提示。来自 [托管设置](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的规则仍然适用。需要 Claude Code v2.1.212 或更高版本。请参阅 [检查默认值和您的有效配置](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

34| `claude daemon logs` | 跟踪后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 的日志文件 `~/.claude/daemon.log`，在新行到达时将其打印出来，直到您按下 `Ctrl+C` | `claude daemon logs` |34| `claude daemon logs` | 跟踪后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 的日志文件 `~/.claude/daemon.log`，在新行到达时将其打印出来，直到您按下 `Ctrl+C` | `claude daemon logs` |

37| `claude daemon stop --any` | 停止后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/docs/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | 停止后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/docs/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |

39| `claude import [source]` | 启动交互式会话，运行 [`/import`](/docs/zh-CN/commands#all-commands) 以将来自其他编码 Agent 的配置引入 Claude Code。接受与命令相同的 `--dry-run` 和 `--yes` 选项。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。当您关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 时也不可用。需要 Claude Code v2.1.213 或更高版本 | `claude import codex --dry-run` |39| `claude import [source]` | 启动交互式会话，运行 [`/import`](/docs/zh-CN/commands#all-commands) 以将来自其他编码 Agent 的配置引入 Claude Code。接受与命令相同的 `--dry-run` 和 `--yes` 选项。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。当您关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 时也不可用。需要 Claude Code v2.1.213 或更高版本 | `claude import codex --dry-run` |

42| `claude mcp login <name>` | 运行配置的 MCP 服务器的 OAuth 流程而不打开交互式 `/mcp` 面板。适用于 HTTP、SSE 和 claude.ai 连接器服务器。在 SSH 上添加 `--no-browser` 以打印授权 URL 而不是打开浏览器，然后在提示处粘贴重定向 URL。请参阅 [从命令行进行身份验证](/docs/zh-CN/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |42| `claude mcp login <name>` | 运行配置的 MCP 服务器的 OAuth 流程而不打开交互式 `/mcp` 面板。适用于 HTTP、SSE 和 claude.ai 连接器服务器。在 SSH 上添加 `--no-browser` 以打印授权 URL 而不是打开浏览器，然后在提示处粘贴重定向 URL。请参阅 [从命令行进行身份验证](/docs/zh-CN/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

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 −2

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 在那里使用自己的滚动处理 |

590* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)591* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)

591* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)592* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)

592* 让 Claude 读取[其他组织的公开 Artifact](/docs/zh-CN/artifacts#read-an-artifact-shared-with-you)593* 让 Claude 读取[其他组织的公开 Artifact](/docs/zh-CN/artifacts#read-an-artifact-shared-with-you)

593* 让 Claude Code 针对 [MCP 协议修订版 2026-07-28](/docs/zh-CN/mcp#mcp-client-runtimes) 探测 claude.ai 连接器服务器，除非您设置了 `MCP_PROTOCOL_NEGOTIATION=auto`

594* 在安装了 Git Bash 的 Windows 上，为 claude.ai 和 Console 账户默认获得 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)；除非您设置了 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否则 Claude Code 会通过 Git Bash 执行 shell 命令。在未安装 Git Bash 的 Windows 上，该工具保持启用594* 在安装了 Git Bash 的 Windows 上，为 claude.ai 和 Console 账户默认获得 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)；除非您设置了 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否则 Claude Code 会通过 Git Bash 执行 shell 命令。在未安装 Git Bash 的 Windows 上，该工具保持启用

595* 获得 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，该功能由 Claude Code 通过获取的标志启用595* 获得 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，该功能由 Claude Code 通过获取的标志启用

596* 让 Claude [将大段粘贴内容视为粘贴而非键入的文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 占位符背后的内容将以无标记形式传给 Claude596* 让 Claude [将大段粘贴内容视为粘贴而非键入的文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 占位符背后的内容将以无标记形式传给 Claude

errors.md +4 −5

Details

386* 在 Claude 完成思考之后、但在开始任何文本或工具调用之前到达的服务器错误或过载响应。Claude Code 会在该点重试服务器错误最多两次。在 v2.1.284 之前，Claude Code 会在该点以该错误结束轮次。386* 在 Claude 完成思考之后、但在开始任何文本或工具调用之前到达的服务器错误或过载响应。Claude Code 会在该点重试服务器错误最多两次。在 v2.1.284 之前，Claude Code 会在该点以该错误结束轮次。

387* 连接断开。当连接在请求过程中途断开，且 Claude 尚未完成其响应的任何部分（包括其思考过程）时，Claude Code 会使用相同的退避重新发送请求，轮次继续进行，即使某些文本已经开始流式传输。当连接在 Claude 完成思考之后但在开始任何文本或工具调用之前断开时，Claude Code 改为快速连续重新发送请求最多两次，如果连接在该点继续断开，则以 `Connection lost before a response was produced` 结束轮次。387* 连接断开。当连接在请求过程中途断开，且 Claude 尚未完成其响应的任何部分（包括其思考过程）时，Claude Code 会使用相同的退避重新发送请求，轮次继续进行，即使某些文本已经开始流式传输。当连接在 Claude 完成思考之后但在开始任何文本或工具调用之前断开时，Claude Code 改为快速连续重新发送请求最多两次，如果连接在该点继续断开，则以 `Connection lost before a response was produced` 结束轮次。

388* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果轮次在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。388* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果轮次在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。

389* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不计入上述 10 次尝试预算。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束轮次。389* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接，并最多再以流式方式发送一次请求。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束轮次。

390* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束轮次。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。390* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束轮次。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。

391* 在 Claude 完成思考或开始任何文本或工具调用之前，被 API 输出内容过滤器拦截的流式响应。Claude Code 会在重试预算内重新发送一次请求，如果过滤器也拦截了第二次响应，则显示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。391* 在 Claude 完成思考或开始任何文本或工具调用之前，被 API 输出内容过滤器拦截的流式响应。Claude Code 会在重试预算内重新发送一次请求，如果过滤器也拦截了第二次响应，则显示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。

392* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。392* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。

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.

4817 此会话没有保存的会话记录4817 此会话没有保存的会话记录

4818</h3>4818</h3>

4819 4819

4820您附加到一个停止的[后台会话](/docs/zh-CN/agent-view)，该会话从另一个对话中用 `←` 或 `/background` 后台化，并在其第一个回复完成之前停止。在该第一个回复完成之前，对话仍然仅存在于后台化它的会话中，因此 `claude attach` 拒绝启动停止的会话，而不是在相同的会话 ID 下开始空白对话。消息以此会话的 `claude respawn` 命令结尾：4820您附加到一个通过 `←` 或 `/background` [移至后台](/docs/zh-CN/agent-view#from-inside-a-session)的会话，该会话在运行自己的轮次之前就已停止。Claude Code 找不到您将其移出的那个对话，因此该会话没有可恢复的内容。消息以此会话的 `claude respawn` 命令结尾：

4821 4821

4822```text theme={null}4822```text theme={null}

4823This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4823This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4827 4827

4828**要做什么：**4828**要做什么：**

4829 4829

4830* 您后台化的对话是完整的：使用 [`claude --resume`](/docs/zh-CN/sessions) 恢复它或继续在其中工作4830* 要重新启动停止的会话，请使用消息中的 ID 运行 `claude respawn <id>`，或在 Agent 视图中的其行上按 `Enter` 两次

4831* 要无论如何启动停止的会话，请使用消息中的 ID 运行 `claude respawn <id>`，或在 Agent 视图中的其行上按 `Enter` 两次

4832* 如果会话确实完成了回复，您仍然在 v2.1.214 之前的版本上看到此拒绝，`~/.claude/projects` 中的不可读文件夹可能会使会话记录扫描错过保存的对话；更新到 v2.1.214 或更高版本，它在扫描期间容忍不可读的文件夹4831* 如果会话确实完成了回复，您仍然在 v2.1.214 之前的版本上看到此拒绝，`~/.claude/projects` 中的不可读文件夹可能会使会话记录扫描错过保存的对话；更新到 v2.1.214 或更高版本，它在扫描期间容忍不可读的文件夹

4833 4832

4834<h3 id="this-session-is-running-in-another-terminal">4833<h3 id="this-session-is-running-in-another-terminal">

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

goal.md +1 −1

Details

127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

128```128```

129 129

130使用默认文本输出时，在运行结束前不会打印任何内容，所以运行许多回合的目标可能看起来卡住了。添加 `--output-format stream-json --verbose` 以在循环运行时发出每条消息。130使用默认文本输出时，Claude 的最终回复会在循环结束时打印，因此运行许多轮次的目标可能看起来卡住了。添加 `--output-format stream-json --verbose` 以在循环运行时输出每条消息。

131 131

132使用 Ctrl+C 中断进程以在条件满足之前停止非交互式目标。132使用 Ctrl+C 中断进程以在条件满足之前停止非交互式目标。

133 133

headless.md +24 −22

Details

20 基本用法20 基本用法

21</h2>21</h2>

22 22

23在任何 `claude` 命令中添加 `-p`（或 `--print`）标志以非交互方式运行它。并非每个 [CLI 选项](/docs/zh-CN/cli-reference) 都与 `-p` 兼容。Claude Code 拒绝 `--bg`，并在任务描述中拒绝 `--cloud`，会报错说明冲突；`--cloud` 与会话 ID 和 `-p` 一起使用时，会 [将消息排队到该云会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli) 并退出。你通常会与 `-p` 结合使用的选项包括：23在任何 `claude` 命令中添加 `-p`（或 `--print`）标志以非交互方式运行它。并非每个 [CLI 选项](/docs/zh-CN/cli-reference) 都能与 `-p` 组合使用。Claude Code 会拒绝 `--bg`，也会拒绝带有任务描述的 `--cloud`，并报错说明冲突；而 `--cloud` 与会话 ID 和 `-p` 一起使用时，会 [将消息排队到该云端会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli) 并退出。经常与 `-p` 结合使用的选项包括：

24 24

25* `--continue` 用于 [继续对话](#continue-conversations)25* `--continue` 用于 [继续对话](#continue-conversations)

26* `--allowedTools` 用于 [自动批准工具](#auto-approve-tools)26* `--allowedTools` 用于 [自动批准工具](#auto-approve-tools)

27* `--output-format` 用于 [获取结构化输出](#get-structured-output)27* `--output-format` 用于 [获取结构化输出](#get-structured-output)

28 28

~~29此示例向 Claude 询问有关你的代码库的问题并打印响应：~~29此示例向 Claude 询问有关您的代码库的问题并打印回复：

30 30

31```bash theme={null}31```bash theme={null}

32claude -p "What does the auth module do?"32claude -p "What does the auth module do?"

33```33```

34 34

35Claude Code 在成功时以代码 0 退出，在运行失败时以非零代码退出，因此你的脚本可以根据退出状态进行分支。如果你传递无效标志，Claude Code 会在运行开始前向 stderr 报告错误。当运行内部发生故障（例如缺少身份验证）时，Claude Code 会将故障作为结果打印到 stdout。35Claude Code 在成功时以代码 0 退出，在运行失败时以非零代码退出，因此您的脚本可以根据退出状态进行分支。如果您传递无效标志，Claude Code 会在运行开始前向 stderr 报告错误。当运行内部发生故障（例如缺少身份验证）时，Claude Code 会将故障作为结果打印到 stdout。

36 36

37<h3 id="start-faster-with-bare-mode">37<h3 id="start-faster-with-bare-mode">

~~38 使用裸模式更快启动~~38 使用 bare 模式更快启动

39</h3>39</h3>

40 40

41添加 `--bare` 以通过跳过 hooks、skills、自定义命令、[subagents](/docs/zh-CN/sub-agents)、已安装的插件、MCP 服务器、自动内存和 CLAUDE.md 的自动发现来减少启动时间。没有它，`claude -p` 会加载交互式会话相同的 [context](/docs/zh-CN/how-claude-code-works#the-context-window)，包括在工作目录或 `~/.claude` 中配置的任何内容。41添加 `--bare` 可以跳过 hook、skill、自定义命令、[子代理](/docs/zh-CN/sub-agents)、已安装的插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现，从而减少启动时间。如果不使用它，`claude -p` 会加载与交互式会话相同的 [上下文](/docs/zh-CN/how-claude-code-works#the-context-window)，包括在工作目录或 `~/.claude` 中配置的任何内容。

42 42

43裸模式对于 CI 和脚本很有用，你需要在每台机器上获得相同的结果。队友的 `~/.claude` 中的 hook 或项目的 `.mcp.json` 中的 MCP 服务器不会运行，因为裸模式永远不会读取它们。你用 `--add-dir` 命名的目录是一个部分例外：裸模式从其 `.claude/skills/` 文件夹加载 skills，但仍然跳过其 `.claude/commands/` 和 `.claude/agents/` 文件夹。[来自其他目录的 Skills](/docs/zh-CN/skills#skills-from-additional-directories) 涵盖了加载和不加载的内容。43bare 模式适用于需要在每台机器上获得相同结果的 CI 和脚本。队友的 `~/.claude` 中的 hook 或项目的 `.mcp.json` 中的 MCP 服务器不会运行，因为 bare 模式从不读取它们。您用 `--add-dir` 指定的目录是一个部分例外：bare 模式会从其 `.claude/skills/` 文件夹加载 skill，但仍然跳过其 `.claude/commands/` 和 `.claude/agents/` 文件夹。[来自其他目录的 Skills](/docs/zh-CN/skills#skills-from-additional-directories) 介绍了哪些内容会加载、哪些不会加载。

44 44

45没有 `--bare`，`-p` 会话会运行项目的 `.claude/settings.json` 中的 hooks 并连接其 `.mcp.json` 中的服务器，即使在你从未信任的文件夹中也是如此。`-p` 会话不显示工作区信任对话框和每个服务器的批准提示。[在你信任文件夹之前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 涵盖了 `-p` 下每种类型的存储库内容以及如何将其排除在外。45如果不使用 `--bare`，`-p` 会话会运行项目的 `.claude/settings.json` 中的 hook 并连接其 `.mcp.json` 中的服务器，即使在您从未信任过的文件夹中也是如此。`-p` 会话不会显示工作区信任对话框，也不会显示逐个服务器的批准提示。[在您信任文件夹之前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 介绍了 `-p` 下每种仓库内容以及如何将其排除在外。

46 46

47此示例在裸模式下运行一次性摘要任务，并预先批准 Read 工具，以便调用完成而无需权限提示。运行前设置 `ANTHROPIC_API_KEY`，因为裸模式不使用你的订阅登录：47此示例在 bare 模式下运行一次性摘要任务，并预先批准 Read 工具，以便调用无需权限提示即可完成。运行前请设置 `ANTHROPIC_API_KEY`，因为 bare 模式不使用您的订阅登录：

48 48

49```bash theme={null}49```bash theme={null}

50claude --bare -p "Summarize README.md" --allowedTools "Read"50claude --bare -p "Summarize README.md" --allowedTools "Read"

51```51```

52 52

53在裸模式下，Claude Code 永远不会读取 OAuth 凭证或系统密钥链。对于 Anthropic API，在环境中设置 `ANTHROPIC_API_KEY`，使用在 [Claude Console](https://platform.claude.com) 中创建的密钥，或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 继续照常读取它们自己的提供商凭证。53在 bare 模式下，Claude Code 从不读取 OAuth 凭据或系统密钥链。对于 Anthropic API，请在环境中设置 `ANTHROPIC_API_KEY`（使用在 [Claude Console](https://platform.claude.com) 中创建的密钥），或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会继续照常读取各自的提供商凭据。

54 54

~~55在裸模式下，Claude 可以访问 Bash、文件读取和文件编辑工具。使用标志传递你需要的任何 context：~~55在 bare 模式下，Claude 可以使用 Bash、文件读取和文件编辑工具。请使用标志传递您需要的任何上下文：

56 56

~~57| 要加载 | 使用 |~~57| 要加载的内容 | 使用 |

58| - | - |58| - | - |

60| 设置 | `--settings <file-or-json>` |60| 设置 | `--settings <file-or-json>` |

61| MCP 服务器 | `--mcp-config <file-or-json>` |61| MCP 服务器 | `--mcp-config <file-or-json>` |

62| [自定义 Agent](/docs/zh-CN/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |62| [自定义 Agent](/docs/zh-CN/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |

~~63| 一个插件 | `--plugin-dir <path>`, `--plugin-url <url>` |~~63| 插件 | `--plugin-dir <path>`, `--plugin-url <url>` |

64 64

65bare 模式还会限制会话运行期间发生的事情：65bare 模式还会限制会话运行期间发生的事情：

66 66

84 84

85运行会等待后台工作，例如后台命令、子代理和工作流、Monitor 监视以及待处理的 `/loop` 唤醒：85运行会等待后台工作，例如后台命令、子代理和工作流、Monitor 监视以及待处理的 `/loop` 唤醒：

86 86

87* **[后台命令](/docs/zh-CN/tools-reference#background-commands)**：对于主对话启动的命令（例如开发服务器或监视构建），运行会等待，直到该命令退出或达到其 [时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。随后 Claude 会根据结果再进行一轮，该轮次的结果成为运行的最后结果，也就是 `text` 和 `json` 输出所打印的结果。在命令运行期间，10 分钟上限不会结束等待。87* **[后台命令](/docs/zh-CN/tools-reference#background-commands)**：对于主对话启动的命令（例如开发服务器或监视构建），运行会等待，直到该命令退出或达到其 [时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。随后 Claude 会根据结果再进行一轮。在命令运行期间，10 分钟上限不会结束等待。

88* **后台[子代理](/docs/zh-CN/sub-agents)和工作流**：运行会保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。88* **后台[子代理](/docs/zh-CN/sub-agents)和工作流**：运行会保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。

89* **[Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视**：运行会等待，直到监视超时或 10 分钟上限结束等待，以先发生者为准。在等待期间，Claude 会继续响应监视报告的内容。默认情况下，监视在 Claude 启动后五分钟超时。89* **[Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视**：运行会等待，直到监视超时或 10 分钟上限结束等待，以先发生者为准。在等待期间，Claude 会继续响应监视报告的内容。默认情况下，监视在 Claude 启动后五分钟超时。

90* **待处理的唤醒**：在以文本形式而非通过 `--input-format stream-json` 传递提示词的运行中，如果 Claude 已安排 [自定节奏的 `/loop` 唤醒](/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval)，运行会等待每次唤醒触发并执行其迭代，直到 [循环结束](/docs/zh-CN/scheduled-tasks#stop-a-loop)，即使超过 10 分钟上限也是如此。90* **待处理的唤醒**：在以文本形式而非通过 `--input-format stream-json` 传递提示词的运行中，如果 Claude 已安排 [自定节奏的 `/loop` 唤醒](/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval)，运行会等待每次唤醒触发并执行其迭代，直到 [循环结束](/docs/zh-CN/scheduled-tasks#stop-a-loop)，即使超过 10 分钟上限也是如此。

91 91

92如果运行达到其 [`--max-budget-usd`](/docs/zh-CN/cli-reference#cli-flags) 上限，Claude Code 会停止剩余的后台工作，而不是继续等待。92如果运行达到其 [`--max-budget-usd`](/docs/zh-CN/cli-reference#cli-flags) 上限，Claude Code 会停止剩余的后台工作，而不是继续等待。

93 93

94当后台工作启动新的轮次时，使用默认的 `text` 输出时运行会打印每一轮的结果，使用 `json` 输出时则打印最后一轮的结果。在 v2.1.295 之前，使用 `text` 输出时运行也只打印最后一轮的结果。

94<h3 id="stop-a-run-with-sigterm">96<h3 id="stop-a-run-with-sigterm">

95 使用 SIGTERM 停止运行97 使用 SIGTERM 停止运行

96</h3>98</h3>

97 99

98如果你使用 SIGTERM 停止 `claude -p` 运行，例如使用 `kill` 或从进程监督程序，Claude Code 以代码 143 退出。Claude Code 将正在进行的转向保持未完成状态，并且不为其记录任何结果。要改为结束转向，请发送 SIGINT，或在停止进程之前调用 Agent SDK 的 `interrupt()`。100如果您使用 SIGTERM 停止 `claude -p` 运行（例如使用 `kill` 或通过进程监督程序），Claude Code 会以代码 143 退出。Claude Code 会让正在进行的轮次保持未完成状态，并且不为其记录任何结果。如果要结束该轮次，请在停止进程之前发送 SIGINT，或调用 Agent SDK 的 `interrupt()`。

99 101

100在 SIGTERM 上，Claude Code 终止仍在运行的任何 Bash 命令的进程树。Claude Code 然后运行 [`SessionEnd` hooks](/docs/zh-CN/hooks#sessionend) 并退出。退出时，Claude Code 不启动新的工具调用，不发送新的模型请求，也不运行除 `SessionEnd` 之外的任何 hook。如果运行在信号到达时处于命令中间或等待权限提示的答案，Claude Code 按如下方式处理该步骤：102收到 SIGTERM 时，Claude Code 会终止仍在运行的任何 Bash 命令的进程树。然后 Claude Code 运行 [`SessionEnd` hook](/docs/zh-CN/hooks#sessionend) 并退出。在退出过程中，Claude Code 不会启动新的工具调用，不会发送新的模型请求，也不会运行除 `SessionEnd` 之外的任何 hook。如果信号到达时运行正在执行命令或等待权限提示，Claude Code 会按如下方式处理该步骤：

101 103

102* **运行命令**：Claude Code 在会话中将命令记录为已杀死。104* **正在运行命令**：Claude Code 会在会话中将该命令记录为已终止。

103* **等待权限提示的答案**：如果你向进程发送 SIGTERM，Claude Code 会将提示保持未回答状态。如果你的程序通过 Agent SDK 关闭会话，SDK 会在发送任何信号之前结束 Claude Code 的输入，Claude Code 会在输入结束后立即取消提示。105* **正在等待权限提示的答复**：如果您向进程发送 SIGTERM，Claude Code 会让该提示保持未答复状态。如果您的程序通过 Agent SDK 关闭会话，SDK 会在发送任何信号之前结束 Claude Code 的输入，而 Claude Code 会在输入结束后立即取消该提示。

104 106

105当你 [恢复会话](#continue-conversations) 时，Claude Code 将中断的转向保持原样，你的下一个提示驱动对话。要让 Claude Code 在恢复时继续中断的转向，请设置 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/zh-CN/env-vars)。107当您 [恢复会话](#continue-conversations) 时，Claude Code 会保留被中断的轮次原样，由您的下一个提示词推动对话。如果希望 Claude Code 在恢复时继续被中断的轮次，请设置 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/zh-CN/env-vars)。

106 108

107<h3 id="if-the-working-directory-is-deleted">109<h3 id="if-the-working-directory-is-deleted">

108 如果工作目录被删除110 如果工作目录被删除

109</h3>111</h3>

110 112

111如果 `claude -p` 或 Agent SDK 会话的工作目录在会话中间被删除，会话继续运行。当转向在目录缺失时启动时，Claude Code 在 `stream-json` 输出中发出 [警告消息](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)，shell 命令失败，直到目录再次存在。113如果 `claude -p` 或 Agent SDK 会话的工作目录在会话进行中被删除，会话会继续运行。当某个轮次在目录缺失时开始，Claude Code 会在 `stream-json` 输出中发出 [警告消息](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)，并且 shell 命令会失败，直到该目录重新存在。

112 114

113<h2 id="examples">115<h2 id="examples">

114 示例116 示例

264| `attempt` | 整数 | 当前尝试次数，从 1 开始 |266| `attempt` | 整数 | 当前尝试次数，从 1 开始 |

265| `max_retries` | 整数 | 允许的总重试次数，对于此失败的原因可能少于会话范围的预算 |267| `max_retries` | 整数 | 针对此失败原因允许的总重试次数 |

266| `retry_delay_ms` | 整数 | 毫秒直到下一次尝试 |268| `retry_delay_ms` | 整数 | 毫秒直到下一次尝试 |

268| `no_response` | 对象，可选 | 仅当失败的尝试 [及时没有获得响应头](/docs/zh-CN/errors#no-response-from-api) 时存在。`waited_ms` 是该尝试等待的时间，`retry_wait_ms` 是重试将等待的时间。在这些事件中，`max_retries` 反映此原因通常获得的一次重试，而不是会话范围的预算。需要 Claude Code v2.1.261 或更高版本 |270| `no_response` | 对象，可选 | 仅当失败的尝试 [未及时获得响应头](/docs/zh-CN/errors#no-response-from-api) 时存在。`waited_ms` 是该尝试等待的时间，`retry_wait_ms` 是重试将等待的时间。需要 Claude Code v2.1.261 或更高版本 |

269| `error` | 字符串 | 错误类别：`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`rate_limit`、`overloaded`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |271| `error` | 字符串 | 错误类别：`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`rate_limit`、`overloaded`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |

270| `uuid` | 字符串 | 唯一事件标识符 |272| `uuid` | 字符串 | 唯一事件标识符 |

271| `session_id` | 字符串 | 事件所属的会话 |273| `session_id` | 字符串 | 事件所属的会话 |

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 安全考虑

interactive-mode.md +12 −11

Details

216| `^` | 第一个非空白字符 |216| `^` | 第一个非空白字符 |

217| `gg` | 输入开始 |217| `gg` | 输入开始 |

218| `G` | 最后一行的行首 |218| `G` | 最后一行的行首 |

219| `f{char}` | 跳转到下一个字符出现位置 |219| `f{char}` | 跳转到当前行中该字符的下一个出现位置 |

220| `F{char}` | 跳转到上一个字符出现位置 |220| `F{char}` | 跳转到当前行中该字符的上一个出现位置 |

221| `t{char}` | 跳转到下一个字符出现位置之前 |221| `t{char}` | 跳转到当前行中该字符的下一个出现位置之前 |

222| `T{char}` | 跳转到上一个字符出现位置之后 |222| `T{char}` | 跳转到当前行中该字符的上一个出现位置之后 |

223| `;` | 重复上一个 f/F/t/T 动作 |223| `;` | 重复上一个 f/F/t/T 动作 |

224| `,` | 反向重复上一个 f/F/t/T 动作 |224| `,` | 反向重复上一个 f/F/t/T 动作 |

225| `/` | 打开反向历史搜索，与 `Ctrl+R` 相同。空搜索提示显示提示：按 `Esc` 然后 `i` 然后 `/` 来打开命令菜单 |225| `/` | 打开反向历史搜索，与 `Ctrl+R` 相同。空搜索提示显示提示：按 `Esc` 然后 `i` 然后 `/` 来打开命令菜单 |

239| `dd` | 删除行 |239| `dd` | 删除行 |

240| `D` | 删除到行尾 |240| `D` | 删除到行尾 |

242| `df{char}`/`dt{char}` | 删除到并包括，或删除到下一个字符出现位置 |242| `df{char}`/`dt{char}` | 删除到当前行中该字符的下一个出现位置（包括或不包括该字符） |

245| `d0`/`c0`/`y0` | 从光标删除、更改或复制回行首。需要 Claude Code v2.1.281 或更高版本 |245| `d0`/`c0`/`y0` | 从光标删除、更改或复制回行首。需要 Claude Code v2.1.281 或更高版本 |

852 问题参考链接852 问题参考链接

853</h2>853</h2>

854 854

855当 Claude 提到一个问题为 `owner/repo#123` 时，只要你的终端支持超链接，你就可以点击该参考来打开它。如果 Claude Code 没有检测到你的终端支持超链接，请设置 [`FORCE_HYPERLINK`](/docs/zh-CN/env-vars) 为 `1` 来打开链接，或设置为 `0` 来保持参考为纯文本。855当 Claude 以 `owner/repo#123` 的形式提到一个问题时，只要您的终端支持超链接，您就可以点击该参考来打开它。如果 Claude Code 没有检测到您的终端支持超链接，请将 [`FORCE_HYPERLINK`](/docs/zh-CN/env-vars) 设置为 `1` 来启用链接，或设置为 `0` 来保持参考为纯文本。

856 856

857你只能获得两部分 `owner/repo#123` 形式的链接。这些保持为纯文本：857只有两部分的 `owner/repo#123` 形式才会生成链接。以下情况保持为纯文本：

858 858

859* 一个单独的 `#123`859* 单独的 `#123`

860* 一个嵌套的 GitLab 路径，例如 `group/subgroup/project#123`860* 嵌套的 GitLab 路径，例如 `group/subgroup/project#123`

861* 代码跨度或代码块内的任何参考861* 代码跨度或代码块内的任何参考

862* 长度超过约 1,000 行或 100,000 个字符的回复中的任何参考

862 863

863Claude Code 根据它从你的 git remote 识别的仓库主机来构建链接，而不是根据参考命名的仓库：864Claude Code 根据它从您的 git remote 识别出的仓库主机来构建链接，而不是根据参考所指定的仓库：

864 865

866| :- | :- |867| :- | :- |

mcp.md +1 −1

Details

367 367

368在 v2 上，Claude Code 还会：368在 v2 上，Claude Code 还会：

369 369

370* 询问 HTTP 和 stdio 服务器是否支持较新的修订版，并与支持的服务器一起使用它。在获取功能标志的会话中，它还会询问 claude.ai 连接器服务器。它与 v1 一样连接到其他所有服务器。370* 询问 HTTP、stdio 和 claude.ai 连接器服务器是否支持较新的修订版，并与支持的服务器一起使用它。它与 v1 一样连接到其他所有服务器。

371* 通过 [它保持打开的流](#notification-streams-on-the-v2-runtime) 从使用较新修订版的服务器接收 `list_changed` 通知。371* 通过 [它保持打开的流](#notification-streams-on-the-v2-runtime) 从使用较新修订版的服务器接收 `list_changed` 通知。

372* 不注册在较新修订版上连接的 [频道](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。372* 不注册在较新修订版上连接的 [频道](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。

373* 当授权响应指明意外的发行者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers) 失败。373* 当授权响应指明意外的发行者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers) 失败。

monitoring-usage.md +9 −3

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事件另外包括以下属性。这些永远不会附加到指标，因为它们会导致无限的基数：

917* `error`：错误消息921* `error`：错误消息

918* `status_code`：HTTP 状态代码作为数字。对于非 HTTP 错误（如连接失败）不存在。922* `status_code`：HTTP 状态代码作为数字。对于非 HTTP 错误（如连接失败）不存在。

919* `duration_ms`：请求持续时间（以毫秒为单位）923* `duration_ms`：请求持续时间（以毫秒为单位）

920* `attempt`：进行的总尝试次数，包括初始请求（`1` 表示没有重试发生）924* `attempt`：已进行的尝试次数，包括初始请求。[检测重试耗尽](#detect-retry-exhaustion)说明了计数何时重新开始

921* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。925* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。

922* `client_request_id`：作为 `x-client-request-id` 请求头发送的客户端生成的 UUID。即使在超时或连接错误等失败从未产生服务器 `request_id` 时也可用；请参阅[事件关联属性](#event-correlation-attributes)表了解何时存在。需要 Claude Code v2.1.214 或更高版本926* `client_request_id`：作为 `x-client-request-id` 请求头发送的客户端生成的 UUID。即使在超时或连接错误等失败从未产生服务器 `request_id` 时也可用；请参阅[事件关联属性](#event-correlation-attributes)表了解何时存在。需要 Claude Code v2.1.214 或更高版本

923* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否活跃927* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否活跃

1528 1541

1529Claude Code 在内部重试失败的 API 请求，仅在放弃后才发出单个 `claude_code.api_error` 事件，因此事件本身是该请求的终端信号。中间重试尝试不会作为单独的事件记录。1542Claude Code 在内部重试失败的 API 请求，仅在放弃后才发出单个 `claude_code.api_error` 事件，因此事件本身是该请求的终端信号。中间重试尝试不会作为单独的事件记录。

1530 1543

1531事件上的 `attempt` 属性记录进行的总尝试次数。`CLAUDE_CODE_MAX_RETRIES` 默认为 10，上限为 15。在 v2.1.199 或更高版本上，您可以设置 `CLAUDE_CODE_RETRY_WATCHDOG` 来提高默认值并移除上限。1544事件上的 `attempt` 属性记录尝试次数。`CLAUDE_CODE_MAX_RETRIES` 默认为 10，上限为 15。在 v2.1.199 或更高版本上，您可以设置 `CLAUDE_CODE_RETRY_WATCHDOG` 来提高默认值并移除上限。

1545

1546当请求在瞬时错误上耗尽所有重试时，`attempt` 最多等于该有效限制加一：默认为 11。

1532 1547

1533当请求在瞬时错误上耗尽所有重试时，`attempt` 等于该有效限制加一：默认为 11，除非设置了看门狗，否则永远不超过 16。较低的值表示不可重试的错误，例如 `400` 响应，或具有自己较小重试预算的原因。例如，Claude Code 最多重试两次加载 AWS 或 Google Cloud 凭证的失败。1548较低的值仍可能表示重试已耗尽：每次 Claude Code 在流式传输失败后重新发出请求时，`attempt` 都会从 `1` 重新开始计数。

1534 1549

1535要区分从一个恢复的会话与停滞的会话，按 `session.id` 分组事件，并检查错误后是否存在更晚的 `api_request` 事件。1550要区分从一个恢复的会话与停滞的会话，按 `session.id` 分组事件，并检查错误后是否存在更晚的 `api_request` 事件。

1536 1551

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/manifest-reference.md +1 −1

Details

185| 将 `official` 放在 `claude` 或 `anthropic` 旁边，例如 `official-claude-tools` | 错误 |185| 将 `official` 放在 `claude` 或 `anthropic` 旁边，例如 `official-claude-tools` | 错误 |

186| 在其他任何地方有 `claude`、`anthropic` 或 `anthropics` 作为整个单词，例如 `mcp-for-claude` | 警告 |186| 在其他任何地方有 `claude`、`anthropic` 或 `anthropics` 作为整个单词，例如 `mcp-for-claude` | 警告 |

187 187

188错误读作 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`，警告读作 `Plugin name "<name>" reads as one of Anthropic's own`。`claude plugin init` 和 `claude plugin tag` 拒绝引发错误的名称。仅这些命令检查名称。Claude Code 仍然安装和加载其名称被拒绝的 plugin。188错误读作 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`，警告读作 `Plugin name "<name>" reads as one of Anthropic's own`。`claude plugin init` 和 `claude plugin tag` 拒绝引发错误的名称。Claude Code 仍然安装和加载其名称被拒绝的插件。

189 189

190<h3 id="displayname">190<h3 id="displayname">

191 `displayName`191 `displayName`

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 +20 −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

812 812

813如果您的组织为您预安装插件，它通过托管设置而不是这样做。请参阅 [预安装和要求插件](/docs/zh-CN/plugins/org#pre-install-and-require-plugins)。813如果您的组织为您预安装插件，它通过托管设置而不是这样做。请参阅 [预安装和要求插件](/docs/zh-CN/plugins/org#pre-install-and-require-plugins)。

814 814

815<h3 id="a-plugin-stays-installed-after-plugin-uninstall-on-windows">

816 在 Windows 上执行 `plugin uninstall` 后插件仍保持安装

817</h3>

818

819在 Windows 上，您在项目或本地作用域运行 `claude plugin uninstall` 并报告成功，但 `claude plugin list` 或 `/plugin` 仍然列出该插件。

820

821`installed_plugins.json` 为该项目文件夹保存了该插件的两条安装记录，每条记录对文件夹路径的写法不同，而一次卸载只会删除其中一条。要进行检查，请在您的 shell 中运行 `claude plugin list --json`。该插件剩余的行中，`projectPath` 对文件夹的写法与您运行卸载的位置不同，例如 `C:\work\app` 被写为 `c:\work\app`。

822

823在同一文件夹中，使用相同的 `--scope` 再次运行相同的卸载命令。第二次运行在其自身的路径写法下找不到记录，因此会删除另一种写法下的记录。对于项目作用域的安装：

824

825```shell theme={null}

826claude plugin uninstall <name>@<marketplace> --scope project

827```

828

829然后再次运行 `claude plugin list --json`，确认该行已消失。

830

831在 v2.1.295 之前，第二次运行会失败并显示 `Plugin "<name>" is not installed in project scope`。请运行 `claude update`，然后再次运行卸载。

832

815<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">833<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">

816 `Failed to load hooks from <path>` 和不触发的 hooks834 `Failed to load hooks from <path>` 和不触发的 hooks

817</h3>835</h3>

scheduled-tasks.md +21 −4

Details

191 抖动191 抖动

192</h3>192</h3>

193 193

194为了避免每个会话在同一个挂钟时刻击中 API，调度程序会向触发时间添加一个确定性偏移：194定时任务的实际运行时间可能与其计划时间不同。如果每个会话的任务都严格按计划运行，许多任务会在同一时刻调用 API，因此 Claude Code 会调整每个任务的运行时间。重复任务会延后运行，而安排在整点或半点的一次性任务会稍微提前运行。

195 195

196* 重复任务最多在计划时间之后 30 分钟触发（或对于运行频率超过每小时的任务，最多为间隔的一半）。为 `:00` 计划的每小时作业可能在 `:00` 到 `:30` 之间的任何时间触发。196<h4 id="how-late-a-recurring-task-runs">

197* 为小时顶部或底部计划的一次性任务最多提前 90 秒触发。197 重复任务会延后多久运行

198</h4>

198 199

199偏移是从任务 ID 派生的，所以相同的任务总是获得相同的偏移。如果精确的时间很重要，选择不是 `:00` 或 `:30` 的分钟，例如 `3 9 * * *` 而不是 `0 9 * * *`，一次性抖动将不适用。200当您创建重复任务时，Claude Code 会为其分配一个固定的延迟，并将该延迟添加到每次运行中。该延迟是根据任务 ID 计算得出的，因此同一任务每次都会延后相同的分钟数运行，包括在会话空闲且没有其他任何内容运行时。

201

202运行越频繁的任务获得的延迟越短，任务可获得的最长延迟为 30 分钟。以下是一些常见计划的延迟范围：

203

204| 任务运行频率 | 延迟范围 |

205| :- | :- |

206| 每 10 分钟 | 0 到 5 分钟 |

207| 每 30 分钟 | 0 到 15 分钟 |

208| 每小时，或频率更低（例如每天） | 0 到 30 分钟 |

209

210例如，`7,37 * * * *` 将任务安排在 `:07` 和 `:37` 运行，两者相隔 30 分钟，因此其延迟介于 0 到 15 分钟之间。如果该任务的延迟为 14 分钟，它会在每小时的 `:21` 和 `:51` 运行。将计划更改为其他分钟会改变运行时间，但仍会在其基础上添加延迟。

211

212<h4 id="when-a-one-shot-task-runs-early">

213 一次性任务何时提前运行

214</h4>

215

216安排在 `:00` 或 `:30` 的一次性任务最多会提前 90 秒运行。Claude Code 不会调整安排在其他任何分钟的一次性任务，因此当时间很重要时，请避开整点和半点进行安排：使用 `3 9 * * *` 而不是 `0 9 * * *`。

200 217

201<h3 id="seven-day-expiry">218<h3 id="seven-day-expiry">

202 七天过期219 七天过期

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 +4 −2

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

640Implement API endpoints. Follow the conventions and patterns from the preloaded skills.642Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

641```643```

642 644

643每个列出的技能的完整内容被注入到 subagent 的上下文中。此字段控制哪些技能被预加载，而不是 subagent 可以访问哪些技能：没有它，subagent 仍然可以在执行期间通过 Skill 工具发现和调用项目、用户和 plugin 技能。要防止 subagent 完全调用技能，请从 [`tools`](#available-tools) 列表中省略 `Skill` 或将其添加到 `disallowedTools`。645每个列出的 skill 的完整内容会在启动时注入到子代理的上下文中，最多为列表中前 32 个不同的名称。此字段控制预加载哪些 skill，而不是子代理可以访问哪些 skill：即使没有此字段，子代理仍然可以在执行期间通过 Skill 工具发现和调用项目、用户和插件 skill。要完全阻止子代理调用 skill，请从 [`tools`](#available-tools) 列表中省略 `Skill`，或将其添加到 `disallowedTools`。

644 646

645您无法预加载设置了 [`disable-model-invocation: true`](/docs/zh-CN/skills#control-who-invokes-a-skill) 的 skill，因为预加载的来源与 Claude 可以调用的 skill 集合相同。这包括内置的 `/verify` skill，Claude 无法自行运行它。647您无法预加载设置了 [`disable-model-invocation: true`](/docs/zh-CN/skills#control-who-invokes-a-skill) 的 skill，因为预加载的来源与 Claude 可以调用的 skill 集合相同。这包括内置的 `/verify` skill，Claude 无法自行运行它。

646 648

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 19:00 UTC