Documentation — Spybara

agent-sdk/file-checkpointing.md +22 −11

Details

14 14

15## Checkpointing 如何工作15## Checkpointing 如何工作

16 16

17启用文件 checkpointing 时，SDK 会在通过 Write、Edit 或 NotebookEdit 工具修改文件之前创建文件备份。响应流中的用户消息包含一个 checkpoint UUID，您可以将其用作恢复点。17启用文件检查点功能时，SDK 会在通过 Write、Edit 或 NotebookEdit 工具修改文件之前创建文件备份。每个开启一个轮次的提示词都是一个检查点，其用户消息的 UUID 即为恢复点。

18 18

19> [!NOTE]19> [!NOTE]

20>20>

147 147

148**2. 捕获checkpoint UUID和会话ID**148**2. 捕获checkpoint UUID和会话ID**

149 149

150设置`replay-user-messages`选项后，响应流中的每个用户消息都有一个UUID，用作checkpoint。150设置`replay-user-messages`选项后，每个开启一个轮次的提示词所对应的用户消息都有一个 UUID，用作检查点。携带工具结果的用户消息也有 UUID，但它不是检查点。

151 151

152对于大多数用例，捕获第一个用户消息UUID（`message.uuid`）；回滚到它会将已跟踪文件恢复到原始状态。要存储多个checkpoint并回滚到中间状态，请参阅[多个恢复点](#multiple-restore-points)。152对于大多数用例，捕获第一个用户消息UUID（`message.uuid`）；回滚到它会将已跟踪文件恢复到原始状态。要存储多个checkpoint并回滚到中间状态，请参阅[多个恢复点](#multiple-restore-points)。

153 153

171 171

172### 在危险操作之前创建checkpoint172### 在危险操作之前创建checkpoint

173 173

174此模式仅保留最新的checkpoint UUID，在每个agent轮次之前更新它。如果处理过程中出现问题，您可以立即回滚到最后的安全状态并跳出循环。174此模式仅保留最新的检查点 UUID，在每个开启一个轮次的提示词处更新它。如果处理过程中出现问题，您可以立即回滚到最后的安全状态并跳出循环。

175 175

176运行此示例之前，请将`your_revert_condition`（Python）或`yourRevertCondition`（TypeScript）替换为您自己的检查，例如错误检测或验证失败；该占位符在示例中未定义。176运行此示例之前，请将`your_revert_condition`（Python）或`yourRevertCondition`（TypeScript）替换为您自己的检查，例如错误检测或验证失败；该占位符在示例中未定义。

177 177

193 await client.query("Refactor the authentication module")193 await client.query("Refactor the authentication module")

194 194

195 async for message in client.receive_response():195 async for message in client.receive_response():

196 # Update checkpoint before each agent turn starts196 # Update checkpoint at each prompt you send; a tool result isn't one

197 # This overwrites the previous checkpoint. Only keep the latest197 # This overwrites the previous checkpoint. Only keep the latest

198 if isinstance(message, UserMessage) and message.uuid:198 if (

199 isinstance(message, UserMessage)

200 and message.uuid

201 and message.tool_use_result is None

202 and message.parent_tool_use_id is None

203 ):

199 safe_checkpoint = message.uuid204 safe_checkpoint = message.uuid

200 205

201 # Decide when to revert based on your own logic206 # Decide when to revert based on your own logic

225 let safeCheckpoint: string | undefined;230 let safeCheckpoint: string | undefined;

226 231

227 for await (const message of response) {232 for await (const message of response) {

228 // Update checkpoint before each agent turn starts233 // Update checkpoint at each prompt you send; a tool result isn't one

229 // This overwrites the previous checkpoint. Only keep the latest234 // This overwrites the previous checkpoint. Only keep the latest

230 if (message.type === "user" && message.uuid) {235 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

231 safeCheckpoint = message.uuid;236 safeCheckpoint = message.uuid;

232 }237 }

233 238

246 251

247### 多个恢复点252### 多个恢复点

248 253

249如果Claude在多个轮次中进行更改，您可能想回滚到特定点而不是一直回滚。例如，如果Claude在第一轮重构文件，在第二轮添加测试，您可能想保留重构但撤销测试。254如果 Claude 在多个提示词中进行了更改，您可能想回滚到特定点而不是一直回滚到最初。例如，如果您的第一个提示词重构了一个文件，第二个提示词添加了测试，则可以回滚到第二个提示词的检查点，以保留重构并撤销测试。

250 255

251此模式将所有checkpoint UUID存储在带有元数据的数组中。会话完成后，您可以回滚到任何之前的checkpoint：256此模式将每个检查点 UUID 存储在带有元数据的数组中。会话完成后，您可以回滚到任何之前的检查点：

252 257

253```python Python theme={null}258```python Python theme={null}

254import asyncio259import asyncio

284 await client.query("Refactor the authentication module")289 await client.query("Refactor the authentication module")

285 290

286 async for message in client.receive_response():291 async for message in client.receive_response():

287 if isinstance(message, UserMessage) and message.uuid:292 if (

293 isinstance(message, UserMessage)

294 and message.uuid

295 and message.tool_use_result is None

296 and message.parent_tool_use_id is None

297 ):

288 checkpoints.append(298 checkpoints.append(

289 Checkpoint(299 Checkpoint(

290 id=message.uuid,300 id=message.uuid,

338 348

339 try {349 try {

340 for await (const message of response) {350 for await (const message of response) {

341 if (message.type === "user" && message.uuid) {351 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

342 checkpoints.push({352 checkpoints.push({

343 id: message.uuid,353 id: message.uuid,

344 description: `After turn ${checkpoints.length + 1}`,354 description: `After turn ${checkpoints.length + 1}`,

638 648

639* 文件checkpointing在原始会话上未启用（`enable_file_checkpointing`或`enableFileCheckpointing`未设置为`true`）649* 文件checkpointing在原始会话上未启用（`enable_file_checkpointing`或`enableFileCheckpointing`未设置为`true`）

640* 会话在尝试恢复和回滚之前未正确完成650* 会话在尝试恢复和回滚之前未正确完成

651* 该UUID来自携带工具结果的用户消息，而此类消息不是检查点

641 652

642**解决方案**：确保在原始会话上设置了`enable_file_checkpointing=True`（Python）或`enableFileCheckpointing: true`（TypeScript），然后使用示例中显示的模式：捕获第一个用户消息UUID，完全完成会话，然后使用空提示恢复并调用`rewindFiles()`一次。653**解决方案**：确保在原始会话上设置了`enable_file_checkpointing=True`（Python）或`enableFileCheckpointing: true`（TypeScript），然后使用示例中显示的模式：捕获第一个用户消息UUID，完全完成会话，然后使用空提示恢复并调用`rewindFiles()`一次。

643 654

agent-sdk/modifying-system-prompts.md +1 −1

Details

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

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

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

501| **自定义级别** | 仅添加 | 添加；可省略编码指令 | 仅添加 | 完全控制 |501| **自定义级别** | 仅添加 | 添加；可省略编码指令 | 仅添加 | 完全控制 |

agent-sdk/python.md +1 −1

Details

875| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具，但从[网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)进行的读取除外。这不会限制 Claude 仅使用这些工具。如果您在此处列出[任务跟踪工具](https://code.claude.com/docs/zh-CN/agent-sdk/todo-tracking.md#model-availability)之一，Claude Code 也会为该会话启用它们。其他未列出的工具会交由 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#allow-and-deny-rules) |875| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具，但从[网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)进行的读取除外。这不会限制 Claude 仅使用这些工具。如果您在此处列出[任务跟踪工具](https://code.claude.com/docs/zh-CN/agent-sdk/todo-tracking.md#model-availability)之一，Claude Code 也会为该会话启用它们。其他未列出的工具会交由 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#allow-and-deny-rules) |

876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系统提示词配置。传递字符串以使用自定义提示词，`{"type": "preset", "preset": "claude_code"}` 以使用 Claude Code 的系统提示词（带可选 `"append"`），`{"type": "custom", "prompt": "..."}` 以使用也可以设置 `"snapshot"` 的自定义提示词，或 `{"type": "file", "path": "..."}` 从磁盘加载大型提示词。见 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系统提示词配置。传递字符串以使用自定义提示词，`{"type": "preset", "preset": "claude_code"}` 以使用 Claude Code 的系统提示词（带可选 `"append"`），`{"type": "custom", "prompt": "..."}` 以使用也可以设置 `"snapshot"` 的自定义提示词，或 `{"type": "file", "path": "..."}` 从磁盘加载大型提示词。见 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |

877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |

878| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，仅使用在 `mcp_servers` 中传递的服务器，忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器和 [claude.ai 连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)。映射到 CLI `--strict-mcp-config` 标志 |878| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，使用在 `mcp_servers` 中传入的服务器，并忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器以及 [claude.ai 连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)。对应 CLI 的 `--strict-mcp-config` 标志 |

agent-sdk/quickstart.md +2 −0

Details

342 342

343要将 Agent 的内置工具限制为其中一组，请将该组作为 `tools` 传入。如果您改为在 `allowedTools` 中列出一组工具，则是[预先批准这些工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools.md#configure-allowed-tools)，Agent 仍可调用其他工具，但须遵循您的权限模式。

344

343**权限模式**控制你想要多少人工监督。SDK 按照固定的顺序评估活跃模式以及你的允许和拒绝规则，详见[权限如何被评估](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)。有关完整的模式列表、它们的行为以及何时使用每种模式，请参阅[代理循环工作原理中的权限模式](https://code.claude.com/docs/zh-CN/agent-sdk/agent-loop.md#permission-mode)。345**权限模式**控制你想要多少人工监督。SDK 按照固定的顺序评估活跃模式以及你的允许和拒绝规则，详见[权限如何被评估](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)。有关完整的模式列表、它们的行为以及何时使用每种模式，请参阅[代理循环工作原理中的权限模式](https://code.claude.com/docs/zh-CN/agent-sdk/agent-loop.md#permission-mode)。

344 346

345## 后续步骤347## 后续步骤

agent-sdk/subagents.md +1 −1

Details

149| `model` | `string` | 否 | 此代理的模型覆盖。接受别名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 或完整模型 ID。`'inherit'` 使用主模型。省略时，Claude Code 选择[子代理模型顺序](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)中的模型 |149| `model` | `string` | 否 | 此 Agent 的模型覆盖。接受别名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 或完整模型 ID。`'inherit'` 使用生成此 Agent 的那个 Agent 的模型。省略 `model` 时，Claude Code 选择[子代理模型顺序](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)中的模型 |

agent-sdk/typescript.md +2 −2

Details

589| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skill。传递 `'all'` 以启用所有发现的 skill，或传递 skill 名称列表。仅传递精确名称。在 Agent SDK v0.3.221 或更高版本中，SDK 会在启动 Claude Code 进程之前以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您同时传递了 `tools`，请在该列表中包含 `'Skill'`。请参阅 [Skills](https://code.claude.com/docs/zh-CN/agent-sdk/skills.md) |589| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skill。传递 `'all'` 以启用所有发现的 skill，或传递 skill 名称列表。仅传递精确名称。在 Agent SDK v0.3.221 或更高版本中，SDK 会在启动 Claude Code 进程之前以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您同时传递了 `tools`，请在该列表中包含 `'Skill'`。请参阅 [Skills](https://code.claude.com/docs/zh-CN/agent-sdk/skills.md) |

593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最简提示词） | 系统提示词配置。传递字符串以使用自定义提示词，或传递 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示词。传递字符串数组，并在静态部分与每请求部分之间放置导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量，即可[缓存自定义提示词的静态部分](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以附加额外指令进行扩展，并设置 `excludeDynamicSections: true` 将每会话上下文移到第一条用户消息中，以[在不同机器间更好地复用提示缓存](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 可在每次请求时重新构建提示词，而不是[复用会话在首次请求时记录的提示词](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)。要在自定义提示词上设置 `snapshot`，请使用 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最简提示词） | 系统提示词配置。传递字符串以使用自定义提示词，或传递 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示词。传递字符串数组，并在静态部分与每请求部分之间放置导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量，即可[缓存自定义提示词的静态部分](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以附加额外指令进行扩展，并设置 `excludeDynamicSections: true` 将每会话上下文移到第一条用户消息中，以[在不同机器间更好地复用提示缓存](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 可在每次请求时重新构建提示词，而不是[复用会话在首次请求时记录的提示词](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)。要在自定义提示词上设置 `snapshot`，请使用 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |

594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端的任务预算（以 token 计）。设置后，模型会被告知其剩余的 token 预算，以便控制工具使用节奏并在达到限制前收尾 |594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端的任务预算（以 token 计）。设置后，模型会被告知其剩余的 token 预算，以便控制工具使用节奏并在达到限制前收尾 |

595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 对支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。有关选项，请参阅 [`ThinkingConfig`](#thinkingconfig) |595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 对支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。有关选项，请参阅 [`ThinkingConfig`](#thinkingconfig) |

1285| `tools` | 否 | 允许的工具名称数组。如果省略，则继承所有[子代理可用的工具](https://code.claude.com/docs/zh-CN/sub-agents.md#available-tools)。要将 Skills 预加载到 Agent 的上下文中，请使用 `skills` 字段，而不是在此处列出 `'Skill'` |1285| `tools` | 否 | 允许的工具名称数组。如果省略，则继承所有[子代理可用的工具](https://code.claude.com/docs/zh-CN/sub-agents.md#available-tools)。要将 Skills 预加载到 Agent 的上下文中，请使用 `skills` 字段，而不是在此处列出 `'Skill'` |

1286| `disallowedTools` | 否 | 要为此 Agent 明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 会移除该服务器的所有工具，`mcp__*` 会移除任何服务器的所有 MCP 工具 |1286| `disallowedTools` | 否 | 要为此 Agent 明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 会移除该服务器的所有工具，`mcp__*` 会移除任何服务器的所有 MCP 工具 |

1287| `prompt` | 是 | Agent 的系统提示词 |1287| `prompt` | 是 | Agent 的系统提示词 |

1288| `model` | 否 | 此 Agent 的模型覆盖。接受 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 等别名，或完整的模型 ID。`'inherit'` 使用主模型。省略时，Claude Code 会按照[子代理模型顺序](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)选择模型 |1288| `model` | 否 | 此 Agent 的模型覆盖。接受别名（例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`）或完整的模型 ID。`'inherit'` 使用生成此 Agent 的 Agent 所用的模型。当您省略 `model` 时，Claude Code 会按照[子代理模型顺序](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)选择模型 |

1289| `mcpServers` | 否 | 此 Agent 的 MCP 服务器规范 |1289| `mcpServers` | 否 | 此 Agent 的 MCP 服务器规范 |

1290| `skills` | 否 | 要预加载到 Agent 上下文中的 skill 名称数组 |1290| `skills` | 否 | 要预加载到 Agent 上下文中的 skill 名称数组 |

1291| `initialPrompt` | 否 | 当此 Agent 作为主线程 Agent 运行时，作为第一轮用户输入自动提交 |1291| `initialPrompt` | 否 | 当此 Agent 作为主线程 Agent 运行时，作为第一轮用户输入自动提交 |

agent-teams.md +26 −9

Details

102>102>

103> `tmux` 在某些操作系统上存在已知限制，传统上在 macOS 上效果最佳。建议在 iTerm2 中使用 `tmux -CC` 作为进入 `tmux` 的方式。103> `tmux` 在某些操作系统上存在已知限制，传统上在 macOS 上效果最佳。建议在 iTerm2 中使用 `tmux -CC` 作为进入 `tmux` 的方式。

104 104

105默认值为 `"in-process"`。设置为 `"auto"` 时，如果您已在 tmux 会话中运行，或者您的终端是已安装 `it2` CLI 的 iTerm2，则启用分屏窗格，否则回退到进程内模式。`"tmux"` 设置会启用分屏窗格模式，并根据您的终端自动检测使用 tmux 还是 iTerm2。105在 agent team 已[启用](#enable-agent-teams)的情况下，按照以下步骤为每个队友分配独立的窗格：

106 106

107设置为 `"iterm2"` 可显式使用 iTerm2 原生分屏窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果缺少 `it2`，会显示错误并附带安装命令。当您的终端是 iTerm2 且 tmux 可作为回退选项时，在 `"auto"` 或 `"tmux"` 下会出现设置提示，询问是安装 `it2` 还是切换到 tmux。107**1. 安装 tmux 或设置 iTerm2**

108 108

109要覆盖默认值，请在 `~/.claude/settings.json` 中设置 [`teammateMode`](https://code.claude.com/docs/zh-CN/settings-reference#teammatemode)：109分屏窗格模式需要 [tmux](https://github.com/tmux/tmux/wiki)，或者安装了 [`it2` CLI](https://github.com/mkusaka/it2) 的 iTerm2。请设置您将在其中运行 Claude Code 的那一个：

110

111* **tmux**：通过系统的包管理器安装。有关特定平台的说明，请参阅 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)。

112* **iTerm2**：安装 [`it2` CLI](https://github.com/mkusaka/it2)，然后在 **iTerm2 > Settings > General > Magic > Enable Python API** 中启用 Python API。

113

114**2. 启用分屏窗格**

115

116在您更改 [`teammateMode`](https://code.claude.com/docs/zh-CN/settings-reference#teammatemode) 设置之前，队友都以进程内方式运行。

117

118在 `~/.claude/settings.json` 中将其设置为 `"auto"`：

110 119

111```json theme={null}120```json theme={null}

112{121{

114}123}

115```124```

116 125

126设置为 `"auto"` 时，如果您在 tmux 或 iTerm2 中运行 Claude Code，队友会在分屏窗格中打开；在其他终端中则以进程内方式运行。

127

128**3. 启动 Claude Code 并生成队友**

129

130在 tmux 或 iTerm2 中运行 `claude`，然后让 Claude 生成队友。

131

132如果 iTerm2 中出现 `it2` 的设置提示，请选择 **Install it2 now**，以便在您的 iTerm2 窗口中打开窗格。

133

134如果您在 tmux 和 iTerm2 之外运行 Claude Code，或者窗格没有在您的 iTerm2 窗口中打开，请再次更改 `teammateMode`：

135

136* **在 tmux 和 iTerm2 之外**：在已安装 tmux 的情况下，将 `teammateMode` 设置为 `"tmux"`。窗格会在单独的 tmux 会话中打开。要查看它们，请从 Claude Code 提示符处的 `View teammates` 行复制命令，并在第二个终端中运行该命令。

137* **窗格未在您的 iTerm2 窗口中打开**：将 `teammateMode` 设置为 `"iterm2"` 以使用 iTerm2 自身的窗格。这样，只有当您在已设置 `it2` 的 iTerm2 中运行 Claude Code 时，队友才会启动。

138

117要为单个会话设置模式，请将其作为标志传入：139要为单个会话设置模式，请将其作为标志传入：

118 140

119```bash theme={null}141```bash theme={null}

122 144

123`--teammate-mode` 标志是实验性的，不会出现在 `claude --help` 中。145`--teammate-mode` 标志是实验性的，不会出现在 `claude --help` 中。

124 146

125分屏窗格模式需要 [tmux](https://github.com/tmux/tmux/wiki)，或者安装了 [`it2` CLI](https://github.com/mkusaka/it2) 的 iTerm2。手动安装方法：

~~126~~

127* **tmux**：通过系统的包管理器安装。有关特定平台的说明，请参阅 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)。

128* **iTerm2**：安装 [`it2` CLI](https://github.com/mkusaka/it2)，然后在 **iTerm2 → Settings → General → Magic → Enable Python API** 中启用 Python API。

~~129~~

130### 指定队友和模型147### 指定队友和模型

131 148

132Claude 会根据您的任务决定生成的队友数量，您也可以准确指定您想要的内容：149Claude 会根据您的任务决定生成的队友数量，您也可以准确指定您想要的内容：

497* **没有来自 in-process 队友的后台子代理**：in-process 队友自己的子代理在前台运行，因为队友的后台工作无法超越负责人的进程。Claude Code 在队友生成定义设置 `background: true` 的子代理时返回错误。队友的 `run_in_background: true` 请求也会失败，要么返回错误，要么在前台静默运行。从主对话启动的子代理遵循[后台默认值](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。514* **没有来自 in-process 队友的后台子代理**：in-process 队友自己的子代理在前台运行，因为队友的后台工作无法超越负责人的进程。Claude Code 在队友生成定义设置 `background: true` 的子代理时返回错误。队友的 `run_in_background: true` 请求也会失败，要么返回错误，要么在前台静默运行。从主对话启动的子代理遵循[后台默认值](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。

498* **负责人是固定的**：主会话在其生命周期内是其团队的负责人。你无法将队友提升为负责人或转移领导权。515* **负责人是固定的**：主会话在其生命周期内是其团队的负责人。你无法将队友提升为负责人或转移领导权。

499* **生成时无法为每个队友设置权限模式**：队友以 [权限](#permissions) 下描述的权限模式启动。516* **生成时无法为每个队友设置权限模式**：队友以 [权限](#permissions) 下描述的权限模式启动。

500* **分割窗格需要 tmux 或 iTerm2**：默认 in-process 模式在任何终端中工作。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。517* **分割窗格需要 tmux 或 iTerm2**：默认 in-process 模式在任何终端中工作。

501 518

502## 后续步骤519## 后续步骤

503 520

agent-view.md +30 −39

Details

144| 形状 | 含义 |144| 形状 | 含义 |

145| :- | :- |145| :- | :- |

146| `✻` 或动画 `✽` | 会话进程正在运行，或会话需要您的输入 |146| `✻` 或动画 `✽` | 会话进程正在运行，或会话需要您的输入 |

147| `∙` | 进程已退出。您仍然可以窥视该行，当您回复或附加时，Claude 会根据其保存的对话重新启动它 |147| `∙` | 进程已退出。您仍然可以窥视该行，当您回复或按 `Enter` 时，Claude 会根据其保存的对话重新启动它 |

148| `✢` | 一个 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks) 会话正在迭代之间休眠。该行显示其运行次数和倒计时 |148| `✢` | 一个 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks) 会话正在迭代之间休眠。该行显示其运行次数和倒计时 |

149 149

150行右边缘可能出现的 `#N` 或 `!N` 标签是指向会话的[拉取请求或合并请求](#pull-request-status)的链接，不是状态图标的一部分。150行右边缘可能出现的 `#N` 或 `!N` 标签是指向会话的[拉取请求或合并请求](#pull-request-status)的链接，不是状态图标的一部分。

316* 在组标题上按 `Enter` 将其折叠，但[过滤器](#filter-sessions)处于活动状态时除外，此时所有组都保持展开316* 在组标题上按 `Enter` 将其折叠，但[过滤器](#filter-sessions)处于活动状态时除外，此时所有组都保持展开

317* 按 `Ctrl+X` 停止会话，并在两秒内再按一次 `Ctrl+X` 将其从列表中删除，或按 `Esc` 关闭确认而不删除。即使停止尝试失败（例如因为[后台服务没有响应](#agent-view-says-the-background-service-did-not-respond)），第二次按下也会删除会话。在这种情况下，确认状态会再保持两秒，删除操作会自行结束会话的进程317* 按 `Ctrl+X` 停止会话，并在两秒内再按一次 `Ctrl+X` 将其从列表中删除，或按 `Esc` 关闭确认而不删除。即使停止尝试失败（例如因为[后台服务没有响应](#agent-view-says-the-background-service-did-not-respond)），第二次按下也会删除会话。在这种情况下，确认状态会再保持两秒，删除操作会自行结束会话的进程

318 318

319在组标题上按 `Ctrl+X` 会在确认后删除该组中的所有会话。除了[删除会话会移除什么](#what-deleting-a-session-removes)中所述的保留情况外，删除会将会话从列表中移除。Claude 为其创建的 worktree 会被移除、保留或留在原处，具体取决于您的删除方式以及 worktree 中的内容。对话会话记录保留在您的本地机器上，可通过 `claude --resume` 访问。319在组标题上按 `Ctrl+X` 会在确认后删除该组中的所有会话，但 Claude Code [拒绝删除](#delete-a-session-after-claude-code-refuses)的会话除外。有关每个会话的 worktree 会如何处理，请参阅[删除会话会移除什么](#what-deleting-a-session-removes)。对话会话记录保留在您的本地机器上，可通过 `claude --resume` 访问。

320 320

321屏幕容纳不下的已完成会话会折叠成一行 `… N more`。`Completed` 组会填满活跃组之后剩余的垂直空间。在较矮的终端上，标题会压缩为单行摘要，以便正在工作或需要输入的会话保持可见。321屏幕容纳不下的已完成会话会折叠成一行 `… N more`。`Completed` 组会填满活跃组之后剩余的垂直空间。在较矮的终端上，标题会压缩为单行摘要，以便正在工作或需要输入的会话保持可见。

322 322

622 622

623#### 删除会话会移除什么623#### 删除会话会移除什么

624 624

625在 [Agent 视图](#organize-the-list) 中按两次 `Ctrl+X`，或使用 [`claude rm`](#manage-sessions-from-the-shell) 删除会话。除下述保留的情况外，会话会从列表中移除。其会话记录仍保留在您的机器上，可通过 `claude --resume` 访问，且该移除在主管进程重新启动后依然有效。625在 [Agent 视图](#organize-the-list) 中按两次 `Ctrl+X`，或使用 [`claude rm`](#manage-sessions-from-the-shell) 删除会话。会话会从列表中消失，除非 Claude Code [拒绝删除它](#delete-a-session-after-claude-code-refuses)。其会话记录仍保留在您的机器上，可通过 `claude --resume` 访问。

626 626

627Claude 为会话创建的 worktree 会如何处理：627Claude 为会话创建的 worktree 会如何处理：

628 628

629* Agent 视图会移除它，包括未提交的更改，因此请先提交您想保留的内容。629* Agent 视图会移除它，包括未提交的更改，因此请先提交您想保留的内容。

630* 当它有未提交的更改时，`claude rm` 会保留它以及会话行。630* 当它有未提交的更改时，`claude rm` 会保留它以及会话行。

631* Agent 视图和 `claude rm` 都不会移除另一个正在运行的会话正在使用或已锁定的 worktree，再次删除也不会改变这一点。Claude Code 会保留 worktree 和会话，并指明保留的目录及原因；在 Agent 视图中，该会话的行会显示 `not removed`。请关闭另一个会话，然后再次删除。

632* 当您删除的会话的 worktree 中有 Claude Code 无法确认已保存到其他位置的提交时，Claude Code 会保留 worktree 和会话，消息会指明 worktree 的分支以及有多少未推送的提交。消息还提供两种后续做法：推送这些提交，或再次删除以丢弃它们。

633 631

634 远程上的提交不会阻止删除。您的 `origin` 远程默认分支的本地副本上的提交也不会阻止删除，前提是该分支检出在您的主检出中（即仓库目录本身，而不是 worktree）。632Claude Code 拒绝删除会话的原因之一是 [其 worktree 中有未推送的提交](https://code.claude.com/docs/zh-CN/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。要保留这些提交，请在删除会话前推送它们。

635 633

636 在该拒绝之后，您可以选择：634无论您使用 Agent 视图还是 `claude rm`，某些 worktree 都会保留在磁盘上：

637 635

638 * 要保留这些提交，请推送它们，或将它们合并到该默认分支，然后再次删除会话。636* 如果您自己创建了 worktree 并在其中启动了会话，该 worktree 会保留在磁盘上，由您决定保留还是移除。

639 * 要丢弃它们，请不推送而直接再次删除会话：在 Agent 视图中该会话的行上按两次 `Ctrl+X`，或运行拒绝消息中打印的 `claude rm <id> --discard-unpushed` 命令。这会移除会话和 worktree 及其分支，丢弃未推送的提交和任何未提交的更改。637* 如果 Claude 在您的仓库内创建的 worktree 目录已不再有其 `.git` 文件，该目录会保留在磁盘上，由您自行移除。该 worktree 的分支会保留在仓库中，因此您会保留该分支上的提交。

640 638

641 当您再次删除时，Claude Code 只会丢弃拒绝消息中显示的内容：如果此后 worktree 又有了新的提交，Claude Code 会再次保留它并显示更新后的状态。639##### 在 Claude Code 拒绝后删除会话

642 640

643 当另一个已完成会话的记录也指向该 worktree 时，再次删除时它仍会被保留；请推送这些提交，然后再次删除。641当 Claude Code 因会话的 worktree 而拒绝删除该会话时，请按照其显示的消息操作。如果消息指出有未推送的提交，请参阅 [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/zh-CN/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。

644* git 已不再识别的 worktree（例如在执行 `git worktree prune` 之后）不会阻止删除。Claude Code 会删除会话，并将目录留在磁盘上。

645* 当 git 或您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-CN/hooks#worktreeremove) 未能移除 worktree 时，Claude Code 会保留 worktree 和会话，消息会指明原因。对于 hook，消息会说明它是如何结束的（例如 `exited 1`），并引用其 stderr 的开头部分。消息还会告诉您接下来执行以下哪项操作：

646 642

647 * 再次删除会话以强制移除目录：在 Agent 视图中该会话的行上按两次 `Ctrl+X`，或运行 `claude rm` 拒绝消息中打印的 `claude rm <id> --force-remove-worktree <worktree-id>` 命令。worktree 的分支会保留在仓库中。643##### 解决 `Worktree not removed` 消息

648 644

649 只有当 Claude Code 能确认以下所有条件时才会提供此选项：645`Worktree not removed` 消息表示 Claude Code 或您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-CN/hooks#worktreeremove) 未能完成移除会话的 worktree。请推送所有提交并复制出您想保留的任何文件，然后按照消息操作。

650 646

651 * 该目录是仓库在 `.claude/worktrees/` 下的链接 worktree 之一647##### 解决 `files that weren't checked against a repository` 消息

652 * worktree 及其已检出的子模块都没有对已跟踪文件的未提交更改

653 * 没有其他会话的记录指向它

654 648

655 当 Claude Code 无法验证子模块检出的状态时（例如该子模块被一个单独的 git 仓库替换），也不会提供此选项。649`claude rm` 显示的这条消息表示，某个不在任何 git 仓库内、或由 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/hooks#worktreecreate) 管理的 worktree 目录中仍有文件。请复制出您想保留的任何文件，然后根据您的情况执行相应步骤：

656 * 解决阻碍因素，例如提交或储藏未提交的更改、将单独的 git 仓库移出 worktree、关闭正在使用该目录的程序或修复 hook，然后再次删除会话。

657 * 自行移除该目录，然后再次删除会话。

658 650

659您自己创建并在其中启动会话的 worktree 在任何情况下都会保留。651| 您的情况 | 操作方法 |

~~660~~ 652| :- | :- |

661如果会话的 worktree 目录不属于任何 git 仓库（因为仓库已被删除，或 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/hooks#worktreecreate) 在其他位置创建了该目录），该会话仍然可以删除。当目录中仍有文件时：653| 没有 `WorktreeCreate` hook 管理该目录 | 要丢弃这些文件，请在 Agent 视图中该会话的行上按两次 `Ctrl+X`。或者自行移除该目录，然后再次运行 `claude rm <id>` |

~~662~~ 654| 有 `WorktreeCreate` hook 管理该目录，且您有 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-CN/hooks#worktreeremove) | 要尝试使用您的 hook 移除该目录，请在 Agent 视图中该会话的行上按两次 `Ctrl+X`。或者自行移除该目录，然后再次运行 `claude rm <id>` |

663* Agent 视图在丢弃这些文件前会要求同样按两次 `Ctrl+X`。对于由 hook 创建的目录，它会改为运行您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-CN/hooks#worktreeremove)；如果没有该 hook，它会拒绝删除并保留会话。655| 有 `WorktreeCreate` hook 管理该目录，且您没有 `WorktreeRemove` hook | 自行移除该目录，然后再次运行 `claude rm <id>` |

664* `claude rm` 会保留会话和 worktree，并指明原因。

~~665~~

666两种方式都会保留另一个已完成会话的记录所指向的目录。

667 656

668### 设置模型、effort 和快速模式657### 设置模型、effort 和快速模式

669 658

774| [`--add-dir <path>`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | 授予对附加目录的文件访问权限 |763| [`--add-dir <path>`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | 授予对附加目录的文件访问权限 |

775| [`--plugin-dir <path>`](https://code.claude.com/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session) | 从本地目录加载插件 |764| [`--plugin-dir <path>`](https://code.claude.com/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session) | 从本地目录加载插件 |

777| `--strict-mcp-config` | 仅使用来自 `--mcp-config` 的 MCP 服务器，忽略其他 MCP 配置。请参阅 [使用 managed-mcp.json 进行独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json) 了解该标志在托管 MCP 文件下的作用 |766| `--strict-mcp-config` | 跳过在 `.mcp.json` 等位置配置的 MCP 服务器，并加载您通过 `--mcp-config` 传递的 MCP 服务器。请参阅 [使用 managed-mcp.json 进行独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json) 了解该标志在托管 MCP 文件下的作用 |

778 767

779每个值需重复一次 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。`claude agents` 不支持空格分隔的形式，例如 `--add-dir a b c`。768每个值需重复一次 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。`claude agents` 不支持空格分隔的形式，例如 `--add-dir a b c`。

780 769

805| `claude rm <id>` | 从列表中删除会话，以及 Claude 为其创建的 worktree（当安全删除时）；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。会话记录保存在您的本地机器上，并且仍然可以通过 `claude --resume` 访问 |794| `claude rm <id>` | 从列表中删除会话，以及 Claude 为其创建的 worktree（当可以安全删除时）。如果 Claude Code 因其 worktree 而拒绝删除该会话，请参见 [在 Claude Code 拒绝后删除会话](#delete-a-session-after-claude-code-refuses)。对话的会话记录保存在您的本地机器上，并且仍然可以通过 `claude --resume` 访问 |

806| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 删除因未推送提交而删除被拒绝的会话，丢弃 worktree 及其分支和提交。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.260 或更高版本 |795| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 在 Claude Code 因未推送的提交而拒绝后，再次尝试删除会话并丢弃其 worktree。从提供该命令的 `claude rm` 消息中复制命令；参见 [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/zh-CN/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。需要 v2.1.260 或更高版本 |

807| `claude rm <id> --force-remove-worktree <worktree-id>` | 删除因 git 或 `WorktreeRemove` hook 无法删除其 worktree 而删除被拒绝的会话，无论如何删除 worktree 目录并在仓库中保留其分支。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.268 或更高版本 |796| `claude rm <id> --force-remove-worktree <worktree-id>` | 在 Claude Code 因无法删除 worktree 而拒绝后，再次尝试删除会话，并无论如何删除其 worktree 目录。从提供该命令的 `claude rm` 消息中复制命令；参见 [解决 `Worktree not removed` 消息](#resolve-a-worktree-not-removed-message)。需要 v2.1.268 或更高版本 |

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

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

939 928

940 在该行上按 `Enter`，页脚会显示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` 在同一行上再次按 `Enter` 来恢复其保存的对话。回复或 `claude attach <id>` 会在没有该页脚提示的情况下恢复它。929 在该行上按 `Enter`，页脚会显示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` 在同一行上再次按 `Enter` 来恢复其保存的对话。回复或 `claude attach <id>` 会在没有该页脚提示的情况下恢复它。

941 930

942当[会话记录清理](https://code.claude.com/docs/zh-CN/settings-reference.md#cleanupperioddays)删除了已停止会话的保存对话时，Claude Code 拒绝打开该行：消息说没有可恢复的内容。`claude rm <id>` 删除该行，除了上文[保留的情况](#what-deleting-a-session-removes)中描述的情况，`claude respawn <id>` 再次运行其原始提示词。请参阅[此会话的保存对话不再在磁盘上](https://code.claude.com/docs/zh-CN/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。931当[会话记录清理](https://code.claude.com/docs/zh-CN/settings-reference.md#cleanupperioddays)删除了已停止会话的保存对话时，Claude Code 拒绝打开该行：消息说没有可恢复的内容。`claude rm <id>` 会删除该行（除非 [Claude Code 拒绝删除](#what-deleting-a-session-removes)），`claude respawn <id>` 再次运行其原始提示词。请参阅[此会话的保存对话不再在磁盘上](https://code.claude.com/docs/zh-CN/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。

943 932

944仅睡眠不会停止会话。会话在睡眠中被保留，主管在唤醒时重新连接到它们。933仅睡眠不会停止会话。会话在睡眠中被保留，主管在唤醒时重新连接到它们。

945 934

973 962

974当后台会话的进程在完成启动之前退出，且主机内存不足时，该行的状态命名退出并添加 `possibly low memory — free some up and retry`。963当后台会话的进程在完成启动之前退出，且主机内存不足时，该行的状态命名退出并添加 `possibly low memory — free some up and retry`。

975 964

976该注释是一个假设，而不是确认的原因。Claude Code 仅在进程无声退出时添加它，没有写入错误，也没有被信号停止，且主机在那一刻报告内存不足。当进程在退出前确实写入了错误时，该行显示该错误。965> [!NOTE]

966>

967> 该注释是一个假设，而不是确认的原因。Claude Code 仅在进程无声退出时添加它，没有写入错误，也没有被信号停止，且主机在那一刻报告内存不足。当进程在退出前确实写入了错误时，该行显示该错误。

977 968

978释放机器上的内存，然后附加或回复该行，主管为会话启动新进程。当内存保持不足时，主管也会[停止空闲会话](#the-supervisor-process)来自行释放资源，如果停止其他会话没有释放任何内容，也会停止空闲的固定会话。969释放主机上的内存，然后在该行上按 `Enter`，如果[页脚提示](#opening-a-session-says-it-has-no-saved-transcript)，请再按一次。[主管](#the-supervisor-process)会为该会话启动新进程。当内存保持不足时，主管也会[停止空闲会话](#the-supervisor-process)来自行释放资源，如果停止其他会话没有释放任何内容，也会停止空闲的固定会话。

979 970

980### Agent 视图说后台服务没有响应971### Agent 视图说后台服务没有响应

981 972

1036 1027

1037### `.claude/worktrees/` 正在填满1028### `.claude/worktrees/` 正在填满

1038 1029

1039在 Agent 视图中删除会话会删除 Claude 为其创建的 worktree，但[某些删除会保留 worktree 或在磁盘上留下其目录](#what-deleting-a-session-removes)，所以剩余目录可能会累积。Git 不再识别的目录不会出现在 `git worktree list` 中，所以手动删除这些目录。1030在 Agent 视图中删除会话会删除 Claude 为其创建的 worktree，但[某些 worktree 目录会保留在磁盘上](#what-deleting-a-session-removes)。Git 不再识别的目录不会出现在 `git worktree list` 中，所以请手动删除这些目录。

1040 1031

1041在项目目录中使用 `git worktree list` 列出剩余条目，并使用 `git worktree remove <path>` 删除每一个。请参阅[清理 worktrees](https://code.claude.com/docs/zh-CN/worktrees.md#clean-up-worktrees)。1032在项目目录中使用 `git worktree list` 列出剩余条目，并使用 `git worktree remove <path>` 删除每一个。如果 Git 拒绝删除，请参阅[清理子代理和后台会话的 worktree](https://code.claude.com/docs/zh-CN/worktrees.md#clean-up-subagent-and-background-session-worktrees)。

1042 1033

1043## 限制1034## 限制

1044 1035

1046 1037

1047* **速率限制适用**：后台会话消耗你的订阅使用量，与交互式会话相同，因此并行运行十个代理的配额消耗速度大约是运行一个代理的十倍。1038* **速率限制适用**：后台会话消耗你的订阅使用量，与交互式会话相同，因此并行运行十个代理的配额消耗速度大约是运行一个代理的十倍。

1048* **会话是本地的**：后台会话在你的机器上运行。它们在机器睡眠时保留，但在机器关闭时停止。1039* **会话是本地的**：后台会话在你的机器上运行。它们在机器睡眠时保留，但在机器关闭时停止。

1049* **Claude 创建的 worktrees 在 agent view 中随会话删除**：在删除在其自己的 worktree 中编辑文件的会话之前，请提交更改。[某些删除会保留 worktree](#what-deleting-a-session-removes)。1040* **Claude 创建的 worktree 在 agent view 中随会话删除**：在删除在其自己的 worktree 中编辑文件的会话之前，请提交更改。[某些 worktree 会保留在磁盘上](#what-deleting-a-session-removes)。

1050 1041

1051## 相关资源1042## 相关资源

1052 1043

artifacts.md +2 −2

Details

432 432

433要设置 Artifact 在被自动删除之前的保留时长，请前往 [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls)。您可以分别为仍仅对作者私有的 Artifact 和已被共享的 Artifact 设置不同的保留期限。433要设置 Artifact 在被自动删除之前的保留时长，请前往 [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls)。您可以分别为仍仅对作者私有的 Artifact 和已被共享的 Artifact 设置不同的保留期限。

434 434

435### 查看审计日志435### 使用 Compliance API 审计 Artifact 活动

436 436

437发布、共享和删除 Artifact 的操作都会以 `claude_artifact_*` 事件类型出现在组织的审计日志中，这与在 claude.ai 对话中创建的 Artifact 所使用的事件类型系列相同。437在 Enterprise 计划中，查询 Compliance API 的 [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed)，即可查看谁发布、共享或删除了 Artifact。要查找可用于筛选的活动类型，请在 [Activity Feed 参考](https://platform.claude.com/docs/en/api/compliance/activities/list)中展开 `activity_types`，并查找名称中包含 `artifact` 的类型。

438 438

439### 将查看器域名加入允许列表439### 将查看器域名加入允许列表

440 440

claude-projects.md +3 −9

Details

163Claude 决定你在对话中发送的每条消息的去向：163Claude 决定你在对话中发送的每条消息的去向：

164 164

165* 快速问题通常会在对话中得到答案。165* 快速问题通常会在对话中得到答案。

166* 新工作会进入新线程或已在该区域工作的线程，Claude 会告诉你是哪一个。每个新线程在你的消息下显示为一张卡片：一个包含线程标题和状态的框，你点击它来打开线程。166* 新工作会进入新线程或已在该区域工作的线程，Claude 会告诉您是哪一个。每个新线程都会显示在对话中，点击它即可打开该线程。

167* 一条消息中的多个不相关的任务会变成单独的线程。167* 一条消息中的多个不相关的任务会变成单独的线程。

168 168

169如果 Claude 路由的方式与你想要的不同，请说出来。[调整 Claude 如何运行项目](#tune-how-claude-runs-a-project)列出了你可以告诉它的事情，例如为后续工作重用现有线程或就地回答而不是启动线程。169如果 Claude 路由的方式与你想要的不同，请说出来。[调整 Claude 如何运行项目](#tune-how-claude-runs-a-project)列出了你可以告诉它的事情，例如为后续工作重用现有线程或就地回答而不是启动线程。

170 170

171线程的完整结果保留在线程中，您可以打开对话中的线程卡片来阅读它们。线程生成的文件也位于项目的[**库**](#see-what-needs-you-in-overview)中。171线程的完整结果保留在线程中，因此请打开线程来阅读它们。线程生成的文件也位于项目的[**库**](#see-what-needs-you-in-overview)中。

172 172

173有时 Claude 会在**建议的线程**列表中提议线程而不是启动它们。点击建议上的箭头来启动该线程。当列出多个时，列表下的按钮会启动所有这些线程。173有时 Claude 会在**建议的线程**列表中提议线程而不是启动它们。点击建议上的箭头来启动该线程。当列出多个时，列表下的按钮会启动所有这些线程。

174 174

180* **拉取请求**：当你要求时打开一个，并且可以为错误修复或其他具体更改自动打开一个。180* **拉取请求**：当你要求时打开一个，并且可以为错误修复或其他具体更改自动打开一个。

181* **打开后**：使用[自动修复](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)打开的情况下监视拉取请求，无论你的其他云会话是否打开了自动修复。当 CI 失败时它会推送修复，处理审查评论，并在检查通过且拉取请求准备好供你使用时在线程中回复。181* **打开后**：使用[自动修复](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)打开的情况下监视拉取请求，无论你的其他云会话是否打开了自动修复。当 CI 失败时它会推送修复，处理审查评论，并在检查通过且拉取请求准备好供你使用时在线程中回复。

182 182

183当线程推送了分支或打开了拉取请求时，其在对话中的卡片可以显示下一步的按钮：

~~184~~

185* **解决冲突**、**修复 CI**、**处理评论**和**合并它**将该指令作为来自你的消息发送给线程，因此你可以自己提示线程，而不是等待它对拉取请求做出反应。

186* **审查 PR** 在 GitHub 上打开拉取请求。

187* **创建 PR** 在空闲线程推送了分支但尚未打开拉取请求时出现。点击它会直接从该分支创建拉取请求，而不是向线程发送打开拉取请求的指令。

~~188~~

189要更改线程何时打开拉取请求（例如仅在你要求时）或它们从哪个分支开始，请在任务中或在[项目说明](#write-project-instructions)中说明。183要更改线程何时打开拉取请求（例如仅在你要求时）或它们从哪个分支开始，请在任务中或在[项目说明](#write-project-instructions)中说明。

190 184

191### 在概览中查看需要你的内容185### 在概览中查看需要你的内容

212 206

213### 当你需要控制时打开线程207### 当你需要控制时打开线程

214 208

215点击对话中线程的卡片或概览中的对应行，即可在概览窗格中打开其会话记录。在那里您可以：209点击对话中的线程或概览中的对应行，即可在概览窗格中打开该线程。在那里您可以：

216 210

217* 逐步阅读 Claude 所做的事情。211* 逐步阅读 Claude 所做的事情。

218* 通过在线程自己的消息框中写入来引导任务。那里的消息直接进入该线程，而项目对话中的后续消息仅在 Claude 将后续消息与该线程匹配时才到达它。212* 通过在线程自己的消息框中写入来引导任务。那里的消息直接进入该线程，而项目对话中的后续消息仅在 Claude 将后续消息与该线程匹配时才到达它。

cli-reference.md +1 −1

Details

129| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`）。有关从此会话启动并继承该列表的会话，请参阅 [Agent 视图](https://code.claude.com/docs/zh-CN/agent-view.md#what-carries-over-when-you-background)和 [agent team](https://code.claude.com/docs/zh-CN/agent-teams.md#context-and-communication) | `claude --setting-sources user,project` |129| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`）。有关从此会话启动并继承该列表的会话，请参阅 [Agent 视图](https://code.claude.com/docs/zh-CN/agent-view.md#what-carries-over-when-you-background)和 [agent team](https://code.claude.com/docs/zh-CN/agent-teams.md#context-and-communication) | `claude --setting-sources user,project` |

130| `--settings` | 设置 JSON 文件的路径或内联 JSON 字符串。您在此处设置的值会在此会话中覆盖 `settings.json` 文件中的相同键。您省略的键保持其基于文件的值。文件必须是不超过 2 MiB 的常规文件。请参阅[设置优先级](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence) | `claude --settings ./settings.json` |130| `--settings` | 设置 JSON 文件的路径或内联 JSON 字符串。您在此处设置的值会在此会话中覆盖 `settings.json` 文件中的相同键。您省略的键保持其基于文件的值。文件必须是不超过 2 MiB 的常规文件。请参阅[设置优先级](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence) | `claude --settings ./settings.json` |

131| `--strict-mcp-config` | 仅使用 `--mcp-config` 中的 MCP 服务器，忽略所有其他 MCP 配置。有关此标志在托管 MCP 文件下的行为，请参阅[使用 managed-mcp.json 的独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json) | `claude --strict-mcp-config --mcp-config ./mcp.json` |131| `--strict-mcp-config` | 跳过在 `.mcp.json`、`~/.claude.json` 或插件等位置配置的 MCP 服务器，并加载您通过 `--mcp-config` 传递的 MCP 服务器。有关此标志在托管 MCP 文件下的行为，请参阅[使用 managed-mcp.json 的独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json) | `claude --strict-mcp-config --mcp-config ./mcp.json` |

134| `--system-prompt-snapshot` | 传递 `off` 以在每个请求上重建系统提示词，而不是重用[在对话的第一个请求上记录的](#system-prompt-flags-in-resumed-conversations)提示词，例如在跨多次 `--continue` 运行迭代 `--append-system-prompt` 文本时。需要 Claude Code v2.1.257 或更高版本 | `claude --system-prompt-snapshot off` |134| `--system-prompt-snapshot` | 传递 `off` 以在每个请求上重建系统提示词，而不是重用[在对话的第一个请求上记录的](#system-prompt-flags-in-resumed-conversations)提示词，例如在跨多次 `--continue` 运行迭代 `--append-system-prompt` 文本时。需要 Claude Code v2.1.257 或更高版本 | `claude --system-prompt-snapshot off` |

desktop.md +2 −1

Details

2127 2127

2128要阻止这种情况，还需在 Claude Desktop 策略中（Windows 上位于 `HKLM` 中）部署 `forceLoginOrgUUID`，并填入您的 claude.ai 组织 ID。除非策略本身[选择了 Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)，否则 Claude Desktop 会在应用下次启动时停止使用个人自己的 API 密钥或 Console 帐户。2128要阻止这种情况，还需在 Claude Desktop 策略中（Windows 上位于 `HKLM` 中）部署 `forceLoginOrgUUID`，并填入您的 claude.ai 组织 ID。除非策略本身[选择了 Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)，否则 Claude Desktop 会在应用下次启动时停止使用个人自己的 API 密钥或 Console 帐户。

2129 2129

2130部署之前，请检查以下两种情况：2130部署之前，请检查以下三种情况：

2131 2131

2132* **Claude Console 组织**：不要仅凭 Claude Console 组织的 ID 单独部署 `forceLoginOrgUUID`，否则会将您组织中的人员锁定在 Claude Desktop 之外。请改为参阅[哪些设备提供 Claude API 帐户登录](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)。2132* **Claude Console 组织**：不要仅凭 Claude Console 组织的 ID 单独部署 `forceLoginOrgUUID`，否则会将您组织中的人员锁定在 Claude Desktop 之外。请改为参阅[哪些设备提供 Claude API 帐户登录](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)。

2133* **Enterprise Admin Console**：如果它为您的计算机提供 Claude Desktop 配置，请先将这些计算机更新到 Claude Desktop v2.37337.0 或更高版本，因为一旦设置了此键，早期版本会忽略该配置。请参阅[使设备保持使用其托管配置文件](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)。2133* **Enterprise Admin Console**：如果它为您的计算机提供 Claude Desktop 配置，请先将这些计算机更新到 Claude Desktop v2.37337.0 或更高版本，因为一旦设置了此键，早期版本会忽略该配置。请参阅[使设备保持使用其托管配置文件](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)。

2134* **第三方提供商**：如果用户在应用中设置了自己的[第三方推理配置](https://claude.com/docs/third-party/claude-desktop/in-app-configuration)，则在您部署此键后，Claude Desktop 会从下次启动起忽略该配置。要让用户继续使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关，请在同一 Claude Desktop 策略中向其计算机[部署配置](https://claude.com/docs/third-party/claude-desktop/configuration)。

2134 2135

2135### 网络访问要求2136### 网络访问要求

2136 2137

desktop-scheduled-tasks.md +4 −4

Details

182* **Review allowed permissions**：从 **Always allowed** 面板查看和撤销此任务的已保存工具批准182* **Review allowed permissions**：从 **Always allowed** 面板查看和撤销此任务的已保存工具批准

183* **Delete**：删除任务。该任务创建的会话会被[存档](https://code.claude.com/docs/zh-CN/desktop.md#organize-and-find-sessions)，而不是被删除。存放任务 `SKILL.md` 文件的文件夹会保留在磁盘上的 `~/.claude/scheduled-tasks/<task-name>/` 中；如果您设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 变量，则保留在其下的 `scheduled-tasks/<task-name>/` 中。要删除该文件夹，请您自行删除。183* **Delete**：删除任务。该任务创建的会话会被[存档](https://code.claude.com/docs/zh-CN/desktop.md#organize-and-find-sessions)，而不是被删除。存放任务 `SKILL.md` 文件的文件夹会保留在磁盘上的 `~/.claude/scheduled-tasks/<task-name>/` 中；如果您设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 变量，则保留在其下的 `scheduled-tasks/<task-name>/` 中。要删除该文件夹，请您自行删除。

184 184

185您也可以通过在任何 Desktop 会话中询问 Claude 来列出、创建、编辑和暂停任务。例如，"pause my dependency-audit task"或"show me my scheduled tasks"。要删除任务，请使用其详细信息页面上的 **Delete** 按钮。185您还可以通过询问 Claude、让任务自行更新或在磁盘上编辑任务的提示词来管理任务：

186 186

187要让任务使用 `update_scheduled_task` MCP 工具更改其自己的调度或提示词，请单击 **Run now** 并每次批准该调用。187* **询问 Claude**：在任何 Desktop 会话中询问 Claude 来列出、创建、编辑和暂停任务。例如，"pause my dependency-audit task"或"show me my scheduled tasks"。要删除任务，请使用其详细信息页面上的 **Delete** 按钮。

~~188~~ 188* **让任务自行更新**：要让任务使用 `update_scheduled_task` MCP 工具更改其自己的调度或提示词，请单击 **Run now** 并每次批准该调用

189要在磁盘上编辑任务的提示词，请打开 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars)，则在其下）。该文件使用 YAML frontmatter 表示 `name` 和 `description`，提示词作为正文。更改在下一次运行时生效。Schedule、folder 和 enabled 状态不在此文件中：通过 Edit 表单更改它们或询问 Claude。189* **在磁盘上编辑提示词**：打开 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`；如果您设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 变量，则打开其下的 `scheduled-tasks/<task-name>/SKILL.md`。该文件使用 YAML frontmatter 表示 `name` 和 `description`，提示词作为正文。更改在下一次运行时生效。Schedule、folder 和 enabled 状态不在此文件中：请通过 Edit 表单更改它们或询问 Claude。

190 190

191## 相关资源191## 相关资源

192 192

env-vars.md +1 −1

Details

356| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 将其打开。这可以防止 Claude Code 绕过 Perforce 变更跟踪 |356| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 将其打开。这可以防止 Claude Code 绕过 Perforce 变更跟踪 |

358| `CLAUDE_CODE_PLUGIN_DIRS` | 要为会话加载的插件目录，每个目录的加载方式与 [`--plugin-dir`](https://code.claude.com/docs/zh-CN/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 标志相同。在 Unix 上用 `:` 分隔多个路径，在 Windows 上用 `;` 分隔。每个路径都应为绝对路径或以 `~` 开头，因为 Claude Code 会跳过相对路径。需要 Claude Code v2.1.280 或更高版本。请参阅[为单个会话加载插件](https://code.claude.com/docs/zh-CN/plugins/create.md#load-a-directory-or-archive-for-one-session) |358| `CLAUDE_CODE_PLUGIN_DIRS` | 要为会话加载的插件目录，每个目录的加载方式与 [`--plugin-dir`](https://code.claude.com/docs/zh-CN/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 标志相同。在 Unix 上用 `:` 分隔多个路径，在 Windows 上用 `;` 分隔。每个路径都应为绝对路径或以 `~` 开头，因为 Claude Code 会跳过相对路径。需要 Claude Code v2.1.280 或更高版本。请参阅[为单个会话加载插件](https://code.claude.com/docs/zh-CN/plugins/create.md#load-a-directory-or-archive-for-one-session) |

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 的文件发生变化时重新加载该 mod。重新加载适用于您通过 `--plugin-dir` 从目录加载的 mod，在交互式会话中默认开启。设置为 `1` 可同时在非交互式会话中开启，设置为 `0` 则在所有会话中关闭。需要 Claude Code v2.1.287 或更高版本。请参阅 [mod 设置和环境变量](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#settings-and-environment-variables) |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 在其文件更改时是否重新加载。默认情况下，[skill 目录](https://code.claude.com/docs/zh-CN/plugins/org.md#keep-skills-directory-plugins-loading)中的 mod 会在任何包含多个提示词的会话中重新加载，包括[非交互](https://code.claude.com/docs/zh-CN/headless.md)会话。`--plugin-dir` 目录中的 mod 仅在交互式终端会话中重新加载。设置为 `1` 可使它们像 skill 目录中的 mod 一样重新加载，设置为 `0` 则在所有地方关闭重新加载。需要 Claude Code v2.1.287 或更高版本 |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒，默认：120000）。对于大型仓库或较慢的网络连接，请调高此值。请参阅 [Git clone timed out](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#git-clone-timed-out-after-120s) |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒，默认：120000）。对于大型仓库或较慢的网络连接，请调高此值。请参阅 [Git clone timed out](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#git-clone-timed-out-after-120s) |

361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程仓库或无法通过其身份验证时，跳过重新克隆尝试并继续使用现有的市场检出副本。适用于重新克隆同样会失败的离线或气隙环境。请参阅[市场更新在离线环境中失败](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline) |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程仓库或无法通过其身份验证时，跳过重新克隆尝试并继续使用现有的市场检出副本。适用于重新克隆同样会失败的离线或气隙环境。请参阅[市场更新在离线环境中失败](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline) |

362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而非 SSH 克隆 GitHub `owner/repo` 简写来源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何没有为 `github.com` 配置 SSH 密钥的环境 |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而非 SSH 克隆 GitHub `owner/repo` 简写来源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何没有为 `github.com` 配置 SSH 密钥的环境 |

errors.md +4 −8

Details

5556 5556

5557### Worktree has commits that are not pushed anywhere5557### Worktree has commits that are not pushed anywhere

5558 5558

5559您尝试删除一个[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#what-deleting-a-session-removes)，而其 worktree 中包含 Claude Code 无法确认已保存在别处的提交。Claude Code 会保留该 worktree 和会话行，而不是在您未察看的情况下销毁这些提交。`claude rm` 会指明分支和未推送的提交，并说明如何继续：5559您尝试删除一个[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#what-deleting-a-session-removes)，而其 worktree 中包含 Claude Code 无法确认已保存在别处的提交。`claude rm` 会说明如何继续：

5560 5560

5561```text theme={null}5561```text theme={null}

5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”

5566 5566

5567当 Claude Code 无法汇总这些提交时，详情行会改为显示 `The worktree has unpushed commits`。在 [agent view](https://code.claude.com/docs/zh-CN/agent-view.md) 中，该会话的行会显示 `not removed` 以及相同的原因。5567当 Claude Code 无法汇总这些提交时，详情行会改为显示 `The worktree has unpushed commits`。在 [agent view](https://code.claude.com/docs/zh-CN/agent-view.md) 中，该会话的行会显示 `not removed` 以及相同的原因。

5568 5568

5569远程上的提交不会阻止删除。您的 `origin` 远程默认分支的本地副本上的提交也不会阻止删除，前提是该分支已在您的主检出（即仓库目录本身，而非某个 worktree）中检出。

~~5570~~

5571**解决方法：**5569**解决方法：**

5572 5570

5573* 要保留这些提交，请推送该 worktree 的分支，或将其合并到主检出中已检出的默认分支，然后再次删除该会话5571* 要保留这些提交，请推送它们。推送使它们出现在某个远程跟踪分支（例如 `origin/claude/fix-login`）上之后，再次尝试删除该会话。

5574* 要丢弃这些提交，请运行消息中打印的 `claude rm <id> --discard-unpushed` 命令，或在 agent view 中该会话的行上再次按两次 `Ctrl+X`。这会删除该会话和 worktree，连同其分支、未推送的提交以及所有未提交的更改。如果删除再次被拒绝，请按照新消息操作。5572* 如果消息提供了丢弃这些提交的选项，请先确认您不再需要该 worktree、这些提交以及任何未提交的更改。然后执行消息给出的操作：在 agent view 中该会话的行上按两次 `Ctrl+X`，或运行 `claude rm` 打印的 `claude rm <id> --discard-unpushed <commit>@<worktree-id>` 命令。如果 Claude Code 再次拒绝，请按照新消息操作。

5575* 当消息说明该 worktree 还被另一个已结束的会话记录时，再次删除不会丢弃它：请推送这些提交，然后再次删除该会话5573* 当消息说明该 worktree 还被另一个已结束的会话记录时，再次删除不会丢弃它：请推送这些提交，然后再次尝试删除该会话

5576 5574

5577在 v2.1.268 之前，`claude rm` 会将提交摘要放在 `kept` 行本身。当 `claude rm` 无法汇总提交时，`kept` 行会以 `worktree has commits that are not pushed anywhere` 代替摘要。5575在 v2.1.268 之前，`claude rm` 会将提交摘要放在 `kept` 行本身。当 `claude rm` 无法汇总提交时，`kept` 行会以 `worktree has commits that are not pushed anywhere` 代替摘要。

5578 5576

5579在 v2.1.260 之前，该消息不会指明分支或提交，也没有丢弃途径。您仍然可以删除该会话，这会丢失未提交的更改，但保留分支和提交。请使用拒绝消息中打印的路径运行 `git worktree remove --force --force <path>`，然后运行 `claude rm <id>`。对于已锁定的 worktree，Git 需要两次 `--force`。5577在 v2.1.260 之前，该消息不会指明分支或提交，也没有丢弃途径。您仍然可以删除该会话，这会丢失未提交的更改，但保留分支和提交。请使用拒绝消息中打印的路径运行 `git worktree remove --force --force <path>`，然后运行 `claude rm <id>`。对于已锁定的 worktree，Git 需要两次 `--force`。

5580 5578

5581在 v2.1.248 之前，主检出中已检出的默认分支不算在内：即使某个分支已在那里合并，在其提交到达远程之前仍会触发此拒绝。

~~5582~~

5583### Terminal host process died5579### Terminal host process died

5584 5580

5585每个[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)的终端都运行在后台服务下的一个宿主进程中，而该进程在服务仍持有其连接时终止了，因此无法访问该会话。5581每个[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)的终端都运行在后台服务下的一个宿主进程中，而该进程在服务仍持有其连接时终止了，因此无法访问该会话。

feature-availability.md +1 −1

Details

35这些有提供商特定的差异：35这些有提供商特定的差异：

36 36

37* **MCP 服务器**：[来自 claude.ai 的连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)仅在您的 claude.ai 订阅是活跃身份验证方法时加载。[工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#configure-tool-search)在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)时不受支持。在 Google Cloud's Agent Platform 上，早于 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型不支持工具搜索37* **MCP 服务器**：[来自 claude.ai 的连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)仅在您的 claude.ai 订阅是活跃身份验证方法时加载。[工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#configure-tool-search)在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)时不受支持。在 Google Cloud's Agent Platform 上，早于 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型不支持工具搜索

38* **Subagents**：当主对话运行 Fable 时，如果使用 Claude 订阅、Anthropic Console 账户或通过 `ANTHROPIC_BASE_URL` 访问的 [LLM gateway](https://code.claude.com/docs/zh-CN/llm-gateway)，内置的 [Explore subagent](https://code.claude.com/docs/zh-CN/sub-agents.md#built-in-subagents) 会在 Opus 上运行。在其他提供商（包括 Claude Platform on AWS）上，它在 Fable 上运行38* **子代理**：当父对话运行 Fable 时，如果使用 Claude 订阅、Anthropic Console 账户，或通过 `ANTHROPIC_BASE_URL` 访问的 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)，内置的 [Explore 子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#built-in-subagents)将在 Opus 上运行。在其他提供商（包括 Claude Platform on AWS）上，它将在 Fable 上运行

39* **[Commands](https://code.claude.com/docs/zh-CN/commands.md#all-commands)**：39* **[Commands](https://code.claude.com/docs/zh-CN/commands.md#all-commands)**：

40 * `/design-sync` 和 `/import` 及其 `claude import` 子命令形式在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上不可用，以及通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway#availability-and-limitations)40 * `/design-sync` 和 `/import` 及其 `claude import` 子命令形式在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上不可用，以及通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway#availability-and-limitations)

41 * `/voice` 需要 claude.ai 账户41 * `/voice` 需要 claude.ai 账户

features-overview.md +1 −1

Details

188>188>

189> **将护栏放在 hooks 中。** CLAUDE.md 或 skill 中的"永远不要编辑 `.env`"之类的说明是请求，而不是保证。阻止编辑的 `PreToolUse` hook 是强制执行。如果规则必须每次都成立，将其作为 hook 而不是提示说明。189> **将护栏放在 hooks 中。** CLAUDE.md 或 skill 中的"永远不要编辑 `.env`"之类的说明是请求，而不是保证。阻止编辑的 `PreToolUse` hook 是强制执行。如果规则必须每次都成立，将其作为 hook 而不是提示说明。

190>190>

191> **Hook 输出进入上下文。** 运行您的 linter 的 `PostToolUse` hook 将结果作为 Claude 读取的文本反馈；`/fix-lint` skill 告诉 Claude 如何解决它们。191> **将 hook 与 skill 搭配使用。** 使用 `PostToolUse` hook 运行您的 linter 并[将错误发送给 Claude](https://code.claude.com/docs/zh-CN/hooks.md#exit-code-2-behavior-per-event)。要为 Claude 提供您自己的错误修复规则，请编写一个 skill，例如 `/fix-lint`。

192 192

193### 了解功能如何分层193### 了解功能如何分层

194 194

glossary.md +1 −1

Details

283 283

284### Sandboxing284### Sandboxing

285 285

286Bash 工具的操作系统级文件系统和网络隔离。命令在您预先定义的边界内运行，因此 Claude 可以在其中自由工作，无需每个命令的批准提示。沙箱隔离是与 [permission rules](#permission-rule) 分开的一层。286Bash 工具的操作系统级文件系统和网络隔离。命令在您预先定义的边界内运行。沙箱隔离是与 [permission rules](#permission-rule) 分开的一层。

287 287

288了解更多：[Sandboxing](https://code.claude.com/docs/zh-CN/sandboxing.md)288了解更多：[Sandboxing](https://code.claude.com/docs/zh-CN/sandboxing.md)

289 289

hooks-guide.md +5 −1

Details

242 242

243### 阻止编辑受保护的文件243### 阻止编辑受保护的文件

244 244

245防止 Claude 修改敏感文件，例如 `.env`、`package-lock.json` 或 `.git/` 中的任何内容。Claude 会收到说明编辑被阻止原因的反馈，从而可以调整其做法。245阻止 Claude 的 `Edit` 和 `Write` 工具修改敏感文件，例如 `.env`、`package-lock.json` 或 `.git/` 中的任何内容。Claude 会收到说明编辑被阻止原因的反馈，从而可以调整其做法。

246 246

247此示例使用一个由 hook 调用的独立脚本文件。该脚本将目标文件路径与受保护模式列表进行比对，并以退出码 2 退出以阻止编辑。247此示例使用一个由 hook 调用的独立脚本文件。该脚本将目标文件路径与受保护模式列表进行比对，并以退出码 2 退出以阻止编辑。

248 248

306 306

307让 Claude 向您的 `.env` 文件添加一条注释。Claude Code 会在编辑执行前将其阻止，并将脚本的 `Blocked:` 消息作为反馈传递给 Claude。307让 Claude 向您的 `.env` 文件添加一条注释。Claude Code 会在编辑执行前将其阻止，并将脚本的 `Blocked:` 消息作为反馈传递给 Claude。

308 308

309Claude 仍然可以通过 shell 命令更改受保护的文件。若要阻止其中部分命令，请在 `.claude/settings.json` 的 `permissions.deny` 下为每个路径添加一条 [`Edit` 拒绝规则](https://code.claude.com/docs/zh-CN/permissions#what-read-and-edit-rules-cover)，例如针对项目根目录下 `.env` 的 `Edit(/.env)`。

310

311即使有这些规则，Claude 仍可以通过其他方式更改 `.env`。若要限制命令可以写入哪些文件，请参阅[配置沙箱隔离](https://code.claude.com/docs/zh-CN/sandboxing.md#configure-sandboxing)。

312

309### 上下文压缩后重新注入上下文313### 上下文压缩后重新注入上下文

310 314

311当 Claude 的上下文窗口填满时，压缩会总结对话以释放空间。这可能会丢失重要细节。使用带有 `compact` 匹配器的 `SessionStart` hook，在每次压缩后重新注入关键上下文。315当 Claude 的上下文窗口填满时，压缩会总结对话以释放空间。这可能会丢失重要细节。使用带有 `compact` 匹配器的 `SessionStart` hook，在每次压缩后重新注入关键上下文。

llm-gateway-protocol.md +1 −0

Details

296* 顶层的 `output_config.effort` 字段。[自动重试和错误转发](#automatic-retry-and-error-forwarding)介绍了上游拒绝它的情况296* 顶层的 `output_config.effort` 字段。[自动重试和错误转发](#automatic-retry-and-error-forwarding)介绍了上游拒绝它的情况

297* 自适应推理的 `thinking` 字段，它没有 beta 请求头297* 自适应推理的 `thinking` 字段，它没有 beta 请求头

298* 携带[对话中途系统消息](#feature-pass-through)的 `role: "system"` 条目298* 携带[对话中途系统消息](#feature-pass-through)的 `role: "system"` 条目

299* 自动模式[服务器端分类器审查](https://code.claude.com/docs/zh-CN/permission-modes.md#server-side-classifier-review)的 `anthropic-beta` 值和 `safeguards` 字段，适用于该审查保持开启的会话，例如 `/status` 将 **Auto mode server** 显示为 `Enabled` 时。若要关闭该审查，请在启动会话之前设置 `CLAUDE_CODE_AUTO_MODE_SERVER=0`。在终端中，`/status` 随后会将 **Auto mode server** 显示为 `Disabled`。

299* 订阅身份验证所需的 OAuth `anthropic-beta` 值300* 订阅身份验证所需的 OAuth `anthropic-beta` 值

300* 开发者通过 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/zh-CN/env-vars) 或 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/zh-CN/env-vars) 自行添加的请求头值和请求体字段301* 开发者通过 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/zh-CN/env-vars) 或 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/zh-CN/env-vars) 自行添加的请求头值和请求体字段

301 302

managed-mcp.md +3 −2

Details

30| 模式 | 功能 | 配置 |30| 模式 | 功能 | 配置 |

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

36| **仅插件服务器** | 用户无法通过 `~/.claude.json` 或 `.mcp.json` 添加服务器；[技能目录插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)不再作为插件加载，来自其他插件的服务器仍然加载 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/zh-CN/settings-reference#strictpluginonlycustomization) 列表中包含 `mcp` |36| **仅插件服务器** | 用户无法通过 `~/.claude.json` 或 `.mcp.json` 添加服务器；[技能目录插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)不再作为插件加载，来自其他插件的服务器仍然加载 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/zh-CN/settings-reference#strictpluginonlycustomization) 列表中包含 `mcp` |

49* 该文件定义的服务器49* 该文件定义的服务器

50* 你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)50* 你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)

51* 启动会话的应用程序注册的进程内服务器，例如 VS Code 扩展自己的服务器或[桌面应用程序提供的连接器](https://code.claude.com/docs/zh-CN/mcp.md#how-connectors-reach-claude-code)51* 启动会话的应用程序注册的进程内服务器，例如 VS Code 扩展自己的服务器或[桌面应用程序提供的连接器](https://code.claude.com/docs/zh-CN/mcp.md#how-connectors-reach-claude-code)

52* 当 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) [添加工具](https://code.claude.com/docs/zh-CN/plugins/mods/api.md#add-a-tool)时 Claude Code 创建的服务器。要阻止用户的 mod 添加的工具，请[阻止用户安装的 mod 加载](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#stop-user-installed-mods-from-loading)。

52* 内置的[Chrome 中的 Claude](https://code.claude.com/docs/zh-CN/chrome.md) 服务器，如果你[允许它与托管集合一起使用](#allow-claude-in-chrome-alongside-the-managed-set)53* 内置的[Chrome 中的 Claude](https://code.claude.com/docs/zh-CN/chrome.md) 服务器，如果你[允许它与托管集合一起使用](#allow-claude-in-chrome-alongside-the-managed-set)

53 54

54用户无法添加、修改或使用任何其他 MCP 服务器，包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会禁止 Claude Code 自身获取的 claude.ai 连接器，除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。55用户无法添加、修改或使用任何其他 MCP 服务器，包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会禁止 Claude Code 自身获取的 claude.ai 连接器，除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。

137}138}

138```139```

139 140

140`claude mcp add` 失败，显示上述企业策略错误。用户之前配置的服务器在下次启动会话时停止加载，没有警告说明策略是原因。你通过 `managedMcpServers` 提供的服务器以及你允许与托管集合一起使用的任何其他内容仍然在空映射下加载，因此保持这些键未设置以完全关闭 MCP。141`claude mcp add` 失败，显示上述企业策略错误。用户之前配置的服务器在下次启动会话时停止加载，没有警告说明策略是原因。您通过 `managedMcpServers` 提供的服务器以及您允许与托管集合一起使用的任何其他内容在空映射下[仍然会加载](#exclusive-control-with-managed-mcp-json)，因此请保持这些键未设置。

141 142

142### 允许 claude.ai 连接器与托管集合一起使用143### 允许 claude.ai 连接器与托管集合一起使用

143 144

mcp.md +1 −1

Details

806 806

807* 将其添加到 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers)，这会在所有权限模式下阻止它。807* 将其添加到 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers)，这会在所有权限模式下阻止它。

808* 使用 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 或 SDK 的 `settingSources` 选项完全排除项目设置。808* 使用 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 或 SDK 的 `settingSources` 选项完全排除项目设置。

809* 使用 [`--strict-mcp-config`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 启动会话。此时 Claude Code 仅使用您通过 `--mcp-config` 传入的 MCP 服务器。对于 Claude Code 未加载的 Project 作用域服务器跳过批准提示，需要 Claude Code v2.1.246 或更高版本；在 v2.1.246 之前，strict 会话仍会等待对这些服务器的批准，导致后台会话在启动时处于等待状态。有关在托管 MCP 文件下该标志的作用，请参阅[使用 managed-mcp.json 进行独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json)。809* 使用 [`--strict-mcp-config`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 启动会话。此时 Claude Code 会加载您通过 `--mcp-config` 传入的服务器，并跳过在 `.mcp.json` 等位置配置的服务器。对于 Claude Code 未加载的 Project 作用域服务器跳过批准提示，需要 Claude Code v2.1.246 或更高版本。有关在托管 MCP 文件下该标志的作用，请参阅[使用 managed-mcp.json 进行独占控制](https://code.claude.com/docs/zh-CN/managed-mcp.md#exclusive-control-with-managed-mcp-json)。

810 810

811[项目服务器批准与工作区信任](#project-server-approvals-and-workspace-trust)介绍了提交到仓库中的批准如何与工作区信任相互作用。811[项目服务器批准与工作区信任](#project-server-approvals-and-workspace-trust)介绍了提交到仓库中的批准如何与工作区信任相互作用。

812 812

model-config.md +2 −2

Details

273* **`/model`**：Claude Code 以错误拒绝切换273* **`/model`**：Claude Code 以错误拒绝切换

274* **`--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置**：Claude Code 在启动时用警告替换该值，命名请求的和替换的模型，会话在默认模型上启动274* **`--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置**：Claude Code 在启动时用警告替换该值，命名请求的和替换的模型，会话在默认模型上启动

275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 忽略该变量275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 忽略该变量

276* **子代理或队友覆盖**：Claude Code 在备用模型上运行子代理或队友，而不是使请求失败。有关子代理回退，请参阅[选择模型](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)，有关队友回退，请参阅[指定队友和模型](https://code.claude.com/docs/zh-CN/agent-teams.md#specify-teammates-and-models)。276* **子代理或队友覆盖**：Claude Code 在备用模型上运行子代理或队友，而不是使请求失败。有关子代理回退，请参阅[当允许列表阻止子代理模型时](https://code.claude.com/docs/zh-CN/sub-agents.md#when-an-allowlist-blocks-a-subagent-model)，有关队友回退，请参阅[指定队友和模型](https://code.claude.com/docs/zh-CN/agent-teams.md#specify-teammates-and-models)。

277 277

278 在交互式会话中，当 Claude Code 通过此回退或上面的最新允许版本替换来替换子代理的模型时，它会警告您，命名请求的和替换的模型；它不报告队友的回退。278 在交互式会话中，当 Claude Code 替换顶层子代理的模型时，它会警告您。它不报告队友的回退。

279 279

280 在上面的最新允许版本替换操作的地方，被阻止的系列别名遵循它。在 v2.1.222 之前，别名在每个提供商上像任何其他被阻止的值一样回退280 在上面的最新允许版本替换操作的地方，被阻止的系列别名遵循它。在 v2.1.222 之前，别名在每个提供商上像任何其他被阻止的值一样回退

281* **skill 或命令覆盖**：Claude Code 忽略覆盖，包括被阻止的系列别名，skill 或命令在会话模型上运行。[在子代理中运行](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent)的 skill 或命令遵循上面的子代理行为281* **skill 或命令覆盖**：Claude Code 忽略覆盖，包括被阻止的系列别名，skill 或命令在会话模型上运行。[在子代理中运行](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent)的 skill 或命令遵循上面的子代理行为

permission-modes.md +1 −1

Details

50| 您想要 | 起步方式 | 所需隔离 | 说明 |50| 您想要 | 起步方式 | 所需隔离 | 说明 |

51| :- | :- | :- | :- |51| :- | :- | :- | :- |

52| 亲自审查每个操作 | 手动模式：`claude --permission-mode default` | 无 | 敏感工作、不熟悉的代码 |52| 亲自审查每个操作 | 手动模式：`claude --permission-mode default` | 无 | 敏感工作、不熟悉的代码 |

53| 在本地迭代，减少提示，且不使用分类器 | 手动模式加上处于[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#sandbox-modes)的 Bash 沙箱：`claude --permission-mode default`，然后运行 `/sandbox` 并选择自动允许 | 内置 Bash 沙箱，适用于 macOS、Linux 和 WSL2 | 拒绝规则仍然适用，指定了命令的询问规则（例如 `Bash(git push *)`）仍会提示。[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)介绍了其他可能触发提示的命令。若要改为通过设置文件启用沙箱，请将 [`sandbox.enabled`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-enabled) 设为 `true` |53| 在本地迭代，减少提示，且不使用分类器 | 手动模式加上处于[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#sandbox-modes)的 Bash 沙箱：`claude --permission-mode default`，然后运行 `/sandbox` 并选择自动允许 | 内置 Bash 沙箱，适用于 macOS、Linux 和 WSL2 | 拒绝规则仍然适用，指定了命令的询问规则（例如 `Bash(git push *)`）仍会提示。[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)介绍了其他可能触发提示的命令。若要改为通过设置文件启用沙箱，请将 [`sandbox.enabled`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-enabled) 和 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-autoallowbashifsandboxed) 设为 `true` |

54| 在进行任何更改之前先探索 | `claude --permission-mode plan` | 无 | 在您[批准计划](#review-and-approve-a-plan)之前，Claude Code 会阻止编辑 |54| 在进行任何更改之前先探索 | `claude --permission-mode plan` | 无 | 在您[批准计划](#review-and-approve-a-plan)之前，Claude Code 会阻止编辑 |

55| 在自动模式下免干预工作 | `claude --permission-mode auto`，即 v2.1.283 或更高版本的[内置起始权限模式](#which-mode-a-session-starts-in) | 无；沙箱或容器可提供纵深防御 | 需要[受支持的模型](#eliminate-prompts-with-auto-mode)，并且您的组织可以[关闭自动模式](#eliminate-prompts-with-auto-mode) |55| 在自动模式下免干预工作 | `claude --permission-mode auto`，即 v2.1.283 或更高版本的[内置起始权限模式](#which-mode-a-session-starts-in) | 无；沙箱或容器可提供纵深防御 | 需要[受支持的模型](#eliminate-prompts-with-auto-mode)，并且您的组织可以[关闭自动模式](#eliminate-prompts-with-auto-mode) |

56| 在 CI 中使用精确的允许列表运行 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | 除 CI 运行器所提供的隔离外无需其他隔离 | [云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)会忽略来自设置文件的 `dontAsk` |56| 在 CI 中使用精确的允许列表运行 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | 除 CI 运行器所提供的隔离外无需其他隔离 | [云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)会忽略来自设置文件的 `dontAsk` |

permissions.md +1 −1

Details

743 743

744使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](https://code.claude.com/docs/zh-CN/sandboxing.md#permission-rules)中。744使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](https://code.claude.com/docs/zh-CN/sandboxing.md#permission-rules)中。

745 745

746当您启用沙箱并将 `autoAllowBashIfSandboxed` 保留为其默认值 `true` 时，沙箱化的 Bash 命令无需提示即可运行，即使您的权限包括裸 `Bash` ask 规则，或[等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱边界替代了该整体工具提示。746当您启用沙箱隔离并将 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-autoallowbashifsandboxed) 设置为 `true` 时，沙箱化的 Bash 命令无需提示即可运行。即使存在裸 `Bash` ask 规则或[等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)，也是如此：沙箱边界替代了该整体工具提示。

747 747

748在[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)中，Claude Code 跳过此替代。没有 ask 规则时，[内置只读命令](#read-only-commands)仍然无需提示即可运行，任何其他 shell 命令在您仍在计划时通过常规权限流程；请参见[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)了解 Claude Code 如何在那里控制命令。使用裸 `Bash` ask 规则时，每个 Bash 命令都会提示，包括沙箱化的只读命令，与沙箱隔离之外相同。748在[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)中，Claude Code 跳过此替代。没有 ask 规则时，[内置只读命令](#read-only-commands)仍然无需提示即可运行，任何其他 shell 命令在您仍在计划时通过常规权限流程；请参见[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)了解 Claude Code 如何在那里控制命令。使用裸 `Bash` ask 规则时，每个 Bash 命令都会提示，包括沙箱化的只读命令，与沙箱隔离之外相同。

749 749

plugins/mods/interface.md +91 −2

Details

438 438

439* **`backdrop` 字段**：`scene` 是您为由您的 hook 绘制的背景选择的[名称](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#limits)。有关其他字段以及 `overrideColorScheme`，请参阅[适用于您所用版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)。439* **`backdrop` 字段**：`scene` 是您为由您的 hook 绘制的背景选择的[名称](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#limits)。有关其他字段以及 `overrideColorScheme`，请参阅[适用于您所用版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)。

440* **背景是否被绘制**：当连接到该会话的 Desktop 或移动应用表示它会绘制背景时，`$.theme.set` 以 `isDrawn: true` 解析。否则 `isDrawn` 为 `false`，`reason` 说明原因。440* **背景是否被绘制**：当连接到该会话的 Desktop 或移动应用表示它会绘制背景时，`$.theme.set` 以 `isDrawn: true` 解析。否则 `isDrawn` 为 `false`，`reason` 说明原因。

441* **每个会话一个背景**：无论背景是由哪个 mod 设置的，`$.theme.set` 调用都会替换会话的背景，`$.theme.clear()` 都会移除该背景。请仅在用户要求时调用 `$.theme.clear()`。441* **每个会话一个主题**：无论背景和[颜色](#change-the-colors-of-the-desktop-app)是由哪个 mod 设置的，调用 `$.theme.set` 的 mod 都会替换会话的背景和颜色，调用 `$.theme.clear()` 的 mod 都会移除它们。请仅在用户要求时调用 `$.theme.clear()`。

442

443### 更改 Desktop 应用的颜色

444

445要使用 mod 更改 Desktop 应用 Code 选项卡的颜色，请[让 Claude 编写一个](#ask-claude-for-a-colors-mod)或[自己编写一个](#write-a-colors-mod-yourself)。这两种方式都需要 Code 选项卡中的 Claude Code 为 v2.1.324 或更高版本，因此请先[在那里检查版本](https://code.claude.com/docs/zh-CN/desktop.md#claude-code-version-in-the-code-tab)。终端中的 Claude Code 会保留其自己的颜色。

446

447#### 让 Claude 编写颜色 mod

448

449**1. 描述颜色**

450

451在 Code 选项卡中启动一个本地会话，并告诉 Claude 您想要哪些颜色。例如，输入 `make a mod that makes the app cream in light mode and dark brown in dark mode`。Claude 会编写该 mod 的文件。

452

453**2. 批准 mod**

454

455回答 Claude Code 就该 mod 的文件和热重载提出的问题。有关每个回答的作用，请参阅[让 Claude 编写 mod](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#ask-claude-for-a-mod)。

456

457**3. 检查颜色**

458

459mod 加载后，Code 选项卡会改变颜色。要调整某种颜色，请告诉 Claude 要更改什么。如果没有任何变化，请参阅[修复缺失的 mod 颜色](#fix-missing-mod-colors-in-the-desktop-app)。

460

461#### 自己编写颜色 mod

462

463`makeColors` 是一个根据几个十六进制颜色构建主题的函数。以下步骤会创建一个使用它、名为 `paper` 的 mod。

464

465**1. 让 Claude 复制 makeColors**

466

467在 Code 选项卡中启动一个本地会话，然后输入 `copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/`。检查这两个文件是否都在该目录中。

468

469**2. 保存清单和 hooks.json**

470

471根据[自己编写 mod](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#write-a-mod-yourself)，将 `.claude-plugin/plugin.json` 和 `hooks/hooks.json` 保存到 `~/.claude/skills/paper/` 中，并在这两个文件中将 `first-mod` 改为 `paper`。[位于 `~/.claude/skills/` 下](https://code.claude.com/docs/zh-CN/plugins/create#scaffold-a-plugin-that-loads-every-session)的 mod 会在您启动会话时加载。

472

473**3. 编写代码**

474

475将此文件保存为 `~/.claude/skills/paper/hooks/register.js`。会话开始时，该代码会调用 `$.theme.set`，为浅色模式和深色模式设置颜色：

476

477```javascript theme={null}

478import { makeColors } from './make-colors.js'

479

480const { theme } = makeColors({

481 label: 'Paper',

482 // surface-0 is the background, text-primary is the main text, and text-muted is the faint text

483 light: {

484 gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },

485 },

486 dark: {

487 gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },

488 },

489})

490

491export function register(on) {

492 on('session.start', async ($, e, next) => {

493 await $.theme.set({ colors: theme })

494 return next(e)

495 })

496}

497```

498

499要使用您自己的颜色，请将这些十六进制值替换为其他六位十六进制颜色。

500

501**4. 检查颜色**

502

503在 Code 选项卡中启动一个新的本地会话。使用示例中的值时，背景在浅色模式下为奶油色，在深色模式下为深棕色。如果没有任何变化，请参阅[修复缺失的 mod 颜色](#fix-missing-mod-colors-in-the-desktop-app)。

504

505### 修复 Desktop 应用中缺失的 mod 颜色

506

507如果您在 [Claude Desktop v5.11492.5 或更早版本](https://code.claude.com/docs/zh-CN/desktop.md#check-your-version)中使用[第三方提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)而不是 Claude 账户，Code 选项卡会保留其自己的颜色，因此请跳过这些检查。否则，如果 mod 的颜色没有出现在 Code 选项卡中，或者颜色消失了，请检查以下原因：

508

509* **版本过旧**：[更新 Desktop 应用](https://code.claude.com/docs/zh-CN/desktop.md#claude-code-version-in-the-code-tab)，重启它，然后在 Code 选项卡中启动一个新的本地会话。如果该 mod 是由 Claude 编写的，请在那里再次请求。

510* **mod 未加载**：如果该 mod 是由 Claude 编写的，请在[让 Claude 编写 mod](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#ask-claude-for-a-mod) 中了解它何时加载。如果是您自己编写的，请将您的文件及其路径与[自己编写颜色 mod](#write-a-colors-mod-yourself) 进行比较。

511* **主题被拒绝**：请让 Claude 运行该 mod 的 [`makeColors`](#write-a-colors-mod-yourself) 调用。如果该调用抛出错误，或者其 `problems` 列表中有以 `Desktop won't paint this theme` 开头的条目，请让 Claude 修复该主题。如果该 mod 是您安装的，请将 Claude 发现的问题发送给其作者。

512* **另一个 `$.theme` 调用**：当会话中的任何 mod 调用 `$.theme.set` 或 `$.theme.clear()` 时，之前调用设置的颜色和[背景](#put-a-backdrop-behind-the-conversation)都会消失。在您自己的 mod 中，请在同一个 `$.theme.set` 调用中传递 `colors` 和 `backdrop`。一次只使用一个设置主题的 mod。

513

514### 从 Desktop 应用中移除 mod 颜色

515

516要从 Code 选项卡中移除 mod 的颜色，请先关闭该 mod。仍处于启用状态的 mod 可能会再次设置其颜色。

517

518**1. 关闭 mod**

519

520* **mod 由 Claude 编写**：将其目录移出 Claude 编写它时所在会话的 [mod 文件夹](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#ask-claude-for-a-mod)。

521* **您将 mod 放在 `~/.claude/skills/` 下**：将其目录（例如 `~/.claude/skills/paper/`）移到 `~/.claude/skills/` 之外的位置。

522* **您安装了该 mod**：在 Desktop 应用中，从 **Manage plugins** [停用或卸载其插件](https://code.claude.com/docs/zh-CN/desktop.md#install-plugins)。如果您看不到 **Manage plugins**，并且您已安装 [CLI](https://code.claude.com/docs/zh-CN/quickstart.md)，则可以[从 shell 停用或卸载市场插件](https://code.claude.com/docs/zh-CN/plugins/install.md#manage-plugins-from-your-shell)。

523

524**2. 启动新会话**

525

526在 Code 选项卡中启动一个新的本地会话。

527

528**3. 移除仍保留的颜色**

529

530如果颜色仍然存在，请从 Code 选项卡打开 **Settings**，并在其中搜索 `code appearance`。打开搜索结果，然后选择 **Remove colors**。

442 531

443## 从元素构建树532## 从元素构建树

444 533

677 766

678相同的按键，或在全屏渲染中点击该行，可以再次展开条带。在此之前，任何方式都无法按下其中的按钮：快捷键、在空输入框中键入的数字以及按钮 [`action`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#elements) 的快捷键均无效。如果用户折叠条带时条带拥有键盘焦点，焦点会返回到输入框，并且在条带折叠期间，Ctrl+X 然后按 Tab 会跳过条带。767相同的按键，或在全屏渲染中点击该行，可以再次展开条带。在此之前，任何方式都无法按下其中的按钮：快捷键、在空输入框中键入的数字以及按钮 [`action`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#elements) 的快捷键均无效。如果用户折叠条带时条带拥有键盘焦点，焦点会返回到输入框，并且在条带折叠期间，Ctrl+X 然后按 Tab 会跳过条带。

679 768

680条带会保持折叠状态直到用户展开它，即使在 `/clear` 之后也是如此，并会在下次启动 Claude Code 时重新展开。您的 mod 无法展开它，也无法得知它已折叠：`ui.render` hook 会继续运行，`e.props` 中也没有任何内容表明这一点。请不要让条带成为您的 mod 显示需要用户回应的内容的唯一位置。769条带会保持折叠状态直到用户展开它，即使在 `/clear` 之后也是如此，并会在下次启动 Claude Code 时重新展开。您的 mod 无法展开它。请不要让条带成为您的 mod 显示需要用户回应的内容的唯一位置。若要仅在条带折叠期间在其他位置显示这些内容，请在您的 `ui.render` hook 中读取 `e.props.isCollapsed`，该 hook 会继续运行。`isCollapsed` 需要 Claude Code v2.1.321 或更高版本。

681 770

682### 获取输入的文本并为每个项目绘制一行771### 获取输入的文本并为每个项目绘制一行

683 772

plugins/mods/reference.md +16 −3

Details

212 212

213其中一些事件也会针对 Claude Code 自身的操作触发，因此在拒绝某个事件之前，请先检查 `next.origin.plugin` 是否为 `engine`。213其中一些事件也会针对 Claude Code 自身的操作触发，因此在拒绝某个事件之前，请先检查 `next.origin.plugin` 是否为 `engine`。

214 214

215#### Claude Code 自身 `http.fetch` 请求上的字段

216

217在 `http.fetch` hook 中，值为 `{ plugin: 'engine', tier: 'core' }` 的 [`next.origin`](#the-hook-function) 标记的是 Claude Code 自身的请求（例如模型请求），而不是 mod 的 `$.http.fetch` 调用。在加载了[内置守卫](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#know-what-happens-by-default)的情况下，您的 hook 不会收到这些事件，除非您的 mod [被视为您组织的 mod](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#install-your-organizations-mods)。

218

219在这些事件中，`e.init` 以及 `next(e)` 解析得到的 `value` 可以包含以下字段等：

220

221| 字段 | 含义 |

222| :- | :- |

223| `e.init.compress` | 当 Claude Code 在您的 hook 之后压缩请求体时设置。`e.init.body` 包含未压缩的请求体。要以未压缩形式发送请求体，请调用 `next({ ...e, init: { ...e.init, compress: undefined } })`。 |

224| `value.isStreaming` | 设为 `true`，因为 Claude Code 会自行读取响应体，所以 `value.text` 为空。请改为读取 `value.status` 和 `value.headers`。要使用您自己的 `text` 应答，请返回不带 `isStreaming` 的 `value`。 |

225

226这些事件和字段需要 Claude Code v2.1.321 或更高版本。

227

215## mods API 方法228## mods API 方法

216 229

217mods API 是每个 hook 接收的 `$` 参数。它的方法按命名空间分组，例如 `$.ui`。此表按名称列出每个命名空间的方法，因此 `$.ui` 行中的 `open` 就是调用 `$.ui.open(...)`。指南展示了常用方法的用法，而[您的构建版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)记录了每个方法并附有示例。230mods API 是每个 hook 接收的 `$` 参数。它的方法按命名空间分组，例如 `$.ui`。此表按名称列出每个命名空间的方法，因此 `$.ui` 行中的 `open` 就是调用 `$.ui.open(...)`。指南展示了常用方法的用法，而[您的构建版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)记录了每个方法并附有示例。

222| [`$.ui`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更高版本，`place` 需要 v2.1.314 或更高版本。 |235| [`$.ui`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更高版本，`place` 需要 v2.1.314 或更高版本。 |

223| [`$.theme`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：设置一个由 Desktop 或移动应用绘制的背景，以及移除该背景。需要 Claude Code v2.1.319 或更高版本。 |236| [`$.theme`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：设置一个由 Desktop 或移动应用绘制的背景，以及移除该背景。需要 Claude Code v2.1.319 或更高版本。 |

225| [`$.tool`](https://code.claude.com/docs/zh-CN/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list` |238| [`$.tool`](https://code.claude.com/docs/zh-CN/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list`。当某次 `call` 需要人工批准时（例如 hook 或您的组织以 `ask` 回应的调用），它会解析为 `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`，其中 `<tool>` 是该工具的名称。 |

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

228| [`$.prompt`](https://code.claude.com/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 })` 将文本作为用户自己的话发送，不带那句话。 |241| [`$.prompt`](https://code.claude.com/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 })` 将文本作为用户自己的话发送，不带那句话。 |

250| 位置 | `e.props` | `e.requestId` | 渲染于 |263| 位置 | `e.props` | `e.requestId` | 渲染于 |

251| :- | :- | :- | :- |264| :- | :- | :- | :- |

253| [`AbovePrompt`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`、`isWorking`、`maxRows`、`bodyColumns`、`scroll`、`view` | 单一实例 | 终端、Desktop |266| [`AbovePrompt`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`、[`isCollapsed`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#when-the-user-collapses-the-band)、`isWorking`、`maxRows`、`bodyColumns`、`scroll`、`view` | 单一实例 | 终端、Desktop |

254| `AbovePromptList`，即由 `AbovePrompt` 行组成的堆栈 | `rows`，一个列表，其中每个 mod 的行对应一个 `{ plugin, tree }`，外加 `AbovePrompt` 的 prop | 单一实例 | 终端、Desktop。需要 Claude Code v2.1.323 或更高版本。 |267| `AbovePromptList`，即由 `AbovePrompt` 行组成的堆栈 | `rows`，一个列表，其中每个 mod 的行对应一个 `{ plugin, tree }`，外加 `AbovePrompt` 的 prop | 单一实例 | 终端、Desktop。需要 Claude Code v2.1.323 或更高版本。 |

256| [`Backdrop`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。在 v2.1.323 之前，`scene` 为 `id`，`overrideColorScheme` 为 `colorScheme`。 | `backdrop` | `desktop` 和 `mobile` 使用入口。当 Desktop 或移动应用请求绘制背景时，您的 hook 会运行。 |269| [`Backdrop`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。在 v2.1.323 之前，`scene` 为 `id`，`overrideColorScheme` 为 `colorScheme`。 | `backdrop` | `desktop` 和 `mobile` 使用入口。当 Desktop 或移动应用请求绘制背景时，您的 hook 会运行。 |

426| 名称 | 位置 | 作用 |439| 名称 | 位置 | 作用 |

427| :- | :- | :- |440| :- | :- | :- |

430| `prependPlugins`, `appendPlugins` | 托管设置。仅在没有托管设置或 [`managed-mcp.json`](https://code.claude.com/docs/zh-CN/managed-mcp#deploy-managed-mcp-json) 文件的机器上、且会话的凭据不是 Team 或 Enterprise `/login` 时，才可在用户设置中使用。 | 插件 id 列表，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 在用户安装的每个 mod 之前运行，`appendPlugins` 中的 mod 在之后运行，均按列出的顺序。请参阅 [mod 运行顺序](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#the-order-mods-run-in)。 |443| `prependPlugins`, `appendPlugins` | 托管设置。仅在没有托管设置或 [`managed-mcp.json`](https://code.claude.com/docs/zh-CN/managed-mcp#deploy-managed-mcp-json) 文件的机器上、且会话的凭据不是 Team 或 Enterprise `/login` 时，才可在用户设置中使用。 | 插件 id 列表，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 在用户安装的每个 mod 之前运行，`appendPlugins` 中的 mod 在之后运行，均按列出的顺序。请参阅 [mod 运行顺序](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#the-order-mods-run-in)。 |

431| `allowManagedModsOnly` | 托管设置，作为[内置守卫的选项](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 只有[算作您组织的](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#install-your-organizations-mods) mod 以及 Claude Code 内置的 mod 会运行其 hook。用户的设置 hook 会继续运行。 |444| `allowManagedModsOnly` | 托管设置，作为[内置守卫的选项](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 只有[算作您组织的](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#install-your-organizations-mods) mod 以及 Claude Code 内置的 mod 会运行其 hook。用户的设置 hook 会继续运行。 |

432| `allowModsToOverrideDenyRules` | 托管设置，作为[内置守卫的选项](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 允许用户安装的 mod 批准工具调用，越过大多数[默认保持有效的结果](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)，包括 `deny` 规则 |445| `allowModsToOverrideDenyRules` | 托管设置，作为[内置守卫的选项](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 允许用户安装的 mod 批准工具调用，越过大多数[默认保持有效的结果](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)，包括 `deny` 规则 |

plugins/mods/test.md +3 −4

Details

115 115

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

117 117

118测试工具包有一些自己的规则，违反其中一个会产生新测试作者首先遇到的错误：

~~119~~

120* **在测试对 `$` 的第一次调用之前注册每个 stub。** 在那之后调用 `on` 会抛出一个错误，例如 `on("ui.render") after the test first called $`。118* **在测试对 `$` 的第一次调用之前注册每个 stub。** 在那之后调用 `on` 会抛出一个错误，例如 `on("ui.render") after the test first called $`。

121 119

122* **[`session.start`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) 不会自己运行。** 每个测试都以您的模块新加载开始，其 hooks 都没有被调用，因此模块级变量保持其初始值。如果 hook 依赖于 `session.start` 设置的内容，请先触发它：120* **[`session.start`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) 不会自己运行。** 每个测试都以您的模块新加载开始，其 hooks 都没有被调用，因此模块级变量保持其初始值。如果 hook 依赖于 `session.start` 设置的内容，请先触发它：

132 130

133 第二个 stub 回答 `session.start` hook（例如 [tutorial](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#write-a-mod-yourself) 中的那个）进行的 `$.command.register` 调用。没有它，该调用会以 `no implementation for command.register` 拒绝，工具包会跳过您的 hook，因此 hook 中调用后的任何内容都不会运行。测试在那一点不会失败。仅当稍后的检查失败时，跳过的 hook 才会在 `the engine reported:` 下列出。131 第二个 stub 回答 `session.start` hook（例如 [tutorial](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#write-a-mod-yourself) 中的那个）进行的 `$.command.register` 调用。没有它，该调用会以 `no implementation for command.register` 拒绝，工具包会跳过您的 hook，因此 hook 中调用后的任何内容都不会运行。测试在那一点不会失败。仅当稍后的检查失败时，跳过的 hook 才会在 `the engine reported:` 下列出。

134 132

135* **返回 `next(e)` 的 hook 需要一个 stub 来回答。** 例如，当您的 [`ui.render`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#interface) hook 返回 `next(e)` 时，为了在 Claude 空闲时不绘制任何内容，[mounting it](#test-a-drawing) 会失败并显示 `no implementation for ui.render`。注册一个返回元素作为纯数据的 stub：133* **注册一个 `ui.render` stub 来选择 `next(e)` 返回的内容。** 当您的 [`ui.render`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#interface) hook 返回 `next(e)` 时（例如为了在 Claude 空闲时不绘制任何内容），即使没有 stub，[mount](#test-a-drawing) 也会成功。要让 `next(e)` 返回您选定的元素，请注册一个以纯数据形式返回该元素的 stub：

136 134

137 ```typescript theme={null}135 ```typescript theme={null}

138 // Stands for what Claude Code would draw at the site136 // Stands for what Claude Code would draw at the site

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))137 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```138 ```

141 139

142 注册 stub 后，mount 成功，`ui.find({ type: 'Text' })` 在您的 hook 返回 `next(e)` 时返回该元素。在 v2.1.323 或更高版本中，对于 band，请将您的 mod 名称作为第二个参数传给 `on`，例如 `{ plugin: 'my-mod' }`。如果不传，该 stub 不会回答您的 `next(e)`。140 在该位置[可以绘制该元素](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#change-what-claude-code-already-draws)的情况下，`ui.find({ type: 'Text' })` 会在您的 hook 返回 `next(e)` 时返回该元素。在 v2.1.323 或更高版本中，对于 band，请将您的 mod 名称作为第二个参数传给 `on`，例如 `{ plugin: 'my-mod' }`。如果不传，该 stub 不会回答您的 `next(e)`。在 v2.1.321 之前，除非您注册该 stub，否则 mount 会失败并显示 `no implementation for ui.render`。

143 141

144* **`turn.step` 的 stub 是一个异步生成器**，测试读取流到其末尾以获得结果：142* **`turn.step` 的 stub 是一个异步生成器**，测试读取流到其末尾以获得结果：

145 143

316| `press({ key: 'more' })` | 按下具有该 key 的 `Button` |314| `press({ key: 'more' })` | 按下具有该 key 的 `Button` |

317| `input({ key: 'new-note', text: 'buy milk' })` | 将文本输入到具有该 key 的 `Input` 中并按 Enter。添加 `kind: 'change'` 以输入而不提交。对于带有 `rows` 的字段，文本中可以包含 `\n`。 |315| `input({ key: 'new-note', text: 'buy milk' })` | 将文本输入到具有该 key 的 `Input` 中并按 Enter。添加 `kind: 'change'` 以输入而不提交。对于带有 `rows` 的字段，文本中可以包含 `\n`。 |

318| `select({ key: 'size', value: 'large' })` | 在具有该 key 的 `Select` 中选择具有该值的选项 |316| `select({ key: 'size', value: 'large' })` | 在具有该 key 的 `Select` 中选择具有该值的选项 |

317| `keepsBeneath()` | 在没有 `ui.render` stub 的测试中，当绘图包含 `next(e)` 返回的内容时，它解析为 `true`；当您的 hook 将其省略时，解析为 `false`。在注册了 stub 的测试中，请使用 `find` 查找该 stub 绘制的内容。需要 Claude Code v2.1.321 或更高版本。 |

319| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一个匹配的元素作为 `{ type, props, children }`，或 `undefined`。`text` 可以是字符串或正则表达式。 |318| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一个匹配的元素作为 `{ type, props, children }`，或 `undefined`。`text` 可以是字符串或正则表达式。 |

321 320

sandbox-environments.md +1 −1

Details

41 41

42| 您想要 | 开始使用 |42| 您想要 | 开始使用 |

43| :- | :- |43| :- | :- |

45| 让 Claude 使用 `--dangerously-skip-permissions` 或自动模式无人值守工作 | 预配置的 [dev container](https://code.claude.com/docs/zh-CN/devcontainer.md)、任何容器或虚拟机，或 [sandbox runtime](#sandbox-runtime) |45| 让 Claude 使用 `--dangerously-skip-permissions` 或自动模式无人值守工作 | 预配置的 [dev container](https://code.claude.com/docs/zh-CN/devcontainer.md)、任何容器或虚拟机，或 [sandbox runtime](#sandbox-runtime) |

46| 隔离 MCP 服务器和 hooks 以及 Bash，不使用 Docker | sandbox runtime |46| 隔离 MCP 服务器和 hooks 以及 Bash，不使用 Docker | sandbox runtime |

47| 在团队中标准化沙箱环境 | 预配置的 [dev container](https://code.claude.com/docs/zh-CN/devcontainer.md)，复制到您的存储库中 |47| 在团队中标准化沙箱环境 | 预配置的 [dev container](https://code.claude.com/docs/zh-CN/devcontainer.md)，复制到您的存储库中 |

sandboxing.md +4 −7

Details

6 6

7> 使用内置沙箱限制 Claude Code 的 shell 命令可以访问的文件和网络主机。启用沙箱、设置边界，并修复它导致的问题。7> 使用内置沙箱限制 Claude Code 的 shell 命令可以访问的文件和网络主机。启用沙箱、设置边界，并修复它导致的问题。

8 8

9Bash 沙箱是操作系统围绕 Claude 在您的计算机上运行的 shell 命令强制执行的边界。您可以设置这些命令可以访问哪些文件和网络域，这些限制适用于 Bash、PowerShell 和 Monitor 命令及其启动的进程。由于操作系统会在命令运行时应用这些限制，Claude Code 可以[运行沙箱化命令而无需询问您](#sandbox-modes)逐一批准。9Bash 沙箱是操作系统围绕 Claude 在您的计算机上运行的 shell 命令强制执行的边界。您可以设置这些命令可以访问哪些文件和网络域，这些限制适用于 Bash、PowerShell 和 Monitor 命令及其启动的进程。沙箱化命令仍会经过常规的权限流程，除非您选择[自动允许模式](#sandbox-modes)，该模式可以在不询问您的情况下运行这些命令。

10 10

11沙箱仅涵盖 shell 命令。Claude 的文件工具、MCP 服务器和 hook [在沙箱之外运行](#what-runs-outside-the-sandbox)。11沙箱仅涵盖 shell 命令。Claude 的文件工具、MCP 服务器和 hook [在沙箱之外运行](#what-runs-outside-the-sandbox)。

12 12

395| 以掩码方式应用的 [`credentials.files` `mask` 条目](#mask-credential-files) | 强制执行：掩码独立于文件系统层。[已回退为 `deny`](#mask-credential-files) 的条目与任何 `deny` 条目一样不强制执行 |395| 以掩码方式应用的 [`credentials.files` `mask` 条目](#mask-credential-files) | 强制执行：掩码独立于文件系统层。[已回退为 `deny`](#mask-credential-files) 的条目与任何 `deny` 条目一样不强制执行 |

396 396

397另外还有两项变化：397沙箱命令还会继承您 shell 的 `$TMPDIR`，而不是每用户临时目录，因为所有临时目录都可写，Claude Code 不再将命令重定向到每用户临时目录。

398 398

399* 沙箱命令会继承您 shell 的 `$TMPDIR`，而不是每用户临时目录，因为所有临时目录都可写，Claude Code 不再将命令重定向到每用户临时目录。399在 Linux 上，父 shell 中通常未设置该变量。Bash 工具指引会告诉 Claude 使用 `mktemp -d` 创建临时工作目录，而不是依赖 `$TMPDIR`。

~~400~~

401 在 Linux 上，父 shell 中通常未设置该变量。Bash 工具指引会告诉 Claude 使用 `mktemp -d` 创建临时工作目录，而不是依赖 `$TMPDIR`。

402* [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-autoallowbashifsandboxed) 默认仍为 `true`，因此沙箱命令会继续在无确认提示的情况下运行。将其设置为 `false` 可对沙箱命令进行确认提示。

403 400

404### 保护凭据401### 保护凭据

405 402

1095}1092}

1096```1093```

1097 1094

1098这会启用[自动允许模式](#sandbox-modes)。如需使用常规权限模式，还需将 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-autoallowbashifsandboxed) 设置为 `false`。该更改会在 Claude 运行下一条 shell 命令时在您正在运行的会话中生效，随后 `/sandbox` 的 **Mode** 选项卡会标记当前生效的模式。1095这会启用[常规权限模式](#sandbox-modes)。如需使用自动允许模式，还需将 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-autoallowbashifsandboxed) 设置为 `true`。该更改会在 Claude 运行下一条 shell 命令时在您正在运行的会话中生效，随后 `/sandbox` 的 **Mode** 选项卡会标记当前生效的模式。

1099 1096

1100## 限制1097## 限制

1101 1098

security.md +2 −2

Details

25 25

26为了降低代理系统中的风险：26为了降低代理系统中的风险：

27 27

28* **沙箱化 bash 工具**：使用文件系统和网络隔离的 [Sandbox](https://code.claude.com/docs/zh-CN/sandboxing.md) bash 命令，减少权限提示同时保持安全性。使用 `/sandbox` 配置以定义 Claude Code 可以自主工作的边界28* **沙箱化 Bash 工具**：通过文件系统和网络隔离对 Bash 命令进行[沙箱](https://code.claude.com/docs/zh-CN/sandboxing.md)处理。使用 `/sandbox` 进行配置

29* **工作目录边界**：在 Manual mode 中，Claude Code 的文件工具在读取或写入启动它的文件夹及其子文件夹之外的内容之前会先询问您。该边界是一个权限提示，因此您批准的 Bash 命令仍然可以写入您的用户账户有权写入的任何位置29* **工作目录边界**：在 Manual mode 中，Claude Code 的文件工具在读取或写入启动它的文件夹及其子文件夹之外的内容之前会先询问您。该边界是一个权限提示，因此您批准的 Bash 命令仍然可以写入您的用户账户有权写入的任何位置

30 * 要在没有提示的情况下读取某个文件夹，请将其添加为[额外目录](https://code.claude.com/docs/zh-CN/permissions.md#working-directories)30 * 要在没有提示的情况下读取某个文件夹，请将其添加为[额外目录](https://code.claude.com/docs/zh-CN/permissions.md#working-directories)

31 * 要在操作系统层面限制 Bash 命令，请启用[沙箱隔离](https://code.claude.com/docs/zh-CN/sandboxing.md#filesystem-isolation)31 * 要在操作系统层面限制 Bash 命令，请启用[沙箱隔离](https://code.claude.com/docs/zh-CN/sandboxing.md#filesystem-isolation)

62* **信任验证**：在交互式会话中，当您在尚未信任的文件夹中启动 Claude Code 时，它会显示工作区信任对话框。项目 `.mcp.json` 中的服务器有其单独的批准提示，[项目作用域](https://code.claude.com/docs/zh-CN/mcp.md#project-scope) 列出了跳过该提示的会话62* **信任验证**：在交互式会话中，当您在尚未信任的文件夹中启动 Claude Code 时，它会显示工作区信任对话框。项目 `.mcp.json` 中的服务器有其单独的批准提示，[项目作用域](https://code.claude.com/docs/zh-CN/mcp.md#project-scope) 列出了跳过该提示的会话

63 * 注意：`-p` 会话不会显示上述任何一种提示。[信任文件夹之前会运行什么](https://code.claude.com/docs/zh-CN/permissions.md#what-runs-before-you-trust-a-folder) 列出了仓库中的文件在此情况下可以运行的内容63 * 注意：`-p` 会话不会显示上述任何一种提示。[信任文件夹之前会运行什么](https://code.claude.com/docs/zh-CN/permissions.md#what-runs-before-you-trust-a-folder) 列出了仓库中的文件在此情况下可以运行的内容

64 * 注意：当您直接在主目录中启动 Claude Code 时，信任接受仅在当前会话期间保持，不会写入磁盘，因此提示在每次启动时都会重新出现。没有设置可以持久化它。请从项目子目录启动 Claude Code，其中信任接受按目录保存64 * 注意：当您直接在主目录中启动 Claude Code 时，信任接受仅在当前会话期间保持，不会写入磁盘，因此提示在每次启动时都会重新出现。没有设置可以持久化它。请从项目子目录启动 Claude Code，其中信任接受按目录保存

65* **命令注入检测**：在手动模式下，Claude Code 在运行无法完全分析的 Bash 命令之前会先询问。针对命令一部分的允许规则（如 `Bash(git *)`）不会跳过该提示。[沙箱隔离的命令](https://code.claude.com/docs/zh-CN/permissions.md#how-permissions-interact-with-sandboxing)可以在没有该提示的情况下运行65* **命令注入检测**：在手动模式下，Claude Code 在运行无法完全分析的 Bash 命令之前会先询问。针对命令一部分的允许规则（如 `Bash(git *)`）不会跳过该提示。处于[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)下的[沙箱隔离的命令](https://code.claude.com/docs/zh-CN/permissions.md#how-permissions-interact-with-sandboxing)可以在没有该提示的情况下运行

66* **故障关闭匹配**：在手动模式下，不匹配的命令默认需要批准66* **故障关闭匹配**：在手动模式下，不匹配的命令默认需要批准

67* **安全凭据存储**：API 密钥和令牌在可用时存储在 macOS Keychain 中。在 Linux 上，它们存储在模式为 `0600` 的文件中；在 Windows 上，它们存储在继承您用户配置文件目录访问控制的文件中。请参阅 [Credential Management](https://code.claude.com/docs/zh-CN/authentication.md#credential-management)67* **安全凭据存储**：API 密钥和令牌在可用时存储在 macOS Keychain 中。在 Linux 上，它们存储在模式为 `0600` 的文件中；在 Windows 上，它们存储在继承您用户配置文件目录访问控制的文件中。请参阅 [Credential Management](https://code.claude.com/docs/zh-CN/authentication.md#credential-management)

68 68

settings-reference.md +14 −14

Details

1355 1355

1356### `sandbox.autoAllowBashIfSandboxed`1356### `sandbox.autoAllowBashIfSandboxed`

1357 1357

1358让 Claude Code 在没有权限提示的情况下运行沙箱化的 Bash 命令。无法在沙箱中运行的命令仍会走常规权限流程，`deny` 规则和限定内容的 `ask` 规则（例如 `Bash(git push *)`）仍然适用；单独的 `Bash` ask 规则对沙箱化命令会被跳过。将其设置为 `false` 可让沙箱化命令也走常规权限流程，`/sandbox` 的 **Mode** 选项卡将此称为常规权限模式。1358让 Claude Code 无需权限提示即可运行沙箱化的 Bash 命令。无法在沙箱中运行的命令仍会经过常规权限流程。`deny` 规则以及限定内容的 `ask` 规则（例如 `Bash(git push *)`）仍然适用，但对于沙箱化命令，会跳过单纯的 `Bash` ask 规则。如需在托管设置中将其设为 `true`，请将其添加到您[排名最高的托管来源](https://code.claude.com/docs/zh-CN/managed-settings.md#how-claude-code-combines-managed-sources)的 `sandbox` 块中。

1359 1359

1360* **作用域**：[`Any file`](#scopes)1360* **作用域**：[`Any file`](#scopes)

1361* **类型**：布尔值1361* **类型**：布尔值

1362 * `true`：Claude Code 在没有权限提示的情况下运行沙箱化的 Bash 命令，[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)中描述的情况除外；`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 会关闭自动允许1362 * `true`：Claude Code 在没有权限提示的情况下运行沙箱化的 Bash 命令，[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)中描述的情况除外；`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 会关闭自动允许

1363 * `false`：沙箱化命令走常规权限流程，由您的允许规则和权限模式决定。`/sandbox` 的 **Mode** 选项卡将此称为常规权限模式1363 * `false`：沙箱化命令走常规权限流程，由您的允许规则和权限模式决定。`/sandbox` 的 **Mode** 选项卡将此称为常规权限模式

1364* **默认值**：`true`1364* **默认值**：`false`。在 v2.1.324 之前，默认值为 `true`

1365 1365

1366以下配置保持沙箱启用，并让沙箱化命令走常规权限流程：1366如需保持沙箱启用并在无权限提示的情况下运行沙箱化命令，请在 `sandbox` 块中同时设置这两个键：

1367 1367

1368```json settings.json theme={null}1368```json settings.json theme={null}

1369{1369{

1370 "sandbox": {1370 "sandbox": {

1371 "enabled": true,1371 "enabled": true,

1372 "autoAllowBashIfSandboxed": false1372 "autoAllowBashIfSandboxed": true

1373 }1373 }

1374}1374}

1375```1375```

1653}1653}

1654```1654```

1655 1655

1656关闭该层后，Claude Code 不会强制执行 `denyRead` 或 `credentials.files` 的 `deny` 条目，而 `credentials.envVars` 条目和已应用的 `mask` 条目仍然有效。[`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) 仍默认为 `true`，因此请将其设置为 `false` 以继续显示提示。有关可以设置它的完整来源列表以及关闭隔离后的变化，请参阅[禁用文件系统隔离](https://code.claude.com/docs/zh-CN/sandboxing.md#disable-filesystem-isolation)。1656关闭该层后，Claude Code 不会强制执行 `denyRead` 或 `credentials.files` 的 `deny` 条目，而 `credentials.envVars` 条目和已应用的 `mask` 条目仍然有效。有关可以设置它的完整来源列表以及关闭隔离后的变化，请参阅[禁用文件系统隔离](https://code.claude.com/docs/zh-CN/sandboxing.md#disable-filesystem-isolation)。

1657 1657

1658### `sandbox.ignoreViolations`1658### `sandbox.ignoreViolations`

1659 1659

4870 4870

4871### `agentPushNotifEnabled`4871### `agentPushNotifEnabled`

4872 4872

4873允许 Claude 在认为值得发送时向您的手机发送推送通知，例如在长时间任务完成时。在本地会话中，Claude 可以在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 已连接时发送通知。在 `/config` 中显示为 **Push when Claude decides**。在该处更改时，Claude Code 还会将该值保存到您的账户。4873允许 Claude 在认为值得发送时向您的手机发送推送通知，例如在长时间任务完成时。在本地会话中，Claude 可以在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 已连接时发送通知。在 `/config` 中显示为 **Push when Claude decides**。

4874 4874

4875* **作用域**：[`Any file`](#scopes)。Claude Code 也会读取旧版本遗留在 `~/.claude.json` 中的值。4875* **作用域**：[`Any file`](#scopes)。Claude Code 也会读取旧版本遗留在 `~/.claude.json` 中的值。

4876* **类型**：Boolean4876* **类型**：Boolean

4884}4884}

4885```4885```

4886 4886

4887如果您在 [`claude remote-control`](https://code.claude.com/docs/zh-CN/remote-control#start-a-remote-control-session) 服务器下运行会话，这些会话将遵循保存在您账户中的值，而不是此设置项。要更改该值，请在终端的 Claude Code 会话中运行 `/config`，并打开或关闭 **Push when Claude decides**。如果开关已显示您想要的值，请先更改再改回，以便 Claude Code 将该值保存到您的账户。4887仅凭此设置项您不会收到通知。要进行设置，请按照[移动推送通知](https://code.claude.com/docs/zh-CN/remote-control.md#mobile-push-notifications)中的步骤操作。

4888 4888

4889请参阅 [移动推送通知](https://code.claude.com/docs/zh-CN/remote-control.md#mobile-push-notifications)。4889如果您在 [`claude remote-control`](https://code.claude.com/docs/zh-CN/remote-control#start-a-remote-control-session) 服务器下运行会话，这些会话将遵循保存在您账户中的值，而不是此设置项。要更改该值，请在终端的 Claude Code 会话中运行 `/config`，并打开或关闭 **Push when Claude decides**。如果开关已显示您想要的值，请先更改再改回，以便 Claude Code 将该值保存到您的账户。

4890 4890

4891### `awaySummaryEnabled`4891### `awaySummaryEnabled`

4892 4892

5043}5043}

5044```5044```

5045 5045

5046请参阅 [移动推送通知](https://code.claude.com/docs/zh-CN/remote-control.md#mobile-push-notifications)。5046仅凭此设置项您不会收到通知。要进行设置，请按照[移动推送通知](https://code.claude.com/docs/zh-CN/remote-control.md#mobile-push-notifications)中的步骤操作。

5047 5047

5048### `preferredNotifChannel`5048### `preferredNotifChannel`

5049 5049

5421 5421

5422### `minimumVersion`5422### `minimumVersion`

5423 5423

5424阻止后台自动更新和 `claude update` 安装低于此版本的任何版本，这样切换到 `"stable"` 渠道时不会使您从较新的 `"latest"` 构建版本降级。当您在 `/config` 中切换渠道并选择保留当前版本时，Claude Code 会自动为您写入此键；当您切换回 `"latest"` 时则会清除它。5424阻止后台自动更新和 `claude update` 安装低于您所设置版本的任何版本。当您在 `/config` 中切换渠道并选择保留当前版本时，Claude Code 会自动为您写入此键。当您在 `/config` 中切换回 `"latest"` 时，Claude Code 会清除此键。

5425 5425

5426* **作用域**：[`Any file`](#scopes)。在托管设置中设置此项，可固定一个用户设置和项目设置无法调低的组织级最低版本。5426* **作用域**：[`Any file`](#scopes)。在托管设置中设置此键，可固定一个用户设置和项目设置无法覆盖的组织级最低版本。

5427* **类型**：字符串，即版本号，例如 `"2.1.100"`；无效的版本值将被忽略5427* **类型**：字符串，即版本号，例如 `"2.1.323"`；无效的版本值将被忽略

5428* **默认值**：未设置，因此更新可以安装该渠道提供的任何版本5428* **默认值**：未设置，因此更新可以安装该渠道提供的任何版本

5429 5429

5430以下示例遵循 stable 渠道，并拒绝安装低于 2.1.100 的任何版本：5430以下示例遵循 stable 渠道，并拒绝安装低于 2.1.323 的任何版本：

5431 5431

5432```json settings.json theme={null}5432```json settings.json theme={null}

5433{5433{

5434 "autoUpdatesChannel": "stable",5434 "autoUpdatesChannel": "stable",

5435 "minimumVersion": "2.1.100"5435 "minimumVersion": "2.1.323"

5436}5436}

5437```5437```

5438 5438

setup.md +19 −10

Details

40>40>

41> **macOS、Linux、WSL：**41> **macOS、Linux、WSL：**

42>42>

~~43> ```bash theme={null}~~43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell：**49> **Windows PowerShell：**

50>50>

~~51> ```powershell theme={null}~~51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD：**55> **Windows CMD：**

56>56>

~~57> ```batch theme={null}~~57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72

73> [tab] Homebrew73> [tab] Homebrew

74>74>

~~75> ```bash theme={null}~~75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84

85> [tab] WinGet85> [tab] WinGet

86>86>

~~87> ```powershell theme={null}~~87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

220}220}

221```221```

222 222

223使用此设置时，即使 stable 版本比您当前的版本更旧，原生安装也会更新到该 stable 版本。为避免降级，请同时[固定最低版本](#pin-a-minimum-version)。

224

223新发布的模型可能需要比 stable 渠道所提供版本更新的 Claude Code 版本。要立即运行该模型，请切换到 latest 渠道。225新发布的模型可能需要比 stable 渠道所提供版本更新的 Claude Code 版本。要立即运行该模型，请切换到 latest 渠道。

224 226

225对于企业部署，您可以使用[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)在整个组织中强制执行一致的发布渠道。227对于企业部署，您可以使用[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)在整个组织中强制执行一致的发布渠道。

230 232

231### 固定最低版本233### 固定最低版本

232 234

233`minimumVersion` 设置建立了一个下限。后台自动更新和 `claude update` 拒绝安装低于此值的任何版本，因此如果您已经在较新的 `"latest"` 构建上，切换到 `"stable"` 渠道不会降级您。235要将原生安装切换到 `"stable"` [发布渠道](#configure-release-channel)而不降级，请将 [`minimumVersion`](https://code.claude.com/docs/zh-CN/settings-reference#minimumversion) 设置为您正在运行的版本。后台自动更新和 `claude update` 会拒绝安装低于该最低版本的任何版本。

236

237您可以在 `/config` 中设置最低版本，让 Claude Code 自动填入您的当前版本；也可以在设置文件中自行输入版本号：

234 238

235通过 `/config` 从 `"latest"` 切换到 `"stable"` 会提示您选择保留当前版本或允许降级。选择保留会将 `minimumVersion` 设置为该版本。切换回 `"latest"` 会清除它。239* **在 `/config` 中**：将**自动更新渠道**切换为 stable，然后选择**保留当前版本**。如果您在 `/config` 中切换回 latest，Claude Code 会清除该最低版本。

240* **在您的[设置文件](https://code.claude.com/docs/zh-CN/settings.md)中**：在您的 shell 中运行 `claude --version`，并将 `minimumVersion` 设置为输出开头的版本号。在同一次编辑中，将 `autoUpdatesChannel` 设置为 `"stable"`。

236 241

237将其添加到您的 [settings.json 文件](https://code.claude.com/docs/zh-CN/settings.md)以显式固定下限：242以下 `~/.claude/settings.json` 会将版本为 2.1.323 的安装切换到 stable：

238 243

239```json theme={null}244```json theme={null}

240{245{

241 "autoUpdatesChannel": "stable",246 "autoUpdatesChannel": "stable",

242 "minimumVersion": "2.1.100"247 "minimumVersion": "2.1.323"

243}248}

244```249```

245 250

246在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中，这会强制执行用户和项目设置无法覆盖的组织范围最低版本。251该安装会保持在 2.1.323，直到 stable 渠道提供更新的版本。

252

253#### 为您的组织设置版本限制

254

255在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中，`minimumVersion` 会强制执行用户和项目设置无法覆盖的组织范围最低版本。

247 256

248`minimumVersion` 固定仅约束更新。要使 Claude Code 拒绝在版本范围外启动，请改为使用托管设置 `requiredMinimumVersion` 和 `requiredMaximumVersion`。更新也会遵守 `requiredMaximumVersion` 上限。请参阅 [`requiredMinimumVersion`](https://code.claude.com/docs/zh-CN/settings-reference#requiredminimumversion) 和 [`requiredMaximumVersion`](https://code.claude.com/docs/zh-CN/settings-reference#requiredmaximumversion)。257`minimumVersion` 固定仅约束更新。要使 Claude Code 拒绝在版本范围外启动，请改为使用托管设置 `requiredMinimumVersion` 和 `requiredMaximumVersion`。更新也会遵守 `requiredMaximumVersion` 上限。请参阅 [`requiredMinimumVersion`](https://code.claude.com/docs/zh-CN/settings-reference#requiredminimumversion) 和 [`requiredMaximumVersion`](https://code.claude.com/docs/zh-CN/settings-reference#requiredmaximumversion)。

249 258

skills.md +4 −2

Details

22 22

23Claude Code 包含一组捆绑技能，例如 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。捆绑技能是基于提示的：它们为 Claude 提供详细的指令，让它使用其工具来协调工作。大多数内置命令则直接执行固定逻辑。23Claude Code 包含一组捆绑技能，例如 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。捆绑技能是基于提示的：它们为 Claude 提供详细的指令，让它使用其工具来协调工作。大多数内置命令则直接执行固定逻辑。

24 24

25输入 `/` 后跟 skill 名称即可调用随附 skill。Claude 在相关时会自动调用某些随附 skill；其他 skill（包括 [`/verify`](#run-and-verify-your-app)）仅在您调用它们时运行。25输入 `/` 后跟 skill 名称即可调用随附 skill。Claude 在相关时会自动调用某些随附 skill。

26 26

27大多数捆绑技能在每个会话中都可用。少数技能取决于特定功能：例如，`/workflow-authoring` 仅在[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)启用时可用。27大多数捆绑技能在每个会话中都可用。少数技能取决于特定功能：例如，`/workflow-authoring` 仅在[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)启用时可用。

28 28

320 320

321如果您创建了会话启动时不存在的顶级 skills 目录，请运行 [`/reload-skills`](https://code.claude.com/docs/zh-CN/commands#all-commands) 以获取您放在那里的 skills。Claude Code 还没有监视该目录，因此在稍后每次更改后再次运行 `/reload-skills`。321如果您创建了会话启动时不存在的顶级 skills 目录，请运行 [`/reload-skills`](https://code.claude.com/docs/zh-CN/commands#all-commands) 以获取您放在那里的 skills。Claude Code 还没有监视该目录，因此在稍后每次更改后再次运行 `/reload-skills`。

322 322

323实时更改检测仅涵盖 `SKILL.md` 文本。对于也是 [插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#plugins-shared-through-a-repository) 的 skill 文件夹，对 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。323> [!NOTE]

324>

325> 实时更改检测涵盖 `SKILL.md` 文本。对于也是 [插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#plugins-shared-through-a-repository) 的 skill 文件夹，对 `.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。对 `hooks/` 的更改也需要它，但 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 的模块文件在 [自行重新加载](https://code.claude.com/docs/zh-CN/env-vars.md) 时除外。

324 326

325### 删除 skill327### 删除 skill

326 328

sub-agents.md +60 −43

Details

36>36>

37> 一个快速的、只读的代理，针对搜索和分析代码库进行了优化。37> 一个快速的、只读的代理，针对搜索和分析代码库进行了优化。

38>38>

~~39> * **Model**: 主对话的模型。当主对话运行 Fable 时，Explore 的模型取决于您的连接方式：~~39> * **Model**: [父对话](#which-model-a-nested-subagent-runs-on)的模型。当父对话运行 Fable 时，Explore 会根据您的连接方式在 Opus 上运行或保持使用 Fable。

40> * 使用 Claude 订阅、Anthropic Console 账户，或通过 `ANTHROPIC_BASE_URL` 访问的 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)时，Explore 在 [`opus` 别名](https://code.claude.com/docs/zh-CN/model-config#model-aliases)解析到的 Opus 模型上运行。40> * 使用 Claude 订阅、Anthropic Console 账户，或通过 `ANTHROPIC_BASE_URL` 访问的 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)时，Explore 在 [`opus` 别名](https://code.claude.com/docs/zh-CN/model-config#model-aliases)解析到的 Opus 模型上运行。

41> * 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 或 [Claude apps 网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)上，Explore 保持使用主对话的模型。41> * 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 或 [Claude apps 网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)上，Explore 保持使用 Fable。

42> * **Tools**: 只读工具；拒绝访问 Write 和 Edit42> * **Tools**: 只读工具；拒绝访问 Write 和 Edit

43> * **Purpose**: 文件发现、代码搜索、代码库探索43> * **Purpose**: 文件发现、代码搜索、代码库探索

44>44>

52>52>

53> 一个研究代理，在 [plan mode](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode) 期间使用，以在呈现计划之前收集上下文。53> 一个研究代理，在 [plan mode](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode) 期间使用，以在呈现计划之前收集上下文。

54>54>

~~55> * **Model**: 从主对话继承，除非您设置 `CLAUDE_CODE_SUBAGENT_MODEL` 并[强制将其应用于每个 subagent](#run-every-subagent-on-one-model)~~55> * **Model**: 从[父对话](#which-model-a-nested-subagent-runs-on)继承，除非您设置 `CLAUDE_CODE_SUBAGENT_MODEL` 并[强制将其应用于每个子代理](#run-every-subagent-on-one-model)

56> * **Tools**: 只读工具；拒绝访问 Write 和 Edit56> * **Tools**: 只读工具；拒绝访问 Write 和 Edit

57> * **Purpose**: 用于规划的代码库研究57> * **Purpose**: 用于规划的代码库研究

58>58>

62>62>

63> 一个能够处理复杂、多步骤任务的代理，需要探索和操作。63> 一个能够处理复杂、多步骤任务的代理，需要探索和操作。

64>64>

65> * **Model**: 如果您设置了 [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) 模型且没有其他方式分配模型，则使用该模型，否则使用主对话的模型；[选择模型](#choose-a-model) 说明了完整的顺序，[在一个模型上运行每个 subagent](#run-every-subagent-on-one-model) 展示了如何使变量覆盖这些来源65> * **Model**: 默认使用父对话的模型，遵循[模型顺序](#choose-a-model)

~~66> * **Tools**: 所有[可用于 subagents 的工具](#available-tools)~~66> * **Tools**: 所有[可用于子代理的工具](#available-tools)

67> * **Purpose**: 复杂研究、多步骤操作、代码修改67> * **Purpose**: 复杂研究、多步骤操作、代码修改

68>68>

69> 当任务需要探索和修改、复杂推理来解释结果或多个依赖步骤时，Claude 会委托给 general-purpose。69> 当任务需要探索和修改、复杂推理来解释结果或多个依赖步骤时，Claude 会委托给 general-purpose。

346 346

347### 选择模型347### 选择模型

348 348

349`model` 字段控制子代理使用哪个模型：349默认情况下，您定义的子代理与启动它的对话在同一模型上运行。若要自行选择其模型，请将其定义中的 [`model`](#supported-frontmatter-fields) 字段设置为以下值之一：

350 350

351* **模型别名**：使用可用别名之一：`sonnet`、`opus`、`haiku` 或 `fable`351* **模型别名**：`sonnet`、`opus`、`haiku` 或 `fable`

352* **完整模型 ID**：使用完整模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受与 `--model` 标志相同的值352* **完整模型 ID**：[`--model`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 标志接受的值，例如 `claude-opus-5-5` 或 `claude-sonnet-5`

353* **inherit**：使用与主对话相同的模型353* **`inherit`**：主对话的模型；对于[嵌套子代理](#which-model-a-nested-subagent-runs-on)，则为生成它的子代理的模型

354 354

355当 Claude 调用子代理时，它还可以为该次调用传入 `model` 参数。在 Agent 工具调用中，该参数接受模型别名：`sonnet`、`opus`、`haiku` 或 `fable`。Claude 无法在该调用中传入完整模型 ID 或 `inherit`。Claude Code 按以下顺序确定子代理的模型：355当有多个来源设置了模型时，Claude Code 按以下顺序使用第一个：

356 356

3571. 单次调用的 `model` 参数3571. 单次调用的 `model` 参数，Claude 可以在启动子代理时传入该参数。在 Agent 工具调用中，该参数接受模型别名，而不接受完整模型 ID 或 `inherit`。

3582. 子代理定义中的 `model` frontmatter，其中 `inherit` 选择主对话的模型3582. 子代理定义中的 `model` 字段，包括 `inherit`

3593. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/zh-CN/model-config#environment-variables) 环境变量（当您将其设置为模型别名或模型 ID 时）3593. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/zh-CN/model-config#environment-variables) 环境变量

3604. 主对话的模型3604. 主对话的模型；对于嵌套子代理，则为生成它的子代理的模型

361 361

362如果已安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 在其 [`agent.spawn`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型来代替单次调用的参数。362如果 Claude 传入了别名，子代理在[被恢复或收到后续消息](#resume-subagents)时会保留该别名。如果已安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 在其 [`agent.spawn`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型来代替单次调用的参数。

~~363~~

364在两种情况下，单次调用参数或 frontmatter 中的系列别名（如 `opus`）会解析为主对话的模型，而不是[该别名指向的版本](https://code.claude.com/docs/zh-CN/model-config.md#model-aliases)：

~~365~~

366* **主对话的模型属于该系列**：子代理在主对话的确切模型上运行，包括任何 `[1m]` 后缀，因此它获得与主对话相同的[扩展上下文](https://code.claude.com/docs/zh-CN/model-config.md#extended-context)窗口。

367* **在 [Anthropic API 以外的提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)上，Claude Code 无法判断主对话的模型系列**：这可能发生在 Amazon Bedrock 上使用 Claude Code 尚未解析到后端模型的[应用推理配置文件 ARN](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#iam-configuration) 时。这种情况仅涵盖 `opus` 别名，并且在您设置了 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/zh-CN/model-config#environment-variables) 时不适用，因为此时 `opus` 会解析为您设置的模型。

~~368~~

369`CLAUDE_CODE_SUBAGENT_MODEL` 中的别名始终解析为该别名指向的版本，即使它指向主对话的系列。将该变量设置为 `inherit` 等同于不设置它。

370 363

371仅设置 `CLAUDE_CODE_SUBAGENT_MODEL` 不会改变内置 Explore 和 Plan 子代理所运行的模型。若要更改，请参阅[让所有子代理在同一模型上运行](#run-every-subagent-on-one-model)。364仅设置 `CLAUDE_CODE_SUBAGENT_MODEL` 不会改变内置 Explore 和 Plan 子代理所运行的模型。若要更改，请参阅[让所有子代理在同一模型上运行](#run-every-subagent-on-one-model)。

372 365

373在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此顺序中排在首位，会覆盖单次调用参数和 frontmatter，包括 `model: inherit`。366#### 嵌套子代理在哪个模型上运行

374 367

375Claude Code 会根据您组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表检查单次调用参数、frontmatter 和环境变量的值。对于被阻止的值，它会替换为另一个模型：368默认情况下，您定义的[嵌套子代理](#let-subagents-spawn-their-own-subagents)在其父级（即生成它的子代理）的模型上运行。若要让嵌套子代理在其他模型上运行，请将其 `model` 字段设置为该模型。

376 369

377* 当被阻止的值是系列别名（如 `opus`）时，Claude Code 会在允许列表允许的该系列最新版本上运行子代理，遵循与 `/model` 相同的[替换规则和提供商范围](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)。在 v2.1.222 之前，对于被阻止的系列别名，Claude Code 同样会在继承的模型上运行子代理。370例如，假设您的主对话在 Opus 上运行，并在 Haiku 上启动了一个审查子代理。默认情况下，当该审查子代理生成以下子代理时，它们会在 Haiku 而不是 Opus 上运行：

378* 对于任何其他被阻止的值、在该替换不起作用的提供商上，或者当允许列表不允许该系列的任何版本时，Claude Code 会改为在继承的模型上运行子代理。如果您设置了 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 会按照同样的规则首先尝试该模型。

379 371

380在交互式会话中，对于上述任一种替换，Claude Code 都会显示一条警告，列出请求的模型和子代理实际运行的模型。372* 设置了 `model: inherit` 或没有 `model` 字段的子代理

373* 内置的 Explore、Plan 和 general-purpose 子代理

374* [分叉](#fork-the-current-conversation)

381 375

382若要查看子代理正在哪个模型上运行，请运行 [`/tasks`](https://code.claude.com/docs/zh-CN/commands)。Claude Code 会在子代理所在行显示模型名称，并附上为该子代理设置的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)（如果有）。需要 Claude Code v2.1.242 或更高版本。376在计划模式下，如果您将会话的模型设置为 [`opusplan`](https://code.claude.com/docs/zh-CN/model-config#opusplan-model-setting)，这些子代理会在 Opus 上运行；如果您将其设置为 `haiku`，则在 Sonnet 上运行。

383 377

384当子代理被[恢复或收到后续消息](#resume-subagents)时，单次调用的 `model` 参数同样适用，因此子代理会保持在该模型上。378#### 检查子代理的模型

385 379

386从 v2.1.198 开始，子代理还会继承主对话的[扩展思考](https://code.claude.com/docs/zh-CN/model-config.md#extended-thinking)配置：如果您的会话中启用了思考，子代理也会启用；如果关闭，它也保持关闭。没有针对单个子代理的思考设置。在 v2.1.198 之前，无论主对话的设置如何，子代理都在禁用扩展思考的情况下运行。380若要查看子代理正在哪个模型上运行，请运行 [`/tasks`](https://code.claude.com/docs/zh-CN/commands)。Claude Code 会在子代理所在行显示模型名称，并附上为该子代理设置的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)（如果有）。需要 Claude Code v2.1.242 或更高版本。

387 381

388#### 让所有子代理在同一模型上运行382#### 让所有子代理在同一模型上运行

389 383

390`CLAUDE_CODE_SUBAGENT_MODEL` 是一个默认值，因此子代理的定义或 Claude 传入的模型仍优先于它。若要将同一模型应用于每个子代理、[队友](https://code.claude.com/docs/zh-CN/agent-teams.md#specify-teammates-and-models)和[工作流 Agent](https://code.claude.com/docs/zh-CN/workflows.md)，还需将 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 设置为 `1`。需要 Claude Code v2.1.257 或更高版本。384若要将同一模型应用于每个子代理、[队友](https://code.claude.com/docs/zh-CN/agent-teams.md#specify-teammates-and-models)和[工作流 Agent](https://code.claude.com/docs/zh-CN/workflows.md)，请将 `CLAUDE_CODE_SUBAGENT_MODEL` 设置为该模型，并将 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 设置为 `1`。需要 Claude Code v2.1.257 或更高版本。

~~391~~

392* 如果同时设置了这两个变量，子代理会在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上运行。

393* 如果只设置了 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，子代理会在主对话的模型上运行，但内置 Explore 子代理除外，它在[内置子代理下为其列出的模型](#built-in-subagents)上运行。

394 385

395例如，若要让所有子代理都在 Haiku 上运行，请在[设置文件](https://code.claude.com/docs/zh-CN/settings.md)的 `env` 块中同时设置这两个变量：386例如，若要让所有子代理都在 Haiku 上运行，请在[设置文件](https://code.claude.com/docs/zh-CN/settings.md)的 `env` 块中同时设置这两个变量：

396 387

405 396

406若要检查设置是否生效，请在子代理运行时运行 [`/tasks`](https://code.claude.com/docs/zh-CN/commands)。子代理所在行会显示它所运行的模型。397若要检查设置是否生效，请在子代理运行时运行 [`/tasks`](https://code.claude.com/docs/zh-CN/commands)。子代理所在行会显示它所运行的模型。

407 398

408当 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [启用](https://code.claude.com/docs/zh-CN/env-vars.md)时，Claude Code 会忽略子代理定义中的 `model` 字段，并且 Claude 在启动子代理时无法传入模型。以下子代理仍在主对话的模型上运行：399当 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [启用](https://code.claude.com/docs/zh-CN/env-vars.md)时，Claude Code 会忽略子代理定义中的 `model` 字段，并且 Claude 在启动子代理时无法传入模型。以下子代理仍在其父对话的模型上运行：

409 400

410* [分叉](#fork-the-current-conversation)401* [分叉](#fork-the-current-conversation)

411* 设置了 `model: inherit` 的[在子代理中运行的 skill](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent)402* 设置了 `model: inherit` 的[在子代理中运行的 skill](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent)

412 403

404如果只设置了 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，子代理会在主对话的模型上运行，但内置 Explore 子代理除外，它在[内置子代理下为其列出的模型](#built-in-subagents)上运行。

405

406#### 模型别名选择哪个版本

407

408默认情况下，使用模型别名的子代理会在[该别名指向的版本](https://code.claude.com/docs/zh-CN/model-config.md#model-aliases)上运行。当 `model` 字段或单次调用参数中使用系列别名（如 `opus`）时，在以下两种情况下，子代理会在其父对话的模型上运行：

409

410* **同一系列**：例如，如果您的主对话在 `claude-opus-4-7` 上运行，设置了 `model: opus` 的子代理也会在该版本上运行。若要运行其他版本，请在 `model` 字段中设置完整模型 ID。

411* **未知系列**：Claude Code 无法判断父模型的系列，例如使用它[无法查询](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#iam-configuration)的 Amazon Bedrock ARN 时。这种情况仅适用于 [Anthropic API 以外的提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)上的 `opus` 别名。若要选择 Opus 版本，请设置 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/zh-CN/model-config#environment-variables)。

412

413#### 当允许列表阻止子代理模型时

414

415如果您组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表阻止了为子代理设置的模型，子代理会在以下适用的第一项上运行：

416

4171. 对于被阻止的系列别名，在[支持此替换的提供商](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)上，使用该系列中允许的最新版本

4182. `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型（如果您设置了），遵循同样的规则

4193. 主对话的模型；对于嵌套子代理，则为生成它的子代理的模型

420

421对于交互式会话中的顶层子代理，会显示一条警告，列出请求的模型及其替代模型。若要运行特定模型，请将被阻止的值更改为允许列表允许的值。

422

423### 子代理中的扩展思考

424

425子代理继承主对话的[扩展思考](https://code.claude.com/docs/zh-CN/model-config.md#extended-thinking)配置。没有针对单个子代理的思考设置。

426

413### 选择 effort 级别427### 选择 effort 级别

414 428

415若要让子代理以其自己的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)运行，请在其定义中设置 [`effort`](#supported-frontmatter-fields) 字段。429若要让子代理以其自己的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)运行，请在其定义中设置 [`effort`](#supported-frontmatter-fields) 字段。

426 440

427#### 可用工具441#### 可用工具

428 442

429子代理继承主对话中可用的[内置工具](https://code.claude.com/docs/zh-CN/tools-reference.md)和 MCP 工具，并经过两个过滤器的缩减：第一个过滤器从每个子代理中移除少量工具，第二个过滤器为在[后台](#run-subagents-in-foreground-or-background)运行的子代理（默认情况）缩减内置工具集。在 macOS、Linux 和 WSL 上，当主对话没有 Glob 和 Grep 工具时，子代理也可以获得这些工具，如 [Glob 工具行为](https://code.claude.com/docs/zh-CN/tools-reference.md#glob-tool-behavior)中所述。[分叉](#fork-the-current-conversation)会跳过这两个过滤器，获得与主对话完全相同的工具池。第一个过滤器会移除以下工具，即使它们列在 `tools` 字段中：443子代理继承主对话中可用的[内置工具](https://code.claude.com/docs/zh-CN/tools-reference.md)和 MCP 工具，并经过两个过滤器的缩减。第一个过滤器从每个子代理中移除少量工具。第二个过滤器为在[后台](#run-subagents-in-foreground-or-background)运行的子代理（默认情况）缩减内置工具集。

444

445在 macOS、Linux 和 WSL 上，当主对话没有 Glob 和 Grep 工具时，子代理也可以获得这些工具，如 [Glob 工具行为](https://code.claude.com/docs/zh-CN/tools-reference.md#glob-tool-behavior)中所述。[分叉](#fork-the-current-conversation)会跳过这两个过滤器，获得与其父对话完全相同的工具池。第一个过滤器会移除以下工具，即使它们列在 `tools` 字段中：

430 446

431* `Agent`，当子代理达到[深度限制](#let-subagents-spawn-their-own-subagents)时；在[分叉](#fork-the-current-conversation)中，该工具仍会列出，但会返回错误而不是生成子代理447* `Agent`，当子代理达到[深度限制](#let-subagents-spawn-their-own-subagents)时；在[分叉](#fork-the-current-conversation)中，该工具仍会列出，但会返回错误而不是生成子代理

432* `AskUserQuestion`448* `AskUserQuestion`

1077 1093

1078使用此值时，您的子代理可以委托给它们自己的第二层子代理，而第二层无法再进一步委托。设置为 `1` 可关闭嵌套。1094使用此值时，您的子代理可以委托给它们自己的第二层子代理，而第二层无法再进一步委托。设置为 `1` 可关闭嵌套。

1079 1095

1080嵌套子代理的配置方式与顶层子代理相同，并从相同的[作用域](#choose-the-subagent-scope)中解析。要在嵌套开启时阻止某个子代理生成子代理（例如应保持只读的审查者），请从其 [`tools`](#available-tools) 列表中省略 `Agent`，或将其添加到 `disallowedTools`。1096在与顶层子代理相同的[作用域](#choose-the-subagent-scope)中定义嵌套子代理。默认情况下，您定义的嵌套子代理会在[发起启动的子代理的模型](#which-model-a-nested-subagent-runs-on)上运行。要在嵌套开启时阻止某个子代理生成子代理（例如应保持只读的审查者），请从其 [`tools`](#available-tools) 列表中省略 `Agent`，或将其添加到 `disallowedTools`。

1081 1097

1082在终端中，Claude Code 会在输入框下方的子代理面板中以树形显示嵌套子代理，并为面板中仍有后代的每一行标注 `(+N)`，表示其后代数量。打开某一行即可查看该子代理的同级和直接子级，以及返回 `main` 的路径。1098在终端中，Claude Code 会在输入框下方的子代理面板中以树形显示嵌套子代理，并为面板中仍有后代的每一行标注 `(+N)`，表示其后代数量。打开某一行即可查看该子代理的同级和直接子级，以及返回 `main` 的路径。

1083 1099

1221>1237>

1222> 当[Agent 视图被关闭](https://code.claude.com/docs/zh-CN/agent-view.md#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 改为启动分叉子代理；否则 `/fork` 将整个会话复制到新的[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#from-inside-a-session)中。1238> 当[Agent 视图被关闭](https://code.claude.com/docs/zh-CN/agent-view.md#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 改为启动分叉子代理；否则 `/fork` 将整个会话复制到新的[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#from-inside-a-session)中。

1223 1239

1224分叉是一个 subagent，它继承到目前为止的整个对话，而不是从头开始。这消除了 subagents 通常提供的输入隔离：分叉看到与主会话相同的系统提示、工具、模型和消息历史，因此您可以将其交给一个辅助任务而无需重新解释情况。分叉自己的工具调用仍然保持在您的对话之外，只有其最终结果返回，因此您的主 context window 保持干净。当任何其他 subagent 需要太多背景才能有用时，或当您想从相同的起点并行尝试多种方法时，使用分叉。1240分叉是一个子代理，它继承到目前为止的整个对话，而不是从头开始。当任何其他子代理需要太多背景才能有用时，或当您想从相同的起点并行尝试多种方法时，使用分叉。

1241

1242* **输入**：分叉看到与其父对话相同的系统提示词、工具、[模型](#which-model-a-nested-subagent-runs-on)和消息历史

1243* **输出**：分叉自己的工具调用保持在其父对话之外，只有其最终结果返回

1225 1244

1226分叉模式启用时（默认即为启用），Claude 可以自行启动分叉。要停止分叉，请参阅[关闭分叉模式](#turn-fork-mode-on-or-off)。1245分叉模式启用时（默认即为启用），Claude 可以自行启动分叉。要停止分叉，请参阅[关闭分叉模式](#turn-fork-mode-on-or-off)。

1227 1246

1257 1276

1258### 分叉与其他 subagents 的区别1277### 分叉与其他 subagents 的区别

1259 1278

1260分叉继承主会话在生成时拥有的一切。任何其他 subagent 从其定义开始。

~~1261~~

1262| | 分叉 | 非分叉 subagent |1279| | 分叉 | 非分叉 subagent |

1263| :- | :- | :- |1280| :- | :- | :- |

1264| 上下文 | 完整的对话历史 | 新鲜上下文，带有您传递的提示 |1281| 上下文 | 完整的对话历史 | 新鲜上下文，带有您传递的提示 |

1266| 模型 | 与主会话相同 | 来自 subagent 的 `model` 字段 |1283| 模型 | 与[父对话](#which-model-a-nested-subagent-runs-on)相同 | 遵循[子代理模型顺序](#choose-a-model) |

1268 1285

1269因为分叉的系统提示词和工具定义与父级相同，其第一个请求重用父级的[提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md#subagents-and-the-cache)。由于这种重用，对于需要相同上下文的任务，分叉的成本低于新的子代理。1286因为分叉的系统提示词和工具定义与父级相同，其第一个请求重用父级的[提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md#subagents-and-the-cache)。由于这种重用，对于需要相同上下文的任务，分叉的成本低于新的子代理。

1270 1287

workflows.md +1 −1

Details

454* 如果您通常会为日常工作切换到较小的模型，请在大型运行之前检查 `/model`454* 如果您通常会为日常工作切换到较小的模型，请在大型运行之前检查 `/model`

455* 在描述任务时，让 Claude 为不需要最强模型的阶段使用较小的模型455* 在描述任务时，让 Claude 为不需要最强模型的阶段使用较小的模型

456 456

457当您组织的 [`availableModels` 允许列表](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection)阻止了脚本为某个 Agent 请求的模型时，该 Agent 会改用替代模型运行，遵循与[子代理相同的替代规则](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)。457当您组织的 [`availableModels` 允许列表](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection)阻止了脚本为某个 Agent 请求的模型时，该 Agent 会改用替代模型运行，遵循与[子代理相同的替代规则](https://code.claude.com/docs/zh-CN/sub-agents.md#when-an-allowlist-blocks-a-subagent-model)。

458 458

459### 设置规模指导459### 设置规模指导

460 460

worktrees.md +5 −2

Details

232 232

233使用默认的 `"fresh"` [基础](#choose-the-base-branch)，当以下所有条件都成立时，重新打开的 worktree 会重置为仓库的默认分支而不是在其原来的顶端继续：233使用默认的 `"fresh"` [基础](#choose-the-base-branch)，当以下所有条件都成立时，重新打开的 worktree 会重置为仓库的默认分支而不是在其原来的顶端继续：

234 234

235* 它没有未提交的更改或未跟踪的文件。235* [沙箱](https://code.claude.com/docs/zh-CN/sandboxing.md#filesystem-isolation)未在您的会话中限制文件写入，并且 worktree 和主检出的 `.claude` 设置文件均未启用沙箱。

236* worktree 没有未提交的更改或未跟踪的文件。

236* 它仍然在 Claude Code 为其创建的分支上。237* 它仍然在 Claude Code 为其创建的分支上。

237* 它没有自己的提交，或其拉取请求或合并请求已合并且其远程分支已删除。238* 它没有自己的提交，或其拉取请求或合并请求已合并且其远程分支已删除。

238 239

240 241

241在所有其他情况下，Claude Code 在其原来的顶端重新打开 worktree：242在所有其他情况下，Claude Code 在其原来的顶端重新打开 worktree：

242 243

243* worktree 有任一条件不成立。244* worktree 或会话有任一条件不成立。

244* Claude Code 无法验证 worktree 的状态。245* Claude Code 无法验证 worktree 的状态。

245* `worktree.baseRef` 是 `"head"`。246* `worktree.baseRef` 是 `"head"`。

246* 名称是拉取请求或合并请求引用。247* 名称是拉取请求或合并请求引用。

247 248

249如果您在使用 `"fresh"` 基础的同时使用沙箱，请运行 `git fetch origin`，然后向 `--worktree` 传递一个新名称，以从最新的默认分支开始。

250

248### 使用 hook 替换 worktree 创建251### 使用 hook 替换 worktree 创建

249 252

250配置 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/hooks#worktreecreate) 以完全替换默认的 `git worktree` 逻辑，包括将 worktrees 放在 `.claude/worktrees/` 之外的地方。有关完整示例，请参阅[非 git 版本控制](#non-git-version-control)。253配置 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/hooks#worktreecreate) 以完全替换默认的 `git worktree` 逻辑，包括将 worktrees 放在 `.claude/worktrees/` 之外的地方。有关完整示例，请参阅[非 git 版本控制](#non-git-version-control)。

Documentation 2026-11-13 23:02 UTC to 2026-11-14 03:01 UTC