Documentation — Spybara

admin-setup.md +3 −2

Details

174| 主题 | 需要了解的内容 | 从何处开始 |174| 主题 | 需要了解的内容 | 从何处开始 |

175| :- | :- | :- |175| :- | :- | :- |

178| HIPAA configuration | 适用于已启用 HIPAA 的 Claude for Enterprise 组织。部分 Claude Code（本地模式）功能会被关闭，其他功能默认关闭 | [Set up Claude Code (local mode) for a HIPAA-ready organization](/docs/zh-CN/hipaa-setup) |

179 180

180如果您需要请求级别的审计日志或按数据敏感性路由流量，请在开发人员和您的提供商之间放置网关：自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 记录带有 IdP 身份的每个请求审计日志，或使用另一个 [LLM gateway](/docs/zh-CN/llm-gateway)。有关监管要求和认证，请参阅 [Legal and compliance](/docs/zh-CN/legal-and-compliance)。181如果您需要请求级别的审计日志或按数据敏感性路由流量，我们建议您在开发人员和您的提供商之间放置网关：自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 记录带有 IdP 身份的每个请求审计日志，或者您也可以使用另一个 [LLM gateway](/docs/zh-CN/llm-gateway)。通过网关的会话不符合 HIPAA 配置的条件。[Check how developers sign in and connect](/docs/zh-CN/hipaa-setup#check-how-developers-sign-in-and-connect) 列出了符合条件的连接方式。有关监管要求和认证，请参阅 [Legal and compliance](/docs/zh-CN/legal-and-compliance)。

181 182

182<h2 id="verify-and-onboard">183<h2 id="verify-and-onboard">

183 验证和入职184 验证和入职

agent-sdk/cost-tracking.md +4 −0

Details

10 10

11有关完整的 API 文档，请参阅 [TypeScript SDK 参考](/docs/zh-CN/agent-sdk/typescript) 和 [Python SDK 参考](/docs/zh-CN/agent-sdk/python)。11有关完整的 API 文档，请参阅 [TypeScript SDK 参考](/docs/zh-CN/agent-sdk/typescript) 和 [Python SDK 参考](/docs/zh-CN/agent-sdk/python)。

12 12

13<span id="estimates-not-billing" />

13<Warning>15<Warning>

14 `total_cost_usd` 和 `costUSD` 字段是客户端估计值，不是权威的计费数据。SDK 从在构建时捆绑的价格表中本地计算它们，除非 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表生效。当以下情况发生时，它们可能与您实际被计费的金额不同：16 `total_cost_usd` 和 `costUSD` 字段是客户端估计值，不是权威的计费数据。SDK 从在构建时捆绑的价格表中本地计算它们，除非 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表生效。当以下情况发生时，它们可能与您实际被计费的金额不同：

15 17

242* **独立调用，没有 `resume` 或 `continue` 选项**：每个结果仅涵盖其自己的调用，因此您需要自己添加总计，如下面的示例所做的那样。244* **独立调用，没有 `resume` 或 `continue` 选项**：每个结果仅涵盖其自己的调用，因此您需要自己添加总计，如下面的示例所做的那样。

243* **恢复同一会话的调用**：Claude Code 在进程正常退出时将会话的总计保存到其[记录](/docs/zh-CN/sessions#where-transcripts-are-stored)，并在稍后的调用恢复或分叉会话时恢复它们。每个结果已经包括会话的早期支出。读取会话的最新结果以获得会话总计；对结果求和会重复计算恢复的支出。在 v2.1.277 之前，通过 SDK 或 `claude -p` 恢复的会话将其总计从零开始，因此每个调用的结果仅涵盖该调用。245* **恢复同一会话的调用**：Claude Code 在进程正常退出时将会话的总计保存到其[记录](/docs/zh-CN/sessions#where-transcripts-are-stored)，并在稍后的调用恢复或分叉会话时恢复它们。每个结果已经包括会话的早期支出。读取会话的最新结果以获得会话总计；对结果求和会重复计算恢复的支出。在 v2.1.277 之前，通过 SDK 或 `claude -p` 恢复的会话将其总计从零开始，因此每个调用的结果仅涵盖该调用。

244 246

247无论哪种情况，合并后的数值仍然是[客户端估算值](#estimates-not-billing)。

248

245在流式输入模式下，按照[在流式输入模式下跟踪成本](#track-costs-in-streaming-input-mode)中的说明读取每个调用的总计。对于以崩溃结束的调用，请参阅[在会话崩溃后恢复总计](#recover-totals-after-a-session-crash)。249在流式输入模式下，按照[在流式输入模式下跟踪成本](#track-costs-in-streaming-input-mode)中的说明读取每个调用的总计。对于以崩溃结束的调用，请参阅[在会话崩溃后恢复总计](#recover-totals-after-a-session-crash)。

246 250

247以下示例按顺序运行两个 `query()` 调用，将每个调用的 `total_cost_usd` 添加到运行总计中，并打印每个调用和合并的成本：251以下示例按顺序运行两个 `query()` 调用，将每个调用的 `total_cost_usd` 添加到运行总计中，并打印每个调用和合并的成本：

agent-sdk/custom-tools.md +78 −12

Details

15| 如果您想... | 执行此操作 |15| 如果您想... | 执行此操作 |

16| :- | :- |16| :- | :- |

17| 定义工具 | 使用 [`@tool`](/docs/zh-CN/agent-sdk/python#tool)（Python）或 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool)（TypeScript），包含名称、描述、架构和处理程序。请参阅[创建自定义工具](#create-a-custom-tool)。 |17| 定义工具 | 使用 [`@tool`](/docs/zh-CN/agent-sdk/python#tool)（Python）或 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool)（TypeScript），包含名称、描述、架构和处理程序。请参阅[创建自定义工具](#create-a-custom-tool)。 |

18| 将参数设为可选 | 在 schema 中将其声明为可选，并在处理程序中应用默认值。请参阅[将参数设为可选](#make-a-parameter-optional)。 |

18| 向 Claude 注册工具 | 在 `create_sdk_mcp_server` / `createSdkMcpServer` 中包装并传递给 `query()` 中的 `mcpServers`。请参阅[调用自定义工具](#call-a-custom-tool)。 |19| 向 Claude 注册工具 | 在 `create_sdk_mcp_server` / `createSdkMcpServer` 中包装并传递给 `query()` 中的 `mcpServers`。请参阅[调用自定义工具](#call-a-custom-tool)。 |

19| 预先批准工具 | 添加到您的允许工具列表。请参阅[配置允许的工具](#configure-allowed-tools)。 |20| 预先批准工具 | 添加到您的允许工具列表。请参阅[配置允许的工具](#configure-allowed-tools)。 |

20| 从 Claude 的上下文中删除内置工具 | 传递仅列出您想要的内置工具的 `tools` 数组。请参阅[配置允许的工具](#configure-allowed-tools)。 |21| 从 Claude 的上下文中删除内置工具 | 传递仅列出您想要的内置工具的 `tools` 数组。请参阅[配置允许的工具](#configure-allowed-tools)。 |

32 33

33* **名称：** Claude 用来调用工具的唯一标识符。34* **名称：** Claude 用来调用工具的唯一标识符。

34* **描述：** 工具的功能。Claude 读取此内容以决定何时调用它。35* **描述：** 工具的功能。Claude 读取此内容以决定何时调用它。

35* **输入模式：** Claude 必须提供的参数。在 TypeScript 中，这始终是一个 [Zod schema](https://zod.dev/)，处理程序的 `args` 会自动从中获得类型。在 Python 中，这是一个将名称映射到类型的字典，如 `{"latitude": float}`，SDK 会为您将其转换为 JSON Schema。Python 装饰器还接受完整的 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 字典，当您需要枚举、范围、可选字段或嵌套对象时。36* **输入 schema：** 工具接受的参数，按语言分别声明：

37 * **TypeScript**：一个 [Zod schema](https://zod.dev/)。处理程序的 `args` 从中获得类型。对字段调用 `.describe()` 可为其添加 Claude 能看到的描述。

38 * **Python**：一个将名称映射到类型的字典，如 `{"latitude": float}`，SDK 会为您将其转换为 JSON Schema。将类型包装在 `Annotated` 中，如 `{"latitude": Annotated[float, "Latitude coordinate"]}`，可为字段添加 Claude 能看到的描述。当您需要枚举、范围、可选字段或嵌套对象时，装饰器还可以直接接受完整的 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 字典。

36* **处理程序：** 当 Claude 调用工具时运行的异步函数。它接收验证的参数，必须返回一个包含以下内容的对象：39* **处理程序：** 当 Claude 调用工具时运行的异步函数。它接收验证的参数，必须返回一个包含以下内容的对象：

37 * `content`（必需）：结果块数组，每个块的 `type` 为 `"text"`、`"image"`、`"audio"`、`"resource"` 或 `"resource_link"`。有关非文本块，请参阅[返回图像和资源](#return-images-and-resources)。40 * `content`（必需）：结果块数组，每个块的 `type` 为 `"text"`、`"image"`、`"audio"`、`"resource"` 或 `"resource_link"`。有关非文本块，请参阅[返回图像和资源](#return-images-and-resources)。

38 * `structuredContent`（可选）：包含结果作为机器可读数据的 JSON 对象，与 `content` 一起返回。请参阅[返回结构化数据](#return-structured-data)。41 * `structuredContent`（可选）：包含结果作为机器可读数据的 JSON 对象，与 `content` 一起返回。请参阅[返回结构化数据](#return-structured-data)。

40 43

41定义工具后，使用 [`createSdkMcpServer`](/docs/zh-CN/agent-sdk/typescript#createsdkmcpserver)（TypeScript）或 [`create_sdk_mcp_server`](/docs/zh-CN/agent-sdk/python#create_sdk_mcp_server)（Python）将其包装在服务器中。服务器在应用程序内部进程中运行，而不是作为单独的进程运行。44定义工具后，使用 [`createSdkMcpServer`](/docs/zh-CN/agent-sdk/typescript#createsdkmcpserver)（TypeScript）或 [`create_sdk_mcp_server`](/docs/zh-CN/agent-sdk/python#create_sdk_mcp_server)（Python）将其包装在服务器中。服务器在应用程序内部进程中运行，而不是作为单独的进程运行。

42 45

46本页中发出 HTTP 请求的 Python 示例使用 [httpx](https://www.python-httpx.org/)。请使用您项目所用的包管理器添加它：

48<Tabs>

49 <Tab title="Python (uv)">

50 ```bash theme={null}

51 uv add httpx

52 ```

53 </Tab>

55 <Tab title="Python (pip)">

56 ```bash theme={null}

57 pip install httpx

58 ```

59 </Tab>

60</Tabs>

43<h3 id="weather-tool-example">62<h3 id="weather-tool-example">

44 天气工具示例63 天气工具示例

45</h3>64</h3>

46 65

47此示例定义了一个 `get_temperature` 工具并将其包装在 MCP 服务器中。它仅设置工具；要将其传递给 `query` 并运行它，请参阅下面的[调用自定义工具](#call-a-custom-tool)。66此示例定义了一个 `get_temperature` 工具并将其包装在 MCP 服务器中，但没有将服务器传递给 `query`。要运行该工具，请参阅下面的[调用自定义工具](#call-a-custom-tool)。

48 67

49<CodeGroup>68<CodeGroup>

50 ```python Python theme={null}69 ```python Python theme={null}

~~51 from typing import Any~~70 from typing import Annotated, Any

52 import httpx71 import httpx

53 from claude_agent_sdk import tool, create_sdk_mcp_server72 from claude_agent_sdk import tool, create_sdk_mcp_server

54 73

57 @tool(76 @tool(

58 "get_temperature",77 "get_temperature",

59 "Get the current temperature at a location",78 "Get the current temperature at a location",

~~60 {"latitude": float, "longitude": float},~~79 {

80 "latitude": Annotated[float, "Latitude coordinate"],

81 "longitude": Annotated[float, "Longitude coordinate"],

82 },

61 )83 )

62 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:84 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:

63 async with httpx.AsyncClient() as client:85 async with httpx.AsyncClient() as client:

128 150

129有关完整的参数详细信息，包括 JSON Schema 输入格式和返回值结构，请参阅 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool) TypeScript 参考或 [`@tool`](/docs/zh-CN/agent-sdk/python#tool) Python 参考。151有关完整的参数详细信息，包括 JSON Schema 输入格式和返回值结构，请参阅 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool) TypeScript 参考或 [`@tool`](/docs/zh-CN/agent-sdk/python#tool) Python 参考。

130 152

131<Tip>153<h3 id="make-a-parameter-optional">

132 要使参数可选：在 TypeScript 中，向 Zod 字段添加 `.optional()`，并在处理程序中应用默认值。在 Python 中，字典模式将每个键视为必需的，因此将参数从模式中省略，在描述字符串中提及它，并在处理程序中使用 `args.get()` 读取它。下面的 [`get_precipitation_chance` 工具](#add-more-tools)展示了两种模式。154 使参数可选

133</Tip>155</h3>

156

157要使参数可选，请在 schema 中将其声明为可选，并在处理程序中应用默认值：

158

159* **TypeScript**：向 Zod 字段添加 `.optional()`。

160* **Python**：字典 schema 要求每个键都必须提供。请使用 JSON Schema 形式，将该参数从 `required` 中省略，并使用 `args.get()` 读取它。如需带有可选键的类型化 schema，请参阅 [TypedDict 类](/docs/zh-CN/agent-sdk/python#input-schema-options)。

161

162下面的 [`get_precipitation_chance` 工具](#add-more-tools)展示了这两种写法。

134 163

135<h3 id="call-a-custom-tool">164<h3 id="call-a-custom-tool">

136 调用自定义工具165 调用自定义工具

182 ```211 ```

183</CodeGroup>212</CodeGroup>

184 213

185将此代码片段与[天气工具示例](#weather-tool-example)中的工具和服务器定义结合在一个文件中，然后使用 `python weather.py`（Python）或 `npx tsx weather.ts`（TypeScript）运行它。Claude 调用 `get_temperature`，脚本打印一行答案，显示旧金山的当前温度。214将此代码片段与[天气工具示例](#weather-tool-example)中的工具和服务器定义合并到一个文件（`weather.py` 或 `weather.ts`）中，然后在终端中运行它：

215

216<Tabs>

217 <Tab title="TypeScript">

218 ```bash theme={null}

219 npx tsx weather.ts

220 ```

221 </Tab>

222

223 <Tab title="Python (uv)">

224 ```bash theme={null}

225 uv run weather.py

226 ```

227 </Tab>

228

229 <Tab title="Python (pip)">

230 激活您安装了 SDK 的虚拟环境，然后运行：

231

232 ```bash theme={null}

233 python weather.py

234 ```

235 </Tab>

236</Tabs>

237

238Claude 调用 `get_temperature`，脚本打印一行答案，显示旧金山的当前温度。

186 239

187<h3 id="add-more-tools">240<h3 id="add-more-tools">

188 添加更多工具241 添加更多工具

197 # Define a second tool for the same server250 # Define a second tool for the same server

198 @tool(251 @tool(

199 "get_precipitation_chance",252 "get_precipitation_chance",

200 "Get the hourly precipitation probability for a location. "253 "Get the hourly precipitation probability for a location",

201 "Optionally pass 'hours' (1-24) to control how many hours to return.",254 {

202 {"latitude": float, "longitude": float},255 "type": "object",

256 "properties": {

257 "latitude": {"type": "number"},

258 "longitude": {"type": "number"},

259 "hours": {

260 "type": "integer",

261 "minimum": 1,

262 "maximum": 24,

263 "description": "How many hours of forecast to return",

264 },

265 },

266 # 'hours' is left out of required, so Claude can omit it

267 "required": ["latitude", "longitude"],

268 },

203 )269 )

204 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:270 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:

205 # 'hours' isn't in the schema - read it with .get() to make it optional271 # 'hours' isn't in required - read it with .get() to fall back to a default

206 hours = args.get("hours", 12)272 hours = args.get("hours", 12)

207 async with httpx.AsyncClient() as client:273 async with httpx.AsyncClient() as client:

208 response = await client.get(274 response = await client.get(

agent-sdk/python.md +25 −0

Details

147 }147 }

148 ```148 ```

149 149

1503. **TypedDict 类**：一种类型化的 schema，其中 `NotRequired` 键不会包含在 `required` 中。

151

152 * **Python 3.11 及更高版本**：从 `typing` 导入 `TypedDict` 和 `NotRequired`。

153 * **Python 3.10**：`typing` 中没有 `NotRequired`。请从 `typing_extensions` 导入 `TypedDict` 和 `NotRequired`，SDK 会在 Python 3.10 上安装该包。

154

155 ```python theme={null}

156 from typing import Annotated, Any, NotRequired, TypedDict

157 from claude_agent_sdk import tool

158

159

160 class ForecastArgs(TypedDict):

161 latitude: Annotated[float, "Latitude coordinate"]

162 hours: NotRequired[Annotated[int, "How many hours of forecast to return"]]

163

164

165 @tool("get_forecast", "Get the hourly forecast for a location", ForecastArgs)

166 async def get_forecast(args: dict[str, Any]) -> dict[str, Any]:

167 hours = args.get("hours", 12)

168 return {"content": [{"type": "text", "text": f"{hours}-hour forecast for {args['latitude']}"}]}

169 ```

170

171在简单映射和 TypedDict 形式中，将类型包装在 `Annotated[type, "description"]` 中即可设置该字段的描述。

172

150<h4 id="returns-2">173<h4 id="returns-2">

151 返回值174 返回值

152</h4>175</h4>

1781 data: dict[str, Any]1804 data: dict[str, Any]

1782```1805```

1783 1806

1807没有自己数据类的子类型以 `SystemMessage` 的形式到达。要在轮次之间跟踪会话，请设置 [`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`](/docs/zh-CN/env-vars#variables)，并在每条 `subtype` 为 `session_state_changed` 的消息上读取 `message.data["state"]`。[`SDKSessionStateChangedMessage`](/docs/zh-CN/agent-sdk/typescript#sdksessionstatechangedmessage) 列出了它可以携带的状态。使用 `receive_messages()` 迭代以读取这些消息：`receive_response()` 会在 `ResultMessage` 处停止，而 `session_state_changed` 消息可能出现在该结果之后。

1808

1784<h3 id="resultmessage">1809<h3 id="resultmessage">

1785 `ResultMessage`1810 `ResultMessage`

1786</h3>1811</h3>

agent-sdk/typescript.md +130 −106

Details

5101 `ApiKeySource`5101 `ApiKeySource`

5102</h3>5102</h3>

5103 5103

5104会话请求的 API 密钥来源，在 [`SDKSystemMessage`](#sdksystemmessage) 初始化消息上报告为 `apiKeySource`。5104会话请求所用 API 密钥的来源，在 [`SDKSystemMessage`](#sdksystemmessage) init 消息中以 `apiKeySource` 报告。

5105 5105

5106```typescript theme={null}5106```typescript theme={null}

5107type ApiKeySource =5107type ApiKeySource =

5116 | "oauth";5116 | "oauth";

5117```5117```

5118 5118

5119Claude Code 报告以下四个值之一：5119Claude Code 会报告以下四个值之一：

5120 5120

5121| 值 | 使用中的密钥 |5121| 值 | 使用的密钥 |

5122| - | - |5122| - | - |

5125| `/login managed key` | Claude Code 在您使用 [Claude Console 账户](/docs/zh-CN/authentication#claude-console-authentication) 登录时存储的密钥 |5125| `/login managed key` | 您使用 [Claude Console 账户](/docs/zh-CN/authentication#claude-console-authentication)登录时 Claude Code 存储的密钥 |

5127 5127

5128Agent SDK v0.3.234 及更高版本在类型中列出这四个值。该类型还保留 `user`、`project`、`org`、`temporary` 和 `oauth`，以便旧代码仍能编译，Claude Code 不报告它们。5128Agent SDK v0.3.234 及更高版本在该类型中列出这四个值。该类型还保留了 `user`、`project`、`org`、`temporary` 和 `oauth`，以便旧代码仍能编译，但 Claude Code 不会报告它们。

5129 5129

5130<h3 id="sdkbeta">5130<h3 id="sdkbeta">

5131 `SdkBeta`5131 `SdkBeta`

5132</h3>5132</h3>

5133 5133

5134可通过 `betas` 选项启用的可用 beta 功能。有关更多信息，请参阅 [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)。5134可通过 `betas` 选项启用的 beta 功能。有关更多信息，请参阅 [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)。

5135 5135

5136```typescript theme={null}5136```typescript theme={null}

5137type SdkBeta = "context-1m-2025-08-07";5137type SdkBeta = "context-1m-2025-08-07";

5138```5138```

5139 5139

5140<Warning>5140<Warning>

5141 在 Claude API 上，`context-1m-2025-08-07` beta 已针对 Claude Sonnet 4.5 和 Claude Sonnet 4 停用。如果您在使用这两个模型之一时仍传递它，超过标准 200K token 上下文窗口的请求将返回错误，因此请将其从 `betas` 中移除。要以 1M token 上下文窗口运行会话，请将 `model` 设置为[默认以 1M 窗口运行](/docs/zh-CN/model-config#extended-context)的模型，例如 `claude-sonnet-5-5` 或 `claude-opus-5-5`。对于仅通过其 `[1m]` 变体才能达到 1M 的模型，请在模型 ID 后附加该后缀，例如 `claude-opus-4-6[1m]`。5141 在 Claude API 上，`context-1m-2025-08-07` beta 已针对 Claude Sonnet 4.5 和 Claude Sonnet 4 停用。如果您仍在这两个模型中的任一个上传递它，超出标准 200K token 上下文窗口的请求将返回错误，因此请将其从 `betas` 中移除。要以 1M token 上下文窗口运行会话，请将 `model` 设置为[默认以 1M 窗口运行](/docs/zh-CN/model-config#extended-context)的模型，例如 `claude-sonnet-5-5` 或 `claude-opus-5-5`。对于只能通过其 `[1m]` 变体达到 1M 的模型，请在模型 ID 后附加该后缀，例如 `claude-opus-4-6[1m]`。

5142</Warning>5142</Warning>

5143 5143

5144<h3 id="slashcommand">5144<h3 id="slashcommand">

5157};5157};

5158```5158```

5159 5159

5160`builtin` 在命令是 Claude Code 自己的命令且输入 `/name` 运行它时为 `true`。对于由用户、项目、插件或 MCP 服务器定义的命令，以及由这些命令之一 [按名称替换](/docs/zh-CN/skills#resolve-skills-that-share-a-name) 的捆绑命令，它不存在。需要 Agent SDK v0.3.277 或更高版本。5160当某条命令是 Claude Code 自身的命令且输入 `/name` 即可运行它时，该行的 `builtin` 为 `true`。对于由用户、项目、插件或 MCP 服务器定义的命令，以及被上述某一来源[按名称替换](/docs/zh-CN/skills#resolve-skills-that-share-a-name)的内置命令，该字段不存在。需要 Agent SDK v0.3.277 或更高版本。

5161 5161

5162<h3 id="modelinfo">5162<h3 id="modelinfo">

5163 `ModelInfo`5163 `ModelInfo`

5193 5193

5209| :- | :- | :- |5209| :- | :- | :- |

5213 5213

5214<h3 id="mcpserverprovenance">5214<h3 id="mcpserverprovenance">

5215 `McpServerProvenance`5215 `McpServerProvenance`

5216</h3>5216</h3>

5217 5217

5218提供 `mcp__*` 工具的 MCP 服务器，以及该服务器定义的来源。[`PreToolUse`](#pretoolusehookinput)、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied` hook 输入将其作为 `mcp_server` 携带，[`CanUseTool`](#canusetool) 选项将其作为 `mcpServer` 携带。对于不来自 MCP 服务器的工具，两者都省略它。5218提供某个 `mcp__*` 工具的 MCP 服务器，以及该服务器定义的来源。[`PreToolUse`](#pretoolusehookinput)、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied` hook 输入以 `mcp_server` 携带它，[`CanUseTool`](#canusetool) 选项以 `mcpServer` 携带它。对于并非来自 MCP 服务器的工具，两者都会省略它。

5219 5219

5220```typescript theme={null}5220```typescript theme={null}

5221type McpServerProvenance = {5221type McpServerProvenance = {

5227| 字段 | 类型 | 描述 |5227| 字段 | 类型 | 描述 |

5228| :- | :- | :- |5228| :- | :- | :- |

5231 5231

5232`source` 采用以下值之一。该集合是开放的，因此将您不认识的值视为配置的来源，而不是 `sdk`：5232`source` 取以下值之一。该集合是开放的，因此请将无法识别的值视为已配置的来源，绝不要视为 `sdk`：

5233 5233

5234* **`sdk`**：您的应用程序注册的进程内服务器。只有 SDK 主机应用程序可以注册一个，因此配置的服务器永远不会报告 `sdk`，无论其名称如何。5234* **`sdk`**：由您的应用程序注册的进程内服务器。只有 SDK 宿主应用程序才能注册此类服务器，因此已配置的服务器无论名称为何，都不会报告 `sdk`。

5235* **`plugin`**：[插件](/docs/zh-CN/agent-sdk/plugins) 提供的服务器。其 `name` 是 [插件提供的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers) 下描述的作用域 `plugin:<plugin-name>:<server-name>` 形式。5235* **`plugin`**：由[插件](/docs/zh-CN/agent-sdk/plugins)提供的服务器。其 `name` 为[插件提供的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)中描述的限定形式 `plugin:<plugin-name>:<server-name>`。

5236* **配置作用域**：`user`、`project`、`local`、`dynamic`、`managed`、`enterprise`、`claudeai` 或 `agent`。`.mcp.json` 服务器报告 `project`，[MCP installation scopes](/docs/zh-CN/mcp#mcp-installation-scopes) 定义 `local`、`project` 和 `user`。您的应用程序在 [`mcpServers` 选项](#options) 中传递的服务器（除了进程内 SDK 服务器外）报告 `dynamic`。5236* **配置作用域**：`user`、`project`、`local`、`dynamic`、`managed`、`enterprise`、`claudeai` 或 `agent`。`.mcp.json` 服务器报告 `project`，[MCP 安装作用域](/docs/zh-CN/mcp#mcp-installation-scopes)定义了 `local`、`project` 和 `user`。您的应用程序通过 [`mcpServers` 选项](#options)传入的服务器（进程内 SDK 服务器除外）报告 `dynamic`。

5237 5237

5238基于 `source` 做出信任决策，而不是基于 `name` 或 `mcp__<server>__` 工具名称前缀。对于除 `sdk` 之外的任何来源，`name` 是不受信任的文本：在显示前对其进行转义。5238请基于 `source` 做出信任决策，而不是基于 `name` 或 `mcp__<server>__` 工具名前缀。对于 `sdk` 以外的任何来源，`name` 都是不可信文本：在显示之前请对其进行转义。

5239 5239

5240`McpServerProvenance` 和携带它的字段需要 Agent SDK v0.3.274 或更高版本。5240`McpServerProvenance` 及携带它的字段需要 Agent SDK v0.3.274 或更高版本。

5241 5241

5242<h3 id="mcpserverstatus">5242<h3 id="mcpserverstatus">

5243 `McpServerStatus`5243 `McpServerStatus`

5244</h3>5244</h3>

5245 5245

5246连接的 MCP 服务器的状态。5246已连接 MCP 服务器的状态。

5247 5247

5248```typescript theme={null}5248```typescript theme={null}

5249type McpServerStatus = {5249type McpServerStatus = {

5270};5270};

5271```5271```

5272 5272

5273`source` 说明服务器定义的来源，具有与 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同的值和信任规则。该字段需要 Agent SDK v0.3.274 或更高版本，在早期版本中不存在。5273`source` 表示服务器定义的来源，其取值和信任规则与 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同。该字段需要 Agent SDK v0.3.274 或更高版本，在更早的版本中不存在。

5274 5274

5275`_meta` 在 `tools` 条目上携带该工具的 `_meta` 的 MCP Apps 成员，因此您的应用程序可以找到 `ui://` 资源以使用 [`readMcpResource()`](#query-object) 呈现。Claude Code 传递 `ui` 对象和已弃用的平面 `ui/resourceUri` 字符串，并保留所有其他键。在 `ui` 内，`resourceUri` 是 `ui://` 字符串，`visibility` 是当服务器设置它们时的 `"model"` 和 `"app"` 数组，任何其他成员原样传递。Claude Code 在值格式不正确时删除任一键，并从既不声明任何一个的工具中省略 `_meta`。该字段仅在初始化消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 时出现，并需要 TypeScript Agent SDK v0.3.280 或更高版本。5275`tools` 条目上的 `_meta` 携带该工具 `_meta` 中的 MCP Apps 成员，以便您的应用程序找到要通过 [`readMcpResource()`](#query-object) 渲染的 `ui://` 资源。Claude Code 会透传 `ui` 对象和已弃用的扁平 `ui/resourceUri` 字符串，并扣留所有其他键，不予透传。在 `ui` 内部，当服务器设置了 `resourceUri` 和 `visibility` 时，`resourceUri` 为 `ui://` 字符串，`visibility` 为由 `"model"` 和 `"app"` 组成的数组，其他任何成员原样透传。当值格式错误时，Claude Code 会丢弃相应的键；对于两者都未声明的工具，则省略 `_meta`。仅当 init 消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 时，该字段才会出现，并且需要 TypeScript Agent SDK v0.3.280 或更高版本。

5276 5276

5277<h3 id="mcpserverstatusconfig">5277<h3 id="mcpserverstatusconfig">

5278 `McpServerStatusConfig`5278 `McpServerStatusConfig`

5279</h3>5279</h3>

5280 5280

5281MCP 服务器的配置，由 `mcpServerStatus()` 报告。这是所有 MCP 服务器传输类型的并集。5281由 `mcpServerStatus()` 报告的 MCP 服务器配置。这是所有 MCP 服务器传输类型的联合类型。

5282 5282

5283```typescript theme={null}5283```typescript theme={null}

5284type McpServerStatusConfig =5284type McpServerStatusConfig =

5295 `AccountInfo`5295 `AccountInfo`

5296</h3>5296</h3>

5297 5297

5298经过身份验证的用户的账户信息。5298已通过身份验证用户的账户信息。

5299 5299

5300```typescript theme={null}5300```typescript theme={null}

5301type AccountInfo = {5301type AccountInfo = {

5311 `ModelUsage`5311 `ModelUsage`

5312</h3>5312</h3>

5313 5313

5314在结果消息中返回的每个模型的使用统计信息。`costUSD` 值是客户端估计。有关计费注意事项，请参阅 [Track cost and usage](/docs/zh-CN/agent-sdk/cost-tracking)。5314在结果消息中返回的按模型统计的使用情况。`costUSD` 值是客户端估算值。有关计费注意事项，请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)。

5315 5315

5316```typescript theme={null}5316```typescript theme={null}

5317type ModelUsage = {5317type ModelUsage = {

5330};5330};

5331```5331```

5332 5332

5333`thinkingTokens` 计算此模型生成的思考 token。`outputTokens` 已包含它们，因此不要将两者相加。该字段在运行在记录它的 Claude Code 版本上的轮次之前不存在，因此在早期版本上开始的已恢复会话报告部分计数。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。5333`thinkingTokens` 统计此模型生成的思考 token。`outputTokens` 已包含它们，因此不要将两者相加。在某个轮次于记录该字段的 Claude Code 版本上运行之前，该字段不存在，因此在更早版本上开始的恢复会话会报告部分计数。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。

5334 5334

5335`canonicalModel` 和 `provider` 字段需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是定价查询使用的规范模型 ID；它可能与键入条目的原始模型字符串不同，例如当该字符串是提供商特定的 ID 或别名时。5335`canonicalModel` 和 `provider` 字段需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是价格查询所使用的规范模型 ID；它可能与作为条目键的原始模型字符串不同，例如当该字符串是特定于提供商的 ID 或别名时。

5336 5336

5337`provider` 命名提供模型的 API 后端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。5337`provider` 指明提供该模型的 API 后端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。

5338 5338

5339`costBasis` 命名为模型最新请求定价的价格表：`list` 表示列表价格，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，或 `unknown` 表示两者都不匹配模型 ID。该字段需要 Claude Code v2.1.246 或更高版本。5339`costBasis` 指明为该模型最近一次请求定价所使用的价格表：`list` 表示标价，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，`unknown` 表示两者都未匹配该模型 ID。该字段需要 Claude Code v2.1.246 或更高版本。

5340 5340

5341<h3 id="configscope">5341<h3 id="configscope">

5342 `ConfigScope`5342 `ConfigScope`

5350 `NonNullableUsage`5350 `NonNullableUsage`

5351</h3>5351</h3>

5352 5352

5353[`Usage`](#usage) 的一个版本，除 `fallback_credit` 外所有可空字段都变为非可空，`fallback_credit` 仍可以为 `null`。5353[`Usage`](#usage) 的一个版本，其中除 `fallback_credit`（仍可为 `null`）外，所有可为空的字段都变为不可为空。

5354 5354

5355```typescript theme={null}5355```typescript theme={null}

5356type NonNullableUsage = {5356type NonNullableUsage = {

5388 5388

5389`BetaServerToolUsage`、`BetaIterationsUsage`、`BetaOutputTokensDetails` 和 `BetaFallbackCreditUsage` 在 `@anthropic-ai/sdk` 中定义。5389`BetaServerToolUsage`、`BetaIterationsUsage`、`BetaOutputTokensDetails` 和 `BetaFallbackCreditUsage` 在 `@anthropic-ai/sdk` 中定义。

5390 5390

5391`output_tokens_details` 按类别分解计费输出。它目前携带一个字段 `thinking_tokens: number`，计算模型生成的作为内部推理的输出 token，包括思考块分隔符。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，它捆绑了 Claude Code v2.1.228。5391`output_tokens_details` 按类别细分计费的输出。它目前包含一个字段 `thinking_tokens: number`，统计模型作为内部推理生成的输出 token，包括思考块分隔符。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，该版本捆绑了 Claude Code v2.1.228。

5392 5392

5393* **计费**：读取分解以进行观察，而不是用于计费。`output_tokens` 保持为权威总数，`output_tokens - thinking_tokens` 近似非推理输出。5393* **计费**：请将此细分用于可观测性，而不是计费。`output_tokens` 仍是权威总数，`output_tokens - thinking_tokens` 近似于非推理输出。

5394* **计数涵盖的内容**：模型生成的原始推理，可能比响应体中返回的思考文本更长。API 通过重新对该原始文本进行 token 化来计算它，因此它可能与模型的精确生成计数相差几个 token。5394* **计数涵盖的内容**：模型产生的原始推理，可能比响应体中返回的思考文本更长。API 通过对该原始文本重新进行 token 化来计算它，因此可能与模型的确切生成计数相差几个 token。

5395* **流式输出**：在流式助手消息上，此分解与 `output_tokens` 一样是 `message_start` 占位符，不携带真实计数，因此从结果消息的 `usage` 读取它，如 [Read output tokens from the result message](/docs/zh-CN/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 所述。在结果消息上，当模型或提供商不报告分解时，`thinking_tokens` 读取 `0`。5395* **流式**：在流式的助手消息上，此细分与 `output_tokens` 一样是 `message_start` 占位符，不携带真实计数，因此请按照[从结果消息中读取输出 token](/docs/zh-CN/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 的说明，从结果消息的 `usage` 中读取。在结果消息上，当模型或提供商未报告细分时，`thinking_tokens` 为 `0`。

5396* **`null` 情况**：`output_tokens_details` 本身在 Claude Code 合成的助手消息上为 `null`，例如 API 错误消息。5396* **`null` 情况**：在 Claude Code 合成的助手消息（例如 API 错误消息）上，`output_tokens_details` 本身为 `null`。

5397 5397

5398`Usage` 是否携带 `fallback_credit` 取决于您安装的 `@anthropic-ai/sdk`，该字段在 0.115.0 中添加。5398`Usage` 是否携带 `fallback_credit` 取决于您安装的 `@anthropic-ai/sdk`，该字段在 0.115.0 中添加。

5399 5399

5401 `CallToolResult`5401 `CallToolResult`

5402</h3>5402</h3>

5403 5403

5404MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是可与 `content` 一起返回的 JSON 对象，包括图像块。请参阅 [Return structured data](/docs/zh-CN/agent-sdk/custom-tools#return-structured-data)。5404MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一个 JSON 对象，可以与 `content`（包括图像块）一起返回。请参阅[返回结构化数据](/docs/zh-CN/agent-sdk/custom-tools#return-structured-data)。

5405 5405

5406```typescript theme={null}5406```typescript theme={null}

5407type CallToolResult = {5407type CallToolResult = {

5418 `SDKMcpResourceLink`5418 `SDKMcpResourceLink`

5419</h3>5419</h3>

5420 5420

5421MCP 工具通过引用返回的一个文件。Claude Code 从工具结果中的 `resource_link` 块构建每个条目，并将列表作为 `resourceLinks` 在 [`SDKUserMessage.tool_use_result`](#sdkusermessage) 上传递，或在后台完成调用时作为 `resource_links` 在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 上传递。需要 Agent SDK v0.3.257 或更高版本。5421MCP 工具以引用方式返回的一个文件。Claude Code 根据工具结果中的 `resource_link` 块构建每个条目，并将列表作为 [`SDKUserMessage.tool_use_result`](#sdkusermessage) 上的 `resourceLinks` 传递；当调用在后台完成时，则作为 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 上的 `resource_links` 传递。需要 Agent SDK v0.3.257 或更高版本。

5422 5422

5423```typescript theme={null}5423```typescript theme={null}

5424type SDKMcpResourceLink = {5424type SDKMcpResourceLink = {

5432};5432};

5433```5433```

5434 5434

5435Claude Code 丢弃其 `uri` 或 `name` 不是字符串的块，并省略其值不是列出的类型的可选字段。5435Claude Code 会丢弃 `uri` 或 `name` 不是字符串的块，并省略值不属于所列类型的可选字段。

5436 5436

5437| 字段 | 类型 | 描述 |5437| 字段 | 类型 | 描述 |

5438| :- | :- | :- |5438| :- | :- | :- |

5439| `uri` | `string` | 资源的 URI，如服务器返回的那样 |5439| `uri` | `string` | 资源的 URI，与服务器返回的一致 |

5446 5446

5447<h3 id="thinkingconfig">5447<h3 id="thinkingconfig">

5448 `ThinkingConfig`5448 `ThinkingConfig`

5459 | { type: "disabled" }; // No extended thinking5459 | { type: "disabled" }; // No extended thinking

5460```5460```

5461 5461

5462可选的 `display` 字段控制思考文本是否返回为 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不向 Amazon Bedrock 或 Google Cloud 的 Agent Platform 发送 `display`，因此在这些提供商上，Opus 4.7 及更高版本即使在您将 `display` 设置为 `"summarized"` 时也返回空 `thinking` 块。5462可选的 `display` 字段控制思考文本以 `"summarized"` 还是 `"omitted"` 方式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此请设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不会将 `display` 发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在这些提供商上，即使您将 `display` 设置为 `"summarized"`，Opus 4.7 及更高版本也会返回空的 `thinking` 块。

5463 5463

5464<h3 id="spawnedprocess">5464<h3 id="spawnedprocess">

5465 `SpawnedProcess`5465 `SpawnedProcess`

5466</h3>5466</h3>

5467 5467

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

5469 5469

5470```typescript theme={null}5470```typescript theme={null}

5471interface SpawnedProcess {5471interface SpawnedProcess {

5496 `SpawnOptions`5496 `SpawnOptions`

5497</h3>5497</h3>

5498 5498

5499传递给自定义生成函数的选项。5499传递给自定义 spawn 函数的选项。

5500 5500

5501```typescript theme={null}5501```typescript theme={null}

5502interface SpawnOptions {5502interface SpawnOptions {

5509```5509```

5510 5510

5511<Note>5511<Note>

5512 `signal` 字段告诉您的生成函数何时拆除进程。将其作为 `signal` 选项传递给 Node 的 `spawn()`，或将其传递给您的 VM 或容器拆除处理程序。5512 `signal` 字段告诉您的 spawn 函数何时拆除进程。请将其作为 `signal` 选项传递给 Node 的 `spawn()`，或将其传递给您的 VM 或容器拆除处理程序。

5513 5513

5514 此信号不会在 [`Options.abortController`](#options) 中止时立即触发。SDK 首先关闭进程的 stdin 并等待约两秒，以便 CLI 可以干净地关闭，然后中止此信号。要在调用者中止时立即做出反应，请侦听您自己的 `Options.abortController.signal`，您的生成函数可以从其封闭范围引用。5514 此信号不会在 [`Options.abortController`](#options) 中止的瞬间触发。SDK 会先关闭进程的 stdin 并等待约两秒，以便 CLI 能够干净地关闭，然后再中止此信号。如果要在调用方中止的那一刻立即作出反应，请监听您自己的 `Options.abortController.signal`，您的 spawn 函数可以从其外围作用域引用它。

5515</Note>5515</Note>

5516 5516

5517<h3 id="mcpsetserversresult">5517<h3 id="mcpsetserversresult">

5528};5528};

5529```5529```

5530 5530

5531当您调用 `setMcpServers()` 时，Claude Code 应用这些规则：5531调用 `setMcpServers()` 时，Claude Code 会应用以下规则：

5532 5532

5533* **调用未命名的服务器**：Claude Code 保持插件提供的服务器运行。需要 Agent SDK v0.3.210 或更高版本。5533* **调用未指定的服务器**：Claude Code 会保持插件提供的服务器继续运行。需要 Agent SDK v0.3.210 或更高版本。

5534* **调用命名的服务器**：除了 CLI 在启动时启动的内置服务器外，Claude Code 仅在其配置与您传递的配置不同时才替换运行中的服务器。5534* **调用指定的服务器**：除 CLI 在启动时启动的内置服务器外，只有当正在运行的服务器的配置与您传入的配置不同时，Claude Code 才会替换它。

5535* **CLI 在启动时启动的内置服务器**：如果调用命名了一个，Claude Code 会删除该条目并在 `errors` 中报告它。5535* **CLI 在启动时启动的内置服务器**：如果调用指定了其中之一，Claude Code 会丢弃该条目并在 `errors` 中报告它。

5536 5536

5537该 Promise 在新添加的 stdio、HTTP 和 SSE 服务器连接或失败后解析，因此来自已连接服务器的工具在下一轮可用。5537Promise 会在新添加的 stdio、HTTP 和 SSE 服务器连接成功或失败后 resolve，因此已连接服务器的工具在下一轮次即可使用。

5538 5538

5539`added` 列出 Claude Code 添加或替换的服务器，无论它们是否连接。连接失败的服务器同时出现在 `added` 和 `errors` 中，`errors` 下有失败文本，[`mcpServerStatus()`](#methods) 中有 `failed` 行。在 Claude Code v2.1.257 之前，连接尝试抛出的服务器仅在 `errors` 下报告。5539`added` 列出 Claude Code 添加或替换的服务器，无论它们是否已连接。连接失败的服务器会同时出现在 `added` 和 `errors` 中，失败文本位于 `errors` 下，并在 [`mcpServerStatus()`](#methods) 中有一行 `failed`。在 Claude Code v2.1.257 之前，连接尝试抛出异常的服务器只会在 `errors` 下报告。

5540 5540

5541<h3 id="rewindfilesresult">5541<h3 id="rewindfilesresult">

5542 `RewindFilesResult`5542 `RewindFilesResult`

5555};5555};

5556```5556```

5557 5557

5558`skippedLinks` 计算倒带拒绝恢复或删除以确保链接安全的跟踪路径：跟踪路径处的符号链接、硬链接或其他非常规文件，不再解析为检查点时指向的位置的父目录，或无法安全读取的备份。该字段需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的预览调用永远不会设置它。5558`skippedLinks` 统计回退出于链接安全考虑而拒绝恢复或删除的被跟踪路径：被跟踪路径上的符号链接、硬链接或其他非常规文件，不再解析到创建检查点时所指向位置的父目录，或无法安全读取的备份。该字段需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的预览调用永远不会设置它。

5559 5559

5560<h3 id="sdkstatusmessage">5560<h3 id="sdkstatusmessage">

5561 `SDKStatusMessage`5561 `SDKStatusMessage`

5562</h3>5562</h3>

5563 5563

5564状态更新消息（例如压缩）。5564状态更新消息（例如压缩中）。

5565 5565

5566```typescript theme={null}5566```typescript theme={null}

5567type SDKStatusMessage = {5567type SDKStatusMessage = {

5578 `SDKTaskNotificationMessage`5578 `SDKTaskNotificationMessage`

5579</h3>5579</h3>

5580 5580

5581后台任务完成、失败或停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视和后台子代理。对于 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定义了它和它的版本要求。5581后台任务完成、失败或被停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视以及后台子代理。有关 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。

5582 5582

5583```typescript theme={null}5583```typescript theme={null}

5584type SDKTaskNotificationMessage = {5584type SDKTaskNotificationMessage = {

5601};5601};

5602```5602```

5603 5603

5604当 Claude Code [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 时，该调用的 `tool_result` 块仅保存占位符，调用的真实结果在此通知中到达。使用 `tool_use_id` 将通知与调用匹配。在 `completed` 通知上，`resource_links` 列出工具通过引用返回的文件，作为 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目，具有与 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 链接和 64 KiB 限制。Claude Code 在结果没有链接时省略 `resource_links`，以及在不是 MCP 工具调用的任务的通知上。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。5604当 Claude Code [将耗时较长的 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)时，该调用的 `tool_result` 块只包含一个占位符，调用的真实结果会在此通知中到达。请使用 `tool_use_id` 将通知与调用匹配。在 `completed` 通知上，`resource_links` 以 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目的形式列出工具以引用方式返回的文件，其 50 个链接和 64 KiB 的限制与 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同。当结果没有链接时，以及在非 MCP 工具调用任务的通知上，Claude Code 会省略 `resource_links`。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。

5605 5605

5606Claude Code 在发送给模型的每个任务通知前面加上通知，除了带有 [`scheduled-trigger` subkind](#task-notification-subkinds) 戳记的通知外，它们改为携带分配任务框架。通知说明没有发生人类输入，因此模型不会将通知视为用户指令或批准。5606Claude Code 会在其发送给模型的每个任务通知前添加一条提示，但带有 [`scheduled-trigger` subkind](#task-notification-subkinds) 标记的投递除外，这类投递改为携带分配任务的框架说明。该提示声明没有发生任何人工输入，因此模型不会将通知视为用户指令或批准。

5607 5607

5608要检测任务通知轮次，请在 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上检查 `origin.kind === "task-notification"`，而不是匹配通知文本。如果您需要知道是什么引发了它，请从同一字段读取 `subkind`。在 v2.1.205 之前，Claude Code 在会话空闲时到达的通知上省略了通知。5608要检测任务通知轮次，请检查 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上的 `origin.kind === "task-notification"`，而不是匹配提示文本。如果需要知道是什么触发了它，请从同一字段读取 `subkind`。在 v2.1.205 之前，Claude Code 不会在会话空闲时到达的通知上添加该提示。

5609 5609

5610<h3 id="sdktoolusesummarymessage">5610<h3 id="sdktoolusesummarymessage">

5611 `SDKToolUseSummaryMessage`5611 `SDKToolUseSummaryMessage`

5612</h3>5612</h3>

5613 5613

5614对话中工具使用的摘要。5614对话中工具使用情况的摘要。

5615 5615

5616```typescript theme={null}5616```typescript theme={null}

5617type SDKToolUseSummaryMessage = {5617type SDKToolUseSummaryMessage = {

5629 5629

5630在 hook 开始执行时发出。5630在 hook 开始执行时发出。

5631 5631

5632Claude Code 将此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 立即传递到消息流，包括在会话启动期间 `SessionStart` 或 `Setup` hook 仍在运行时。Claude Code v2.1.169 至 v2.1.203 在 `SessionStart` 或 `Setup` hook 完成后分批传递这些消息；v2.1.204 恢复了实时传递。5632Claude Code 会立即将此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 传递到消息流，包括在会话启动期间 `SessionStart` 或 `Setup` hook 仍在运行时。Claude Code v2.1.169 至 v2.1.203 会在 `SessionStart` 或 `Setup` hook 完成后一次性批量传递这些消息；v2.1.204 恢复了实时传递。

5633 5633

5634```typescript theme={null}5634```typescript theme={null}

5635type SDKHookStartedMessage = {5635type SDKHookStartedMessage = {

5647 `SDKHookProgressMessage`5647 `SDKHookProgressMessage`

5648</h3>5648</h3>

5649 5649

5650在 hook 运行时发出，带有 stdout/stderr 输出。5650在 hook 运行期间发出，包含 stdout/stderr 输出。

5651 5651

5652```typescript theme={null}5652```typescript theme={null}

5653type SDKHookProgressMessage = {5653type SDKHookProgressMessage = {

5668 `SDKHookResponseMessage`5668 `SDKHookResponseMessage`

5669</h3>5669</h3>

5670 5670

5671在 hook 完成执行时发出。5671在 hook 执行完成时发出。

5672 5672

5673```typescript theme={null}5673```typescript theme={null}

5674type SDKHookResponseMessage = {5674type SDKHookResponseMessage = {

5691 `SDKToolProgressMessage`5691 `SDKToolProgressMessage`

5692</h3>5692</h3>

5693 5693

5694在工具执行时定期发出，以指示进度。5694在工具执行期间定期发出，以指示进度。

5695 5695

5696```typescript theme={null}5696```typescript theme={null}

5697type SDKToolProgressMessage = {5697type SDKToolProgressMessage = {

5716};5716};

5717```5717```

5718 5718

5719当工具调用在主对话中运行时，Claude Code 每 30 秒发出一条 `tool_progress` 消息，带有 `heartbeat: true`。每个心跳携带工具名称和经过的秒数，因此您可以区分长时间运行的调用和停滞的会话。Claude Code 不为子代理内的工具调用发出心跳。`heartbeat` 字段需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不为前台 Agent 工具调用发出心跳。5719当工具调用在主对话中运行时，Claude Code 每 30 秒发出一条带有 `heartbeat: true` 的 `tool_progress` 消息。每个心跳都携带工具名称和已用秒数，因此您可以区分长时间运行的调用和停滞的会话。Claude Code 不会为子代理内部的工具调用发出心跳。`heartbeat` 字段需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不会为前台的 Agent 工具调用发出心跳。

5720 5720

5721在除心跳外的 Agent 工具的 `tool_progress` 消息上，`subagent_type` 命名运行中的子代理类型，例如 `general-purpose`。`subagent_retry` 在该子代理等待 API 错误退避（例如速率限制或过载）时出现，每次重试尝试一条消息。两个字段都需要 Agent SDK v0.3.214 或更高版本。5721在 Agent 工具的非心跳 `tool_progress` 消息上，`subagent_type` 指明正在运行的子代理类型，例如 `general-purpose`。当该子代理因 API 错误（例如速率限制或过载）而等待退避时，会出现 `subagent_retry`，每次重试尝试对应一条消息。这两个字段都需要 Agent SDK v0.3.214 或更高版本。

5722 5722

5723要从 `subagent_retry` 呈现重试指示器：5723要根据 `subagent_retry` 渲染重试指示器：

5724 5724

5725* 按 `parent_tool_use_id` 跟踪指示器，这对每个子代理是唯一的。`tool_use_id` 由来自一个助手轮次的并行子代理共享，因此按它跟踪会让一个子代理的更新清除另一个的指示器。5725* 按 `parent_tool_use_id` 跟踪指示器，它对每个子代理都是唯一的。同一助手轮次中的并行子代理共享 `tool_use_id`，因此按它跟踪会导致一个子代理的更新清除另一个子代理的指示器。

5726* 当同一 `parent_tool_use_id` 的后续 `tool_progress` 到达时清除指示器，既不带 `subagent_retry` 也不带 `heartbeat: true`，或当工具的结果消息到达时。带 `heartbeat: true` 的帧仅报告活跃性，因此在一个到达时保持指示器。`attempt` 可能在持续重试下超过 `max_retries`，因此不要从计数器派生清除。5726* 当同一 `parent_tool_use_id` 的后续 `tool_progress` 到达且既没有 `subagent_retry` 也没有 `heartbeat: true` 时，或当工具的结果消息到达时，清除指示器。带有 `heartbeat: true` 的帧仅报告存活状态，因此在收到此类帧时请保留指示器。在持续重试下，`attempt` 可能超过 `max_retries`，因此不要根据计数器来判断是否清除。

5727* 将 `error_category` 视为用于选择您自己的消息文本的标识符，而不是显示文本。值为 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。处理您不认识的值的方式与处理 `unknown` 的方式相同，因为后续版本可以添加值。5727* 将 `error_category` 视为用于选择您自己的消息文本的标记，而不是显示文本。其取值为 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。请以处理 `unknown` 的方式处理无法识别的值，因为后续版本可能会添加新值。

5728 5728

5729<h3 id="sdkauthstatusmessage">5729<h3 id="sdkauthstatusmessage">

5730 `SDKAuthStatusMessage`5730 `SDKAuthStatusMessage`

5731</h3>5731</h3>

5732 5732

5733在身份验证流程期间发出。5733在身份验证流程中发出。

5734 5734

5735```typescript theme={null}5735```typescript theme={null}

5736type SDKAuthStatusMessage = {5736type SDKAuthStatusMessage = {

5747 `SDKTaskStartedMessage`5747 `SDKTaskStartedMessage`

5748</h3>5748</h3>

5749 5749

5750在任务开始时发出。`task_type` 字段对于 Bash 命令和 [Monitor](#monitor) 监视为 `"local_bash"`，对于子代理为 `"local_agent"`，或 `"remote_agent"`。5750在任务开始时发出。对于 Bash 命令和 [Monitor](#monitor) 监视，`task_type` 字段为 `"local_bash"`；对于子代理为 `"local_agent"`；否则为 `"remote_agent"`。

5751 5751

5752```typescript theme={null}5752```typescript theme={null}

5753type SDKTaskStartedMessage = {5753type SDKTaskStartedMessage = {

5765};5765};

5766```5766```

5767 5767

5768`ambient` 对于不是会话工作一部分的任务为 `true`，例如 Claude Code 为其自己的操作运行的任务。实时更新监视器也是环境的，包括用户要求的监视器。从活动指示器中排除环境任务。该字段需要 Agent SDK v0.3.247 或更高版本。5768对于不属于会话工作的任务（例如 Claude Code 为其自身运行而执行的任务），`ambient` 为 `true`。实时更新监视器也属于 ambient，包括用户要求的监视器。请将 ambient 任务从活动指示器中排除。该字段需要 Agent SDK v0.3.247 或更高版本。

5769 5769

5770`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 条目上。5770`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 以及 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 的条目上。

5771 5771

5772`is_backgrounded` 和 `spawn_depth` 描述 Claude Code 如何启动任务。两个字段都需要 Agent SDK v0.3.238 或更高版本。5772`is_backgrounded` 和 `spawn_depth` 描述 Claude Code 如何启动该任务。这两个字段都需要 Agent SDK v0.3.238 或更高版本。

5773 5773

5774* `is_backgrounded`：Claude Code 在 `"local_agent"` 和 `"local_bash"` 任务上设置它。`true` 表示任务在后台运行。`false` 表示任务在前台运行，启动它的工具调用保持阻止，直到任务完成或移到后台。5774* `is_backgrounded`：Claude Code 在 `"local_agent"` 和 `"local_bash"` 任务上设置它。`true` 表示任务在后台运行。`false` 表示任务在前台运行，启动它的工具调用会一直阻塞，直到任务完成或移到后台。

5775* `spawn_depth`：Claude Code 仅在 `"local_agent"` 任务上设置它。主线程生成的子代理的深度为 `1`。深度 `1` 子代理生成的子代理的深度为 `2`，以此类推。5775* `spawn_depth`：Claude Code 仅在 `"local_agent"` 任务上设置它。由主线程生成的子代理深度为 `1`。由深度为 `1` 的子代理生成的子代理深度为 `2`，依此类推。

5776 5776

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

5778 5778

5779<h3 id="sdktaskprogressmessage">5779<h3 id="sdktaskprogressmessage">

5780 `SDKTaskProgressMessage`5780 `SDKTaskProgressMessage`

5781</h3>5781</h3>

5782 5782

5783在子代理或后台任务运行时定期发出。5783在子代理或后台任务运行期间定期发出。

5784 5784

5785对于子代理任务，`summary` 字段携带模型生成的进度摘要，并且仅在启用 [`agentProgressSummaries`](#options) 时填充。对于 [backgrounded MCP tool call](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 携带 MCP 服务器的最新报告进度，不依赖于该选项。5785对于子代理任务，`summary` 字段携带模型生成的进度摘要，仅在启用 [`agentProgressSummaries`](#options) 时填充。对于[已移到后台的 MCP 工具调用](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 携带 MCP 服务器最近报告的进度，不依赖于该选项。

5786 5786

5787```typescript theme={null}5787```typescript theme={null}

5788type SDKTaskProgressMessage = {5788type SDKTaskProgressMessage = {

5808 `SDKTaskUpdatedMessage`5808 `SDKTaskUpdatedMessage`

5809</h3>5809</h3>

5810 5810

5811在后台任务的状态更改时发出，例如当它从 `running` 转换为 `completed` 时。将 `patch` 合并到由 `task_id` 键入的本地任务映射中。`end_time` 字段是 Unix 纪元时间戳（以毫秒为单位），可与 `Date.now()` 比较。5811在后台任务状态发生变化时发出，例如从 `running` 转换为 `completed` 时。请将 `patch` 合并到以 `task_id` 为键的本地任务映射中。`end_time` 字段是以毫秒为单位的 Unix 纪元时间戳，可与 `Date.now()` 比较。

5812 5812

5813```typescript theme={null}5813```typescript theme={null}

5814type SDKTaskUpdatedMessage = {5814type SDKTaskUpdatedMessage = {

5832 `SDKBackgroundTasksChangedMessage`5832 `SDKBackgroundTasksChangedMessage`

5833</h3>5833</h3>

5834 5834

5835每当实时后台任务集更改时发出：任务启动、完成、被杀死、前台 Agent 被后台化，或任务的 `description` 或 `ambient` 字段更改。5835每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description` 或 `ambient` 字段发生变化。

5836 5836

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

5838 5838

5839相对于这些每任务事件的顺序是未指定的，因此不要关联两个流。5839相对于这些逐任务事件的顺序是未指定的，因此不要将这两个流相互关联。

5840 5840

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

5842 5842

5843当您向运行中的会话发送重复的 `initialize` 控制请求时，例如在传输间隙后使用 [`reinitialize()`](#query-object)，Claude Code 在响应后跟随当前实时集的快照，即使它为空。因此，重新连接的主机可以了解正在运行的内容，而无需等待下一个成员资格更改。在 Agent SDK v0.3.239 之前，Claude Code 在重复的 `initialize` 后不发送快照。5843当您向正在运行的会话发送重复的 `initialize` 控制请求时（例如在传输中断后使用 [`reinitialize()`](#query-object)），Claude Code 会在响应之后发送当前活动集合的快照，即使该集合为空。因此，重新连接的宿主无需等待下一次成员变化即可了解正在运行的内容。在 Agent SDK v0.3.239 之前，Claude Code 在重复的 `initialize` 之后不发送快照。

5844 5844

5845需要 Claude Code v2.1.203 或更高版本。5845需要 Claude Code v2.1.203 或更高版本。

5846 5846

5863 `SDKThinkingTokensMessage`5863 `SDKThinkingTokensMessage`

5864</h3>5864</h3>

5865 5865

5866在 Claude 生成思考块时发出，包括编辑过的块。`estimated_tokens` 是当前块中迄今为止生成的思考 token 的运行估计，`estimated_tokens_delta` 是此帧携带的增量。使用这些估计进行进度显示。5866在 Claude 生成思考块（包括经过编辑隐去的思考块）期间发出。`estimated_tokens` 是当前块中迄今为止生成的思考 token 的累计估算值，`estimated_tokens_delta` 是此帧携带的增量。请将这些估算值用于进度显示。

5867 5867

5868当模型或提供商报告分解时，顶级 Agent 循环的最终计数是结果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它 [不包括子代理 token](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。5868当模型或提供商报告细分时，顶层 Agent 循环的最终计数是结果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它[不包括子代理的 token](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。

5869 5869

5870需要 Claude Code v2.1.153 或更高版本。5870需要 Claude Code v2.1.153 或更高版本。

5871 5871

5881};5881};

5882```5882```

5883 5883

5884<h3 id="sdksessionstatechangedmessage">

5885 `SDKSessionStateChangedMessage`

5886</h3>

5887

5888在 Claude Code 报告会话状态时发出。要接收这些消息，请设置 [`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`](/docs/zh-CN/env-vars#variables)。Claude Code 可能会多次报告相同的状态，因此请将消息理解为会话的当前状态，而不是状态转换。

5889

5890`state` 字段携带以下值之一：

5891

5892* `running`：会话正在工作。

5893* `idle`：Claude Code 正在等待您的下一个提示词。

5894* `requires_action`：会话因等待对其发送给宿主的请求（例如权限提示）的答复而被阻塞。

5895

5896一个轮次的 `idle` 消息与其 `result` 消息可能以任意顺序到达。要更改 `idle` 是否等待后台工作（例如后台子代理或[工作流](/docs/zh-CN/workflows)运行），请参阅 [`CLAUDE_CODE_BG_TASKS_REPORT_RUNNING`](/docs/zh-CN/env-vars#variables)。

5897

5898```typescript theme={null}

5899type SDKSessionStateChangedMessage = {

5900 type: "system";

5901 subtype: "session_state_changed";

5902 state: "idle" | "running" | "requires_action";

5903 uuid: UUID;

5904 session_id: string;

5905};

5906```

5907

5884<h3 id="sdkfilespersistedevent">5908<h3 id="sdkfilespersistedevent">

5885 `SDKFilesPersistedEvent`5909 `SDKFilesPersistedEvent`

5886</h3>5910</h3>

5903 `SDKRateLimitEvent`5927 `SDKRateLimitEvent`

5904</h3>5928</h3>

5905 5929

5906当会话遇到速率限制时发出。5930在会话遇到速率限制时发出。

5907 5931

5908```typescript theme={null}5932```typescript theme={null}

5909type SDKRateLimitEvent = {5933type SDKRateLimitEvent = {

5921};5945};

5922```5946```

5923 5947

5924当 `errorCode` 为 `"credits_required"` 时，拒绝来自 claude.ai 订阅，其包含的用量已耗尽，会话在用户购买使用额度之前无法继续。`canUserPurchaseCredits` 指示经过身份验证的用户是否可以为账户购买额度，`hasChargeableSavedPaymentMethod` 指示是否有已保存的付款方式。所有三个字段在不是需要额度拒绝的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。5948当 `errorCode` 为 `"credits_required"` 时，表示拒绝来自已用尽所含用量的 claude.ai 订阅，在用户购买使用额度之前，会话无法继续。`canUserPurchaseCredits` 表示已通过身份验证的用户是否可以为该账户购买额度，`hasChargeableSavedPaymentMethod` 表示是否存有已保存的付款方式。在不属于 credits-required 拒绝的速率限制事件上，这三个字段都不存在。需要 Claude Code v2.1.181 或更高版本。

5925 5949

5926<h3 id="sdklocalcommandoutputmessage">5950<h3 id="sdklocalcommandoutputmessage">

5927 `SDKLocalCommandOutputMessage`5951 `SDKLocalCommandOutputMessage`

5928</h3>5952</h3>

5929 5953

5930Claude Code 不发出此消息类型。当您将命令（如 `/context` 或 `/usage`）作为提示词发送时，其输出作为 [`SDKAssistantMessage`](#sdkassistantmessage) 到达。5954Claude Code 不会发出此消息类型。当您将 `/context` 或 `/usage` 等命令作为提示词发送时，其输出会以 [`SDKAssistantMessage`](#sdkassistantmessage) 的形式到达。

5931 5955

5932```typescript theme={null}5956```typescript theme={null}

5933type SDKLocalCommandOutputMessage = {5957type SDKLocalCommandOutputMessage = {

5943 `SDKCommandsChangedMessage`5967 `SDKCommandsChangedMessage`

5944</h3>5968</h3>

5945 5969

5946当可用命令集在会话中途更改时发出，例如当 Claude Code 在 Agent 进入子目录时发现 skill 时。`commands` 数组是完整的更新列表，因此用此负载替换任何缓存的命令列表。在此消息后调用 [`supportedCommands()`](#query-object) 返回相同的更新列表，因为该方法跟踪最新推送；这需要 Agent SDK v0.3.216 或更高版本。在早期 SDK 版本中，`supportedCommands()` 返回在初始化时捕获的快照，永远不会反映会话中途的更改。5970在会话中途可用命令集合发生变化时发出，例如当 Agent 进入子目录时 Claude Code 发现了 skill。`commands` 数组是完整的更新列表，因此请用此负载替换任何缓存的命令列表。在此消息之后调用 [`supportedCommands()`](#query-object) 会返回相同的更新列表，因为该方法会跟踪最新的推送；这需要 Agent SDK v0.3.216 或更高版本。在更早的 SDK 版本中，`supportedCommands()` 返回初始化时捕获的快照，永远不会反映会话中途的变化。

5947 5971

5948Claude Code 也在 MCP 服务器的 [提示词](/docs/zh-CN/mcp#use-mcp-prompts-as-commands) 加入或离开列表时发出此消息，例如当服务器在会话启动后完成连接时。这需要 Claude Code v2.1.281 或更高版本。5972当 MCP 服务器的[提示词](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)加入或离开列表时（例如服务器在会话开始后才完成连接），Claude Code 也会发出此消息。这需要 Claude Code v2.1.281 或更高版本。

5949 5973

5950```typescript theme={null}5974```typescript theme={null}

5951type SDKCommandsChangedMessage = {5975type SDKCommandsChangedMessage = {

5961 `SDKPromptSuggestionMessage`5985 `SDKPromptSuggestionMessage`

5962</h3>5986</h3>

5963 5987

5964在启用 [`promptSuggestions`](#options) 且 Claude Code 为该轮生成建议时，在轮次后发出。包含预测的下一个用户提示词。对于未获得任何建议的轮次，请参阅 [When Claude Code skips suggestions](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。5988在启用 [`promptSuggestions`](#options) 且 Claude Code 为某个轮次生成了建议时，于该轮次之后发出。包含预测的下一个用户提示词。有关不会获得建议的轮次，请参阅 [Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。

5965 5989

5966```typescript theme={null}5990```typescript theme={null}

5967type SDKPromptSuggestionMessage = {5991type SDKPromptSuggestionMessage = {

5976 `SDKConversationResetMessage`6000 `SDKConversationResetMessage`

5977</h3>6001</h3>

5978 6002

5979在会话的对话被替换而不结束会话时发出。在 `query()` 调用中，只有 `/clear` 及其别名产生此消息。在 `new_conversation_id` 下挂载空会话记录并丢弃任何缓存的会话标题。6003在会话的对话被替换但会话未结束时发出。在 `query()` 调用中，只有 `/clear` 及其别名会产生此消息。请在 `new_conversation_id` 下挂载一个空的会话记录，并丢弃任何缓存的会话标题。

5980 6004

5981```typescript theme={null}6005```typescript theme={null}

5982type SDKConversationResetMessage = {6006type SDKConversationResetMessage = {

5990};6014};

5991```6015```

5992 6016

5993可选字段描述重置：6017可选字段描述此次重置：

5994 6018

5995* `trigger`：什么丢弃了对话。在每个 `conversation_reset` 消息上重置您的会话记录，包括此字段不存在或携带您不认识的值的消息。6019* `trigger`：是什么丢弃了对话。请在每条 `conversation_reset` 消息上重置您的会话记录，包括该字段不存在或携带无法识别的值的消息。

5996* `user_message_uuid`：携带 `/clear` 的用户消息的 `uuid`。使用它将重置与该消息匹配。6020* `user_message_uuid`：携带 `/clear` 的用户消息的 `uuid`。使用它将重置与该消息匹配。

5997* `timestamp`：重置发生的时间，作为 UTC 中的 ISO 8601 字符串。使用它进行显示，而不是用于排序消息。6021* `timestamp`：重置发生的时间，为 UTC 的 ISO 8601 字符串。请将其用于显示，而不是用于消息排序。

5998 6022

5999`trigger`、`user_message_uuid` 和 `timestamp` 字段需要 Claude Code v2.1.281 或更高版本。6023`trigger`、`user_message_uuid` 和 `timestamp` 字段需要 Claude Code v2.1.281 或更高版本。

6000 6024

6001SDK 的已发布类型在 Claude Code v2.1.203 及更高版本中声明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型而不声明它，因此当 `skipLibCheck` 被禁用时，在 `type === "conversation_reset"` 上缩小范围无法通过类型检查。6025在 Claude Code v2.1.203 及更高版本中，SDK 发布的类型定义声明了 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型却未声明它，因此在禁用 `skipLibCheck` 时，基于 `type === "conversation_reset"` 的类型收窄无法通过类型检查。

6002 6026

6003<h3 id="aborterror">6027<h3 id="aborterror">

6004 `AbortError`6028 `AbortError`

6005</h3>6029</h3>

6006 6030

6007中止操作的自定义错误类。6031用于中止操作的自定义错误类。

6008 6032

6009```typescript theme={null}6033```typescript theme={null}

6010class AbortError extends Error {}6034class AbortError extends Error {}

6011```6035```

6012 6036

6013`AbortError` 是 SDK 的类型化 API 中唯一的错误类。其他失败，例如 Claude Code 进程退出或启动失败，使用不携带可供匹配的 SDK 类的错误拒绝消息迭代。[故障排除](/docs/zh-CN/agent-sdk/troubleshooting) 按消息列出这些错误，并给出每个错误的原因和修复方法。6037`AbortError` 是 SDK 类型化 API 中唯一的错误类。其他失败（例如 Claude Code 进程退出或启动失败）会以不带任何可匹配 SDK 类的错误拒绝消息迭代。[故障排除](/docs/zh-CN/agent-sdk/troubleshooting)按消息列出了这些错误，并给出了每种错误的原因和修复方法。

6014 6038

6015<h2 id="sandbox-configuration">6039<h2 id="sandbox-configuration">

6016 沙箱配置6040 沙箱配置

agent-view.md +1 −1

Details

240 240

241无法传递的回复，因为后台服务无法访问或发送失败，会被保存并在其进程再次启动时作为其下一个提示发送到会话，错误消息说回复已保存。前缀为 `!` 的回复不会被保存，因为保存的文本会作为纯提示而不是 Bash 命令到达会话。241无法传递的回复，因为后台服务无法访问或发送失败，会被保存并在其进程再次启动时作为其下一个提示发送到会话，错误消息说回复已保存。前缀为 `!` 的回复不会被保存，因为保存的文本会作为纯提示而不是 Bash 命令到达会话。

242 242

243启用[语音听写](/docs/zh-CN/voice-dictation)后，在回复输入获得焦点时按住或点击你的推送通话键以听写回复而不是输入。同样的功能在 agent view 底部的调度输入中也有效。243在[按住模式](/docs/zh-CN/voice-dictation#hold-to-record)下启用[语音听写](/docs/zh-CN/voice-dictation)后，在回复输入框获得焦点时按住您的按键通话键，即可通过听写而非键入来回复。agent view 底部的分派输入框中也同样适用。

244 244

245使用 `↑` 和 `↓` 窥视相邻会话而不关闭面板，或 `→` 附加。245使用 `↑` 和 `↓` 窥视相邻会话而不关闭面板，或 `→` 附加。

246 246

channels.md +4 −4

Details

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

48 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。48 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。

49 49

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

51 </Step>51 </Step>

52 52

53 <Step title="配置您的令牌">53 <Step title="配置您的令牌">

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

126 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。126 * 插件[在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。

127 127

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

129 </Step>129 </Step>

130 130

131 <Step title="配置您的令牌">131 <Step title="配置您的令牌">

192 192

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

194 194

195 如果安装摘要报告 `Run /reload-plugins to activate.`，您无需在此处理，因为下一步中的重启会加载该插件。195 如果安装摘要报告 `Run /reload-plugins to apply.`，您无需在此处理，因为下一步中的重启会加载该插件。

196 </Step>196 </Step>

197 197

198 <Step title="重启并启用频道">198 <Step title="重启并启用频道">

251 251

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

253 253

254 如果安装摘要报告 `Run /reload-plugins to activate.`，您不需要在此处采取行动，因为下一步中的重启会选择该插件。254 如果安装摘要报告 `Run /reload-plugins to apply.`，您不需要在此处采取行动，因为下一步中的重启会加载该插件。

255 </Step>255 </Step>

256 256

257 <Step title="重启并启用 channel">257 <Step title="重启并启用 channel">

chrome.md +3 −1

Details

35* **会话录制**：将浏览器交互录制为 GIF，以记录或分享发生的情况35* **会话录制**：将浏览器交互录制为 GIF，以记录或分享发生的情况

36 36

37<h2 id="prerequisites">37<h2 id="prerequisites">

~~38 前置条件~~38 前提条件

39</h2>39</h2>

40 40

41在使用 Claude Code 与 Chrome 之前，您需要：41在使用 Claude Code 与 Chrome 之前，您需要：

45* [Claude Code](/docs/zh-CN/quickstart#step-1-install-claude-code)45* [Claude Code](/docs/zh-CN/quickstart#step-1-install-claude-code)

46* 直接 Anthropic 计划（Pro、Max、Team 或 Enterprise）46* 直接 Anthropic 计划（Pro、Max、Team 或 Enterprise）

47 47

48在已启用 HIPAA 的 Enterprise 组织中，Claude in Chrome 默认处于关闭状态，[Owner](/docs/zh-CN/server-managed-settings#access-control) 可以在 [**Organization settings > Claude in Chrome**](https://claude.ai/admin-settings/browser-extension) 中将其启用。您与 Anthropic 签订的商业伙伴协议（BAA）不涵盖通过 Claude in Chrome 发送到第三方网站的数据。有关合格服务（Eligible Services）的列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide)。

48Chrome 集成还需要使用 `/login` 登录。如果您使用 API 密钥或来自 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 的长期令牌进行身份验证，Claude Code 会关闭 Chrome 集成，即使您传递 `--chrome`，因为浏览器扩展程序无法使用这些凭据进行身份验证。在 v2.1.216 之前，这些会话可以启用 Chrome 集成，但每次尝试连接到浏览器扩展程序都会失败，并显示 403 错误。50Chrome 集成还需要使用 `/login` 登录。如果您使用 API 密钥或来自 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 的长期令牌进行身份验证，Claude Code 会关闭 Chrome 集成，即使您传递 `--chrome`，因为浏览器扩展程序无法使用这些凭据进行身份验证。在 v2.1.216 之前，这些会话可以启用 Chrome 集成，但每次尝试连接到浏览器扩展程序都会失败，并显示 403 错误。

49 51

50<Note>52<Note>

claude-code-on-the-web.md +1 −1

Details

64有关 `/web-setup` 的分步说明（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。64有关 `/web-setup` 的分步说明（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。

65 65

66<Note>66<Note>

~~67 启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织无法使用 `/web-setup` 或其他云会话功能。~~67 启用了[零数据保留](/docs/zh-CN/zero-data-retention)或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织无法使用 `/web-setup` 或其他云端会话功能。

68</Note>68</Note>

69 69

70<h3 id="quick-setup-for-team-and-enterprise">70<h3 id="quick-setup-for-team-and-enterprise">

claude-directory.md +2 −2

Details

1582 在以下任一情况下，Claude Code 改为在 `cleanupPeriodDays` 后删除这些会话记录：1582 在以下任一情况下，Claude Code 改为在 `cleanupPeriodDays` 后删除这些会话记录：

1583 1583

1584 * [托管设置](/docs/zh-CN/managed-settings)设置了 `cleanupPeriodDays`1584 * [托管设置](/docs/zh-CN/managed-settings)设置了 `cleanupPeriodDays`

1585 * 您的组织应用了 HIPAA 配置，且 Claude Code 直接连接到 Claude API1585 * [HIPAA 配置适用于您的会话](/docs/zh-CN/hipaa-setup#check-how-developers-sign-in-and-connect)

1586 1586

1587Claude Code 在这些情况下跳过基于年龄的扫描：1587Claude Code 在这些情况下跳过基于年龄的扫描：

1588 1588

1619 1619

1620| `~/.claude/` 下的路径 | 内容 |1620| `~/.claude/` 下的路径 | 内容 |

1621| - | - |1621| - | - |

1622| `history.jsonl` | 您输入的每个提示词，带有时间戳和项目路径。用于向上箭头回忆、`Ctrl+R` 历史搜索和 `!` shell 命令补全。在应用了 HIPAA 配置的组织中，当 Claude Code 直接连接到 Claude API 时，每次扫描都会删除早于 `cleanupPeriodDays` 的条目。 |1622| `history.jsonl` | 您输入的每个提示词，带有时间戳和项目路径。用于向上箭头回忆、`Ctrl+R` 历史搜索和 `!` shell 命令补全。当 [HIPAA 配置适用于您的会话](/docs/zh-CN/hipaa-setup#check-how-developers-sign-in-and-connect)时，每次扫描都会删除早于 `cleanupPeriodDays` 的条目。 |

1624| `remote-settings.json` | [server-managed settings](/docs/zh-CN/server-managed-settings) 的缓存副本，用于您的组织，或当您的组织未配置任何设置时为 `{}`。仅在会话 [获取它们](/docs/zh-CN/server-managed-settings#platform-availability) 时存在。Claude Code 在启动时和会话期间每小时检查更新。Claude Code 在您注销时删除它。 |1624| `remote-settings.json` | [server-managed settings](/docs/zh-CN/server-managed-settings) 的缓存副本，用于您的组织，或当您的组织未配置任何设置时为 `{}`。仅在会话 [获取它们](/docs/zh-CN/server-managed-settings#platform-availability) 时存在。Claude Code 在启动时和会话期间每小时检查更新。Claude Code 在您注销时删除它。 |

claude-security.md +1 −1

Details

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

54* 如果它报告[在市场中找不到该插件](/docs/zh-CN/plugins/install#install-a-plugin)，检查插件名称是否有拼写错误。54* 如果它报告[在市场中找不到该插件](/docs/zh-CN/plugins/install#install-a-plugin)，检查插件名称是否有拼写错误。

55 55

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

57 57

58一旦插件处于活跃状态，您已准备好[扫描和修复您的代码库](#scan-and-fix-your-codebase)。58一旦插件处于活跃状态，您已准备好[扫描和修复您的代码库](#scan-and-fix-your-codebase)。

59 59

code-review.md +2 −2

Details

7> 设置自动化 PR 审查，通过对完整代码库的多代理分析来捕获逻辑错误、安全漏洞和回归问题7> 设置自动化 PR 审查，通过对完整代码库的多代理分析来捕获逻辑错误、安全漏洞和回归问题

8 8

9<Note>9<Note>

10 Code Review 处于研究预览阶段，仅适用于 [Team 和 Enterprise](https://claude.ai/admin-settings/claude-code) 订阅。对于启用了 [Zero Data Retention](/docs/zh-CN/zero-data-retention) 的组织，此功能不可用。在其他计划上，您仍然可以使用 `/code-review` 命令[在本地审查差异](#review-a-diff-locally)。10 Code Review 目前为研究预览版，仅适用于 [Team 和 Enterprise](https://claude.ai/admin-settings/claude-code) 订阅。对于启用了 [Zero Data Retention](/docs/zh-CN/zero-data-retention) 或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织，此功能不可用，且不在 Anthropic 的 BAA 涵盖范围内。在其他套餐上，您仍然可以使用 `/code-review` 命令[在本地审查 diff](#review-a-diff-locally)。

11</Note>11</Note>

12 12

13Code Review 分析您的 GitHub pull request，并在发现问题的代码行上发布内联评论。一支由专业代理组成的团队在完整代码库的上下文中检查代码更改，寻找逻辑错误、安全漏洞、破损的边界情况和微妙的回归问题。13Code Review 分析您的 GitHub pull request，并在发现问题的代码行上发布内联评论。一支由专业代理组成的团队在完整代码库的上下文中检查代码更改，寻找逻辑错误、安全漏洞、破损的边界情况和微妙的回归问题。

429当目标是 `github.com` pull request 时，您可以让 Claude[将完成的发现发布到 PR](/docs/zh-CN/ultrareview#post-findings-to-the-pull-request)作为来自您 GitHub 账户的评论。需要 Claude Code v2.1.227 或更高版本。429当目标是 `github.com` pull request 时，您可以让 Claude[将完成的发现发布到 PR](/docs/zh-CN/ultrareview#post-findings-to-the-pull-request)作为来自您 GitHub 账户的评论。需要 Claude Code v2.1.227 或更高版本。

430 430

431<Note>431<Note>

432 Ultrareview 需要使用 claude.ai 账户进行身份验证，在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，或对启用了零数据保留的组织不可用。当 ultrareview 不可用时，`/code-review ultra` 在您的会话中运行本地审查。432 Ultrareview 需要使用 claude.ai 账户进行身份验证，在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，对启用了零数据保留或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织也不可用。当 ultrareview 不可用时，`/code-review ultra` 在您的会话中运行本地审查。

433</Note>433</Note>

434 434

435要从脚本或 CI 作业运行云审查，请使用 [`claude ultrareview` 子命令](/docs/zh-CN/ultrareview#run-ultrareview-non-interactively)，它会等待发现并将其打印到 stdout。435要从脚本或 CI 作业运行云审查，请使用 [`claude ultrareview` 子命令](/docs/zh-CN/ultrareview#run-ultrareview-non-interactively)，它会等待发现并将其打印到 stdout。

costs.md +1 −1

Details

37 37

38这些总计在 `/clear` 启动新会话时重置，因此下一个会话的总成本从 \$0 开始。在 v2.1.211 之前，它们在 `/clear` 后继续累积，直到 Claude Code 进程的生命周期结束。38这些总计在 `/clear` 启动新会话时重置，因此下一个会话的总成本从 \$0 开始。在 v2.1.211 之前，它们在 `/clear` 后继续累积，直到 Claude Code 进程的生命周期结束。

39 39

40对于以 1.1× [数据驻留费率](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing) 计费的 Claude API 响应，Claude Code 在会话成本数字中将该响应令牌的列表价格乘以 1.1。Claude Code 在[状态行的成本字段](/docs/zh-CN/statusline#cost-and-duration-tracking)中报告相同的总计，并将其与 [`--max-budget-usd`](/docs/zh-CN/cli-reference#cli-flags) 进行比较。在 v2.1.239 之前，Claude Code 没有对这些响应应用 1.1×，因此会话成本数字低于账单。40对于以 1.1× [数据驻留费率](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing) 计费的 Claude API 响应，Claude Code 在会话成本数字中将该响应 token 的列表价格乘以 1.1。相同的总计也会出现在[状态栏的成本字段](/docs/zh-CN/statusline#cost-and-duration-tracking)中，并且乘以后的数字同样计入 [`--max-budget-usd`](/docs/zh-CN/cli-reference#cli-flags)。

41 41

42<h4 id="prompt-cache-statistics">42<h4 id="prompt-cache-statistics">

43 Prompt cache 统计43 Prompt cache 统计

debug-your-config.md +2 −2

Details

29| `/debug [issue]` | 为会话启用调试日志，并提示 Claude 利用日志输出和设置路径进行诊断 |29| `/debug [issue]` | 为会话启用调试日志，并提示 Claude 利用日志输出和设置路径进行诊断 |

30| `/status` | 当前生效的设置来源，包括托管设置是否生效 |30| `/status` | 当前生效的设置来源，包括托管设置是否生效 |

31 31

32如果某个记忆文件未出现在 `/context` 的细分列表中，请对照[CLAUDE.md 文件的加载方式](/docs/zh-CN/memory#how-claude-md-files-load)检查其位置。子目录中的 `CLAUDE.md` 文件并非在会话开始时加载，而是在 Claude 对该目录中的文件使用 Read、Write 或 Edit 工具后按需加载。32如果某个记忆文件未出现在 `/context` 的细分列表中，请对照[CLAUDE.md 文件的加载方式](/docs/zh-CN/memory#how-claude-md-files-load)检查其位置。子目录中的 `CLAUDE.md` 文件是按需加载的，而不是在会话开始时加载，因此它们不会出现在该细分列表中。

33 33

34如果 `/context` 确认文件已加载，但 Claude 仍未遵循某条特定指令，那么问题很可能在于指令的编写方式，而非是否已加载。CLAUDE.md 非常适合用于提供您会给新团队成员的那类指导，例如项目约定、构建命令以及文件应放置的位置。34如果 `/context` 确认文件已加载，但 Claude 仍未遵循某条特定指令，那么问题很可能在于指令的编写方式，而非是否已加载。CLAUDE.md 非常适合用于提供您会给新团队成员的那类指导，例如项目约定、构建命令以及文件应放置的位置。

35 35

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

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

119| 子目录 `CLAUDE.md` 指令似乎被忽略 | 子目录文件按需加载，而不是在会话开始时加载 | 它们在 Claude 对该目录中的文件使用 Read、Write 或 Edit 工具之后加载，而不是在启动时加载。在 v2.1.288 之前，只有 Read 工具会加载它们。请参阅[CLAUDE.md 文件如何加载](/docs/zh-CN/memory#how-claude-md-files-load)。 |119| 子目录 `CLAUDE.md` 指令似乎被忽略 | 子目录文件按需加载，而不是在会话开始时加载 | 请参阅[子目录文件何时加载](/docs/zh-CN/memory#how-claude-md-files-load)。在 v2.1.288 之前，只有 Read 工具会加载它们。 |

120| 子代理忽略 `CLAUDE.md` 指令 | 内置的 Explore 和 Plan 代理跳过 `CLAUDE.md`。自定义子代理以与主对话相同的方式加载它，除非其定义设置了 [`omitClaudeMd`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) | 对于 Explore 或 Plan，在你的委派提示中重新陈述指令。对于设置 `omitClaudeMd` 的子代理，删除该字段。对于任何其他自定义子代理，将关键指令放在代理文件体中，它成为代理的系统提示。请参阅[启动时加载的内容](/docs/zh-CN/sub-agents#what-loads-at-startup)。 |120| 子代理忽略 `CLAUDE.md` 指令 | 内置的 Explore 和 Plan 代理跳过 `CLAUDE.md`。自定义子代理以与主对话相同的方式加载它，除非其定义设置了 [`omitClaudeMd`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) | 对于 Explore 或 Plan，在你的委派提示中重新陈述指令。对于设置 `omitClaudeMd` 的子代理，删除该字段。对于任何其他自定义子代理，将关键指令放在代理文件体中，它成为代理的系统提示。请参阅[启动时加载的内容](/docs/zh-CN/sub-agents#what-loads-at-startup)。 |

122| `.mcp.json` 中的 MCP 服务器永远不加载 | 文件在 `.claude/` 下，或其服务器位于顶级 `servers` 键下，如 VS Code 的 `mcp.json` 中那样，而不是 `mcpServers` | 项目 MCP 配置在存储库根目录下作为 `.mcp.json`，而不是在 `.claude/` 内，服务器位于 `mcpServers` 键下。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |122| `.mcp.json` 中的 MCP 服务器永远不加载 | 文件在 `.claude/` 下，或其服务器位于顶级 `servers` 键下，如 VS Code 的 `mcp.json` 中那样，而不是 `mcpServers` | 项目 MCP 配置在存储库根目录下作为 `.mcp.json`，而不是在 `.claude/` 内，服务器位于 `mcpServers` 键下。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |

desktop.md +22 −21

Details

823 企业配置823 企业配置

824</h2>824</h2>

825 825

826Teams 或 Enterprise 计划上的组织可以通过管理员控制台控制、托管设置文件和设备管理策略来管理桌面应用行为。826Team 或 Enterprise 计划上的组织可以通过管理员控制台控制、托管设置文件和设备管理策略来管理桌面应用行为。

827 827

828<h3 id="admin-console-controls">828<h3 id="admin-console-controls">

829 管理员控制台控制829 管理员控制台控制

831 831

832这些设置通过[管理员设置控制台](https://claude.ai/admin-settings/claude-code)配置：832这些设置通过[管理员设置控制台](https://claude.ai/admin-settings/claude-code)配置：

833 833

834* **Desktop 中的 Code**：控制你的组织中的用户是否可以在桌面应用中访问 Claude Code834* **Desktop**：控制您的组织中的用户是否可以在桌面应用中访问 Claude Code

835* **Web 中的 Code**：为你的组织启用或禁用[云会话](/docs/zh-CN/claude-code-on-the-web)835* **Cloud sessions**：为您的组织启用或禁用[云端会话](/docs/zh-CN/claude-code-on-the-web)

836* **Remote Control**：为你的组织启用或禁用[远程控制](/docs/zh-CN/remote-control)836* **Remote Control**：为您的组织启用或禁用 [Remote Control](/docs/zh-CN/remote-control)

837* **禁用绕过权限模式**：防止你的组织中的用户启用绕过权限模式837

838在启用了 HIPAA 的 Enterprise 组织中，**Desktop** 开关默认关闭，[Owner](/docs/zh-CN/server-managed-settings#access-control) 可以将其打开。应用 [HIPAA 配置](/docs/zh-CN/hipaa-setup)会将其关闭（即使之前已打开），因此 Owner 之后必须重新将其打开。**Cloud sessions** 和 **Remote Control** 也默认关闭，并且一旦组织应用了 HIPAA 配置，Owner 就无法将它们打开。

838 839

839<Note>840<Note>

840 Cowork 下的 OpenTelemetry 表单位于管理员控制台的[数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls)中的**监控**下，仅适用于 Cowork 会话。在此机器上的 Cowork 会话中，桌面应用将该收集器作为 `OTEL_*` 环境变量传递给 Claude Code，因此该表单生效，尽管该会话中的 Claude Code [从不获取管理员控制台设置](#managed-settings)。841 Cowork 下的 OpenTelemetry 表单位于管理员控制台的[数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls)中的**监控**下，仅适用于 Cowork 会话。在此机器上的 Cowork 会话中，桌面应用将该收集器作为 `OTEL_*` 环境变量传递给 Claude Code，因此该表单生效，尽管该会话中的 Claude Code [从不获取管理员控制台设置](#managed-settings)。

841 842

842 要从 Code 选项卡会话导出遥测，请在 Claude Code 托管设置的 `env` 块中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量，如[监控的管理员配置](/docs/zh-CN/monitoring-usage#administrator-configuration)中所示。本地、云和 SSH 会话各自从不同来源读取[托管设置](#managed-settings)。有关云会话可以到达的主机，请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)。有关 Code 选项卡会话报告的 `service.name`，请参阅[服务信息](/docs/zh-CN/monitoring-usage#service-information)。843 要从 Code 选项卡会话导出遥测，请在 Claude Code 托管设置的 `env` 块中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量，如[监控的管理员配置](/docs/zh-CN/monitoring-usage#administrator-configuration)中所示。本地、云端和 SSH 会话各自从不同来源读取[托管设置](#managed-settings)。有关云端会话可以到达的主机，请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)。有关 Code 选项卡会话报告的 `service.name`，请参阅[服务信息](/docs/zh-CN/monitoring-usage#service-information)。

843</Note>844</Note>

844 845

845<h3 id="managed-settings">846<h3 id="managed-settings">

846 托管设置847 托管设置

847</h3>848</h3>

848 849

849托管设置覆盖项目和用户设置，并应用于 Desktop 中的 Claude Code 会话。你可以在你的组织的[托管设置](/docs/zh-CN/managed-settings)文件中设置这些键，或通过管理员控制台远程推送它们。850托管设置覆盖项目和用户设置，并应用于 Desktop 中的 Claude Code 会话。您可以在您的组织的[托管设置](/docs/zh-CN/managed-settings)文件中设置这些键，或通过管理员控制台远程推送它们。

850 851

851| 键 | 描述 |852| 键 | 描述 |

852| - | - |853| - | - |

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

856| `browserExternalPageTools` | 设置为 `"disabled"` 以防止 Claude 使用工具在[浏览器窗格](#browse-external-sites)中读取或作用于外部页面。用户仍然可以自己导航到外部网站，本地开发服务器预览不受影响。 |857| `browserExternalPageTools` | 设置为 `"disabled"` 以防止 Claude 使用工具在[浏览器窗格](#browse-external-sites)中读取或作用于外部页面。用户仍然可以自己导航到外部网站，本地开发服务器预览不受影响。 |

857| `disableMobileSimulatorTools` | 设置为 `true` 以阻止 Claude 在 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)中控制和捕获设备的工具。该窗格仍可用于用户自己的点击；仅删除 Claude 的访问权限。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |858| `disableMobileSimulatorTools` | 设置为 `true` 以阻止 Claude 在 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)中控制和捕获设备的工具。该窗格仍可用于用户自己的点击；仅删除 Claude 的访问权限。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

858| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |859| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

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

861| `disableDesktopLocalSessions` | 设置为 `true` 以关闭[在设备上运行的 Code 会话](#local-sessions-on-managed-devices)，仅保留 SSH 会话到其他主机和云会话可用。该值必须是 JSON 布尔值 `true`。仅从托管设置中读取。需要 Claude Desktop v1.37937.0 或更高版本。 |862| `disableDesktopLocalSessions` | 设置为 `true` 以关闭[在设备上运行的 Code 会话](#local-sessions-on-managed-devices)，仅保留到其他主机的 SSH 会话和云端会话可用。该值必须是 JSON 布尔值 `true`。仅从托管设置中读取。需要 Claude Desktop v1.37937.0 或更高版本。 |

862| `managedMcpServers` | 将 MCP 服务器配置推送到所有用户。仅在第三方 (3P) Desktop 部署中可用。在每个条目中，设置 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。通过托管设置文件、MDM 或 Claude apps gateway 策略的 [`desktop` 块](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)提供它，因为 3P 部署不接收管理员控制台设置。要通过网关提供它，你需要网关服务器上的 Claude Code v2.1.232 或更高版本。这是桌面应用自己的键；Claude Code 读取自己的[同名托管设置](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)，具有不同的条目形状。 |863| `managedMcpServers` | 将 MCP 服务器配置推送到所有用户。仅在第三方 (3P) Desktop 部署中可用。在每个条目中，设置 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。通过托管设置文件、MDM 或 Claude apps gateway 策略的 [`desktop` 块](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)提供它，因为 3P 部署不接收管理员控制台设置。要通过网关提供它，您需要网关服务器上的 Claude Code v2.1.232 或更高版本。这是桌面应用自己的键；Claude Code 读取自己的[同名托管设置](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)，具有不同的条目形状。 |

863 864

864哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[表面覆盖](/docs/zh-CN/model-config#surface-coverage)。865哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[使用入口覆盖范围](/docs/zh-CN/model-config#surface-coverage)。

865 866

866* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。867* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。

867* **[云会话](#cloud-sessions)**：接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话也读取运行程序镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明该文件何时适用。868* **[云端会话](#cloud-sessions)**：接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话也读取运行程序镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明该文件何时适用。

868* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身从本地机器的托管设置中读取 `sshConfigs`、`sshHostAllowlist` 和 `disableDesktopLocalSessions`。869* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身从本地机器的托管设置中读取 `sshConfigs`、`sshHostAllowlist` 和 `disableDesktopLocalSessions`。

869* **[Cowork](https://claude.com/docs/cowork/overview) 会话**：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非你的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。远程 Cowork 会话都不接收。请参阅[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)了解哪些设备文件到达 Cowork，以及[MCP 权限规则](/docs/zh-CN/permissions#mcp)了解 `Bash` 和 `WebFetch` 规则如何应用于 Cowork 的工具。870* **[Cowork](https://claude.com/docs/cowork/overview) 会话**：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非您的 Claude Desktop 配置设置了 `requireCoworkFullVmSandbox`。远程 Cowork 会话两者都不接收。请参阅[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)了解哪些设备文件到达 Cowork，以及[MCP 权限规则](/docs/zh-CN/permissions#mcp)了解 `Bash` 和 `WebFetch` 规则如何应用于 Cowork 的工具。

870 871

871在本地和 SSH 会话中，桌面应用直接将每个用户连接的 claude.ai 连接器传递给 Claude Code。无论你使用哪个设置源或文件位置，都没有 MCP 设置或 `managed-mcp.json` 到达这些连接器。要在这些会话中阻止连接器的工具，请使用你的组织的[连接器工具控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)显示在每种会话中哪些设置管理连接器。872在本地和 SSH 会话中，桌面应用直接将每个用户连接的 claude.ai 连接器传递给 Claude Code。无论您使用哪个设置源或文件位置，都没有 MCP 设置或 `managed-mcp.json` 到达这些连接器。要在这些会话中阻止连接器的工具，请使用您的组织的[连接器工具控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)显示在每种会话中哪些设置管理连接器。

872 873

873`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。874`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。

874 875

902*.claudemcpcontent.com903*.claudemcpcontent.com

903```904```

904 905

905流量在端口 443 上使用 HTTPS，除非你为 [OTLP](/docs/zh-CN/monitoring-usage)、LLM 网关或 MCP 服务器配置自定义端口。906流量在端口 443 上使用 HTTPS，除非您为 [OTLP](/docs/zh-CN/monitoring-usage)、LLM 网关或 MCP 服务器配置自定义端口。

906 907

907有关代理服务器、自定义证书颁发机构、mTLS 和独立 CLI 需要的域，请参阅[网络配置](/docs/zh-CN/network-config)。908有关代理服务器、自定义证书颁发机构、mTLS 和独立 CLI 需要的域，请参阅[网络配置](/docs/zh-CN/network-config)。

908 909

928*.claudemcpcontent.com929*.claudemcpcontent.com

929```930```

930 931

931如果你的组织启用了[IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)用于 Claude，请通过与 `claude.ai` 和 `api.anthropic.com` 相同的代理出口路由 `bridge.claudeusercontent.com`。如果你无法以这种方式路由它，请将你的代理用于该主机的出口地址添加到你的组织的 IP 允许列表，但仅当该地址专用于你的组织时：共享代理出口范围也允许代理供应商的其他客户。932如果您的组织为 Claude 启用了[IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，请通过与 `claude.ai` 和 `api.anthropic.com` 相同的代理出口路由 `bridge.claudeusercontent.com`。如果您无法以这种方式路由它，请将您的代理用于该主机的出口地址添加到您的组织的 IP 允许列表，但仅当该地址专用于您的组织时：共享代理出口范围也允许代理供应商的其他客户。

932 933

933Anthropic 根据它们到达的地址检查与该主机的连接是否符合你的组织的 IP 允许列表。如果你的代理通过不在该允许列表上的地址为其发送流量，Chrome 中的 Claude 和通过网桥连接的其他功能将停止工作，而应用的其余部分继续工作。934Anthropic 根据连接到达的地址检查与该主机的连接是否符合您的组织的 IP 允许列表。如果您的代理通过不在该允许列表上的地址为其发送流量，Chrome 中的 Claude 和通过网桥连接的其他功能将停止工作，而应用的其余部分继续工作。

934 935

935从 [Google Fonts](/docs/zh-CN/artifacts#improve-the-visual-design) 加载字体的[工件](/docs/zh-CN/artifacts)也请求 `fonts.googleapis.com` 和 `fonts.gstatic.com`。两个主机都是可选的。如果你阻止它们，工件将以备用字体呈现。使用快速拒绝而不是静默丢弃来阻止，以便字体请求立即失败，而不是延迟页面的首次呈现。936从 [Google Fonts](/docs/zh-CN/artifacts#improve-the-visual-design) 加载字体的 [Artifact](/docs/zh-CN/artifacts) 也会请求 `fonts.googleapis.com` 和 `fonts.gstatic.com`。两个主机都是可选的。如果您阻止它们，Artifact 将以备用字体呈现。使用快速拒绝而不是静默丢弃来阻止，以便字体请求立即失败，而不是延迟页面的首次呈现。

936 937

937工件还可以从 `cdnjs.cloudflare.com`、`cdn.jsdelivr.net`、`cdn.tailwindcss.com`、`code.jquery.com` 和 `unpkg.com` 加载 JavaScript 库（如 React 或图表包），而不能从其他任何外部主机加载。如果你阻止这些主机，工件中依赖库的部分将无法工作，与阻止的字体不同，阻止的库没有备用。这里也使用快速拒绝，以便阻止的库请求立即失败，而不是挂起直到超时。938Artifact 还可以从 `cdnjs.cloudflare.com`、`cdn.jsdelivr.net`、`cdn.tailwindcss.com`、`code.jquery.com` 和 `unpkg.com` 加载 JavaScript 库（如 React 或图表包），而不能从其他任何外部主机加载。如果您阻止这些主机，Artifact 中依赖库的部分将无法工作，与被阻止的字体不同，被阻止的库没有备用方案。这里也使用快速拒绝，以便被阻止的库请求立即失败，而不是挂起直到超时。

938 939

939<h3 id="authentication-and-sso">940<h3 id="authentication-and-sso">

940 身份验证和 SSO941 身份验证和 SSO

946 数据处理947 数据处理

947</h3>948</h3>

948 949

949Claude Code 在本地会话中本地处理你的代码，或在云会话中在 Anthropic 管理的基础设施上处理，除非你的组织将它们路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。云会话（包括在自托管环境中）将对话和代码上下文发送到 Anthropic 的 API 进行处理；本地和 SSH 会话将它们发送到你的部署配置的任何[模型提供商](#feature-comparison)，默认为 Anthropic 的 API。有关数据保留、隐私和合规性的详细信息，请参阅[数据处理](/docs/zh-CN/data-usage)。950Claude Code 在本地会话中本地处理您的代码，或在云端会话中在 Anthropic 管理的基础设施上处理，除非您的组织将它们路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。云端会话（包括在自托管环境中）将对话和代码上下文发送到 Anthropic 的 API 进行处理；本地和 SSH 会话将它们发送到您的部署配置的任何[模型提供商](#feature-comparison)，默认为 Anthropic 的 API。有关数据保留、隐私和合规性的详细信息，请参阅[数据处理](/docs/zh-CN/data-usage)。

950 951

951<h3 id="deployment">952<h3 id="deployment">

952 部署953 部署

957* **macOS**：通过 MDM（如 Jamf 或 Kandji）使用 `.dmg` 安装程序分发958* **macOS**：通过 MDM（如 Jamf 或 Kandji）使用 `.dmg` 安装程序分发

958* **Windows**：通过 MSIX 包部署。有关企业部署选项（包括静默安装），请参阅[为 Windows 部署 Claude Desktop](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows)959* **Windows**：通过 MSIX 包部署。有关企业部署选项（包括静默安装），请参阅[为 Windows 部署 Claude Desktop](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows)

959 960

960有关在防火墙中允许列表的域，请参阅上面的[网络访问要求](#network-access-requirements)。有关代理设置、自定义证书颁发机构和 LLM 网关，请参阅[网络配置](/docs/zh-CN/network-config)。961有关需要在防火墙中加入允许列表的域，请参阅上面的[网络访问要求](#network-access-requirements)。有关代理设置、自定义证书颁发机构和 LLM 网关，请参阅[网络配置](/docs/zh-CN/network-config)。

961 962

962有关完整的企业配置参考，请参阅[企业配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。963有关完整的企业配置参考，请参阅[企业配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。

963 964

env-vars.md +1 −0

Details

287| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 可在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)命令，而不是通过 `cmd.exe` 启动器。默认情况下，该启动器可让[在后台运行](/docs/zh-CN/tools-reference#background-commands)的 PowerShell 命令[延续到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如当您[将会话转入后台](/docs/zh-CN/agent-view#from-inside-a-session)时。如果设置了该变量，转入后台的 PowerShell 命令会在会话进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |287| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 可在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)命令，而不是通过 `cmd.exe` 启动器。默认情况下，该启动器可让[在后台运行](/docs/zh-CN/tools-reference#background-commands)的 PowerShell 命令[延续到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如当您[将会话转入后台](/docs/zh-CN/agent-view#from-inside-a-session)时。如果设置了该变量，转入后台的 PowerShell 命令会在会话进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |

288| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 可禁用[工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |288| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 可禁用[工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |

289| `CLAUDE_CODE_EFFORT_LEVEL` | 为受支持的模型设置 effort 级别。取值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 以及 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。请参阅[调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |289| `CLAUDE_CODE_EFFORT_LEVEL` | 为受支持的模型设置 effort 级别。取值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 以及 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。请参阅[调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |

290| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 设置为 `1` 可向消息流中添加携带会话状态的 [`session_state_changed`](/docs/zh-CN/agent-sdk/typescript#sdksessionstatechangedmessage) 消息。需要使用 [Agent SDK](/docs/zh-CN/agent-sdk/overview)，或同时使用 `--print`、`--output-format stream-json` 和 `--verbose` |

290| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 仅为与旧版本兼容而接受，不起任何作用。自动模式默认在所有提供商上可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 至 v2.1.206 中，必须将此变量设置为 `1` 才能在这些提供商上使用[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |291| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 仅为与旧版本兼容而接受，不起任何作用。自动模式默认在所有提供商上可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 至 v2.1.206 中，必须将此变量设置为 `1` 才能在这些提供商上使用[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |

291| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/docs/zh-CN/interactive-mode#session-recap)的可用性。设置为 `0` 可强制关闭回顾，无论 `/config` 开关如何设置。当 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时，设置为 `1` 可强制开启回顾。优先于该设置和 `/config` 开关 |292| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/docs/zh-CN/interactive-mode#session-recap)的可用性。设置为 `0` 可强制关闭回顾，无论 `/config` 开关如何设置。当 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时，设置为 `1` 可强制开启回顾。优先于该设置和 `/config` 开关 |

292| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 可在[非交互模式](/docs/zh-CN/headless)下后台安装完成后，在轮次边界刷新插件状态。默认关闭，因为刷新会在会话中途更改系统提示词，导致该轮次的[提示缓存](/docs/zh-CN/prompt-caching)失效 |293| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 可在[非交互模式](/docs/zh-CN/headless)下后台安装完成后，在轮次边界刷新插件状态。默认关闭，因为刷新会在会话中途更改系统提示词，导致该轮次的[提示缓存](/docs/zh-CN/prompt-caching)失效 |

feature-availability.md +2 −0

Details

303 303

304如果您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic Console API 密钥进行身份验证，本部分不适用于您。当您使用 claude.ai 账户登录时，您的计划决定了以下哪些功能可用。304如果您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic Console API 密钥进行身份验证，本部分不适用于您。当您使用 claude.ai 账户登录时，您的计划决定了以下哪些功能可用。

305 305

306在已应用 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的 Enterprise 组织中，此表中的部分功能会被关闭。

307

306| 功能 | Pro | Max | Team | Enterprise |308| 功能 | Pro | Max | Team | Enterprise |

307| :- | :- | :- | :- | :- |309| :- | :- | :- | :- | :- |

308| [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup><a href="#fn6">6</a></sup> |310| [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup><a href="#fn6">6</a></sup> |

hipaa-setup.md +12 −5

Details

15 * Claude Desktop 的 Code 标签页中的 Claude Code15 * Claude Desktop 的 Code 标签页中的 Claude Code

16 * Claude Desktop 中的 Cowork16 * Claude Desktop 中的 Cowork

17 17

18 适用于 VS Code 和 JetBrains 的 Claude Code 扩展不属于（本地模式）。应用 HIPAA 配置后，这些扩展仍可继续使用，但您的 BAA 不涵盖它们。有关合格服务的完整列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=rgirr4qe8u7ek8c2igx3\&name=claude-for-enterprise-hipaa-ready-offering-implementation-guide)。18 适用于 VS Code 和 JetBrains 的 Claude Code 扩展不属于（本地模式）。应用 HIPAA 配置后，这些扩展仍可继续使用，但您的 BAA 不涵盖它们。有关合格服务的完整列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide)。

19</Note>19</Note>

20 20

21本页面面向负责为开发人员准备计算机的 IT 或安全管理员。配置本身由您的 Claude 组织的主要所有者（Primary Owner）应用。[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)说明了您的 BAA 包含的内容、配置的应用方式，以及如何安排应用配置的日期。21本页面面向负责为开发人员准备计算机的 IT 或安全管理员。配置本身由您的 Claude 组织的主要所有者（Primary Owner）应用。[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)说明了您的 BAA 包含的内容、配置的应用方式，以及如何安排应用配置的日期。

174 174

175* **Claude Console 登录和联合凭据**：`forceLoginOrgUUID` 仅检查 claude.ai 登录。[将登录限制为您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)列出了 Claude Code 对每种登录路径和凭据检查的内容。175* **Claude Console 登录和联合凭据**：`forceLoginOrgUUID` 仅检查 claude.ai 登录。[将登录限制为您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)列出了 Claude Code 对每种登录路径和凭据检查的内容。

176* **服务器托管设置**：如果您的组织还使用[服务器托管设置](/docs/zh-CN/server-managed-settings)，请让所有者在其中添加相同的键。[Claude Code 如何合并托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了哪个来源生效。176* **服务器托管设置**：如果您的组织还使用[服务器托管设置](/docs/zh-CN/server-managed-settings)，请让所有者在其中添加相同的键。[Claude Code 如何合并托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了哪个来源生效。

177* **低于 v2.1.285 的版本**：这些版本会忽略 `allowedProviders`，因此仍可能在云提供商或网关上启动。要让 v2.1.163 至 v2.1.284 拒绝启动，您可以在与[示例键](#deploy-managed-settings)相同的托管设置中添加值为 `"2.1.285"` 的 [`requiredMinimumVersion`](/docs/zh-CN/settings-reference#requiredminimumversion)。v2.1.163 之前的版本既会忽略 `allowedProviders`，也会忽略 `requiredMinimumVersion`，因此请[更新这些计算机](#update-claude-code-and-claude-desktop)。

177 178

178要了解您的 BAA 是否涵盖在没有 HIPAA 配置的情况下运行的会话，请参阅[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)。179要了解您的 BAA 是否涵盖在没有 HIPAA 配置的情况下运行的会话，请参阅[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)。

179 180

234 235

235应用 HIPAA 配置后，Claude Code 会从其启动的 shell 命令、hook 和 MCP 服务器的环境中移除其用于访问 Anthropic 的凭据，例如 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`。236应用 HIPAA 配置后，Claude Code 会从其启动的 shell 命令、hook 和 MCP 服务器的环境中移除其用于访问 Anthropic 的凭据，例如 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`。

236 237

237HIPAA 配置不会移除云提供商或 GitHub 凭据，因此推送到 GitHub 或调用其他服务的命令仍然可以使用该开发人员的访问权限正常工作。您与 Anthropic 签订的 BAA 不涵盖发送到这些位置的数据。有关合格服务的完整列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=rgirr4qe8u7ek8c2igx3\&name=claude-for-enterprise-hipaa-ready-offering-implementation-guide)。238HIPAA 配置不会移除云提供商或 GitHub 凭据，因此推送到 GitHub 或调用其他服务的命令仍然可以使用该开发人员的访问权限正常工作。您与 Anthropic 签订的 BAA 不涵盖发送到这些位置的数据。有关合格服务的完整列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide)。

238 239

239要限制 Claude 可以使用的命令和主机，请参阅[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)。240要限制 Claude 可以使用的命令和主机，请参阅[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)。

240 241

275 立即删除会话数据276 立即删除会话数据

276</h3>277</h3>

277 278

278如果您的组织需要在保留清理删除之前移除某位开发人员的会话数据，您可以使用一条命令移除其中的大部分数据。以该开发人员的身份登录计算机，然后在任意 shell 中运行以下命令：279如果您的组织需要在保留清理删除之前移除某位开发人员的会话数据，您可以使用一条命令移除其中的大部分数据。以该开发人员的身份登录计算机，打开任意 shell，然后运行与已安装的 Claude Code 版本对应的命令。

280

281在 Claude Code v2.1.288 或更高版本上，运行 `claude purge`：

279 282

280```bash theme={null}283```bash theme={null}

281claude purge --all --yes284claude purge --all --yes

282```285```

283 286

284在 v2.1.288 之前，该命令为 `claude project purge`。287在 v2.1.126 至 v2.1.287 上，运行 `claude project purge`，它接受相同的标志：

288

289```bash theme={null}

290claude project purge --all --yes

291```

285 292

286该命令会删除每个项目的会话记录和自动记忆、`tasks/`、`debug/` 和 `file-history/` 中的条目、`history.jsonl`，以及 `~/.claude.json` 中的项目条目。如果不加 `--yes`，它会先输出计划并进行询问。293这两个命令都会删除每个项目的会话记录和自动记忆、`tasks/`、`debug/` 和 `file-history/` 中的条目、`history.jsonl`，以及 `~/.claude.json` 中的项目条目。如果不加 `--yes`，它会先输出计划并进行询问。

287 294

288清除操作会保留其他可能包含会话内容的路径，例如 `paste-cache/` 中粘贴的文本。[清除本地数据](/docs/zh-CN/claude-directory#clear-local-data)列出了您可以手动删除的路径。要彻底清理一台计算机（例如在重新分配之前），请[擦除它](#offboard-a-developer)。295清除操作会保留其他可能包含会话内容的路径，例如 `paste-cache/` 中粘贴的文本。[清除本地数据](/docs/zh-CN/claude-directory#clear-local-data)列出了您可以手动删除的路径。要彻底清理一台计算机（例如在重新分配之前），请[擦除它](#offboard-a-developer)。

289 296

hooks.md +1 −1

Details

2140| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 可匹配整个工具。`behavior` 为 `"allow"`、`"deny"` 或 `"ask"` |2140| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 可匹配整个工具。`behavior` 为 `"allow"`、`"deny"` 或 `"ask"` |

2143| `setMode` | `mode`、`destination` | 更改权限模式。有效模式为 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`，以及作为 `default` 别名的 `manual`。`manual` 别名需要 Claude Code v2.1.200 或更高版本 |2143| `setMode` | `mode`、`destination` | 更改权限模式。有效模式为 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`，以及作为 `default` 别名的 `manual` |

2146 2146

interactive-mode.md +1 −1

Details

215| `$` | 行尾 |215| `$` | 行尾 |

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

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

218| `G` | 输入结束 |218| `G` | 最后一行的行首 |

219| `f{char}` | 跳转到下一个字符出现位置 |219| `f{char}` | 跳转到下一个字符出现位置 |

220| `F{char}` | 跳转到上一个字符出现位置 |220| `F{char}` | 跳转到上一个字符出现位置 |

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

legal-and-compliance.md +6 −1

Details

46 医疗保健合规（BAA）46 医疗保健合规（BAA）

47</h3>47</h3>

48 48

49如果客户与 Anthropic 签订了业务关联协议（BAA），并为相关组织启用了[零数据保留（ZDR）](/docs/zh-CN/zero-data-retention)，该 BAA 将扩展到客户通过 Claude Code 的 API 流量。49如果客户与 Anthropic 签订了业务关联协议（BAA），该 BAA 将在以下两种配置中扩展到 Claude Code，具体取决于您的组织可用的选项：

51* **HIPAA 配置**：Claude Code CLI 或 Claude Desktop 中的 Code 标签页，与 Claude for Enterprise 账户配合使用。组织必须已启用 HIPAA，并已将 HIPAA 配置应用于 Claude Code（本地模式）和 Cowork（本地模式）。请参阅[为符合 HIPAA 要求的组织设置 Claude Code（本地模式）](/docs/zh-CN/hipaa-setup)。

52* **零数据保留**：为相关组织启用了[零数据保留（ZDR）](/docs/zh-CN/zero-data-retention)的 Claude Code。ZDR 并非对所有组织都可用。

54在 HIPAA 配置下，云端会话、Remote Control、Claude 移动应用中的 Claude Code，以及通过第三方云提供商或网关路由的 Claude Code 均不在涵盖范围内。请查阅[实施指南](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide)，了解符合条件的服务的完整列表。

50 55

51<h2 id="usage-policy">56<h2 id="usage-policy">

52 使用政策57 使用政策

mcp.md +1 −1

Details

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

53 * plugin [在 marketplace 中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查 plugin 名称。53 * plugin [在 marketplace 中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查 plugin 名称。

54 54

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

56 </Step>56 </Step>

57 57

58 <Step title="运行构建 skill">58 <Step title="运行构建 skill">

memory.md +21 −20

Details

161 161

162所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到您的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近您启动 Claude 的位置的指令最后读取。在每个目录中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之后，因此您的个人笔记是 Claude 在该级别读取的最后一件事。162所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到您的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近您启动 Claude 的位置的指令最后读取。在每个目录中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之后，因此您的个人笔记是 Claude 在该级别读取的最后一件事。

163 163

164Claude 还发现当前工作目录下子目录中的 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不是在启动时加载，而是在 Claude 读取这些子目录中的文件时包含。对于 `.claude/worktrees/` 下 worktree 中的文件，请参阅 [使用 worktree 隔离子代理](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)。164Claude 还发现当前工作目录下子目录中的 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不是在启动时加载，而是在 Claude 读取这些子目录中的文件时包含。如果 Claude 已使用 Read、Write 或 Edit 工具读取、写入或编辑过某个子目录中的 `CLAUDE.md`，则不会以这种方式加载该文件，因为其内容已在对话中。对于 `.claude/worktrees/` 下 worktree 中的文件，请参阅 [使用 worktree 隔离子代理](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)。

165 165

166如果您在大型 monorepo 中工作，其中其他团队的 CLAUDE.md 文件被拾取，请使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。有关根目录和每目录 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型仓库](/docs/zh-CN/large-codebases)。166如果您在大型 monorepo 中工作，其中其他团队的 CLAUDE.md 文件被拾取，请使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。有关根目录和每目录 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型仓库](/docs/zh-CN/large-codebases)。

167 167

623 使用 `/memory` 查看和编辑623 使用 `/memory` 查看和编辑

624</h2>624</h2>

625 625

626`/memory` 命令列出你的 CLAUDE.md、CLAUDE.local.md 和其他内存文件在用户和项目范围内的位置，包括尚不存在的文件的用户和项目 CLAUDE.md 条目。它还让你切换自动记忆开或关，并提供打开自动记忆文件夹的选项。选择任何文件在你的编辑器中打开它；选择一个尚不存在的文件会先创建它。要检查哪些 `CLAUDE.md` 和规则文件加载到当前会话中，请运行 `/context`。626`/memory` 命令列出您的 CLAUDE.md、CLAUDE.local.md 和其他记忆文件在用户和项目作用域内的位置，包括尚不存在的文件的用户和项目 CLAUDE.md 条目。它还允许您开启或关闭自动记忆，并提供打开自动记忆文件夹的选项。选择任何文件即可在您的编辑器中打开它；选择一个尚不存在的文件会先创建它。要检查启动时加载了哪些 `CLAUDE.md` 和规则文件，请运行 `/context`。

627 627

628VS Code 等 GUI 编辑器在单独的窗口中打开文件，你可以在文件打开时继续使用会话。在 v2.1.216 之前，`/memory` 会等待你关闭文件后才响应。Vim 等终端编辑器会接管终端，直到你退出。628VS Code 等 GUI 编辑器在单独的窗口中打开文件，你可以在文件打开时继续使用会话。在 v2.1.216 之前，`/memory` 会等待你关闭文件后才响应。Vim 等终端编辑器会接管终端，直到你退出。

629 629

639 Claude 不遵循我的 CLAUDE.md639 Claude 不遵循我的 CLAUDE.md

640</h3>640</h3>

641 641

642CLAUDE.md 内容作为用户消息在系统提示之后传递，而不是系统提示本身的一部分。Claude 读取它并尝试遵循它，但没有严格遵守的保证，特别是对于模糊或冲突的指令。642CLAUDE.md 内容作为用户消息在系统提示词之后传递，而不是系统提示词本身的一部分。Claude 读取它并尝试遵循它，但没有严格遵守的保证，特别是对于模糊或冲突的指令。

643 643

644要调试：644要调试：

645 645

646* 运行 `/context` 并检查 **Memory files** 下的列表，以验证你的 CLAUDE.md 和 CLAUDE.local.md 文件已加载。如果 `CLAUDE.md` 文件未列出，Claude 看不到它。使用 `/memory` 打开和编辑文件。646* 运行 `/context` 并检查 **Memory files** 下的列表，以验证应在启动时加载的 CLAUDE.md 和 CLAUDE.local.md 文件。如果其中某个文件不在列表中，Claude 就看不到它。使用 `/memory` 打开和编辑文件。

647* 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。647* 工作目录的子目录中的 `CLAUDE.md` 不会出现在 **Memory files** 下，因为它是按需加载而不是在启动时加载的。加载时，终端中会出现一行带有其路径的 `Loaded`。要测试新建的此类文件，请从 shell 中创建它，而不是让 Claude 编写它，然后让 Claude 读取该子目录中的某个文件。

648* 检查相关 CLAUDE.md 是否在为您的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。

648* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。649* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。

649* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。650* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。

650* 检查你的指令是否与 Claude Code 自身添加的指导相竞争。如果你的 CLAUDE.md 设置了提交或拉取请求规则，请使用 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 关闭内置规则，并使用 [`attribution`](/docs/zh-CN/settings-reference#attribution) 设置归属文本。651* 检查您的指令是否与 Claude Code 自身添加的指导相竞争。如果您的 CLAUDE.md 设置了提交或 Pull Request 规则，请使用 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 关闭内置规则，并使用 [`attribution`](/docs/zh-CN/settings-reference#attribution) 设置归属文本。

651 652

652如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 [hook](/docs/zh-CN/hooks-guide) 代替。Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。653如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 [hook](/docs/zh-CN/hooks-guide) 代替。hook 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。

653 654

654对于你想要在系统提示级别的指令，使用 [`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)。你在启动时传递它，因此它更适合脚本和自动化而不是交互式使用。有关它在恢复对话时的行为，请参见 [恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。655对于希望处于系统提示词级别的指令，使用 [`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)。它在启动时传递，因此更适合脚本和自动化而不是交互式使用。有关它在恢复对话时的行为，请参见 [恢复对话中的系统提示词标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

655 656

656<Tip>657<Tip>

657 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录确切加载了哪些 `CLAUDE.md` 和规则文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。658 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录加载了哪些 `CLAUDE.md` 和规则文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。

658</Tip>659</Tip>

659 660

660<h3 id="my-agents-md-isn’t-loading">661<h3 id="my-agents-md-isn’t-loading">

661 我的 AGENTS.md 未加载662 我的 AGENTS.md 未加载

662</h3>663</h3>

663 664

664如果你的存储库有 `AGENTS.md` 而 Claude 似乎不知道它说什么，通常原因是项目路径上某处有 `CLAUDE.md`。默认情况下，Claude 仅在你的工作目录或其上方没有 `CLAUDE.md` 或 `CLAUDE.local.md` 时读取 `AGENTS.md`。按顺序检查这些：665如果您的仓库有 `AGENTS.md` 而 Claude 似乎不知道它说什么，通常原因是项目路径上某处有 `CLAUDE.md`。默认情况下，Claude 仅在您的工作目录或其上方没有 `CLAUDE.md` 或 `CLAUDE.local.md` 时读取 `AGENTS.md`。按顺序检查这些：

665 666

6661. 在你的工作目录或其上方的任何目录中查找 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，除了你的 `~/.claude/CLAUDE.md`。如果你找到一个，Claude 会读取它而不是 `AGENTS.md`，除非你将 **Project instructions** 设置为 `claude-md-and-agents-md`。6671. 在您的工作目录或其上方的任何目录中查找 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，除了您的 `~/.claude/CLAUDE.md`。如果找到一个，Claude 会读取它而不是 `AGENTS.md`，除非您将 **Project instructions** 设置为 `claude-md-and-agents-md`。

6672. 运行 `claude --version` 并确认 v2.1.277 或更高版本。在 v2.1.281 之前，某些会话，例如 Amazon Bedrock 上的会话或禁用遥测的会话，[无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable)，因此在这些版本上更新到 v2.1.281 或更高版本。6682. 运行 `claude --version` 并确认 v2.1.277 或更高版本。在 v2.1.281 之前，某些会话，例如 Amazon Bedrock 上的会话或禁用遥测的会话，也[无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable)，因此在这些版本上请更新到 v2.1.281 或更高版本。

6683. 在你的会话中输入 `/config` 以打开设置面板，并确认 **Project instructions** 未设置为 `claude-md` 或 `managed-only`。如果你根本看不到该设置，你的会话是 [无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable) 的会话。6693. 在会话中输入 `/config` 以打开设置面板，并确认 **Project instructions** 未设置为 `claude-md` 或 `managed-only`。如果根本看不到该设置，则您的会话属于[无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable) 的会话。

669 670

670要检查 Claude 是否读取了你的 `AGENTS.md`，运行 `/memory` 并在列表中查找其路径。671要检查 Claude 是否读取了您的 `AGENTS.md`，运行 `/memory` 并在列表中查找其路径。

671 672

672在 v2.1.280 之前，`/memory` 和 `/context` 没有列出 Claude 直接读取的 `AGENTS.md`。在这些版本上，改为询问 Claude 其项目指令说什么。673在 v2.1.280 之前，`/memory` 和 `/context` 没有列出 Claude 直接读取的 `AGENTS.md`。在这些版本上，改为询问 Claude 其项目指令说什么。

673 674

674如果你想保留你找到的 `CLAUDE.md`，或你的会话无法加载 `AGENTS.md`，[添加一个 `CLAUDE.md` 在你的 `AGENTS.md` 旁边来导入它](#share-one-file-with-other-coding-tools)。675如果您想保留找到的 `CLAUDE.md`，或您的会话无法加载 `AGENTS.md`，请[在您的 `AGENTS.md` 旁边添加一个导入它的 `CLAUDE.md`](#share-one-file-with-other-coding-tools)。

675 676

676<h3 id="i-don’t-know-what-auto-memory-saved">677<h3 id="i-don’t-know-what-auto-memory-saved">

677 我不知道自动记忆保存了什么678 我不知道自动记忆保存了什么

678</h3>679</h3>

679 680

680运行 `/memory` 并选择自动记忆文件夹来浏览 Claude 保存的内容。一切都是纯 markdown，你可以读取、编辑或删除。681运行 `/memory` 并选择自动记忆文件夹来浏览 Claude 保存的内容。一切都是纯 markdown，您可以读取、编辑或删除。

681 682

682<h3 id="my-claude-md-is-too-large">683<h3 id="my-claude-md-is-too-large">

683 我的 CLAUDE.md 太大了684 我的 CLAUDE.md 太大了

684</h3>685</h3>

685 686

686超过 200 行的文件消耗更多上下文并可能降低遵守度。Claude Code 跳过超过 4 MiB 的文件。使用 [path-scoped rules](#path-specific-rules) 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容。分割到 [`@path` imports](#import-additional-files) 有助于组织，但不会减少上下文，因为导入的文件在启动时加载。687超过 200 行的文件消耗更多上下文并可能降低遵守度。Claude Code 会跳过超过 4 MiB 的文件。使用 [path-scoped rules](#path-specific-rules) 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容。分割到 [`@path` imports](#import-additional-files) 有助于组织，但不会减少上下文，因为导入的文件在启动时加载。

687 688

688如果你的一个指令文件超过推荐长度，你会在启动时和运行 `/status` 时看到警告。当每个都在该长度内的文件在会话开始时加起来超过组合限制时，你也会看到警告。每个 CLAUDE.md、规则文件和 `@path` 导入都计为单独的文件。689如果您的某个指令文件超过推荐长度，您会在启动时和运行 `/status` 时看到警告。当各自都在该长度内的文件在会话开始时加起来超过组合限制时，您也会看到警告。每个 CLAUDE.md、规则文件和 `@path` 导入都计为单独的文件。

689 690

690[`/doctor`](/docs/zh-CN/commands#all-commands) 检查为已检入的 CLAUDE.md 提议修剪：它删除 Claude 可以从代码库派生的内容，例如目录布局、依赖项列表和架构概览，并保留与工具默认值不同的陷阱、基本原理和约定。修剪检查需要 Claude Code v2.1.206 或更高版本。691[`/doctor`](/docs/zh-CN/commands#all-commands) 检查为已检入的 CLAUDE.md 提议修剪：它删除 Claude 可以从代码库派生的内容，例如目录布局、依赖项列表和架构概览，并保留与工具默认值不同的陷阱、基本原理和约定。修剪检查需要 Claude Code v2.1.206 或更高版本。

691 692

693 在 `/compact` 后指令似乎丢失了694 在 `/compact` 后指令似乎丢失了

694</h3>695</h3>

695 696

696项目根 CLAUDE.md 在压缩中存活：在 `/compact` 之后，Claude 从磁盘重新读取它并将其重新注入到会话中。子目录中的嵌套 CLAUDE.md 文件和具有 [`paths:` frontmatter](#path-specific-rules) 的规则在 Claude 读取它们适用的文件时重新加载。697项目根 CLAUDE.md 在压缩后仍会保留：在 `/compact` 之后，Claude 从磁盘重新读取它并将其重新注入到会话中。子目录中的嵌套 CLAUDE.md 文件和具有 [`paths:` frontmatter](#path-specific-rules) 的规则在 Claude 读取它们适用的文件时重新加载。

697 698

698如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中，或者是尚未匹配文件的路径范围规则。将仅对话的指令添加到 CLAUDE.md 以使其持久化。有关完整的细分，请参阅 [压缩后存活的内容](/docs/zh-CN/context-window#what-survives-compaction)。699如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中，或者是此后尚未匹配到文件的路径范围规则。将仅在对话中给出的指令添加到 CLAUDE.md 以使其持久化。有关完整的细分，请参阅 [压缩后保留的内容](/docs/zh-CN/context-window#what-survives-compaction)。

699 700

700有关大小、结构和具体性的指导，请参阅 [编写有效的指令](#write-effective-instructions)。701有关大小、结构和具体性的指导，请参阅 [编写有效的指令](#write-effective-instructions)。

701 702

permission-modes.md +5 −8

Details

26| [`bypassPermissions`](#skip-all-checks-with-bypasspermissions-mode) | 一切 | 仅限隔离容器和虚拟机 |26| [`bypassPermissions`](#skip-all-checks-with-bypasspermissions-mode) | 一切 | 仅限隔离容器和虚拟机 |

27 27

28审查每项操作的模式在 CLI 中名为 **Manual**，在 `claude --help` 中、在 VS Code 和 JetBrains 扩展中以及在桌面应用中也是如此。其配置值是 `default`，这是 hooks 和 SDK 集成使用的。CLI 在您输入值的任何地方接受 `manual` 作为别名，例如 `claude --permission-mode manual` 或 `"defaultMode": "manual"`。Manual 标签和 `manual` 别名需要 Claude Code v2.1.200 或更高版本。桌面应用的标签不依赖于您的 CLI 版本。28审查每项操作的模式在 CLI 中名为 **Manual**，在 `claude --help` 中、在 VS Code 和 JetBrains 扩展中以及在桌面应用中也是如此。其配置值是 `default`，这是 hook 和 SDK 集成使用的。CLI 在您输入值的任何地方接受 `manual` 作为别名，例如 `claude --permission-mode manual` 或 `"defaultMode": "manual"`。

29 29

30对 [受保护路径](#protected-paths) 的写入永远不会自动批准，除非在 `bypassPermissions` 模式下以及在 plan 模式会话中，其中绕过权限可用，意味着会话以 [将 `bypassPermissions` 放入模式循环](#switch-permission-modes) 的方式启动。30对 [受保护路径](#protected-paths) 的写入永远不会自动批准，除非在 `bypassPermissions` 模式下以及在 plan 模式会话中，其中绕过权限可用，意味着会话以 [将 `bypassPermissions` 放入模式循环](#switch-permission-modes) 的方式启动。

31 31

359 分类器默认阻止的内容359 分类器默认阻止的内容

360</h3>360</h3>

361 361

362分类器信任您的工作目录以及会话启动时为其配置的远程仓库。在会话期间通过 `git remote add` 或 `git remote set-url` 添加或重新指向的远程仓库不受信任，其他所有内容都被视为外部内容，直到您[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。在 v2.1.200 之前，会话中途添加的远程仓库也受信任。362分类器信任您的工作目录以及会话启动时为其配置的远程仓库。在会话期间通过 `git remote add` 或 `git remote set-url` 添加或重新指向的远程仓库不受信任，其他所有内容都被视为外部内容，直到您[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。

363 363

364**默认阻止**：364**默认阻止**：

365 365

392* 启动无需人工批准或沙箱即可运行的自主 Agent 循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。这包括在禁用隔离和逐操作批准的情况下运行第三方 Agent 或评估工具，例如使用 `--yes-always` 启动的运行器392* 启动无需人工批准或沙箱即可运行的自主 Agent 循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。这包括在禁用隔离和逐操作批准的情况下运行第三方 Agent 或评估工具，例如使用 `--yes-always` 启动的运行器

393* 可能将页面内容、cookie 或凭据发送到源站之外的 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器操作393* 可能将页面内容、cookie 或凭据发送到源站之外的 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器操作

394* 通过通配符、glob 或时间过滤器（而非指定的具体路径）删除 `/tmp`、`$TMPDIR` 或其他共享临时目录或缓存目录中的文件394* 通过通配符、glob 或时间过滤器（而非指定的具体路径）删除 `/tmp`、`$TMPDIR` 或其他共享临时目录或缓存目录中的文件

395* 在发送、上传、发布或写入给他人或共享系统的内容中包含敏感细节，而您自己的消息并未授权将这些细节提供给该接收方。当仓库位于信任边界之外或为公开仓库（包括您组织自己的公开仓库）时，PR 和 issue 正文、提交信息以及评论都属于此类外发内容；内部文件路径、代号、实时 API 响应数据（例如电子邮件或账户标识符）以及基础设施标识符都属于敏感细节。PR、issue 和提交信息的范围限定需要 Claude Code v2.1.200 或更高版本。对于 PR 或 issue 正文中来自 API 响应的实时个人数据，例如电子邮件地址、账户或组织标识符或使用量指标，无论仓库的可见性或信任边界如何，都需要您明确指出这些细节和接收方。该检查需要 Claude Code v2.1.203 或更高版本395* 在发送、上传、发布或写入给他人或共享系统的内容中包含敏感细节，而您自己的消息并未授权将这些细节提供给该接收方。当仓库位于信任边界之外或为公开仓库（包括您组织自己的公开仓库）时，PR 和 issue 正文、提交信息以及评论都属于此类外发内容；内部文件路径、代号、实时 API 响应数据（例如电子邮件或账户标识符）以及基础设施标识符都属于敏感细节。对于 PR 或 issue 正文中来自 API 响应的实时个人数据，例如电子邮件地址、账户或组织标识符或使用量指标，无论仓库的可见性或信任边界如何，都需要您明确指出这些细节和接收方。该检查需要 Claude Code v2.1.203 或更高版本

396* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自身界面，分类器会将此视为 Claude 更改其自身的权限或监督396* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自身界面，分类器会将此视为 Claude 更改其自身的权限或监督

~~397~~

398其中一些类别依赖于[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感远程目标和受保护的 IaC 作用域，您可以将它们收窄到具体名称。

~~399~~

400Claude Code v2.1.200 及更高版本还会默认阻止以下操作：

~~401~~

402* 注释掉、删除或强制通过用于保护安全行为（例如身份验证、访问控制、输入验证或沙箱隔离）的测试或断言397* 注释掉、删除或强制通过用于保护安全行为（例如身份验证、访问控制、输入验证或沙箱隔离）的测试或断言

403* 删除或拆除 Claude 未在本会话中创建的有状态资源，且没有更具体的删除规则适用、您也未指定该资源398* 删除或拆除 Claude 未在本会话中创建的有状态资源，且没有更具体的删除规则适用、您也未指定该资源

404* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向与任务不相符的第三方主机，包括在 `.env.example` 等示例文件中399* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向与任务不相符的第三方主机，包括在 `.env.example` 等示例文件中

406* 将密钥或个人数据、受托数据推送到已知为公开的仓库，或将不属于该仓库本身工作的机密材料推送到该仓库。对于个人数据或受托数据，唯一的例外是 dotfiles 仓库本身的主题内容；来自私有仓库的内容进入任何公开渠道也会以同样方式被阻止；这两项细化都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料归为一类，仅在不属于该仓库本身工作时才被阻止。当仓库的可见性无法确定时，分类器不会仅凭这一点进行阻止，而是依据其他规则来判断内容401* 将密钥或个人数据、受托数据推送到已知为公开的仓库，或将不属于该仓库本身工作的机密材料推送到该仓库。对于个人数据或受托数据，唯一的例外是 dotfiles 仓库本身的主题内容；来自私有仓库的内容进入任何公开渠道也会以同样方式被阻止；这两项细化都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料归为一类，仅在不属于该仓库本身工作时才被阻止。当仓库的可见性无法确定时，分类器不会仅凭这一点进行阻止，而是依据其他规则来判断内容

407* 向其他仓库或组织发起 Pull Request、使用 `gh repo fork` 进行 fork，或推送到第三方仓库，除非您指定了该外部目标402* 向其他仓库或组织发起 Pull Request、使用 `gh repo fork` 进行 fork，或推送到第三方仓库，除非您指定了该外部目标

408 403

404其中一些类别依赖于[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感远程目标和受保护的 IaC 作用域，您可以将它们收窄到具体名称。

405

409Claude Code v2.1.203 及更高版本还会默认阻止以下操作：406Claude Code v2.1.203 及更高版本还会默认阻止以下操作：

410 407

411* 来自敏感本地存储的内容，或来自名称、路径或类型表明其为敏感文件的内容，进入提交、推送、PR 或 issue 文本、gist 或粘贴、或包发布，除非您同时指定了来源和目标。会话记录和对话日志、凭据和配置类点文件夹（例如 SSH 密钥、云凭据、浏览器配置文件和 shell 历史记录）以及用户数据导出都包括在内，仓库为私有也不能解除此阻止408* 来自敏感本地存储的内容，或来自名称、路径或类型表明其为敏感文件的内容，进入提交、推送、PR 或 issue 文本、gist 或粘贴、或包发布，除非您同时指定了来源和目标。会话记录和对话日志、凭据和配置类点文件夹（例如 SSH 密钥、云凭据、浏览器配置文件和 shell 历史记录）以及用户数据导出都包括在内，仓库为私有也不能解除此阻止

permissions.md +2 −2

Details

87 87

88| 模式 | 描述 |88| 模式 | 描述 |

89| :- | :- |89| :- | :- |

90| `default` | 在首次使用每个工具时提示权限。在 CLI、VS Code 和 JetBrains 扩展以及桌面应用中标记为 Manual，Claude Code 接受 `manual` 作为别名。标签和别名需要 Claude Code v2.1.200 或更高版本。桌面应用的标签不依赖于您的 CLI 版本 |90| `default` | 在首次使用每个工具时提示权限。在 CLI、VS Code 和 JetBrains 扩展以及桌面应用中标记为 Manual，Claude Code 接受 `manual` 作为别名 |

91| `acceptEdits` | 自动接受工作目录或 `additionalDirectories` 中路径的文件编辑和常见文件系统命令，例如 `mkdir`、`touch`、`mv` 和 `cp` |91| `acceptEdits` | 自动接受工作目录或 `additionalDirectories` 中路径的文件编辑和常见文件系统命令，例如 `mkdir`、`touch`、`mv` 和 `cp` |

92| `plan` | Claude 读取文件并运行只读 shell 命令来探索，但不编辑您的源文件；在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)可用的情况下，分类器批准的命令也会运行。在 CLI 和 VS Code 扩展中标记为 Plan |92| `plan` | Claude 读取文件并运行只读 shell 命令来探索，但不编辑您的源文件；在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)可用的情况下，分类器批准的命令也会运行。在 CLI 和 VS Code 扩展中标记为 Plan |

93| `auto` | 无需常规提示即可运行；在 shell 命令和网络请求等操作运行之前，后台[分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)会检查它们是否与您的请求一致 |93| `auto` | 无需常规提示即可运行；在 shell 命令和网络请求等操作运行之前，后台[分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)会检查它们是否与您的请求一致 |

773 配置主目录例外仅跳过信任步骤。`~/.claude/settings.local.json` 仍然是[本地范围](/docs/zh-CN/settings#compare-the-scope-of-each-settings-file)，因此 Claude Code 仅在您从主目录本身启动的会话中读取它，而不是在每个项目中。要在所有项目中应用权限规则，请将它们添加到您的用户设置中：`~/.claude/settings.json`，或当设置 `CLAUDE_CONFIG_DIR` 时为 `$CLAUDE_CONFIG_DIR/settings.json`。773 配置主目录例外仅跳过信任步骤。`~/.claude/settings.local.json` 仍然是[本地范围](/docs/zh-CN/settings#compare-the-scope-of-each-settings-file)，因此 Claude Code 仅在您从主目录本身启动的会话中读取它，而不是在每个项目中。要在所有项目中应用权限规则，请将它们添加到您的用户设置中：`~/.claude/settings.json`，或当设置 `CLAUDE_CONFIG_DIR` 时为 `$CLAUDE_CONFIG_DIR/settings.json`。

774</Note>774</Note>

775 775

776在版本 2.1.196 至 2.1.199 中，Claude Code 在您的配置主目录中和 git 存储库外也会暂不应用该文件的规则，并在那里打印[`this workspace has not been trusted`](/docs/zh-CN/errors#workspace-has-not-been-trusted)警告。在 v2.1.207 之前，Claude Code 在您接受对话框之前应用未跟踪文件的规则。776在 v2.1.207 之前，Claude Code 在您接受对话框之前应用未跟踪文件的规则。

777 777

778<h3 id="what-runs-before-you-trust-a-folder">778<h3 id="what-runs-before-you-trust-a-folder">

779 在您信任文件夹之前运行什么779 在您信任文件夹之前运行什么

plugins/install.md +6 −6

Details

71 <Step title="读取安装摘要">71 <Step title="读取安装摘要">

72 摘要的最后一句告诉您插件在此会话中是否可用：72 摘要的最后一句告诉您插件在此会话中是否可用：

73 73

~~74 * **Active now**：`Plugin is now active.` 不需要重新加载。~~74 * **已激活**：`Plugin is now active.` 无需重新加载。

75 * **Active, but a server needs setup**：`Plugin is now active.` 后跟 `Its bundled MCP server needs configuration before it can start`。插件的 [bundled MCP server](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server) 在您设置其选项之前无法启动。在 `/plugin` 的 **Installed** 选项卡上选择插件，然后选择 **Configure** 以设置服务器的选项。75 * **已激活，但服务器需要设置**：`Plugin is now active.` 后跟 `Its bundled MCP server needs configuration before it can start`。在您设置其选项之前，插件的[捆绑 MCP 服务器](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server)无法启动。在 `/plugin` 的 **Installed** 选项卡上选择该插件，然后选择 **Configure** 以设置服务器的选项。

76 * **Reload needed**：`Run /reload-plugins to activate.` 面板关闭，Claude Code 为您运行该重新加载。如果重新加载会 [使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，它会警告并改为保留插件待处理。运行 `/reload-plugins --force` 以激活它，这会花费一个未缓存的请求。76 * **需要重新加载**：`Run /reload-plugins to apply.` 面板会关闭，Claude Code 会为您运行该重新加载。如果重新加载会[使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，它会发出警告，并改为让插件保持待处理状态。运行 `/reload-plugins --force` 可强制激活它，这会产生一次未缓存的请求。

77 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中打开 **Errors** 选项卡以了解原因，然后查看 [安装后：插件不工作](/docs/zh-CN/plugins/troubleshooting#plugin-installed-but-not-working)。77 * **加载失败**：`The plugin couldn't be loaded`。在 `/plugin` 中打开 **Errors** 选项卡查看原因，然后参阅[安装后：插件不工作](/docs/zh-CN/plugins/troubleshooting#plugin-installed-but-not-working)。

78 </Step>78 </Step>

79 79

~~80 <Step title="确认插件有效">~~80 <Step title="确认插件正常工作">

~~81 输入 `/` 并在其名称下查找插件的 skills，形式为 `/<plugin>:<skill>`。对于 `commit-commands`，`/commit-commands:commit` 出现。还有两个其他地方列出插件：~~81 输入 `/`，并在插件名称下查找其 skill，形式为 `/<plugin>:<skill>`。对于 `commit-commands`，会出现 `/commit-commands:commit`。另外还有两个地方会列出该插件：

82 82

83 * 在 `/plugin` 中打开 **Installed** 选项卡，该选项卡列出带有其范围的插件。83 * 在 `/plugin` 中打开 **Installed** 选项卡，该选项卡列出带有其范围的插件。

84 * 在您的 shell 中，运行 `claude plugin list`，它打印相同的列表，带有 `Version`、`Scope` 和 `Status` 行。84 * 在您的 shell 中，运行 `claude plugin list`，它打印相同的列表，带有 `Version`、`Scope` 和 `Status` 行。

plugins/mods/admin.md +1 −1

Details

8 8

9[mod](/docs/zh-CN/plugins/mods/overview) 是在 Claude Code 内运行代码的插件，具有安装它的用户的权限。Mods 不是沙箱化的。通过[托管设置](/docs/zh-CN/managed-settings)，您可以决定 mods 是否在用户的机器上运行、运行哪些 mods 以及运行顺序。您还可以安装自己的 mod，用于监视或拒绝其他 mods 的操作。9[mod](/docs/zh-CN/plugins/mods/overview) 是在 Claude Code 内运行代码的插件，具有安装它的用户的权限。Mods 不是沙箱化的。通过[托管设置](/docs/zh-CN/managed-settings)，您可以决定 mods 是否在用户的机器上运行、运行哪些 mods 以及运行顺序。您还可以安装自己的 mod，用于监视或拒绝其他 mods 的操作。

10 10

11本页面适用于为 Claude Code 部署托管设置的人员，无论是通过文件、MDM 还是从 claude.ai 管理控制台部署。在 Claude Code v2.1.287 及更高版本中，Mods 默认处于启用状态。从与您要执行的操作相匹配的部分开始：11本页面适用于为 Claude Code 部署托管设置的人员，无论是通过文件、MDM 还是从 claude.ai 管理控制台部署。在 Claude Code v2.1.286 及更高版本中，mod 默认处于启用状态。从与您要执行的操作相匹配的部分开始：

12 12

13* **排除用户自己的 mods，有或没有您自己的 mods**：[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)13* **排除用户自己的 mods，有或没有您自己的 mods**：[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)

14* **查看当您不做任何更改时用户会获得什么**：[了解默认情况下会发生什么](#know-what-happens-by-default)14* **查看当您不做任何更改时用户会获得什么**：[了解默认情况下会发生什么](#know-what-happens-by-default)

plugins/mods/create.md +1 −1

Details

14如果你还没有决定 mod 是否是合适的工具，请先阅读[概述中的比较](/docs/zh-CN/plugins/mods/overview#compare-mods-settings-hooks-skills-and-mcp-servers)。14如果你还没有决定 mod 是否是合适的工具，请先阅读[概述中的比较](/docs/zh-CN/plugins/mods/overview#compare-mods-settings-hooks-skills-and-mcp-servers)。

15 15

16<Note>16<Note>

17 Mod 需要 Claude Code v2.1.287 或更高版本。在你的 shell 中，运行 `claude --version` 来检查。要查看 mod 是否可以为你加载，请参阅[检查 mod 是否可以加载](/docs/zh-CN/plugins/mods/troubleshoot#check-whether-mods-can-load)。17 请使用 Claude Code v2.1.287 或更高版本。在 shell 中运行 `claude --version` 进行检查。要查看 mod 是否可以为您加载，请参阅[检查 mod 是否可以加载](/docs/zh-CN/plugins/mods/troubleshoot#check-whether-mods-can-load)。

18</Note>18</Note>

19 19

20<h2 id="ask-claude-for-a-mod">20<h2 id="ask-claude-for-a-mod">

plugins/mods/overview.md +4 −1

Details

110 打开或关闭 mods110 打开或关闭 mods

111</h2>111</h2>

112 112

113Mods 需要 Claude Code v2.1.287 或更高版本，默认情况下它们是打开的。在您的 shell 中，运行 `claude --version` 以检查，如果您的版本较旧，请更新 Claude Code。113mod 默认处于打开状态。在终端中，请使用 Claude Code v2.1.287 或更高版本。Desktop 应用包含其自带的 Claude Code 副本，mod 从 v2.1.286 起即可在其中使用。请在您使用 mod 的地方检查版本：

114

115* **终端**：在您的 shell 中运行 `claude --version`。如果您的版本较旧，请[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。

116* **Desktop 应用**：在 Code 选项卡的本地会话中输入 `/status`，查看 **Claude Code** 一行，其中会显示 `2.1.286` 之类的版本号。如果您的版本较旧，请更新 Desktop 应用。

114 117

115要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：118要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：

116 119

plugins/mods/troubleshoot.md +3 −5

Details

40 40

41mod 添加的任何内容都不会出现：没有命令、没有绘图，也没有行为改变。41mod 添加的任何内容都不会出现：没有命令、没有绘图，也没有行为改变。

42 42

~~43<h3 id="your-version-is-older-than-2-1-287">~~43<h3 id="your-version-is-too-old">

~~44 您的版本早于 2.1.287~~44 您的版本过旧

45</h3>45</h3>

46 46

~~47`claude --version` 打印的版本早于 2.1.287。您的版本早于 mod 默认启用的时期。~~47请参阅[应使用哪个版本以及如何检查您的版本](/docs/zh-CN/plugins/mods/overview#turn-mods-on-or-off)。

~~49[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。~~

50 48

51<h3 id="the-mods-active-line-doesn’t-name-the-mod">49<h3 id="the-mods-active-line-doesn’t-name-the-mod">

52 `mods active` 行不命名 mod50 `mods active` 行不命名 mod

plugins/troubleshooting.md +2 −2

Details

695* **某人发布的插件**：在 `/plugin` 中打开 **Installed** 并打开插件的详细信息窗格，其中列出了插件包含的内容。在那里列出无技能的插件在您键入 `/` 时没有什么可提供的695* **某人发布的插件**：在 `/plugin` 中打开 **Installed** 并打开插件的详细信息窗格，其中列出了插件包含的内容。在那里列出无技能的插件在您键入 `/` 时没有什么可提供的

696 696

697<h3 id="run-reload-plugins-to-activate">697<h3 id="run-reload-plugins-to-activate">

698 `Run /reload-plugins to activate.`698 `Run /reload-plugins to apply.`

699</h3>699</h3>

700 700

701`/plugin` 中的安装摘要以 `Run /reload-plugins to activate.` 结尾，而不是 `Plugin is now active.`701`/plugin` 中的安装摘要以 `Run /reload-plugins to apply.` 结尾，而不是 `Plugin is now active.`。同时，输入框上方可能会出现 `Plugins changed. Run /reload-plugins to activate.` 通知。

702 702

703Claude Code 在安装期间没有激活插件，要么是因为激活它会 [使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，要么是因为激活尝试失败。703Claude Code 在安装期间没有激活插件，要么是因为激活它会 [使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，要么是因为激活尝试失败。

704 704

prompt-library.md +11 −11

Details

1181 title: "将会议转化为工单",1181 title: "将会议转化为工单",

1182 teaches: "省去整理文字稿这一步。Claude 会从非结构化输入中提取行动项，并通过 [MCP](/docs/zh-CN/mcp) 直接写入您的跟踪器，因此您审查的是工单，而不是文字稿。",1182 teaches: "省去整理文字稿这一步。Claude 会从非结构化输入中提取行动项，并通过 [MCP](/docs/zh-CN/mcp) 直接写入您的跟踪器，因此您审查的是工单，而不是文字稿。",

1183 next: "将此保存为 `/tickets` skill",1183 next: "将此保存为 `/tickets` skill",

1184 prompt: "阅读 {input} 并整理出行动项，然后为每一项创建一个包含验收标准的 {tracker} 工单",1184 prompt: "阅读 {input} 并整理出行动项，然后在{tracker}中为每一项创建一个包含验收标准的工单",

1185 slots: {1185 slots: {

1186 input: "@meeting-notes.md",1186 input: "@meeting-notes.md",

1187 tracker: "Linear"1187 tracker: "我们的问题跟踪器"

1188 }1188 }

1189 },1189 },

1190 "map-edge-cases-before": {1190 "map-edge-cases-before": {

1212 next: "请 Claude 将其遵循的模式写入 `CLAUDE.md`，以便以后的会话无需参考也能保持一致",1212 next: "请 Claude 将其遵循的模式写入 `CLAUDE.md`，以便以后的会话无需参考也能保持一致",

1213 prompt: "查看 {example} 的实现方式以理解其模式，然后用相同的方式构建 {new}",1213 prompt: "查看 {example} 的实现方式以理解其模式，然后用相同的方式构建 {new}",

1214 slots: {1214 slots: {

1215 example: "GitHub webhook 处理程序",1215 example: "现有的 webhook 处理程序",

1216 new: "Stripe webhook 处理程序"1216 new: "支付 webhook 处理程序"

1217 }1217 }

1218 },1218 },

1219 "add-a-small-well": {1219 "add-a-small-well": {

1419 "open-a-pull-request": {1419 "open-a-pull-request": {

1420 title: "根据工单创建 Pull Request",1420 title: "根据工单创建 Pull Request",

1421 teaches: "省去在跟踪器、编辑器和 GitHub 之间来回切换。一个提示词即可读取需求、完成更改并创建 PR。",1421 teaches: "省去在跟踪器、编辑器和 GitHub 之间来回切换。一个提示词即可读取需求、完成更改并创建 PR。",

1422 prompt: "找到关于{topic}的 {tracker} 工单，并创建一个实现它的 PR",1422 prompt: "在{tracker}中找到关于{topic}的工单，并创建一个实现它的 PR",

1423 slots: {1423 slots: {

1424 tracker: "Linear",1424 tracker: "我们的问题跟踪器",

1425 topic: "登录超时"1425 topic: "登录超时"

1426 }1426 }

1427 },1427 },

1470 "investigate-a-production-incident": {1470 "investigate-a-production-incident": {

1471 title: "调查生产事件",1471 title: "调查生产事件",

1472 teaches: "列出需要关联分析的证据来源，而不是要采取的步骤。Claude 会综合读取日志、git 历史和配置，以缩小原因范围。",1472 teaches: "列出需要关联分析的证据来源，而不是要采取的步骤。Claude 会综合读取日志、git 历史和配置，以缩小原因范围。",

1473 next: "通过 MCP 连接 Sentry 或您的日志存储",1473 next: "通过 MCP 连接您的错误跟踪器或日志存储",

1474 prompt: "{symptom}。检查日志、最近的部署和配置更改，然后告诉我最可能的原因",1474 prompt: "{symptom}。检查日志、最近的部署和配置更改，然后告诉我最可能的原因",

1475 slots: {1475 slots: {

1476 symptom: "结账端点从一小时前开始返回 500"1476 symptom: "结账端点从一小时前开始返回 500"

1491 teaches: "云控制台会向您展示问题，但不会给出修复命令。Claude 会读取截图，并将仪表板内容转换为需要运行的 kubectl、gcloud 或 aws 命令。",1491 teaches: "云控制台会向您展示问题，但不会给出修复命令。Claude 会读取截图，并将仪表板内容转换为需要运行的 kubectl、gcloud 或 aws 命令。",

1492 prompt: "这是{console}的截图。请带我分析{resource}为什么失败，并给出修复它的确切命令",1492 prompt: "这是{console}的截图。请带我分析{resource}为什么失败，并给出修复它的确切命令",

1493 slots: {1493 slots: {

1494 console: "GCP Kubernetes 仪表板",1494 console: "我们的 Kubernetes 仪表板",

1495 resource: "这个 pod"1495 resource: "这个 pod"

1496 }1496 }

1497 },1497 },

1538 "connect-a-tool-with": {1538 "connect-a-tool-with": {

1539 title: "使用 MCP 连接工具",1539 title: "使用 MCP 连接工具",

1540 teaches: "一次性连接数据源，而不是每个会话都粘贴数据。完成 [MCP](/docs/zh-CN/mcp) 设置后，当您询问相关内容时，Claude 会直接从该工具读取数据。",1540 teaches: "一次性连接数据源，而不是每个会话都粘贴数据。完成 [MCP](/docs/zh-CN/mcp) 设置后，当您询问相关内容时，Claude 会直接从该工具读取数据。",

1541 prompt: "设置 {server} MCP 服务器，以便直接读取我的{data}",1541 prompt: "通过 MCP 连接{server}，以便你能直接读取其{data}",

1542 slots: {1542 slots: {

1543 server: "Sentry",1543 server: "我们的错误跟踪器",

1544 data: "错误报告"1544 data: "堆栈跟踪"

1545 }1545 }

1546 },1546 },

1547 "capture-what-to-remember": {1547 "capture-what-to-remember": {

remote-control.md +2 −2

Details

236 236

237Remote Control 连接时，会话记录（包括您的消息、Claude 的响应和工具活动）存储在 Anthropic 服务器上。存储的记录保持您的设备之间的对话同步，并让会话在网络中断后重新连接。执行和文件系统访问保留在您的机器上，存储的记录根据[数据使用](/docs/zh-CN/data-usage)政策保留。237Remote Control 连接时，会话记录（包括您的消息、Claude 的响应和工具活动）存储在 Anthropic 服务器上。存储的记录保持您的设备之间的对话同步，并让会话在网络中断后重新连接。执行和文件系统访问保留在您的机器上，存储的记录根据[数据使用](/docs/zh-CN/data-usage)政策保留。

238 238

239要完全关闭 Remote Control，请使用 [`disableRemoteControl`](/docs/zh-CN/settings-reference#disableremotecontrol) 设置。具有零数据保留等合规要求的组织无法启用 Remote Control。239要完全关闭 Remote Control，请使用 [`disableRemoteControl`](/docs/zh-CN/settings-reference#disableremotecontrol) 设置。启用了[零数据保留](/docs/zh-CN/zero-data-retention)或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织无法启用 Remote Control。

240 240

241<h2 id="trusted-devices">241<h2 id="trusted-devices">

242 受信任的设备242 受信任的设备

451 451

452* **错误提到 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。452* **错误提到 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。

453* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。453* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。

454* **消息未说联系您的组织管理员**：您的组织具有与 Remote Control 不兼容的 HIPAA 配置，`/status` 在其 `Organization configuration` 行中列出 `HIPAA`。在此状态下，管理面板的 Remote Control 切换呈灰显状态，因此所有者无法在那里更改它。联系 Anthropic 支持以讨论选项。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。454* **消息未说联系您的组织管理员**：您的组织应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)，该配置会关闭 Remote Control。要确认这一点，请运行 `/status` 并在 `Organization configuration` 行中查找 `HIPAA`。所有者会在[管理设置](https://claude.ai/admin-settings/claude-code)中看到 **Remote Control** 切换呈灰显状态，且无法将其打开。如果您对该配置有疑问，请询问所有者，所有者可以联系您组织的 Anthropic 客户团队。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。

455* **否则，所有者尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。所有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。455* **否则，所有者尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。所有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。

456 456

457在 v2.1.281 之前，当 Claude Code 未在此计算机上加载您的组织策略时，此消息也会出现，例如在离线启动后。更高版本将该状态报告为[`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。457在 v2.1.281 之前，当 Claude Code 未在此计算机上加载您的组织策略时，此消息也会出现，例如在离线启动后。更高版本将该状态报告为[`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。

security-guidance.md +1 −1

Details

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

45* 插件[在市场中未找到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。45* 插件[在市场中未找到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。

46 46

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

48 48

49<h3 id="enable-for-your-team-in-local-sessions">49<h3 id="enable-for-your-team-in-local-sessions">

50 在本地会话中为您的团队启用50 在本地会话中为您的团队启用

self-hosted-environments.md +1 −1

Details

45在规划推出之前检查这些：45在规划推出之前检查这些：

46 46

47* **计划**：Team 和 Enterprise 组织的公开测试版。自托管环境默认关闭；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**，这需要为组织启用 [cloud sessions](/docs/zh-CN/claude-code-on-the-web)。47* **计划**：Team 和 Enterprise 组织的公开测试版。自托管环境默认关闭；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**，这需要为组织启用 [cloud sessions](/docs/zh-CN/claude-code-on-the-web)。

~~48* **零数据保留**：对于启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织不可用。~~48* **零数据保留和 HIPAA**：对于启用了[零数据保留](/docs/zh-CN/zero-data-retention)或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织不可用。

49* **模型推理**：会话使用 Anthropic API，除非您将 runner 配置为[将模型请求发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform](/docs/zh-CN/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform)。在这两种情况下，会话内容都会发送给 Anthropic。在以这种方式配置的 runner 上，来自 claude.ai 的[服务器托管设置](/docs/zh-CN/server-managed-settings)和组织策略不会作用于会话。49* **模型推理**：会话使用 Anthropic API，除非您将 runner 配置为[将模型请求发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform](/docs/zh-CN/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform)。在这两种情况下，会话内容都会发送给 Anthropic。在以这种方式配置的 runner 上，来自 claude.ai 的[服务器托管设置](/docs/zh-CN/server-managed-settings)和组织策略不会作用于会话。

50* **表面**：从 [claude.ai/code](https://claude.ai/code)、移动和桌面应用、[计划例程](/docs/zh-CN/routines)以及终端启动的会话，带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](/docs/zh-CN/claude-security) 和[代码审查](/docs/zh-CN/code-review)会话还不能路由到它们。对这两个表面的支持将单独跟进。50* **表面**：从 [claude.ai/code](https://claude.ai/code)、移动和桌面应用、[计划例程](/docs/zh-CN/routines)以及终端启动的会话，带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](/docs/zh-CN/claude-security) 和[代码审查](/docs/zh-CN/code-review)会话还不能路由到它们。对这两个表面的支持将单独跟进。

51* **存储库**：会话从 GitHub 检出存储库；请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)。对于 GitHub Enterprise Server 主机，请参阅其[网络要求](/docs/zh-CN/github-enterprise-server#network-requirements)。51* **存储库**：会话从 GitHub 检出存储库；请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)。对于 GitHub Enterprise Server 主机，请参阅其[网络要求](/docs/zh-CN/github-enterprise-server#network-requirements)。

settings-reference.md +4 −4

Details

1765 * `"auto"`: Claude Code 运行而不进行常规提示；在 shell 命令和网络请求等操作运行之前，后台分类器检查它们是否与您的请求一致1765 * `"auto"`: Claude Code 运行而不进行常规提示；在 shell 命令和网络请求等操作运行之前，后台分类器检查它们是否与您的请求一致

1766 * `"dontAsk"`: Claude Code 自动拒绝每个本应提示的调用；读取、不需要批准的其他操作以及预批准的工具仍然运行1766 * `"dontAsk"`: Claude Code 自动拒绝每个本应提示的调用；读取、不需要批准的其他操作以及预批准的工具仍然运行

1767 * `"bypassPermissions"`: Claude Code 运行所有内容而不询问1767 * `"bypassPermissions"`: Claude Code 运行所有内容而不询问

1768 * `"manual"`: `"default"` 的别名，在 Claude Code v2.1.200 或更高版本中1768 * `"manual"`: `"default"` 的别名

1769* **默认值**: 未设置1769* **默认值**: 未设置

1770* **每个会话覆盖**: `--permission-mode` 及其 `bypassPermissions` 的等效 `--dangerously-skip-permissions` 对一个会话优先于此键1770* **每个会话覆盖**: `--permission-mode` 及其 `bypassPermissions` 的等效 `--dangerously-skip-permissions` 对一个会话优先于此键

1771 1771

1777}1777}

1778```1778```

1779 1779

1780权限规则分层在每种模式之上：`deny` 规则在每种模式中阻止，包括 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes)。`manual` 命名 CLI 和 VS Code 扩展中标记为 Manual 的权限模式；别名需要 Claude Code v2.1.200 或更高版本。在云会话中，Claude Code 仅从此键中遵守 `acceptEdits`、`plan`、`default` 和 `auto`。对于 VS Code 扩展启动的对话，请参阅[扩展为启动权限模式读取的设置](/docs/zh-CN/permission-modes#switch-permission-modes)。1780权限规则分层在每种模式之上：`deny` 规则在每种模式中阻止，包括 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes)。在云端会话中，Claude Code 仅从此键中遵守 `acceptEdits`、`plan`、`default` 和 `auto`。对于 VS Code 扩展启动的对话，请参阅[扩展为启动权限模式读取的设置](/docs/zh-CN/permission-modes#switch-permission-modes)。

1781 1781

1782<h3 id="permissions-disablebypasspermissionsmode">1782<h3 id="permissions-disablebypasspermissionsmode">

1783 `permissions.disableBypassPermissionsMode`1783 `permissions.disableBypassPermissionsMode`

3232 `askUserQuestionTimeout`3232 `askUserQuestionTimeout`

3233</h3>3233</h3>

3234 3234

3235让未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲一段时间后自动继续，提交您已选择的任何选项。当您离开时设置此项，让 Claude 在没有您的情况下继续。使用默认设置时，问题会等待您回答。关于计时器何时暂停或从不启动，请参阅[问题自动继续超时](/docs/zh-CN/tools-reference#question-auto-continue-timeout)。需要 Claude Code v2.1.200 或更高版本。3235让未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲一段时间后自动继续，提交您已选择的任何选项。当您离开时设置此项，让 Claude 在没有您的情况下继续。使用默认设置时，问题会等待您回答。关于计时器何时暂停或从不启动，请参阅[问题自动继续超时](/docs/zh-CN/tools-reference#question-auto-continue-timeout)。

3236 3236

3237* **Scope**: [`User or managed`](#scopes)3237* **Scope**: [`User or managed`](#scopes)

3238* **Type**: string，值为 `"60s"`、`"5m"`、`"10m"` 或 `"never"` 之一3238* **Type**: string，值为 `"60s"`、`"5m"`、`"10m"` 或 `"never"` 之一

3245}3245}

3246```3246```

3247 3247

3248在 `/config` 中显示为**问题自动继续超时**，它将此键写入用户设置；当托管设置或 `--settings` 标志设置此键时，Claude Code 会隐藏该行。需要 Claude Code v2.1.200 或更高版本。3248在 `/config` 中显示为**问题自动继续超时**，它将此键写入用户设置；当托管设置或 `--settings` 标志设置此键时，Claude Code 会隐藏该行。

3249 3249

3250<h3 id="autocontinueatusagelimit">3250<h3 id="autocontinueatusagelimit">

3251 `autoContinueAtUsageLimit`3251 `autoContinueAtUsageLimit`

skills.md +2 −2

Details

52 52

53`/run-skill-generator` 改为记录配方。它从干净的环境中让您的应用运行，捕获有效的内容（安装命令、环境变量、启动脚本），并将其作为每个项目的技能提交到 `.claude/skills/run-<name>/`。之后，`/run`、`/verify` 和存储库中的任何其他代理都遵循记录的配方而不是重新发现它。每个项目运行一次 `/run-skill-generator`，如果构建或启动过程更改，则再次运行。53`/run-skill-generator` 改为记录配方。它从干净的环境中让您的应用运行，捕获有效的内容（安装命令、环境变量、启动脚本），并将其作为每个项目的技能提交到 `.claude/skills/run-<name>/`。之后，`/run`、`/verify` 和存储库中的任何其他代理都遵循记录的配方而不是重新发现它。每个项目运行一次 `/run-skill-generator`，如果构建或启动过程更改，则再次运行。

54 54

55`/verify` 也可以记录自己的配方。当它必须在没有记录的配方的情况下构建和驱动您的应用时，它会将有效的内容写入存储库根目录的 `.claude/skills/verify/SKILL.md`，或在 monorepo 中的受触及的包目录中，以便后续运行和其他代理遵循相同的步骤。在存储库根目录，记录的技能替换捆绑的 `/verify`。这需要 Claude Code v2.1.200 或更高版本。55`/verify` 也可以记录自己的配方。当它必须在没有记录的配方的情况下构建和驱动您的应用时，它会将有效的内容写入存储库根目录的 `.claude/skills/verify/SKILL.md`，或在 monorepo 中的受触及的包目录中，以便后续运行和其他 Agent 遵循相同的步骤。在存储库根目录，记录的 skill 替换随附的 `/verify`。

56 56

57Claude 仅在它引导运行出错时编辑记录的文件，例如失败的命令或缺少的步骤，因此您可以提交文件而无需每个会话的差异。在 v2.1.205 之前，捆绑技能告诉 Claude 折叠运行学到的任何内容，这导致频繁的合并冲突。57Claude 仅在它引导运行出错时编辑记录的文件，例如失败的命令或缺少的步骤，因此您可以提交文件而无需每个会话的差异。在 v2.1.205 之前，捆绑技能告诉 Claude 折叠运行学到的任何内容，这导致频繁的合并冲突。

58 58

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

997* [插件在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。997* [插件在市场中找不到](/docs/zh-CN/plugins/install#install-a-plugin)：检查插件名称。

998 998

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

1000 1000

1001* **测试用例**：在技能目录内的 `evals/evals.json` 中存储提示、输入文件和预期行为1001* **测试用例**：在技能目录内的 `evals/evals.json` 中存储提示、输入文件和预期行为

1002* **隔离运行**：为每个测试用例生成一个[子代理](/docs/zh-CN/sub-agents)，以便每次运行都从干净的上下文开始，并记录令牌计数和持续时间1002* **隔离运行**：为每个测试用例生成一个[子代理](/docs/zh-CN/sub-agents)，以便每次运行都从干净的上下文开始，并记录令牌计数和持续时间

sub-agents.md +2 −2

Details

315| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作为逗号分隔的字符串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，继承 subagents 可用的每个工具。如果列表中没有条目解析为工具，subagent 通常 [fails to launch](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 并出现错误，命名条目。要将 Skills 预加载到上下文中，请使用 `skills` 字段而不是在此处列出 `Skill` |315| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作为逗号分隔的字符串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，继承 subagents 可用的每个工具。如果列表中没有条目解析为工具，subagent 通常 [fails to launch](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 并出现错误，命名条目。要将 Skills 预加载到上下文中，请使用 `skills` 字段而不是在此处列出 `Skill` |

316| `disallowedTools` | 否 | 要拒绝的工具，从继承或指定的列表中删除。格式与 `tools` 相同。带有说明符的条目，例如 `Bash(git push *)`，仍然 [removes the whole tool](#available-tools) |316| `disallowedTools` | 否 | 要拒绝的工具，从继承或指定的列表中删除。格式与 `tools` 相同。带有说明符的条目，例如 `Bash(git push *)`，仍然 [removes the whole tool](#available-tools) |

317| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5-5`）或 `inherit`。当您省略它时，Claude Code 在 [subagent model order](#choose-a-model) 中选择模型 |317| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5-5`）或 `inherit`。当您省略它时，Claude Code 在 [subagent model order](#choose-a-model) 中选择模型 |

318| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作为 `default` 的别名。`manual` 别名需要 Claude Code v2.1.200 或更高版本。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |318| `permissionMode` | 否 | [权限模式](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，或作为 `default` 别名的 `manual`。对[插件子代理](#choose-the-subagent-scope)会被忽略 |

319| `maxTurns` | 否 | subagent 停止前的最大代理轮数。当 subagent 达到限制时，Claude Code 返回其输出标记为部分，Claude 可以 [resume it](#resume-subagents) 继续。部分标记需要 Claude Code v2.1.246 或更高版本 |319| `maxTurns` | 否 | subagent 停止前的最大代理轮数。当 subagent 达到限制时，Claude Code 返回其输出标记为部分，Claude 可以 [resume it](#resume-subagents) 继续。部分标记需要 Claude Code v2.1.246 或更高版本 |

320| `skills` | 否 | [Skills](/docs/zh-CN/skills) 在启动时预加载到 subagent 的上下文中。注入完整的技能内容，而不仅仅是描述。Subagents 仍然可以通过 Skill 工具调用未列出的项目、用户和 plugin 技能 |320| `skills` | 否 | [Skills](/docs/zh-CN/skills) 在启动时预加载到 subagent 的上下文中。注入完整的技能内容，而不仅仅是描述。Subagents 仍然可以通过 Skill 工具调用未列出的项目、用户和 plugin 技能 |

321| `mcpServers` | 否 | [MCP servers](/docs/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/docs/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |321| `mcpServers` | 否 | [MCP servers](/docs/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/docs/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

988 988

989因 API 错误（例如用量限制或反复出现的服务器错误）而结束运行的子代理会将该失败报告给 Claude。Claude 收到的内容取决于子代理的运行位置：989因 API 错误（例如用量限制或反复出现的服务器错误）而结束运行的子代理会将该失败报告给 Claude。Claude 收到的内容取决于子代理的运行位置：

990 990

991* **前台**：如果速率限制、过载或服务器错误截断了已经产生文本输出的子代理，Agent 工具会返回该部分输出，并附注说明子代理被截断、未完成其任务。未产生任何输出、或输出仅包含工具调用的子代理会以 [`Agent terminated early due to an API error`](/docs/zh-CN/errors#agent-terminated-early-due-to-an-api-error) 失败，后跟错误详情。在 v2.1.199 中，速率限制、过载或服务器错误截断仅含工具调用的输出时，返回的是只包含截断说明的空部分结果。991* **前台**：如果速率限制、过载或服务器错误截断了已经产生文本输出的子代理，Agent 工具会返回该部分输出，并附注说明子代理被截断、未完成其任务。未产生任何输出、或输出仅包含工具调用的子代理会以 [`Agent terminated early due to an API error`](/docs/zh-CN/errors#agent-terminated-early-due-to-an-api-error) 失败，后跟错误详情。

992* **后台**：子代理会被标记为失败，Claude 在其结束时收到的消息会指明该 API 错误，并包含子代理的最后输出，因此部分工作不会丢失。992* **后台**：子代理会被标记为失败，Claude 在其结束时收到的消息会指明该 API 错误，并包含子代理的最后输出，因此部分工作不会丢失。

993 993

994当您配置了[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，且子代理遇到该链所覆盖的失败（例如其模型不可用）时，Claude Code 会将子代理切换到链中第一个接受请求的模型。子代理会继续工作，而不是因错误而结束。994当您配置了[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，且子代理遇到该链所覆盖的失败（例如其模型不可用）时，Claude Code 会将子代理切换到链中第一个接受请求的模型。子代理会继续工作，而不是因错误而结束。

tools-reference.md +2 −2

Details

603 603

604Claude Code 在本地草稿中保留您的工作目录，以便它可以找到记录，并且不发送目录。604Claude Code 在本地草稿中保留您的工作目录，以便它可以找到记录，并且不发送目录。

605 605

606在 [零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr) 中，Claude Code 会省略该工具，就像它对 `/feedback` 所做的那样。如果此类组织中的会话仍然提供该工具，草稿保留在您的机器上，发送失败并显示 `Feedback collection is not available for organizations with custom data retention policies.`606在 [零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr) 中，以及在已应用 [HIPAA 配置](/docs/zh-CN/hipaa-setup) 的组织中，Claude Code 会省略该工具，就像它对 `/feedback` 所做的那样。如果零数据保留组织中的会话仍然提供该工具，草稿保留在您的机器上，发送失败并显示 `Feedback collection is not available for organizations with custom data retention policies.`

607 607

608<h3 id="discard-or-keep-a-draft">608<h3 id="discard-or-keep-a-draft">

609 丢弃或保留草稿609 丢弃或保留草稿

627* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 等云会话，无法在您的机器上写入队列627* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 等云会话，无法在您的机器上写入队列

628* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上的会话628* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上的会话

629* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)629* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)

630* 已关闭产品反馈的组织，以及 [零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr)630* 已关闭产品反馈的组织、[零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr)，以及已应用 [HIPAA 配置](/docs/zh-CN/hipaa-setup) 的组织

631 631

632<h2 id="task-tool-availability">632<h2 id="task-tool-availability">

633 Task 工具可用性633 Task 工具可用性

ultrareview.md +1 −1

Details

18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现本地审查可能遗漏的问题18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现本地审查可能遗漏的问题

19* **无本地资源使用**：审查完全在云沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作19* **无本地资源使用**：审查完全在云沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作

20 20

21Ultrareview 需要使用 claude.ai 账户进行身份验证，因为它在 Anthropic 基础设施上作为云会话运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Ultrareview 不可用，对于已启用零数据保留的组织也不可用。当 ultrareview 不可用时，`/code-review ultra` 会在您的会话中运行本地审查。21Ultrareview 需要使用 claude.ai 账户进行身份验证，因为它在 Anthropic 基础设施上作为云端会话运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Ultrareview 不可用；对于已启用零数据保留或已应用 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织也不可用。当 ultrareview 不可用时，`/code-review ultra` 会在您的会话中运行本地审查。

22 22

23<h2 id="run-ultrareview-from-the-cli">23<h2 id="run-ultrareview-from-the-cli">

24 从 CLI 运行 ultrareview24 从 CLI 运行 ultrareview

voice-dictation.md +1 −1

Details

8 8

9在 Claude Code CLI 中说出你的提示词，而不是输入它们。你的语音会实时转录到提示词输入中，所以你可以在同一条消息中混合使用语音和输入。使用 `/voice` 启用听写，然后要么在说话时按住一个键，要么点击一次开始，再点击一次发送。9在 Claude Code CLI 中说出你的提示词，而不是输入它们。你的语音会实时转录到提示词输入中，所以你可以在同一条消息中混合使用语音和输入。使用 `/voice` 启用听写，然后要么在说话时按住一个键，要么点击一次开始，再点击一次发送。

10 10

11听写功能也适用于[代理视图](/docs/zh-CN/agent-view#peek-and-reply)。在调度输入或窥视面板回复获得焦点时，按住或点击你的按键通话键，以便向后台会话进行听写。11在[按住模式](#hold-to-record)下，听写功能也适用于 [Agent 视图](/docs/zh-CN/agent-view#peek-and-reply)。在 Dispatch 输入框或窥视面板回复获得焦点时，按住您的按键通话键，即可向后台会话进行听写。

12 12

13<h2 id="requirements">13<h2 id="requirements">

14 要求14 要求

web-quickstart.md +2 −2

Details

103如果您已经在浏览器中连接了 GitHub，`/web-setup` 会警告您继续将替换您的云会话的该连接。103如果您已经在浏览器中连接了 GitHub，`/web-setup` 会警告您继续将替换您的云会话的该连接。

104 104

105<Note>105<Note>

106 启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织无法使用 `/web-setup` 或其他云会话功能。如果未安装 GitHub CLI 或未进行身份验证，Claude Code 会打开浏览器入门流程。106 启用了[零数据保留](/docs/zh-CN/zero-data-retention)或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)的组织无法使用 `/web-setup` 或其他云端会话功能。如果未安装 GitHub CLI 或未进行身份验证，Claude Code 会打开浏览器入门流程。

107</Note>107</Note>

108 108

109<Steps>109<Steps>

264该命令在另外两种情况下也被隐藏：264该命令在另外两种情况下也被隐藏：

265 265

266* 管理员为您的组织禁用了云会话。在这种情况下，提交 `/web-setup` 返回 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-CN/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，这种情况也返回 `Unknown command: /web-setup`。266* 管理员为您的组织禁用了云会话。在这种情况下，提交 `/web-setup` 返回 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-CN/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，这种情况也返回 `Unknown command: /web-setup`。

267* 您的 Enterprise 组织启用了[零数据保留](/docs/zh-CN/zero-data-retention)，这使云会话不可用。267* 您的 Enterprise 组织启用了[零数据保留](/docs/zh-CN/zero-data-retention)，或应用了 [HIPAA 配置](/docs/zh-CN/hipaa-setup)。任一情况都会使云会话不可用。

268 268

269<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud">269<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud">

270 使用 `--cloud` 时出现 "Could not create a cloud environment" 或 "No cloud environment available"270 使用 `--cloud` 时出现 "Could not create a cloud environment" 或 "No cloud environment available"

zero-data-retention.md +4 −2

Details

4 4

5# 零数据保留5# 零数据保留

6 6

~~7> 了解 Claude for Enterprise 上 Claude Code 的零数据保留 (ZDR)，包括范围、禁用功能以及如何请求启用。~~7> 了解 Claude Code 的零数据保留 (ZDR)，适用于 Claude for Enterprise 上符合条件的账户，包括范围、禁用功能以及如何请求启用。

8 8

9零数据保留 (ZDR) 在通过 Claude for Enterprise 使用 Claude Code 时可用。启用 ZDR 后，Claude Code 会话期间生成的提示和模型响应会实时处理，在返回响应后不会由 Anthropic 存储，除非需要遵守法律或防止滥用。9Claude Code 的零数据保留 (ZDR) 适用于 Claude for Enterprise 上符合条件的账户。启用 ZDR 后，Claude Code 会话期间生成的提示词和模型响应会实时处理，在返回响应后不会由 Anthropic 存储，除非需要遵守法律或防止滥用。

10 10

11<Note>11<Note>

12 ZDR 不包含在标准 Claude for Enterprise 计划中，也无法从您的管理员设置中启用。它仅适用于符合条件的账户，需要由 Anthropic 单独启用。如果您的组织需要 ZDR，请[联系销售](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request)或您的 Anthropic 账户团队以确认资格。12 ZDR 不包含在标准 Claude for Enterprise 计划中，也无法从您的管理员设置中启用。它仅适用于符合条件的账户，需要由 Anthropic 单独启用。如果您的组织需要 ZDR，请[联系销售](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request)或您的 Anthropic 账户团队以确认资格。

13</Note>13</Note>

14 14

15已启用 HIPAA 的 Claude for Enterprise 组织，在将 HIPAA 配置应用于 Claude Code（本地模式）和 Cowork（本地模式）后，无需 ZDR 即可将 Claude Code CLI 和 Claude Desktop 中的 Code 标签页纳入其业务伙伴协议 (BAA) 的覆盖范围。请参阅[为符合 HIPAA 要求的组织设置 Claude Code（本地模式）](/docs/zh-CN/hipaa-setup)。未应用 HIPAA 配置的组织仍需要 ZDR 才能使 Claude Code 获得 BAA 覆盖。有关合格服务的列表，请参阅[实施指南](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide)。

15Claude for Enterprise 上的 ZDR 为企业客户提供了使用 Claude Code 并实现零数据保留的能力，同时可以访问管理功能：17Claude for Enterprise 上的 ZDR 为企业客户提供了使用 Claude Code 并实现零数据保留的能力，同时可以访问管理功能：

16 18

17* 按用户的成本控制19* 按用户的成本控制

Documentation 2026-10-05 23:58 UTC to 2026-10-06 00:58 UTC