Documentation — Spybara

agent-sdk/agent-loop.md +10 −10

Details

111SDK 包含与 Claude Code 相同的工具：111SDK 包含与 Claude Code 相同的工具：

112 112

113| 类别 | 工具 | 它们做什么 |113| 类别 | 工具 | 它们做什么 |

114| :------- | :-------------------------------------------- | :--------------------- |114| :------- | :---------------------------------------------------------- | :--------------------- |

116| **搜索** | `Glob`、`Grep` | 按模式查找文件，使用正则表达式搜索内容 |116| **搜索** | `Glob`、`Grep` | 按模式查找文件，使用正则表达式搜索内容 |

117| **执行** | `Bash` | 运行 shell 命令、脚本、git 操作 |117| **执行** | `Bash` | 运行 shell 命令、脚本、git 操作 |

118| **Web** | `WebSearch`、`WebFetch` | 搜索网络、获取和解析页面 |118| **Web** | `WebSearch`、`WebFetch` | 搜索网络、获取和解析页面 |

119| **发现** | `ToolSearch` | 动态查找和按需加载工具，而不是预加载所有工具 |119| **发现** | `ToolSearch` | 动态查找和按需加载工具，而不是预加载所有工具 |

120| **编排** | `Agent`、`Skill`、`AskUserQuestion`、`TodoWrite` | 生成子代理、调用技能、询问用户、跟踪任务 |120| **编排** | `Agent`、`Skill`、`AskUserQuestion`、`TaskCreate`、`TaskUpdate` | 生成子代理、调用技能、询问用户、跟踪任务 |

121 121

122除了内置工具，你还可以：122除了内置工具，你还可以：

123 123

197 197

198## 上下文窗口198## 上下文窗口

199 199

200上下文窗口是会话期间可用于 Claude 的信息总量。它在会话内的轮次之间不重置。一切都累积：系统提示、工具定义、对话历史、工具输入和工具输出。在轮次之间保持相同的内容（系统提示、工具定义、CLAUDE.md）自动 [提示缓存](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)，这减少了重复前缀的成本和延迟。200上下文窗口是会话期间可用于 Claude 的信息总量。它在会话内的轮次之间不重置。一切都累积：系统提示、工具定义、对话历史、工具输入和工具输出。在轮次之间保持相同的内容（系统提示、工具定义、CLAUDE.md）自动进行[提示缓存](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-caching)，这减少了重复前缀的成本和延迟。

201 201

202### 什么消耗上下文202### 什么消耗上下文

203 203

204以下是每个组件如何影响 SDK 中上下文的方式：204以下是每个组件如何影响 SDK 中上下文的方式：

205 205

206| 源 | 何时加载 | 影响 |206| 源 | 何时加载 | 影响 |

207| :--------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------- |207| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

213 213

243 243

244对于长时间运行的代理的几个策略：244对于长时间运行的代理的几个策略：

245 245

