Documentation 2026-10-15 23:58 UTC to 2026-10-16 22:59 UTC

9Hooks 是回调函数，用于响应代理事件（如工具被调用、会话启动或执行停止）运行您的代码。使用 hooks，您可以：9Hooks 是回调函数，用于响应代理事件（如工具被调用、会话启动或执行停止）运行您的代码。使用 hooks，您可以：

10 10 

11* **阻止危险操作**在执行前进行，如破坏性 shell 命令或未授权的文件访问11* **阻止危险操作**在执行前进行，如破坏性 shell 命令或未授权的文件访问

12* **记录和审计**每个工具调用，用于合规性、调试或分析12* **记录和审计**工具调用，用于合规性、调试或分析

13* **转换输入和输出**以清理数据、注入凭证或重定向文件路径13* **转换输入和输出**以清理数据、注入凭证或重定向文件路径

14* **要求人工批准**敏感操作，如数据库写入或 API 调用14* **要求人工批准**敏感操作，如数据库写入或 API 调用

15* **跟踪会话生命周期**以管理状态、清理资源或发送通知15* **跟踪会话生命周期**以管理状态、清理资源或发送通知

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42 

43以下示例将这些步骤组合在一起。它注册一个 `PreToolUse` hook（步骤 1），带有 `"Write|Edit"` 匹配器（步骤 3），因此回调仅对文件写入工具触发。触发时，回调接收工具的输入（步骤 4），检查文件路径是否针对 `.env` 文件，并返回 `permissionDecision: "deny"` 以阻止操作（步骤 5）：43此示例注册一个 `PreToolUse` hook（步骤 1），带有 `"Write|Edit"` 匹配器（步骤 3），因此回调会针对 Write 和 Edit 工具触发。触发时，回调接收工具的输入（步骤 4），检查文件路径是否针对 `.env` 文件，并返回 `permissionDecision: "deny"` 以阻止操作（步骤 5）：

44 44 

45<CodeGroup>45<CodeGroup>

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

61 file_name = file_path.split("/")[-1]61 file_name = file_path.split("/")[-1]

62 62 

63 # 如果针对 .env 文件，阻止操作63 # 如果针对 .env 文件，阻止操作

64 if file_name == ".env":64 if file_name.lower() == ".env":

