Documentation 2026-05-13 23:01 UTC to 2026-05-14 17:02 UTC

235 235 

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

237 237 

238* **顶级字段**控制对话：`systemMessage` 将消息注入到对话中，对模型可见，`continue`（Python 中的 `continue_`）确定代理在此 hook 后是否继续运行。238* **顶级字段**在每个事件上的工作方式相同：`systemMessage` 向用户显示消息，`continue`（Python 中的 `continue_`）确定代理在此 hook 后是否继续运行。

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

240 240 

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

331 331 

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

333 333 

334此示例阻止任何尝试写入 `/etc` 目录的操作，并将两个输出字段一起使用：`permissionDecision: 'deny'` 停止工具调用，而 `systemMessage` 将提醒注入到对话中，以便代理接收有关操作被阻止原因的上下文并避免重试：334此示例阻止写入 `/etc` 目录的操作，并向模型和用户解释原因：

335 

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

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

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

335 339 

336<CodeGroup>340<CodeGroup>

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

340 344 

341 if file_path.startswith("/etc"):345 if file_path.startswith("/etc"):

342 return {346 return {

343 # 顶级字段：将指导注入到对话中347 # 顶级字段：显示给用户的消息

344 "systemMessage": "Remember: system directories like /etc are protected.",348 "systemMessage": "Remember: system directories like /etc are protected.",

345 # hookSpecificOutput：阻止操作349 # hookSpecificOutput：阻止操作

346 "hookSpecificOutput": {350 "hookSpecificOutput": {

360 364 

361 if (filePath?.startsWith("/etc")) {365 if (filePath?.startsWith("/etc")) {

362 return {366 return {

363 // 顶级字段：将指导注入到对话中367 // 顶级字段：显示给用户的消息

364 systemMessage: "Remember: system directories like /etc are protected.",368 systemMessage: "Remember: system directories like /etc are protected.",

365 // hookSpecificOutput：阻止操作369 // hookSpecificOutput：阻止操作

366 hookSpecificOutput: {370 hookSpecificOutput: {

807 811 

808### systemMessage 未出现在输出中812### systemMessage 未出现在输出中

809 813 

810`systemMessage` 字段将上下文添加到模型看到的对话中，但它可能不会出现在所有 SDK 输出模式中。如果您需要将 hook 决定呈现给您的应用程序，请单独记录它们或使用专用输出通道。814`systemMessage` 字段向用户显示消息，而不是模型。默认情况下，SDK 不会在消息流中显示 hook 输出，因此除非您设置 `includeHookEvents`（Python 中为 `include_hook_events`），否则消息可能不会出现。要改为将上下文传递给模型，请返回 [`additionalContext`](/zh-CN/hooks#add-context-for-claude)。

815 

816如果您需要可靠地将 hook 决定呈现给您的应用程序，请单独记录它们或使用专用输出通道。

811 817 

812## 相关资源818## 相关资源

813 819 

1860返回可能包含以下内容的 [`HookJSONOutput`](#hookjsonoutput)：1860返回可能包含以下内容的 [`HookJSONOutput`](#hookjsonoutput)：

1861 1861 

1862* `decision`：`"block"` 以阻止操作1862* `decision`：`"block"` 以阻止操作

1863* `systemMessage`：要添加到记录的系统消息1863* `systemMessage`：显示给用户的警告消息

1864* `hookSpecificOutput`：hook 特定的输出数据1864* `hookSpecificOutput`：hook 特定的输出数据

1865 1865 

1866### `HookContext`1866### `HookContext`

2645 2645 

2646**工具名称：** `TodoWrite`2646**工具名称：** `TodoWrite`

2647 2647 

2648<Note>

2649 `TodoWrite` 已弃用，将在未来版本中删除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。设置 `CLAUDE_CODE_ENABLE_TASKS=1` 以选择加入。见 [迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools) 了解如何监视代码更改。

2650</Note>

2651 

2648**输入：**2652**输入：**

2649 2653 

2650```python theme={null}2654```python theme={null}

2668}2672}

2669```2673```

2670 2674 

2675### TaskCreate

2676 

2677**工具名称：** `TaskCreate`

2678 

2679**输入：**

2680 

2681```python theme={null}

2682{

2683 "subject": str, # 简短的任务标题

2684 "description": str, # 详细的任务正文

2685 "activeForm": str | None, # 进行中时显示的现在时标签

2686 "metadata": dict | None, # 任意调用者元数据

2687}

2688```

2689 

2690**输出：**

2691 

2692```python theme={null}

2693{

2694 "task": {"id": str, "subject": str}, # 创建的任务及其分配的 ID

2695}

2696```

2697 

2698### TaskUpdate

2699 

2700**工具名称：** `TaskUpdate`

2701 

2702**输入：**

2703 

2704```python theme={null}

2705{

2706 "taskId": str, # 要修补的任务的 ID

2707 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,

2708 "subject": str | None,

2709 "description": str | None,

2710 "activeForm": str | None,

2711 "addBlocks": list[str] | None, # 此任务现在阻止的任务 ID

2712 "addBlockedBy": list[str] | None, # 现在阻止此任务的任务 ID

2713 "owner": str | None,

2714 "metadata": dict | None,

2715}

2716```

2717 

2718**输出：**

2719 

2720```python theme={null}

2721{

2722 "success": bool,

2723 "taskId": str,

2724 "updatedFields": list[str], # 更改的字段名称

2725 "error": str | None,

2726 "statusChange": {"from": str, "to": str} | None,

2727}

2728```

2729 

2730### TaskGet

2731 

2732**工具名称：** `TaskGet`

2733 

2734**输入：**

2735 

2736```python theme={null}

2737{

2738 "taskId": str, # 要读取的任务的 ID

2739}

2740```

2741 

2742**输出：**

2743 

2744```python theme={null}

2745{

2746 "task": {

2747 "id": str,

2748 "subject": str,

2749 "description": str,

2750 "status": Literal["pending", "in_progress", "completed"],

2751 "blocks": list[str],

2752 "blockedBy": list[str],

2753 } | None, # 当 ID 未找到时为 None

2754}

2755```

2756 

2757### TaskList

2758 

2759**工具名称：** `TaskList`

2760 

2761**输入：**

2762 

2763```python theme={null}

2764{}

2765```

2766 

2767**输出：**

2768 

2769```python theme={null}

2770{

2771 "tasks": [

2772 {

2773 "id": str,

2774 "subject": str,

2775 "status": Literal["pending", "in_progress", "completed"],

2776 "owner": str | None,

2777 "blockedBy": list[str],

2778 }

2779 ],

2780}

2781```

2782 

2671### BashOutput2783### BashOutput

2672 2784 

2673**工具名称：** `BashOutput`2785**工具名称：** `BashOutput`

389| `fallbackModel` | `string` | `undefined` | 主模型失败时使用的模型 |389| `fallbackModel` | `string` | `undefined` | 主模型失败时使用的模型 |

390| `forkSession` | `boolean` | `false` | 使用 `resume` 恢复时，分叉到新会话 ID 而不是继续原始会话 |390| `forkSession` | `boolean` | `false` | 使用 `resume` 恢复时，分叉到新会话 ID 而不是继续原始会话 |

391| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |391| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |

392| `includeHookEvents` | `boolean` | `false` | 在消息流中包括 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) |

392| `includePartialMessages` | `boolean` | `false` | 包括部分消息事件 |393| `includePartialMessages` | `boolean` | `false` | 包括部分消息事件 |

393| `maxBudgetUsd` | `number` | `undefined` | 当客户端成本估计达到此 USD 值时停止查询。与 `total_cost_usd` 的相同估计进行比较；请参阅[跟踪成本和使用情况](/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项 |394| `maxBudgetUsd` | `number` | `undefined` | 当客户端成本估计达到此 USD 值时停止查询。与 `total_cost_usd` 的相同估计进行比较；请参阅[跟踪成本和使用情况](/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项 |

394| `maxThinkingTokens` | `number` | `undefined` | *已弃用：* 改用 `thinking`。思考过程的最大令牌数 |395| `maxThinkingTokens` | `number` | `undefined` | *已弃用：* 改用 `thinking`。思考过程的最大令牌数 |

1596 | ReadMcpResourceInput1597 | ReadMcpResourceInput

1597 | SubscribeMcpResourceInput1598 | SubscribeMcpResourceInput

1598 | SubscribePollingInput1599 | SubscribePollingInput

1600 | TaskCreateInput

1601 | TaskGetInput

1602 | TaskListInput

1599 | TaskStopInput1603 | TaskStopInput

1604 | TaskUpdateInput

1600 | TodoWriteInput1605 | TodoWriteInput

1601 | UnsubscribeMcpResourceInput1606 | UnsubscribeMcpResourceInput

1602 | UnsubscribePollingInput1607 | UnsubscribePollingInput

1850**工具名称：** `TaskCreate`1855**工具名称：** `TaskCreate`

1851 1856 

1852```typescript theme={null}1857```typescript theme={null}

1853// 尚未从 SDK 导出；在本地定义。

1854type TaskCreateInput = {1858type TaskCreateInput = {

1855 subject: string;1859 subject: string;

1856 description: string;1860 description: string;

1866**工具名称：** `TaskUpdate`1870**工具名称：** `TaskUpdate`

1867 1871 

1868```typescript theme={null}1872```typescript theme={null}

1869// 尚未从 SDK 导出；在本地定义。

1870type TaskUpdateInput = {1873type TaskUpdateInput = {

1871 taskId: string;1874 taskId: string;

1872 status?: "pending" | "in_progress" | "completed" | "deleted";1875 status?: "pending" | "in_progress" | "completed" | "deleted";

1887**工具名称：** `TaskGet`1890**工具名称：** `TaskGet`

1888 1891 

1889```typescript theme={null}1892```typescript theme={null}

1890// 尚未从 SDK 导出；在本地定义。

1891type TaskGetInput = {1893type TaskGetInput = {

1892 taskId: string;1894 taskId: string;

1893};1895};

1900**工具名称：** `TaskList`1902**工具名称：** `TaskList`

1901 1903 

1902```typescript theme={null}1904```typescript theme={null}

1903// 尚未从 SDK 导出；在本地定义。

1904type TaskListInput = {};1905type TaskListInput = {};

1905```1906```

1906 1907 

1983 | MonitorOutput1984 | MonitorOutput

1984 | NotebookEditOutput1985 | NotebookEditOutput

1985 | ReadMcpResourceOutput1986 | ReadMcpResourceOutput

1987 | TaskCreateOutput

1988 | TaskGetOutput

1989 | TaskListOutput

1986 | TaskStopOutput1990 | TaskStopOutput

1991 | TaskUpdateOutput

1987 | TodoWriteOutput1992 | TodoWriteOutput

1988 | WebFetchOutput1993 | WebFetchOutput

1989 | WebSearchOutput;1994 | WebSearchOutput;

2347**工具名称：** `TaskCreate`2352**工具名称：** `TaskCreate`

2348 2353 

2349```typescript theme={null}2354```typescript theme={null}

2350// Not yet exported from the SDK; define locally.

2351type TaskCreateOutput = {2355type TaskCreateOutput = {

2352 task: {2356 task: {

2353 id: string;2357 id: string;

2363**工具名称：** `TaskUpdate`2367**工具名称：** `TaskUpdate`

2364 2368 

2365```typescript theme={null}2369```typescript theme={null}

2366// Not yet exported from the SDK; define locally.

2367type TaskUpdateOutput = {2370type TaskUpdateOutput = {

2368 success: boolean;2371 success: boolean;

2369 taskId: string;2372 taskId: string;

2383**工具名称：** `TaskGet`2386**工具名称：** `TaskGet`

2384 2387 

2385```typescript theme={null}2388```typescript theme={null}

2386// Not yet exported from the SDK; define locally.

2387type TaskGetOutput = {2389type TaskGetOutput = {

2388 task: {2390 task: {

2389 id: string;2391 id: string;

2403**工具名称：** `TaskList`2405**工具名称：** `TaskList`

2404 2406 

2405```typescript theme={null}2407```typescript theme={null}

2406// Not yet exported from the SDK; define locally.

2407type TaskListOutput = {2408type TaskListOutput = {

2408 tasks: Array<{2409 tasks: Array<{

2409 id: string;2410 id: string;

170 170 

171Claude Code 支持 AWS SSO 和企业身份提供商的自动凭证刷新。将这些设置添加到您的 Claude Code 设置文件（请参阅[设置](/zh-CN/settings)了解文件位置）。171Claude Code 支持 AWS SSO 和企业身份提供商的自动凭证刷新。将这些设置添加到您的 Claude Code 设置文件（请参阅[设置](/zh-CN/settings)了解文件位置）。

172 172 

173当 Claude Code 检测到您的 AWS 凭证已过期（基于本地时间戳或当 Bedrock 返回凭证错误时），它将自动运行您配置的 `awsAuthRefresh` 和/或 `awsCredentialExport` 命令来获取新凭证，然后重试请求。173这两个设置有不同的触发条件：

174 

175* **`awsAuthRefresh`**：仅当 Claude Code 检测到您的 AWS 凭证已过期时运行，基于本地时间戳或当 Bedrock 返回凭证错误时，然后使用刷新的凭证重试请求。

176* **`awsCredentialExport`**：在会话启动和每次凭证重新加载时运行，即使您的 AWS 默认凭证提供商链中的凭证仍然有效。当您的 Bedrock 账户需要与默认提供商链会解析的凭证不同的跨账户凭证时，请使用此选项。

174 177 

175##### 示例配置178##### 示例配置

176 179 

187 190 

188**`awsAuthRefresh`**：用于修改 `.aws` 目录的命令，例如更新凭证、SSO 缓存或配置文件。命令的输出显示给用户，但不支持交互式输入。这适用于基于浏览器的 SSO 流，其中 CLI 显示 URL 或代码，您在浏览器中完成身份验证。191**`awsAuthRefresh`**：用于修改 `.aws` 目录的命令，例如更新凭证、SSO 缓存或配置文件。命令的输出显示给用户，但不支持交互式输入。这适用于基于浏览器的 SSO 流，其中 CLI 显示 URL 或代码，您在浏览器中完成身份验证。

189 192 

190**`awsCredentialExport`**：仅在您无法修改 `.aws` 且必须直接返回凭证时使用。输出被静默捕获，不显示给用户。命令必须以此格式输出 JSON：193**`awsCredentialExport`**：仅在您无法修改 `.aws` 且必须直接返回凭证时使用。此命令在需要刷新凭证时运行，而不仅仅是在凭证过期时。输出被静默捕获，不显示给用户。命令必须以此格式输出 JSON：

191 194 

192```json theme={null}195```json theme={null}

193{196{

52 将研究和规划与实现分开，以避免解决错误的问题。52 将研究和规划与实现分开，以避免解决错误的问题。

53</Tip>53</Tip>

54 54 

55让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用 [Plan Mode](/zh-CN/common-workflows#use-plan-mode-for-safe-code-analysis) 将探索与执行分开。55让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用 [Plan Mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 将探索与执行分开。

56 56 

57推荐的工作流有四个阶段：57推荐的工作流有四个阶段：

58 58 

60 <Step title="探索">60 <Step title="探索">

61 进入 Plan Mode。Claude 读取文件并回答问题，不进行任何更改。61 进入 Plan Mode。Claude 读取文件并回答问题，不进行任何更改。

62 62 

63 ```txt claude (Plan Mode) theme={null}63 ```txt claude (plan mode) theme={null}

64 read /src/auth and understand how we handle sessions and login.64 read /src/auth and understand how we handle sessions and login.

65 also look at how we manage environment variables for secrets.65 also look at how we manage environment variables for secrets.

66 ```66 ```

69 <Step title="规划">69 <Step title="规划">

70 要求 Claude 创建详细的实现计划。70 要求 Claude 创建详细的实现计划。

71 71 

72 ```txt claude (Plan Mode) theme={null}72 ```txt claude (plan mode) theme={null}

73 I want to add Google OAuth. What files need to change?73 I want to add Google OAuth. What files need to change?

74 What's the session flow? Create a plan.74 What's the session flow? Create a plan.

75 ```75 ```

78 </Step>78 </Step>

79 79 

80 <Step title="实现">80 <Step title="实现">

81 切换回 Normal Mode 并让 Claude 编码，根据其计划进行验证。81 切换出 Plan Mode 并让 Claude 编码，根据其计划进行验证。

82 82 

83 ```txt claude (Normal Mode) theme={null}83 ```txt claude (default mode) theme={null}

84 implement the OAuth flow from your plan. write tests for the84 implement the OAuth flow from your plan. write tests for the

85 callback handler, run the test suite and fix any failures.85 callback handler, run the test suite and fix any failures.

86 ```86 ```

89 <Step title="提交">89 <Step title="提交">

90 要求 Claude 使用描述性消息进行提交并创建 PR。90 要求 Claude 使用描述性消息进行提交并创建 PR。

91 91 

92 ```txt claude (Normal Mode) theme={null}92 ```txt claude (default mode) theme={null}

93 commit with a descriptive message and open a PR93 commit with a descriptive message and open a PR

94 ```94 ```

95 </Step>95 </Step>

396* 在任务之间频繁使用 `/clear` 来完全重置 context window396* 在任务之间频繁使用 `/clear` 来完全重置 context window

397* 当自动压缩触发时，Claude 总结最重要的东西，包括代码模式、文件状态和关键决策397* 当自动压缩触发时，Claude 总结最重要的东西，包括代码模式、文件状态和关键决策

398* 为了更多控制，运行 `/compact <instructions>`，如 `/compact Focus on the API changes`398* 为了更多控制，运行 `/compact <instructions>`，如 `/compact Focus on the API changes`

399* 要仅压缩对话的一部分，使用 `Esc + Esc` 或 `/rewind`，选择消息检查点，并选择 **从这里总结**。这会压缩从该点开始的消息，同时保持早期 context 完整。399* 要仅压缩对话的一部分，使用 `Esc + Esc` 或 `/rewind`，选择消息检查点，并选择 **从这里总结** 或 **总结到这里**。第一个会压缩从该点开始的消息，同时保持早期 context 完整；第二个会压缩早期消息，同时保持最近的消息完整。请参阅 [恢复与总结](/zh-CN/checkpointing#restore-vs-summarize)。

400* 在 CLAUDE.md 中使用像 `"When compacting, always preserve the full list of modified files and any test commands"` 这样的指令来自定义压缩行为，以确保关键 context 在总结中存活400* 在 CLAUDE.md 中使用像 `"When compacting, always preserve the full list of modified files and any test commands"` 这样的指令来自定义压缩行为，以确保关键 context 在总结中存活

401* 对于不需要留在 context 中的快速问题，使用 [`/btw`](/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。答案出现在可关闭的覆盖层中，永远不会进入对话历史，所以你可以检查细节而不增加 context。401* 对于不需要留在 context 中的快速问题，使用 [`/btw`](/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。答案出现在可关闭的覆盖层中，永远不会进入对话历史，所以你可以检查细节而不增加 context。

402 402 

424### 使用检查点进行 Rewind424### 使用检查点进行 Rewind

425 425 

426<Tip>426<Tip>

427 Claude 进行的每个操作都会创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。427 Claude 进行的每个提示都会创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。

428</Tip>428</Tip>

429 429 

430Claude 在更改前自动检查点。双击 `Escape` 或运行 `/rewind` 来打开 rewind 菜单。你可以仅恢复对话、仅恢复代码、恢复两者或从选定的消息进行总结。有关详细信息，请参阅 [Checkpointing](/zh-CN/checkpointing)。430Claude 在每次更改前自动对文件进行快照，以便检查点可以恢复它们。双击 `Escape` 或运行 `/rewind` 来打开 rewind 菜单。你可以仅恢复对话、仅恢复代码、恢复两者或从选定的消息进行总结。有关详细信息，请参阅 [Checkpointing](/zh-CN/checkpointing)。

431 431 

432与其仔细规划每一步，你可以告诉 Claude 尝试一些冒险的事情。如果不起作用，rewind 并尝试不同的方法。检查点在会话中持续，所以你可以关闭你的终端并稍后仍然 rewind。432与其仔细规划每一步，你可以告诉 Claude 尝试一些冒险的事情。如果不起作用，rewind 并尝试不同的方法。检查点在会话中持续，所以你可以关闭你的终端并稍后仍然 rewind。

433 433 

438### 恢复对话438### 恢复对话

439 439 

440<Tip>440<Tip>

441 运行 `claude --continue` 来继续你离开的地方，或 `--resume` 来从最近的会话中选择。441 使用 `/rename` 给会话命名，并像对待分支一样对待它们：每个工作流都有自己的持久 context。

442</Tip>442</Tip>

443 443 

444Claude Code 在本地保存对话。当任务跨越多个会话时，你不必重新解释 context：444Claude Code 在本地保存对话，所以当任务跨越多个会话时，你不必重新解释 context。运行 `claude --continue` 来继续最近的会话，或 `claude --resume` 来从列表中选择。给会话起描述性名称，如 `oauth-migration`，以便你稍后可以找到它们。有关完整的恢复、分支和命名控制集，请参阅 [管理会话](/zh-CN/sessions)。

445 

446```bash theme={null}

447claude --continue # Resume the most recent conversation

448claude --resume # Select from recent conversations

449```

450 

451使用 `/rename` 给会话起描述性名称，如 `"oauth-migration"` 或 `"debugging-memory-leak"`，以便你稍后可以找到它们。像对待分支一样对待会话：不同的工作流可以有单独的、持久的 context。

452 445 

453***446***

454 447 

464 在 CI、pre-commit hooks 或脚本中使用 `claude -p "prompt"`。添加 `--output-format stream-json` 用于流式 JSON 输出。457 在 CI、pre-commit hooks 或脚本中使用 `claude -p "prompt"`。添加 `--output-format stream-json` 用于流式 JSON 输出。

465</Tip>458</Tip>

466 459 

467使用 `claude -p "your prompt"`，你可以非交互地运行 Claude，不需要会话。非交互模式是你将 Claude 集成到 CI 管道、pre-commit hooks 或任何自动化工作流中的方式。输出格式让你以编程方式解析结果：纯文本、JSON 或流式 JSON。460使用 `claude -p "your prompt"`，你可以非交互地运行 Claude，不需要会话。[非交互模式](/zh-CN/headless)是你将 Claude 集成到 CI 管道、pre-commit hooks 或任何自动化工作流中的方式。输出格式让你以编程方式解析结果：纯文本、JSON 或流式 JSON。

468 461 

469```bash theme={null}462```bash theme={null}

470# One-off queries463# One-off queries

483 并行运行多个 Claude 会话以加快开发、运行隔离的实验或启动复杂的工作流。476 并行运行多个 Claude 会话以加快开发、运行隔离的实验或启动复杂的工作流。

484</Tip>477</Tip>

485 478 

486有三种主要方式来运行并行会话：479选择适合你想要自己进行多少协调的并行方法：

487 480 

488* [Claude Code 桌面应用](/zh-CN/desktop#work-in-parallel-with-sessions)：以视觉方式管理多个本地会话。每个会话获得自己的隔离 worktree。481* [Worktrees](/zh-CN/worktrees)：在隔离的 git 检出中运行单独的 CLI 会话，以便编辑不会冲突

489* [Claude Code 在网络上](/zh-CN/claude-code-on-the-web)：在 Anthropic 的安全云基础设施中的隔离 VM 上运行。482* [桌面应用](/zh-CN/desktop#work-in-parallel-with-sessions)：以视觉方式管理多个本地会话，每个会话都在自己的 worktree 中

490* [Agent teams](/zh-CN/agent-teams)：具有共享任务、消息和团队主管的多个会话的自动协调。483* [Claude Code 在网络上](/zh-CN/claude-code-on-the-web)：在 Anthropic 管理的云基础设施中的隔离虚拟机上运行会话

484* [Agent teams](/zh-CN/agent-teams)：具有共享任务、消息和团队主管的多个会话的自动协调

491 485 

492除了并行化工作，多个会话启用了质量关注的工作流。新鲜的 context 改进了代码审查，因为 Claude 不会偏向于它刚刚编写的代码。486除了并行化工作，多个会话启用了质量关注的工作流。新鲜的 context 改进了代码审查，因为 Claude 不会偏向于它刚刚编写的代码。

493 487 

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

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

4 4 

5# checkpointing5# Checkpointing

6 6 

7> 跟踪、回溯和总结 Claude 的编辑和对话以管理会话状态。7> 跟踪、回溯和总结 Claude 的编辑和对话以管理会话状态。

8 8 

30* **从此处总结**：将此点之后的对话压缩为摘要，释放 context window 空间30* **从此处总结**：将此点之后的对话压缩为摘要，释放 context window 空间

31* **算了**：返回消息列表而不做任何更改31* **算了**：返回消息列表而不做任何更改

32 32 

33恢复对话或总结后，所选消息的原始提示会恢复到输入字段中，以便您可以重新发送或编辑它。33恢复对话或选择"从此处总结"后，所选消息的原始提示会恢复到输入字段中，以便您可以重新发送或编辑它。

34 

35选择"算了"会让您留在消息列表，输入字段为空。

34 36 

35#### 恢复与总结37#### 恢复与总结

36 38 

37三个恢复选项恢复状态：它们撤销代码更改、对话历史或两者。"从此处总结"的工作方式不同：39恢复选项恢复状态：它们撤销代码更改、对话历史或两者。总结选项将对话的一部分压缩为 AI 生成的摘要，而不改变磁盘上的文件：

38 40 

39* 所选消息之前的消息保持不变41* **从此处总结**：所选消息之前的消息保持不变。所选消息及其后的所有消息被替换为摘要。使用此选项可以放弃旁支讨论，同时保持早期上下文的完整细节。

40* 所选消息及其后的所有消息被替换为紧凑的 AI 生成的摘要42* **算了总结**：所选消息之前的消息被替换为摘要。所选消息及其后的所有消息保持不变，您留在对话的末尾。使用此选项可以压缩早期设置讨论，同时保持最近工作的完整细节。

41* 磁盘上的文件不会改变

42* 原始消息保存在会话记录中，因此 Claude 可以在需要时参考详细信息

43 43 

44这类似于 `/compact`，但更有针对性：您不是总结整个对话，而是保持早期上下文的完整细节，只压缩占用空间的部分。您可以输入可选说明来指导摘要的重点。44在这两种情况下，原始消息都保存在会话记录中，因此 Claude 可以在需要时参考详细信息。您可以输入可选说明来指导摘要的重点。这类似于 `/compact`，但更有针对性：您不是总结整个对话，而是选择所选消息的哪一侧进行压缩。

45 45 

46<Note>46<Note>

47 总结将您保持在同一会话中并压缩上下文。如果您想尝试不同的方法，同时保持原始会话完整，请改用 [fork](/zh-CN/how-claude-code-works#resume-or-fork-sessions)（`claude --continue --fork-session`）。47 总结将您保持在同一会话中并压缩上下文。如果您想尝试不同的方法，同时保持原始会话完整，请改用 [fork](/zh-CN/sessions#branch-a-session)（`claude --continue --fork-session`）。

48</Note>48</Note>

49 49 

50## 常见用例50## 常见用例

85## 另请参阅85## 另请参阅

86 86 

87* [Interactive mode](/zh-CN/interactive-mode) - 快捷键和会话控制87* [Interactive mode](/zh-CN/interactive-mode) - 快捷键和会话控制

88* [Built-in commands](/zh-CN/commands) - 使用 `/rewind` 访问 checkpoints88* [Commands](/zh-CN/commands) - 使用 `/rewind` 访问 checkpoints

89* [CLI reference](/zh-CN/cli-reference) - 命令行选项89* [CLI reference](/zh-CN/cli-reference) - 命令行选项

782 782 

783### 远程控制会话已过期或访问被拒绝783### 远程控制会话已过期或访问被拒绝

784 784 

785`--teleport` 通过与云会话使用的相同远程控制会话基础设施连接，所以身份验证和会话过期错误会显示远程控制措辞。你可能会看到 `Remote Control session has expired` 或 `Access denied`。连接令牌是短期的，并限定于你的账户。785`--teleport` 通过与云会话使用的相同远程控制会话基础设施连接，所以身份验证和会话过期错误会显示远程控制措辞。你可能会看到 `Remote Control session expired` 或 `Access denied`。连接令牌是短期的，并限定于你的账户。

786 786 

787* 在本地运行 `/login` 以刷新你的凭证，然后重新连接787* 在本地运行 `/login` 以刷新你的凭证，然后重新连接

788* 确认你已登录到拥有会话的相同账户788* 确认你已登录到拥有会话的相同账户

24| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |24| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |

25| `claude auth logout` | 从您的 Anthropic 账户登出 | `claude auth logout` |25| `claude auth logout` | 从您的 Anthropic 账户登出 | `claude auth logout` |

26| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出 | `claude auth status` |26| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出 | `claude auth status` |

27| `claude agents` | 打开 [agent view](/zh-CN/agent-view) 以监控和分派并行后台会话。当输出被管道传输时，改为列出已配置的 [subagents](/zh-CN/sub-agents) | `claude agents` |27| `claude agents` | 打开 [agent view](/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话 | `claude agents` |

28| `claude attach <id>` | 在此终端中附加到 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell) | `claude attach 7c5dcf5d` |28| `claude attach <id>` | 在此终端中附加到 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell) | `claude attach 7c5dcf5d` |

29| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置 | `claude auto-mode defaults > rules.json` |29| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置 | `claude auto-mode defaults > rules.json` |

30| `claude logs <id>` | 从 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell) 打印最近的输出 | `claude logs 7c5dcf5d` |30| `claude logs <id>` | 从 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell) 打印最近的输出 | `claude logs 7c5dcf5d` |

26 26 

27**在会话之间。** `/clear` 在保持项目内存的同时开始新任务。`/resume` 和 `/branch` 让您返回或分叉早期的对话。`/teleport` 将网络会话拉入此终端，`/remote-control` 让您从另一台设备继续此本地会话。27**在会话之间。** `/clear` 在保持项目内存的同时开始新任务。`/resume` 和 `/branch` 让您返回或分叉早期的对话。`/teleport` 将网络会话拉入此终端，`/remote-control` 让您从另一台设备继续此本地会话。

28 28 

29**当出现问题时。** `/rewind` 将代码和对话回滚到检查点。`/doctor` 和 `/debug` 诊断安装和运行时问题，`/feedback` 报告附加会话上下文的错误。29**当出现问题时。** `/rewind` 将代码和对话回滚到检查点，或总结对话的一部分。`/doctor` 和 `/debug` 诊断安装和运行时问题，`/feedback` 报告附加会话上下文的错误。

30 30 

31## 所有命令31## 所有命令

32 32 

148 148 

149### 在终端中运行命令149### 在终端中运行命令

150 150 

151集成终端让你在不切换到另一个应用的情况下运行命令。从 **Views** 菜单打开它，或在 macOS 或 Windows 上按 **Ctrl+\`**。终端在你的会话工作目录中打开，并与 Claude 共享相同的环境，因此 `npm test` 或 `git status` 等命令看到 Claude 正在编辑的相同文件。终端仅在本地会话中可用。151集成终端让你在不切换到另一个应用的情况下运行命令。从 **Views** 菜单打开它，或在 macOS 或 Windows 上按 **Ctrl+\`**。终端在你的会话工作目录中打开，并与 Claude 共享相同的环境，因此 `npm test` 或 `git status` 等命令看到 Claude 正在编辑的相同文件。要打开第二个终端选项卡，点击终端窗格标题中的 **+** 或右键点击聊天中的文件夹来选择 **Open in terminal**。终端仅在本地会话中可用。

152 152 

153### 打开和编辑文件153### 打开和编辑文件

154 154 

296 296 

297使用侧边栏顶部的控制来按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活跃会话顶部工具栏中的会话标题。要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 自动总结对话并继续工作。你也可以输入 `/compact` 来更早触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/zh-CN/how-claude-code-works#the-context-window)。297使用侧边栏顶部的控制来按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活跃会话顶部工具栏中的会话标题。要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 自动总结对话并继续工作。你也可以输入 `/compact` 来更早触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/zh-CN/how-claude-code-works#the-context-window)。

298 298 

299桌面应用在 Code 会话完成任务且你当前未查看该会话时发送操作系统通知。

300 

299### 在不偏离会话的情况下提出侧边问题301### 在不偏离会话的情况下提出侧边问题

300 302 

301侧边聊天让你提出一个使用你的会话上下文的问题，但不会添加任何内容回到主对话。当你想要理解一段代码、检查一个假设或探索一个想法而不引导会话偏离时，使用它。303侧边聊天让你提出一个使用你的会话上下文的问题，但不会添加任何内容回到主对话。当你想要理解一段代码、检查一个假设或探索一个想法而不引导会话偏离时，使用它。

598托管设置覆盖项目和用户设置，并在 Desktop 生成 CLI 会话时应用。你可以在你的组织的[托管设置](/zh-CN/settings#settings-precedence)文件中设置这些键，或通过管理员控制台远程推送它们。600托管设置覆盖项目和用户设置，并在 Desktop 生成 CLI 会话时应用。你可以在你的组织的[托管设置](/zh-CN/settings#settings-precedence)文件中设置这些键，或通过管理员控制台远程推送它们。

599 601 

600| 键 | 描述 |602| 键 | 描述 |

601| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |603| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |

602| `permissions.disableBypassPermissionsMode` | 设置为 `"disable"` 以防止用户启用绕过权限模式。 |604| `permissions.disableBypassPermissionsMode` | 设置为 `"disable"` 以防止用户启用绕过权限模式。 |

603| `disableAutoMode` | 设置为 `"disable"` 以防止用户启用 [Auto](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。从模式选择器中删除 Auto。也在 `permissions` 下接受。 |605| `disableAutoMode` | 设置为 `"disable"` 以防止用户启用 [Auto](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。从模式选择器中删除 Auto。也在 `permissions` 下接受。 |

604| `autoMode` | 自定义 auto 模式分类器在你的组织中信任和阻止的内容。请参阅[配置 auto 模式](/zh-CN/auto-mode-config)。 |606| `autoMode` | 自定义 auto 模式分类器在你的组织中信任和阻止的内容。请参阅[配置 auto 模式](/zh-CN/auto-mode-config)。 |

605| `sshConfigs` | 预配置[SSH 连接](#pre-configure-ssh-connections-for-your-team)，在环境下拉菜单中显示。用户无法编辑或删除托管连接。 |607| `sshConfigs` | 预配置[SSH 连接](#pre-configure-ssh-connections-for-your-team)，在环境下拉菜单中显示。用户无法编辑或删除托管连接。 |

606| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |608| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |

609| `managedMcpServers` | 将 MCP 服务器配置推送到第三方部署中的所有用户。每个条目指定 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。仅在第三方 (3P) Desktop 部署中可用。 |

607 610 

608部署到每台机器上磁盘的托管设置文件适用于 Desktop 会话。通过管理员控制台远程推送的托管设置目前仅适用于 CLI 和 IDE 会话，因此对于 Desktop 部署，要么通过 MDM 分发文件，要么使用上面的[管理员控制台控制](#admin-console-controls)。611部署到每台机器上磁盘的托管设置文件适用于 Desktop 会话。通过管理员控制台远程推送的托管设置目前仅适用于 CLI 和 IDE 会话，因此对于 Desktop 部署，要么通过 MDM 分发文件，要么使用上面的[管理员控制台控制](#admin-console-controls)。

609 612 

1> ## Documentation Index

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

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

4 

5# 在 Claude Code Desktop 中安排定期任务

6 

7> 在 Claude Code Desktop 中设置定期任务，以定期自动运行 Claude 进行日常代码审查、依赖项审计或早晨简报。

8 

9定期任务在您选择的时间和频率自动启动新会话。使用它们进行定期工作，如日常代码审查、依赖项更新检查或从您的日历和收件箱中提取信息的早晨简报。

10 

11Desktop 应用的 **Routines** 页面让您可以创建本地定期任务和远程 [routines](/zh-CN/routines)。本地任务在您的机器上运行，可直接访问您的文件和工具，但仅在应用打开且计算机处于唤醒状态时才会触发。远程 routine 在 Anthropic 管理的云基础设施上运行，即使您的计算机关闭也可以运行，还可以通过 API 调用或 GitHub 事件触发。本页面涵盖本地定期任务；有关远程 routine 及其触发选项，请参阅 [Routines](/zh-CN/routines)。

12 

13## 比较调度选项

14 

15Claude Code offers three ways to schedule recurring or one-off work:

16 

17| | [Cloud](/en/routines) | [Desktop](/en/desktop-scheduled-tasks) | [`/loop`](/en/scheduled-tasks) |

18| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |

19| Runs on | Anthropic cloud | Your machine | Your machine |

20| Requires machine on | No | Yes | Yes |

21| Requires open session | No | No | Yes |

22| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |

23| Access to local files | No (fresh clone) | Yes | Yes |

24| MCP servers | Connectors configured per task | [Config files](/en/mcp) and connectors | Inherits from session |

25| Permission prompts | No (runs autonomously) | Configurable per task | Inherits from session |

26| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

27| Minimum interval | 1 hour | 1 minute | 1 minute |

28 

29<Tip>

30 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.

31</Tip>

32 

33<Note>

34 默认情况下，定期任务针对您的工作目录的任何状态运行，包括未提交的更改。在创建任务时启用 worktree 切换，为每次运行提供其自己的隔离 Git worktree，与 [parallel sessions](/zh-CN/desktop#work-in-parallel-with-sessions) 的工作方式相同。

35</Note>

36 

37## 创建定期任务

38 

39单击侧边栏中的 **Routines**，然后单击 **New routine** 并选择 **Local**。配置这些字段：

40 

41| 字段 | 描述 |

42| ------------ | ---------------------------------------------------------------------------------------------------------- |

43| Name | 任务的标识符。转换为小写 kebab-case 并用作磁盘上的文件夹名称。在您的任务中必须是唯一的。 |

44| Description | 任务列表中显示的简短摘要。 |

45| Instructions | 任务运行时 Claude 应该做什么。以您在提示框中编写任何消息的相同方式编写此内容。instructions 输入包括权限模式和模型的选择器，在其下方您选择工作文件夹以及是否在隔离的 worktree 中运行。 |

46| Schedule | 任务运行的频率。请参阅下面的 [schedule options](#schedule-options)。 |

47 

48在保存任务之前需要一个文件夹。如果您还没有信任该文件夹，Desktop 会在保存前提示您信任它。

49 

50您也可以通过在任何会话中描述您想要的内容来创建任务。例如，"设置一个每天早上 9 点运行的日常代码审查"会创建一个定期任务，"提醒我明天下午 3 点检查部署"会创建一个一次性任务，在触发后禁用自己。

51 

52## 调度选项

53 

54从 Schedule 控件中选择一个预设：

55 

56* **Manual**：无调度，仅在您单击 **Run now** 时运行。适用于保存您按需触发的提示

57* **Hourly**：每小时运行一次

58* **Daily**：显示时间选择器，默认为本地时间上午 9:00

59* **Weekdays**：与 Daily 相同，但跳过星期六和星期日

60* **Weekly**：显示时间选择器和日期选择器

61 

62对于选择器不提供的间隔，例如每 15 分钟、每月的第一天或在特定未来时间的单次运行，请在任何 Desktop 会话中询问 Claude 来设置调度。使用纯语言；例如，"安排一个任务每 6 小时运行一次所有测试。"

63 

64## 定期任务如何运行

65 

66定期任务在您的机器上运行。Desktop 在应用打开时每分钟检查一次调度，并在任务到期时启动一个新会话，独立于您打开的任何手动会话。每个任务在计划时间后会有几分钟的小延迟，以错开 API 流量。延迟是确定性的：同一任务总是在相同的偏移量处启动。

67 

68当任务触发时，您会收到桌面通知，新会话会在侧边栏的 **Scheduled** 部分下出现。打开它以查看 Claude 做了什么、审查更改或响应权限提示。会话的工作方式与任何其他会话相同：Claude 可以编辑文件、运行命令、创建提交和打开拉取请求。

69 

70任务仅在 desktop 应用运行且计算机处于唤醒状态时运行。如果您的计算机在计划时间内进入睡眠状态，该运行将被跳过。要防止空闲睡眠，请在 Settings 中的 **Desktop app → General** 下启用 **Keep computer awake**。关闭笔记本电脑盖仍会使其进入睡眠状态。对于需要在计算机关闭时运行或应该通过 API 调用或 GitHub 事件触发的任务，请改为创建远程 [routine](/zh-CN/routines)。

71 

72## 错过的运行

73 

74当应用启动或计算机唤醒时，Desktop 会检查每个任务是否在过去七天内错过了任何运行。如果有，Desktop 会为最近错过的时间启动恰好一次追赶运行，并丢弃任何更早的运行。一个错过六天的日常任务在唤醒时运行一次。当追赶运行启动时，Desktop 会显示通知。

75 

76在编写提示时请记住这一点。计划在上午 9 点运行的任务可能在晚上 11 点运行，如果您的计算机整天处于睡眠状态。如果时间很重要，请在提示本身中添加护栏，例如："仅审查今天的提交。如果已经是下午 5 点之后，请跳过审查，只发布一份错过内容的摘要。"

77 

78## 定期任务的权限

79 

80每个任务都有自己的权限模式，您在创建或编辑任务时设置。来自 `~/.claude/settings.json` 的允许规则也适用于定期任务会话。如果任务在 Ask 模式下运行并需要运行它没有权限的工具，运行将停滞，直到您批准它。会话保持在侧边栏中打开，以便您稍后可以回答。

81 

82为了避免停滞，在创建任务后单击 **Run now**，查看权限提示，并为每个提示选择"always allow"。该任务的未来运行会自动批准相同的工具，无需提示。您可以从任务的详细信息页面查看和撤销这些批准。

83 

84## 管理定期任务

85 

86单击 **Routines** 列表中的任务以打开其详细信息页面。从这里您可以：

87 

88* **Run now**：立即启动任务，无需等待下一个计划时间

89* **Status**：在 Active 和 Paused 之间切换，以暂停或恢复定期运行，而无需删除任务

90* **Edit**：更改 instructions、schedule、folder 或其他设置

91* **Review history**：查看每次过去的运行，包括跳过的运行。将鼠标悬停在跳过的条目上以查看原因：您的计算机处于睡眠状态、前一次运行仍在进行中，或其他定期任务已在运行。单击 **Show more** 以加载较早的条目。

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

93* **Delete**：删除任务并存档它创建的所有会话。确认对话框中会出现 **Also delete files on disk** 复选框；选中它以同时删除任务的 `SKILL.md` 文件和 `~/.claude/scheduled-tasks/` 中的关联数据。

94 

95您也可以通过在任何 Desktop 会话中询问 Claude 来列出、创建、编辑和暂停任务。例如，"pause my dependency-audit task"或"show me my scheduled tasks"。要删除任务，请使用其详细信息页面上的 **Delete** 按钮。

96 

97定期任务还可以使用 `update_scheduled_task` MCP 工具从运行中的会话内修改其自己的调度或提示。这让任务可以根据它发现的内容重新调度自己，例如，当它检测到发布分支已创建时，将代码审查重新调度为更早运行。

98 

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

100 

101## 相关资源

102 

103* [Routines](/zh-CN/routines)：在 Anthropic 管理的基础设施上按计划、通过 API 调用或响应 GitHub 事件运行任务，即使您的计算机关闭

104* [Run prompts on a schedule](/zh-CN/scheduled-tasks)：在 CLI 中使用 `/loop` 的会话范围调度

105* [Claude Code GitHub Actions](/zh-CN/github-actions)：在 CI 中按计划运行 Claude，而不是在您的机器上

106* [Use Claude Code Desktop](/zh-CN/desktop)：完整的 Desktop 应用指南

45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Bedrock 或 Bedrock Mantle 时覆盖 Haiku 级模型的 AWS 区域 |45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Bedrock 或 Bedrock Mantle 时覆盖 Haiku 级模型的 AWS 区域 |

46| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Vertex AI 端点 URL。用于自定义 Vertex 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |46| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Vertex AI 端点 URL。用于自定义 Vertex 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |

47| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 请求的 GCP 项目 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 凭证文件中的项目覆盖。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |47| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 请求的 GCP 项目 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 凭证文件中的项目覆盖。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |

48| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)的工作区 ID。当您的联合规则的范围超过一个工作区时设置此选项，以便令牌交换知道要针对哪个工作区 |

48| `API_TIMEOUT_MS` | API 请求的超时时间（以毫秒为单位）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |49| `API_TIMEOUT_MS` | API 请求的超时时间（以毫秒为单位）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |

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

50| `BASH_DEFAULT_TIMEOUT_MS` | 长时间运行的 bash 命令的默认超时（默认值：120000，或 2 分钟） |51| `BASH_DEFAULT_TIMEOUT_MS` | 长时间运行的 bash 命令的默认超时（默认值：120000，或 2 分钟） |

138| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 覆盖插件根目录。尽管名称如此，这设置的是父目录，而不是缓存本身：市场和插件缓存位于此路径下的子目录中。默认为 `~/.claude/plugins` |139| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 覆盖插件根目录。尽管名称如此，这设置的是父目录，而不是缓存本身：市场和插件缓存位于此路径下的子目录中。默认为 `~/.claude/plugins` |

139| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安装或更新插件时 git 操作的超时（以毫秒为单位）（默认值：120000）。对于大型存储库或网络连接缓慢的情况，请增加此值。请参阅[Git 操作超时](/zh-CN/plugin-marketplaces#git-operations-time-out) |140| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安装或更新插件时 git 操作的超时（以毫秒为单位）（默认值：120000）。对于大型存储库或网络连接缓慢的情况，请增加此值。请参阅[Git 操作超时](/zh-CN/plugin-marketplaces#git-operations-time-out) |

140| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 以在 `git pull` 失败时保留现有市场缓存，而不是擦除并重新克隆。在离线或隔离环境中很有用，其中重新克隆会以相同方式失败。请参阅[市场更新在离线环境中失败](/zh-CN/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 以在 `git pull` 失败时保留现有市场缓存，而不是擦除并重新克隆。在离线或隔离环境中很有用，其中重新克隆会以相同方式失败。请参阅[市场更新在离线环境中失败](/zh-CN/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 以通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 插件源。在 CI 运行器、容器或任何没有为 `github.com` 配置 SSH 密钥的环境中很有用 |

141| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。使用此选项可将预填充的插件目录捆绑到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而无需重新克隆。请参阅[为容器预填充插件](/zh-CN/plugin-marketplaces#pre-populate-plugins-for-containers) |143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。使用此选项可将预填充的插件目录捆绑到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而无需重新克隆。请参阅[为容器预填充插件](/zh-CN/plugin-marketplaces#pre-populate-plugins-for-containers) |

142| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 的主机平台设置，并代表其管理模型提供商路由。设置后，提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在设置文件中被忽略，以便用户设置无法覆盖主机的路由。Bedrock、Vertex 和 Foundry 的自动遥测选择退出也被跳过，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider) |144| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 的主机平台设置，并代表其管理模型提供商路由。设置后，提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在设置文件中被忽略，以便用户设置无法覆盖主机的路由。Bedrock、Vertex 和 Foundry 的自动遥测选择退出也被跳过，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider) |

143| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 设置为 `1` 以允许代理执行 DNS 解析而不是调用者。对于代理应处理主机名解析的环境选择加入 |145| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 设置为 `1` 以允许代理执行 DNS 解析而不是调用者。对于代理应处理主机名解析的环境选择加入 |

152| `CLAUDE_CODE_SHELL` | 覆盖自动 shell 检测。当您的登录 shell 与您的首选工作 shell 不同时很有用（例如，`bash` 与 `zsh`） |154| `CLAUDE_CODE_SHELL` | 覆盖自动 shell 检测。当您的登录 shell 与您的首选工作 shell 不同时很有用（例如，`bash` 与 `zsh`） |

153| `CLAUDE_CODE_SHELL_PREFIX` | 命令前缀以包装 Claude Code 生成的所有 bash 命令：Bash 工具调用、[hook](/zh-CN/hooks) 命令和 stdio [MCP server](/zh-CN/mcp) 启动命令。对于日志记录或审计很有用。示例：设置 `/path/to/logger.sh` 将每个命令作为 `/path/to/logger.sh <command>` 运行 |155| `CLAUDE_CODE_SHELL_PREFIX` | 命令前缀以包装 Claude Code 生成的所有 bash 命令：Bash 工具调用、[hook](/zh-CN/hooks) 命令和 stdio [MCP server](/zh-CN/mcp) 启动命令。对于日志记录或审计很有用。示例：设置 `/path/to/logger.sh` 将每个命令作为 `/path/to/logger.sh <command>` 运行 |

154| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。[`--bare`](/zh-CN/headless#start-faster-with-bare-mode) CLI 标志设置此选项 |156| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。[`--bare`](/zh-CN/headless#start-faster-with-bare-mode) CLI 标志设置此选项 |

155| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在 Opus 4.7 上使用较短的系统提示和缩写的工具描述。对其他模型无效。完整的工具集、hooks、MCP 服务器和 CLAUDE.md 发现保持启用 |157| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在任何模型上使用较短的系统提示和缩写的工具描述。设置为 `0`、`false`、`no` 或 `off` 以选择退出，即使在实验或服务器配置会以其他方式启用它的模型上。完整的工具集、hooks、MCP 服务器和 CLAUDE.md 发现保持启用 |

156| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |158| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |

157| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | 跳过 Bedrock 的 AWS 身份验证（例如，使用 LLM 网关时） |159| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | 跳过 Bedrock 的 AWS 身份验证（例如，使用 LLM 网关时） |

158| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证（例如，使用 LLM 网关时） |160| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证（例如，使用 LLM 网关时） |

156 156 

157### 使用 skills157### 使用 skills

158 158 

159`prompt` 输入接受 [skill](/zh-CN/skills) 调用以及纯文本：

160 

161* 对于存储库的 `.claude/skills/` 目录中的 skill，在操作步骤之前运行 `actions/checkout`，然后传递 `/skill-name`。

162* 对于打包在插件中的 skill，使用 `plugin_marketplaces` 和 `plugins` 输入安装插件，然后传递命名空间的 `/plugin-name:skill-name`。

163 

164以下工作流安装 `code-review` 插件并在每个新的或更新的拉取请求上运行其 skill：

165 

159```yaml theme={null}166```yaml theme={null}

160name: Code Review167name: Code Review

161on:168on:

168 - uses: anthropics/claude-code-action@v1175 - uses: anthropics/claude-code-action@v1

169 with:176 with:

170 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}177 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

171 prompt: "Review this pull request for code quality, correctness, and security. Analyze the diff, then post your findings as review comments."178 plugin_marketplaces: "https://github.com/anthropics/claude-code.git"

172 claude_args: "--max-turns 5"179 plugins: "code-review@claude-code-plugins"

180 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

173```181```

174 182 

175### 使用提示的自定义自动化183### 使用提示的自定义自动化

622Claude Code Action v1 使用简化的配置：630Claude Code Action v1 使用简化的配置：

623 631 

624| 参数 | 描述 | 必需 |632| 参数 | 描述 | 必需 |

625| ------------------- | ------------------------------------------ | ----- |633| --------------------- | ------------------------------------------ | ----- |

626| `prompt` | Claude 的说明（纯文本或 [skill](/zh-CN/skills) 名称） | 否\* |634| `prompt` | Claude 的说明（纯文本或 [skill](/zh-CN/skills) 名称） | 否\* |

627| `claude_args` | 传递给 Claude Code 的 CLI 参数 | 否 |635| `claude_args` | 传递给 Claude Code 的 CLI 参数 | 否 |

636| `plugin_marketplaces` | 插件市场 Git URL 的换行符分隔列表 | 否 |

637| `plugins` | 执行前要安装的插件名称的换行符分隔列表 | 否 |

628| `anthropic_api_key` | Claude API 密钥 | 是\*\* |638| `anthropic_api_key` | Claude API 密钥 | 是\*\* |

629| `github_token` | 用于 API 访问的 GitHub 令牌 | 否 |639| `github_token` | 用于 API 访问的 GitHub 令牌 | 否 |

630| `trigger_phrase` | 自定义触发短语（默认："@claude"） | 否 |640| `trigger_phrase` | 自定义触发短语（默认："@claude"） | 否 |

70 70 

71### Checkpoint71### Checkpoint

72 72 

73在 Claude 进行每次编辑之前捕获的代码自动快照。按两次 `Esc` 或运行 `/rewind` 将代码、对话或两者恢复到较早的点。Checkpoints 是会话本地的，与 git 分开，不跟踪通过 Bash 工具进行的更改。73在每个您发送的提示处创建的还原点。Claude Code 在每次编辑之前对文件进行快照，以便 checkpoint 可以恢复它们。按两次 `Esc` 或运行 `/rewind` 将代码、对话或两者恢复到较早的点，或从选定的消息总结对话的一部分。Checkpoints 是会话本地的，与 git 分开，不跟踪通过 Bash 工具进行的更改。

74 74 

75了解更多：[Checkpointing](/zh-CN/checkpointing)75了解更多：[Checkpointing](/zh-CN/checkpointing)

76 76 

78 78 

79Claude Code 读取项目范围配置的目录：settings、hooks、skills、subagents、rules 和 auto memory。项目在其根目录有 `.claude/`；您的用户级默认值在 `~/.claude/`。79Claude Code 读取项目范围配置的目录：settings、hooks、skills、subagents、rules 和 auto memory。项目在其根目录有 `.claude/`；您的用户级默认值在 `~/.claude/`。

80 80 

81了解更多：[`.claude` directory](/zh-CN/claude-directory)81了解更多：[The `.claude` directory](/zh-CN/claude-directory)

82 82 

83### CLAUDE.md83### CLAUDE.md

84 84 

98 98 

99当 [context window](#context-window) 接近其限制时，自动总结您的对话。首先清除较旧的工具输出，然后总结对话。项目根 CLAUDE.md 和 auto memory 在 compaction 期间保留并从磁盘重新加载；仅在对话中给出的指令可能会丢失。运行 `/compact` 手动触发，可选择使用焦点，如 `/compact focus on the API changes`。99当 [context window](#context-window) 接近其限制时，自动总结您的对话。首先清除较旧的工具输出，然后总结对话。项目根 CLAUDE.md 和 auto memory 在 compaction 期间保留并从磁盘重新加载；仅在对话中给出的指令可能会丢失。运行 `/compact` 手动触发，可选择使用焦点，如 `/compact focus on the API changes`。

100 100 

101了解更多：[什么在 compaction 中保留](/zh-CN/context-window#what-survives-compaction) · [当上下文填满时](/zh-CN/how-claude-code-works#when-context-fills-up)101了解更多：[What survives compaction](/zh-CN/context-window#what-survives-compaction) · [When context fills up](/zh-CN/how-claude-code-works#when-context-fills-up)

102 102 

103### Context window103### Context window

104 104 

105会话的工作内存，保存对话历史、文件内容、命令输出、CLAUDE.md、auto memory、加载的 skills 和系统指令。当您工作时，上下文会填满直到 [compaction](#compaction) 总结它。运行 `/context` 查看什么在使用空间。对于底层模型概念，请参阅[平台术语表](https://platform.claude.com/docs/zh-CN/about-claude/glossary#context-window)。105会话的工作内存，保存对话历史、文件内容、命令输出、CLAUDE.md、auto memory、加载的 skills 和系统指令。当您工作时，上下文会填满直到 [compaction](#compaction) 总结它。运行 `/context` 查看什么在使用空间。对于底层模型概念，请参阅[平台术语表](https://platform.claude.com/docs/zh-CN/about-claude/glossary#context-window)。

106 106 

107了解更多：[探索 context window](/zh-CN/context-window)107了解更多：[Explore the context window](/zh-CN/context-window)

108 108 

109## D109## D

110 110 

108 108 

109### 非交互式运行109### 非交互式运行

110 110 

111`/goal` 在[非交互式模式](/zh-CN/headless)和通过[远程控制](/zh-CN/remote-control)中工作。使用 `-p` 设置目标会在单个调用中运行循环至完成：111`/goal` 在[非交互式模式](/zh-CN/headless)、[桌面应用](/zh-CN/desktop)中工作，并通过[远程控制](/zh-CN/remote-control)工作。使用 `-p` 设置目标会在单个调用中运行循环至完成：

112 112 

113```bash theme={null}113```bash theme={null}

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

297| :-------------- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |297| :-------------- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

298| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |298| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |

299| `if` | 否 | 权限规则语法以过滤此 hook 何时运行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。仅当工具调用与模式匹配时，hook 才会生成，或当 Bash 命令太复杂而无法解析时。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与[权限规则](/zh-CN/permissions)相同的语法 |299| `if` | 否 | 权限规则语法以过滤此 hook 何时运行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。仅当工具调用与模式匹配时，hook 才会生成，或当 Bash 命令太复杂而无法解析时。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与[权限规则](/zh-CN/permissions)相同的语法 |

300| `timeout` | 否 | 取消前的秒数。默认值：命令 600、提示 30、代理 60 |300| `timeout` | 否 | 取消前的秒数。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。[`UserPromptSubmit`](#userpromptsubmit) 将 `command`、`http` 和 `mcp_tool` 的默认值降低到 30 |

301| `statusMessage` | 否 | hook 运行时显示的自定义加载程序消息 |301| `statusMessage` | 否 | hook 运行时显示的自定义加载程序消息 |

302| `once` | 否 | 如果为 `true`，每个会话仅运行一次，然后被移除。仅在[skill frontmatter](#hooks-in-skills-and-agents)中声明的 hooks 中受尊重；在设置文件和代理 frontmatter 中被忽略 |302| `once` | 否 | 如果为 `true`，每个会话仅运行一次，然后被移除。仅在[skill frontmatter](#hooks-in-skills-and-agents)中声明的 hooks 中受尊重；在设置文件和代理 frontmatter 中被忽略 |

303 303 

558 558 

559命令 hooks 通过 stdin 接收 JSON 数据，并通过退出代码、stdout 和 stderr 传回结果。HTTP hooks 接收相同的 JSON 作为 POST 请求体，并通过 HTTP 响应体传回结果。本部分涵盖所有事件通用的字段和行为。每个事件在[Hook 事件](#hook-events)下的部分包括其特定的输入架构和决定控制选项。559命令 hooks 通过 stdin 接收 JSON 数据，并通过退出代码、stdout 和 stderr 传回结果。HTTP hooks 接收相同的 JSON 作为 POST 请求体，并通过 HTTP 响应体传回结果。本部分涵盖所有事件通用的字段和行为。每个事件在[Hook 事件](#hook-events)下的部分包括其特定的输入架构和决定控制选项。

560 560 

561从 v2.1.139 开始，在 macOS 和 Linux 上，命令 hooks 在没有控制终端的自己的会话中运行。hook 进程和任何子进程无法打开 `/dev/tty` 或直接向 Claude Code 界面发送转义序列。Windows 没有 `/dev/tty`。要在任何平台上向用户显示消息，请在 JSON 输出中返回[`systemMessage`](#json-output)。要触发桌面通知、设置窗口标题或响铃，请改为返回[`terminalSequence`](#emit-terminal-notifications)。

562 

561### 通用输入字段563### 通用输入字段

562 564 

563所有 hook 事件都接收这些字段作为 JSON，除了每个[hook 事件](#hook-events)部分中记录的事件特定字段。对于命令 hooks，此 JSON 通过 stdin 到达。对于 HTTP hooks，它作为 POST 请求体到达。565Hook 事件接收这些字段作为 JSON，除了每个[hook 事件](#hook-events)部分中记录的事件特定字段。对于命令 hooks，此 JSON 通过 stdin 到达。对于 HTTP hooks，它作为 POST 请求体到达。

564 566 

565| 字段 | 描述 |567| 字段 | 描述 |

566| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |568| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

685 687 

686您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的[JSON 验证失败](/zh-CN/hooks-guide#json-validation-failed)。688您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的[JSON 验证失败](/zh-CN/hooks-guide#json-validation-failed)。

687 689 

688Hook 输出注入到上下文中（`additionalContext`、`systemMessage` 或纯 stdout）的上限为 10,000 个字符。超过此限制的输出被保存到文件并替换为预览和文件路径，与大型工具结果的处理方式相同。690Hook 输出字符串，包括 `additionalContext`、`systemMessage` 和纯 stdout，上限为 10,000 个字符。超过此限制的输出被保存到文件并替换为预览和文件路径，与大型工具结果的处理方式相同。

689 691 

690JSON 对象支持三种字段：692JSON 对象支持三种字段：

691 693 

694* **`hookSpecificOutput`** 是一个嵌套对象，用于需要更丰富控制的事件。它需要一个设置为事件名称的 `hookEventName` 字段。696* **`hookSpecificOutput`** 是一个嵌套对象，用于需要更丰富控制的事件。它需要一个设置为事件名称的 `hookEventName` 字段。

695 697 

696| 字段 | 默认 | 描述 |698| 字段 | 默认 | 描述 |

697| :--------------- | :------ | :--------------------------------------------------- |699| :----------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------- |

698| `continue` | `true` | 如果为 `false`，Claude 在 hook 运行后完全停止处理。优先于任何事件特定的决定字段 |700| `continue` | `true` | 如果为 `false`，Claude 在 hook 运行后完全停止处理。优先于任何事件特定的决定字段 |

699| `stopReason` | 无 | hook 运行后 `continue` 为 `false` 时向用户显示的消息。不向 Claude 显示 |701| `stopReason` | 无 | 当 `continue` 为 `false` 时向用户显示的消息。不向 Claude 显示 |

700| `suppressOutput` | `false` | 如果为 `true`，从调试日志中隐藏 stdout |702| `suppressOutput` | `false` | 如果为 `true`，从调试日志中隐藏 stdout |

701| `systemMessage` | 无 | 向用户显示的警告消息 |703| `systemMessage` | 无 | 向用户显示的警告消息 |

704| `terminalSequence` | 无 | Claude Code 代表您发出的终端转义序列，例如桌面通知、窗口标题或响铃。限制为 OSC `0`/`1`/`2`/`9`/`99`/`777` 和 BEL。如果值包含允许列表之外的任何内容，该字段将被忽略。使用此而不是写入 `/dev/tty`，这对 hooks 不可用 |

702 705 

703要无论事件类型如何都完全停止 Claude：706要无论事件类型如何都完全停止 Claude：

704 707 

706{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }709{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

707```710```

708 711 

712#### 发出终端通知

713 

714`terminalSequence` 字段需要 Claude Code v2.1.141 或更高版本。

715 

716Hooks 运行时没有控制终端，因此直接向 `/dev/tty` 写入转义序列会失败。相反，在 `terminalSequence` 字段中返回转义序列，Claude Code 通过其自己的终端写入路径为您发出它。这是无竞争的，在 tmux 和 GNU screen 内工作，并在 Windows 上工作，其中没有 `/dev/tty`。

717 

718该字段接受一个或多个允许列表转义序列的字符串：

719 

720* OSC `0`、`1`、`2`：窗口和图标标题

721* OSC `9`：iTerm2、ConEmu、Windows Terminal 和 WezTerm 通知，包括 `9;4` 任务栏进度

722* OSC `99`：Kitty 通知

723* OSC `777`：urxvt、Ghostty 和 Warp 通知

724* 裸 BEL

725 

726序列可以用 BEL 或 ST 终止。允许列表之外的任何内容，包括 CSI 光标和颜色序列、OSC 调色板序列、OSC 8 超链接、OSC 52 剪贴板写入和 OSC 1337，都会被拒绝，该字段将被忽略。

727 

728下面的示例从 `Notification` hook 触发桌面通知。转义序列使用 `printf` 八进制转义构建，因此控制字节永远不会出现在 shell 命令行上，`jq -n --arg` 构建 JSON 输出，因此通知消息中的引号、反斜杠和换行符被正确转义：

729 

730```bash theme={null}

731#!/bin/bash

732# Notification hook：当 Claude Code 需要注意时 ping 桌面。

733input=$(cat)

734title="Claude Code'

735body=$(jq -r '.message // "Needs your attention"' <<<"$input")

736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

738```

739 

740`{ "terminalSequence": "..." }` 形状从任何 shell 或语言都相同。在 Windows 上，在 PowerShell 或脚本中构建转义字符串并发出相同的 JSON 对象。

741 

742<Note>

743 `terminalSequence` 是之前直接向 `/dev/tty` 写入转义序列的 hooks 的受支持替代品。允许列表限制为无法移动光标或改变颜色的序列，因此 hook 永远无法破坏屏幕上的提示。

744</Note>

745 

709#### 为 Claude 添加上下文746#### 为 Claude 添加上下文

710 747 

711`additionalContext` 字段将来自您的 hook 的字符串传递到 Claude 的上下文窗口中。Claude Code 将字符串包装在系统提醒中，并将其插入到 hook 触发的对话点。Claude 在下一个模型请求时读取提醒，但它不会在界面中显示为聊天消息。748`additionalContext` 字段将来自您的 hook 的字符串传递到 Claude 的上下文窗口中。Claude Code 将字符串包装在系统提醒中，并将其插入到 hook 触发的对话点。Claude 在下一个模型请求时读取提醒，但它不会在界面中显示为聊天消息。

989 1026 

990在用户提交提示时运行，在 Claude 处理之前。这允许您根据提示/对话添加额外上下文、验证提示或阻止某些类型的提示。1027在用户提交提示时运行，在 Claude 处理之前。这允许您根据提示/对话添加额外上下文、验证提示或阻止某些类型的提示。

991 1028 

1029`UserPromptSubmit` hooks 对 `command`、`http` 和 `mcp_tool` 类型的默认超时为 30 秒，比这些类型在其他事件上的 600 秒默认值更短。因为此 hook 在每个提示之前运行并阻止模型处理直到完成，卡住的 hook 会停滞会话。如果您的 hook 需要更多时间，在 hook 条目中设置 `timeout` 字段。

1030 

992#### UserPromptSubmit 输入1031#### UserPromptSubmit 输入

993 1032 

994除了[通用输入字段](#common-input-fields)外，UserPromptSubmit hooks 还接收包含用户提交的文本的 `prompt` 字段。1033除了[通用输入字段](#common-input-fields)外，UserPromptSubmit hooks 还接收包含用户提交的文本的 `prompt` 字段。

2596 2635 

2597当异步 hook 触发时，Claude Code 启动 hook 进程并立即继续，不等待其完成。Hook 通过 stdin 接收与同步 hook 相同的 JSON 输入。2636当异步 hook 触发时，Claude Code 启动 hook 进程并立即继续，不等待其完成。Hook 通过 stdin 接收与同步 hook 相同的 JSON 输入。

2598 2637 

2599后台进程退出后，如果 hook 产生了带有 `systemMessage` 或 `additionalContext` 字段的 JSON 响应，该内容在下一个对话轮次作为上下文传递给 Claude。2638后台进程退出后，如果 hook 产生了带有 `additionalContext` 字段的 JSON 响应，该内容在下一个对话轮次作为上下文传递给 Claude。`systemMessage` 字段显示给你，而不是 Claude。

2600 2639 

2601异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。2640异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。

2602 2641 

2617 exit 02656 exit 0

2618fi2657fi

2619 2658 

2620# 运行测试并通过 systemMessage 报告结果2659# 运行测试并通过 additionalContext 向 Claude 报告结果

2621RESULT=$(npm test 2>&1)2660RESULT=$(npm test 2>&1)

2622EXIT_CODE=$?2661EXIT_CODE=$?

2623 2662 

2624if [ $EXIT_CODE -eq 0 ]; then2663if [ $EXIT_CODE -eq 0 ]; then

2625 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"2664 MSG="Tests passed after editing $FILE_PATH"

2626else2665else

2627 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"2666 MSG="Tests failed after editing $FILE_PATH: $RESULT"

2628fi2667fi

2668jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

2629```2669```

2630 2670 

2631然后将此配置添加到项目根目录中的 `.claude/settings.json`。`async: true` 标志让 Claude 在测试运行时继续工作：2671然后将此配置添加到项目根目录中的 `.claude/settings.json`。`async: true` 标志让 Claude 在测试运行时继续工作：

865### 限制865### 限制

866 866 

867* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。867* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。

868* Hook 超时默认为 10 分钟，可通过 `timeout` 字段（以秒为单位）按 hook 配置。868* Hook 超时因类型而异。通过 `timeout` 字段（以秒为单位）按 hook 覆盖。

869 * `command`、`http`、`mcp_tool`：10 分钟。`UserPromptSubmit` 将这些降低到 30 秒。

870 * `prompt`：30 秒。

871 * `agent`：60 秒。

869* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。872* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。

870* `PermissionRequest` hooks 不在 [非交互模式](/zh-CN/headless)（`-p`）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。873* `PermissionRequest` hooks 不在 [非交互模式](/zh-CN/headless)（`-p`）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。

871* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/zh-CN/hooks#stopfailure) 代替。874* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/zh-CN/hooks#stopfailure) 代替。

458 458 

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

460 460 

461当服务器响应 `401 Unauthorized` 和指向其授权服务器的 `WWW-Authenticate` 标头时，Claude Code 将远程服务器标记为需要身份验证。任何返回该响应的自定义服务器都会获得与任何其他远程服务器相同的 `/mcp` 身份验证流程。461当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时，Claude Code 将远程服务器标记为需要身份验证。任一状态代码都会在 `/mcp` 中标记该服务器，以便您可以完成 OAuth 流程。返回指向其授权服务器的 `WWW-Authenticate` 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。

462 462 

463<Steps>463<Steps>

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

51 可用标志：51 可用标志：

52 52 

53 | 标志 | 描述 |53 | 标志 | 描述 |

54 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |54 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

55 | `--name "My Project"` | 设置自定义会话标题，在 claude.ai/code 的会话列表中可见。 |55 | `--name "My Project"` | 设置自定义会话标题，在 claude.ai/code 的会话列表中可见。 |

56 | `--remote-control-session-name-prefix <prefix>` | 未设置显式名称时自动生成的会话名称的前缀。默认为您的机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果。 |56 | `--remote-control-session-name-prefix <prefix>` | 未设置显式名称时自动生成的会话名称的前缀。默认为您的机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果。 |

57 | `--spawn <mode>` | 服务器如何创建会话。<br />• `same-dir`（默认）：所有会话共享当前工作目录，因此如果编辑相同的文件可能会冲突。<br />• `worktree`：每个按需会话都获得自己的 [git worktree](/zh-CN/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)。需要 git 存储库。<br />• `session`：单会话模式。恰好提供一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |57 | `--spawn <mode>` | 服务器如何创建会话。<br />• `same-dir`（默认）：所有会话共享当前工作目录，因此如果编辑相同的文件可能会冲突。<br />• `worktree`：每个按需会话都获得自己的 [git worktree](/zh-CN/worktrees)。需要 git 存储库。<br />• `session`：单会话模式。恰好提供一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |

58 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |58 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |

59 | `--verbose` | 显示详细的连接和会话日志。 |59 | `--verbose` | 显示详细的连接和会话日志。 |

60 | `--sandbox` / `--no-sandbox` | 启用或禁用[沙箱](/zh-CN/sandboxing)以进行文件系统和网络隔离。默认关闭。 |60 | `--sandbox` / `--no-sandbox` | 启用或禁用[沙箱](/zh-CN/sandboxing)以进行文件系统和网络隔离。默认关闭。 |

113 113 

114* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。114* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。

115* **扫描 QR 码** 显示在会话 URL 旁边，直接在 Claude 应用中打开它。使用 `claude remote-control` 时，按空格键切换 QR 码显示。115* **扫描 QR 码** 显示在会话 URL 旁边，直接在 Claude 应用中打开它。使用 `claude remote-control` 时，按空格键切换 QR 码显示。

116* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称查找会话。Remote Control 会话在在线时显示带有绿色状态点的计算机图标。116* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称查找会话。在 Claude 移动应用中，点击导航中的**代码**以访问会话列表。Remote Control 会话在在线时显示带有绿色状态点的计算机图标。

117 117 

118远程会话标题按以下顺序选择：118远程会话标题按以下顺序选择：

119 119 

130 130 

131### 为所有会话启用 Remote Control131### 为所有会话启用 Remote Control

132 132 

133默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置回 `false` 以禁用。133默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置回 `false` 以禁用。在桌面应用中，您也可以从**设置 → Claude Code → 默认启用远程控制**切换此选项。

134 134 

135启用此设置后，每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例，每个实例都获得自己的环境和会话。要从单个进程运行多个并发会话，请改用[服务器模式](#start-a-remote-control-session)。135启用此设置后，每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例，每个实例都获得自己的环境和会话。要从单个进程运行多个并发会话，请改用[服务器模式](#start-a-remote-control-session)。

136 136 

215 215 

216### "Remote Control 被您的组织的策略禁用"216### "Remote Control 被您的组织的策略禁用"

217 217 

218此错误有三个不同的原因。首先运行 `/status` 以查看您使用的登录方法和订阅。218此错误有四个不同的原因。首先运行 `/status` 以查看您使用的登录方法和订阅。

219 219 

220* **您使用 API 密钥或 Console 账户进行身份验证**：Remote Control 需要 claude.ai OAuth。运行 `/login` 并选择 claude.ai 选项。如果在您的环境中设置了 `ANTHROPIC_API_KEY`，请取消设置它。220* **您使用 API 密钥或 Console 账户进行身份验证**：Remote Control 需要 claude.ai OAuth。运行 `/login` 并选择 claude.ai 选项。如果在您的环境中设置了 `ANTHROPIC_API_KEY`，请取消设置它。

221* **您的 Team 或 Enterprise 管理员尚未启用它**：Remote Control 在这些计划上默认处于关闭状态。管理员可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。这是一个服务器端组织设置，不是[仅管理设置](/zh-CN/permissions#managed-only-settings)密钥。221* **您的 Team 或 Enterprise 管理员尚未启用它**：Remote Control 在这些计划上默认处于关闭状态。管理员可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。

222* **管理员切换呈灰色**：您的组织有数据保留或合规配置与 Remote Control 不兼容。这无法从管理面板更改。请联系 Anthropic 支持以讨论选项。222* **管理员切换呈灰色**：您的组织有数据保留或合规配置与 Remote Control 不兼容。这无法从管理面板更改。请联系 Anthropic 支持以讨论选项。

223* **错误提及 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/zh-CN/settings#settings-files)在此设备上禁用了 Remote Control，独立于组织范围的切换。

223 224 

224### "Remote credentials fetch failed"225### "Remote credentials fetch failed"

225 226 

158 158 

159这是创建和管理 subagents 的推荐方式。对于手动创建或自动化，您也可以直接添加 subagent 文件。159这是创建和管理 subagents 的推荐方式。对于手动创建或自动化，您也可以直接添加 subagent 文件。

160 160 

161要从命令行列出所有配置的 subagents 而不打开 [agent view](/zh-CN/agent-view)，请使用管道输出 `claude agents`。例如，`claude agents | cat` 打印按来源分组的代理，并指示哪些被更高优先级的定义覆盖。

162 

163### 选择 subagent 范围161### 选择 subagent 范围

164 162 

165Subagents 是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。当多个 subagents 共享相同的名称时，更高优先级的位置获胜。163Subagents 是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。当多个 subagents 共享相同的名称时，更高优先级的位置获胜。

178 176 

179**用户 subagents**（`~/.claude/agents/`）是在所有项目中可用的个人 subagents。177**用户 subagents**（`~/.claude/agents/`）是在所有项目中可用的个人 subagents。

180 178 

179Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。在整个树中保持 `name` 值唯一：如果一个范围内的两个文件声明相同的名称，Claude Code 会保留一个并丢弃另一个而不发出警告。

180 

181Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。

182 

181**CLI 定义的 subagents** 在启动 Claude Code 时作为 JSON 传递。它们仅存在于该会话中，不会保存到磁盘，使其对快速测试或自动化脚本很有用。您可以在单个 `--agents` 调用中定义多个 subagents：183**CLI 定义的 subagents** 在启动 Claude Code 时作为 JSON 传递。它们仅存在于该会话中，不会保存到磁盘，使其对快速测试或自动化脚本很有用。您可以在单个 `--agents` 调用中定义多个 subagents：

182 184 

183<Tabs>185<Tabs>

638 640 

639您的完整消息仍然发送给 Claude，它根据您的要求为 subagent 编写任务提示。@-mention 控制调用哪个 subagent，而不是它接收什么提示。641您的完整消息仍然发送给 Claude，它根据您的要求为 subagent 编写任务提示。@-mention 控制调用哪个 subagent，而不是它接收什么提示。

640 642 

641由启用的 [plugin](/zh-CN/plugins) 提供的 Subagents 在类型提前中显示为 `<plugin-name>:<agent-name>`。命名背景 subagents 当前在会话中运行也出现在类型提前中，在名称旁边显示其状态。您也可以手动输入提及而不使用选择器：`@agent-<name>` 用于本地 subagents，或 `@agent-<plugin-name>:<agent-name>` 用于 plugin subagents。643由启用的 [plugin](/zh-CN/plugins) 提供的 Subagents 在类型提前中显示为其作用域名称，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`，当 plugin [将 agents 组织到子文件夹中](#choose-the-subagent-scope)。命名背景 subagents 当前在会话中运行也出现在类型提前中，在名称旁边显示其状态。您也可以手动输入提及而不使用选择器：`@agent-<name>` 用于本地 subagents，或 `@agent-` 后跟 plugin subagents 的作用域名称，例如 `@agent-my-plugin:code-reviewer`。

642 644 

643**将整个会话作为 subagent 运行。** 传递 [`--agent <name>`](/zh-CN/cli-reference) 以启动一个会话，其中主线程本身采用该 subagent 的系统提示、工具限制和模型：645**将整个会话作为 subagent 运行。** 传递 [`--agent <name>`](/zh-CN/cli-reference) 以启动一个会话，其中主线程本身采用该 subagent 的系统提示、工具限制和模型：

644 646 

650 652 

651这适用于内置和自定义 subagents，当您恢复会话时选择会持续。653这适用于内置和自定义 subagents，当您恢复会话时选择会持续。

652 654 

653对于 plugin 提供的 subagent，传递作用域名称：`claude --agent <plugin-name>:<agent-name>`。655对于 plugin 提供的 subagent，传递作用域名称：`claude --agent <plugin-name>:<agent-name>`。如果 plugin 将 agent 放在其 `agents/` 目录的子文件夹中，请在作用域名称中包含子文件夹，例如 `claude --agent my-plugin:review:security`。

654 656 

655要使其成为项目中每个会话的默认值，在 `.claude/settings.json` 中设置 `agent`：657要使其成为项目中每个会话的默认值，在 `.claude/settings.json` 中设置 `agent`：

656 658 

16 16 

17语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/zh-CN/data-usage)。17语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/zh-CN/data-usage)。

18 18 

19语音听写还需要本地麦克风访问权限，因此在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 或 SSH 会话。在 WSL 中，语音听写需要 WSLg 来访问音频，这包含在 Windows 11 上的 WSL2 中。在 Windows 10 或 WSL1 上，改为在本机 Windows 中运行 Claude Code。19语音听写还需要本地麦克风访问权限，因此在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 或 SSH 会话。在 WSL 中，语音听写需要 WSLg 来访问音频。WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。

20 20 

21音频录制在 macOS、Linux 和 Windows 上使用内置的本机模块。在 Linux 上，如果本机模块无法加载，Claude Code 会回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果两者都不可用，`/voice` 会打印你的包管理器的安装命令。21音频录制在 macOS、Linux 和 Windows 上使用内置的本机模块。在 Linux 上，如果本机模块无法加载，Claude Code 会回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果两者都不可用，`/voice` 会打印你的包管理器的安装命令。

22 22 

51}51}

52```52```

53 53 

54启用语音听写时，当提示词为空时，输入页脚会显示 `hold Space to speak` 提示。提示文本在两种模式中都相同，如果你配置了[自定义状态行](/zh-CN/statusline)，则不会显示。54启用语音听写时，当提示词为空时，输入页脚会显示 `hold Space to speak` 提示。提示文本反映你当前的 `voice:pushToTalk` 快捷键绑定，如果你[重新绑定听写键](#rebind-the-dictation-key)，它会更新。提示文本在两种模式中都相同，如果你配置了[自定义状态行](/zh-CN/statusline)，则不会显示。

55 55 

56转录在两种模式中都针对编码词汇进行了调整。常见的开发术语如 `regex`、`OAuth`、`JSON` 和 `localhost` 被正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。56转录在两种模式中都针对编码词汇进行了调整。常见的开发术语如 `regex`、`OAuth`、`JSON` 和 `localhost` 被正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。

57 57 

155* **`Voice mode requires a Claude.ai account`**：你使用 API 密钥或第三方提供商进行了身份验证。运行 `/login` 以使用 Claude.ai 账户登录。155* **`Voice mode requires a Claude.ai account`**：你使用 API 密钥或第三方提供商进行了身份验证。运行 `/login` 以使用 Claude.ai 账户登录。

156* **`Microphone access is denied`**：在系统设置中授予你的终端麦克风权限。在 macOS 上，转到系统设置 → 隐私和安全 → 麦克风并启用你的终端应用，然后再次运行 `/voice`。在 Windows 上，转到设置 → 隐私和安全 → 麦克风并为桌面应用打开麦克风访问，然后再次运行 `/voice`。如果你的终端未在 macOS 设置中列出，请参阅[终端未在 macOS 麦克风设置中列出](#terminal-not-listed-in-macos-microphone-settings)。156* **`Microphone access is denied`**：在系统设置中授予你的终端麦克风权限。在 macOS 上，转到系统设置 → 隐私和安全 → 麦克风并启用你的终端应用，然后再次运行 `/voice`。在 Windows 上，转到设置 → 隐私和安全 → 麦克风并为桌面应用打开麦克风访问，然后再次运行 `/voice`。如果你的终端未在 macOS 设置中列出，请参阅[终端未在 macOS 麦克风设置中列出](#terminal-not-listed-in-macos-microphone-settings)。

157* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。157* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。

158* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。

159* **`Voice input is failing repeatedly and has been paused`**：语音听写连续遇到多个启动失败，并停止尝试新会话，直到一个成功。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。

158* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。160* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。

159* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。161* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。

160* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。162* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。