246* **为子任务使用子代理。** 每个子代理以新鲜对话开始（没有先前的消息历史，尽管它确实加载自己的系统提示和项目级上下文，如 CLAUDE.md）。它看不到父级的轮次，只有其最终响应作为工具结果返回给父级。主代理的上下文增长该摘要，而不是完整的子任务成绩单。有关详情，请参阅 [子代理继承什么](/zh-CN/agent-sdk/subagents#what-subagents-inherit)。246* **为子任务使用子代理。** 每个子代理以新鲜对话开始（没有先前的消息历史，尽管它确实加载自己的系统提示和项目级上下文，如 CLAUDE.md）。它看不到父级的轮次，只有其最终响应作为工具结果返回给父级。主代理的上下文增长该摘要，而不是完整的子任务成绩单。有关详情，请参阅[子代理继承什么](/zh-CN/agent-sdk/subagents#what-subagents-inherit)。

247* **对工具有选择性。** 每个工具定义占用上下文空间。在 [`AgentDefinition`](/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 字段将子代理限制在它们需要的最小集合，并使用 [MCP 工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search) 按需加载工具而不是预加载所有工具。247* **对工具有选择性。** 每个工具定义占用上下文空间。在 [`AgentDefinition`](/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 字段将子代理限制在它们需要的最小集合。

248* **监视 MCP 服务器成本。** 每个 MCP 服务器将其所有工具架构添加到每个请求。具有许多工具的几个服务器可以在代理执行任何工作之前消耗大量上下文。`ToolSearch` 工具可以通过按需加载工具而不是预加载所有工具来帮助。有关配置，请参阅 [MCP 工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)。248* **监视 MCP 服务器成本。** [MCP 工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)默认延迟 MCP 工具架构，并按需加载它们。当工具搜索关闭、在 Vertex AI 上或在非第一方 `ANTHROPIC_BASE_URL` 后面时，每个 MCP 服务器将其所有工具架构添加到每个请求，因此具有许多工具的几个服务器可以在代理执行任何工作之前消耗大量上下文。

249* **对常规任务使用较低的努力。** 为仅需要读取文件或列出目录的代理设置 [努力](#effort-level) 为 `"low"`。这减少了令牌使用和成本。249* **对常规任务使用较低的努力。** 为仅需要读取文件或列出目录的代理设置[努力](#effort-level)为 `"low"`。这减少了令牌使用和成本。

250 250

251有关每个功能上下文成本的详细分解，请参阅 [理解上下文成本](/zh-CN/features-overview#understand-context-costs)。251有关每个功能上下文成本的详细分解，请参阅[理解上下文成本](/zh-CN/features-overview#understand-context-costs)。

252 252

253## 会话和连续性253## 会话和连续性

254 254

agent-sdk/python.md +36 −15

Details

19### 快速比较19### 快速比较

20 20

21| 功能 | `query()` | `ClaudeSDKClient` |21| 功能 | `query()` | `ClaudeSDKClient` |

~~22| :-------- | :-------- | :---------------- |~~22| :-------- | :----------------------------------------- | :---------------- |

~~23| **会话** | 每次创建新会话 | 重用同一会话 |~~23| **会话** | 默认创建新会话 | 重用同一会话 |

24| **对话** | 单次交换 | 同一上下文中的多次交换 |24| **对话** | 单次交换 | 同一上下文中的多次交换 |

25| **连接** | 自动管理 | 手动控制 |25| **连接** | 自动管理 | 手动控制 |

26| **流式输入** | ✅ 支持 | ✅ 支持 |26| **流式输入** | ✅ 支持 | ✅ 支持 |

27| **中断** | ❌ 不支持 | ✅ 支持 |27| **中断** | ❌ 不支持 | ✅ 支持 |

28| **hooks** | ✅ 支持 | ✅ 支持 |28| **hooks** | ✅ 支持 | ✅ 支持 |

29| **自定义工具** | ✅ 支持 | ✅ 支持 |29| **自定义工具** | ✅ 支持 | ✅ 支持 |

31| **用例** | 一次性任务 | 持续对话 |31| **用例** | 一次性任务 | 持续对话 |

32 32

~~33### 何时使用 `query()`（每次新会话）~~33### 何时使用 `query()`（一次性任务）

34 34

35**最适合：**35**最适合：**

36 36

53 53

54### `query()`54### `query()`

55 55

~~56为每次与 Claude Code 的交互创建一个新会话。返回一个异步迭代器，当消息到达时产生消息。每次调用 `query()` 都会重新开始，不记得之前的交互。~~56为每次与 Claude Code 的交互创建一个新会话。默认情况下返回一个异步迭代器，当消息到达时产生消息。每次调用 `query()` 都会重新开始，不记得之前的交互，除非你传递 `continue_conversation=True` 或在 [`ClaudeAgentOptions`](#claudeagentoptions) 中传递 `resume`。参见 [Sessions](/zh-CN/agent-sdk/sessions)。

57 57

58```python theme={null}58```python theme={null}

59async def query(59async def query(

157 157

158#### `ToolAnnotations`158#### `ToolAnnotations`

159 159

160从 `mcp.types` 重新导出（也可以从 `claude_agent_sdk` 导入）。所有字段都是可选的提示；客户端不应依赖它们做出安全决策。160从 `mcp.types` 重新导出（也可以从 `claude_agent_sdk` 导入为 `from claude_agent_sdk import ToolAnnotations`）。所有字段都是可选的提示；客户端不应依赖它们做出安全决策。

161 161

162| 字段 | 类型 | 默认值 | 描述 |162| 字段 | 类型 | 默认值 | 描述 |

163| :---------------- | :------------- | :------ | :------------------------------------------------------------- |163| :---------------- | :------------- | :------ | :------------------------------------------------------------- |

790 plugins: list[SdkPluginConfig] = field(default_factory=list)790 plugins: list[SdkPluginConfig] = field(default_factory=list)

791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

792 thinking: ThinkingConfig | None = None792 thinking: ThinkingConfig | None = None

793 effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None793 effort: EffortLevel | None = None

794 enable_file_checkpointing: bool = False794 enable_file_checkpointing: bool = False

795 session_store: SessionStore | None = None795 session_store: SessionStore | None = None

796 session_store_flush: SessionStoreFlushMode = "batched"796 session_store_flush: SessionStoreFlushMode = "batched"

843 843

1039 initialPrompt: str | None = None1039 initialPrompt: str | None = None

1040 maxTurns: int | None = None1040 maxTurns: int | None = None

1041 background: bool | None = None1041 background: bool | None = None

1042 effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None1042 effort: EffortLevel | int | None = None

1043 permissionMode: PermissionMode | None = None1043 permissionMode: PermissionMode | None = None

1044```1044```

1045 1045

1056| `initialPrompt` | 否 | 当此代理作为主线程代理运行时自动提交为第一个用户轮次 |1056| `initialPrompt` | 否 | 当此代理作为主线程代理运行时自动提交为第一个用户轮次 |

1057| `maxTurns` | 否 | 代理停止前的最大代理轮次数 |1057| `maxTurns` | 否 | 代理停止前的最大代理轮次数 |

1058| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |1058| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |

1059| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |1059| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数。见 [`EffortLevel`](#effortlevel) |

1060| `permissionMode` | 否 | 此代理内工具执行的权限模式。见 [`PermissionMode`](#permissionmode) |1060| `permissionMode` | 否 | 此代理内工具执行的权限模式。见 [`PermissionMode`](#permissionmode) |

1061 1061

1062<Note>1062<Note>

1077]1077]

1078```1078```

1079 1079

1080### `EffortLevel`

1081

1082用于指导思考深度的努力级别。

1083

1084```python theme={null}

1085EffortLevel = Literal[

1086 "low", # Minimal thinking, fastest responses

1087 "medium", # Moderate thinking

1088 "high", # Deep reasoning

1089 "xhigh", # Extended reasoning (Opus 4.7 only; falls back to "high" on other models)

1090 "max", # Maximum effort

1091]

1092```

1093

1080### `CanUseTool`1094### `CanUseTool`

1081 1095

1082工具权限回调函数的类型别名。1096工具权限回调函数的类型别名。

1224控制扩展思考行为。三种配置的联合：1238控制扩展思考行为。三种配置的联合：

1225 1239

1226```python theme={null}1240```python theme={null}

1241ThinkingDisplay = Literal["summarized", "omitted"]

1242

1243

1227class ThinkingConfigAdaptive(TypedDict):1244class ThinkingConfigAdaptive(TypedDict):

1228 type: Literal["adaptive"]1245 type: Literal["adaptive"]

1246 display: NotRequired[ThinkingDisplay]

1229 1247

1230 1248

1231class ThinkingConfigEnabled(TypedDict):1249class ThinkingConfigEnabled(TypedDict):

1232 type: Literal["enabled"]1250 type: Literal["enabled"]

1233 budget_tokens: int1251 budget_tokens: int

1252 display: NotRequired[ThinkingDisplay]

1234 1253

1235 1254

1236class ThinkingConfigDisabled(TypedDict):1255class ThinkingConfigDisabled(TypedDict):

1241```1260```

1242 1261

1243| 变体 | 字段 | 描述 |1262| 变体 | 字段 | 描述 |

1244| :--------- | :---------------------- | :--------------- |1263| :--------- | :--------------------------------- | :--------------- |

1248 1267

1268可选的 `display` 字段控制思考文本是否返回为 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 输出中接收思考内容。

1269

1249因为这些是 `TypedDict` 类，它们在运行时是普通字典。要么将它们构造为字典字面量，要么调用类作为构造函数；两者都产生 `dict`。使用 `config["budget_tokens"]` 访问字段，而不是 `config.budget_tokens`：1270因为这些是 `TypedDict` 类，它们在运行时是普通字典。要么将它们构造为字典字面量，要么调用类作为构造函数；两者都产生 `dict`。使用 `config["budget_tokens"]` 访问字段，而不是 `config.budget_tokens`：

1250 1271

1251```python theme={null}1272```python theme={null}

2177 hookEventName: Literal["PostToolUse"]2198 hookEventName: Literal["PostToolUse"]

2178 additionalContext: NotRequired[str]2199 additionalContext: NotRequired[str]

2179 updatedToolOutput: NotRequired[Any]2200 updatedToolOutput: NotRequired[Any]

2180 updatedMCPToolOutput: NotRequired[Any]2201 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools

2181 2202

2182 2203

2183class PostToolUseFailureHookSpecificOutput(TypedDict):2204class PostToolUseFailureHookSpecificOutput(TypedDict):

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

2647 2668

2648<Note>2669<Note>

2649 `TodoWrite` 已弃用，将在未来版本中删除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。设置 `CLAUDE_CODE_ENABLE_TASKS=1` 以选择加入。见 [迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools) 了解如何监视代码更改。2670 自 Claude Code v2.1.142 起，`TodoWrite` 默认被禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。见 [迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools) 更新您的监视代码，或设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢复到 `TodoWrite`。

2650</Note>2671</Note>

2651 2672

2652**输入：**2673**输入：**

agent-sdk/sessions.md +3 −3

Details

46 46

47### Python：`ClaudeSDKClient`47### Python：`ClaudeSDKClient`

48 48

49[`ClaudeSDKClient`](/zh-CN/agent-sdk/python#claudesdkclient) 在内部处理会话 ID。每次调用 `client.query()` 都会自动继续同一会话。调用 [`client.receive_response()`](/zh-CN/agent-sdk/python#claudesdkclient) 以迭代当前查询的消息。客户端必须用作异步上下文管理器。49[`ClaudeSDKClient`](/zh-CN/agent-sdk/python#claudesdkclient) 在内部处理会话 ID。每次调用 `client.query()` 都会自动继续同一会话。调用 [`client.receive_response()`](/zh-CN/agent-sdk/python#claudesdkclient) 以迭代当前查询的消息。客户端通常用作异步上下文管理器。

50 50

51此示例针对同一 `client` 运行两个查询。第一个要求代理分析一个模块；第二个要求它重构该模块。因为两个调用都通过同一客户端实例进行，第二个查询具有来自第一个查询的完整上下文，无需任何显式 `resume` 或会话 ID：51此示例针对同一 `client` 运行两个查询。第一个要求代理分析一个模块；第二个要求它重构该模块。因为两个调用都通过同一客户端实例进行，第二个查询具有来自第一个查询的完整上下文，无需任何显式 `resume` 或会话 ID：

52 52

100 100

101### TypeScript：`continue: true`101### TypeScript：`continue: true`

102 102

103稳定的 TypeScript SDK（整个文档中使用的 `query()` 函数，有时称为 V1）没有像 Python 的 `ClaudeSDKClient` 那样的会话保持客户端对象。相反，在每个后续 `query()` 调用上传递 `continue: true`，SDK 会在当前目录中选择最近的会话。无需 ID 跟踪。103TypeScript SDK 没有像 Python 的 `ClaudeSDKClient` 那样的会话保持客户端对象。相反，在每个后续 `query()` 调用上传递 `continue: true`，SDK 会在当前目录中选择最近的会话。无需 ID 跟踪。

104 104

105此示例进行两个单独的 `query()` 调用。第一个创建一个新会话；第二个设置 `continue: true`，这告诉 SDK 在磁盘上查找并恢复最近的会话。代理具有来自第一个调用的完整上下文：105此示例进行两个单独的 `query()` 调用。第一个创建一个新会话；第二个设置 `continue: true`，这告诉 SDK 在磁盘上查找并恢复最近的会话。代理具有来自第一个调用的完整上下文：

106 106

132```132```

133 133

134<Note>134<Note>

135 实验性的 [V2 会话 API](/zh-CN/agent-sdk/typescript-v2-preview)（提供了带有 `send` / `stream` 模式的 `createSession()`）已弃用。使用 V1 `query()` 函数和本页面上描述的会话选项。135 实验性的 [V2 会话 API](/zh-CN/agent-sdk/typescript-v2-preview)（提供了带有 `send` / `stream` 模式的 `createSession()`）已在 TypeScript Agent SDK 0.3.142 中移除。使用 `query()` 函数和本页面上描述的会话选项。

136</Note>136</Note>

137 137

138## 将会话选项与 `query()` 一起使用138## 将会话选项与 `query()` 一起使用

agent-sdk/todo-tracking.md +69 −4

Details

8 8

9待办事项跟踪提供了一种结构化的方式来管理任务并向用户显示进度。Claude Agent SDK 包含内置的待办事项功能，可帮助组织复杂的工作流程并让用户了解任务进度。9待办事项跟踪提供了一种结构化的方式来管理任务并向用户显示进度。Claude Agent SDK 包含内置的待办事项功能，可帮助组织复杂的工作流程并让用户了解任务进度。

10 10

11<Note>

12 截至 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142，会话使用结构化的 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`，而不是 `TodoWrite`。请参阅[迁移到 Task 工具](#migrate-to-task-tools)了解监控代码如何变化。本页面上的示例设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以继续为尚未迁移的会话显示 `TodoWrite`。

13</Note>

11### 待办事项生命周期15### 待办事项生命周期

12 16

13待办事项遵循可预测的生命周期：17待办事项遵循可预测的生命周期：

36 40

37 for await (const message of query({41 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",42 prompt: "Optimize my React app performance and track progress with todos",

~~39 options: { maxTurns: 15 }~~43 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

44 // Task tools instead and these tool_use blocks never appear.

45 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

40 })) {46 })) {

41 // Todo updates are reflected in the message stream47 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {48 if (message.type === "assistant") {

61 67

62 async for message in query(68 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",69 prompt="Optimize my React app performance and track progress with todos",

~~64 options=ClaudeAgentOptions(max_turns=15),~~70 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

71 # Task tools instead and these tool_use blocks never appear.

72 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

65 ):73 ):

66 # Todo updates are reflected in the message stream74 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):75 if isinstance(message, AssistantMessage):

112 async trackQuery(prompt: string) {120 async trackQuery(prompt: string) {

113 for await (const message of query({121 for await (const message of query({

114 prompt,122 prompt,

115 options: { maxTurns: 20 }123 // Re-enable TodoWrite, which this tracker watches for.

124 options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

116 })) {125 })) {

117 if (message.type === "assistant") {126 if (message.type === "assistant") {

118 for (const block of message.message.content) {127 for (const block of message.message.content) {

167 print(f"{i + 1}. {icon} {text}")176 print(f"{i + 1}. {icon} {text}")

168 177

169 async def track_query(self, prompt: str):178 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):179 async for message in query(

180 prompt=prompt,

181 # Re-enable TodoWrite, which this tracker watches for.

182 options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

183 ):

171 if isinstance(message, AssistantMessage):184 if isinstance(message, AssistantMessage):

172 for block in message.content:185 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":186 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

181 ```194 ```

182</CodeGroup>195</CodeGroup>

183 196

197## 迁移到 Task 工具

198

199Task 工具将单个 `TodoWrite` 调用分为 `TaskCreate`（用于每个新项目）和 `TaskUpdate`（用于每个状态更改），`TaskList` 和 `TaskGet` 可供模型读取当前列表。您的监控代码仍然检查助手流中的 `tool_use` 块，但维护一个由任务 ID 键入的映射，而不是在每次调用时替换整个列表。{/* min-version: 2.1.142 */}Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 的默认工具，因此不需要更改 `options.env`。

200

201| 使用 `TodoWrite` | 使用 Task 工具 |

202| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

203| 一个工具调用重写完整的 `todos` 数组 | `TaskCreate` 添加一个项目，`TaskUpdate` 按 `taskId` 修补一个项目 |

204| 匹配 `block.name === "TodoWrite"` | 匹配 `block.name === "TaskCreate"` 或 `"TaskUpdate"` |

205| 项目形状：`{ content, status, activeForm }` | `TaskCreate` 输入：`{ subject, description, activeForm?, metadata? }`。`TaskUpdate` 输入：`{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`。`status` 是 `"pending"`、`"in_progress"` 或 `"completed"`；设置 `status: "deleted"` 以删除 |

206| 直接渲染 `block.input.todos` | 跨调用累积项目，或从 `TaskList` 工具结果读取快照 |

207

208分配的任务 ID 不在 `TaskCreate` 输入中。它在匹配的 `tool_result` 中返回为 `{ task: { id, subject } }`，因此从结果块捕获它以键入您的映射。以下示例显示了对[监控待办事项变化](#monitoring-todo-changes)循环的最小更改。要渲染完整列表，请在流中监视 `TaskList` 工具结果或将 `TaskCreate` 结果和 `TaskUpdate` 输入累积到映射中：

209

210<CodeGroup>

211 ```typescript TypeScript theme={null}

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

213

214 for await (const message of query({

215 prompt: "Optimize my React app performance",

216 })) {

217 if (message.type !== "assistant") continue;

218 for (const block of message.message.content) {

219 if (block.type !== "tool_use") continue;

220 if (block.name === "TaskCreate") {

221 const input = block.input as { subject: string };

222 console.log(`+ ${input.subject}`);

223 } else if (block.name === "TaskUpdate") {

224 const input = block.input as { taskId: string; status?: string };

225 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);

226 }

227 }

228 }

229 ```

230

231 ```python Python theme={null}

232 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock

233

234 async for message in query(

235 prompt="Optimize my React app performance",

236 ):

237 if not isinstance(message, AssistantMessage):

238 continue

239 for block in message.content:

240 if not isinstance(block, ToolUseBlock):

241 continue

242 if block.name == "TaskCreate":

243 print(f"+ {block.input['subject']}")

244 elif block.name == "TaskUpdate" and block.input.get("status"):

245 print(f" {block.input['taskId']} -> {block.input['status']}")

246 ```

247</CodeGroup>

248

184## 相关文档249## 相关文档

185 250

186* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript)251* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript)

agent-sdk/typescript.md +11 −7

Details

418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获取自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话上下文移到第一条用户消息中，以便[更好地跨机器重用提示缓存](/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获取自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话上下文移到第一条用户消息中，以便[更好地跨机器重用提示缓存](/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

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

1847创建和管理结构化任务列表以跟踪进度。1847创建和管理结构化任务列表以跟踪进度。

1848 1848

1849<Note>1849<Note>

1850 `TodoWrite` 已弃用，将在未来版本中删除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。设置 `CLAUDE_CODE_ENABLE_TASKS=1` 以选择加入。请参阅[迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)了解如何监视代码更改。1850 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 默认被禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。请参阅[迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的监视代码，或设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢复为 `TodoWrite`。

1851</Note>1851</Note>

1852 1852

1853### TaskCreate1853### TaskCreate

2344返回之前和更新的任务列表。2344返回之前和更新的任务列表。

2345 2345

2346<Note>2346<Note>

2347 `TodoWrite` 已弃用，将在未来版本中删除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。设置 `CLAUDE_CODE_ENABLE_TASKS=1` 以选择加入。请参阅[迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)了解如何监视代码更改。2347 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 默认被禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。请参阅[迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)更新您的监视代码，或设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢复为 `TodoWrite`。

2348</Note>2348</Note>

2349 2349

2350### TaskCreate2350### TaskCreate

2739控制 Claude 的思考/推理行为。优先于已弃用的 `maxThinkingTokens`。2739控制 Claude 的思考/推理行为。优先于已弃用的 `maxThinkingTokens`。

2740 2740

2741```typescript theme={null}2741```typescript theme={null}

2742type ThinkingDisplay = "summarized" | "omitted";

2743

2742type ThinkingConfig =2744type ThinkingConfig =

2743 | { type: "adaptive" } // 模型确定何时以及多少推理（Opus 4.6+）2745 | { type: "adaptive"; display?: ThinkingDisplay } // 模型确定何时以及多少推理（Opus 4.6+）

2744 | { type: "enabled"; budgetTokens?: number } // 固定思考令牌预算2746 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定思考令牌预算

2745 | { type: "disabled" }; // 无扩展思考2747 | { type: "disabled" }; // 无扩展思考

2746```2748```

2747 2749

2750可选的 `display` 字段控制思考文本是否以 `"summarized"` 或 `"omitted"` 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。

2751

2748### `SpawnedProcess`2752### `SpawnedProcess`

2749 2753

2750自定义进程生成的接口（与 `spawnClaudeCodeProcess` 选项一起使用）。`ChildProcess` 已满足此接口。2754自定义进程生成的接口（与 `spawnClaudeCodeProcess` 选项一起使用）。`ChildProcess` 已满足此接口。

3158```3162```

3159 3163

3160| 属性 | 类型 | 默认值 | 描述 |3164| 属性 | 类型 | 默认值 | 描述 |

3161| :------------------------ | :--------- | :---------- | :--------------------------------------- |3165| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |

agent-sdk/typescript-v2-preview.md +7 −5

Details

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# TypeScript SDK V2 session API（已弃用）~~5# TypeScript SDK V2 session API（已移除）

6 6

~~7> 已弃用的 V2 TypeScript Agent SDK session API 参考，具有用于多轮对话的基于会话的 send/stream 模式。~~7> 已移除的 V2 TypeScript Agent SDK session API 参考，具有用于多轮对话的基于会话的 send/stream 模式。

8 8

9<Warning>9<Warning>

10 V2 session API 函数 `unstable_v2_createSession`、`unstable_v2_resumeSession` 和 `unstable_v2_prompt` 已弃用，将在未来版本中删除。请改用 [V1 `query()` API](/zh-CN/agent-sdk/typescript)。10 V2 session API 不再受支持。TypeScript Agent SDK 0.3.142 移除了 `unstable_v2_createSession`、`unstable_v2_resumeSession`、`unstable_v2_prompt` 以及 `SDKSession` 和 `SDKSessionOptions` 类型。

12 要迁移，请使用 [`query()` API](/zh-CN/agent-sdk/typescript) 和它接受的 [session 选项](/zh-CN/agent-sdk/sessions)。为多轮对话传递 `AsyncIterable<SDKUserMessage>`，或使用 `options.resume` 继续已保存的会话。如果您在 Agent SDK 0.2.x 或更早版本上维护代码，此页面保留供参考。

11</Warning>13</Warning>

12 14

13V2 是一个实验性的 session API，消除了对异步生成器和 yield 协调的需求。与其在各轮之间管理生成器状态，每一轮都是一个单独的 `send()`/`stream()` 周期。API 表面简化为三个概念：15V2 是一个实验性的 session API，消除了对异步生成器和 yield 协调的需求。与其在各轮之间管理生成器状态，每一轮都是一个单独的 `send()`/`stream()` 周期。API 表面简化为三个概念：

18 20

19## 安装21## 安装

20 22

~~21V2 interface 包含在现有的 SDK 包中：~~23Agent SDK 0.2.x 是包含 V2 interface 的最后一个版本。包版本从 0.2.x 直接跳到 0.3.142，因此上面的移除版本和下面的安装固定版本描述的是同一个边界。要安装最后一个 V2 兼容版本，请固定主版本号和次版本号：

22 24

23```bash theme={null}25```bash theme={null}

~~24npm install @anthropic-ai/claude-agent-sdk~~26npm install @anthropic-ai/claude-agent-sdk@0.2

25```27```

26 28

27<Note>29<Note>

agent-view.md +244 −69

Details

6 6

7> 从一个屏幕调度和管理多个 Claude Code 会话。Agent view 显示每个会话正在做什么以及哪些会话需要你的输入。7> 从一个屏幕调度和管理多个 Claude Code 会话。Agent view 显示每个会话正在做什么以及哪些会话需要你的输入。

8 8

9Agent view 通过 `claude agents` 打开，是所有后台会话的一个屏幕：什么正在运行、什么需要你的输入、什么已完成。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在需要时才介入。会话在没有终端连接的情况下继续在后台运行。9Agent view 通过 `claude agents` 打开，是所有后台会话的一个屏幕：什么正在运行、什么需要你的输入、什么已完成。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在需要时才介入。每个后台会话都是一个完整的 Claude Code 对话，在没有终端连接的情况下继续运行，所以你可以随时打开它、回复并离开。

10 10

11当你有多个独立任务 Claude 可以同时处理时，使用 agent view，例如修复 bug、审查拉取请求或调查日志。当你想一起解决问题时，附加到一个会话并像往常一样交互式地使用 Claude Code。会话在 agent view 中独立运行，仅向你报告。要与 subagents、agent teams 和 worktrees 进行比较，请参阅 [并行运行代理](/zh-CN/agents)。11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="终端中的 Agent view：标题显示 Claude Code v2.1.140、模型、工作目录和摘要计数。会话分组在'需要输入'、'正在工作'和'已完成'下，底部有调度输入和键盘提示页脚。" width="1772" height="780" data-path="images/agent-view-light.png" />

13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="终端中的 Agent view：标题显示 Claude Code v2.1.140、模型、工作目录和摘要计数。会话分组在'需要输入'、'正在工作'和'已完成'下，底部有调度输入和键盘提示页脚。" width="1772" height="780" data-path="images/agent-view-dark.png" />

15当你有多个独立任务 Claude 可以在不需要你观看每一步的情况下处理时，使用 agent view。调度一个 bug 修复、一个拉取请求审查和一个不稳定测试调查作为三行，在另一个窗口中继续工作，当一行显示它需要你或有结果时检查回来。

17当你想在任何代理的会话中更直接地工作时，附加到该行以进入完整对话。

19要比较 agent view 与 subagents、agent teams 和 worktrees，请参阅 [并行运行代理](/zh-CN/agents)。

12 20

13<Note>21<Note>

14 Agent view 是研究预览版，需要 Claude Code v2.1.139 或更高版本。使用 `claude --version` 检查你的版本。随着功能的发展，界面和快捷键可能会改变，管理员可以通过 [`disableAgentView`](#how-background-sessions-are-hosted) 托管设置为组织禁用 agent view。22 Agent view 是研究预览版，需要 Claude Code v2.1.139 或更高版本。使用 `claude --version` 检查你的版本。随着功能的发展，界面和快捷键可能会改变。

15</Note>23</Note>

16 24

17本页涵盖：25本页涵盖：

18 26

~~19* [快速开始](#quick-start)~~27* [快速开始](#quick-start)：给 Claude 一个在后台处理的任务，检查它，并在需要时介入

20* [使用 agent view 监控会话](#monitor-sessions-with-agent-view)，包括状态图标、窥视和回复、附加、组织和快捷键28* [使用 agent view 监控会话](#monitor-sessions-with-agent-view)，包括状态图标、窥视和回复、附加、组织和快捷键

21* [调度新代理](#dispatch-new-agents)，从 agent view、从会话内部或从 shell29* [调度新代理](#dispatch-new-agents)，从 agent view、从会话内部或从 shell

22* [从 shell 管理会话](#manage-sessions-from-the-shell)30* [从 shell 管理会话](#manage-sessions-from-the-shell)

24 32

25## 快速开始33## 快速开始

26 34

~~27本演练打开 agent view、调度一个会话、从窥视面板回复，以及附加到完整对话。~~35本演练涵盖核心 agent view 循环：调度一个任务，观看其行在 Claude 工作时更新，窥视以检查它并回复，以及附加到完整对话。你调度的会话在关闭 agent view 后继续运行，所以你可以离开并稍后回到它。

28 36

29<Steps>37<Steps>

30 <Step title="打开 agent view">38 <Step title="打开 agent view">

34 claude agents42 claude agents

35 ```43 ```

36 44

~~37 Agent view 打开，底部有一个输入框，当会话启动时表格会填充。随时按 `Esc` 退出。你的会话继续运行。~~45 Agent view 打开，底部有一个输入框，当会话启动时表格会填充。随时按 `Esc` 返回你的 shell。你的会话在你离开时继续运行，下次打开 agent view 时会重新出现。

38 </Step>46 </Step>

39 47

40 <Step title="调度一个会话">48 <Step title="调度一个会话">

41 在输入框中输入提示并按 `Enter`。一个新会话启动并显示为一行，显示它是否正在工作、等待你或已完成。重复以并行运行多个会话。每个会话独立使用你的订阅配额，所以在一次调度多个会话之前，请查看[限制](#limitations)。49 输入描述任务的提示并按 `Enter`。一个新的后台会话在该任务上启动并显示为一行，显示它是否正在工作、等待你或已完成。新会话使用 agent view 标题中显示的模型和在该目录中运行 `claude` 时会获得的相同[权限模式](#permission-mode-model-and-effort)。

51 你在此输入的每个提示都会启动自己的新会话。输入另一个提示并按 `Enter` 会启动第二个会话，与第一个会话并行运行，而不是向其发送后续消息。你可以通过这种方式并行运行多个会话。

53 每个会话独立使用你的订阅配额，所以在一次调度多个会话之前，请查看[限制](#limitations)。

42 </Step>54 </Step>

43 55

44 <Step title="窥视和回复">56 <Step title="窥视和回复">

~~45 用箭头键选择一行，按 `Space` 查看会话正在做什么或它需要什么。输入回复并按 `Enter` 发送，无需离开 agent view。~~57 用箭头键选择一行并按 `Space` 打开窥视面板。它显示会话的最近输出，或它正在等待的问题，而不是完整的记录。输入回复并按 `Enter` 发送，无需离开 agent view。

46 </Step>58 </Step>

47 59

48 <Step title="附加和分离">60 <Step title="附加和分离">

49 在一行上按 `Enter` 或 `→` 在你想要完整对话时附加。会话接管终端，就像你运行了 `claude` 一样。在空提示上按 `←` 分离并返回表格。61 在一行上按 `Enter` 或 `→` 在你想要完整对话时附加。会话接管终端，就像你运行了 `claude` 一样。在空提示上按 `←` 分离并返回表格。

50 </Step>62 </Step>

~~51</Steps>~~

52 63

53要将现有的交互式会话带入 agent view，在其中运行 `/bg`，或在空提示上按 `←` 以后台会话并在一步中打开 agent view。会话继续在后台运行并显示为一行。要直接从 shell 启动新的后台会话，运行 `claude --bg "<prompt>"`。64 <Step title="将现有会话引入">

65 要将你已经打开的会话移入 agent view，在其中运行 `/bg`，或在空提示上按 `←` 以后台会话并在一步中打开 agent view。会话继续运行并显示为一行，与你调度的会话并排。

66 </Step>

67</Steps>

54 68

55你可以使用 `claude agents` 作为你的主要入口点而不是 `claude`：从 agent view 调度每个任务，当你想要完整对话时附加，按 `←` 返回表格。69你可以使用 `claude agents` 作为你的主要入口点而不是 `claude`：从 agent view 调度每个任务，当你想要完整对话时附加，按 `←` 返回表格。

56 70

58 72

59运行 `claude agents` 打开 agent view。它接管整个终端并列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动和上次更改的时间。73运行 `claude agents` 打开 agent view。它接管整个终端并列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动和上次更改的时间。

60 74

61该列表涵盖你的 [配置目录](#how-background-sessions-are-hosted) 下的每个后台会话，无论它在哪个项目或 worktree 中工作，因此在一个存储库中启动的会话和在不同 worktree 中启动的另一个会话都一起出现。你在其他终端中打开的交互式会话不会出现，直到你 [后台它们](#from-inside-a-session)，[subagents](/zh-CN/sub-agents) 在会话内运行不会列为单独的行。75默认情况下，列表显示你启动的每个后台会话，跨越所有项目。在一个存储库中工作的会话和在不同 worktree 中工作的另一个会话都会出现在这里，无论你从哪个目录打开 agent view。要将列表限制到一个项目，请传递 `--cwd`（需要 Claude Code v2.1.141 或更高版本）：

77```bash theme={null}

78claude agents --cwd ~/projects/my-app

79```

81这只显示在该目录下启动的会话。已[移入 worktree](#how-file-edits-are-isolated) 到 `~/projects/my-app/.claude/worktrees/` 下的会话仍然算作属于 `~/projects/my-app`。

83你在其他终端中打开的交互式会话不会出现，直到你[后台它们](#from-inside-a-session)。[Subagents](/zh-CN/sub-agents) 和 [teammates](/zh-CN/agent-teams) 会话生成的不会列为单独的行。

62 84

63```text theme={null}85```text theme={null}

64Pinned86Pinned

65 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m87 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

66 88

67Ready for review89Ready for review

~~68 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h~~90 ∙ jump physics github.com/example/game/pull/2048 ● 2h

69 91

70Needs input92Needs input

71 ✻ power-up design needs input: double jump or wall climb? 1m93 ✻ power-up design needs input: double jump or wall climb? 1m

80 … 6 more102 … 6 more

81```103```

82 104

~~83每行的图标传达两个信号。指示器告诉你会话的状态，图标的形状告诉你底层进程是否仍在运行。状态如下：~~105### 读取会话状态

106

107每行以一个图标开头，其颜色和动画显示会话的状态：

108

109| 状态 | 图标显示为 | 含义 |

110| :--- | :---- | :------------------------------ |

111| 工作中 | 动画 | Claude 正在积极运行工具或生成响应 |

112| 需要输入 | 黄色 | Claude 等待你的特定问题或权限决定 |

113| 空闲 | 暗淡 | 会话没有任何事情要做，准备好接收你的下一个提示 |

114| 已完成 | 绿色 | 任务成功完成 |

115| 失败 | 红色 | 任务以错误结束 |

116| 已停止 | 灰色 | 会话被 `Ctrl+X` 或 `claude stop` 停止 |

84 117

~~85| 指示器 | 状态 | 含义 |~~118另外，图标的形状显示底层进程是否正在运行：

~~86| :-- | :--- | :------------------------------ |~~

~~87| 动画 | 工作中 | Claude 正在积极运行工具或生成响应 |~~

~~88| 黄色 | 需要输入 | Claude 等待你的输入，通常是权限决定或答案 |~~

~~89| 暗淡 | 空闲 | 会话等待输入但不被特定问题阻止 |~~

~~90| 绿色 | 已完成 | 任务成功完成 |~~

~~91| 红色 | 失败 | 任务以错误结束 |~~

~~92| 灰色 | 已停止 | 会话被 `Ctrl+X` 或 `claude stop` 停止 |~~

93 119

94图标的形状告诉你底层进程是否仍在运行。`✻` 或动画 `✽`（当 Claude 工作时）意味着会话是活跃的，你可以立即回复。`∙` 意味着进程已退出，但你仍然可以窥视、回复或附加：Claude 从中断处重新启动会话。`✢` 是一个 [`/loop`](/zh-CN/commands) 会话在迭代之间休眠，行显示其运行计数和下一次迭代的倒计时。120| 形状 | 含义 |

121| :---------- | :----------------------------------------------------------- |

122| `✻` 或动画 `✽` | 会话进程处于活跃状态并立即回复 |

123| `∙` | 进程已退出。你仍然可以窥视、回复或附加，Claude 从中断处重新启动 |

124| `✢` | 一个 [`/loop`](/zh-CN/scheduled-tasks) 会话在迭代之间休眠。该行显示其运行计数和倒计时 |

95 125

96后台会话不需要任何打开的终端来继续工作。一个单独的 [监督进程](#how-background-sessions-are-hosted) 运行它们，所以你可以关闭 agent view、关闭你的 shell 或启动一个新的交互式会话，你的调度工作继续进行。126行右边缘可能出现的 `●` 是[拉取请求状态](#pull-request-status)指示器，不是状态图标的一部分。它前面的数字是会话打开的拉取请求数。

97 127

98会话在磁盘上持久化：关闭你的终端或自动更新不会丢失它们，重新打开 `claude agents` 显示它们全部。如果你的机器休眠或关闭，运行中的会话停止；用 `claude respawn --all` 重新启动它们。128后台会话不需要任何打开的终端来继续工作。一个单独的[监督进程](#the-supervisor-process)运行它们，所以你可以关闭 agent view、关闭你的 shell 或启动一个新的交互式会话，你的调度工作继续进行。

99 129

100每行中的单行摘要由你配置的 [Haiku-class 模型](/zh-CN/model-config) 生成，所以行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒刷新一次，加上每个回合结束时刷新一次。每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的 [数据使用条款](/zh-CN/data-usage) 计费和处理。130会话状态通过自动更新和监督进程重启在磁盘上持久化。会话在你的机器休眠时也会被保留。它们的进程在唤醒时恢复，监督进程重新连接到它们，而不是将时间间隙视为空闲。关闭仍然会停止运行中的会话；请参阅[关闭后会话显示为失败](#sessions-show-as-failed-after-shutdown)了解如何恢复它们。

131

132### 行摘要

133

134每行中的单行摘要由 [Haiku-class 模型](/zh-CN/model-config)生成，所以该行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒刷新一次，加上每个回合结束时刷新一次。

135

136每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的[数据使用条款](/zh-CN/data-usage)计费和处理。

137

138### 拉取请求状态

101 139

102当会话打开拉取请求时，状态点出现在行的右边缘，在支持超链接的终端中链接到拉取请求。当会话打开了多个拉取请求时，计数出现在点之前，颜色反映最需要关注的那个。140当会话打开拉取请求时，状态点出现在行的右边缘，在支持超链接的终端中链接到拉取请求。当会话打开了多个拉取请求时，计数出现在点之前，颜色反映最需要关注的那个。

103 141

120 158

121### 附加到会话159### 附加到会话

122 160

123在选定的行上按 `Enter` 或 `→` 附加，或按 `Alt+1` 到 `Alt+9` 直接附加到焦点组中的第 N 个会话。Agent view 被完整的交互式会话替换，就像你在该目录中运行了 `claude` 一样。当你附加时，Claude 发布一个关于你离开时发生的事情的简短回顾。161在选定的行上按 `Enter` 或 `→` 附加。Agent view 被完整的交互式会话替换，就像你在该目录中运行了 `claude` 一样。当你附加时，Claude 发布一个关于你离开时发生的事情的简短回顾。

124 162

125附加时，会话的行为像任何其他 Claude Code 会话：每个 [命令](/zh-CN/commands)、快捷键和功能都有效。163附加时，会话的行为像任何其他 Claude Code 会话：每个[命令](/zh-CN/commands)、快捷键和功能都有效。

126 164

127在空提示上按 `←` 分离并返回 agent view。如果对话有焦点且不响应 `←`，按 `Ctrl+Z` 立即分离。165在空提示上按 `←` 分离并返回 agent view。如果对话有焦点且不响应 `←`，按 `Ctrl+Z` 立即分离。

128 166

129分离永远不会停止后台会话：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都让它运行。要从内部结束会话，运行 `/stop`。167分离永远不会停止后台会话：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都让它运行。要从内部结束会话，运行 `/stop`。

130 168

131一旦你调度或后台了会话，在空提示上按 `←` 从任何 Claude Code 会话工作，不仅仅是你从 agent view 附加的会话。它后台当前会话并打开 agent view，该会话预选，所以你可以在不离开终端的情况下切换会话。你可以在 `/config` 中关闭此快捷键。169在你调度或后台了会话后，在空提示上按 `←` 从任何 Claude Code 会话工作，不仅仅是你从 agent view 附加的会话。它后台当前会话并打开 agent view，该行被选中，所以你可以在不离开终端的情况下切换会话。该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。当该行是唯一的行时，agent view 在它下方显示一个入门提示。你可以在 `/config` 中关闭此快捷键（`leftArrowOpensAgents` 设置）。

132 170

133### 组织列表171### 组织列表

134 172

135Agent view 按状态分组会话，需要输入的会话在工作或完成的会话上方。按 `Ctrl+S` 改为按目录分组。你的选择在运行中保存。在一个组内，用 `Ctrl+T` 将会话固定到顶部，用 `Shift+↑` 和 `Shift+↓` 重新排序，或在组标题上按 `Enter` 折叠它。要删除会话，按 `Ctrl+X` 停止它，在两秒内再按 `Ctrl+X` 删除它。在组标题上按 `Ctrl+X` 在确认后删除该组中的每个会话。173Agent view 按状态分组会话，需要输入的会话在顶部，`Ready for review` 和 `Needs input` 在 `Working` 和 `Completed` 上方。这些组名不与上面的[状态](#read-session-state)一一对应：当会话有打开的拉取请求时，它移动到 `Ready for review`，`Completed` 收集已完成、失败和已停止的会话。按 `Ctrl+S` 改为按目录分组。你的选择在运行中保存。

174

175在一个组内：

136 176

137较旧的已完成会话折叠成"… N more"行以保持列表简短。失败和有打开拉取请求的会话始终保持可见。177* 按 `Ctrl+T` 将会话固定到顶部

178* 按 `Shift+↑` 或 `Shift+↓` 重新排序会话

179* 按 `Ctrl+R` 重命名会话

180* 在组标题上按 `Enter` 折叠它

138 181

139### 过滤列表182要从列表中删除会话，按 `Ctrl+X` 停止它，在两秒内再按 `Ctrl+X` 删除它。在组标题上按 `Ctrl+X` 在确认后删除该组中的每个会话。

183

184删除会从 agent view 中删除会话并删除其对话记录。如果 Claude [为会话创建了 worktree](#how-file-edits-are-isolated)，删除会删除该 worktree，包括其中的任何未提交的更改，所以在删除前推送或提交你想保留的工作。你自己创建的 worktree 并在其中启动会话的会被保留。

185

186较旧的已完成会话折叠成 `… N more` 行以保持列表简短。失败和有打开拉取请求的会话始终保持可见。

187

188### 过滤会话

140 189

141在调度输入中输入以过滤而不是调度：190在调度输入中输入以过滤而不是调度：

142 191

143| 过滤 | 显示 |192| 过滤 | 显示 |

144| :------------------- | :------------------------------ |193| :------------------- | :------------------------------------------------ |

148 197

149### 快捷键198### 快捷键

150 199

151在 agent view 中按 `?` 查看每个快捷键。最常见的：200在 agent view 中按 `?` 查看每个快捷键的上下文。下表总结了它们。

152 201

153| 快捷键 | 操作 |202| 快捷键 | 操作 |

154| :-------------------- | :------------------------ |203| :-------------------- | :-------------------------------- |

155| `↑` / `↓` | 在行之间移动 |204| `↑` / `↓` | 在行之间移动 |

159| `→` | 附加到选定的会话 |208| `→` | 附加到选定的会话 |

161| `Tab` | 浏览所有 subagents，或应用突出显示的建议 |210| `Tab` | 在空输入上浏览所有 subagents。否则应用突出显示的建议 |

168| `Esc` | 关闭窥视面板、清除输入或退出 |217| `Esc` | 关闭窥视面板、清除输入或退出 |

175 224

176### 从 agent view225### 从 agent view

177 226

178在 agent view 底部的输入框中输入提示并按 `Enter` 启动新的后台会话。会话从提示自动命名。你可以稍后用 `Ctrl+R` 重命名它。将图像粘贴到提示中以包含任务的屏幕截图或图表。227在 agent view 底部的输入框中输入提示并按 `Enter` 启动新的后台会话。会话从提示自动命名；稍后可以用 `Ctrl+R` 重命名它。

228

229将图像粘贴到提示中以包含任务的屏幕截图或图表。

179 230

180前缀或提及提示的部分以控制会话如何启动：231前缀或提及提示的部分以控制会话如何启动：

181 232

190 241

191输入 `/` 调度一个 [skill](/zh-CN/skills)。将重复任务打包为 skill 让你从 agent view 多次启动相同的工作流而无需重新输入提示。在空输入上按 `Tab` 浏览每个可调度的 subagent，或在显示建议时应用突出显示的建议。242将重复任务打包为 [skill](/zh-CN/skills) 让你从 agent view 多次启动相同的工作流而无需重新输入提示。

192 243

193当相同的 `@name` 同时匹配 subagent 和同级存储库时，subagent 优先。不带 `@` 的首字形式也适用于任何 subagent 名称，所以以匹配你的某个 subagent 名称的单词开头的提示会调度该 subagent。当你想要明确指定时，使用 `@` 形式。244当相同的 `@name` 同时匹配 subagent 和同级存储库时，subagent 优先。不带 `@` 的首字形式也适用，所以以匹配你的某个 subagent 名称的单词开头的提示会调度该 subagent 而不是将该单词视为纯文本。当你想要明确指定时，使用 `@` 形式，或以不同的单词开头提示以避免匹配。

194 245

195#### 调度到特定目录246#### 调度到特定目录

196 247

204 255

205### 从会话内部256### 从会话内部

206 257

207运行 `/background` 或其别名 `/bg` 分离当前对话并保持其运行。传递提示如 `/bg run the test suite and fix any failures` 在分离前发送一个更多指令。258运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。

259

260从交互式会话后台化启动一个新的进程，该进程从保存的对话恢复，所以运行 subagent、[monitors](/zh-CN/tools-reference#monitor-tool) 和后台命令不会转移到它。当任何正在运行时，Claude 会要求你在后台化前确认。一旦在后台，会话可以启动新的 subagent、monitor 和后台命令，这些会在后续的分离和重新附加中保持运行。

208 261

209### 从 shell262来自原始启动的配置标志会传递到后台化的会话，所以其 MCP servers、settings 和备用模型保持有效：

263

264* `--mcp-config` 和 `--strict-mcp-config`

265* `--settings`

266* `--add-dir`

267* `--plugin-dir`

268* `--fallback-model`

269* `--allow-dangerously-skip-permissions`

270

271传递 `--allow-dangerously-skip-permissions` 会在后台化的会话中保持 `bypassPermissions` 可访问，但它不会授予任何新权限。该模式仍然需要在任何会话使用它之前进行相同的一次性交互式接受，如 [权限模式、模型和工作量](#permission-mode-model-and-effort) 中所述。

272

273### 从你的 shell

210 274

211传递 `--bg` 启动直接进入后台的会话：275传递 `--bg` 启动直接进入后台的会话：

212 276

220claude --agent code-reviewer --bg "address review comments on PR 1234"284claude --agent code-reviewer --bg "address review comments on PR 1234"

221```285```

222 286

287传递 `--name` 以在 agent view 中设置会话的显示名称而不是自动生成的名称：

288

289```bash theme={null}

290claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

291```

292

223后台化后，Claude 打印会话的短 ID 和管理它的命令：293后台化后，Claude 打印会话的短 ID 和管理它的命令：

224 294

225```text theme={null}295```text theme={null}

232 302

233### 文件编辑如何隔离303### 文件编辑如何隔离

234 304

235每个后台会话，无论是从 agent view、`/bg` 还是 `claude --bg` 启动，都在你的工作目录中启动，但被阻止在那里写入文件。当会话需要编辑文件时，Claude 自动将其移动到 `.claude/worktrees/` 下的隔离 [git worktree](/zh-CN/worktrees) 中，所以并行会话可以读取相同的检出但每个都写入自己的。当会话已经在 worktree 内、工作目录不是 git 存储库或写入工作目录外时，该块不适用。305每个后台会话，无论是从 agent view、`/bg` 还是 `claude --bg` 启动，都在你的工作目录中启动。在编辑文件前，Claude 将会话移动到 `.claude/worktrees/` 下的隔离 [git worktree](/zh-CN/worktrees) 中，所以并行会话可以读取相同的检出但每个都写入自己的。

306

307Claude 在以下情况下跳过 worktree：

308

309* 会话已经在链接的 git worktree 内，无论 Claude 是在 `.claude/worktrees/` 下创建的还是你用 `git worktree add` 在其他地方创建的

310* 工作目录不是 git 存储库

311* 写入在工作目录外

312

313要为 git worktree 不实用的存储库关闭 worktree 隔离，将 [`worktree.bgIsolation`](/zh-CN/settings#worktree-settings) 设置为 `"none"`。后台会话随后直接编辑你的工作副本而不先移动到 worktree。将设置添加到项目的 `.claude/settings.json`：

314

315```json theme={null}

316{

317 "worktree": {

318 "bgIsolation": "none"

319 }

320}

321```

322

323<Note>

324 `worktree.bgIsolation` 设置需要 Claude Code v2.1.143 或更高版本。

325</Note>

326

327在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。

328

329在 agent view 中删除会话（`Ctrl+X` 两次）会删除 Claude 为其创建的 worktree，包括任何未提交的更改，所以在删除前合并或推送你想保留的更改。从 shell 用 [`claude rm`](#manage-sessions-from-the-shell) 删除会保持有未提交更改的 worktree 并打印其路径，以便你可以自己清理它。你自己创建的 worktree 并在其中启动会话的，无论哪种方式都会保留在原地。

236 330

237当你删除会话时，worktree 被删除，所以在删除前合并或推送你想保留的更改。要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。331要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。

238 332

239要使 subagent 始终在其自己的 worktree 中运行，无论如何启动，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)。333要使 subagent 始终在其自己的 worktree 中运行，无论如何启动，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)。

240 334

241### 权限模式和设置335### 设置模型

336

337agent view 标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，这与 [`/model`](/zh-CN/model-config) 在任何会话中控制的设置相同。要为整个 agent view 会话覆盖它，在打开 agent view 时传递 `--model`。参见 [权限模式、模型和工作量](#permission-mode-model-and-effort)。

338

339每个后台会话可以在不同的模型上运行。要为一个会话覆盖它：

340

341* 从 shell，用 `claude --bg` 传递 `--model`。

342* 附加到运行中的会话并在那里运行 `/model`。如果会话被重新生成，更改会持续。

343* 调度一个 [subagent](/zh-CN/sub-agents)，其 frontmatter 设置 `model` 字段。

344

345### 权限模式、模型和工作量

346

347后台会话从它运行的目录读取其 [settings](/zh-CN/settings)，就像你在那里启动了 `claude` 一样。

348

349[permission mode](/zh-CN/permissions) 取决于你如何启动会话。用 `/bg` 或 `←` 后台化现有会话会保持当前权限模式，所以你切换到 `acceptEdits` 或 `auto` 的会话在分离后仍保持该模式。从 agent view 输入调度或从你的 shell 运行 `claude --bg` 使用该目录设置中的 `defaultMode`，或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。

350

351你启动后台会话时的权限模式在监督者稍后 [停止并重新启动](#the-supervisor-process) 会话的进程时持续。你用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 启动的会话在该重新启动后仍保持 `bypassPermissions` 而不是回退到目录的 `defaultMode`。

352

353要为从 agent view 调度的每个会话设置默认值，在打开它时传递 `--permission-mode`、`--model` 或 `--effort` 中的任何一个：

354

355```bash theme={null}

356claude agents --permission-mode plan --model opus --effort high

357```

358

359`claude agents` 也接受 `--dangerously-skip-permissions` 作为 `--permission-mode bypassPermissions` 的简写，以及 `--allow-dangerously-skip-permissions` 以在每个调度会话的 `Shift+Tab` 循环中使不带权限模式启动的 `bypassPermissions` 可用。两者都匹配 [顶级 CLI 标志](/zh-CN/cli-reference)。

360

361<Note>

362 向 `claude agents` 传递 `--permission-mode`、`--model`、`--effort` 或 `--dangerously-skip-permissions` 需要 Claude Code v2.1.142 或更高版本。{/* min-version: 2.1.143 */}`claude agents` 上的 `--allow-dangerously-skip-permissions` 需要 v2.1.143 或更高版本。更早的版本会以未知选项错误拒绝这些标志。

363</Note>

364

365活跃的默认值出现在调度输入下方的页脚中。

366

367没有这些标志，会话使用该目录设置中的 `defaultMode` 或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`，以及 agent view 标题中显示的模型。

368

369使用 `bypassPermissions` 或 `auto` 被拒绝，直到你通过交互式运行 `claude` 一次接受该模式，因为这些模式让你没有看到的会话无需批准就能行动。无论你是将模式传递给 `claude agents` 还是 `claude --bg --permission-mode`，同样的规则都适用。

370

371### Settings、plugins 和 MCP servers

242 372

243调度的会话从它运行的目录读取其 [settings](/zh-CN/settings) 和 [permission mode](/zh-CN/permissions)，就像你在那里启动了 `claude` 一样。从 agent view 输入调度不传递权限模式，所以会话使用该目录设置中的 `defaultMode` 或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。373Agent view 接受与 `claude` 相同的配置标志以加载 settings、plugins、MCP servers 和额外目录。这些标志需要 Claude Code v2.1.142 或更高版本。每个标志适用于 agent view 本身，并传递给你从它调度的每个会话，所以以这种方式加载的 plugin 或 MCP server 在这些会话中也可用。

244 374

245要从 shell 设置模式，用 `claude --bg` 传递 `--permission-mode`。以这种方式使用 `bypassPermissions` 或 `auto` 被拒绝，直到你通过交互式运行 `claude` 一次接受该模式，因为这些模式让你没有看到的会话无需批准就能行动。375| 标志 | 效果 |

376| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |

377| [`--settings <file-or-json>`](/zh-CN/settings) | 覆盖 agent view 和调度会话的 settings |

378| [`--add-dir <path>`](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | 授予对额外目录的文件访问权限 |

379| [`--plugin-dir <path>`](/zh-CN/plugins) | 从本地目录加载 plugin |

380| [`--mcp-config <file-or-json>`](/zh-CN/mcp) | 从配置文件或 JSON 字符串加载 MCP servers |

381| `--strict-mcp-config` | 仅使用来自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置 |

382

383对每个值重复 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。空格分隔的形式，如 `--add-dir a b c`，不支持与 `claude agents` 一起使用。

384

385以下示例使用 settings 覆盖和一个额外目录打开 agent view：

386

387```bash theme={null}

388claude agents --settings ./ci-settings.json --add-dir ../shared-lib

389```

246 390

247## 从 shell 管理会话391## 从 shell 管理会话

248 392

249每个后台会话有一个短 ID，你可以从 shell 使用。这些命令对于脚本编写或当你不想打开 agent view 时很有用。393每个后台会话有一个短 ID，你可以从 shell 使用。当你使用 `claude --bg` 启动会话时会打印该 ID，每个会话的 ID 是其在 `~/.claude/jobs/` 下的目录名。这些命令对于脚本编写或当你不想打开 agent view 时很有用。

250 394

251| 命令 | 目的 |395| 命令 | 目的 |

252| :--------------------- | :--------------------- |396| :--------------------------- | :------------------------------------------------------------------------------------- |

398| `claude agents --cwd <path>` | 打开 agent view，范围限定为在 `<path>` 下启动的会话 |

405| `claude daemon status` | 打印 [supervisor](#the-supervisor-process) 的状态、版本、socket 目录和 worker 数量 |

260 406

261## 后台会话如何被托管407## 后台会话如何被托管

262 408

263后台会话由每用户监督进程托管，与你的终端和 agent view 分离。它在你第一次后台会话或打开 agent view 时自动启动，你不直接管理它。监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。409agent view 中列出的每个会话都被视为后台会话，无论你当前是否连接到它。相比之下，通过直接运行 `claude` 启动的会话与该终端绑定，并在终端关闭时结束，除非你[将其发送到后台](#from-inside-a-session)。

410

411### 监督进程

412

413后台会话由每用户监督进程托管，与你的终端和 agent view 分离。监督进程在你第一次后台会话或打开 agent view 时自动启动，你不直接管理它。

414

415监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。

416

417每个后台会话是其自己的 Claude Code 进程，由监督进程管理而不是与你的终端绑定。积极工作、等待你的输入或有终端连接的会话保持其进程运行。

418

419一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。记录和状态保留在磁盘上，下次你附加、窥视或回复时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你需要它时再次启动。

264 420

265每个后台会话是其自己的 Claude Code 进程，父进程是监督进程而不是你的终端。积极工作、等待你的输入或有终端连接的会话保持其进程运行。一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。记录和状态保留在磁盘上，下次你附加、窥视或回复时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你后台会话或打开 agent view 时再次启动。421监督进程监视磁盘上安装的 Claude Code 二进制文件，在常规[自动更新程序](/zh-CN/setup#auto-updates)替换它后重新启动到新版本。这是本地文件监视，不是网络检查。后台会话是分离的进程，所以它们在重新启动期间继续运行，新的监督进程重新连接到它们。

266 422

267监督进程监视磁盘上安装的 Claude Code 二进制文件，在常规 [自动更新程序](/zh-CN/setup#auto-updates) 替换它后重新启动到新版本。这是本地文件监视，不是网络检查。后台会话是分离的进程，所以它们在重新启动期间继续运行，新的监督进程重新连接到它们。423### 状态存储位置

268 424

269会话状态存储在你的 Claude Code 配置目录下。如果你设置 [`CLAUDE_CONFIG_DIR`](/zh-CN/env-vars)，监督进程使用该目录而不是 `~/.claude` 并作为单独的实例运行，具有其自己的会话。425会话状态存储在你的 Claude Code 配置目录下。如果你设置了 [`CLAUDE_CONFIG_DIR`](/zh-CN/env-vars)，监督进程使用该目录而不是 `~/.claude` 并作为单独的实例运行，具有其自己的会话。

270 426

271| 路径 | 内容 |427| 路径 | 内容 |

272| :------------------------------- | :---------------------- |428| :------------------------------- | :---------------------- |

276 432

277要完全关闭后台代理和 agent view，将 `disableAgentView` [设置](/zh-CN/settings) 设为 `true` 或设置 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 环境变量。管理员可以通过 [托管设置](/zh-CN/permissions#managed-settings) 强制执行这个。433要在不直接读取文件的情况下检查此状态，请运行 `claude daemon status`。它报告监督进程是否可达、其进程 ID 和版本、套接字目录以及有多少后台会话处于活跃状态。`/doctor` 包括相同检查的摘要。在 Windows 上，当守护进程的管道密钥文件被锁定或无法读取时，`claude daemon status` 会显示底层文件错误，而不是报告通用连接失败。

434

435### 关闭 agent view

436

437要完全关闭后台代理和 agent view，将 `disableAgentView` [设置](/zh-CN/settings)设为 `true` 或设置 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 环境变量。管理员可以通过[托管设置](/zh-CN/permissions#managed-settings)强制执行这个。

278 438

279## 故障排除439## 故障排除

280 440

441### `claude agents` 列出子代理而不是打开代理视图

442

443如果 `claude agents` 打印一个计数，然后是你配置的子代理，然后退出，说明代理视图在你的环境中不可用。早期版本不会在每个环境中打开代理视图，包括通过 Bedrock、Vertex AI 或 Foundry 连接时。运行 `claude update` 来安装最新版本。

444

445如果更新后代理视图仍然没有打开，检查它是否已被设置或环境变量[关闭](#turn-off-agent-view)。

446

281### Agent view 打开时没有会话447### Agent view 打开时没有会话

282 448

283Agent view 为空，直到你调度你的第一个会话。在底部的输入框中输入提示并按 `Enter`。449在你调度你的第一个会话之前，agent view 显示一个简短的入门提示，在会话列表的位置显示示例提示。在底部的输入框中输入提示并按 `Enter` 来调度你的第一个会话。

450

451### 无法打开代理，因为后台任务正在运行

452

453如果按 `←` 来后台当前会话显示 `Cannot open agents — N background task(s) running`，说明会话有进行中的工作，例如子代理、工作流或后台 shell 命令，快捷键不会默默放弃它。运行 `/tasks` 来查看正在运行的内容，然后运行 `/bg` 来确认放弃它们。参见[从会话内部](#from-inside-a-session)了解后台时什么会转移，什么不会转移。

454

455### 提示被拒绝，因为太短

456

457调度输入期望一个任务描述，而不是对话开场白。少于四个字符的提示会被拒绝，并显示 `Too short` 提示，这样随意的按键就不会启动会话。描述你希望会话执行的操作，例如 `investigate the flaky checkout test`。

458

459### 会话在关闭后显示为已失败

284 460

285### 机器唤醒后会话显示为已停止461关闭或重启你的机器会停止运行中的后台会话，所以当你下次打开 agent view 时，它们显示为已失败。附加、窥视或回复任何已失败的会话，会话从中断处重新启动。

286 462

287后台会话不能存活睡眠或关闭。附加、窥视或回复任何已停止的会话，它从中断处重新启动。要一次重新启动所有会话，运行 `claude respawn --all`。463睡眠单独不会导致这种情况。会话在睡眠期间被保留，监督进程在唤醒时重新连接到它们。

288 464

289### 附加后会话响应缓慢465### 附加后会话响应缓慢

290 466

292 468

293### `.claude/worktrees/` 填满了469### `.claude/worktrees/` 填满了

294 470

295Worktrees 在你删除创建它们的会话时删除。如果会话结束而没有清理，在项目目录中用 `git worktree list` 列出剩余条目，并用 `git worktree remove <path>` 删除每个。参见 [清理 worktrees](/zh-CN/worktrees#clean-up-worktrees)。471在 agent view 中删除会话会删除 Claude 为其创建的 worktree。`claude rm` 保留具有未提交更改的 worktree 并打印其路径。在项目目录中用 `git worktree list` 列出剩余条目，并用 `git worktree remove <path>` 删除每个。参见[清理 worktrees](/zh-CN/worktrees#clean-up-worktrees)。

296 472

297## 限制473## 限制

298 474

299Agent view 是研究预览版。要注意的当前限制：475Agent view 处于研究预览阶段，存在以下限制：

300 476

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

302* **会话是本地的**：后台会话在你的机器上运行，如果它睡眠或关闭则停止。478* **会话是本地的**：后台会话在你的机器上运行。它们在机器睡眠时保留，但在机器关闭时停止。

303* **Worktrees 随会话删除**：在删除在其自己的 worktree 中编辑文件的会话前合并或推送更改。479* **Claude 创建的 worktrees 在 agent view 中随会话删除**：在删除在其自己的 worktree 中编辑文件的会话之前，请合并或推送更改。`claude rm` 保留具有未提交更改的 worktree；你自己创建的 worktree 保持原位。

304 480

305## 后续步骤481## 相关资源

306 482

307现在你理解了 agent view，探索这些相关功能：483有关以并行方式运行 Claude 的其他方法，请参阅：

308 484

309* [在并行中运行代理](/zh-CN/agents)：比较 agent view 与 subagents、agent teams 和 worktrees485* [在并行中运行代理](/zh-CN/agents)：比较 agent view 与 subagents、agent teams 和 worktrees

310* [Subagents](/zh-CN/sub-agents)：定义具有自定义提示、工具和隔离的可重用代理配置

311* [Agent teams](/zh-CN/agent-teams)：协调相互发送消息的多个会话486* [Agent teams](/zh-CN/agent-teams)：协调相互发送消息的多个会话

312* [Claude Code on the web](/zh-CN/claude-code-on-the-web)：在托管的云环境中运行会话而不是本地487* [Claude Code on the web](/zh-CN/claude-code-on-the-web)：在托管的云环境中运行会话而不是本地

cli-reference.md +5 −4

Details

11您可以使用这些命令启动会话、管道内容、恢复对话和管理更新：11您可以使用这些命令启动会话、管道内容、恢复对话和管理更新：

12 12

13| 命令 | 描述 | 示例 |13| 命令 | 描述 | 示例 |

14| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |14| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |

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

27| `claude agents` | 打开 [agent view](/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话 | `claude agents` |27| `claude agents` | 打开 [agent view](/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话。传递 `--permission-mode`、`--model` 或 `--effort` 以设置 [分派会话的默认值](/zh-CN/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如顶级 `claude` 命令。需要交互式终端 | `claude agents --cwd ~/projects/my-app` |

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 daemon status` | 打印后台会话 [supervisor](/zh-CN/agent-view#the-supervisor-process) 的状态、版本、套接字目录和工作进程数以进行诊断。如果 supervisor 未运行，则退出代码 1 | `claude daemon status` |

32| `claude plugin` | 管理 Claude Code [plugins](/zh-CN/plugins)。别名：`claude plugins`。请参阅 [plugin 参考](/zh-CN/plugins-reference#cli-commands-reference) 了解子命令 | `claude plugin install code-review@claude-plugins-official` |33| `claude plugin` | 管理 Claude Code [plugins](/zh-CN/plugins)。别名：`claude plugins`。请参阅 [plugin 参考](/zh-CN/plugins-reference#cli-commands-reference) 了解子命令 | `claude plugin install code-review@claude-plugins-official` |

33| `claude project purge [path]` | 删除项目的所有本地 Claude Code 状态：记录、任务列表、调试日志、文件编辑历史、提示历史行和项目在 `~/.claude.json` 中的条目。省略 `[path]` 以从交互式列表中选择。标志：`--dry-run` 预览，`-y`/`--yes` 跳过确认，`-i`/`--interactive` 确认每一项，`--all` 用于每个项目。请参阅 [清除本地数据](/zh-CN/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |34| `claude project purge [path]` | 删除项目的所有本地 Claude Code 状态：记录、任务列表、调试日志、文件编辑历史、提示历史行和项目在 `~/.claude.json` 中的条目。省略 `[path]` 以从交互式列表中选择。标志：`--dry-run` 预览，`-y`/`--yes` 跳过确认，`-i`/`--interactive` 确认每一项，`--all` 用于每个项目。请参阅 [清除本地数据](/zh-CN/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |

34| `claude remote-control` | 启动 [Remote Control](/zh-CN/remote-control) 服务器以从 Claude.ai 或 Claude 应用控制 Claude Code。在服务器模式下运行（无本地交互式会话）。请参阅 [服务器模式标志](/zh-CN/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |35| `claude remote-control` | 启动 [Remote Control](/zh-CN/remote-control) 服务器以从 Claude.ai 或 Claude 应用控制 Claude Code。在服务器模式下运行（无本地交互式会话）。请参阅 [服务器模式标志](/zh-CN/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |

35| `claude respawn <id>` | 重启已停止的 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell)，保持其对话完整。使用 `--all` 重启每个已停止的会话 | `claude respawn 7c5dcf5d` |36| `claude respawn <id>` | 重启 [background session](/zh-CN/agent-view#manage-sessions-from-the-shell)，运行或已停止，保持其对话完整。使用 `--all` 重启每个运行中的会话，例如以获取更新的 Claude Code 二进制文件 | `claude respawn 7c5dcf5d` |

68| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。覆盖此会话的 [`effortLevel`](/zh-CN/settings#available-settings) 设置，不会持久化 | `claude --effort high` |69| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。覆盖此会话的 [`effortLevel`](/zh-CN/settings#available-settings) 设置，不会持久化 | `claude --effort high` |

69| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以它开始 | `claude --permission-mode auto` |70| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以它开始 | `claude --permission-mode auto` |

70| `--exclude-dynamic-system-prompt-sections` | 将每台机器的部分从系统提示（工作目录、环境信息、内存路径、git 状态）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |71| `--exclude-dynamic-system-prompt-sections` | 将每台机器的部分从系统提示（工作目录、环境信息、内存路径、git 状态）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

74| `--ide` | 如果恰好有一个有效的 IDE 可用，则在启动时自动连接到 IDE | `claude --ide` |75| `--ide` | 如果恰好有一个有效的 IDE 可用，则在启动时自动连接到 IDE | `claude --ide` |

code-review.md +2 −2

Details

29 29

30一旦管理员为您的组织[启用 Code Review](#set-up-code-review)，审查将在 PR 打开时、每次推送时或手动请求时触发，具体取决于存储库的配置行为。在任何模式下，注释 `@claude review` 可以[在 PR 上启动审查](#manually-trigger-reviews)。30一旦管理员为您的组织[启用 Code Review](#set-up-code-review)，审查将在 PR 打开时、每次推送时或手动请求时触发，具体取决于存储库的配置行为。在任何模式下，注释 `@claude review` 可以[在 PR 上启动审查](#manually-trigger-reviews)。

31 31

32当审查运行时，多个代理在 Anthropic 基础设施上并行分析差异和周围代码。每个代理寻找不同类别的问题，然后验证步骤检查候选项是否与实际代码行为相符，以过滤掉误报。结果被去重、按严重程度排序，并作为内联评论发布在发现问题的特定行上，并在审查正文中包含摘要。如果未发现问题，Claude 会在 PR 上发布简短的确认评论。32当审查运行时，多个代理在 Anthropic 基础设施上并行分析差异和周围代码。每个代理寻找不同类别的问题，然后验证步骤检查候选项是否与实际代码行为相符，以过滤掉误报。结果被去重、按严重程度排序，并作为内联评论发布在发现问题的特定行上，并在审查正文中包含摘要。如果未发现问题，Code Review 会更新 GitHub 检查运行以显示未检测到问题。Claude 也可能在 PR 上发布简短的确认评论。

33 33

34审查成本随 PR 大小和复杂性而扩展，平均在 20 分钟内完成。管理员可以通过[分析仪表板](#view-usage)监控审查活动和支出。34审查成本随 PR 大小和复杂性而扩展，平均在 20 分钟内完成。管理员可以通过[分析仪表板](#view-usage)监控审查活动和支出。

35 35

225 225

226## 定价226## 定价

227 227

228Code Review 根据令牌使用情况计费。审查平均花费 \$15-25，随 PR 大小、代码库复杂性和需要验证的问题数量而扩展。Code Review 使用通过[额外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)单独计费，不计入您的计划包含的使用。228Code Review 根据令牌使用情况计费。每次审查平均花费 \$15-25，随 PR 大小、代码库复杂性和需要验证的问题数量而扩展。Code Review 使用通过[使用额度](https://support.claude.com/zh-CN/articles/12429409-extra-usage-for-paid-claude-plans)单独计费，不计入您的计划包含的使用。

229 229

230您选择的审查触发器影响总成本：230您选择的审查触发器影响总成本：

231 231

commands.md +1 −1

Details

63| `/effort [level\|auto]` | 设置模型[工作量级别](/zh-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh` 或 `max`；可用级别取决于模型，`max` 仅限会话。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成 |63| `/effort [level\|auto]` | 设置模型[工作量级别](/zh-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh` 或 `max`；可用级别取决于模型，`max` 仅限会话。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成 |

66| `/extra-usage` | 配置额外使用量以在达到速率限制时继续工作 |

67| `/fast [on\|off]` | 切换[快速模式](/zh-CN/fast-mode)开启或关闭 |66| `/fast [on\|off]` | 切换[快速模式](/zh-CN/fast-mode)开启或关闭 |

69| `/fewer-permission-prompts` | **[Skill](/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |68| `/fewer-permission-prompts` | **[Skill](/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |

125| `/ultrareview [PR]` | 在云沙箱中运行深度、多 agent 代码审阅，使用 [ultrareview](/zh-CN/ultrareview)。Pro 和 Max 包括 3 次免费运行，然后需要[额外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |124| `/ultrareview [PR]` | 在云沙箱中运行深度、多 agent 代码审阅，使用 [ultrareview](/zh-CN/ultrareview)。Pro 和 Max 包括 3 次免费运行，然后需要[额外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

127| `/usage-credits` | 配置使用额度以在达到限制时继续工作。之前为 `/extra-usage` |

128| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。要在 Vim 和普通编辑模式之间切换，请使用 `/config` → 编辑器模式 |128| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。要在 Vim 和普通编辑模式之间切换，请使用 `/config` → 编辑器模式 |

129| `/voice [hold\|tap\|off]` | 切换[语音听写](/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |129| `/voice [hold\|tap\|off]` | 切换[语音听写](/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |

130| `/web-setup` | 使用您的本地 `gh` CLI 凭证将您的 GitHub 账户连接到[网络版 Claude Code](/zh-CN/web-quickstart#connect-from-your-terminal)。如果 GitHub 未连接，`/schedule` 会自动提示此操作 |130| `/web-setup` | 使用您的本地 `gh` CLI 凭证将您的 GitHub 账户连接到[网络版 Claude Code](/zh-CN/web-quickstart#connect-from-your-terminal)。如果 GitHub 未连接，`/schedule` 会自动提示此操作 |

debug-your-config.md +3 −3

Details

87大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：87大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：

88 88

89| 症状 | 原因 | 修复 |89| 症状 | 原因 | 修复 |

90| :-------------------------------------------------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------ |90| :-------------------------------------------------- | :------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |

93| Hook 永远不触发 | Hooks 在独立的 `.claude/hooks.json` 文件中 | 没有独立的 hooks 文件。在 `settings.json` 中的 `"hooks"` 键下定义 hooks。请参阅[hook 配置](/zh-CN/hooks)。 |93| Hook 永远不触发 | Hooks 在独立文件而不是 `settings.json` 中定义 | 项目或用户配置没有独立的 hooks 文件。在 `settings.json` 中的 `"hooks"` 键下定义 hooks。只有[plugins](/zh-CN/plugins-reference#hooks)加载单独的 `hooks/hooks.json`。请参阅[hook 配置](/zh-CN/hooks)。 |

95| `settings.json` 值似乎被忽略 | 相同的键在 `settings.local.json` 中设置 | `settings.local.json` 覆盖 `settings.json`，两者都覆盖 `~/.claude/settings.json`。请参阅[设置优先级](/zh-CN/settings#how-scopes-interact)。 |95| `settings.json` 值似乎被忽略 | 相同的键在 `settings.local.json` 中设置 | `settings.local.json` 覆盖 `settings.json`，两者都覆盖 `~/.claude/settings.json`。请参阅[设置优先级](/zh-CN/settings#how-scopes-interact)。 |

97| Skill 出现在 `/skills` 中但 Claude 从不调用它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述与你表述请求的方式不匹配 | 检查 `/skills` 中的徽章：一个"user-only"标签意味着 Claude 不会自动触发它。请参阅[skill 调用](/zh-CN/skills)。 |97| Skill 出现在 `/skills` 中但 Claude 从不调用它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述与你表述请求的方式不匹配 | 检查 `/skills` 中的徽章：一个"user-only"标签意味着 Claude 不会自动触发它。请参阅[skill 调用](/zh-CN/skills)。 |

102| 在 `settings.json` 中的 `mcpServers` 下添加的 MCP 服务器永远不出现 | `settings.json` 不读取 `mcpServers` 键 | 在存储库根目录的 `.mcp.json` 中定义项目服务器，或运行 `claude mcp add --scope user` 来添加用户范围的服务器。请参阅[MCP 配置](/zh-CN/mcp)。 |102| 在 `settings.json` 中的 `mcpServers` 下添加的 MCP 服务器永远不出现 | `settings.json` 不读取 `mcpServers` 键 | 在存储库根目录的 `.mcp.json` 中定义项目服务器，或运行 `claude mcp add --scope user` 来添加用户范围的服务器。请参阅[MCP 配置](/zh-CN/mcp)。 |

desktop.md +2 −1

Details

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# 使用 Claude Code Desktop~~5# Desktop application

6 6

7> 充分利用 Claude Code Desktop：使用 Git 隔离的并行会话、拖放窗格布局、集成终端和文件编辑器、侧边聊天、计算机使用、从手机 Dispatch 会话、可视化 diff 审查、应用预览、PR 监控、连接器和企业配置。7> 充分利用 Claude Code Desktop：使用 Git 隔离的并行会话、拖放窗格布局、集成终端和文件编辑器、侧边聊天、计算机使用、从手机 Dispatch 会话、可视化 diff 审查、应用预览、PR 监控、连接器和企业配置。

8 8

707* **Linux**：桌面应用仅在 macOS 和 Windows 上可用。在 Linux 上，使用 [CLI](/zh-CN/quickstart)。707* **Linux**：桌面应用仅在 macOS 和 Windows 上可用。在 Linux 上，使用 [CLI](/zh-CN/quickstart)。

708* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。708* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。

709* **Agent teams**：多 agent 编排通过 [CLI](/zh-CN/agent-teams) 和 [Agent SDK](/zh-CN/headless) 可用，不在 Desktop 中。709* **Agent teams**：多 agent 编排通过 [CLI](/zh-CN/agent-teams) 和 [Agent SDK](/zh-CN/headless) 可用，不在 Desktop 中。

710* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，例如 `/permissions`、`/config`、`/agents` 和 `/doctor`，在 Code 选项卡中不可用，并回复 `isn't available in this environment`。直接编辑[设置文件](/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。

710 711

711## 故障排除712## 故障排除

712 713

discover-plugins.md +3 −1

Details

138 </Step>138 </Step>

139 139

140 <Step title="安装插件">140 <Step title="安装插件">

141 选择一个插件以查看其详细信息，然后选择安装范围：141 选择一个插件以查看其详细信息。{/* min-version: 2.1.143 */}在 Claude Code v2.1.143 及更高版本上，详细信息窗格包括**上下文成本**估计，因此您可以在安装插件之前查看插件将在每个回合中向您的[上下文窗口](/zh-CN/features-overview#understand-context-costs)添加多少个令牌。

142

143 选择安装范围：

142 144

143 * **用户范围**：在所有项目中为自己安装145 * **用户范围**：在所有项目中为自己安装

144 * **项目范围**：为此存储库上的所有协作者安装146 * **项目范围**：为此存储库上的所有协作者安装

env-vars.md +13 −10

Details

100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |

101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |

102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |

103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 设置为 `1` 以在 Claude Opus 4.7 上运行[快速模式](/zh-CN/fast-mode)而不是 Opus 4.6。设置此变量后，`/fast` 切换到 Opus 4.7；没有它，`/fast` 继续使用 Opus 4.6 |103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 在 v2.1.142 中移除。[快速模式](/zh-CN/fast-mode)默认为 Opus 4.7。设置 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` 以保持 Opus 4.6 |

104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |

105| `CLAUDE_CODE_ENABLE_TASKS` | 设置为 `1` 以在非交互模式（`-p` 标志）中启用任务跟踪系统。任务在交互模式中默认启用。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |105| `CLAUDE_CODE_ENABLE_TASKS` | 控制会话是否使用结构化 Task 工具（`TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList`）或旧版 `TodoWrite` 工具。从 Claude Code v2.1.142 开始，Task 工具是所有模式中的默认工具。设置为 `0` 以恢复为 `TodoWrite`。请参阅[任务列表](/zh-CN/interactive-mode#task-list)和[迁移到 Task 工具](/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools) |

106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用 OpenTelemetry 数据收集以获取指标和日志。在配置 OTel 导出器之前需要。请参阅[监控](/zh-CN/monitoring-usage) |106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用 OpenTelemetry 数据收集以获取指标和日志。在配置 OTel 导出器之前需要。请参阅[监控](/zh-CN/monitoring-usage) |

130| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对于在自动化环境中配置身份验证很有用 |130| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对于在自动化环境中配置身份验证很有用 |

131| `CLAUDE_CODE_OAUTH_SCOPES` | 刷新令牌颁发时使用的空格分隔的 OAuth 作用域，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时为必需 |131| `CLAUDE_CODE_OAUTH_SCOPES` | 刷新令牌颁发时使用的空格分隔的 OAuth 作用域，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时为必需 |

132| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 身份验证的 OAuth 访问令牌。`/login` 对于 SDK 和自动化环境的替代方案。优先于钥匙链存储的凭证。使用 [`claude setup-token`](/zh-CN/authentication#generate-a-long-lived-token) 生成一个 |132| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 身份验证的 OAuth 访问令牌。`/login` 对于 SDK 和自动化环境的替代方案。优先于钥匙链存储的凭证。使用 [`claude setup-token`](/zh-CN/authentication#generate-a-long-lived-token) 生成一个 |

133| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 设置为 `1` 以保持[快速模式](/zh-CN/fast-mode)在 Claude Opus 4.6 上。优先于 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`，所以如果您需要固定 Opus 4.6 无论默认如何变化，请设置此选项 |133| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 设置为 `1` 以将[快速模式](/zh-CN/fast-mode)固定到 Claude Opus 4.6 而不是默认的 Opus 4.7。设置此变量后，`/fast` 在 Opus 4.6 上运行。没有它，`/fast` 在 Opus 4.7 上运行 |

134| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry spans 的超时时间（以毫秒为单位）（默认值：5000）。请参阅[监控](/zh-CN/monitoring-usage) |134| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry spans 的超时时间（以毫秒为单位）（默认值：5000）。请参阅[监控](/zh-CN/monitoring-usage) |

135| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（以毫秒为单位）（默认值：1740000 / 29 分钟）。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) |135| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（以毫秒为单位）（默认值：1740000 / 29 分钟）。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) |

136| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（以毫秒为单位）（默认值：2000）。如果在退出时丢弃指标，请增加此值。请参阅[监控](/zh-CN/monitoring-usage) |136| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（以毫秒为单位）（默认值：2000）。如果在退出时丢弃指标，请增加此值。请参阅[监控](/zh-CN/monitoring-usage) |

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

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

144| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在生成 PowerShell 以进行工具调用、hooks 和状态行命令时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下，Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。无论此设置如何，进程范围的绕过永远不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |

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

153| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程中自动设置为当前会话 ID。与传递给 [hooks](/zh-CN/hooks) 的 `session_id` 字段匹配。在 `/clear` 时更新。用于将脚本和外部工具与启动它们的 Claude Code 会话相关联 |154| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程中自动设置为当前会话 ID。与传递给 [hooks](/zh-CN/hooks) 的 `session_id` 字段匹配。在 `/clear` 时更新。用于将脚本和外部工具与启动它们的 Claude Code 会话相关联 |

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>` 运行 |156| `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>` 运行 |

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 标志设置此选项 |157| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。OAuth 令牌和钥匙链凭证不被读取，所以 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/zh-CN/headless#start-faster-with-bare-mode) |

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

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

162| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话转录写入磁盘。使用此变量启动的会话不会出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |163| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话转录写入磁盘。使用此变量启动的会话不会出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |

165| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-CN/hooks#stop) 或 [SubagentStop](/zh-CN/hooks#subagentstop) hook 可能在 Claude Code 覆盖它并无论如何结束转换之前阻止转换结束的最大连续次数（默认值：8）。设置为 `0` 以禁用上限。如果您的 hook 合法需要更多迭代来解决，请提高此值 |

165| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |167| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |

166| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 设置为 `1` 在非交互模式（`-p` 标志）中等待插件安装完成后再进行第一个查询。没有这个，插件在后台安装，可能在第一个回合不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待时间 |168| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 设置为 `1` 在非交互模式（`-p` 标志）中等待插件安装完成后再进行第一个查询。没有这个，插件在后台安装，可能在第一个回合不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待时间 |

180| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、凭证、会话历史和插件都存储在此路径下。对于并行运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |182| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、凭证、会话历史和插件都存储在此路径下。对于并行运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

181| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为该转换的活动[努力级别](/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hooks](/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持努力参数时设置 |183| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为该转换的活动[努力级别](/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hooks](/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持努力参数时设置 |

182| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 连接默认启用。字节监视程序在 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的持续时间内没有字节到达线路时中止连接，最少 5 分钟，独立于事件级监视程序 |184| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 连接默认启用。字节监视程序在 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的持续时间内没有字节到达线路时中止连接，最少 5 分钟，独立于事件级监视程序 |

183| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `1` 以启用事件级流式空闲监视程序。默认关闭。对于 Bedrock、Vertex 和 Foundry，这是唯一可用的空闲监视程序。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |185| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

186| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `1` 以启用事件级流式空闲监视程序。默认关闭。对于所有提供商，包括 Bedrock。对于 Vertex 和 Foundry，这是唯一可用的空闲监视程序。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 启用独立的字节级监视程序；当两者都设置时，它们一起运行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

184| `CLAUDE_ENV_FILE` | Claude Code 在每个 Bash 命令之前在同一 shell 进程中运行的 shell 脚本的路径，因此文件中的导出对命令可见。用于在命令之间保持 virtualenv 或 conda 激活。也由 [SessionStart](/zh-CN/hooks#persist-environment-variables)、[Setup](/zh-CN/hooks#setup)、[CwdChanged](/zh-CN/hooks#cwdchanged) 和 [FileChanged](/zh-CN/hooks#filechanged) hooks 动态填充 |187| `CLAUDE_ENV_FILE` | Claude Code 在每个 Bash 命令之前在同一 shell 进程中运行的 shell 脚本的路径，因此文件中的导出对命令可见。用于在命令之间保持 virtualenv 或 conda 激活。也由 [SessionStart](/zh-CN/hooks#persist-environment-variables)、[Setup](/zh-CN/hooks#setup)、[CwdChanged](/zh-CN/hooks#cwdchanged) 和 [FileChanged](/zh-CN/hooks#filechanged) hooks 动态填充 |

185| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当未提供显式名称时，自动生成的[远程控制](/zh-CN/remote-control)会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |188| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当未提供显式名称时，自动生成的[远程控制](/zh-CN/remote-control)会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |

186| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。默认和最小 `300000`（5 分钟）对于字节级和事件级监视程序；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。对于第三方提供商，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |189| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。默认和最小 `300000`（5 分钟）对于字节级和事件级监视程序；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。对于第三方提供商，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`。在 Bedrock 上，也在 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 时应用 |

187| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式如 `DEBUG=express:*` 不会触发它 |190| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式如 `DEBUG=express:*` 不会触发它 |

210| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |213| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |

211| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |214| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |

213| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟并发送 beta 标头，在 Vertex AI 或不支持 `tool_reference` 的代理上请求失败）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |216| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟并发送 beta 标头，在 Vertex AI 上支持 Sonnet 4.5 及更高版本或 Opus 4.5 及更高版本的请求失败，或在不支持 `tool_reference` 的代理上）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |

214| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退到 [`--fallback-model`](/zh-CN/cli-reference#cli-flags)。默认情况下，仅 Opus 模型触发回退 |217| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退到 [`--fallback-model`](/zh-CN/cli-reference#cli-flags)。默认情况下，仅 Opus 模型触发回退 |

221| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应无法针对非交互模式（`-p` 标志）中的 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 进行验证时重试的次数。默认为 5 |224| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应无法针对非交互模式（`-p` 标志）中的 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 进行验证时重试的次数。默认为 5 |

222| `MAX_THINKING_TOKENS` | 覆盖[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)令牌预算。上限是模型的[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)减一。设置为 `0` 以完全禁用思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，除非通过 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 禁用自适应推理，否则预算被忽略 |225| `MAX_THINKING_TOKENS` | 覆盖[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)令牌预算。上限是模型的[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)减一。设置为 `0` 以完全禁用思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，除非通过 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 禁用自适应推理，否则预算被忽略 |

223| `MCP_CLIENT_SECRET` | 需要[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |226| `MCP_CLIENT_SECRET` | 需要[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |

224| `MCP_CONNECTION_NONBLOCKING` | 设置为 `true` 在非交互模式（`-p`）中完全跳过 MCP 连接等待。对于不需要 MCP 工具的脚本化管道很有用。没有此变量，第一个查询会等待最多 5 秒以获得 `--mcp-config` 服务器连接。服务器配置为 [`alwaysLoad: true`](/zh-CN/mcp#exempt-a-server-from-deferral) 始终阻止启动，无论此变量如何，因为它们的工具必须在构建第一个提示时存在 |227| `MCP_CONNECTION_NONBLOCKING` | 控制启动是否等待 MCP 服务器在第一个查询之前连接。从 Claude Code v2.1.142 开始，MCP 启动默认为非阻塞：服务器在后台连接，其工具在完成时变为可用。设置为 `0` 以恢复阻塞 5 秒连接等待。配置为 [`alwaysLoad: true`](/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器始终阻止启动，无论此变量如何，因为它们的工具必须在构建第一个提示时存在 |

225| `MCP_CONNECT_TIMEOUT_MS` | 第一个查询等待 MCP 连接批处理的时间（以毫秒为单位），然后快照工具列表（默认值：5000）。在截止时间处仍待处理的服务器继续在后台连接，但在下一个查询之前不会出现。与 `MCP_TIMEOUT` 不同，后者限制单个服务器的连接尝试。最相关的是需要慢速连接服务器可见的非交互式会话，这些会话发出单个查询 |228| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 启动等待连接批处理的时间（以毫秒为单位），然后快照工具列表（默认值：5000）。在截止时间处仍待处理的服务器继续在后台连接，但在下一个查询之前不会出现。与 `MCP_TIMEOUT` 不同，后者限制单个服务器的连接尝试 |

226| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在使用[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时 `--callback-port` 的替代方案 |229| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在使用[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时 `--callback-port` 的替代方案 |

errors.md +8 −6

Details

162 162

163这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的[服务器错误](#server-errors)不同。163这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的[服务器错误](#server-errors)不同。

164 164

165### You've hit your session limit165### 您已达到会话限制

166 166

167订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：167订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：

168 168

178 178

179* 等待错误中显示的重置时间179* 等待错误中显示的重置时间

180* 运行 `/usage` 以查看您的计划限制以及它们何时重置180* 运行 `/usage` 以查看您的计划限制以及它们何时重置

181* 运行 `/extra-usage` 以在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅[付费计划的额外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。181* 运行 `/usage-credits` 以在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅[付费计划的使用信用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

182* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)182* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)

183 183

184要在达到限制之前监视您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用环](/zh-CN/desktop#check-usage)。184要在达到限制之前监视您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用环](/zh-CN/desktop#check-usage)。

185 185

186### Server is temporarily limiting requests186### 服务器暂时限制请求

187 187

188API 应用了与您的计划配额无关的短期限流。188API 应用了与您的计划配额无关的短期限流。

189 189

198* 等待片刻后重试198* 等待片刻后重试

199* 如果持续存在，请检查 [status.claude.com](https://status.claude.com)199* 如果持续存在，请检查 [status.claude.com](https://status.claude.com)

200 200

201### Request rejected (429)201### 请求被拒绝 (429)

202 202

203您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。203您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。

204 204

205```text theme={null}205```text theme={null}

206API Error: Request rejected (429) · this may be a temporary capacity issue206API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check status.claude.com.

207```207```

208 208

209尾部句子命名了检查服务健康的位置，并因提供商而异。Bedrock 和 Vertex AI 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。

210

209**要做什么：**211**要做什么：**

210 212

211* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。213* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。

213* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)以了解层级如何工作以及如何设置每个工作区的上限215* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)以了解层级如何工作以及如何设置每个工作区的上限

214* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行高容量脚本运行216* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行高容量脚本运行

215 217

216### Credit balance is too low218### 信用余额过低

217 219

218您的 Console 组织已用完预付信用。220您的 Console 组织已用完预付信用。

219 221

fast-mode.md +14 −48

Details

12 12

13快速模式是 Claude Opus 的高速配置，使模型速度提高 2.5 倍，但每个令牌的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。13快速模式是 Claude Opus 的高速配置，使模型速度提高 2.5 倍，但每个令牌的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。

14 14

15快速模式不是一个不同的模型。它使用 Claude Opus，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。快速模式在 Opus 4.6 和 Opus 4.7 上受支持。它在 Sonnet、Haiku 或其他模型上不可用。15快速模式不是一个不同的模型。它使用 Claude Opus，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。快速模式在 Opus 4.7 和 Opus 4.6 上受支持。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17<Note>17<Note>

18 快速模式需要 Claude Code v2.1.36 或更高版本。使用 `claude --version` 检查您的版本。18 快速模式需要 Claude Code v2.1.36 或更高版本。使用 `claude --version` 检查您的版本。

21需要了解的内容：21需要了解的内容：

22 22

23* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。也可通过 Claude Code VS Code 扩展中的 `/fast` 使用。23* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。也可通过 Claude Code VS Code 扩展中的 `/fast` 使用。

~~24* 默认情况下，`/fast` 在 Opus 4.6 上运行。要改为在 Opus 4.7 上运行快速模式，请设置 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 环境变量。~~24* 快速模式定价在 Opus 4.7 和 Opus 4.6 上都是 $30/$150 MTok。

~~25* 快速模式定价在 Opus 4.6 和 Opus 4.7 上都是 \$30/150 MTok。~~

26* 可供订阅计划（Pro/Max/Team/Enterprise）上的所有 Claude Code 用户和 Claude 控制台使用。25* 可供订阅计划（Pro/Max/Team/Enterprise）上的所有 Claude Code 用户和 Claude 控制台使用。

~~27* 对于订阅计划（Pro/Max/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过额外使用提供，不包含在订阅速率限制中。~~26* 对于订阅计划（Pro/Max/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过使用额度提供，不包含在订阅速率限制中。

28 27

29本页涵盖如何[切换快速模式](#toggle-fast-mode)、[在 Opus 4.7 上使用快速模式](#use-fast-mode-on-opus-4-7)、[成本权衡](#understand-the-cost-tradeoff)、[何时使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每个会话选择加入](#require-per-session-opt-in)和[速率限制行为](#handle-rate-limits)。28本页涵盖如何[切换快速模式](#toggle-fast-mode)、其[成本权衡](#understand-the-cost-tradeoff)、[何时使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每个会话选择加入](#require-per-session-opt-in)和[速率限制行为](#handle-rate-limits)。

30 29

31## 切换快速模式30## 切换快速模式

32 31

41 40

42启用快速模式时：41启用快速模式时：

43 42

44* 如果您使用的是不同的模型，Claude Code 会自动切换到快速模式模型：默认为 Opus 4.6，或在设置 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 时为 Opus 4.7。43* 如果您使用的是不同的模型，Claude Code 会自动切换到 Opus

45* 您将看到确认消息："Fast mode ON"44* 您将看到确认消息："Fast mode ON"

46* 快速模式处于活动状态时，提示旁边会出现一个小的 `↯` 图标45* 快速模式处于活动状态时，提示旁边会出现一个小的 `↯` 图标

47* 随时再次运行 `/fast` 以检查快速模式是否打开或关闭46* 随时再次运行 `/fast` 以检查快速模式是否打开或关闭

48 47

49当您再次使用 `/fast` 禁用快速模式时，您仍然保持在快速模式运行的同一 Opus 版本上。模型不会恢复到您之前的模型。要切换到不同的模型，请使用 `/model`。48当您再次使用 `/fast` 禁用快速模式时，您仍然保持在 Opus 上。模型不会恢复到您之前的模型。要切换到不同的模型，请使用 `/model`。

50 49

~~51## 在 Opus 4.7 上使用快速模式~~50Opus 4.7 是 Claude Code v2.1.142 及更高版本中的快速模式默认值。要改为将快速模式固定到 Opus 4.6，请设置 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`。

~~53<Note>~~

~~54 Opus 4.7 上的快速模式需要 Claude Code v2.1.139 或更高版本。~~

~~55</Note>~~

~~57Claude Opus 4.7 的快速模式处于研究预览阶段。它以与 Opus 4.6 快速模式相同的 2.5 倍速度和相同的价格运行，没有其他行为变化。~~

~~59<Note>~~

~~60 在 2026 年 5 月 14 日，Opus 4.7 成为默认的快速模式模型。在此之前，通过设置 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1` 选择加入。~~

~~61</Note>~~

63要选择加入，在启动 Claude Code 之前设置 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`。设置了该变量后，`/fast` 在 Opus 4.7 上运行。没有它，`/fast` 继续在 Opus 4.6 上运行。

~~65您可以将该变量设置为 shell 导出：~~

~~67```bash theme={null}~~

~~68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1~~

~~69```~~

~~71或在任何 Claude Code [设置文件](/zh-CN/settings#settings-files)中，包括用户、项目和托管设置，以限定选择加入的范围：~~

~~73```json theme={null}~~

~~74{~~

~~75 "env": {~~

~~76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"~~

~~77 }~~

~~78}~~

~~79```~~

~~81Opus 4.6 的快速模式仍然可与 Opus 4.7 一起使用。两者共享相同的快速模式速率限制池：任一模型上的使用都会从相同的限制中扣除。~~

83要将快速模式明确固定到 Opus 4.6，设置 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`。此变量优先级最高，因此无论是否设置了 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`，快速模式都会在 Opus 4.6 上运行。

84 51

85## 了解成本权衡52## 了解成本权衡

86 53

87快速模式的每个令牌定价高于标准 Opus：54快速模式的每个令牌定价高于标准 Opus：

88 55

89| 模式 | 输入 (MTok) | 输出 (MTok) |56| 模式 | 输入 (MTok) | 输出 (MTok) |

~~90| --------------- | --------- | --------- |~~57| ---- | --------- | --------- |

~~91| Opus 4.6 上的快速模式 | \$30 | \$150 |~~58| 快速模式 | \$30 | \$150 |

~~92| Opus 4.7 上的快速模式 | \$30 | \$150 |~~

93 59

94快速模式定价在整个 1M 令牌上下文窗口中是固定的。60快速模式定价在整个 1M 令牌上下文窗口中是固定的。

95 61

124 90

125快速模式需要以下所有条件：91快速模式需要以下所有条件：

126 92

127* **第三方云提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可通过 Anthropic 控制台 API 和使用额外使用的 Claude 订阅计划获得。93* **第三方云提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可通过 Anthropic 控制台 API 和使用使用额度的 Claude 订阅计划获得。

128* **启用额外使用**：您的账户必须启用额外使用，这允许在您的计划包含的使用量之外进行计费。对于个人账户，在您的[控制台计费设置](https://platform.claude.com/settings/organization/billing)中启用此功能。对于团队和企业，管理员必须为组织启用额外使用。94* **启用使用额度**：您的账户必须启用使用额度，这允许在您的计划包含的使用量之外进行计费。对于个人账户，在您的[控制台计费设置](https://platform.claude.com/settings/organization/billing)中启用此功能。对于团队和企业，管理员必须为组织启用使用额度。

129 95

130<Note>96<Note>

131 快速模式使用直接计入额外使用，即使您的计划上还有剩余使用量。这意味着快速模式令牌不计入您的计划包含的使用量，并从第一个令牌开始按快速模式费率收费。97 快速模式使用直接计入使用额度，即使您的计划上还有剩余使用量。这意味着快速模式令牌不计入您的计划包含的使用量，并从第一个令牌开始按快速模式费率收费。

132</Note>98</Note>

133 99

134* **团队和企业的管理员启用**：快速模式默认对团队和企业组织禁用。管理员必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。100* **团队和企业的管理员启用**：快速模式默认对团队和企业组织禁用。管理员必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。

160 126

161## 处理速率限制127## 处理速率限制

162 128

163快速模式与标准 Opus 有单独的速率限制。Opus 4.6 和 Opus 4.7 的快速模式共享相同的速率限制池：任一模型上的使用都会从相同的限制中扣除。当您达到快速模式速率限制或用完额外使用额度时：129快速模式与标准 Opus 有单独的速率限制。Opus 4.7 和 Opus 4.6 的快速模式共享相同的速率限制池：任一模型上的使用都会从相同的限制中扣除。当您达到快速模式速率限制或用完使用额度时：

164 130

1651. 快速模式自动回退到同一 Opus 版本上的标准速度1311. 快速模式自动回退到标准速度

1662. `↯` 图标变灰以指示冷却1322. `↯` 图标变灰以指示冷却

1673. 您继续以标准速度和定价工作1333. 您继续以标准速度和定价工作

1684. 冷却过期时，快速模式自动重新启用1344. 冷却过期时，快速模式自动重新启用

features-overview.md +2 −2

Details

271 271

272 **加载内容：** 新鲜、隔离的上下文，包含：272 **加载内容：** 新鲜、隔离的上下文，包含：

273 273

274 * 系统提示（与父级共享以提高缓存效率）274 * agent 的自己的系统提示，而不是完整的 Claude Code 系统提示

275 * agent 的 `skills:` 字段中列出的 skills 的完整内容275 * agent 的 `skills:` 字段中列出的 skills 的完整内容

276 * CLAUDE.md 和 git 状态（从父级继承）276 * CLAUDE.md 和 git 状态，除了内置的 Explore 和 Plan agents [省略两者](/zh-CN/sub-agents#what-loads-at-startup)

277 * 主 agent 在提示中传递的任何上下文277 * 主 agent 在提示中传递的任何上下文

278 278

279 **上下文成本：** 与主会话隔离。Subagents 不继承您的对话历史或调用的 skills。279 **上下文成本：** 与主会话隔离。Subagents 不继承您的对话历史或调用的 skills。

hooks.md +2 −2

Details

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

733input=$(cat)733input=$(cat)

734title="Claude Code'734title="Claude Code'

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

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

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

738```738```

2770 2770

2771对于更细粒度的 hook 匹配详细信息，设置 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看额外的日志行，例如 hook 匹配器计数和查询匹配。2771对于更细粒度的 hook 匹配详细信息，设置 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看额外的日志行，例如 hook 匹配器计数和查询匹配。

2772 2772

2773有关故障排除常见问题，如 hooks 不触发、无限 Stop hook 循环或配置错误，请参阅指南中的[限制和故障排除](/zh-CN/hooks-guide#limitations-and-troubleshooting)。有关涵盖 `/context`、`/doctor` 和设置优先级的更广泛的诊断演练，请参阅[调试你的配置](/zh-CN/debug-your-config)。2773有关故障排除常见问题，如 hooks 不触发、Stop hooks 持续阻止或配置错误，请参阅指南中的[限制和故障排除](/zh-CN/hooks-guide#limitations-and-troubleshooting)。有关涵盖 `/context`、`/doctor` 和设置优先级的更广泛的诊断演练，请参阅[调试你的配置](/zh-CN/debug-your-config)。

hooks-guide.md +5 −3

Details

910* 验证你的 JSON 有效（不允许尾随逗号和注释）910* 验证你的 JSON 有效（不允许尾随逗号和注释）

911* 确认设置文件在正确的位置：`.claude/settings.json` 用于项目 hooks，`~/.claude/settings.json` 用于全局 hooks911* 确认设置文件在正确的位置：`.claude/settings.json` 用于项目 hooks，`~/.claude/settings.json` 用于全局 hooks

912 912

913### Stop hook 永远运行913### Stop hook 达到阻止上限

914 914

915Claude 继续工作在无限循环中而不是停止。915Claude 继续工作而不是停止，然后以警告结束该轮，表示 Stop hook 连续阻止了太多次。

916 916

917你的 Stop hook 脚本需要检查它是否已经触发了继续。从 JSON 输入中解析 `stop_hook_active` 字段，如果为 `true` 则提前退出：917Claude Code 在 Stop hook 连续阻止 8 次而没有进展后会覆盖它。你的 hook 脚本需要检查它是否已经触发了继续。从 JSON 输入中解析 `stop_hook_active` 字段，如果为 `true` 则提前退出：

918 918

919```bash theme={null}919```bash theme={null}

920#!/bin/bash920#!/bin/bash

925# ... 你的 hook 逻辑的其余部分925# ... 你的 hook 逻辑的其余部分

926```926```

927 927

928如果你的 hook 合理地需要超过八次迭代才能收敛，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/zh-CN/env-vars) 提高上限。

929

928### JSON 验证失败930### JSON 验证失败

929 931

930Claude Code 显示 JSON 解析错误，即使你的 hook 脚本输出有效的 JSON。932Claude Code 显示 JSON 解析错误，即使你的 hook 脚本输出有效的 JSON。

mcp.md +3 −1

Details

143 143

144`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。144`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。

145 145

146如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。启用[工具搜索](#scale-with-mcp-tool-search)（这是默认设置）后，等待发生在 `ToolSearch` 调用内部。在没有工具搜索的配置中，例如 Vertex AI、自定义 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 改为使用 `WaitForMcpServers` 工具。

147

146服务器名称 `workspace` 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。148服务器名称 `workspace` 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。

147 149

148### 动态工具更新150### 动态工具更新

1007 1009

1008`alwaysLoad` 字段在所有服务器类型上可用，需要 Claude Code v2.1.121 或更高版本。MCP 服务器也可以通过在工具的 `_meta` 对象中包含 `"anthropic/alwaysLoad": true` 来标记单个工具为始终加载，这对该工具仅具有相同的效果。1010`alwaysLoad` 字段在所有服务器类型上可用，需要 Claude Code v2.1.121 或更高版本。MCP 服务器也可以通过在工具的 `_meta` 对象中包含 `"anthropic/alwaysLoad": true` 来标记单个工具为始终加载，这对该工具仅具有相同的效果。

1009 1011

1010设置 `alwaysLoad: true` 也会阻止启动直到服务器连接，上限为标准 5 秒连接超时。即使设置了 [`MCP_CONNECTION_NONBLOCKING=1`](/zh-CN/env-vars)，这也适用，因为工具必须在构建第一个提示时存在。当启用非阻塞时，其他服务器仍在后台连接。1012设置 `alwaysLoad: true` 也会阻止启动直到服务器连接，上限为标准 5 秒连接超时。即使 MCP 启动在其他方面[默认为非阻塞](/zh-CN/env-vars)，这也适用，因为工具必须在构建第一个提示时存在。其他服务器继续在后台连接。

1011 1013

1012## 将 MCP 提示用作命令1014## 将 MCP 提示用作命令

1013 1015

model-config.md +5 −5

Details

284您可以使用以下环境变量，这些变量必须是完整的**模型名称**（或您的 API 提供商的等效项），以控制别名映射到的模型名称。284您可以使用以下环境变量，这些变量必须是完整的**模型名称**（或您的 API 提供商的等效项），以控制别名映射到的模型名称。

285 285

286| 环境变量 | 描述 |286| 环境变量 | 描述 |

287| -------------------------------- | ----------------------------------------------------------- |287| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |

292 292

293注意：`ANTHROPIC_SMALL_FAST_MODEL` 已弃用，改为使用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。293注意：`ANTHROPIC_SMALL_FAST_MODEL` 已弃用，改为使用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。

294 294

312 312

313对 `ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。313对 `ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。

314 314

315要为固定模型启用[扩展上下文](#extended-context)，请在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的模型 ID 后附加 `[1m]`：315要为固定模型启用[扩展上下文](#extended-context)，请在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的模型 ID 后附加 `[1m]`：

316 316

380}380}

381```381```

382 382

383键必须是[模型概览](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)中列出的 Anthropic 模型 ID。对于带日期的模型 ID，请包含日期后缀，完全按照其显示的方式。未知的键会被忽略。383键必须是[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)中列出的 Anthropic 模型 ID。对于带日期的模型 ID，请包含日期后缀，完全按照其显示的方式。未知的键会被忽略。

384 384

385覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。您直接通过 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量提供的值会按原样传递给提供商，不会被 `modelOverrides` 转换。385覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。您直接通过 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量提供的值会按原样传递给提供商，不会被 `modelOverrides` 转换。

386 386

388 388

389### Prompt caching 配置389### Prompt caching 配置

390 390

391Claude Code 自动使用 [prompt caching](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-caching) 来优化性能并降低成本。您可以全局禁用 prompt caching 或针对特定模型层级禁用：391Claude Code 自动使用 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 来优化性能并降低成本。您可以全局禁用 prompt caching 或针对特定模型层级禁用：

392 392

393| 环境变量 | 描述 |393| 环境变量 | 描述 |

394| ------------------------------- | ----------------------------------------- |394| ------------------------------- | ----------------------------------------- |

overview.md +1 −1

Details

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# Claude Code 概述~~5# 概述

6 6

7> Claude Code 是一个代理编码工具，可以读取你的代码库、编辑文件、运行命令，并与你的开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。7> Claude Code 是一个代理编码工具，可以读取你的代码库、编辑文件、运行命令，并与你的开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。

8 8

permission-modes.md +3 −1

Details

73 | Auto mode | `auto` |73 | Auto mode | `auto` |

74 | Bypass permissions | `bypassPermissions` |74 | Bypass permissions | `bypassPermissions` |

75 75

76 在您在扩展设置中启用**允许危险地跳过权限**后，Auto mode 出现在模式指示器中，但它保持不可用，直到您的账户满足 [auto mode 部分](#eliminate-prompts-with-auto-mode)中列出的每个要求。`claudeCode.initialPermissionMode` 设置不接受 `auto`；要默认以 auto mode 启动，请改为在您的 Claude Code [`settings.json`](/zh-CN/settings#settings-files) 中设置 `defaultMode`。76 在您在扩展设置中启用**允许危险地跳过权限**后，Auto mode 出现在模式指示器中，但它保持不可用，直到您的账户满足 [auto mode 部分](#eliminate-prompts-with-auto-mode)中列出的每个要求。`claudeCode.initialPermissionMode` 设置不接受 `auto`；要默认以 auto mode 启动，请改为在您的[用户设置](/zh-CN/settings#settings-files)中设置 `defaultMode`。Claude Code 忽略项目和本地设置中的 `defaultMode: "auto"`。

77 77

78 Bypass permissions 也需要**允许危险地跳过权限**切换才能在模式指示器中出现。78 Bypass permissions 也需要**允许危险地跳过权限**切换才能在模式指示器中出现。

79 79

179 179

180如果 Claude Code 报告 auto mode 不可用，其中一个要求未满足；这不是暂时中断。一个单独的消息命名一个模型并说 auto mode "cannot determine the safety" 的操作是暂时分类器中断；请参阅[错误参考](/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。180如果 Claude Code 报告 auto mode 不可用，其中一个要求未满足；这不是暂时中断。一个单独的消息命名一个模型并说 auto mode "cannot determine the safety" 的操作是暂时分类器中断；请参阅[错误参考](/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

181 181

182如果您在[设置](/zh-CN/settings#available-settings)中设置 `defaultMode: "auto"` 并且会话以 `default` 模式启动且没有错误，该设置可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code 忽略来自这些文件的 `auto`，因此仓库无法授予自己 auto mode。将其移动到 `~/.claude/settings.json`。

183

182### 分类器默认阻止的内容184### 分类器默认阻止的内容

183 185

184分类器信任您的工作目录和您的仓库的配置的远程。其他所有内容都被视为外部，直到您[配置受信任的基础设施](/zh-CN/auto-mode-config)。186分类器信任您的工作目录和您的仓库的配置的远程。其他所有内容都被视为外部，直到您[配置受信任的基础设施](/zh-CN/auto-mode-config)。

plugin-dependencies.md +24 −0

Details

114 114

115当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。115当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。

116 116

117## 启用或禁用具有依赖的插件

118

119启用插件也会启用它依赖的插件，禁用插件会被阻止，如果另一个已启用的插件仍然需要它。这两种行为都需要 Claude Code v2.1.143 或更高版本。早期版本仅启用或禁用命名的插件，并在下次加载时显示 `dependency-unsatisfied` 错误。

120

121当你启用插件时，Claude Code 也会在同一范围内启用其依赖。如果依赖有自己的依赖，Claude Code 也会启用那些。成功消息会列出与你命名的插件一起启用的其他内容。如果依赖无法启用，命令会拒绝并告诉你什么在阻止以及如何修复：

122

123| 条件 | 结果 |

124| :-------------------------- | :------------------------------------------ |

125| 依赖未安装 | 启用失败并为每个缺失的依赖打印 `claude plugin install` 命令。 |

126| 依赖被你的组织的插件策略阻止 | 启用失败并命名被阻止的依赖。 |

127| 依赖在优先级高于目标范围的范围内设置为 `false` | 启用失败。在该范围内启用依赖，或传递 `--scope` 来在那里写入。 |

128| 所有依赖都已安装且被允许 | 启用成功并为插件和每个在目标范围内尚未启用的依赖写入 `true`。 |

129

130当你禁用插件时，Claude Code 会拒绝，如果另一个已启用的插件仍然依赖它。错误会命名依赖它的插件，并给你一个链式命令，以正确的顺序禁用它们，以你要求的那个结尾。

131

132例如，如果 `deploy-kit` 依赖 `secrets-vault`，单独禁用 `secrets-vault` 会失败，输出类似于以下内容：

133

134```text theme={null}

135secrets-vault is still required by deploy-kit. Disable that plugin first, or

136disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

137```

138

139从错误中复制链式命令以一步禁用完整集合。

140

117## 删除孤立的自动安装依赖141## 删除孤立的自动安装依赖

118 142

119自动安装的依赖在安装它们的插件被卸载后仍会保留在磁盘上，以防你重新安装依赖插件或想继续直接使用该依赖。要清理它们，运行 `claude plugin prune` 来列出不再有任何已安装插件需要的自动安装依赖，并在确认提示后删除它们。这需要 Claude Code v2.1.121 或更高版本。143自动安装的依赖在安装它们的插件被卸载后仍会保留在磁盘上，以防你重新安装依赖插件或想继续直接使用该依赖。要清理它们，运行 `claude plugin prune` 来列出不再有任何已安装插件需要的自动安装依赖，并在确认提示后删除它们。这需要 Claude Code v2.1.121 或更高版本。

plugin-marketplaces.md +2 −1

Details

162 162

163<Note>163<Note>

164 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`knowledge-work-plugins`、`life-sciences`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。164 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。

165</Note>165</Note>

166 166

167### 所有者字段167### 所有者字段

200 200

201| 字段 | 类型 | 描述 |201| 字段 | 类型 | 描述 |

202| :------------ | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |202| :------------ | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |

203| `displayName` | string | {/* min-version: 2.1.143 */}在 UI 界面中显示的人类可读名称。当省略时回退到 `name`。可以包含空格和任何大小写。不用于命名空间或查找。需要 Claude Code v2.1.143 或更高版本。 |

204| `version` | string | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。省略以回退到 git commit SHA。见 [版本解析](#version-resolution-and-release-channels)。 |205| `version` | string | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。省略以回退到 git commit SHA。见 [版本解析](#version-resolution-and-release-channels)。 |

plugins-reference.md +14 −9

Details

20 20

21Plugins 向 Claude Code 添加 skills，创建可由您或 Claude 调用的 `/name` 快捷方式。21Plugins 向 Claude Code 添加 skills，创建可由您或 Claude 调用的 `/name` 快捷方式。

22 22

~~23**位置**：插件根目录中的 `skills/` 或 `commands/` 目录~~23**位置**：插件根目录中的 `skills/` 或 `commands/` 目录，或插件根目录中的单个 `SKILL.md` 文件

24 24

25**文件格式**：Skills 是包含 `SKILL.md` 的目录；commands 是简单的 markdown 文件25**文件格式**：Skills 是包含 `SKILL.md` 的目录；commands 是简单的 markdown 文件

26 26

367```json theme={null}367```json theme={null}

368{368{

369 "name": "plugin-name",369 "name": "plugin-name",

370 "displayName": "Plugin Name",

370 "version": "1.2.0",371 "version": "1.2.0",

371 "description": "Brief plugin description",372 "description": "Brief plugin description",

372 "author": {373 "author": {

411| 字段 | 类型 | 描述 | 示例 |412| 字段 | 类型 | 描述 | 示例 |

412| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |413| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

415| `displayName` | string | {/* min-version: 2.1.143 */}在 `/plugin` 选择器和其他 UI 界面中显示的人类可读名称。当省略时回退到 `name`。与 `name` 不同，可以包含空格和任何大小写。不用于命名空间或查找。需要 Claude Code v2.1.143 或更高版本。 | `"Deployment Tools"` |

416| `author` | object | 作者信息 | `{"name": "Dev Team", "email": "dev@company.com"}` |418| `author` | object | 作者信息 | `{"name": "Dev Team", "email": "dev@company.com"}` |

525* 可以将多个路径指定为数组527* 可以将多个路径指定为数组

526* 当 skill 路径指向直接包含 `SKILL.md` 的目录时，例如 `"skills": ["./"]` 指向 plugin 根目录，frontmatter 中的 `name` 字段确定 skill 的调用名称。这提供了一个稳定的名称，无论安装目录如何。如果 frontmatter 中未设置 `name`，则使用目录基名作为后备。528* 当 skill 路径指向直接包含 `SKILL.md` 的目录时，例如 `"skills": ["./"]` 指向 plugin 根目录，frontmatter 中的 `name` 字段确定 skill 的调用名称。这提供了一个稳定的名称，无论安装目录如何。如果 frontmatter 中未设置 `name`，则使用目录基名作为后备。

527 529

530在其根目录中具有 `SKILL.md`、没有 `skills/` 子目录且没有 `skills` 清单字段的 plugin 在 Claude Code v2.1.142 及更高版本中自动作为单一 skill plugin 加载。您不需要在 `plugin.json` 中设置 `"skills": ["./"]` 来使用此布局。skill 的调用名称遵循与上述相同的规则：frontmatter `name` 字段，或目录基名作为后备。

531

528**路径示例**：532**路径示例**：

529 533

530```json theme={null}534```json theme={null}

785 789

786**别名：** `remove`、`rm`790**别名：** `remove`、`rm`

798**选项：**802**选项：**

799 803

800| 选项 | 描述 | 默认值 |804| 选项 | 描述 | 默认值 |

801| :-------------------- | :-------------------------------- | :----- |805| :-------------------- | :--------------------------------- | :----- |

806 810

807**别名：** `autoremove`811**别名：** `autoremove`

814 818

815### plugin enable819### plugin enable

816 820

817启用已禁用的 plugin。821启用已禁用的 plugin。如果 plugin 声明了[依赖项](/zh-CN/plugin-dependencies)，Claude Code 会在同一范围内以传递方式启用它们，当依赖项未安装时命令会失败。

818 822

819```bash theme={null}823```bash theme={null}

820claude plugin enable <plugin> [options]824claude plugin enable <plugin> [options]

833 837

834### plugin disable838### plugin disable

835 839

836禁用 plugin 而不卸载它。840禁用 plugin 而不卸载它。当另一个已启用的 plugin [依赖于](/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)目标时失败。错误消息包括一个链式命令，首先禁用每个依赖项。

837 841

838```bash theme={null}842```bash theme={null}

839claude plugin disable <plugin> [options]843claude plugin disable <plugin> [options]

889 893

890### plugin details894### plugin details

891 895

892显示 plugin 的组件清单和预计令牌成本。输出列出 plugin 贡献的所有组件，分组为 Skills（技能和命令）、Agents、Hooks 和 MCP servers，以及它为每个会话添加多少令牌的估计。896显示 plugin 的组件清单和预计令牌成本。输出列出 plugin 贡献的所有组件，分组为 Skills、Agents、Hooks、MCP servers 和 LSP servers，以及它为每个会话添加多少令牌的估计。Skills 组包括 `skills/` 和 `commands/` 条目。

893 897

894```bash theme={null}898```bash theme={null}

895claude plugin details <name>899claude plugin details <name>

907 911

908输出为每个组件显示两个成本数字：912输出为每个组件显示两个成本数字：

909 913

910* **Always-on：** plugin 的列表文本（如技能描述、agent 描述和命令名称）添加到每个会话的令牌，无论是否有任何组件触发。914* **Always-on：** plugin 的列表文本（如 skill 描述、agent 描述和命令名称）添加到每个会话的令牌，无论是否有任何组件触发。

911* **On-invoke：** 组件触发时的成本令牌。按组件显示，而不是作为 plugin 总计，因为典型会话仅调用组件的子集。915* **On-invoke：** 组件触发时的成本令牌。按组件显示，而不是作为 plugin 总计，因为典型会话仅调用组件的子集。

912 916

913此示例显示具有两个技能的 plugin 的输出外观：917此示例显示具有两个 skills 的 plugin 的输出外观：

914 918

915```919```

916security-guidance 1.2.0920security-guidance 1.2.0

922 Agents (0)926 Agents (0)

923 Hooks (1) (harness-only — no model context cost)927 Hooks (1) (harness-only — no model context cost)

924 MCP servers (0)928 MCP servers (0)

929 LSP servers (0)

925 930

926Projected token cost931Projected token cost

927 Always-on: ~180 tok added to every session932 Always-on: ~180 tok added to every session

remote-control.md +1 −1

Details

188* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 VS Code 或以其他方式停止 `claude` 进程，会话结束。188* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 VS Code 或以其他方式停止 `claude` 进程，会话结束。

189* **扩展网络中断**：如果您的机器处于唤醒状态但无法在大约 10 分钟以上的时间内到达网络，会话超时并且进程退出。再次运行 `claude remote-control` 以启动新会话。189* **扩展网络中断**：如果您的机器处于唤醒状态但无法在大约 10 分钟以上的时间内到达网络，会话超时并且进程退出。再次运行 `claude remote-control` 以启动新会话。

190* **Ultraplan 断开 Remote Control**：启动 [ultraplan](/zh-CN/ultraplan) 会话会断开任何活动的 Remote Control 会话，因为两个功能都占据 claude.ai/code 界面，一次只能连接一个。190* **Ultraplan 断开 Remote Control**：启动 [ultraplan](/zh-CN/ultraplan) 会话会断开任何活动的 Remote Control 会话，因为两个功能都占据 claude.ai/code 界面，一次只能连接一个。

191* **某些命令仅限本地**：在终端中打开交互式选择器的命令，例如 `/mcp`、`/plugin` 或 `/resume`，仅从本地 CLI 工作。生成文本输出的命令，包括 `/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/extra-usage`、`/recap` 和 `/reload-plugins`，可从移动和网络工作。191* **某些命令仅限本地**：在终端中打开交互式选择器的命令，例如 `/mcp`、`/plugin` 或 `/resume`，仅从本地 CLI 工作。生成文本输出的命令，包括 `/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`，可从移动和网络工作。

192 192

193## 故障排除193## 故障排除

194 194

routines.md +1 −1

Details

360 360

361Routines 以与交互式会话相同的方式消耗订阅使用量。除了标准订阅限制外，routines 还对每个账户每天可以启动多少次运行有上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您当前的消耗和剩余的每日 routine 运行次数。361Routines 以与交互式会话相同的方式消耗订阅使用量。除了标准订阅限制外，routines 还对每个账户每天可以启动多少次运行有上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您当前的消耗和剩余的每日 routine 运行次数。

362 362

363当 routine 达到每日上限或您的订阅使用限制时，启用了额外使用的组织可以继续在计量超额上运行 routines。没有额外使用，额外运行被拒绝，直到窗口重置。从 claude.ai 上的 **Settings > Billing** 启用额外使用。363当 routine 达到每日上限或您的订阅使用限制时，启用了使用额度的组织可以继续在计量超额上运行 routines。没有使用额度，额外运行被拒绝，直到窗口重置。从 claude.ai 上的 **Settings > Billing** 启用使用额度。

364 364

365一次性运行不计入每日 routine 运行上限。它们像任何其他会话一样消耗您的常规订阅使用量，但它们不受每个账户每日 routine 运行配额的限制。365一次性运行不计入每日 routine 运行上限。它们像任何其他会话一样消耗您的常规订阅使用量，但它们不受每个账户每日 routine 运行配额的限制。

366 366

scheduled-tasks.md +1 −1

Details

12 12

13计划任务让 Claude 按间隔自动重新运行提示词。使用它们来轮询部署、监督 PR、检查长时间运行的构建，或在会话中稍后提醒自己做某事。要对事件进行实时反应而不是轮询，请参阅 [Channels](/zh-CN/channels)：您的 CI 可以直接将失败推送到会话中。要保持会话工作转向转向直到满足条件而不是按间隔，请参阅 [`/goal`](/zh-CN/goal)。13计划任务让 Claude 按间隔自动重新运行提示词。使用它们来轮询部署、监督 PR、检查长时间运行的构建，或在会话中稍后提醒自己做某事。要对事件进行实时反应而不是轮询，请参阅 [Channels](/zh-CN/channels)：您的 CI 可以直接将失败推送到会话中。要保持会话工作转向转向直到满足条件而不是按间隔，请参阅 [`/goal`](/zh-CN/goal)。

14 14

15任务是会话范围的：它们存在于当前对话中，当您启动新对话时就会停止。使用 `--resume` 或 `--continue` 恢复会带回任何尚未[过期](#seven-day-expiry)的任务：在过去 7 天内创建的重复任务，或计划时间尚未到达的一次性任务。对于独立于任何会话而存在的调度，请使用 [Routines](/zh-CN/routines)、[Desktop 计划任务](/zh-CN/desktop-scheduled-tasks) 或 [GitHub Actions](/zh-CN/github-actions)。15任务是会话范围的：它们存在于当前对话中，当您启动新对话时就会停止。使用 `--resume` 或 `--continue` 恢复会带回任何尚未[过期](#seven-day-expiry)的任务：在过去 7 天内创建的重复任务，或计划时间尚未到达的一次性任务。对于独立于任何会话而存在的调度，请使用 [Routines](/zh-CN/routines) 在 Anthropic 管理的基础设施上创建例程、设置 [Desktop 计划任务](/zh-CN/desktop-scheduled-tasks)，或使用 [GitHub Actions](/zh-CN/github-actions)。

16 16

17## 比较调度选项17## 比较调度选项

18 18

settings.md +4 −3

Details

265配置 `--worktree` 如何创建和管理 git worktrees。265配置 `--worktree` 如何创建和管理 git worktrees。

266 266

267| 键 | 描述 | 示例 |267| 键 | 描述 | 示例 |

268| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |268| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

269| `worktree.baseRef` | 新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支以获得与远程匹配的干净树。`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和特性分支状态存在于 worktree 中。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |269| `worktree.baseRef` | 新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支以获得与远程匹配的干净树。`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和特性分支状态存在于 worktree 中。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |

272| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[后台会话](/zh-CN/agent-view#how-file-edits-are-isolated)的隔离模式。`"worktree"`（默认）在调用 `EnterWorktree` 之前阻止主检出中的 `Edit`/`Write`。`"none"` 让后台作业直接编辑工作副本。需要 Claude Code v2.1.143 或更高版本 | `"none"` |

272 273

273要将 gitignored 文件（如 `.env`）复制到新的 worktrees，请在项目根目录中使用 [`.worktreeinclude` 文件](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。274要将 gitignored 文件（如 `.env`）复制到新的 worktrees，请在项目根目录中使用 [`.worktreeinclude` 文件](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。

274 275

275### 权限设置276### 权限设置

276 277

277| 键 | 描述 | 示例 |278| 键 | 描述 | 示例 |

278| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |279| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

280| `ask` | 在工具使用时要求确认的权限规则数组。请参阅下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |281| `ask` | 在工具使用时要求确认的权限规则数组。请参阅下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |

281| `deny` | 拒绝工具使用的权限规则数组。使用此排除敏感文件不被 Claude Code 访问。请参阅[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/zh-CN/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |282| `deny` | 拒绝工具使用的权限规则数组。使用此排除敏感文件不被 Claude Code 访问。请参阅[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/zh-CN/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

282| `additionalDirectories` | Claude 有权访问的额外[工作目录](/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |283| `additionalDirectories` | Claude 有权访问的额外[工作目录](/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

283| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/zh-CN/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。`--permission-mode` CLI 标志覆盖此设置用于单个会话 | `"acceptEdits"` |284| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/zh-CN/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。{/* min-version: 2.1.142 */}从 Claude Code v2.1.142 开始，当在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中设置时，`auto` 被忽略，因此存储库无法授予自己自动模式。改为在 `~/.claude/settings.json` 中设置它。`--permission-mode` CLI 标志覆盖此设置用于单个会话 | `"acceptEdits"` |

284| `disableBypassPermissionsMode` | 设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。禁用 `--dangerously-skip-permissions` 标志。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |285| `disableBypassPermissionsMode` | 设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。禁用 `--dangerously-skip-permissions` 标志。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |

285| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入 bypass permissions 模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的存储库自动绕过提示 | `true` |286| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入 bypass permissions 模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的存储库自动绕过提示 | `true` |

286 287

skills.md +3 −3

Details

435Skills 和 [subagents](/zh-CN/sub-agents) 以两个方向协同工作：435Skills 和 [subagents](/zh-CN/sub-agents) 以两个方向协同工作：

436 436

437| 方法 | 系统提示 | 任务 | 也加载 |437| 方法 | 系统提示 | 任务 | 也加载 |

438| :------------------------- | :------------------------- | :----------- | :---------------------- |438| :------------------------- | :--------------------- | :----------- | :----------------------------- |

441 441

442使用 `context: fork`，你在你的 skill 中编写任务并选择一个代理类型来执行它。对于反向（定义使用 skills 作为参考资料的自定义 subagent），请参阅 [Subagents](/zh-CN/sub-agents#preload-skills-into-subagents)。442使用 `context: fork`，你在你的 skill 中编写任务并选择一个代理类型来执行它。内置的 Explore 和 Plan 代理[跳过 CLAUDE.md 和 git 状态](/zh-CN/sub-agents#what-loads-at-startup)以保持其上下文较小，因此使用 `agent: Explore` 的分叉 skill 仅看到 SKILL.md 内容和代理自己的系统提示。对于反向情况，其中你定义使用 skills 作为参考资料的自定义 subagent，请参阅 [Subagents](/zh-CN/sub-agents#preload-skills-into-subagents)。

443 443

444#### 示例：使用 Explore 代理的研究 skill444#### 示例：使用 Explore 代理的研究 skill

445 445

statusline.md +6 −1

Details

916 916

917### Windows 配置917### Windows 配置

918 918

919在 Windows 上，Claude Code 通过 Git Bash 运行状态行命令（如果已安装 Git Bash），或在没有 Git Bash 时通过 PowerShell 运行。要将 PowerShell 脚本作为状态行运行，请通过 `powershell` 调用它；这在任一 shell 中都有效：919在 Windows 上，Claude Code 通过 Git Bash 运行状态行命令（如果已安装 Git Bash），或在没有 Git Bash 时通过 PowerShell 运行。

920

921Git Bash 将未引用的反斜杠视为转义字符，因此 Windows 风格的路径（如 `C:\Users\username\script.mjs`）到达脚本运行器时会删除其分隔符，命令会失败而没有可见的错误。在 `command` 字符串中使用正斜杠编写文件路径，如下面的示例所示。`~` 快捷方式也有效，并扩展到你的 Windows 主目录。

922

923要将 PowerShell 脚本作为状态行运行，请通过 `powershell` 调用它。无论 Claude Code 通过 Git Bash 还是 PowerShell 路由命令，这都有效：

920 924

921<CodeGroup>925<CodeGroup>

922 ```json settings.json theme={null}926 ```json settings.json theme={null}

999* 验证你的脚本是可执行的：`chmod +x ~/.claude/statusline.sh`1003* 验证你的脚本是可执行的：`chmod +x ~/.claude/statusline.sh`

1000* 检查你的脚本输出到 stdout，而不是 stderr1004* 检查你的脚本输出到 stdout，而不是 stderr

1001* 手动运行你的脚本以验证它产生输出1005* 手动运行你的脚本以验证它产生输出

1006* 在安装了 Git Bash 的 Windows 上，`command` 路径中的反斜杠可能在脚本运行前被当作转义字符消耗。在路径中使用正斜杠。参见 [Windows 配置](#windows-configuration)。

1002* 如果 `disableAllHooks` 在你的设置中设置为 `true`，状态行也会被禁用。删除此设置或将其设置为 `false` 以重新启用。1007* 如果 `disableAllHooks` 在你的设置中设置为 `true`，状态行也会被禁用。删除此设置或将其设置为 `false` 以重新启用。

1003* 运行 `claude --debug` 以记录会话中第一次状态行调用的退出代码和 stderr1008* 运行 `claude --debug` 以记录会话中第一次状态行调用的退出代码和 stderr

1004* 要求 Claude 读取你的设置文件并直接执行 `statusLine` 命令以显示错误1009* 要求 Claude 读取你的设置文件并直接执行 `statusLine` 命令以显示错误

sub-agents.md +31 −1

Details

37 37

38Claude Code 包括内置 subagents，Claude 在适当时自动使用。每个都继承父对话的权限，并有额外的工具限制。38Claude Code 包括内置 subagents，Claude 在适当时自动使用。每个都继承父对话的权限，并有额外的工具限制。

39 39

40Explore 和 Plan 会跳过您的 CLAUDE.md 文件和父会话的 git 状态，以保持研究快速且成本低廉。所有其他内置和[自定义 subagent](#configure-subagents) 都会加载两者。有关到达 subagent 的内容的完整分解，请参阅[启动时加载的内容](#what-loads-at-startup)。

40<Tabs>42<Tabs>

41 <Tab title="Explore">43 <Tab title="Explore">

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

652 654

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

654 656

655对于 plugin 提供的 subagent，传递作用域名称：`claude --agent <plugin-name>:<agent-name>`。如果 plugin 将 agent 放在其 `agents/` 目录的子文件夹中，请在作用域名称中包含子文件夹，例如 `claude --agent my-plugin:review:security`。657对于 plugin 提供的 subagent，您可以仅传递代理名称，Claude Code 会找到它：

658

659```bash theme={null}

660claude --agent security-reviewer

661```

662

663如果多个 plugins 提供具有相同名称的 agents，传递作用域名称以消除歧义：

664

665```bash theme={null}

666claude --agent my-plugin:security-reviewer

667```

668

669如果 plugin 将 agent 放在其 `agents/` 目录的子文件夹中，请在作用域名称中包含子文件夹，例如 `claude --agent my-plugin:review:security`。

656 670

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

658 672

741 755

742### 管理 subagent 上下文756### 管理 subagent 上下文

743 757

758#### 启动时加载的内容

759

760每个 subagent 都以新鲜的隔离上下文窗口开始。它看不到您的对话历史、您已经调用的技能或 Claude 已经读取的文件。Claude 编写一条委托消息来总结任务，subagent 从那里开始工作。例外是 [fork](#fork-the-current-conversation)，它继承父对话而不是从头开始。

761

762非 fork subagent 的初始上下文包含：

763

764* **系统提示**：代理自己的提示加上 Claude Code 附加的环境详情，而不是完整的 Claude Code 系统提示。自定义 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 字段中定义它们。内置代理有预定义的提示。

765* **任务消息**：Claude 在移交工作时编写的委托提示。

766* **CLAUDE.md 和内存**：主对话加载的 [内存层次结构](/zh-CN/memory#how-claude-md-files-load) 的每个级别，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md` 和托管策略文件。内置的 Explore 和 Plan 代理跳过这个。

767* **Git 状态**：在父会话开始时拍摄的快照。当工作目录不是 Git 存储库或 [`includeGitInstructions`](/zh-CN/settings#available-settings) 为 `false` 时不存在。Explore 和 Plan 无论如何都跳过它。

768* **预加载的技能**：代理的 [`skills` 字段](#preload-skills-into-subagents) 中命名的任何技能的完整内容。内置代理不预加载技能。

769

770Explore 和 Plan 是仅有的省略 CLAUDE.md 和 git 状态的 subagents。没有 frontmatter 字段或按代理设置来改变哪些代理跳过它们。

771

772主对话使用完整的 CLAUDE.md 上下文读取 Explore 和 Plan 结果，所以大多数规则不需要到达 subagent 本身。如果规则必须，例如"忽略 `vendor/` 目录"，在您给 Claude 委托时的提示中重新陈述它。

773

744#### 恢复 subagents774#### 恢复 subagents

745 775

746每个 subagent 调用都会创建一个具有新鲜上下文的新实例。要继续现有 subagent 的工作而不是重新开始，要求 Claude 恢复它。776每个 subagent 调用都会创建一个具有新鲜上下文的新实例。要继续现有 subagent 的工作而不是重新开始，要求 Claude 恢复它。

tools-reference.md +2 −1

Details

45| `TaskUpdate` | 更新任务状态、依赖项、详细信息或删除任务 | 否 |45| `TaskUpdate` | 更新任务状态、依赖项、详细信息或删除任务 | 否 |

46| `TeamCreate` | 创建一个具有多个队友的 [agent team](/zh-CN/agent-teams)。仅当设置了 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 时可用 | 否 |46| `TeamCreate` | 创建一个具有多个队友的 [agent team](/zh-CN/agent-teams)。仅当设置了 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 时可用 | 否 |

47| `TeamDelete` | 解散 agent team 并清理队友进程。仅当设置了 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 时可用 | 否 |47| `TeamDelete` | 解散 agent team 并清理队友进程。仅当设置了 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 时可用 | 否 |

48| `TodoWrite` | 管理会话任务清单。在非交互模式和 [Agent SDK](/zh-CN/headless) 中可用；交互式会话改用 TaskCreate、TaskGet、TaskList 和 TaskUpdate | 否 |48| `TodoWrite` | {/* min-version: 2.1.142 */}管理会话任务清单。在 v2.1.142 起默认禁用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新启用 | 否 |

49| `ToolSearch` | 当启用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |49| `ToolSearch` | 当启用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |

50| `WaitForMcpServers` | {/* min-version: 2.1.142 */}等待一个或多个仍在后台连接的 [MCP servers](/zh-CN/mcp)，以便请求可以使用它们的工具而无需重启会话。当所需的服务器尚未连接时，Claude 会调用它。仅当禁用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时出现，因为启用时 `ToolSearch` 会处理等待 | 否 |

50| `WebFetch` | 从指定 URL 获取内容。请参阅 [WebFetch 工具行为](#webfetch-tool-behavior) | 是 |51| `WebFetch` | 从指定 URL 获取内容。请参阅 [WebFetch 工具行为](#webfetch-tool-behavior) | 是 |

51| `WebSearch` | 执行网络搜索。请参阅 [WebSearch 工具行为](#websearch-tool-behavior) | 是 |52| `WebSearch` | 执行网络搜索。请参阅 [WebSearch 工具行为](#websearch-tool-behavior) | 是 |

52| `Write` | 创建或覆盖文件。请参阅 [Write 工具行为](#write-tool-behavior) | 是 |53| `Write` | 创建或覆盖文件。请参阅 [Write 工具行为](#write-tool-behavior) | 是 |

ultrareview.md +1 −1

Details

56 56

57Pro 和 Max 订阅者获得三次免费 ultrareview 运行来尝试该功能。这三次运行是每个账户的一次性分配，不会刷新。使用完这三次后，或在免费运行期结束后，每次审查都按额外使用量计费，通常根据更改的大小花费 \$5 到 \$20。一次运行在远程会话启动后计数，因此您提前停止或未能完成的审查仍然会使用一次免费运行。对于付费审查，额外使用量仅对运行的部分计费。57Pro 和 Max 订阅者获得三次免费 ultrareview 运行来尝试该功能。这三次运行是每个账户的一次性分配，不会刷新。使用完这三次后，或在免费运行期结束后，每次审查都按额外使用量计费，通常根据更改的大小花费 \$5 到 \$20。一次运行在远程会话启动后计数，因此您提前停止或未能完成的审查仍然会使用一次免费运行。对于付费审查，额外使用量仅对运行的部分计费。

58 58

59由于 ultrareview 在免费运行之外始终按额外使用量计费，您的账户或组织必须在启动付费审查之前启用额外使用量。如果未启用额外使用量，Claude Code 会阻止启动并将您链接到计费设置，您可以在那里打开它。您也可以运行 `/extra-usage` 来检查或更改您的当前设置。59由于 ultrareview 在免费运行之外始终按额外使用量计费，您的账户或组织必须在启动付费审查之前启用额外使用量。如果未启用额外使用量，Claude Code 会阻止启动并将您链接到计费设置，您可以在那里打开它。您也可以运行 `/usage-credits` 来检查或更改您的当前设置。

60 60

61## 跟踪正在运行的审查61## 跟踪正在运行的审查

62 62

Documentation 2026-05-17 01:01 UTC to 2026-05-18 23:59 UTC