65 return {65 return {

66 "hookSpecificOutput": {66 "hookSpecificOutput": {

67 "hookEventName": input_data["hook_event_name"],67 "hookEventName": input_data["hook_event_name"],

108 const fileName = filePath?.split("/").pop();108 const fileName = filePath?.split("/").pop();

109 109 

110 // 如果针对 .env 文件，阻止操作110 // 如果针对 .env 文件，阻止操作

111 if (fileName === ".env") {111 if (fileName?.toLowerCase() === ".env") {

112 return {112 return {

113 hookSpecificOutput: {113 hookSpecificOutput: {

114 hookEventName: preInput.hook_event_name,114 hookEventName: preInput.hook_event_name,

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142 

143当您运行任一脚本时，Claude 尝试创建 `.env` 文件，hook 拒绝该工具调用。143该 hook 会拒绝 `file_path` 以 `/.env` 结尾的 Write 或 Edit 调用，不区分字母大小写。在 Windows 上，`file_path` 使用反斜杠，例如 `C:\project\.env`，此时该 hook 会允许对 `C:\project\.env` 的 Write 或 Edit 调用。

144 

145<Warning>

146 `Write|Edit` 匹配器将此 hook 限制为仅作用于 Write 和 Edit 工具。如果 Claude 通过 Bash 命令写入 `.env`，该 hook 不会运行。要在[沙箱运行](/docs/zh-CN/sandboxing)的情况下阻止 Bash 写入某个文件，请参阅 [Python](/docs/zh-CN/agent-sdk/python#sandbox-configuration) 或 [TypeScript](/docs/zh-CN/agent-sdk/typescript#sandbox-configuration) 的沙箱配置。

147</Warning>

144 148 

145<h2 id="available-hooks">149<h2 id="available-hooks">

146 可用的 hooks150 可用的 hooks

151| Hook 事件 | Python SDK | TypeScript SDK | 触发条件 | 示例用例 |155| Hook 事件 | Python SDK | TypeScript SDK | 触发条件 | 示例用例 |

152| - | - | - | - | - |156| - | - | - | - | - |

153| `PreToolUse` | 是 | 是 | 工具调用请求（可以阻止或修改） | 阻止危险的 shell 命令 |157| `PreToolUse` | 是 | 是 | 工具调用请求（可以阻止或修改） | 阻止危险的 shell 命令 |

154| `PostToolUse` | 是 | 是 | 工具执行结果 | 将所有文件更改记录到审计跟踪 |158| `PostToolUse` | 是 | 是 | 工具执行结果 | 将文件更改记录到审计跟踪 |

155| `PostToolUseFailure` | 是 | 是 | 工具执行失败 | 处理或记录工具错误 |159| `PostToolUseFailure` | 是 | 是 | 工具执行失败 | 处理或记录工具错误 |

156| `PostToolBatch` | 否 | 是 | 一整批工具调用解决，每批一次，在下一个模型调用之前 | 为整个批次注入约定 |160| `PostToolBatch` | 否 | 是 | 一整批工具调用解决，每批一次，在下一个模型调用之前 | 为整个批次注入约定 |

157| [`UserPromptSubmit`](/docs/zh-CN/hooks#userpromptsubmit) | 是 | 是 | 提交提示词，包括 Claude Code 自行发起的轮次 | 将额外上下文注入到提示词中 |161| [`UserPromptSubmit`](/docs/zh-CN/hooks#userpromptsubmit) | 是 | 是 | 提交提示词，包括 Claude Code 自行发起的轮次 | 将额外上下文注入到提示词中 |

235| `hooks` | `HookCallback[]` | - | 必需。当模式匹配时执行的回调函数数组 |239| `hooks` | `HookCallback[]` | - | 必需。当模式匹配时执行的回调函数数组 |

236| `timeout` | `number` | `undefined` | 超时时间（秒）。省略时，Claude Code 应用[事件的默认超时](#hook-timeout)。您的 SDK 回调遵循 `command` hook 默认值 |240| `timeout` | `number` | `undefined` | 超时时间（秒）。省略时，Claude Code 应用[事件的默认超时](#hook-timeout)。您的 SDK 回调遵循 `command` hook 默认值 |

237 241 

238尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。故意省略它以记录您的会话进行的每个工具调用。242尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。

239 243 

240<h3 id="callback-functions">244<h3 id="callback-functions">

241 回调函数245 回调函数

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

269 273 

270<Note>274<Note>

271 当多个 hook 或权限规则适用时，`deny` 优先于 `defer`，`defer` 优先于 `ask`，`ask` 优先于 `allow`。如果任何 hook 返回 `deny`，操作将被阻止，无论其他 hook 如何。275 当多个 `PreToolUse` hook 返回不同的[决策](/docs/zh-CN/hooks#pretooluse-decision-control)时，`deny` 优先于 `defer`，`defer` 优先于 `ask`，`ask` 优先于 `allow`。

272</Note>276</Note>

273 277 

274<h4 id="asynchronous-output">278<h4 id="asynchronous-output">

313 修改工具输入317 修改工具输入

314</h3>318</h3>

315 319 

316此示例拦截 Write 工具调用并重写 `file_path` 参数以添加 `/sandbox` 前缀，将所有文件写入重定向到沙箱目录。回调返回带有修改路径的 `updatedInput` 和 `permissionDecision: 'allow'` 以自动批准重写的操作：320此示例拦截 Write 工具调用并重写 `file_path` 参数以添加 `/sandbox` 前缀。回调返回带有修改路径的 `updatedInput` 和 `permissionDecision: 'allow'` 以自动批准重写的操作：

317 321 

318<CodeGroup>322<CodeGroup>

319 ```python Python theme={null}323 ```python Python theme={null}

370 添加上下文并阻止工具374 添加上下文并阻止工具

371</h3>375</h3>

372 376 

373此示例阻止写入 `/etc` 目录的操作，并向模型和用户解释原因：377此示例拒绝 `file_path` 以 `/etc` 开头的工具调用，并向模型和用户解释原因：

374 378 

375* `permissionDecision: 'deny'` 停止工具调用。379* `permissionDecision: 'deny'` 停止工具调用。

376* `permissionDecisionReason` 告诉模型原因，以便它避免重试。380* `permissionDecisionReason` 告诉模型原因。

377* `systemMessage` 向用户显示发生了什么。381* `systemMessage` 向用户显示发生了什么。

378 382 

379<CodeGroup>383<CodeGroup>

468 注册多个 hooks472 注册多个 hooks

469</h3>473</h3>

470 474 

471当事件触发时，所有匹配的 hooks 并行运行。对于权限决策，最严格的结果获胜：单个 `deny` 会阻止工具调用，无论其他 hooks 返回什么。由于完成顺序是不确定的，请编写每个 hook 以独立行动，而不是依赖另一个 hook 已运行。475当事件触发时，匹配的 hook 并行运行。对于权限决策，以最严格的结果为准。任一 hook 返回的 `deny` 都会阻止工具调用。由于完成顺序是不确定的，请编写每个 hook 以独立行动，而不是依赖另一个 hook 已先运行。

472 476 

473下面的示例为每个工具调用注册三个独立检查。其中的 hook 名称，例如 Python 中的 `audit_logger` 或 TypeScript 中的 `auditLogger`，代表您定义的回调：477下面的示例注册三个独立检查，每个检查都[省略了匹配器](/docs/zh-CN/hooks#matcher-patterns)。其中的 hook 名称，例如 Python 中的 `audit_logger` 或 TypeScript 中的 `auditLogger`，代表您定义的回调：

474 478 

475<CodeGroup>479<CodeGroup>

476 ```python Python theme={null}480 ```python Python theme={null}

504 508 

505使用多工具匹配器在相关工具间共享一个回调。此示例注册三个具有不同范围的匹配器，其中每个 hook 名称代表您定义的回调：509使用多工具匹配器在相关工具间共享一个回调。此示例注册三个具有不同范围的匹配器，其中每个 hook 名称代表您定义的回调：

506 510 

507* 管道分隔的精确列表（`Write|Edit|NotebookEdit`）仅对文件修改工具触发 `file_security_hook`。511* 管道分隔的精确列表（`Write|Edit|NotebookEdit`）对 Write、Edit 和 NotebookEdit 工具触发 `file_security_hook`。

508* 正则表达式（`^mcp__`）对任何名称以 `mcp__` 开头的 MCP 工具触发 `mcp_audit_hook`。512* 正则表达式（`^mcp__`）对任何名称以 `mcp__` 开头的 MCP 工具触发 `mcp_audit_hook`。

509* 省略的匹配器对每个工具调用（无论名称如何）触发 `global_logger`。513* 省略的匹配器触发 `global_logger`，不按工具名称过滤。

510 514 

511<CodeGroup>515<CodeGroup>

512 ```python Python theme={null}516 ```python Python theme={null}

832 836 

833当回调超过其超时时间时，Claude Code 会取消它并丢弃其输出，会话继续而不是挂起。接下来发生的情况取决于事件：837当回调超过其超时时间时，Claude Code 会取消它并丢弃其输出，会话继续而不是挂起。接下来发生的情况取决于事件：

834 838 

835* `PreToolUse`: Claude Code 不运行工具调用，Claude 收到一个工具结果，说明 hook 未在超时前响应，轮次继续。如果另一个 `PreToolUse` hook 返回了明确的拒绝，Claude 会收到该拒绝而不是超时错误。在 v2.1.210 之前，Claude Code 将超时报告给 Claude 作为用户拒绝，这使得无人值守会话停止并等待输入。839* `PreToolUse`: Claude Code 阻止该工具调用。作为替代，Claude 收到一个工具结果，说明 hook 未在超时前响应，轮次继续。在 v2.1.210 之前，Claude Code 将超时报告给 Claude 作为用户拒绝，这使得无人值守会话停止并等待输入。

836* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具结果，轮次继续。840* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具结果，轮次继续。

837* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-CN/hooks#userpromptexpansion)：Claude Code 使用指明 hook 和超时的消息阻止该提示词，会话继续。因为这些事件上的回调可以充当策略门，Claude Code 永远不会让超时的提示词未经筛选就通过。在 v2.1.208 之前，当这些事件上的回调超时时，Claude Code 以 `error_during_execution` 结束查询。841* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-CN/hooks#userpromptexpansion)：Claude Code 使用指明 hook 和超时的消息阻止该提示词，会话继续。在 v2.1.208 之前，当这些事件上的回调超时时，Claude Code 以 `error_during_execution` 结束查询。

838* `Stop` 和 `SubagentStop`：超时的回调计为不返回任何决定。Agent 或子代理停止，就像该回调已允许它一样，您在该事件上的其他 hook 的决定仍然适用。在 Claude Code v2.1.273 之前，超时的 `Stop` 或 `SubagentStop` 回调计为失败的 hook 运行，Claude Code 丢弃了您在该事件上的其他 hook 的决定。842* `Stop` 和 `SubagentStop`：超时的回调计为不返回任何决定。Agent 或子代理停止，就像该回调已允许它一样，您在该事件上的其他 hook 的决定仍然适用。在 Claude Code v2.1.273 之前，超时的 `Stop` 或 `SubagentStop` 回调计为失败的 hook 运行，Claude Code 丢弃了您在该事件上的其他 hook 的决定。

839* `SessionStart`：超时的回调计为不返回任何输出，会话继续使用您的其他 `SessionStart` hook 的输出。843* `SessionStart`：超时的回调计为不返回任何输出，会话继续使用您的其他 `SessionStart` hook 的输出。

840* `PreModelSwitch`：Claude Code 阻止模型切换。未回答的 hook 尚未批准切换。844* `PreModelSwitch`：Claude Code 阻止模型切换。未回答的 hook 尚未批准切换。

3881<Note>3881<Note>

3882 沙箱取决于平台支持，在 Linux 上，需要 `bubblewrap` 和 `socat` 等工具。默认情况下，当 `enabled` 为 `True` 但沙箱无法启动时，命令在沙箱外运行，并在 stderr 上显示警告。此默认值与 TypeScript SDK 不同，后者中 `failIfUnavailable` 默认为 `true`。3882 沙箱取决于平台支持，在 Linux 上，需要 `bubblewrap` 和 `socat` 等工具。默认情况下，当 `enabled` 为 `True` 但沙箱无法启动时，命令在沙箱外运行，并在 stderr 上显示警告。此默认值与 TypeScript SDK 不同，后者中 `failIfUnavailable` 默认为 `true`。

3883 3883 

3884 在沙箱设置中设置 `"failIfUnavailable": True` 以改为停止。该键尚未在 `SandboxSettings` 上声明，但 SDK 会将其转发给 Claude Code，后者会遵守它。然后 `query()` 报告一个 `ResultMessage`，其 `subtype="error_during_execution"` 和 `errors` 中的原因。因为这是一个单次 `query()` 调用，SDK 在生成该错误结果后会引发，所以将循环包装在 try 块中以继续通过它。有关错误合约，请参阅 [处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。3884 在沙箱设置中设置 `"failIfUnavailable": True` 以改为停止。SDK 会将 `failIfUnavailable` 与已声明的 `SandboxSettings` 字段一起转发给 Claude Code。然后 `query()` 报告一个 `ResultMessage`，其 `subtype="error_during_execution"`，原因在 `errors` 中。因为这是一个单次 `query()` 调用，SDK 在生成该错误结果后会引发异常，所以请将循环包装在 try 块中以继续执行。有关错误约定，请参阅 [处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。

3885</Note>3885</Note>

3886 3886 

3887要阻止沙箱化命令写入某个文件，请在沙箱设置中将其绝对路径列在 [`denyWrite`](/docs/zh-CN/settings-reference#sandbox-filesystem-denywrite) 下，例如 `"filesystem": {"denyWrite": ["/home/user/project/.env"]}`。SDK 会将 `filesystem` 与已声明的 `SandboxSettings` 字段一起转发给 Claude Code。沙箱启动后，会阻止对每个所列路径的写入。如果您列出的是 `.env` 或 `./.env`，沙箱化命令仍可以写入会话工作目录中的 `.env` 文件。

3888 

3887<h4 id="example-usage">3889<h4 id="example-usage">

3888 示例用法3890 示例用法

3889</h4>3891</h4>

557[Claude Code skills 指南](/docs/zh-CN/skills) 深入涵盖编写。其指导适用于 SDK 会话。从这些部分开始：557[Claude Code skills 指南](/docs/zh-CN/skills) 深入涵盖编写。其指导适用于 SDK 会话。从这些部分开始：

558 558 

559* [Frontmatter 参考](/docs/zh-CN/skills#frontmatter-reference)：每个支持的字段559* [Frontmatter 参考](/docs/zh-CN/skills#frontmatter-reference)：每个支持的字段

560* [将参数传递给 skills](/docs/zh-CN/skills#pass-arguments-to-skills)：`$ARGUMENTS`、`$0`、`$1` 和 skill 堆叠。[完整替换表](/docs/zh-CN/skills#available-string-substitutions) 添加命名参数和 `${CLAUDE_*}` 变量560* [将参数传递给 skill](/docs/zh-CN/skills#pass-arguments-to-skills)：`$ARGUMENTS`、`$0` 和 `$1`。[完整替换表](/docs/zh-CN/skills#available-string-substitutions) 添加命名参数和 `${CLAUDE_*}` 变量

561* [注入动态上下文](/docs/zh-CN/skills#inject-dynamic-context)：`` !`command` `` 行在 Claude 看到 skill 内容前运行561* [注入动态上下文](/docs/zh-CN/skills#inject-dynamic-context)：`` !`command` `` 行在 Claude 看到 skill 内容前运行

562* [选择 skills 加载的位置](/docs/zh-CN/skills#where-skills-live)：每个 skill 位置、插件命名空间和两个共享名称时哪一个运行562* [选择 skills 加载的位置](/docs/zh-CN/skills#where-skills-live)：每个 skill 位置、插件命名空间和两个共享名称时哪一个运行

563 563 

6246 `SandboxSettings`6246 `SandboxSettings`

6247</h3>6247</h3>

6248 6248 

6249沙箱行为的配置。使用此选项以编程方式启用命令沙箱和配置网络限制。6249沙箱行为的配置。使用它以编程方式启用命令沙箱并配置网络限制。

6250 6250 

6251```typescript theme={null}6251```typescript theme={null}

6252type SandboxSettings = {6252type SandboxSettings = {

6266| 属性 | 类型 | 默认值 | 描述 |6266| 属性 | 类型 | 默认值 | 描述 |

6267| :- | :- | :- | :- |6267| :- | :- | :- | :- |

6268| `enabled` | `boolean` | `false` | 为命令执行启用沙箱模式 |6268| `enabled` | `boolean` | `false` | 为命令执行启用沙箱模式 |

6269| `failIfUnavailable` | `boolean` | `true` | 如果 `enabled` 为 `true` 但沙箱无法启动，则在启动时停止。设置为 `false` 以回退到沙箱外执行，并在 stderr 上显示警告 |6269| `failIfUnavailable` | `boolean` | `true` | 如果 `enabled` 为 `true` 但沙箱无法启动，则在启动时停止。设置为 `false` 可回退到非沙箱执行，并在 stderr 上输出警告 |

6270| `autoAllowBashIfSandboxed` | `boolean` | `true` | 启用沙箱时自动批准 Bash 命令 |6270| `autoAllowBashIfSandboxed` | `boolean` | `true` | 启用沙箱时自动批准 Bash 命令 |

6271| `excludedCommands` | `string[]` | `[]` | 绕过沙箱限制的命令，例如 `['docker *']`。这些自动运行在沙箱外，无需模型参与；[`sandbox.excludedCommands`](/docs/zh-CN/settings-reference#sandbox-excludedcommands) 涵盖何时应用条目 |6271| `excludedCommands` | `string[]` | `[]` | 绕过沙箱限制的命令，例如 `['docker *']`。这些命令会自动在沙箱外运行，无需模型参与；有关条目何时适用，请参阅 [`sandbox.excludedCommands`](/docs/zh-CN/settings-reference#sandbox-excludedcommands) |

6272| `allowUnsandboxedCommands` | `boolean` | `true` | 允许模型请求在沙箱外运行命令。当为 `true` 时，模型可以在工具输入中设置 `dangerouslyDisableSandbox`，这会回退到[权限系统](#permissions-fallback-for-unsandboxed-commands) |6272| `allowUnsandboxedCommands` | `boolean` | `true` | 允许模型请求在沙箱外运行命令。为 `true` 时，模型可以在工具输入中设置 `dangerouslyDisableSandbox`，此时将回退到[权限系统](#permissions-fallback-for-unsandboxed-commands) |

6273| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | 网络特定的沙箱配置 |6273| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | 网络相关的沙箱配置 |

6274| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | 用于读/写限制的文件系统特定沙箱配置 |6274| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | 用于读/写限制的文件系统相关沙箱配置 |

6275| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 命令子字符串或 `*` 的映射（用于每个命令）到要忽略的违规文本的子字符串，例如 `{ "*": ['/etc/hosts'] }`；请参阅 [`sandbox.ignoreViolations`](/docs/zh-CN/settings-reference#sandbox-ignoreviolations) |6275| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 从命令子字符串（或表示所有命令的 `*`）到要忽略的违规文本子字符串的映射，例如 `{ "*": ['/etc/hosts'] }`；请参阅 [`sandbox.ignoreViolations`](/docs/zh-CN/settings-reference#sandbox-ignoreviolations) |

6276| `enableWeakerNestedSandbox` | `boolean` | `false` | 为兼容性启用较弱的嵌套沙箱 |6276| `enableWeakerNestedSandbox` | `boolean` | `false` | 为兼容性启用较弱的嵌套沙箱 |

6277| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱环境中的自定义 ripgrep 二进制配置 |6277| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 用于沙箱环境的自定义 ripgrep 二进制文件配置 |

6278 6278 

6279<Note>6279<Note>

6280 沙箱取决于平台支持，在 Linux 上，还需要 `bubblewrap` 和 `socat` 等工具。当 `enabled` 为 `true` 且沙箱无法启动时，`query()` 报告一条 `result` 消息，其中 `subtype: "error_during_execution"`，原因在 `errors` 中。对于单个消息 `query()` 调用，SDK 在生成该错误结果后抛出异常，因此将循环包装在 try 块中以继续通过它。有关错误合约，请参阅[处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。6280 沙箱依赖于平台支持，在 Linux 上还依赖 `bubblewrap` 和 `socat` 等工具。当 `enabled` 为 `true` 且沙箱无法启动时，`query()` 会报告一条 `subtype: "error_during_execution"` 的 `result` 消息，并在 `errors` 中给出原因。对于单消息 `query()` 调用，SDK 会在产出该错误结果后抛出异常，因此请将循环包裹在 try 块中以便继续执行。有关错误约定，请参阅[处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。

6281 6281 

6282 要改为运行沙箱外的命令，请设置 `failIfUnavailable: false`。6282 如需改为在沙箱外运行，请设置 `failIfUnavailable: false`。

6283</Note>6283</Note>

6284 6284 

6285<h4 id="example-usage">6285<h4 id="example-usage">

6286 示例用法6286 使用示例

6287</h4>6287</h4>

6288 6288 

6289```typescript theme={null}6289```typescript theme={null}

6305 if ("result" in message) console.log(message.result);6305 if ("result" in message) console.log(message.result);

6306 }6306 }

6307} catch (error) {6307} catch (error) {

6308 // 单个 query() 调用在生成错误结果后抛出异常，6308 // A single-shot query() throws after yielding an error result,

6309 // 例如当沙箱无法启动时（failIfUnavailable 默认为 true）。6309 // such as when the sandbox can't start (failIfUnavailable defaults to true).

6310 console.log(`Session ended with an error: ${error}`);6310 console.log(`Session ended with an error: ${error}`);

6311}6311}

6312```6312```

6313 6313 

6314<Warning>6314<Warning>

6315 **Unix socket 安全性：** `allowUnixSockets` 选项可以授予对系统服务的访问权限，这些服务可能会到达沙箱外。例如，允许 `/var/run/docker.sock` 实际上通过 Docker API 授予对主机系统的完全访问权限，绕过沙箱隔离。仅允许严格必要的 Unix sockets 并了解每个的安全含义。6315 **Unix 套接字安全：** `allowUnixSockets` 选项可能会授予对可触及沙箱外部的系统服务的访问权限。例如，允许 `/var/run/docker.sock` 实际上会通过 Docker API 授予对主机系统的完全访问权限，从而绕过沙箱隔离。请仅允许确实必要的 Unix 套接字，并了解每个套接字的安全影响。

6316</Warning>6316</Warning>

6317 6317 

6318<h3 id="sandboxnetworkconfig">6318<h3 id="sandboxnetworkconfig">

6319 `SandboxNetworkConfig`6319 `SandboxNetworkConfig`

6320</h3>6320</h3>

6321 6321 

6322沙箱模式的网络特定配置。这些设置适用于当父级 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 为 `true` 时的沙箱化 Bash 命令。它们不限制 WebFetch 工具，该工具改用[权限规则](/docs/zh-CN/permissions#webfetch)。6322沙箱模式的网络相关配置。当父级 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 为 `true` 时，这些设置适用于在沙箱中运行的 Bash 命令。它们不会限制 WebFetch 工具，该工具改为使用[权限规则](/docs/zh-CN/permissions#webfetch)。

6323 6323 

6324```typescript theme={null}6324```typescript theme={null}

6325type SandboxNetworkConfig = {6325type SandboxNetworkConfig = {

6337 6337 

6338| 属性 | 类型 | 默认值 | 描述 |6338| 属性 | 类型 | 默认值 | 描述 |

6339| :- | :- | :- | :- |6339| :- | :- | :- | :- |

6340| `allowedDomains` | `string[]` | `[]` | 沙箱进程可以访问的域名 |6340| `allowedDomains` | `string[]` | `[]` | 沙箱内进程可以访问的域名 |

6341| `deniedDomains` | `string[]` | `[]` | 沙箱进程无法访问的域名。优先于 `allowedDomains` |6341| `deniedDomains` | `string[]` | `[]` | 沙箱内进程无法访问的域名。优先于 `allowedDomains` |

6342| `strictAllowlist` | `boolean` | `false` | 拒绝沙箱化命令访问[网络允许列表](/docs/zh-CN/sandboxing#network-isolation)之外的主机，而不是提示。仅对沙箱化命令强制执行；WebFetch 等进程内工具不受其限制。仅从用户、托管或 CLI `--settings` 设置中遵守；项目设置被忽略。需要 Claude Code v2.1.219 或更高版本 |6342| `strictAllowlist` | `boolean` | `false` | 拒绝沙箱内命令访问[网络允许列表](/docs/zh-CN/sandboxing#network-isolation)之外的主机，而不是进行提示。仅对沙箱内命令强制执行；WebFetch 等进程内工具不受其限制。仅在用户设置、托管设置或 CLI `--settings` 设置中生效；项目设置中的该项会被忽略。需要 Claude Code v2.1.219 或更高版本 |

6343| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限管理设置。在[管理设置](/docs/zh-CN/managed-settings)中设置时，仅遵守来自管理设置的 `allowedDomains` 条目和来自管理设置的 `WebFetch(domain:...)` 允许规则，来自用户、项目或本地设置的允许条目被忽略。从 SDK 中，通过 [`managedSettings`](#options) 选项传递它 |6343| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限托管设置。在[托管设置](/docs/zh-CN/managed-settings)中设置时，仅采用托管设置中的 `allowedDomains` 条目和 `WebFetch(domain:...)` 允许规则，而用户、项目或本地设置中的允许条目将被忽略。在 SDK 中，请通过 [`managedSettings`](#options) 选项传入 |

6344| `allowLocalBinding` | `boolean` | `false` | 允许进程绑定到本地端口（例如，用于开发服务器） |6344| `allowLocalBinding` | `boolean` | `false` | 允许进程绑定到本地端口（例如用于开发服务器） |

6345| `allowUnixSockets` | `string[]` | `[]` | 进程可以访问的 Unix socket 路径（例如，Docker socket） |6345| `allowUnixSockets` | `string[]` | `[]` | 进程可以访问的 Unix 套接字路径（例如 Docker 套接字） |

6346| `allowAllUnixSockets` | `boolean` | `false` | 允许访问所有 Unix sockets |6346| `allowAllUnixSockets` | `boolean` | `false` | 允许访问所有 Unix 套接字 |

6347| `httpProxyPort` | `number` | `undefined` | 网络请求的 HTTP 代理端口 |6347| `httpProxyPort` | `number` | `undefined` | 用于网络请求的 HTTP 代理端口 |

6348| `socksProxyPort` | `number` | `undefined` | 网络请求的 SOCKS 代理端口 |6348| `socksProxyPort` | `number` | `undefined` | 用于网络请求的 SOCKS 代理端口 |

6349 6349 

6350<Note>6350<Note>

6351 内置沙箱代理基于请求的主机名强制执行 `allowedDomains`，不会终止或检查 TLS 流量，因此[域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技术可能会绕过它。有关详细信息，请参阅[沙箱安全限制](/docs/zh-CN/sandboxing#security-limitations)，以及[安全部署](/docs/zh-CN/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 终止代理。6351 内置沙箱代理根据请求的主机名强制执行 `allowedDomains`，不会终止或检查 TLS 流量，因此[域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技术可能会绕过它。有关详细信息，请参阅[沙箱隔离的安全限制](/docs/zh-CN/sandboxing#security-limitations)；有关配置 TLS 终止代理，请参阅[安全部署](/docs/zh-CN/agent-sdk/secure-deployment#traffic-forwarding)。

6352</Note>6352</Note>

6353 6353 

6354<h3 id="sandboxfilesystemconfig">6354<h3 id="sandboxfilesystemconfig">

6355 `SandboxFilesystemConfig`6355 `SandboxFilesystemConfig`

6356</h3>6356</h3>

6357 6357 

6358沙箱模式的文件系统特定配置。6358沙箱模式的文件系统相关配置。

6359 6359 

6360```typescript theme={null}6360```typescript theme={null}

6361type SandboxFilesystemConfig = {6361type SandboxFilesystemConfig = {

6368| 属性 | 类型 | 默认值 | 描述 |6368| 属性 | 类型 | 默认值 | 描述 |

6369| :- | :- | :- | :- |6369| :- | :- | :- | :- |

6370| `allowWrite` | `string[]` | `[]` | 允许写入访问的文件路径模式 |6370| `allowWrite` | `string[]` | `[]` | 允许写入访问的文件路径模式 |

6371| `denyWrite` | `string[]` | `[]` | 拒绝写入访问的文件路径模式 |6371| `denyWrite` | `string[]` | `[]` | 拒绝写入访问的文件路径模式。要阻止沙箱内对会话工作目录中某个文件的写入，请列出其绝对路径。如果列出的是 `.env` 或 `./.env`，沙箱内命令可以写入会话工作目录中的 `.env` 文件 |

6372| `denyRead` | `string[]` | `[]` | 拒绝读取访问的文件路径模式 |6372| `denyRead` | `string[]` | `[]` | 拒绝读取访问的文件路径模式 |

6373 6373 

6374<h3 id="permissions-fallback-for-unsandboxed-commands">6374<h3 id="permissions-fallback-for-unsandboxed-commands">

6375 沙箱外命令的权限回退6375 非沙箱命令的权限回退

6376</h3>6376</h3>

6377 6377 

6378当 `allowUnsandboxedCommands` 启用时，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 `canUseTool` 处理程序被调用，允许您实现自定义授权逻辑。6378启用 `allowUnsandboxedCommands` 后，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求会回退到现有的权限系统，这意味着您的 `canUseTool` 处理程序会被调用，从而允许您实现自定义授权逻辑。

6379 6379 

6380您的 `excludedCommands` 条目改为自动绕过沙箱，无需模型参与；[`sandbox.excludedCommands`](/docs/zh-CN/settings-reference#sandbox-excludedcommands) 涵盖何时应用条目。6380而您的 `excludedCommands` 条目会在无需模型参与的情况下将调用移出沙箱；有关条目何时适用，请参阅 [`sandbox.excludedCommands`](/docs/zh-CN/settings-reference#sandbox-excludedcommands)。

6381 6381 

6382在下面的示例中，`isCommandAuthorized` 代表您定义的授权检查。6382在下面的示例中，`isCommandAuthorized` 代表您自行定义的授权检查。

6383 6383 

6384```typescript theme={null}6384```typescript theme={null}

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

6389 options: {6389 options: {

6390 sandbox: {6390 sandbox: {

6391 enabled: true,6391 enabled: true,

6392 allowUnsandboxedCommands: true // 模型可以请求沙箱外执行6392 allowUnsandboxedCommands: true // Model can request unsandboxed execution

6393 },6393 },

6394 permissionMode: "default",6394 permissionMode: "default",

6395 canUseTool: async (tool, input) => {6395 canUseTool: async (tool, input) => {

6396 // 检查模型是否请求绕过沙箱6396 // Check if the model is requesting to bypass the sandbox

6397 if (tool === "Bash" && input.dangerouslyDisableSandbox) {6397 if (tool === "Bash" && input.dangerouslyDisableSandbox) {

6398 // 模型请求在沙箱外运行此命令6398 // The model is requesting to run this command outside the sandbox

6399 console.log(`Unsandboxed command requested: ${input.command}`);6399 console.log(`Unsandboxed command requested: ${input.command}`);

6400 6400 

6401 if (isCommandAuthorized(input.command)) {6401 if (isCommandAuthorized(input.command)) {

6415```6415```

6416 6416 

6417<Warning>6417<Warning>

6418 使用 `dangerouslyDisableSandbox: true` 运行的命令具有完整的系统访问权限。确保您的 `canUseTool` 处理程序仔细验证这些请求。6418 以 `dangerouslyDisableSandbox: true` 运行的命令拥有完全的系统访问权限。请确保您的 `canUseTool` 处理程序仔细验证这些请求。

6419 6419 

6420 如果 `permissionMode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需批准提示，除了[操作无模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。此组合实际上允许模型以静默方式逃离沙箱隔离。6420 如果 `permissionMode` 设置为 `bypassPermissions` 且启用了 `allowUnsandboxedCommands`，模型可以在没有批准提示的情况下自主执行沙箱外的命令，[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)除外。这种组合实际上允许模型悄无声息地逃逸沙箱隔离。

6421</Warning>6421</Warning>

6422 6422 

6423<h2 id="see-also">6423<h2 id="see-also">

231 231 

232负责人发送关闭请求。队友可以批准，优雅地退出，或拒绝并提供解释。232负责人发送关闭请求。队友可以批准，优雅地退出，或拒绝并提供解释。

233 233 

234团队的共享目录在会话结束时自动清理，因此没有单独的清理步骤。请参阅[架构](#architecture)了解哪些目录被删除以及哪些目录为恢复的会话保留。234团队的共享目录在会话结束时自动清理，因此没有单独的清理步骤。请参阅[架构](#architecture)了解哪些目录会被删除，以及哪些目录会保留在磁盘上。

235 235 

236<h3 id="enforce-quality-gates-with-hooks">236<h3 id="enforce-quality-gates-with-hooks">

237 使用 hooks 强制质量门237 使用 hooks 强制质量门

278 278 

279团队和任务存储在本地，名称来自会话派生的名称。名称是 `session-` 后跟会话 ID 的前八个字符：279团队和任务存储在本地，名称来自会话派生的名称。名称是 `session-` 后跟会话 ID 的前八个字符：

280 280 

281* **Team config**：`~/.claude/teams/{team-name}/config.json`281* **Team config**：`~/.claude/teams/{team-name}/config.json`。Claude Code 会在会话结束时删除团队配置目录。

282* **Task list**：`~/.claude/tasks/{team-name}/`282* **Task list**：`~/.claude/tasks/{team-name}/`。此目录在会话结束后仍保留在磁盘上。要更改 [Claude Code 保留它的时长](/docs/zh-CN/claude-directory#cleaned-up-automatically)，请设置 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays)。

283 283 

284Claude Code 在会话启动时自动生成这两个，并在队友加入、空闲或离开时更新它们。团队配置目录在会话结束时被删除。任务列表目录在本地持久化，永远不会上传，所以恢复的会话会保留它们的任务。保留期由你已经为会话记录控制的相同 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 管理，遵循 [retention sweep rules](/docs/zh-CN/claude-directory#cleaned-up-automatically)。284Claude Code 在会话启动时自动生成这两项，并在队友加入、空闲或离开时更新它们。

285 285 

286团队配置保存运行时状态，例如会话 ID 和 tmux 窗格 ID，所以不要手动编辑它或预先编写它：你的更改会在下一次状态更新时被覆盖。286团队配置保存运行时状态，例如会话 ID 和 tmux 窗格 ID，所以不要手动编辑它或预先编写它：你的更改会在下一次状态更新时被覆盖。

287 287 

12We're changing auto mode to no longer charge for classifier requests in Claude Code. However, this session isn't eligible.12We're changing auto mode to no longer charge for classifier requests in Claude Code. However, this session isn't eligible.

13```13```

14 14 

15在提示符处，Claude Code 会暂停它要以这种方式检查的第一个操作，直到您回答。没有任何问题：auto mode 继续工作，其分类器请求按之前的方式计费。最常见的原因是 Claude Code 和 API 之间存在 LLM gateway 或代理，当 Claude Code 能够识别一个时，通知会将其命名。按 **Enter** 继续，或参阅 [使会话符合条件](#make-the-session-eligible) 以防止其在新会话中出现。15在该提示处，Claude Code 会暂停它要以这种方式检查的第一个操作，直到您回答。自动模式继续工作，其分类器请求按之前的方式计费。

16 

17最常见的原因是 Claude Code 和 API 之间存在 LLM 网关或代理，当 Claude Code 能够识别出它时，通知会将其名称显示出来。按 **Enter** 继续，或参阅[使会话符合条件](#make-the-session-eligible)以防止其在新会话中出现。

16 18 

17<h2 id="respond-to-the-notice">19<h2 id="respond-to-the-notice">

18 响应通知20 响应通知

45 如果安装失败，请匹配 Claude Code 报告的消息：45 如果安装失败，请匹配 Claude Code 报告的消息：

46 46 

47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

48 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。48 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后打印相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

49 49 

50 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。检查安装摘要：如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以使插件的配置命令可用。50 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。检查安装摘要：如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以使插件的配置命令可用。

51 </Step>51 </Step>

123 如果安装失败，请匹配 Claude Code 报告的消息：123 如果安装失败，请匹配 Claude Code 报告的消息：

124 124 

125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

126 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。126 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后打印相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

127 127 

128 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。检查安装摘要：如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以使插件的配置命令可用。128 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。检查安装摘要：如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以使插件的配置命令可用。

129 </Step>129 </Step>

188 如果安装失败，请匹配 Claude Code 报告的消息：188 如果安装失败，请匹配 Claude Code 报告的消息：

189 189 

190 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。190 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

191 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。191 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后打印相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

192 192 

193 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。193 当安装要求选择安装作用域时，选择用户作用域选项，以便插件在所有项目中可用。

194 194 

247 如果安装失败，请匹配 Claude Code 报告的消息：247 如果安装失败，请匹配 Claude Code 报告的消息：

248 248 

249 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。249 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

250 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。250 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后仍显示相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

251 251 

252 当安装要求安装范围时，选择用户范围选项，以便插件在您的所有项目中可用。252 当安装要求安装范围时，选择用户范围选项，以便插件在您的所有项目中可用。

253 253 

290 note: commandsNote,290 note: commandsNote,

291 when: <>User types <C>/command-name</C></>,291 when: <>User types <C>/command-name</C></>,

292 description: <>A file at <C>commands/deploy.md</C> creates <C>/deploy</C> the same way a skill at <C>skills/deploy/SKILL.md</C> does, and both can be auto-invoked by Claude. Skills use a directory with SKILL.md, letting you bundle reference docs, templates, or scripts alongside the prompt.</>,292 description: <>A file at <C>commands/deploy.md</C> creates <C>/deploy</C> the same way a skill at <C>skills/deploy/SKILL.md</C> does, and both can be auto-invoked by Claude. Skills use a directory with SKILL.md, letting you bundle reference docs, templates, or scripts alongside the prompt.</>,

293 tips: [<>Use <C>$ARGUMENTS</C> in the file to accept parameters: <C>/fix-issue 123</C></>, 'If a skill and command share a name, the skill takes precedence', 'New commands should usually be skills instead; commands remain supported'],293 tips: [<>Use <C>$ARGUMENTS</C> in the file to accept parameters: <C>/fix-issue 123</C></>, 'If a skill and command share a name, the skill takes precedence', 'New commands should usually be skills instead; command files still work'],

294 docsLink: '/en/skills',294 docsLink: '/en/skills',

295 children: [{295 children: [{

296 id: 'cmd-example',296 id: 'cmd-example',

48 48 

49该命令打开插件的详细信息，您可以在其中选择[安装范围](/docs/zh-CN/plugins/install#install-a-plugin)来开始安装。49该命令打开插件的详细信息，您可以在其中选择[安装范围](/docs/zh-CN/plugins/install#install-a-plugin)来开始安装。

50 50 

51如果安装失败，修复方法取决于 Claude Code 报告的消息：51如果安装失败，请对照 Claude Code 报告的消息进行处理：

52 52 

53* 如果它报告 `Marketplace "claude-plugins-official" not found`，使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。53* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

54* 如果它报告[在市场中找不到该插件](/docs/zh-CN/plugins/install#install-a-plugin)，检查插件名称是否有拼写错误。54* `Plugin "claude-security" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试时输出相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

55 55 

56检查安装摘要。如果它报告 `Run /reload-plugins to apply.`，请参阅[应用插件更改而无需重启](/docs/zh-CN/plugins/cli-reference#reload-plugins)以在当前会话中激活插件。56检查安装摘要。如果它报告 `Run /reload-plugins to apply.`，请参阅[应用插件更改而无需重启](/docs/zh-CN/plugins/cli-reference#reload-plugins)以在当前会话中激活插件。

57 57 

118在 effort 级别和标志之后，Claude Code 会将该行的其余部分读取为审查目标。`ultra` 参数会改变这种解读方式：118在 effort 级别和标志之后，Claude Code 会将该行的其余部分读取为审查目标。`ultra` 参数会改变这种解读方式：

119 119 

120* **使用 `ultra` 时**：Claude Code 会将单个单词读取为基础分支或 PR 编号。未指明分支或 PR 的较长文本会成为[附加到审查的备注](/docs/zh-CN/ultrareview#pass-a-request-in-plain-words)。`/code-review ultra check my auth changes` 会审查您的当前分支，Claude 会将发现的问题与您的备注关联起来。120* **使用 `ultra` 时**：Claude Code 会将单个单词读取为基础分支或 PR 编号。未指明分支或 PR 的较长文本会成为[附加到审查的备注](/docs/zh-CN/ultrareview#pass-a-request-in-plain-words)。`/code-review ultra check my auth changes` 会审查您的当前分支，Claude 会将发现的问题与您的备注关联起来。

121* **不使用 `ultra` 时**：剩余的所有内容都是审查目标，即使它以另一个命令名称开头。`/code-review /fix-issue 123` 会以 `/fix-issue 123` 作为目标文本进行审查，而不是将 `/fix-issue` 作为第二个[叠加的 skill](/docs/zh-CN/skills#pass-arguments-to-skills) 加载。在 v2.1.218 之前，叠加在 `/code-review` 之后的命令会作为其自身的 skill 展开。121* **不使用 `ultra` 时**：剩余的所有内容都是审查目标，即使它以另一个命令名称开头。`/code-review /fix-issue 123` 会以 `/fix-issue 123` 作为目标文本进行审查，而不是将 `/fix-issue` 作为第二个[叠加的 skill](/docs/zh-CN/skills#stack-several-skills-in-one-message) 加载。在 v2.1.218 之前，叠加在 `/code-review` 之后的命令会作为其自身的 skill 展开。

122 122 

123<h2 id="run-in-the-foreground">123<h2 id="run-in-the-foreground">

124 在前台运行124 在前台运行

10 10 

11输入 `/` 查看可用的命令，或输入 `/` 后跟字母来筛选。[命令菜单如何匹配你输入的内容](#how-the-command-menu-matches-what-you-type)涵盖了高亮显示、拼写错误以及 Claude Code 在你输入完整名称之前隐藏的少数命令。11输入 `/` 查看可用的命令，或输入 `/` 后跟字母来筛选。[命令菜单如何匹配你输入的内容](#how-the-command-menu-matches-what-you-type)涵盖了高亮显示、拼写错误以及 Claude Code 在你输入完整名称之前隐藏的少数命令。

12 12 

13命令只在您的消息开头被识别。命令名称后面的文本成为其参数。[Skills](/docs/zh-CN/skills#pass-arguments-to-skills) 是例外：一个 skill 调用后跟更多 skill，例如 `/skill-a /skill-b do XYZ`，会加载开头命名的 skill，并将尾部文本作为参数传递给每个 skill。最多可以链接六个 skill。13命令只在您的消息开头被识别。命令名称后面的文本成为其参数。在终端提示符处，您可以在一条消息的开头使用多个 [skill](/docs/zh-CN/skills#stack-several-skills-in-one-message)：输入 `/skill-a /skill-b do XYZ` 会加载这两个 skill，并将尾部文本作为参数传递给每个 skill。最多可以链接六个 skill。

14 14 

15如果你在 Claude 响应时发送命令，Claude Code 会将其排队，并在当前轮次完成后运行。Claude Code 会立即运行某些命令而不中断响应，例如 `/status`、`/tasks` 和 `/usage`。在[全屏渲染](/docs/zh-CN/fullscreen)中，Claude Code 也会立即打开对话命令，例如 `/theme` 和 `/help`。在 v2.1.234 之前，Claude Code 会将这些对话排队直到轮次完成。15如果你在 Claude 响应时发送命令，Claude Code 会将其排队，并在当前轮次完成后运行。Claude Code 会立即运行某些命令而不中断响应，例如 `/status`、`/tasks` 和 `/usage`。在[全屏渲染](/docs/zh-CN/fullscreen)中，Claude Code 也会立即打开对话命令，例如 `/theme` 和 `/help`。在 v2.1.234 之前，Claude Code 会将这些对话排队直到轮次完成。

16 16 

1137</Warning>1137</Warning>

1138 1138 

1139* **睡眠或网络中断后**：如果进程[仍在运行](#limits-while-desktop-is-disconnected)且 Desktop 可以无需提示登录，您会重新获得正在运行的任务。如果无法登录，请[发送消息](#reconnect-after-sleep-or-a-network-loss)。1139* **睡眠或网络中断后**：如果进程[仍在运行](#limits-while-desktop-is-disconnected)且 Desktop 可以无需提示登录，您会重新获得正在运行的任务。如果无法登录，请[发送消息](#reconnect-after-sleep-or-a-network-loss)。

1140* **退出后，macOS 或 Linux 上的 Desktop 并使用 Claude 账户**：如果 Desktop 能够[重新接入进程](#reopen-a-session-after-you-quit-desktop)，您会重新获得正在运行的任务。如果无法重新接入，任务会停止。如果任务一直处于停止状态，请发送消息。1140* **退出之后**：任务会继续运行，但除非 Desktop 能重新接入其进程，否则当会话再次打开时您会失去该任务。退出之前，请查看 [Desktop 何时可以重新接入](#reopen-a-session-after-you-quit-desktop)。如果您失去了任务，请发送消息以继续。

1141* **退出后，Windows 上的 Desktop 或使用[第三方提供商](/docs/zh-CN/third-party-integrations)**：您会失去正在运行的任务，因为 Desktop 会在会话打开时结束该进程。请发送消息以继续。

1142 1141 

1143当您回来而任务尚未完成时，请检查是否有 Desktop 无法重新连接的提示、身份验证错误或等待中的请求：1142当您回来而任务尚未完成时，请检查是否有 Desktop 无法重新连接的提示、身份验证错误或等待中的请求：

1144 1143 

1154</h5>1153</h5>

1155 1154 

1156* **先更新**：在开始长时间任务之前更新 Desktop。在 macOS 和 Windows 上，Desktop 可能会自行重启以安装已下载的更新。当 Claude 正在处理 SSH 任务时，该重启会等待。在使用 Claude 账户的 macOS 上，默认情况下，更新等待 72 小时后，重启仍可能进行。1155* **先更新**：在开始长时间任务之前更新 Desktop。在 macOS 和 Windows 上，Desktop 可能会自行重启以安装已下载的更新。当 Claude 正在处理 SSH 任务时，该重启会等待。在使用 Claude 账户的 macOS 上，默认情况下，更新等待 72 小时后，重启仍可能进行。

1157* **不要退出 Desktop**：如果 Desktop 在 Windows 上运行或使用第三方提供商，请在长时间任务运行期间保持其打开。退出后，它会在会话打开时[结束正在运行的任务](#reopen-a-session-after-you-quit-desktop)。保持打开并不能保护[等待您处理](#handle-requests-that-arrive-while-you-are-away)的请求。1156* **在 Windows 上，或在 v2.42304.0 之前使用第三方提供商时，不要退出**：在这些情况下，退出后您会失去正在运行的任务，因此请在任务期间保持 Desktop 打开。在其他任何情况下，退出之前请查看[您能找回什么](#reopen-a-session-after-you-quit-desktop)。

1158* **减少请求**：选择[让任务更少等待您](#handle-requests-that-arrive-while-you-are-away)的权限模式、规则或 hook1157* **减少请求**：选择[让任务更少等待您](#handle-requests-that-arrive-while-you-are-away)的权限模式、规则或 hook

1159* **检查跳板机**：如果您的跳板机要求登录（例如向手机发送推送），请改用无需提示即可工作的登录方式。否则，Desktop 每次尝试重新连接时都可能发送另一条推送。1158* **检查跳板机**：如果您的跳板机要求登录（例如向手机发送推送），请改用无需提示即可工作的登录方式。否则，Desktop 每次尝试重新连接时都可能发送另一条推送。

1160* **测试远程计算机**：启动一个短任务，在任务仍在运行时退出 Desktop，并在任务应该完成很久之后再次打开会话。如果任务尚未完成且会话未显示身份验证错误，请检查远程计算机上[可能结束任务的因素](#limits-while-desktop-is-disconnected)。1159* **测试远程计算机**：启动一个短任务，在任务仍在运行时退出 Desktop，并在任务应该完成很久之后再次打开会话。如果任务尚未完成且会话未显示身份验证错误，请检查远程计算机上[可能结束任务的因素](#limits-while-desktop-is-disconnected)。

1206 1205 

1207如果 Claude 在 Desktop 断开连接期间需要您的批准或向您提问，Claude 会在远程计算机上等待。该等待本身没有时间限制。当 Desktop 重新接入进程时，它会向您显示该请求。如果 Desktop 改为启动新进程，您将失去该请求。1206如果 Claude 在 Desktop 断开连接期间需要您的批准或向您提问，Claude 会在远程计算机上等待。该等待本身没有时间限制。当 Desktop 重新接入进程时，它会向您显示该请求。如果 Desktop 改为启动新进程，您将失去该请求。

1208 1207 

1209在任务等待您期间，Desktop 可能会自行重启，例如为了安装更新。如果 Desktop 在 Windows 上运行或使用第三方提供商，重启后您将失去该请求。1208如果您回来时发现一个等待您的请求不见了，原因之一是 Desktop 自行重启了，例如为了安装更新。只有当 Desktop 能重新接入进程时，请求才能在重启后保留，因此在让任务保持运行之前，请查看 [Desktop 何时可以重新接入](#reopen-a-session-after-you-quit-desktop)。

1210 1209 

1211如果您失去了请求，请发送消息以继续。1210如果您失去了请求，请发送消息以继续。

1212 1211 

1238 - **跳板机，推送持续不断**：在 Desktop 无法判断无人响应的情况下（例如 Windows 上的 Desktop），只要有可重新接入的进程，无论该进程是否仍在运行，它都会持续尝试。每次尝试您都可能收到另一条推送。若要结束尝试，请退出 Desktop，但这[可能会让您失去正在运行的任务](#reopen-a-session-after-you-quit-desktop)。1237 - **跳板机，推送持续不断**：在 Desktop 无法判断无人响应的情况下（例如 Windows 上的 Desktop），只要有可重新接入的进程，无论该进程是否仍在运行，它都会持续尝试。每次尝试您都可能收到另一条推送。若要结束尝试，请退出 Desktop，但这[可能会让您失去正在运行的任务](#reopen-a-session-after-you-quit-desktop)。

1239 - **长时间中断**：Desktop 会放慢到大约每五分钟尝试一次。若要更快重新连接，请在会话中重试或发送消息，Desktop 会在连接后投递该消息。1238 - **长时间中断**：Desktop 会放慢到大约每五分钟尝试一次。若要更快重新连接，请在会话中重试或发送消息，Desktop 会在连接后投递该消息。

1240 - **输出缺失**：在 Desktop 断开连接期间，辅助程序会在 16 MiB 缓冲区中保留每个会话最近的 Claude Code 输出，并丢弃较早的输出。Desktop 重新连接后，会话可能会显示 `Loading recent output from <host>…`。如果 Desktop 无法加载全部输出，您会看到一行 `Some output produced while you were disconnected may be missing here.`。该行并不表示任务已停止。1239 - **输出缺失**：在 Desktop 断开连接期间，辅助程序会在 16 MiB 缓冲区中保留每个会话最近的 Claude Code 输出，并丢弃较早的输出。Desktop 重新连接后，会话可能会显示 `Loading recent output from <host>…`。如果 Desktop 无法加载全部输出，您会看到一行 `Some output produced while you were disconnected may be missing here.`。该行并不表示任务已停止。

1241 - **进程已不存在**：如果 Desktop 重新连接时进程已不存在，Desktop 可以根据对话已保存的历史记录启动新进程，并让 Claude 继续该任务。如果进程不断结束，或 Desktop 使用第三方提供商，Desktop 不会自行继续该任务。请发送消息以继续。1240 - **进程已不存在**：进程在 Desktop 断开连接期间结束了，例如远程机器重启时。Desktop 随后可以根据对话保存的历史记录启动一个新进程，并让 Claude 继续该任务。如果任务仍处于停止状态，请发送消息。使用第三方提供商时，请更新到 Claude Desktop v2.42304.0 或更高版本，因为较早的版本从不会自行继续任务。

1242</Accordion>1241</Accordion>

1243 1242 

1244<a id="reopen-a-session-after-you-quit-desktop" />1243<a id="reopen-a-session-after-you-quit-desktop" />

1247 退出 Desktop 后重新打开会话1246 退出 Desktop 后重新打开会话

1248</h5>1247</h5>

1249 1248 

1250退出 Desktop 后，任务会继续在远程计算机上运行，直到完成、需要您处理或达到某项[限制](#limits-while-desktop-is-disconnected)。1249退出 Desktop 后，任务会在远程机器上继续运行，但除非 Desktop 能重新接入其进程，否则会话再次打开时任务会停止。在 Desktop 关闭期间，任务会一直运行，直到完成、需要您介入或达到某项[限制](#limits-while-desktop-is-disconnected)。

1251 1250 

1252* **macOS 或 Linux 上的 Desktop，使用 Claude 账户**：启动 Desktop 并打开会话。当 Desktop 能够重新接入进程时，您会重新获得正在运行的任务。它并不总能重新接入，例如在某些 Desktop 更新之后，或在您的组织更改其托管设置之后。1251* **Windows 上的 Desktop**：您无法找回正在运行的任务，因为 Desktop 在退出后从不重新接入。请仅在您预计任务已完成时再次启动 Desktop，因为会话可能会在 Desktop 启动时打开。

1253* **在 macOS 或 Linux 上，Desktop 无法重新接入时**：Desktop 会结束该进程，并根据对话已保存的历史记录启动新进程。您正在运行的任务会停止，并且您会失去任何正在等待您处理的批准或问题。更新后，Desktop 随后可能会让 Claude 继续。如果任务一直处于停止状态，请发送消息。1252* **第三方提供商，来自较早版本的任务**：如果您在 v2.42304.0 之前的 Desktop 版本中启动了任务，在 macOS 或 Linux 上也无法找回它。请仅在您预计任务已完成时再次启动 Desktop。

1254* **Windows 上的 Desktop，或在任何平台上使用第三方提供商**：仅在您预计任务已完成时再启动 Desktop。您无法重新获得正在运行的任务，因为 Desktop 退出后从不重新接入。它会在会话打开时结束该进程，而这可能在 Desktop 启动时就发生。请发送消息以继续。1253* **其他任何任务，在 macOS 或 Linux 上的 Desktop 中**：启动 Desktop 并打开会话，如果 Desktop 重新接入，任务就会继续。它并不总能重新接入，例如在某些 Desktop 更新之后，因此请[在长时间任务之前更新](#prepare-a-long-task)。

1254 

1255当 Desktop 无法重新接入时，您也会失去任何正在等待您的批准或问题。如果任务没有自行继续，请发送消息，Claude 会根据对话保存的历史记录继续。

1255 1256 

1256有关第三方部署，请参阅 [3P 上 Claude Desktop 中的 SSH 远程会话](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。1257有关第三方部署，请参阅 [3P 上 Claude Desktop 中的 SSH 远程会话](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。

1257 1258 

186 | - | - | - |186 | - | - | - |

187 | **运行** | Shell 命令、HTTP 请求、MCP 工具调用、LLM 提示或 subagent | Claude 读取和遵循的说明 |187 | **运行** | Shell 命令、HTTP 请求、MCP 工具调用、LLM 提示或 subagent | Claude 读取和遵循的说明 |

188 | **由以下触发** | [生命周期事件](/docs/zh-CN/hooks#hook-events)，如 `PostToolUse` 或 `SessionStart` | 您输入 `/<name>`，或 Claude 将描述与您的任务相匹配 |188 | **由以下触发** | [生命周期事件](/docs/zh-CN/hooks#hook-events)，如 `PostToolUse` 或 `SessionStart` | 您输入 `/<name>`，或 Claude 将描述与您的任务相匹配 |

189 | **确定性** | 总是在其事件上触发；触发器是有保证的 | Claude 解释说明；结果可能会有所不同 |189 | **确定性** | 在其事件上触发，无需 Claude 决定 | Claude 解释说明；结果可能会有所不同 |

190 | **上下文成本** | 零，除非 hook 返回输出 | 描述在每个会话加载；使用时加载完整内容 |190 | **上下文成本** | 零，除非 hook 返回输出 | 描述在每个会话加载；使用时加载完整内容 |

191 | **最适合** | 每次都以相同方式运行且不需要 Claude 思考的操作 | 需要推理的工作流、参考材料、多步骤任务 |191 | **最适合** | 每次都以相同方式运行且不需要 Claude 思考的操作 | 需要推理的工作流、参考材料、多步骤任务 |

192 192 

1832 1832 

1833使用 [PreToolUse 决策控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。1833使用 [PreToolUse 决策控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。

1834 1834 

1835`PreToolUse` 上的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 超过其超时时间时，会阻止该工具调用，Claude 会收到一个指明该超时的错误结果。另一个 hook 返回的显式拒绝仍然优先。1835`PreToolUse` 上的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 超过其超时时间时，会阻止工具调用，Claude 会收到一个注明该超时的错误结果。

1836 1836 

1837<h4 id="pretooluse-input">1837<h4 id="pretooluse-input">

1838 PreToolUse 输入1838 PreToolUse 输入

3428* 您删除在该 worktree 中运行的[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)3428* 您删除在该 worktree 中运行的[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)

3429* 您在会话期间要求 Claude 退出并删除 worktree，Claude 使用 [`ExitWorktree`](/docs/zh-CN/tools-reference) 工具将其删除3429* 您在会话期间要求 Claude 退出并删除 worktree，Claude 使用 [`ExitWorktree`](/docs/zh-CN/tools-reference) 工具将其删除

3430* 由 [`claude remote-control`](/docs/zh-CN/remote-control#start-a-remote-control-session) 以 `worktree` 模式启动的会话在未崩溃的情况下结束，并且 Claude Code 在其 worktree 中未发现已更改或未跟踪的文件，也没有新的提交3430* 由 [`claude remote-control`](/docs/zh-CN/remote-control#start-a-remote-control-session) 以 `worktree` 模式启动的会话在未崩溃的情况下结束，并且 Claude Code 在其 worktree 中未发现已更改或未跟踪的文件，也没有新的提交

3431* 您在由 `claude remote-control` 以 `worktree` 模式启动的会话仍在运行时停止 `claude remote-control`，并且 Claude Code 在它们的 worktree 中未发现已更改或未跟踪的文件，也没有新的提交3431* 您在由 `claude remote-control` 以 `worktree` 模式启动的会话仍在运行时停止它，并且 Claude Code 在这些会话的 worktree 中未发现已更改或未跟踪的文件，也没有新的提交

3432 3432 

3433当子代理或工作流 Agent 完成时，Claude Code 会保留您的 WorktreeCreate hook 为其创建的 worktree，并且不会运行您的 WorktreeRemove hook。工作完成后，请自行删除这些 worktree。3433当子代理或工作流 Agent 完成时，Claude Code 会保留您的 WorktreeCreate hook 为其创建的 worktree，并且不会运行您的 WorktreeRemove hook。工作完成后，请自行删除这些 worktree。

3434 3434 

213如果安装失败，请匹配 Claude Code 报告的消息：213如果安装失败，请匹配 Claude Code 报告的消息：

214 214 

215* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。215* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

216* 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。216* `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后仍显示相同的消息，请参阅[在市场中找不到插件](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

217 217 

218要为存储库中的每个人启用插件而不是自己安装，请将其添加到 [`enabledPlugins` 项目设置](/docs/zh-CN/settings-reference#plugin-settings)。218要为存储库中的每个人启用插件而不是自己安装，请将其添加到 [`enabledPlugins` 项目设置](/docs/zh-CN/settings-reference#plugin-settings)。

219 219 

49 49 

50 如果安装失败，请匹配 Claude Code 报告的消息：50 如果安装失败，请匹配 Claude Code 报告的消息：

51 51 

52 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加 marketplace，然后重试安装。52 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加该市场，然后重试安装。

53 * plugin [在 marketplace 中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查 plugin 名称。53 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后显示相同的消息，请参阅 [Plugin not found in marketplace](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

54 54 

55 如果安装摘要报告 `Run /reload-plugins to apply.`，Claude Code 会为您运行该重新加载。如果重新加载警告您的下一条消息会重新读取对话，请运行 `/reload-plugins --force`。55 如果安装摘要报告 `Run /reload-plugins to apply.`，Claude Code 会为您运行该重新加载。如果重新加载警告您的下一条消息会重新读取对话，请运行 `/reload-plugins --force`。

56 </Step>56 </Step>

772**属性**：772**属性**：

773 773 

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

775* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）。`"input"` 类型不包括从提示词缓存读取或写入提示词缓存的 token，这些 token 计入 `"cacheRead"` 和 `"cacheCreation"`775* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）。`"input"` 类型不包括从提示缓存读取或写入提示缓存的 token，这些 token 计入 `"cacheRead"` 和 `"cacheCreation"`。`"cacheCreation"` 类型将五分钟和一小时[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)的缓存写入合并计数。

776* `model`：模型标识符（例如 "claude-sonnet-5"）776* `model`：模型标识符（例如 "claude-sonnet-5"）

777* `query_source`：发出请求的子系统类别。取值为 `"main"`、`"subagent"` 或 `"auxiliary"` 之一777* `query_source`：发出请求的子系统类别。取值为 `"main"`、`"subagent"` 或 `"auxiliary"` 之一

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

826 826 

827要追踪由单个提示词触发的所有活动，请按特定的 `prompt.id` 值过滤您的事件。这会返回处理该提示词期间发生的 user\_prompt 事件、所有 api\_request 事件以及所有 tool\_result 事件。827要追踪由单个提示词触发的所有活动，请按特定的 `prompt.id` 值过滤您的事件。这会返回处理该提示词期间发生的 user\_prompt 事件、所有 api\_request 事件以及所有 tool\_result 事件。

828 828 

829每次 Claude Code 进程启动时，`event.sequence` 从 0 开始，并在该进程的生命周期内递增。它在 `/clear` 之后继续计数，`/clear` 会分配一个新的 `session.id`。如果您[在不分叉的情况下恢复会话](/docs/zh-CN/how-claude-code-works#resume-or-fork-sessions)，会话会保留其 `session.id`，但其 `event.sequence` 值来自恢复它的进程，因此在同一会话中，较晚的事件可能携带比较早事件更低的值，或者重复某个值。要对会话的事件排序，请按 `event.timestamp` 排序，并使用 `event.sequence` 对共享同一时间戳的事件进行排序。829`event.sequence` 在每次 Claude Code 进程启动时从 0 开始，并在该进程的生命周期内递增。它在 `/clear`（会分配新的 `session.id`）之后继续计数。如果您[在不分叉的情况下恢复会话](/docs/zh-CN/how-claude-code-works#resume-or-fork-sessions)，会话会保留其 `session.id`，但其 `event.sequence` 值取自恢复它的进程，因此在同一会话中，较晚的事件可能携带比较早事件更小的值，或者重复某个值。要对会话的事件进行排序，请按 `event.timestamp` 排序，并使用 `event.sequence` 对共享同一时间戳的事件进行排序。

830 830 

831为了进行消息级别的重建，每类事件都携带一个与会话记录中某个字段匹配的键。会话记录的条目格式[属于 Claude Code 内部实现](/docs/zh-CN/sessions#where-transcripts-are-stored)，并且会在版本之间变化，因此基于这些字段进行关联的管道可能在任何版本发布时失效；请将这些关联视为特定于版本的，而不是稳定的约定：831为了进行消息级别的重建，每类事件都携带一个与会话记录中某个字段匹配的键。会话记录的条目格式[属于 Claude Code 内部实现](/docs/zh-CN/sessions#where-transcripts-are-stored)，并且会在版本之间变化，因此基于这些字段进行关联的管道可能在任何版本发布时失效；请将这些关联视为特定于版本的，而不是稳定的约定：

832 832 

749这些检查仍然适用：749这些检查仍然适用：

750 750 

751* 内容范围的 ask 规则（如 `Bash(git push *)`）仍然强制提示751* 内容范围的 ask 规则（如 `Bash(git push *)`）仍然强制提示

752* 显式 deny 规则仍然适用

753* 针对[关键路径](/docs/zh-CN/permission-modes#critical-paths)的 `rm` 或 `rmdir` 命令仍然通过常规权限流程

754* 其他沙箱化的命令也可能通过常规权限流程，如[自动允许模式](/docs/zh-CN/sandboxing#auto-allow-mode)中所述752* 其他沙箱化的命令也可能通过常规权限流程，如[自动允许模式](/docs/zh-CN/sandboxing#auto-allow-mode)中所述

755 753 

756不会在沙箱中运行的命令（如排除的命令）按照通常的方式遵守裸 `Bash` ask 规则。请参见[沙箱模式](/docs/zh-CN/sandboxing#sandbox-modes)以更改此行为。754不会在沙箱中运行的命令（如排除的命令）按照通常的方式遵守裸 `Bash` ask 规则。请参见[沙箱模式](/docs/zh-CN/sandboxing#sandbox-modes)以更改此行为。

78 78 

79Mods 不会替换您已有的控制：79Mods 不会替换您已有的控制：

80 80 

81* **设置 hooks 继续工作。** 设置文件和插件的 `hooks/hooks.json` 中的命令、HTTP、提示和代理 hooks 照常运行，与 mods 一起。关于它们的任何内容都没有被弃用。81* **设置 hook 继续工作。** 设置文件和插件的 `hooks/hooks.json` 中的命令、HTTP、提示词和 Agent hook 照常运行，与 mod 一起。

82* **拒绝规则在保护程序加载的地方优先。** 用户的 mod 无法批准 `deny` 规则拒绝的调用，除非您设置 [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)。82* **拒绝规则在保护程序加载的地方优先。** 用户的 mod 无法批准 `deny` 规则拒绝的调用，除非您设置 [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)。

83* **托管 hooks 首先运行。** 托管设置中的 `PreToolUse` hook 在任何 mod 看到工具调用之前运行，其块是最终的。如果 mod 随后重写调用，您的托管 hooks 在重写的调用上再次运行，因此块仍然适用。来自其他设置文件和插件的 `PreToolUse` hooks 在最后一个 mod 之后运行，因此返回自己结果代替运行工具的 mod 会阻止这些运行。请参阅[mods 运行的顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)。83* **托管 hooks 首先运行。** 托管设置中的 `PreToolUse` hook 在任何 mod 看到工具调用之前运行，其块是最终的。如果 mod 随后重写调用，您的托管 hooks 在重写的调用上再次运行，因此块仍然适用。来自其他设置文件和插件的 `PreToolUse` hooks 在最后一个 mod 之后运行，因此返回自己结果代替运行工具的 mod 会阻止这些运行。请参阅[mods 运行的顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)。

84* **网络策略涵盖 `$.http.fetch`。**84* **网络策略涵盖 `$.http.fetch`。**

114 `Text`114 `Text`

115</h3>115</h3>

116 116 

117`Text` 使用您指定的样式绘制字符串。此示例每种样式显示一行：117`Text` 使用您指定的样式绘制字符串。此示例显示纯文本和八种样式，每行一种：

118 118 

119```javascript theme={null}119```javascript theme={null}

120Box({120Box({

455 455 

456| 元素 | 它绘制什么 | 位置 |456| 元素 | 它绘制什么 | 位置 |

457| :- | :- | :- |457| :- | :- | :- |

458| `Box` | 一个 flex 容器。接受布局 prop，如 `flexDirection`、`columnGap`、`padding`、[`borderStyle`](/docs/zh-CN/plugins/mods/reference#box-border-styles) 和 `width`。 | 到处 |458| `Box` | 一个 flex 容器。接受布局 prop，如 `flexDirection`、[`borderStyle`](/docs/zh-CN/plugins/mods/reference#box-border-styles) 和 `width`。`columnGap` 和 `padding` 等间距 prop 接受一个数字，或从 `'xs'` 到 `'xl'` 的[步长名称](/docs/zh-CN/plugins/mods/reference#box-spacing-steps)。 | 到处 |

459| `Text` | 样式化文本。接受 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主题键或颜色，如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到处 |459| `Text` | 样式化文本。接受 `color`、`bold`、`dimColor`、`italic`、`wrap` 以及 [`weight`](/docs/zh-CN/plugins/mods/reference#text-typography) 等其他 prop。`color` 是主题键或颜色，如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到处 |

460| `Button` | 调用 `onPress` 的控件 | 到处 |460| `Button` | 调用 `onPress` 的控件 | 到处 |

461| `Link`, `Code`, `Markdown` | 带有 `href` 和可选 `label` 的链接、代码块和格式化为 Claude 回复方式的文本。`Markdown` 在 `text` 属性中而不是在 `children` 中获取其内容，当您传递 `onLinkPress` 时需要 `key`。 | 到处 |461| `Link`, `Code`, `Markdown` | 带有 `href` 和可选 `label` 的链接、代码块和格式化为 Claude 回复方式的文本。`Markdown` 在 `text` 属性中而不是在 `children` 中获取其内容，当您传递 `onLinkPress` 时需要 `key`。 | 到处 |

462| `Input`, `Select` | 文本字段和下拉列表 | 终端、桌面、VS Code |462| `Input`, `Select` | 文本字段和下拉列表 | 终端、桌面、VS Code |

293 293 

294| 元素 | 主要 prop | 终端 | Desktop | VS Code |294| 元素 | 主要 prop | 终端 | Desktop | VS Code |

295| :- | :- | :-: | :-: | :-: |295| :- | :- | :-: | :-: | :-: |

296| [`Box`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 布局、`gap`、`padding`、`margin`、`width`、`height`、[`borderStyle`](#box-border-styles)、`backgroundColor`、`position`、`hover` | ✓ | ✓ | ✓ |296| [`Box`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 布局、[`gap`、`padding`、`margin`](#box-spacing-steps)、`width`、`height`、[`borderStyle`](#box-border-styles)、`backgroundColor`、`position`、`hover` | ✓ | ✓ | ✓ |

297| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ | ✓ |297| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、[`bold`](#text-bold)、`italic`、`underline`、`dimColor`、`inverse`、`wrap`、[`size`、`weight`、`mono`、`tabular`](#text-typography) | ✓ | ✓ | ✓ |

298| [`Button`](/docs/zh-CN/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ | ✓ |298| [`Button`](/docs/zh-CN/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ | ✓ |

299| [`Link`](/docs/zh-CN/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。请参阅[限制](#limits)。 | ✓ | ✓ | ✓ |299| [`Link`](/docs/zh-CN/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。请参阅[限制](#limits)。 | ✓ | ✓ | ✓ |

300| [`Code`](/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ | ✓ |300| [`Code`](/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ | ✓ |

311VS Code 扩展会忽略某些元素 prop，并像您省略了这些 prop 一样绘制该元素：311VS Code 扩展会忽略某些元素 prop，并像您省略了这些 prop 一样绘制该元素：

312 312 

313* **`Box`**：`position` 和 `hover`313* **`Box`**：`position` 和 `hover`

314* **`Text`**：`size`、`mono` 和 `tabular`

314* **`Button`**：`hotkey`、`plain`、`autoFocus` 和 `action`，因此用户在其中通过点击来按下按钮，或在按钮获得焦点后按 Enter315* **`Button`**：`hotkey`、`plain`、`autoFocus` 和 `action`，因此用户在其中通过点击来按下按钮，或在按钮获得焦点后按 Enter

315* **`Code`**：`language`、`path`、`startLine`、`format` 和 `wrap`，因此代码绘制时不带颜色或行号，而 `format: 'diff'` 代码块会显示 diff 的原始文本316* **`Code`**：`language`、`path`、`startLine`、`format` 和 `wrap`，因此代码绘制时不带颜色或行号，而 `format: 'diff'` 代码块会显示 diff 的原始文本

316* **`Input` 和 `Select`**：`autoFocus`317* **`Input` 和 `Select`**：`autoFocus`

336 337 

337如果 `Box` 的 `borderStyle` 指定的是其他名称（例如 `'rounded'`），则绘制时不带边框。338如果 `Box` 的 `borderStyle` 指定的是其他名称（例如 `'rounded'`），则绘制时不带边框。

338 339 

340<h3 id="box-spacing-steps">

341 `Box` 间距步长

342</h3>

343 

344`Box` 的间距 prop 包括 `gap`、`columnGap`、`rowGap`、`padding`、`margin`，以及 `padding` 和 `margin` 的单边和单轴形式，例如 `paddingX` 和 `marginTop`。每个 prop 都接受以终端单元格为单位的数字（例如 `gap: 1`），或步长名称（例如 `gap: 'md'`）。在终端和 VS Code 扩展中，每个步长对应的单元格数如下：

345 

346| 步长 | 横向单元格数 | 纵向单元格数 |

347| :- | :- | :- |

348| `'xs'` | 1 | 0 |

349| `'sm'` | 1 | 0 |

350| `'md'` | 2 | 1 |

351| `'lg'` | 3 | 1 |

352| `'xl'` | 4 | 2 |

353 

354如果将 `gap`、`padding` 或 `margin` 设置为某个步长，该步长会同时应用于横向和纵向。例如，在终端和 VS Code 扩展中，`padding: 'md'` 表示左右两侧各两个单元格，上下各一行。

355 

356步长名称需要 Claude Code v2.1.299 或更高版本。在更早的版本中，对于使用了步长名称的树，Claude Code 会[绘制它自己版本的该位置内容](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)来代替。

357 

358<h3 id="text-typography">

359 `Text` 排版 prop

360</h3>

361 

362在 `Text` 上设置 `size`、`weight`、`mono` 或 `tabular`，可以请求绘制您的树的应用使用某种文字大小、字重、等宽字体或等宽数字。在依赖某个 prop 之前，请先确认终端和 VS Code 扩展如何处理它。如果某个应用忽略了您设置的 prop，您的树仍会在其中绘制，文本显示效果与您省略该 prop 时相同。

363 

364| Prop | 取值 | 在终端中 | 在 VS Code 扩展中 |

365| :- | :- | :- | :- |

366| `size` | `'caption'`、`'footnote'`、`'body'`、`'heading'` 或 `'title'` | 忽略：终端只有一种文字大小 | 忽略 |

367| `weight` | `'regular'`、`'medium'`、`'semibold'` 或 `'bold'` | `semibold` 和 `bold` 绘制为粗体文本 | `semibold` 和 `bold` 绘制为粗体文本 |

368| `mono` | `true`，请求使用应用的等宽字体 | 忽略：终端始终是等宽的 | 忽略，因此文本保持扩展自身的字体 |

369| `tabular` | `true`，请求使用等宽数字，使原地更新的数字或一列数字保持对齐 | 忽略：终端中的数字本来就占一个单元格宽 | 忽略 |

370 

371这四个 prop 需要 Claude Code v2.1.299 或更高版本。在更早的版本中，对于设置了 `size`、`weight`、`mono` 或 `tabular` 的树，Claude Code 会[绘制它自己版本的该位置内容](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)来代替。

372 

373<h4 id="text-bold">

374 用 `weight` 替换 `bold`

375</h4>

376 

377`Text` 上的 `bold` 已弃用，建议改用 `weight`，但它仍然可用。要在未设置 `weight` 的 `Text` 上替换它，请将 `bold: true` 改为 `weight: 'semibold'`，在 Claude Code v2.1.299 或更高版本上效果相同。

378 

379在早于 v2.1.299 的版本中，设置了 `weight` 的树不会绘制，Claude Code 会改为[绘制它自己版本的该位置内容](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。如果您在 `Text` 上同时设置了 `bold` 和 `weight`，则 `bold` 不起作用。

380 

339<h2 id="limits">381<h2 id="limits">

340 限制382 限制

341</h2>383</h2>

235 235 

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

237 237 

238<h3 id="another-mods-band-shows-and-yours-doesnt">

239 显示了另一个 mod 的带，而您的带没有显示

240</h3>

241 

242输入框上方只有一个带，所有 mod 共用它。在[您的 mod 之前](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)运行的 mod 如果返回的树中不包含 `next(e)` 的结果，就会替换您的带。要同时显示两个带，请修改该 mod 的 hook，或请其作者修改：

243 

244* **保留其后的带**：将 `await next(e)` 的结果放入其树中某个 `Box` 的子元素中，如[选择绘制位置](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw)中“输入框上方的带”选项卡所示

245* **保持树有效**：不要为该 `Box` 或其外层的任何 `Box` 设置 `width`、`height`、`minWidth`、`minHeight`、`position`、`top`、`left`、`right`、`bottom`、`display` 或 `overflow` prop

246 

247要找到该 mod，请[写入调试日志](#read-the-debug-log)并在其中搜索 `answered ui.render without next()`。诸如 `other-mod (user) answered ui.render without next()` 的行会指明一个返回了树但未调用 `next(e)` 的 mod。该行不会指明[渲染位置](/docs/zh-CN/plugins/mods/reference#render-sites)，因此仅绘制窗格的 mod 也可能出现在其中。调用了 `next(e)` 但丢弃其结果的 mod 不会产生该行，因此也请检查在您的 mod 之前运行的 hook。

248 

249进行更改后，如果任一 mod 返回的树未通过验证，带中将不显示任何内容。要了解原因，请在 `--plugin-dir` 会话的会话记录中查找 `ui.render (AbovePrompt) refused:` 行，或在调试日志中搜索 `does not validate`。当带中有多个 mod 时，这两行都不会指明具体的 mod，因此请检查每个 mod 的树。

250 

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

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

240</h3>253</h3>

199 199 

200即使在自动允许模式下，以下规则仍然适用：200即使在自动允许模式下，以下规则仍然适用：

201 201 

202* 始终遵守明确的[拒绝规则](/docs/zh-CN/permissions)202* 采用 [`Bash` 拒绝规则所匹配的形式](/docs/zh-CN/permissions#bash-rule-limits)的命令仍会被阻止

203* 针对[关键路径](/docs/zh-CN/permission-modes#critical-paths)的 `rm` 或 `rmdir` 命令仍会经过常规权限流程203* 被识别为针对[关键路径](/docs/zh-CN/permission-modes#which-paths-are-critical)的 `rm` 或 `rmdir` 命令仍会经过常规权限流程

204* 限定内容范围的[询问规则](/docs/zh-CN/permissions)（如 `Bash(git push *)`）即使对沙箱命令也仍会强制提示204* 限定内容范围的[询问规则](/docs/zh-CN/permissions)（如 `Bash(git push *)`）即使对沙箱命令也仍会强制提示

205* 单独的 `Bash` 询问规则或等效的 `Bash(*)` 形式，对于在沙箱中运行的命令会被跳过；对于在沙箱外运行的命令仍然适用。在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)下，该规则不会被跳过：它同样会对沙箱命令进行提示，包括只读命令205* 单独的 `Bash` 询问规则或等效的 `Bash(*)` 形式，对于在沙箱中运行的命令会被跳过；对于在沙箱外运行的命令仍然适用。在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)下，该规则不会被跳过：它同样会对沙箱命令进行提示，包括只读命令

206* [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool)的命令不会被自动批准，但仍会在沙箱中运行。要跳过提示，请添加与该命令匹配的[允许规则](/docs/zh-CN/permissions#bash)，例如 `Bash(npm run *)`206* [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool)的命令不会被自动批准，但仍会在沙箱中运行。要跳过提示，请添加与该命令匹配的[允许规则](/docs/zh-CN/permissions#bash)，例如 `Bash(npm run *)`

112 IDE 安全性112 IDE 安全性

113</h2>113</h2>

114 114 

115有关在 IDE 中运行 Claude Code 的更多信息，请参阅 [VS Code security and privacy](/docs/zh-CN/vs-code#security-and-privacy)。115有关在 IDE 中运行 Claude Code 的更多信息，请参阅[内置 IDE MCP 服务器](/docs/zh-CN/vs-code#the-built-in-ide-mcp-server)。

116 116 

117<h2 id="cloud-execution-security">117<h2 id="cloud-execution-security">

118 云执行安全性118 云执行安全性

42如果安装失败，请匹配 Claude Code 报告的消息：42如果安装失败，请匹配 Claude Code 报告的消息：

43 43 

44* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。44* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

45* 插件[在市场中未找到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。45* `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过时。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后仍显示相同的消息，请参阅[插件在市场中未找到](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

46 46 

47检查安装摘要。如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以在当前会话中激活插件。47检查安装摘要。如果它报告 `Run /reload-plugins to apply.`，请参阅[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins)以在当前会话中激活插件。

48 48 

718 718 

719如果您在调用 skill 时传递了参数，但 skill 内容中没有占位符接收参数，Claude Code 会将 `ARGUMENTS: <your input>` 附加到 skill 内容的末尾，以便 Claude 仍能看到您输入的内容。占位符是指 `$ARGUMENTS`、索引形式（例如 `$1`）或命名参数。在其位置上没有参数的索引占位符会保留为字面文本，不算作接收了参数。命名占位符即使在其位置上没有参数也算作接收了参数，因为它会展开为空字符串。719如果您在调用 skill 时传递了参数，但 skill 内容中没有占位符接收参数，Claude Code 会将 `ARGUMENTS: <your input>` 附加到 skill 内容的末尾，以便 Claude 仍能看到您输入的内容。占位符是指 `$ARGUMENTS`、索引形式（例如 `$1`）或命名参数。在其位置上没有参数的索引占位符会保留为字面文本，不算作接收了参数。命名占位符即使在其位置上没有参数也算作接收了参数，因为它会展开为空字符串。

720 720 

721您还可以在一条消息的开头叠加多个 skill。输入 `/write-tests /fix-issue 123` 会加载这两个 skill，并将末尾的文本 `123` 作为 `$ARGUMENTS` 传递给每个 skill。

722 

723Claude Code 会展开第一个 skill 以及其后叠加的最多五个 skill。展开会在第一个不是内联用户可调用 skill 的标记处停止，因此以[分叉子代理](#run-skills-in-a-subagent)方式运行的 skill（例如 [`/code-review`](/docs/zh-CN/code-review-local)），或其参数本身可能以斜杠命令开头的 skill（例如 `/loop`），也会在该处终止叠加。该标记及其后的所有内容会成为每个已展开 skill 的参数文本。从 v2.1.218 起，`/code-review` 以分叉子代理方式运行；在更早的版本中，它以内联方式运行并可叠加。

724 

725要按位置访问单个参数，请使用 `$ARGUMENTS[N]` 或更简短的 `$N`：721要按位置访问单个参数，请使用 `$ARGUMENTS[N]` 或更简短的 `$N`：

726 722 

727```yaml theme={null}723```yaml theme={null}

746Preserve all existing behavior and tests.742Preserve all existing behavior and tests.

747```743```

748 744 

745<h4 id="stack-several-skills-in-one-message">

746 在一条消息中叠加多个 skill

747</h4>

748 

749在终端的 Claude Code 输入框中输入时，您可以在一条消息的开头叠加多个 skill。通过 Agent SDK 或 `claude -p` 时，Claude Code 只会加载第一个 skill，并将该行的其余部分作为其参数。在终端输入框中，输入 `/write-tests /fix-issue 123` 会加载这两个 skill，并将末尾的文本 `123` 作为 `$ARGUMENTS` 传递给每个 skill。

750 

751Claude Code 会展开第一个 skill 以及其后叠加的最多五个 skill。展开会在第一个不是内联用户可调用 skill 的标记处停止。如果您叠加了以[分叉子代理](#run-skills-in-a-subagent)方式运行的 skill（例如 [`/code-review`](/docs/zh-CN/code-review-local)），或其参数可能以另一个命令开头的 skill（例如 `/loop`），展开会在该处终止。该标记及其后的所有内容会成为每个已展开 skill 的参数文本。

752 

749<h2 id="advanced-patterns">753<h2 id="advanced-patterns">

750 高级模式754 高级模式

751</h2>755</h2>

1044如果安装失败，请匹配 Claude Code 报告的消息：1048如果安装失败，请匹配 Claude Code 报告的消息：

1045 1049 

1046* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。1050* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 添加市场，然后重试安装。

1047* [插件在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。1051* `Plugin "<name>" not found in marketplace "claude-plugins-official"`：您本地的市场目录副本可能已过期。使用 `/plugin marketplace update claude-plugins-official` 刷新它，然后重试安装。如果重试后仍显示相同的消息，请参阅[插件在市场中找不到](/docs/zh-CN/plugins/troubleshooting#plugin-not-found-in-marketplace)。

1048 1052 

1049如果安装摘要报告 `Run /reload-plugins to apply.`，Claude Code 随后会为您执行该重新加载。如果重新加载警告您的下一条消息会重新读取对话，请运行 `/reload-plugins --force`，使插件的 skill 在当前会话中可用。然后让 Claude 评估现有 skill，例如 `evaluate my summarize-changes skill with skill-creator`。该插件会引导您编写测试用例并运行循环：1053如果安装摘要报告 `Run /reload-plugins to apply.`，Claude Code 随后会为您执行该重新加载。如果重新加载警告您的下一条消息会重新读取对话，请运行 `/reload-plugins --force`，使插件的 skill 在当前会话中可用。然后让 Claude 评估现有 skill，例如 `evaluate my summarize-changes skill with skill-creator`。该插件会引导您编写测试用例并运行循环：

1050 1054 

281 全屏模式281 全屏模式

282 </h4>282 </h4>

283 283 

284 Claude Code 在默认和全屏渲染器中都绘制 `userMessageBackground`、`bashMessageBackgroundColor` 和 `memoryBackgroundColor`。它仅在[全屏渲染模式](/docs/zh-CN/fullscreen)中使用 `userMessageBackgroundHover` 和 `selectionBg`。284 Claude Code 仅在[全屏渲染模式](/docs/zh-CN/fullscreen)中使用 `userMessageBackgroundHover`、`selectionBg` 和 `composerSidebarBackground`。它在默认和全屏渲染器中都绘制 `userMessageBackground`、`bashMessageBackgroundColor` 和 `memoryBackgroundColor`。

285 285 

286 | 令牌 | 控制 |286 | 令牌 | 控制 |

287 | :- | :- |287 | :- | :- |

290 | `bashMessageBackgroundColor` | 成绩单中 `!` shell 命令条目后面的背景 |290 | `bashMessageBackgroundColor` | 成绩单中 `!` shell 命令条目后面的背景 |

291 | `memoryBackgroundColor` | 成绩单中 `#` 内存条目后面的背景 |291 | `memoryBackgroundColor` | 成绩单中 `#` 内存条目后面的背景 |

292 | `selectionBg` | 用鼠标选择的文本的背景 |292 | `selectionBg` | 用鼠标选择的文本的背景 |

293 | `composerSidebarBackground` | 对话旁边面板的背景，例如 [diff 面板](/docs/zh-CN/fullscreen#watch-your-changes-in-the-diff-panel)或 [mod 的窗格](/docs/zh-CN/plugins/mods/interface) |

293 294 

294 <h4 id="usage-meter-and-speaker-labels">295 <h4 id="usage-meter-and-speaker-labels">

295 使用量计量表和说话者标签296 使用量计量表和说话者标签

4 4 

5# 在 VS Code 中使用 Claude Code5# 在 VS Code 中使用 Claude Code

6 6 

7> 安装和配置 VS Code 的 Claude Code 扩展。获得 AI 编码协助，包括内联差异、@-提及、计划审查和快捷键。7> 安装和配置 VS Code 的 Claude Code 扩展。获得 AI 编码协助，包括内联 diff、@-提及、计划审查和快捷键。

8 8 

9<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code 编辑器，右侧打开 Claude Code 扩展面板，显示与 Claude 的对话" width="2500" height="1155" data-path="images/vs-code-extension-interface.jpg" />9<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code 编辑器，右侧打开 Claude Code 扩展面板，显示与 Claude 的对话" width="2500" height="1155" data-path="images/vs-code-extension-interface.jpg" />

10 10 

11VS Code 扩展为 Claude Code 提供了原生图形界面，直接集成到您的 IDE 中。这是在 VS Code 中使用 Claude Code 的推荐方式。11VS Code 扩展为 Claude Code 提供了原生图形界面，直接集成到您的 IDE 中。这是在 VS Code 中使用 Claude Code 的推荐方式。

12 12 

13使用该扩展，您可以在接受 Claude 的计划之前审查和编辑它们、在进行编辑时自动接受、@-提及具有特定行范围的文件、访问对话历史记录，以及在单独的选项卡或窗口中打开多个对话。13使用该扩展，您可以：

14 

15* 在接受 Claude 的计划之前审查和编辑它们

16* 在进行编辑时自动接受

17* 根据您的选择 @-提及具有特定行范围的文件

18* 访问对话历史记录

19* 在单独的选项卡或窗口中打开多个对话

14 20 

15<h2 id="prerequisites">21<h2 id="prerequisites">

16 前置条件22 前置条件

29 安装扩展35 安装扩展

30</h2>36</h2>

31 37 

32点击您的 IDE 的链接以直接安装：38点击与您的 IDE 对应的链接直接安装：

33 39 

34* [为 VS Code 安装](vscode:extension/anthropic.claude-code)40* [为 VS Code 安装](vscode:extension/anthropic.claude-code)

35* [为 Cursor 安装](cursor:extension/anthropic.claude-code)41* [为 Cursor 安装](cursor:extension/anthropic.claude-code)

36 42 

37或在 VS Code 中，按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）打开扩展视图，搜索"Claude Code"，然后点击**安装**。43或者在 VS Code 中，按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）打开扩展视图，搜索"Claude Code"，然后点击 **Install**。

38 44 

39扩展的版本号即其捆绑的 Claude Code 版本。例如，需要 Claude Code v2.1.286 或更高版本的功能，需要 2.1.286 或更高版本的扩展，扩展视图中会显示该版本号。45扩展的版本号即其捆绑的 Claude Code 版本。例如，需要 Claude Code v2.1.286 或更高版本的功能，需要 2.1.286 或更高版本的扩展，版本号可在扩展视图中查看。

40 46 

41该扩展也可以安装在其他 VS Code 分支中，如 Devin Desktop 或 Kiro。在编辑器的扩展视图中搜索"Claude Code"，或从 [Open VSX 注册表](https://open-vsx.org/extension/Anthropic/claude-code) 安装。如果您的编辑器无法安装该扩展，请[安装 CLI](/docs/zh-CN/quickstart) 并在其集成终端中运行 `claude`。CLI 可在任何终端中使用。47Claude Code 还可以在其他编辑器和容器中运行：

42 48 

43要在开发容器中运行 Claude Code，请参阅[开发容器](/docs/zh-CN/devcontainer)。49* **其他 VS Code 分支**：该扩展也可以安装在 Devin Desktop 或 Kiro 等分支中。在编辑器的扩展视图中搜索"Claude Code"，或从 [Open VSX 注册表](https://open-vsx.org/extension/Anthropic/claude-code)安装。

50* **无法安装该扩展的编辑器**：请[安装 CLI](/docs/zh-CN/quickstart)，然后在编辑器的集成终端中运行 `claude`。CLI 可在任何终端中使用。

51* **开发容器**：要在开发容器中运行 Claude Code，请参阅[开发容器](/docs/zh-CN/devcontainer)。

44 52 

45<Note>如果安装后扩展没有出现，请重启 VS Code 或从命令面板运行"Developer: Reload Window"。</Note>53<Note>如果安装后扩展没有出现，请重启 VS Code，或从命令面板运行"Developer: Reload Window"。</Note>

46 54 

47<h2 id="get-started">55<h2 id="get-started">

48 开始使用56 开始使用

49</h2>57</h2>

50 58 

51安装后，您可以通过 VS Code 界面开始使用 Claude Code：59安装完成后，您可以通过 VS Code 界面开始使用 Claude Code：

52 60 

53<Steps>61<Steps>

54 <Step title="打开 Claude Code 面板">62 <Step title="打开 Claude Code 面板">

55 在整个 VS Code 中，Spark 图标表示 Claude Code：<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/vs-code-spark-icon.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=3ca45e00deadec8c8f4b4f807da94505" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} width="16" height="16" data-path="images/vs-code-spark-icon.svg" />63 在 VS Code 中，Spark 图标代表 Claude Code：<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/vs-code-spark-icon.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=3ca45e00deadec8c8f4b4f807da94505" alt="Spark 图标" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} width="16" height="16" data-path="images/vs-code-spark-icon.svg" />

56 64 

57 打开 Claude 的最快方法是点击编辑器右上角**编辑器工具栏**中的 Spark 图标。只有当您打开了文件时，该图标才会出现。65 打开 Claude 最快的方式是点击**编辑器工具栏**（编辑器右上角）中的 Spark 图标。该图标仅在打开文件时显示。

58 66 

59 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code 编辑器显示编辑器工具栏中的 Spark 图标" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />67 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code 编辑器，编辑器工具栏中显示 Spark 图标" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />

60 68 

61 打开 Claude Code 的其他方式：69 打开 Claude Code 的其他方式：

62 70 

63 * **活动栏**：点击左侧边栏中的 Spark 图标以打开会话列表。点击任何会话以在您的[首选位置](#extension-settings)中打开它，或开始新的会话。此图标在活动栏中始终可见。71 * **活动栏**：点击左侧边栏中的 Spark 图标以打开会话列表。点击任意会话即可在您的[首选位置](#extension-settings)打开它，或者开始一个新会话。该图标始终显示在活动栏中。

64 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），输入"Claude Code"，然后选择一个选项，如"在新选项卡中打开"72 * **命令面板**：按 `Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），输入"Claude Code"，然后选择一个选项，例如"Open in New Tab"

65 * **状态栏**：点击窗口右下角的 **✻ Claude Code**。即使没有打开文件，这也有效。73 * **状态栏**：点击窗口右下角的 **✻ Claude Code**。即使没有打开任何文件，此方式也可用。

66 74 

67 您可以拖动 Claude 面板以在 VS Code 中的任何位置重新定位它。有关详细信息，请参阅[自定义您的工作流](#customize-your-workflow)。75 您可以拖动 Claude 面板，将其放置在 VS Code 中的任意位置。详情请参阅[自定义您的工作流](#customize-your-workflow)。

68 </Step>76 </Step>

69 77 

70 <Step title="登录">78 <Step title="登录">

71 第一次打开面板时，会出现登录屏幕。点击**登录**并在浏览器中完成授权。79 首次打开面板时，会显示登录界面。点击 **Sign in**，然后在浏览器中完成授权。

72 80 

73 如果您稍后看到**未登录 · 请运行 /login**，扩展程序会自动重新打开登录屏幕。如果它没有出现，请从命令面板使用**开发者：重新加载窗口**重新加载窗口。81 如果之后看到 **Not logged in · Please run /login**，扩展会自动重新打开登录界面。如果登录界面没有出现，请在命令面板中通过 **Developer: Reload Window** 重新加载窗口。

74 82 

75 如果您在 shell 中设置了 `ANTHROPIC_API_KEY` 但仍然看到登录提示，VS Code 可能没有继承您的 shell 环境。从终端使用 `code .` 启动 VS Code，以便它继承您的环境变量，或改为使用您的 Claude 账户登录。83 如果您已在 shell 中设置了 `ANTHROPIC_API_KEY`，但仍看到登录提示，则可能是 VS Code 没有继承您的 shell 环境。请在终端中使用 `code .` 启动 VS Code，使其继承您的环境变量，或者改用您的 Claude 账户登录。

76 84 

77 登录后，会出现**学习 Claude Code** 检查清单。通过点击**显示给我**来完成每一项，或使用 X 关闭它。要稍后重新打开它，请在 VS Code 设置中的扩展程序 → Claude Code 下取消选中**隐藏入门**。85 登录后，会显示 **Learn Claude Code** 清单。点击 **Show me** 逐项完成，或点击 X 将其关闭。如需稍后重新打开，请在 VS Code 设置的 **Extensions > Claude Code** 下取消勾选 **Hide Onboarding**。

78 </Step>86 </Step>

79 87 

80 <Step title="发送提示">88 <Step title="发送提示词">

81 要求 Claude 帮助您处理代码或文件，无论是解释某些内容的工作原理、调试问题还是进行更改。89 请 Claude 帮助处理您的代码或文件，无论是解释某个功能的工作原理、调试问题，还是进行修改。

82 90 

83 <Tip>Claude 会自动看到您选择的文本。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）也可以在您的提示中插入 @-mention 引用（如 `@file.ts#5-10`）。</Tip>91 <Tip>Claude 会自动看到您选中的文本。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）还可以将 @ 提及引用（例如 `@file.ts#5-10`）插入到提示词中。</Tip>

84 92 

85 以下是询问文件中特定行的示例：93 以下是询问文件中特定行的示例：

86 94 

87 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code 编辑器，在 Python 文件中选择了第 2-3 行，Claude Code 面板显示关于这些行的问题，带有 @-mention 引用" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />95 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code 编辑器中选中了 Python 文件的第 2-3 行，Claude Code 面板显示了关于这些行的问题以及 @ 提及引用" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />

88 </Step>96 </Step>

89 97 

90 <Step title="审查更改">98 <Step title="审查更改">

91 您看到的内容取决于提示框底部显示的[权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)：99 <span id="security-considerations" />

100 

101 <span id="security-and-privacy" />

102 

103 查看输入框底部显示的[权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)：

92 104 

93 * 在自动或自动编辑模式下，Claude 在不询问的情况下编辑工作区中的大多数文件。105 * 在 Auto 或 Edit automatically 模式下，Claude 会直接编辑工作区中的[大多数文件](/docs/zh-CN/permission-modes#protected-paths)，而不会询问。

94 * 在手动模式下，当 Claude 想要编辑文件时，它会显示原始内容和建议更改的并排比较，然后要求权限。您可以接受、拒绝或告诉 Claude 改为做什么。如果您在接受之前直接在差异视图中编辑建议的内容，Claude 会被告知您修改了它，因此它不会假设文件与其原始建议相匹配。106 * 在 Manual 模式下，当 Claude 想要编辑文件时，会并排显示原始内容与建议的更改，然后请求权限。您可以接受、拒绝，或告诉 Claude 改为执行其他操作。如果您在接受之前直接在 diff 视图中编辑了建议的内容，Claude 会被告知您已修改该内容，因此不会假定文件与其原始建议一致。

95 107 

96 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code 显示 Claude 建议更改的差异，以及询问是否进行编辑的权限提示" width="3292" height="1876" data-path="images/vs-code-edits.png" />108 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code 显示 Claude 建议更改的 diff，以及询问是否进行编辑的权限提示" width="3292" height="1876" data-path="images/vs-code-edits.png" />

97 109 

98 要逐个审查建议的编辑，请使用差异中每个更改下的**接受此更改**和**拒绝此更改**按钮。拒绝更改会在建议的内容中还原它；接受会将其标记为已审查。接受或拒绝整个文件仍会完成审查。具有超过 100 个更改的差异会在没有按更改按钮的情况下打开，因此请将其作为整个文件进行审查。按更改审查需要 Claude Code v2.1.275 或更高版本。110 如需逐个审查建议的编辑，请使用 diff 中每处更改下方的 **Accept this change** 和 **Reject this change** 按钮。拒绝某处更改会在建议内容中将其还原；接受则会将其标记为已审查。逐处更改审查需要 Claude Code v2.1.275 或更高版本。

99 111 

100 相同的操作可从编辑器的上下文菜单和命令面板中获得，分别为**Claude Code: Accept Change at Cursor** 和**Claude Code: Reject Change at Cursor**。112 接受或拒绝整个文件仍会结束审查。包含超过 100 处更改的 diff 打开时不会显示逐处更改按钮，因此请将其作为整个文件进行审查。

113 

114 同样的操作也可以在光标位置通过编辑器的上下文菜单使用，或在命令面板中通过 **Claude Code: Accept Change at Cursor** 和 **Claude Code: Reject Change at Cursor** 使用。

101 </Step>115 </Step>

102</Steps>116</Steps>

103 117 

104有关您可以使用 Claude Code 做什么的更多想法，请参阅[常见工作流](/docs/zh-CN/common-workflows)。118有关 Claude Code 更多用法的灵感，请参阅[常见工作流](/docs/zh-CN/common-workflows)。

105 119 

106<Tip>120<Tip>

107 从命令面板运行"Claude Code: Open Walkthrough"以获得基础知识的引导式教程。121 在命令面板中运行"Claude Code: Open Walkthrough"，即可获得基础功能的引导式教程。

108</Tip>122</Tip>

109 123 

110<h2 id="use-the-prompt-box">124<h2 id="use-the-prompt-box">

113 127 

114输入框支持以下几项功能：128输入框支持以下几项功能：

115 129 

116* **权限模式**：点击输入框底部的模式指示器即可切换权限模式。在 Claude Code v2.1.283 或更高版本中，Auto 是内置的初始权限模式；在更早的版本中，仅 Pro、Max 和 Team 套餐如此。请参阅[扩展如何选择初始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)，了解哪些因素会改变这一点，以及指示器提供的所有权限模式。130* **权限模式**：点击输入框底部的模式指示器即可切换权限模式。在 Claude Code v2.1.283 或更高版本中，Auto 是内置的初始权限模式；在更早的版本中，仅 Pro、Max 和 Team 套餐如此。请参阅[扩展如何选择初始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)，了解哪些因素会改变初始模式，以及指示器提供的所有权限模式。

117 * **Auto**：由分类器审查大多数操作，而不是询问您。请参阅[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，了解它会审查和阻止哪些操作。131 * **Auto**：由分类器审查大多数操作，而不是询问您。请参阅[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，了解它会审查和阻止哪些操作。

118 * **Manual**：Claude 在编辑文件和执行大多数 shell 命令之前会请求权限。132 * **Manual**：Claude 在编辑文件和执行大多数 shell 命令之前会请求权限。

119 * **Plan**：Claude 会描述它将要做什么，并在进行更改之前等待批准。VS Code 会自动将计划作为完整的 Markdown 文档打开，您可以在 Claude 开始之前添加行内评论来提供反馈。133 * **Plan**：Claude 会描述它将要执行的操作，并在进行更改前等待批准。VS Code 会自动将计划作为完整的 Markdown 文档打开，您可以在 Claude 开始之前添加行内评论来提供反馈。

120 134 

121 您也可以在输入框中输入 `/plan`。需要 Claude Code v2.1.280 或更高版本。135 您也可以在输入框中输入 `/plan`。需要 Claude Code v2.1.280 或更高版本。

122 136 

123 * `/plan`：切换到计划模式。如果已处于计划模式，则改为显示当前计划。137 * `/plan`：切换到计划模式。如果已处于计划模式，则改为显示当前计划。

124 * 带任务的 `/plan`，例如 `/plan fix the auth bug`：切换到计划模式并开始为该任务制定计划。138 * 带任务的 `/plan`，例如 `/plan fix the auth bug`：切换到计划模式并开始为该任务制定计划。

125 * `/plan open`：已处于计划模式时，在编辑器中打开计划文件。139 * `/plan open`：已处于计划模式时，在编辑器中打开计划文件。

126 * **Edit automatically**：Claude 直接进行编辑，不再询问。140 * **Edit automatically**：Claude 直接进行编辑，不会询问。

127* **模型**：从命令菜单中选择 **Switch model…** 即可在会话中途更换模型。您也可以点击输入框底部的模型名称来打开同一个选择器。在 Claude Code v2.1.284 或更高版本中，在输入框中单独输入 `/model` 也会打开该选择器。141* **模型**：从命令菜单中选择 **Switch model…**，即可在会话中途更换模型。您也可以点击输入框底部的模型名称来打开同一个选择器。在 Claude Code v2.1.284 或更高版本中，在输入框中单独输入 `/model` 也会打开该选择器。

128 142 

129 当当前模型支持 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)时，选择器还会显示 **Effort** 行，模型名称按钮会显示所选级别。当您选择 `max` 以外的级别时，Claude Code 会将其保存为当前模型的默认值，存放在用户设置的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下；`max` 仅适用于当前会话。模型名称按钮和 **Effort** 行需要 Claude Code v2.1.257 或更高版本。143 当前模型支持 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)时，选择器还会显示 **Effort** 行，模型名称按钮也会显示所选级别。当您选择 `max` 以外的级别时，Claude Code 会将其保存为当前模型的默认值，存储在用户设置的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下；`max` 仅适用于当前会话。模型名称按钮和 **Effort** 行需要 Claude Code v2.1.257 或更高版本。

130 144 

131 当启用了[动态工作流](/docs/zh-CN/workflows)且当前模型支持时，**Effort** 行下方会出现 **Ultracode** 开关。打开它后，Claude 会以所选 effort 级别，为此会话中的每项实质性任务规划一个[工作流](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)。开关打开期间，模型名称按钮会在级别后显示 `· Ultracode`。该开关需要 Claude Code v2.1.284 或更高版本。145 启用[动态工作流](/docs/zh-CN/workflows)且当前模型支持时，**Effort** 行下方会出现 **Ultracode** 开关。打开它后，Claude 会以所选 effort 级别，为本会话中的每项实质性任务规划一个[工作流](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)。开关打开期间，模型名称按钮会在级别后显示 `· Ultracode`。该开关需要 Claude Code v2.1.284 或更高版本。

132* **命令菜单**：点击 `/` 或输入 `/` 即可打开命令菜单。选项包括附加文件、切换模型以及开关扩展思考。146* **命令菜单**：点击 `/` 或输入 `/` 即可打开命令菜单。选项包括附加文件、切换模型以及开关扩展思考。

133 147 

134 Customize 部分包含 MCP 服务器、命令、输出样式、hook、记忆、指令、权限和插件等条目。带有终端图标的条目会在集成终端中打开。148 Customize 部分包含 MCP 服务器、命令、输出样式、hook、记忆、指令、权限和插件等条目。带有终端图标的项目会在集成终端中打开。

135 149 

136 * 要浏览 `/usage` 或 [`/remote-control`](/docs/zh-CN/remote-control) 等命令，请在 Customize 部分选择 **Slash commands**。对话框会列出这些命令并提供筛选框。选择其中一个即可运行。在输入框中输入 `/` 仍会以内联方式建议命令。需要 Claude Code v2.1.257 或更高版本。150 * 要浏览 `/usage` 或 [`/remote-control`](/docs/zh-CN/remote-control) 等命令，请在 Customize 部分中选择 **Slash commands**。对话框会列出这些命令并提供筛选框。选择其中一个即可运行。在输入框中输入 `/` 仍会以内联方式提示命令。需要 Claude Code v2.1.257 或更高版本。

137 151 

138 输入 `/skills` 也会打开此对话框。每个 [skill](/docs/zh-CN/skills) 行都会显示其[可见性](/docs/zh-CN/skills#override-skill-visibility-from-settings)，例如 **On** 或 **Name only**。点击可见性即可更改，但标记为 **locked** 的行（例如插件 skill）除外。`/skills` 快捷方式和可见性控件需要 Claude Code v2.1.280 或更高版本。152 输入 `/skills` 也会打开此对话框。每个 [skill](/docs/zh-CN/skills) 行都会显示其[可见性](/docs/zh-CN/skills#override-skill-visibility-from-settings)，例如 **On** 或 **Name only**。点击可见性即可更改，但标记为 **locked** 的行（例如插件 skill）除外。`/skills` 快捷方式和可见性控件需要 Claude Code v2.1.280 或更高版本。

139 * 在 Customize 部分选择 **Output styles** 即可选择[输出样式](/docs/zh-CN/output-styles)，包括您的自定义样式。需要 Claude Code v2.1.257 或更高版本。153 * 在 Customize 部分中选择 **Output styles**，即可选择[输出样式](/docs/zh-CN/output-styles)，包括您的自定义样式。需要 Claude Code v2.1.257 或更高版本。

140 154 

141 若要创建自定义样式，请从 **Output styles** 菜单中选择 **Build a custom style**。Claude Code 会在项目级或用户级为您编写[样式文件](/docs/zh-CN/output-styles#create-a-custom-output-style)。需要 Claude Code v2.1.261 或更高版本。155 如需创建自定义样式，请从 **Output styles** 菜单中选择 **Build a custom style**。Claude Code 会在项目级或用户级为您编写[样式文件](/docs/zh-CN/output-styles#create-a-custom-output-style)。需要 Claude Code v2.1.261 或更高版本。

142 * 在 Customize 部分选择 **Hooks** 即可查看会话中加载的 [hook](/docs/zh-CN/hooks)，按事件分组。您可以添加、编辑或删除保存在用户、项目和本地设置文件中的 hook。来自其他来源（例如托管设置或插件）的 hook 是只读的。需要 Claude Code v2.1.269 或更高版本。156 * 在 Customize 部分中选择 **Hooks**，即可查看会话中已加载的 [hook](/docs/zh-CN/hooks)，按事件分组。您可以添加、编辑或删除保存在用户、项目和本地设置文件中的 hook。来自其他来源（例如托管设置或插件）的 hook 为只读。需要 Claude Code v2.1.269 或更高版本。

143 * 在 Customize 部分选择 **Permissions** 即可查看会话的[权限规则](/docs/zh-CN/permissions)，分为 Allow、Ask 和 Deny 三组。您可以向用户、项目或本地设置添加规则，并删除保存在其中的规则。来自其他来源的规则（例如托管设置或仅对本会话做出的批准）是只读的。需要 Claude Code v2.1.269 或更高版本。157 * 在 Customize 部分中选择 **Permissions**，即可查看会话的[权限规则](/docs/zh-CN/permissions)，按 Allow、Ask 和 Deny 分组。您可以向用户、项目或本地设置添加规则，并删除保存在其中的规则。来自其他来源的规则（例如托管设置或仅针对本会话做出的批准）为只读。需要 Claude Code v2.1.269 或更高版本。

144 * 在 Customize 部分选择 **Memory** 即可打开或关闭[自动记忆](/docs/zh-CN/memory#auto-memory)。打开时，您还可以浏览 Claude 已保存的记忆，并在文件管理器中显示存储这些记忆的文件夹。需要 Claude Code v2.1.274 或更高版本。158 * 在 Customize 部分中选择 **Memory**，即可打开或关闭[自动记忆](/docs/zh-CN/memory#auto-memory)。打开期间，您还可以浏览 Claude 已保存的记忆，并在文件管理器中显示存储这些记忆的文件夹。需要 Claude Code v2.1.274 或更高版本。

145 159 

146 点击已保存的记忆即可在对话框中阅读，您可以在其中编辑文本、删除该记忆，或在编辑器中打开其文件。在对话框中查看、编辑和删除记忆需要 Claude Code v2.1.275 或更高版本。160 点击已保存的记忆即可在对话框中阅读，您可以在其中编辑文本、删除该记忆，或在编辑器中打开其文件。在对话框中查看、编辑和删除记忆需要 Claude Code v2.1.275 或更高版本。

147 * 在 Customize 部分选择 **Instructions** 即可编辑 Claude 读取的 [CLAUDE.md 文件](/docs/zh-CN/memory#claude-md-files)。选择一个文件即可在编辑器中打开。如果该文件尚不存在，Claude Code 会先创建它。需要 Claude Code v2.1.274 或更高版本。161 * 在 Customize 部分中选择 **Instructions**，即可编辑 Claude 读取的 [CLAUDE.md 文件](/docs/zh-CN/memory#claude-md-files)。选择一个文件即可在编辑器中打开。如果文件尚不存在，Claude Code 会先创建它。需要 Claude Code v2.1.274 或更高版本。

148 * 在 Customize 部分选择 **Status**，或输入 `/status`，即可查看会话的 Claude Code 版本、账户、模型和 MCP 服务器详细信息。需要 Claude Code v2.1.280 或更高版本。162 * 在 Customize 部分中选择 **Status**，或输入 `/status`，即可查看会话的 Claude Code 版本、账户、模型和 MCP 服务器详细信息。需要 Claude Code v2.1.280 或更高版本。

149 * 在 Customize 部分选择 **Sandbox**，或输入 `/sandbox`，即可查看 Claude 的 Bash 命令是否在[沙箱中](/docs/zh-CN/sandboxing)运行。您可以在此切换沙箱模式并添加[排除的命令](/docs/zh-CN/settings-reference#sandbox-excludedcommands)。需要 Claude Code v2.1.280 或更高版本。163 * 在 Customize 部分中选择 **Sandbox**，或输入 `/sandbox`，即可查看 Claude 的 Bash 命令是否在[沙箱](/docs/zh-CN/sandboxing)中运行。您可以在此切换沙箱模式并添加[排除的命令](/docs/zh-CN/settings-reference#sandbox-excludedcommands)。需要 Claude Code v2.1.280 或更高版本。

150 * 在 Customize 部分选择 **Claude in Chrome**，或输入 `/chrome`，即可检查和管理 [Claude in Chrome](/docs/zh-CN/chrome) 连接。两者都需要使用 claude.ai 账户登录。需要 Claude Code v2.1.280 或更高版本。164 * 在 Customize 部分中选择 **Claude in Chrome**，或输入 `/chrome`，即可检查和管理 [Claude in Chrome](/docs/zh-CN/chrome) 连接。两者都需要使用 claude.ai 账户登录。需要 Claude Code v2.1.280 或更高版本。

151 * 在 Context 部分选择 **Export conversation**，或输入 `/export`，即可将对话复制为纯文本或保存到文件。添加文件名（例如 `/export notes.txt`）可跳过对话框并选择文件的保存位置。需要 Claude Code v2.1.280 或更高版本。165 * 在 Context 部分中选择 **Export conversation**，或输入 `/export`，即可将对话复制为纯文本或保存到文件。添加文件名（例如 `/export notes.txt`）可跳过对话框并选择文件的保存位置。需要 Claude Code v2.1.280 或更高版本。

152 * Settings 部分包含 **Enable Remote Control for all sessions**，它会设置 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup)，用于控制[新的交互式会话是否自动连接到 Remote Control](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更高版本。166 * Settings 部分包含 **Enable Remote Control for all sessions**，它会设置 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup)，用于控制[新的交互式会话是否自动连接到 Remote Control](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更高版本。

153 167 

154 当您在某个 VS Code 窗口中打开或关闭此开关时，更改会应用于该 VS Code 窗口中已打开的会话，而不仅仅是之后启动的会话。如果关闭它，已打开的会话会断开连接。在 Claude Code v2.1.261 或更高版本中，更改还会同步到您其他 VS Code 窗口中打开的会话。168 在 VS Code 窗口中打开或关闭此开关时，更改不仅限于之后启动的会话，也会应用于该 VS Code 窗口中已打开的会话。如果将其关闭，已打开的会话会断开连接。在 Claude Code v2.1.261 或更高版本中，更改还会作用于您其他 VS Code 窗口中打开的会话。

155 * Settings 部分还包含 **Focus view**，它会将工具调用、工具结果和思考内容隐藏在可展开的行后面，只保留您的提示词和 Claude 的回复。您可以在此处切换，也可以使用 `Ctrl+Option+F`（Mac）/ `Ctrl+Alt+F`（Windows/Linux），或在命令面板中使用 **Claude Code: Toggle Focus view**。更改会应用于所有已打开的会话，并在会话之间保留。需要 Claude Code v2.1.221 或更高版本。169 * Settings 部分还包含 **Focus view**，它会将工具调用、工具结果和思考内容隐藏在可展开的行后面，只保留您的提示词和 Claude 的回复。您可以在此处切换，也可以使用 `Ctrl+Option+F`（Mac）/ `Ctrl+Alt+F`（Windows/Linux），或在命令面板中使用 **Claude Code: Toggle Focus view**。更改会应用于所有已打开的会话，并在会话之间保持。需要 Claude Code v2.1.221 或更高版本。

170 

171 Claude 最新的待办事项列表保持可见，Claude 待回答问题所涉及的文本也保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，显示其最新活动的实时进度行会出现在启动它们的工具调用组下方。这需要 Claude Code v2.1.269 或更高版本。

172 * 要注销您的 Anthropic 账户，请在 Settings 部分中选择 **Sign out**，或输入 `/logout`。使用[第三方提供商](#use-third-party-providers)时，菜单不提供这两种方式。需要 Claude Code v2.1.277 或更高版本。

173 * 要报告错误，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback`，可附带一段描述来预填报告。当您提交报告，且通过第一方连接登录到 Anthropic 时，Claude Code 会将其发送给 Anthropic。需要 Claude Code v2.1.229 或更高版本。

156 174 

157 Claude 最新的待办事项列表会保持可见，Claude 待回答问题所针对的文本也会保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，显示其最新活动的实时进度行会出现在启动它们的工具调用组下方。这需要 Claude Code v2.1.269 或更高版本。175 使用第三方提供商或没有 Anthropic 凭据时，不会发送任何内容。对话框会在您撰写之前说明这一点。提交时会将报告保存为[位于 `~/.claude/feedback-bundles/` 下的本地归档文件](/docs/zh-CN/data-usage#telemetry-services)，其中已知的 API 密钥和令牌模式会被遮盖。将报告保存到您的计算机需要 Claude Code v2.1.284 或更高版本。

158 * 要退出您的 Anthropic 账户，请在 Settings 部分选择 **Sign out**，或输入 `/logout`。使用[第三方提供商](#use-third-party-providers)时，菜单不提供这两种方式。需要 Claude Code v2.1.277 或更高版本。

159 * 要报告 bug，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback`，并可附带一段描述来预填报告。当您提交报告且通过第一方连接登录了 Anthropic 时，Claude Code 会将报告发送给 Anthropic。需要 Claude Code v2.1.229 或更高版本。

160 176 

161 使用第三方提供商或没有 Anthropic 凭据时，不会发送任何内容。对话框会在您填写之前说明这一点。提交后，报告会保存为[位于 `~/.claude/feedback-bundles/` 下的本地归档](/docs/zh-CN/data-usage#telemetry-services)，其中已知的 API 密钥和令牌模式会被遮盖。请将该文件发送给您的 Anthropic 客户代表，或将其附加到支持请求中。确认信息会显示文件名，并包含 **Show folder** 按钮。在您的计算机上保存报告需要 Claude Code v2.1.284 或更高版本。177 报告保存后，确认信息会显示文件名，并包含 **Show folder** 按钮。请将该文件发送给您的 Anthropic 客户代表，或将其附加到支持请求中。

162 178 

163 如果您组织的策略关闭了产品反馈，菜单中不会出现 **Report a problem**，并且 `/bug` 和 `/feedback` 会显示 `Feedback is turned off by your organization's policy or this environment's settings.` 提示，而不是打开报告。在 Claude Code v2.1.284 或更高版本中，如果您设置了 `DISABLE_FEEDBACK_COMMAND` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 环境变量，反馈也会被关闭，打开报告时会改为显示该提示。179 如果您组织的策略关闭了产品反馈，**Report a problem** 不会出现在菜单中，`/bug` 和 `/feedback` 会显示 `Feedback is turned off by your organization's policy or this environment's settings.` 通知，而不是打开报告。在 Claude Code v2.1.284 或更高版本中，如果您设置了 `DISABLE_FEEDBACK_COMMAND` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 环境变量，反馈同样会被关闭，打开报告时会改为显示该通知。

164* **旁支问题**：输入 `/btw` 后跟一个问题，即可就会话提问，且[不会添加到对话中](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。回答会在聊天旁边的面板中打开，您可以在其中继续追问。该线程在窗口重新加载后仍会保留。Claude Code 会保留最新的 20 次交流，并按照 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 的计划使已存储的线程过期，前提是 Claude Code 能够[安全地确定保留期限](/docs/zh-CN/claude-directory#cleaned-up-automatically)。要清除线程，请点击面板中的垃圾桶图标。需要 Claude Code v2.1.227 或更高版本。180* **旁支问题**：输入 `/btw` 后跟一个问题，即可就您的会话提问，而[不会添加到对话中](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。回答会在聊天旁边的面板中打开，您可以在其中继续追问。需要 Claude Code v2.1.227 或更高版本。

165* **复制回复**：将鼠标悬停在某条回复上并点击 **Copy response** 即可将其复制到剪贴板，或输入 `/copy` 复制最新的回复。`/copy 2` 会复制倒数第二条。需要 Claude Code v2.1.277 或更高版本。

166* **书签**：将鼠标悬停在某条回复上并点击 **Bookmark response** 即可保存它，或在已保存的回复上点击 **Remove bookmark** 将其移除。

167 181 

168 要查看已保存的回复，请打开 Bookmarks 面板：点击 Claude Code 面板顶部的书签图标，在命令菜单的 Context 部分中选择 **Bookmarks**，或输入 `/bookmarks`。需要 Claude Code v2.1.286 或更高版本。182 该线程在窗口重新加载后依然保留。Claude Code 会保留最新的 20 轮问答，并按照 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 计划使已存储的线程过期，前提是 Claude Code 能够[安全地确定保留期限](/docs/zh-CN/claude-directory#cleaned-up-automatically)。要清除线程，请点击面板中的垃圾桶图标。

169* **Claude 发送给您的文件**：当会话连接到 [Remote Control](/docs/zh-CN/remote-control#start-a-remote-control-session) 且 Claude 使用 [`SendUserFile` 工具](/docs/zh-CN/tools-reference)向您发送文件时，对话中会显示一行，例如 **Sent report.md, chart.png**。点击文件名即可在编辑器中打开该文件。183* **复制回复**：将鼠标悬停在回复上并点击 **Copy response** 即可将其复制到剪贴板，或输入 `/copy` 复制最新的回复。`/copy 2` 复制倒数第二条回复。需要 Claude Code v2.1.277 或更高版本。

170* **上下文指示器**：输入框会显示您已使用了 Claude 上下文窗口的多少。Claude 会在需要时自动压缩，您也可以手动运行 `/compact`。184* **书签**：将鼠标悬停在回复上并点击 **Bookmark response** 即可保存该回复，或在已保存的回复上点击 **Remove bookmark** 将其移除。

171* **提示缓存时钟**：上下文指示器旁边的时钟图标会估算对话的[提示缓存](/docs/zh-CN/prompt-caching)在过期前还剩多少时间。它会从缓存的五分钟或一小时[生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)开始倒计时，每次使用缓存的响应都会重新开始倒计时。除压缩外，[使缓存失效的操作](/docs/zh-CN/prompt-caching#actions-that-invalidate-the-cache)不会重置时钟，因此在您切换模型后它仍可能显示剩余分钟数。185 

186 要查看已保存的回复，请打开 Bookmarks 面板。您可以点击 Claude Code 面板顶部的书签图标，在命令菜单的 Context 部分中选择 **Bookmarks**，或输入 `/bookmarks`。需要 Claude Code v2.1.286 或更高版本。

187* **Claude 发送给您的文件**：当会话连接到 [Remote Control](/docs/zh-CN/remote-control#start-a-remote-control-session)，且 Claude 使用 [`SendUserFile` 工具](/docs/zh-CN/tools-reference)向您发送文件时，对话中会显示一行，例如 **Sent report.md, chart.png**。点击文件名即可在编辑器中打开。

188* **上下文指示器**：输入框会显示您已使用了多少 Claude 上下文窗口。Claude 会在需要时自动压缩，您也可以手动运行 `/compact`。

189* **提示缓存时钟**：上下文指示器旁边的时钟图标会估算对话的[提示缓存](/docs/zh-CN/prompt-caching)在过期前还剩多少时间。它从缓存的五分钟或一小时[生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)开始倒计时，每次使用缓存的回复都会重新开始倒计时。除压缩外，[使缓存失效的操作](/docs/zh-CN/prompt-caching#actions-that-invalidate-the-cache)不会重置时钟，因此在您切换模型后它仍可能显示剩余的分钟数。

172 * 在倒计时结束之前，图标会显示剩余分钟数，例如 **12m**。190 * 在倒计时结束之前，图标会显示剩余分钟数，例如 **12m**。

173 * 倒计时结束时，分钟数会消失，图标会变为红色（或您主题的错误颜色），直到下一次响应。此时缓存很可能已经过期，因此在缓存重建期间，您下一条消息的响应会更慢、更昂贵。如果五分钟的生命周期总是在您发送消息的间隔中耗尽，请参阅[自行选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。191 * 倒计时结束后，分钟数会消失，图标变为红色（或您主题的错误颜色），直到下一条回复。此时缓存很可能已经过期，因此在缓存重建期间，您下一条消息得到的回复会更慢、成本更高。如果五分钟的生命周期总是在您发送消息之间耗尽，请参阅[自行选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。

174 * 在对话刚刚[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)之后，图标也会变为红色且不显示分钟数，直到下一次响应，因为缓存尚未覆盖压缩后的对话。192 * 对话刚被[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)后，图标同样会变为红色且不显示分钟数，直到下一条回复，因为缓存尚未覆盖压缩后的对话。

175* **Agent 地图**：当对话包含[子代理](/docs/zh-CN/sub-agents)时，输入框底部会出现 Agent 计数，例如 **2 agents**。其圆点显示是否有子代理正在工作或正在等待您授予权限。193* **Agent 地图**：当对话包含[子代理](/docs/zh-CN/sub-agents)时，输入框底部会出现 Agent 计数，例如 **2 agents**。其圆点表示是否有子代理正在工作或正在等待您授予权限。

176 194 

177 点击 Agent 计数即可打开 Agent 地图，它会将对话的子代理以树状形式绘制在主 Agent 之下，每个子代理都显示其状态、已用时间和 token 数。点击某个子代理即可查看其提示词和工具调用、打开其只读会话记录，或在其运行时停止它。需要 Claude Code v2.1.269 或更高版本。195 点击 Agent 计数即可打开 Agent 地图，它以树状结构在主 Agent 下绘制对话中的子代理，每个子代理都附带其状态、已用时间和 token 数。点击某个子代理即可查看其提示词和工具调用、打开其只读会话记录，或在其运行时将其停止。需要 Claude Code v2.1.269 或更高版本。

178 196 

179 地图还会在 Agent 下方列出会话的其他[后台任务](/docs/zh-CN/tools-reference#background-commands)，例如后台 shell 命令和[监视器](/docs/zh-CN/tools-reference#monitor-tool)。点击某一行即可打开该任务的卡片并在其中停止它。197 地图还会在 Agent 下方列出会话的其他[后台任务](/docs/zh-CN/tools-reference#background-commands)，例如后台 shell 命令和[监视器](/docs/zh-CN/tools-reference#monitor-tool)。点击某一行即可打开该任务的卡片，并在其中将其停止。

180 198 

181 当没有显示 Agent 计数时（例如 Claude 启动了后台 shell 但没有子代理），要打开地图，请在输入框中输入 `/tasks`。地图中的后台任务以及输入 `/tasks` 需要 Claude Code v2.1.277 或更高版本。199 如果没有显示 Agent 计数（例如 Claude 启动了后台 shell 但没有子代理），要打开地图，请在输入框中输入 `/tasks`。地图中的后台任务和输入的 `/tasks` 需要 Claude Code v2.1.277 或更高版本。

182 200 

183 在 Claude Code v2.1.286 或更高版本中，当您点击 **Stop** 或按 `Esc` 时，当前轮次会结束。后台 Agent 会继续运行，直到完成或您从地图中将其停止。201 在 Claude Code v2.1.286 或更高版本中，当您点击 **Stop** 或按 `Esc` 时，当前轮次会结束。后台 Agent 会继续运行，直到完成或您从地图中将其停止。

184* **扩展思考**：让 Claude 花更多时间推理复杂问题。通过命令菜单（`/`）将其打开。Claude 的推理会以折叠块的形式出现在对话中：点击某个块即可阅读，或按 `Ctrl+O` 展开或折叠会话中的所有思考块。详情请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)。202* **扩展思考**：让 Claude 花更多时间推理复杂问题。通过命令菜单（`/`）将其打开。Claude 的推理过程会以折叠块的形式出现在对话中：点击某个块即可阅读，或按 `Ctrl+O` 展开或折叠会话中的所有思考块。详情请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)。

185* **多行输入**：按 `Shift+Enter` 可添加新行而不发送。这同样适用于问题对话框中的“Other”自由文本输入。203* **多行输入**：按 `Shift+Enter` 可添加新行而不发送。这在问题对话框的"Other"自由文本输入中同样适用。

186 204 

187<h3 id="reference-files-and-folders">205<h3 id="reference-files-and-folders">

188 引用文件和文件夹206 引用文件和文件夹

189</h3>207</h3>

190 208 

191使用 @ 提及为 Claude 提供有关特定文件或文件夹的上下文。当您输入 `@` 后跟文件或文件夹名称时，Claude 会读取该内容，并可以回答有关它的问题或对其进行更改。Claude Code 支持模糊匹配，因此您可以输入部分名称来找到所需内容：209使用 @ 提及为 Claude 提供有关特定文件或文件夹的上下文。当您输入 `@` 后跟文件或文件夹名称时，Claude 会读取该内容，并可以回答相关问题或对其进行更改。Claude Code 支持模糊匹配，因此您可以输入部分名称来查找所需内容：

192 210 

193```text wrap theme={null}211```text wrap theme={null}

194Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)212Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)

195What's in @src/components/ (include a trailing slash for folders)213What's in @src/components/ (include a trailing slash for folders)

196```214```

197 215 

198对于大型 PDF，您可以让 Claude 读取特定页面而不是整个文件：单个页面、像第 1-10 页这样的范围，或像第 3 页及之后这样的开放范围。读取特定页面需要在运行 Claude Code 的机器上安装 [poppler-utils](/docs/zh-CN/tools-reference#read-tool-behavior)。216对于大型 PDF，您可以让 Claude 读取特定页面而不是整个文件。可以请求单个页面、诸如第 1-10 页的范围，或诸如第 3 页起的开放范围。读取特定页面需要在运行 Claude Code 的计算机上安装 [poppler-utils](/docs/zh-CN/tools-reference#read-tool-behavior)。

217 

218当您在编辑器中选择文本时，Claude 会自动看到您高亮显示的代码。输入框底部会显示已选择的行数。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）可插入包含文件路径和行号的 @ 提及，例如 `@app.ts#5-10`。点击选择指示器上的 **X** 可将其移除，这样 Claude 就不会收到所选内容。当您选择其他文本时，指示器会重新出现。

219 

220扩展不会发送某些文件中的所选文本：

199 221 

200当您在编辑器中选择文本时，Claude 可以自动看到您高亮的代码。输入框底部会显示选中了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）可插入带有文件路径和行号的 @ 提及（例如 `@app.ts#5-10`）。点击选区指示器上的 **X** 可将其移除，这样 Claude 就不会收到该选区。当您选择其他文本时，指示器会重新出现。222* 当文件位于您的工作区内且匹配您的 `files.exclude` 或 `search.exclude` 设置时，Claude 最多只会收到文件路径，而不会收到您所选的文本。

223* 这同样适用于被 git 忽略的文件，前提是 VS Code 的 `search.useIgnoreFiles` 设置和扩展的 [`respectGitIgnore` 设置](#extension-settings)都已打开（默认如此）。

201 224 

202扩展会对某些文件隐瞒所选文本。当文件位于您的工作区内且匹配您的 `files.exclude` 或 `search.exclude` 设置时，Claude 最多只会收到该文件的路径，而不会收到您选择的文本。对于 git 忽略的文件也是如此，前提是 VS Code 的 `search.useIgnoreFiles` 设置和扩展的 [`respectGitIgnore` 设置](#extension-settings)都已打开（默认即为打开）。此过滤仅适用于聊天面板：当 Claude Code 在集成终端中运行时，无论是什么文件，CLI 都会发送您选择的文本，因此若要在那里阻止 Claude 获取某个文件的内容，请添加 [`Read` 拒绝规则](#the-built-in-ide-mcp-server)。225此筛选仅适用于聊天面板。当 Claude Code 在集成终端中运行时，无论是什么文件，CLI 都会发送您所选的文本。要在终端中阻止 Claude 获取文件内容，请添加 [`Read` 拒绝规则](#the-built-in-ide-mcp-server)。

203 226 

204即使没有选择任何内容，Claude 也能看到您在编辑器中打开的是哪个文件，输入框会显示其名称。若只想添加您选择的文本，请关闭 [Attach Open File 设置](vscode://settings/claudeCode.attachOpenFile)。该设置需要 Claude Code v2.1.271 或更高版本。227即使没有选择任何内容，Claude 也能看到您在编辑器中打开的是哪个文件，输入框会显示其名称。如果只想添加您所选的文本，请关闭 [Attach Open File 设置](vscode://settings/claudeCode.attachOpenFile)。该设置需要 Claude Code v2.1.271 或更高版本。

205 228 

206您还可以在消息中附加图片和文件：229您还可以将图片和文件附加到消息中：

207 230 

208* 要附加图片，请将其从剪贴板粘贴到输入框中。231* 要附加图片，请将其从剪贴板粘贴到输入框中。

209* 要附加文件，请按住 `Shift` 将其拖入输入框。232* 要附加文件，请按住 `Shift` 将其拖入输入框。

210* 要从上下文中移除附件，请点击其上的 X。233* 要从上下文中移除附件，请点击附件上的 X。

234 

235<h3 id="include-terminal-output-in-prompts">

236 在提示词中包含终端输出

237</h3>

238 

239在提示词中使用 `@terminal:name` 引用终端输出，其中 `name` 是终端的标题。这样 Claude 无需复制粘贴即可看到命令输出、错误消息或日志。

211 240 

212<h3 id="paste-text">241<h3 id="paste-text">

213 粘贴文本242 粘贴文本

214</h3>243</h3>

215 244 

216您粘贴的文本会在输入框中保持可见，而不会像[在终端中](/docs/zh-CN/terminal-config#paste-large-content)那样折叠为占位符。在 Claude Code [标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)的会话中，Claude 仍会将大段粘贴内容视为您粘贴的文本，而不是您输入的文本。245您粘贴的文本会在输入框中保持可见，而不会像[在终端中](/docs/zh-CN/terminal-config#paste-large-content)那样折叠为占位符。在 Claude Code [标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)的会话中，Claude 仍会将大段粘贴内容视为您粘贴而非输入的文本。

217 246 

218Claude Code 还会从您粘贴到输入框中的文本以及您发送的任何其他内容中移除[不可见的 Unicode 字符](/docs/zh-CN/interactive-mode#invisible-characters-in-prompts)：247Claude Code 还会从您粘贴到输入框中的文本以及您发送的任何其他内容中移除[不可见 Unicode 字符](/docs/zh-CN/interactive-mode#invisible-characters-in-prompts)：

219 248 

220* 如果粘贴时出现 `Removed 3 invisible characters from the pasted text` 之类的提示，说明文本已在去除这些字符后输入。249* 如果粘贴时出现 `Removed 3 invisible characters from the pasted text` 之类的通知，则表示文本已去除这些字符后放入输入框。

221* 如果发送时出现有关已移除字符的提示，说明没有发送任何内容。清理后的文本已回到输入框中。再次发送即可按所示内容发送文本。250* 如果发送时出现有关已移除字符的通知，则表示没有发送任何内容。清理后的文本会回到输入框中。再次发送即可按显示的内容发送文本。

222 251 

223<h3 id="latex-math-in-responses">252<h3 id="latex-math-in-responses">

224 回复中的 LaTeX 数学公式253 回复中的 LaTeX 数学公式

225</h3>254</h3>

226 255 

227聊天面板会将 Claude 回复中的 LaTeX 数学公式显示为排版后的公式。数学公式渲染需要 Claude Code v2.1.301 或更高版本。在[终端模式](#switch-to-terminal-mode)下，数学公式不会被排版。面板会同时排版行间公式和行内公式：256聊天面板会将 Claude 回复中的 LaTeX 数学公式显示为排版后的公式。数学公式渲染需要 Claude Code v2.1.301 或更高版本。在[终端模式](#switch-to-terminal-mode)下，数学公式不会被排版。面板会同时排版独立公式和行内公式：

228 257 

229* **行间公式**：单独占据一行或多行的 `$$ … $$` 或 `\[ … \]` 块，以及语言为 `math` 的围栏代码块258* **独立公式**：独占一行或多行的 `$$ … $$` 或 `\[ … \]` 块，以及语言为 `math` 的围栏代码块

230* **行内公式**：在同一行内开始和结束的 `$…$` 或 `\(…\)`，例如 `$E = mc^2$` 或 `\(a^2 + b^2 = c^2\)`259* **行内公式**：在同一行内开始和结束的 `$…$` 或 `\(…\)`，例如 `$E = mc^2$` 或 `\(a^2 + b^2 = c^2\)`

231 260 

232面板会尝试将数学公式与相同字符的其他用法区分开来，因此 `$HOME`、像 `$5` 这样的价格或 `sed 's/\(foo\)/\1/'` 之类的文本不会被排版。代码片段内的文本，以及除围栏 `math` 块之外的任何代码块内的文本，也都不会被排版。如果某个公式在您期望被排版时仍按原样显示，请参阅[公式显示为原始 LaTeX](#a-formula-shows-as-raw-latex)。261面板会尝试区分数学公式与相同字符的其他用法，因此 `$HOME`、`$5` 之类的价格或 `sed 's/\(foo\)/\1/'` 等文本不会被排版。代码片段内的文本，以及除 `math` 围栏代码块以外的任何代码块中的文本，也不会被排版。如果某个公式本应被排版却按原样显示，请参阅[公式显示为原始 LaTeX](#a-formula-shows-as-raw-latex)。

233 262 

234当您选择并复制包含已排版公式的文本时，得到的是以 `$…$` 或 `$$…$$` 分隔符包裹的公式 TeX 源码，而不是绘制出的符号。[**Copy response**](#use-the-prompt-box) 和 `/copy` 会按 Claude 编写的原样提供回复，包括 TeX 源码。263当您选择并复制包含已排版公式的文本时，得到的是以 `$…$` 或 `$$…$$` 分隔符包裹的公式 TeX 源码，而不是绘制出的符号。[**Copy response**](#use-the-prompt-box) 和 `/copy` 会按 Claude 所写的原样提供回复，包括 TeX 源码。

235 264 

236<h3 id="resume-past-conversations">265<h3 id="resume-past-conversations">

237 恢复过去的对话266 恢复过去的对话

238</h3>267</h3>

239 268 

240点击 Claude Code 面板顶部的 **Session history** 按钮即可访问您的对话历史。您可以按关键字搜索或按时间浏览。269点击 Claude Code 面板顶部的 **Session history** 按钮即可访问您的对话历史记录。您可以按关键字搜索或按时间浏览。

241 270 

242点击任意对话即可带着完整的消息历史恢复它。如果该对话已在当前窗口的另一个标签页中打开，点击它会切换到该标签页。如果消息一开始显示为空白，请参阅[为什么消息为空白以及何时出现](#a-resumed-conversation-is-blank-at-first)。有关恢复会话的更多信息，请参阅[管理会话](/docs/zh-CN/sessions)。271点击任意对话即可连同完整的消息历史记录一起恢复。如果该对话已在当前窗口的另一个标签页中打开，点击它会切换到该标签页。如果消息一开始显示为空白，请参阅[为什么显示为空白以及何时出现](#a-resumed-conversation-is-blank-at-first)。有关恢复会话的更多信息，请参阅[管理会话](/docs/zh-CN/sessions)。

243 272 

244* **会话标题**：新会话会根据您的第一条消息获得 AI 生成的标题。273* **会话标题**：新会话会根据您的第一条消息获得 AI 生成的标题。

245* **重命名和归档**：将鼠标悬停在会话上即可显示这些操作。重命名可为其设置描述性标题，归档则会将其移到列表底部的 **Archived sessions** 组中。274* **重命名和归档**：将鼠标悬停在会话上即可显示这些操作。重命名可为其设置描述性标题，归档则会将其移至列表底部的 **Archived sessions** 组。

275 

276如果该对话在另一个 Claude Code 进程中打开（例如终端中的 `claude` 或另一个 VS Code 窗口），输入框的位置会显示以下通知：

277 

278```text theme={null}

279This conversation is still open somewhere else. Using it in two places at once can mix up its messages.

280```

281 

282要在此处继续，请先在另一处关闭该对话，然后点击 **Open here anyway**。如果未关闭就点击，该对话会在两处同时打开。设置了 [`claudeProcessWrapper`](#extension-settings) 时，扩展会跳过此检查并直接打开对话。

283 

284默认情况下，14 天内没有活动的会话会自动移至 **Archived sessions**，除非它处于打开状态、未读或位于某个[分组](#organize-sessions-into-groups)中。自动归档需要 Claude Code v2.1.265 或更高版本。要更改期限或将其关闭，请打开 [Archive Inactive Sessions 设置](vscode://settings/claudeCode.archiveInactiveSessions)，并选择天数或 **Never**。

246 285 

247如果该对话在另一个 Claude Code 进程中打开（例如终端中的 `claude` 或另一个 VS Code 窗口），输入框的位置会显示一条提示：`This conversation is still open somewhere else. Using it in two places at once can mix up its messages.` 若要在此处继续，请先在另一处关闭该对话，然后点击 **Open here anyway**。如果不关闭就点击，该对话会在两处同时打开。设置了 [`claudeProcessWrapper`](#extension-settings) 时，扩展会跳过此检查并直接打开对话。286要恢复已归档的会话：

248 287 

249默认情况下，14 天内没有活动的会话会自动移到 **Archived sessions**，除非它处于打开状态、未读或位于某个[组](#organize-sessions-into-groups)中。自动归档需要 Claude Code v2.1.265 或更高版本。要更改期限或将其关闭，请打开 [Archive Inactive Sessions 设置](vscode://settings/claudeCode.archiveInactiveSessions)，然后选择天数或 **Never**。288* **单个会话**：展开 **Archived sessions** 并点击 **Unarchive session**。

289* **一次性恢复所有已归档会话**：将鼠标悬停在活动栏会话列表中的 **Archived sessions** 标题上，然后点击其取消归档图标。需要 Claude Code v2.1.277 或更高版本。

250 290 

251要恢复已归档的会话，请展开 **Archived sessions** 并点击 **Unarchive session**。要一次性恢复所有已归档的会话，请将鼠标悬停在活动栏会话列表中的 **Archived sessions** 标题上，然后点击其取消归档图标，这需要 Claude Code v2.1.277 或更高版本。在 v2.1.257 之前，该操作是 **Delete session**，它会隐藏会话且无法恢复。升级后，您当时删除的会话会出现在 **Archived sessions** 下。291在 v2.1.257 之前，该操作是 **Delete session**，它会隐藏会话且无法恢复。升级后，您当时删除的会话会出现在 **Archived sessions** 下。

252 292 

253当您恢复的对话以计划模式结束时，Claude Code 会恢复计划模式。需要 Claude Code v2.1.246 或更高版本。在以下情况下，Claude Code 不会恢复计划模式：293当您恢复的对话以计划模式结束时，Claude Code 会恢复计划模式。需要 Claude Code v2.1.246 或更高版本。在以下情况下，Claude Code 不会恢复计划模式：

254 294 

255* 扩展根据 `claudeCode.initialPermissionMode` 或从先前对话沿用的选择来[选择初始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)295* 扩展根据 `claudeCode.initialPermissionMode` 或从之前对话沿用的选择来[选择初始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)

256* 您配置了 `claudeCode.claudeProcessWrapper`296* 您配置了 `claudeCode.claudeProcessWrapper`

257* 某条[拒绝规则](/docs/zh-CN/permissions#manage-permissions)移除了 [`ExitPlanMode`](/docs/zh-CN/tools-reference) 工具297* 某条[拒绝规则](/docs/zh-CN/permissions#manage-permissions)移除了 [`ExitPlanMode`](/docs/zh-CN/tools-reference) 工具

258 298 

259<h3 id="resume-cloud-sessions-from-claude-ai">299<h3 id="resume-cloud-sessions-from-claude-ai">

260 从 Claude.ai 恢复云端会话300 从 claude.ai 恢复云端会话

261</h3>301</h3>

262 302 

263如果您运行[云端会话](/docs/zh-CN/claude-code-on-the-web)，可以直接在 VS Code 中恢复它们。这需要使用 **Claude.ai Subscription** 登录，而不是 Anthropic Console。303如果您运行[云端会话](/docs/zh-CN/claude-code-on-the-web)，可以直接在 VS Code 中恢复它们。这需要使用 **Claude.ai Subscription** 登录，而不是 Anthropic Console。

264 304 

265<Steps>305<Steps>

266 <Step title="打开会话历史">306 <Step title="打开会话历史记录">

267 点击 Claude Code 面板顶部的 **Session history** 按钮。307 点击 Claude Code 面板顶部的 **Session history** 按钮。

268 </Step>308 </Step>

269 309 

270 <Step title="选择 Web 标签页">310 <Step title="选择 Web 标签页">

271 对话框显示两个标签页：Local 和 Web。点击 **Web** 即可查看来自 claude.ai 的会话。311 对话框会显示两个标签页：Local 和 Web。点击 **Web** 即可查看来自 claude.ai 的会话。

272 </Step>312 </Step>

273 313 

274 <Step title="选择要恢复的会话">314 <Step title="选择要恢复的会话">

279<Note>319<Note>

280 当您打开的文件夹是 GitHub 仓库时，Web 标签页仅显示来自该仓库的会话。320 当您打开的文件夹是 GitHub 仓库时，Web 标签页仅显示来自该仓库的会话。

281 321 

282 当您恢复云端会话时，扩展会下载对话历史的副本；更改不会同步回 claude.ai。322 当您恢复云端会话时，扩展会下载对话历史记录的副本；所做的更改不会同步回 claude.ai。

283</Note>323</Note>

284 324 

285Web 标签页还会列出您的 [Remote Control](/docs/zh-CN/remote-control) 会话。如果您点击的会话曾在您当前打开的文件夹中运行，扩展会打开该本地对话而不是下载副本，并且如果已有标签页正在显示它，则会聚焦到该标签页。如果扩展无法排除另一个 Claude 进程已打开该对话的可能性，您将获得一份下载的副本。325Web 标签页还会列出您的 [Remote Control](/docs/zh-CN/remote-control) 会话。如果您点击的会话是在您当前打开的文件夹中运行的，扩展会直接打开该本地对话，而不是下载副本。如果已有标签页显示该对话，扩展会聚焦到该标签页。如果扩展无法排除另一个 Claude 进程正打开该对话的可能性，您将得到一份下载的副本。

286 326 

287如果对话的任何部分下载失败，会出现错误且不会保存副本。再次选择该会话即可重试。如果您选择的会话尚无可下载的对话，错误信息会告诉您应在何处继续该会话。327如果对话的任何部分下载失败，会显示错误且不会保存副本。再次选择该会话即可重试。如果您选择的会话尚无可下载的对话，错误信息会告诉您应改为在何处继续该会话。

288 328 

289<h3 id="check-account-and-usage">329<h3 id="check-account-and-usage">

290 查看账户和用量330 查看账户和用量

291</h3>331</h3>

292 332 

293运行 `/usage` 即可打开 Account & usage 对话框。它会显示您已登录的账户，所报告的用量因登录方式而异：333运行 `/usage` 可打开 Account & usage 对话框，其中显示您已登录的账户和用量。用量数据与您的登录方式相对应：

294 334 

295* **claude.ai 套餐**：显示您套餐各项限额的用量条，例如当前会话和本周。每个用量条都会显示距离该限额重置还有多长时间。335* **claude.ai 套餐**：显示套餐各项限额的用量条，例如当前会话和本周。每个用量条都会显示距离其限额重置还有多长时间。

296 336 

297 对话框还会细分哪些因素在消耗您的套餐限额。它会标出占近期用量 10% 或以上的行为，例如缓存未命中、长上下文以及大量使用子代理或高度并行的会话，并为每项提供降低用量的建议。归因表会显示每个 skill、子代理、插件和 MCP 服务器各自产生了多少用量。337 对话框还会细分哪些因素在消耗您的套餐限额。它会标出占近期用量 10% 或以上的行为，例如缓存未命中、长上下文，以及大量使用子代理或高度并行的会话。每个被标出的行为都附有减少用量的建议。归因表显示每个 skill、子代理、插件和 MCP 服务器分别产生了多少用量。

298 338 

299 使用 Day 和 Week 切换按钮可在过去 24 小时和过去 7 天之间切换。这些数据是根据本机上的本地会话计算得出的近似值，因此不包括来自其他设备或 claude.ai 的用量。339 使用 Day 和 Week 切换可在过去 24 小时和过去 7 天之间切换。这些数据是近似值，根据本机上的本地会话计算得出，因此不包括来自其他设备或 claude.ai 的用量。

300* **其他登录方式**：当套餐限额不适用于您的登录方式时（例如使用[第三方提供商](#use-third-party-providers)或 API 密钥），Usage 部分会改为显示会话自身的费用和 token 用量。CLI 的 `/usage` 会在其 [Session 区块](/docs/zh-CN/costs#track-your-costs)中显示相同的总计。活动栏中的会话列表也会在其 **Account & usage** 标题下显示活动会话的总计。需要 Claude Code v2.1.277 或更高版本。340* **其他登录方式**：当套餐限额不适用于您的登录方式时（例如使用[第三方提供商](#use-third-party-providers)或 API 密钥），Usage 部分会改为显示该会话自身的费用和 token 用量。CLI 的 `/usage` 会在其 [Session 区块](/docs/zh-CN/costs#track-your-costs)中显示相同的总计。活动栏中的会话列表也会在其 **Account & usage** 标题下显示当前会话的总计。需要 Claude Code v2.1.277 或更高版本。

301 341 

302有关跟踪和降低用量的更多信息，请参阅[跟踪您的费用](/docs/zh-CN/costs#track-your-costs)。342有关跟踪和减少用量的更多信息，请参阅[跟踪您的费用](/docs/zh-CN/costs#track-your-costs)。

343 

344<h3 id="rewind-with-checkpoints">

345 使用检查点回退

346</h3>

347 

348VS Code 扩展支持检查点，它会跟踪 Claude 的文件编辑，并允许您回退到之前的状态。将鼠标悬停在任意消息上即可显示回退按钮，然后从以下三个选项中选择：

349 

350* **Fork conversation from here**：从此消息开始一个新的对话分支，同时保留所有代码更改

351* **Rewind code to here**：将文件更改还原到对话中的此时间点，同时保留完整的对话历史记录

352* **Fork conversation and rewind code**：开始一个新的对话分支，并将文件更改还原到此时间点

353 

354有关检查点工作原理及其限制的完整详情，请参阅[检查点功能](/docs/zh-CN/checkpointing)。

303 355 

304<h2 id="customize-your-workflow">356<h2 id="customize-your-workflow">

305 自定义您的工作流357 自定义您的工作流

306</h2>358</h2>

307 359 

308您可以重新定位 Claude 面板、运行多个对话、将会话列表组织成组或筛选会话列表，或切换到终端模式。360您可以调整 Claude 面板的位置、运行多个对话、对会话列表进行分组或筛选，或切换到终端模式。

309 361 

310<h3 id="choose-where-claude-lives">362<h3 id="choose-where-claude-lives">

311 选择 Claude 的位置363 选择 Claude 的位置

312</h3>364</h3>

313 365 

314您可以拖动 Claude 面板在 VS Code 中重新定位它。抓住面板的选项卡或标题栏并将其拖动到：366您可以拖动 Claude 面板，将其放置在 VS Code 中的任意位置。抓住面板的标签页或标题栏并将其拖动到：

315 367 

316* **次级侧边栏**：窗口的右侧。在您编码时保持 Claude 可见。368* **辅助侧边栏**：窗口右侧。编码时 Claude 始终可见。

317* **主侧边栏**：左侧边栏，带有 Explorer、Search 等图标。369* **主侧边栏**：左侧带有资源管理器、搜索等图标的侧边栏。

318* **编辑器区域**：将 Claude 作为选项卡打开，与您的文件并排显示。适用于辅助任务。370* **编辑器区域**：将 Claude 作为标签页与您的文件并排打开。适用于辅助任务。

319 371 

320当 Claude 在新编辑器组中打开选项卡时，该扩展会锁定该组，因此当 Claude 选项卡处于焦点时打开的文件会转到另一个组，而不是在其旁边。372当 Claude 在新的编辑器组中打开标签页时，扩展会锁定该组。之后在 Claude 标签页获得焦点时打开的文件会进入另一个组，而不会在其旁边打开。

321 373 

322要停止扩展锁定组，请关闭 [Lock Editor Groups setting](vscode://settings/claudeCode.lockEditorGroups)。已锁定的组将保持锁定状态，直到您解锁它们。该设置需要 Claude Code v2.1.274 或更高版本。374若要阻止扩展锁定编辑器组，请关闭 [Lock Editor Groups 设置](vscode://settings/claudeCode.lockEditorGroups)。已锁定的组会保持锁定，直到您手动解锁。该设置需要 Claude Code v2.1.274 或更高版本。

323 375 

324<Tip>376<Tip>

325 将侧边栏用于您的主要 Claude 会话，并为辅助任务打开其他选项卡。Claude 会记住您首选的位置。Activity Bar 会话列表图标与 Claude 面板分开：会话列表始终在 Activity Bar 中可见，而 Claude 面板图标仅在面板停靠到左侧边栏时才出现在那里。377 将侧边栏用于主要的 Claude 会话，并为辅助任务打开额外的标签页。Claude 会记住您偏好的位置。活动栏中的会话列表图标与 Claude 面板是分开的。会话列表始终显示在活动栏中，而 Claude 面板图标仅在面板停靠到左侧边栏时才会出现在那里。

326</Tip>378</Tip>

327 379 

328<h3 id="continue-conversations-after-a-reload">380<h3 id="continue-conversations-after-a-reload">

329 重新加载后继续对话381 重新加载后继续对话

330</h3>382</h3>

331 383 

332运行 **Developer: Reload Window** 或重启 VS Code 后，聊天是否会返回其对话取决于它在哪里打开：384在运行 **Developer: Reload Window** 或重启 VS Code 后，请查看对话原先打开的位置：

385 

386* **编辑器标签页**：对话会随其标签页一起恢复。

387* **侧边栏**：如果您在最近 10 分钟内在该对话中发送过消息或 Claude 在其中做出过响应，对话会恢复。如果未恢复，请从[会话历史记录](#resume-past-conversations)中恢复该对话。

333 388 

334* **编辑器选项卡**：对话会随其选项卡返回。389如果另一个 Claude Code 进程仍打开着该对话，在此处打开之前会先询问您，显示的 **Open here anyway** 通知与[从会话历史记录恢复](#resume-past-conversations)时相同。如果消息起初保持空白，请参阅[消息为何空白以及何时出现](#a-resumed-conversation-is-blank-at-first)。

335* **侧边栏**：如果您在过去 10 分钟内发送了消息或 Claude 在其中做出了响应，对话会返回。如果它没有返回，请从 [Session history](#resume-past-conversations) 恢复对话。