Documentation — Spybara

agent-sdk/hooks.md +35 −35

Details

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

16 16

17<h2 id="how-hooks-work">17<h2 id="how-hooks-work">

~~18 Hooks 如何工作~~18 hook 如何工作

19</h2>19</h2>

20 20

21<Steps>21<Steps>

22 <Step title="事件触发">22 <Step title="事件触发">

23 代理执行期间发生某事，SDK 触发事件：工具即将被调用（`PreToolUse`）、工具返回结果（`PostToolUse`）、子代理启动或停止、代理空闲或执行完成。请参阅[完整事件列表](#available-hooks)。23 Agent 执行期间发生某事，SDK 触发事件：工具即将被调用（`PreToolUse`）、工具返回结果（`PostToolUse`）、子代理启动或停止、Agent 空闲或执行完成。请参阅[完整事件列表](#available-hooks)。

24 </Step>24 </Step>

25 25

~~26 <Step title="SDK 收集已注册的 hooks">~~26 <Step title="SDK 收集已注册的 hook">

27 SDK 检查为该事件类型注册的 hooks。这包括您在 `options.hooks` 中传递的回调 hooks 和来自设置文件的 shell 命令 hooks，当相应的 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/docs/zh-CN/agent-sdk/python#settingsource) 条目启用时（默认 `query()` 选项就是这样）。27 SDK 检查为该事件类型注册的 hook。这包括您在 `options.hooks` 中传递的回调 hook 和来自设置文件的 shell 命令 hook，当相应的 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/docs/zh-CN/agent-sdk/python#settingsource) 条目启用时（默认 `query()` 选项就是这样）。

28 </Step>28 </Step>

29 29

~~30 <Step title="匹配器过滤哪些 hooks 运行">~~30 <Step title="匹配器过滤哪些 hook 运行">

31 如果 hook 有 [`matcher`](#matchers) 模式（如 `"Write|Edit"`），SDK 会针对事件的目标（例如工具名称）测试它。没有匹配器的 hooks 对该类型的每个事件都运行。31 如果 hook 有 [`matcher`](#matchers) 模式（如 `"Write|Edit"`），SDK 会针对事件的目标（例如工具名称）测试它。没有匹配器的 hook 对该类型的每个事件都运行。

32 </Step>32 </Step>

33 33

34 <Step title="回调函数执行">34 <Step title="回调函数执行">

36 </Step>36 </Step>

37 37

38 <Step title="您的回调返回决定">38 <Step title="您的回调返回决定">

39 执行任何操作（日志记录、API 调用、验证）后，您的回调返回一个[输出对象](#outputs)，告诉代理该做什么：允许操作、阻止它、修改输入或将上下文注入到对话中。39 执行任何操作（日志记录、API 调用、验证）后，您的回调返回一个[输出对象](#outputs)，告诉 Agent 该做什么：允许操作、阻止它、修改输入或将上下文注入到对话中。

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142

143当您运行任一脚本时，Claude 尝试创建 `.env` 文件，hook 拒绝工具调用，Claude 的最终响应解释它无法创建 `.env` 文件。143当您运行任一脚本时，Claude 尝试创建 `.env` 文件，hook 拒绝该工具调用。

144 144

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

146 可用的 hooks146 可用的 hooks

179| `ConfigChange` | 否 | 是 | 配置文件更改 | 动态重新加载设置 |179| `ConfigChange` | 否 | 是 | 配置文件更改 | 动态重新加载设置 |

180| `InstructionsLoaded` | 否 | 是 | `CLAUDE.md` 或规则文件加载到上下文中 | 审计加载哪些指令文件 |180| `InstructionsLoaded` | 否 | 是 | `CLAUDE.md` 或规则文件加载到上下文中 | 审计加载哪些指令文件 |

181| `WorktreeCreate` | 否 | 是 | Git worktree 创建 | 跟踪隔离的工作区 |181| `WorktreeCreate` | 否 | 是 | Git worktree 创建 | 跟踪隔离的工作区 |

182| `WorktreeRemove` | 否 | 是 | Git worktree 移除 | 清理工作区资源 |182| `WorktreeRemove` | 否 | 是 | 由 `WorktreeCreate` hook 创建的 worktree 正在被移除 | 清理工作区资源 |

183| `CwdChanged` | 否 | 是 | 会话期间工作目录更改 | 按目录重新加载环境变量 |183| `CwdChanged` | 否 | 是 | 会话期间工作目录更改 | 按目录重新加载环境变量 |

184| `FileChanged` | 否 | 是 | 监视的文件被修改、创建或删除 | 项目文件更改时重新加载配置 |184| `FileChanged` | 否 | 是 | 监视的文件被修改、创建或删除 | 项目文件更改时重新加载配置 |

185| `DirectoryAdded` | 否 | 是 | 会话期间添加工作目录 | 为中途添加的存储库安装依赖项 |185| `DirectoryAdded` | 否 | 是 | 会话期间添加工作目录 | 为中途添加的存储库安装依赖项 |

186 186

187<h2 id="configure-hooks">187<h2 id="configure-hooks">

188 配置 hooks188 配置 hook

189</h2>189</h2>

190 190

191要配置 hook，请在您的代理选项的 `hooks` 字段中传递它（Python 中的 `ClaudeAgentOptions`，TypeScript 中的 `options` 对象）。此代码段假设您已经定义了一个 hook 回调，例如上面示例中 Python 中的 `protect_env_files` 或 TypeScript 中的 `protectEnvFiles`：191要配置 hook，请在您的 Agent 选项的 `hooks` 字段中传递它（Python 中的 `ClaudeAgentOptions`，TypeScript 中的 `options` 对象）。此代码段假设您已经定义了一个 hook 回调，例如上面示例中 Python 中的 `protect_env_files` 或 TypeScript 中的 `protectEnvFiles`：

192 192

193<CodeGroup>193<CodeGroup>

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

225 匹配器225 匹配器

226</h3>226</h3>

227 227

228使用匹配器来过滤您的回调何时触发。`matcher` 字段根据 hook 事件类型匹配不同的值。例如，基于工具的 hooks 匹配工具名称，而 `Notification` hooks 匹配通知类型。228使用匹配器来过滤您的回调何时触发。`matcher` 字段根据 hook 事件类型匹配不同的值。例如，基于工具的 hook 匹配工具名称，而 `Notification` hook 匹配通知类型。

229 229

230SDK 匹配器遵循与[设置文件中的匹配器](/docs/zh-CN/hooks#matcher-patterns)相同的规则。该部分记录了精确字符串和正则表达式评估路径、它们的版本要求以及每个事件类型的匹配器值。230SDK 匹配器遵循与[设置文件中的匹配器](/docs/zh-CN/hooks#matcher-patterns)相同的规则。该部分记录了精确字符串和正则表达式评估路径、它们的版本要求以及每个事件类型的匹配器值。

231 231

232| 选项 | 类型 | 默认值 | 描述 |232| 选项 | 类型 | 默认值 | 描述 |

233| - | - | - | - |233| - | - | - | - |

234| `matcher` | `string` | `undefined` | 针对事件的过滤字段匹配的模式，遵循[设置文件中匹配器的规则](/docs/zh-CN/hooks#matcher-patterns)。对于工具 hooks，这是工具名称。内置工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（请参阅[工具输入类型](/docs/zh-CN/agent-sdk/typescript#tool-input-types)以获取完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 配置中使用的键。 |234| `matcher` | `string` | `undefined` | 针对事件的过滤字段匹配的模式，遵循[设置文件中匹配器的规则](/docs/zh-CN/hooks#matcher-patterns)。对于工具 hook，这是工具名称。内置工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（请参阅[工具输入类型](/docs/zh-CN/agent-sdk/typescript#tool-input-types)以获取完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 配置中使用的键。 |

237 237

259 259

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

261 261

262* **顶级字段**在每个事件上被接受：`systemMessage` 向用户显示消息，`continue`（Python 中的 `continue_`）确定代理在此 hook 后是否继续运行。某些事件会丢弃它们或将它们传递到其他地方。每个[事件的部分](/docs/zh-CN/hooks#hook-events)在 hooks 页面上说明它们的去向。262* **顶级字段**在每个事件上被接受：`systemMessage` 向用户显示消息，`continue`（Python 中的 `continue_`）确定 Agent 在此 hook 后是否继续运行。某些事件会丢弃它们或将它们传递到其他地方。hooks 页面上每个[事件的部分](/docs/zh-CN/hooks#hook-events)说明了它们的去向。

263* **`hookSpecificOutput`** 控制当前操作。内部的字段取决于 hook 事件类型：263* **`hookSpecificOutput`** 控制当前操作。内部的字段取决于 hook 事件类型：

264 * 对于 `PreToolUse` hook，这是您设置 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。如果您返回 `"defer"`，该轮次将以一条 `stop_reason` 为 `"tool_deferred"` 的结果消息结束，以便您可以[稍后恢复该调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)。264 * 对于 `PreToolUse` hook，这是您设置 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。如果您返回 `"defer"`，该轮次将以一条 `stop_reason` 为 `"tool_deferred"` 的结果消息结束，以便您可以[稍后恢复该调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)。

265 * 对于 `PostToolUse` hook，您可以设置 `additionalContext` 以将信息附加到工具结果。要在 Claude 看到之前替换工具的输出，请设置 `updatedToolOutput`，这适用于两个 SDK 中的任何工具。较旧的 `updatedMCPToolOutput` 字段仅替换 MCP 工具输出，已弃用。265 * 对于 `PostToolUse` hook，您可以设置 `additionalContext` 以将信息附加到工具结果。要在 Claude 看到之前替换工具的输出，请设置 `updatedToolOutput`，这适用于两个 SDK 中的任何工具。较旧的 `updatedMCPToolOutput` 字段仅替换 MCP 工具输出。

266 * 在 TypeScript SDK 中，`PostToolUse` 回调也可以返回 `classifierContext`，这是关于工具调用结果的简短说明，用于[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)权限分类器。因为您的回调在您的应用程序自己的进程中运行，分类器可能会将您在说明中转达的用户声明视为用户意图。该字段需要 TypeScript Agent SDK v0.3.236 或更高版本。[为自动模式分类器注释结果](/docs/zh-CN/hooks#annotate-a-result-for-the-auto-mode-classifier)涵盖了长度上限、仅同步规则以及不要在说明中放入的内容。266 * 在 TypeScript SDK 中，`PostToolUse` 回调也可以返回 `classifierContext`，这是关于工具调用结果的简短说明，用于[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)权限分类器。因为您的回调在您的应用程序自己的进程中运行，分类器可能会将您在说明中转达的用户声明视为用户意图。该字段需要 TypeScript Agent SDK v0.3.236 或更高版本。[为自动模式分类器注释结果](/docs/zh-CN/hooks#annotate-a-result-for-the-auto-mode-classifier)涵盖了长度上限、仅同步规则以及不要在说明中放入的内容。

267 267

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

269 269

270<Note>270<Note>

271 当多个 hooks 或权限规则适用时，`deny` 优先于 `defer`，`defer` 优先于 `ask`，`ask` 优先于 `allow`。如果任何 hook 返回 `deny`，操作将被阻止，无论其他 hooks 如何。271 当多个 hook 或权限规则适用时，`deny` 优先于 `defer`，`defer` 优先于 `ask`，`ask` 优先于 `allow`。如果任何 hook 返回 `deny`，操作将被阻止，无论其他 hook 如何。

272</Note>272</Note>

273 273

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

275 异步输出275 异步输出

276</h4>276</h4>

277 277

278默认情况下，代理在您的 hook 返回前等待。如果您的 hook 执行副作用，例如日志记录或发送 webhook，并且不需要影响代理的行为，您可以改为返回异步输出。这告诉代理立即继续，而不等待 hook 完成。在此代码段中，Python 中的 `send_to_logging_service` 和 TypeScript 中的 `sendToLoggingService` 代表您定义的任何日志记录函数：278默认情况下，Agent 在您的 hook 返回前等待。如果您的 hook 执行副作用，例如日志记录或发送 webhook，并且不需要影响 Agent 的行为，您可以改为返回异步输出。这告诉 Agent 立即继续，而不等待 hook 完成。在此代码段中，Python 中的 `send_to_logging_service` 和 TypeScript 中的 `sendToLoggingService` 代表您定义的任何日志记录函数：

279 279

280<CodeGroup>280<CodeGroup>

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

296 296

297| 字段 | 类型 | 描述 |297| 字段 | 类型 | 描述 |

298| - | - | - |298| - | - | - |

301 301

302<Note>302<Note>

303 异步输出无法阻止、修改或将上下文注入到操作中，因为代理已经继续。仅将它们用于日志记录、指标或通知等副作用。303 异步输出无法阻止、修改或将上下文注入到操作中，因为 Agent 已经继续。仅将它们用于日志记录、指标或通知等副作用。

304</Note>304</Note>

305 305

306<h2 id="examples">306<h2 id="examples">

804* 验证 hook 事件名称正确且区分大小写（`PreToolUse`，而不是 `preToolUse`）804* 验证 hook 事件名称正确且区分大小写（`PreToolUse`，而不是 `preToolUse`）

805* 检查您的匹配器模式是否与工具名称完全匹配805* 检查您的匹配器模式是否与工具名称完全匹配

806* 确保 hook 在 `options.hooks` 中的正确事件类型下806* 确保 hook 在 `options.hooks` 中的正确事件类型下

807* 对于支持匹配器的非工具 hooks，如 `Notification` 和 `SubagentStop`，匹配器匹配不同的字段，而 `Stop` 完全忽略匹配器（请参阅[匹配器模式](/docs/zh-CN/hooks#matcher-patterns)）807* 对于支持匹配器的非工具 hook，如 `Notification` 和 `SubagentStop`，匹配器匹配不同的字段，而 `Stop` 完全忽略匹配器（请参阅[匹配器模式](/docs/zh-CN/hooks#matcher-patterns)）

808* 当代理达到 [`max_turns`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 限制时，hooks 可能不会触发，因为会话在 hooks 可以执行前结束808* 当 Agent 达到 [`max_turns`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 限制时，hook 可能不会触发，因为会话在 hook 可以执行前结束

809 809

810<h3 id="matcher-not-filtering-as-expected">810<h3 id="matcher-not-filtering-as-expected">

811 匹配器未按预期过滤811 匹配器未按预期过滤

832 832

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

834 834

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

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

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

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

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

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

841* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。841* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。

842 842

850 工具意外被阻止850 工具意外被阻止

851</h3>851</h3>

852 852

853* 检查所有 `PreToolUse` hooks 是否返回 `permissionDecision: 'deny'`853* 检查所有 `PreToolUse` hook 是否返回 `permissionDecision: 'deny'`

854* 向您的 hooks 添加日志记录以查看它们返回的 `permissionDecisionReason`854* 向您的 hook 添加日志记录以查看它们返回的 `permissionDecisionReason`

855* 验证匹配器模式不会太宽泛：空匹配器匹配所有工具855* 验证匹配器模式不会太宽泛：空匹配器匹配所有工具

856 856

857<h3 id="modified-input-not-applied">857<h3 id="modified-input-not-applied">

875* 在 `hookSpecificOutput` 中包括 `hookEventName` 以识别输出针对的 hook 类型875* 在 `hookSpecificOutput` 中包括 `hookEventName` 以识别输出针对的 hook 类型

876 876

877<h3 id="session-hooks-not-available-in-python">877<h3 id="session-hooks-not-available-in-python">

878 Python 中不可用会话 hooks878 Python 中不可用会话 hook

879</h3>879</h3>

880 880

881`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中注册为 SDK 回调 hooks，但在 Python SDK 中不可用，因为其 `HookEvent` 类型省略了它们。在 Python 中，它们仅作为[shell 命令 hooks](/docs/zh-CN/hooks#hook-events)在设置文件中定义，例如 `.claude/settings.json`。要从您的 SDK 应用程序加载 shell 命令 hooks，请使用 [`setting_sources`](/docs/zh-CN/agent-sdk/python#settingsource) 或 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#settingsource) 包括适当的设置源：881`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中注册为 SDK 回调 hook，但在 Python SDK 中不可用，因为其 `HookEvent` 类型省略了它们。在 Python 中，它们仅作为在设置文件（例如 `.claude/settings.json`）中定义的 [shell 命令 hook](/docs/zh-CN/hooks#hook-events) 可用。您的 SDK 应用程序加载哪些设置文件取决于 [`setting_sources`](/docs/zh-CN/agent-sdk/python#settingsource) 或 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#settingsource)。如果您设置了该选项，请包括包含这些 hook 的设置源：

882 882

883<CodeGroup>883<CodeGroup>

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

900 子代理权限提示倍增900 子代理权限提示倍增

901</h3>901</h3>

902 902

903生成多个子代理时，每个子代理可能会单独请求其自身工具调用的权限。要避免重复提示，请使用 `PreToolUse` hooks 自动批准特定工具，或配置权限规则，子代理[从父对话继承](/docs/zh-CN/sub-agents#permission-modes)。903生成多个子代理时，每个子代理可能会单独请求其自身工具调用的权限。要避免重复提示，请使用 `PreToolUse` hook 自动批准特定工具，或配置权限规则，子代理[从父对话继承](/docs/zh-CN/sub-agents#permission-modes)这些规则。

904 904

905<h3 id="recursive-hook-loops-with-subagents">905<h3 id="recursive-hook-loops-with-subagents">

906 子代理的递归 hook 循环906 子代理的递归 hook 循环

909生成子代理的 `UserPromptSubmit` hook 如果这些子代理触发相同的 hook，可能会创建无限循环。要防止这种情况：909生成子代理的 `UserPromptSubmit` hook 如果这些子代理触发相同的 hook，可能会创建无限循环。要防止这种情况：

910 910

911* 使用共享变量或会话状态来跟踪您是否已在子代理内911* 使用共享变量或会话状态来跟踪您是否已在子代理内

912* 将 hooks 范围限制为仅对顶级代理会话运行912* 将 hook 限定为仅对顶级 Agent 会话运行

913 913

914<h3 id="systemmessage-not-appearing-in-output">914<h3 id="systemmessage-not-appearing-in-output">

915 systemMessage 未出现在输出中915 systemMessage 未出现在输出中

916</h3>916</h3>

917 917

918`systemMessage` 字段向用户显示消息，而不是模型。在 Claude Code v2.1.227 或更高版本上，hook 的 `systemMessage` 可以在消息流中显示为 [`SDKInformationalMessage`](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)。它是否显示取决于事件。每个[事件的部分](/docs/zh-CN/hooks#hook-events)在 hooks 页面上说明输出如何显示。要改为将上下文传递给模型，请返回 [`additionalContext`](/docs/zh-CN/hooks#add-context-for-claude)。918`systemMessage` 字段向用户显示消息，而不是模型。在 Claude Code v2.1.227 或更高版本上，hook 的 `systemMessage` 可以在消息流中显示为 [`SDKInformationalMessage`](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)。它是否显示取决于事件。hooks 页面上每个[事件的部分](/docs/zh-CN/hooks#hook-events)说明输出如何显示。要改为将上下文传递给模型，请返回 [`additionalContext`](/docs/zh-CN/hooks#add-context-for-claude)。

919 919

920在 v2.1.227 之前，SDK 仅在消息流中为 `SessionStart` 和 `Setup` hooks 显示 hook 输出。对于任何其他事件，输出仅出现在 [`includeHookEvents`](/docs/zh-CN/agent-sdk/typescript#options)（Python 中为 `include_hook_events`）添加的生命周期事件中。该选项的条目涵盖每个 hook 事件产生的生命周期事件。920在 v2.1.227 之前，SDK 仅在消息流中为 `SessionStart` 和 `Setup` hook 显示 hook 输出。对于任何其他事件，输出仅出现在 [`includeHookEvents`](/docs/zh-CN/agent-sdk/typescript#options)（Python 中为 `include_hook_events`）添加的生命周期事件中。该选项的条目涵盖每个 hook 事件产生的生命周期事件。

921 921

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

923 923

agent-sdk/python.md +138 −137

Details

67 67

68| 参数 | 类型 | 描述 |68| 参数 | 类型 | 描述 |

69| :- | :- | :- |69| :- | :- | :- |

73 73

122| :- | :- | :- |122| :- | :- | :- |

123| `name` | `str` | 工具的唯一标识符 |123| `name` | `str` | 工具的唯一标识符 |

124| `description` | `str` | 工具功能的人类可读描述 |124| `description` | `str` | 工具功能的人类可读描述 |

127 127

128<h4 id="input-schema-options">128<h4 id="input-schema-options">

129 输入架构选项129 输入 schema 选项

130</h4>130</h4>

131 131

1321. **简单类型映射**（推荐）：1321. **简单类型映射**（推荐）：

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196

197工具的行为提示，作为 [`tool()`](#tool) 的 `annotations` 参数传递。`ToolAnnotations` 扩展了 MCP SDK 的 `mcp.types.ToolAnnotations`，添加了 `maxResultSizeChars` 字段，您可以用 camelCase 或 snake\_case 编写每个提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等效的。您也可以在 SDK 接受注解的任何地方传递普通的 `mcp.types.ToolAnnotations`。197工具的行为提示，作为 [`tool()`](#tool) 的 `annotations` 参数传递。`ToolAnnotations` 扩展了 MCP SDK 的 `mcp.types.ToolAnnotations`，添加了 `maxResultSizeChars` 字段，您可以用 camelCase 或 snake\_case 编写每个提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等效的。要从对象中读回某个提示，请使用已安装的 `mcp` 包所声明的拼写：在 `mcp` 1.x 上为 `.readOnlyHint`，在 2.x 上为 `.read_only_hint`，而 `.maxResultSizeChars` 在两者上均可使用。您也可以在 SDK 接受注解的任何地方传递普通的 `mcp.types.ToolAnnotations`。

198 198

199snake\_case 名称和类型化的 `maxResultSizeChars` 字段需要 Python Agent SDK 0.2.140 或更高版本。版本 0.1.31 到 0.2.139 重新导出 `mcp.types.ToolAnnotations` 不变。在版本 0.1.55 到 0.2.139 上，您仍然可以将 `maxResultSizeChars` 作为关键字参数传递：MCP 类接受额外字段，SDK 将值转发给 Claude Code。199snake\_case 名称和类型化的 `maxResultSizeChars` 字段需要 Python Agent SDK 0.2.140 或更高版本。版本 0.1.31 到 0.2.139 重新导出 `mcp.types.ToolAnnotations` 不变。在版本 0.1.55 到 0.2.139 上，您仍然可以将 `maxResultSizeChars` 作为关键字参数传递：MCP 类接受额外字段，SDK 将值转发给 Claude Code。

200 200

210| `maxResultSizeChars` | `int \| None` | `None` | Claude Code 将此工具的文本结果保持内联在对话中而不是保存到文件的字符数，最多 500,000。包含图像的结果不受影响。Claude Code 设置而不是 MCP 提示：SDK 在工具的 `_meta` 中以 `anthropic/maxResultSizeChars` 的形式发送它。请参阅 [提高特定工具的限制](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) |210| `maxResultSizeChars` | `int \| None` | `None` | Claude Code 将此工具的文本结果保持内联在对话中而不是保存到文件的字符数，最多 500,000。包含图像的结果不受影响。Claude Code 设置而不是 MCP 提示：SDK 在工具的 `_meta` 中以 `anthropic/maxResultSizeChars` 的形式发送它。请参阅 [提高特定工具的限制](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) |

211 211

212```python theme={null}212```python theme={null}

311| `offset` | `int` | `0` | 从排序结果开始跳过的会话数。与 `limit` 一起用于分页 |311| `offset` | `int` | `0` | 从排序结果开始跳过的会话数。与 `limit` 一起用于分页 |

313 313

314<h4 id="return-type-sdksessioninfo">314<h4 id="return-type-sdksessioninfo">

315 返回类型：`SDKSessionInfo`315 返回类型：`SDKSessionInfo`

318| 属性 | 类型 | 描述 |318| 属性 | 类型 | 描述 |

319| :- | :- | :- |319| :- | :- | :- |

320| `session_id` | `str` | 唯一会话标识符 |320| `session_id` | `str` | 唯一会话标识符 |

321| `summary` | `str` | 显示标题：自定义标题、最近的提示、自动生成的摘要或第一个提示 |321| `summary` | `str` | 显示标题：自定义标题、最近的提示词、自动生成的摘要或第一个提示词 |

322| `last_modified` | `int` | 上次修改时间，以自纪元以来的毫秒为单位 |322| `last_modified` | `int` | 上次修改时间，以自纪元以来的毫秒为单位 |

327| `cwd` | `str \| None` | 会话的工作目录 |327| `cwd` | `str \| None` | 会话的工作目录 |

328| `tag` | `str \| None` | 用户设置的会话标签（请参阅 [`tag_session()`](#tag_session)） |328| `tag` | `str \| None` | 用户设置的会话标签（请参阅 [`tag_session()`](#tag_session)） |

378| `session_id` | `str` | 会话标识符 |378| `session_id` | `str` | 会话标识符 |

379| `message` | `Any` | 原始消息内容 |379| `message` | `Any` | 原始消息内容 |

382 382

383<h4 id="example-4">383<h4 id="example-4">

384 示例384 示例

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

806| `name` | `str` | 工具的唯一标识符 |806| `name` | `str` | 工具的唯一标识符 |

807| `description` | `str` | 人类可读的描述 |807| `description` | `str` | 人类可读的描述 |

811 811

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

920| :- | :- | :- | :- |920| :- | :- | :- | :- |

921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |

922| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具。这不会限制 Claude 仅使用这些工具。如果你在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择该会话。其他未列出的工具会通过 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |922| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具。这不会限制 Claude 仅使用这些工具。如果您在此处列出[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会为该会话启用它们。其他未列出的工具会交由 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

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

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

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

932| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。作用域规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，对于[按照书写方式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。限定规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，针对[按书写形式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

939| `cwd` | `str \| Path \| None` | `None` | 当前工作目录 |939| `cwd` | `str \| Path \| None` | `None` | 当前工作目录 |

943| `env` | `dict[str, str]` | `{}` | 环境变量合并到继承的进程环境之上。见 [环境变量](/docs/zh-CN/env-vars) 了解底层 CLI 读取的变量，以及 [处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses) 了解超时相关变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识你的应用 |943| `env` | `dict[str, str]` | `{}` | 合并到继承的进程环境之上的环境变量。见 [环境变量](/docs/zh-CN/env-vars) 了解底层 CLI 读取的变量，以及 [处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses) 了解超时相关变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |

944| `extra_args` | `dict[str, str \| None]` | `{}` | 直接传递给 CLI 的其他 CLI 参数 |944| `extra_args` | `dict[str, str \| None]` | `{}` | 直接传递给 CLI 的其他 CLI 参数 |

948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 工具权限回调，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowed_tools` 自动批准的调用、允许规则或 `permission_mode` 调用。允许规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。见 [`CanUseTool`](#canusetool) 了解详情 |948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 工具权限回调，仅在[权限流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。对于由 `allowed_tools`、允许规则或 `permission_mode` 自动批准的调用不会调用。允许规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。见 [`CanUseTool`](#canusetool) 了解详情 |

954| `verbatim_prompts` | `bool` | `False` | 按照书写方式传递每个提示。SDK 使用 `client_composed` 设置为 `True` 发送每条用户消息。见 [`client_composed`](/docs/zh-CN/agent-sdk/typescript#sdkusermessage) 了解 Claude Code 在这些消息上跳过的内容。当你的提示文本包含最终用户未输入的内容时使用此选项。对于每轮控制，将其关闭并改为在单个流式消息上设置 `"client_composed": True`。启用此选项时，SDK 会覆盖你设置的任何 `client_composed` 值。需要 Python Agent SDK 0.2.158 或更高版本以及 Claude Code v2.1.248 或更高版本；这些 SDK 版本附带的 CLI 满足 Claude Code 要求 |954| `verbatim_prompts` | `bool` | `False` | 按原样传递每个提示词。SDK 发送每条用户消息时将 `client_composed` 设置为 `True`。见 [`client_composed`](/docs/zh-CN/agent-sdk/typescript#sdkusermessage) 了解 Claude Code 在这些消息上跳过的内容。当您的提示词文本包含最终用户未输入的内容时使用此选项。如需按轮次控制，请保持关闭，并改为在单个流式消息上设置 `"client_composed": True`。启用此选项时，SDK 会覆盖您设置的任何 `client_composed` 值。需要 Python Agent SDK 0.2.158 或更高版本以及 Claude Code v2.1.248 或更高版本；这些 SDK 版本附带的 CLI 满足 Claude Code 要求 |

961| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。有关无论此选项如何都会读取的输入，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |961| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。如果设置了 `skills` 而未设置此字段，则仅加载用户和项目源。显式设置 `setting_sources` 以保留本地设置。端点托管策略始终会加载；当会话使用组织凭据在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器托管设置。有关无论此选项如何都会读取的输入，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 会话可用的技能。传递 `"all"` 以启用每个发现的技能，或传递技能名称列表。仅传递精确名称。SDK 在启动 Claude Code 进程之前会以 `ValueError` 拒绝格式错误和通配符形式的名称；此检查需要 Python Agent SDK 0.2.129 或更高版本。设置时，SDK 会自动将 Skill 工具添加到 `allowed_tools`。如果你也传递 `tools`，在该列表中包含 `"Skill"`。见 [Skills](/docs/zh-CN/agent-sdk/skills) |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 会话可用的 skill。传递 `"all"` 以启用每个发现的 skill，或传递 skill 名称列表。仅传递精确名称。SDK 在启动 Claude Code 进程之前会以 `ValueError` 拒绝格式错误和通配符形式的名称；此检查需要 Python Agent SDK 0.2.129 或更高版本。设置时，SDK 会自动将 Skill 工具添加到 `allowed_tools`。如果您也传递 `tools`，请在该列表中包含 `"Skill"`。见 [Skills](/docs/zh-CN/agent-sdk/skills) |

968| `load_timeout_ms` | `int` | `60000` | 在恢复物化期间，`session_store.load()` 和 `list_subkeys()` 的每次调用超时，以毫秒为单位 |968| `load_timeout_ms` | `int` | `60000` | 在恢复物化期间，`session_store.load()` 和 `list_subkeys()` 的每次调用超时时间，以毫秒为单位 |

969| `task_budget` | `TaskBudget \| None` | `None` | API 端令牌预算。使用 `task-budgets-2026-03-13` 测试版标头作为 `output_config.task_budget` 发送。传递 `{"total": <int>}`。 |969| `task_budget` | `TaskBudget \| None` | `None` | API 端 token 预算。作为 `output_config.task_budget` 随 `task-budgets-2026-03-13` 测试版标头发送。传递 `{"total": <int>}`。 |

970 970

971<h4 id="handle-slow-or-stalled-api-responses">971<h4 id="handle-slow-or-stalled-api-responses">

972 处理缓慢或停滞的 API 响应972 处理缓慢或停滞的 API 响应

986)986)

987```987```

988 988

989* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时，以毫秒为单位。默认 `600000`。适用于主循环和所有子代理。989* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时时间，以毫秒为单位。默认 `600000`。适用于主循环和所有子代理。

990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它无限期重试瞬时容量错误，自 Claude Code v2.1.199 起，对其他瞬时错误将默认值提高到 `300` 并移除此变量的上限。990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避时间。对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它会无限期重试瞬时容量错误，并且在 Claude Code v2.1.199 或更高版本上，将其他瞬时错误的默认值提高到 `300` 并移除此变量的上限。

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞监视器。当流监视器打开时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非你提高该变量。当流监视器关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞监视器。当流监视器开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。当流监视器关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。

992 992

993 计时器在每个流事件时重置。停滞时，Claude Code 中止子代理并向父代理报告停滞。对于后台子代理，它也会将任务标记为失败并附加任何部分结果。993 计时器在每个流事件时重置。停滞时，Claude Code 中止子代理并向父 Agent 报告停滞。对于后台子代理，它也会将任务标记为失败并附加任何部分结果。

994* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：流监视器，当标头已到达但响应体停止流式传输时中止请求。监视器对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止后，[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖 Claude Code 所做的事情，基于响应进行的程度。994* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：流监视器，当标头已到达但响应体停止流式传输时中止请求。监视器对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000`，且不能低于该最小值。中止后 Claude Code 会如何处理取决于响应已进行到什么程度，详见[自动重试](/docs/zh-CN/errors#automatic-retries)。

995 995

996 当监视器等待 `ANTHROPIC_BASE_URL` 后面的网关保持打开的响应时，设置 `include_partial_messages` 的主机继续接收 `ping` [`StreamEvent`](#streamevent) 消息。将这些帧读作活跃性而不是在沉默时超时会话。在 v2.1.257 之前，帧在最后一个真实流事件后 5 分钟停止。996 当 `ANTHROPIC_BASE_URL` 后面的网关通过 keep-alive ping 保持响应打开、而监视器在等待该响应时，设置了 `include_partial_messages` 的主机会持续接收 `ping` [`StreamEvent`](#streamevent) 消息。请将这些帧视为存活信号，而不要因为静默而使会话超时。在 v2.1.257 之前，这些帧会在最后一个真实流事件后 5 分钟停止。

997 997

998<h3 id="outputformat">998<h3 id="outputformat">

999 `OutputFormat`999 `OutputFormat`

1018 `SystemPromptPreset`1018 `SystemPromptPreset`

1019</h3>1019</h3>

1020 1020

1021使用 Claude Code 的预设系统提示和可选添加的配置。1021使用 Claude Code 的预设系统提示词和可选添加内容的配置。

1022 1022

1023```python theme={null}1023```python theme={null}

1024class SystemPromptPreset(TypedDict):1024class SystemPromptPreset(TypedDict):

1031 1031

1032| 字段 | 必需 | 描述 |1032| 字段 | 必需 | 描述 |

1033| :- | :- | :- |1033| :- | :- | :- |

1034| `type` | 是 | 必须是 `"preset"` 以使用预设系统提示 |1034| `type` | 是 | 必须是 `"preset"` 以使用预设系统提示词 |

1035| `preset` | 是 | 必须是 `"claude_code"` 以使用 Claude Code 的系统提示 |1035| `preset` | 是 | 必须是 `"claude_code"` 以使用 Claude Code 的系统提示词 |

1036| `append` | 否 | 要追加到预设系统提示的其他说明 |1036| `append` | 否 | 要追加到预设系统提示词的其他说明 |

1037| `exclude_dynamic_sections` | 否 | 将每个会话的上下文（如自动内存位置）从系统提示移到第一条用户消息。改进跨用户和机器的提示缓存重用。见 [修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1037| `exclude_dynamic_sections` | 否 | 将每个用户的上下文（如自动记忆位置）从系统提示词移到第一条用户消息。改进跨用户和机器的提示词缓存重用。见 [修改系统提示词](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1038| `snapshot` | 否 | 设置为 `False` 以在每个请求上重建系统提示，而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更高版本 |1038| `snapshot` | 否 | 设置为 `False` 以在每个请求上重建系统提示词，而不是[重用会话在其第一个请求上记录的提示词](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更高版本 |

1039 1039

1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">

1041 `SystemPromptCustom`1041 `SystemPromptCustom`

1042</h3>1042</h3>

1043 1043

1044对象形式的自定义系统提示，等同于将字符串作为 `system_prompt` 传递，也可以设置 `snapshot`。需要 `claude-agent-sdk` v0.2.153 或更高版本。1044对象形式的自定义系统提示词，等同于将字符串作为 `system_prompt` 传递，也可以设置 `snapshot`。需要 `claude-agent-sdk` v0.2.153 或更高版本。

1045 1045

1046```python theme={null}1046```python theme={null}

1047class SystemPromptCustom(TypedDict):1047class SystemPromptCustom(TypedDict):

1053| 字段 | 必需 | 描述 |1053| 字段 | 必需 | 描述 |

1054| :- | :- | :- |1054| :- | :- | :- |

1055| `type` | 是 | 必须是 `"custom"` |1055| `type` | 是 | 必须是 `"custom"` |

1056| `prompt` | 是 | 系统提示文本。作为命令行参数传递给 CLI，因此[命令行长度限制](#systempromptfile)适用 |1056| `prompt` | 是 | 系统提示词文本。作为命令行参数传递给 CLI，因此[命令行长度限制](#systempromptfile)适用 |

1057| `snapshot` | 否 | 与 [`SystemPromptPreset.snapshot`](#systempromptpreset) 相同，应用于 `prompt` |1057| `snapshot` | 否 | 与 [`SystemPromptPreset.snapshot`](#systempromptpreset) 相同，应用于 `prompt` |

1058 1058

1059<h3 id="systempromptfile">1059<h3 id="systempromptfile">

1060 `SystemPromptFile`1060 `SystemPromptFile`

1061</h3>1061</h3>

1062 1062

1063从文件加载自定义系统提示而不是作为字符串传递的配置。SDK 将其映射到 CLI [`--system-prompt-file`](/docs/zh-CN/cli-reference#system-prompt-flags) 标志。当提示很大时使用文件形式：SDK 在 CLI 子进程 argv 上传递字符串 `system_prompt`，这受到 OS 命令行长度限制的限制，然后 SDK 才能发送任何 API 请求。在 Linux 上，单个参数长于大约 128 KB 会在进程生成时失败，出现 `Argument list too long`。在 Windows 上，整个命令行被限制为大约 32 KB，因此字符串形式在更低的阈值处失败。1063从文件加载自定义系统提示词而不是作为字符串传递的配置。SDK 将其映射到 CLI [`--system-prompt-file`](/docs/zh-CN/cli-reference#system-prompt-flags) 标志。当提示词很大时使用文件形式：SDK 在 CLI 子进程 argv 上传递字符串 `system_prompt`，这在 SDK 发送任何 API 请求之前就受到 OS 命令行长度限制的约束。在 Linux 上，单个参数长于大约 128 KB 会在进程生成时失败，出现 `Argument list too long`。在 Windows 上，整个命令行被限制为大约 32 KB，因此字符串形式在更低的阈值处失败。

1064 1064

1065```python theme={null}1065```python theme={null}

1066class SystemPromptFile(TypedDict):1066class SystemPromptFile(TypedDict):

1070 1070

1071| 字段 | 必需 | 描述 |1071| 字段 | 必需 | 描述 |

1072| :- | :- | :- |1072| :- | :- | :- |

1073| `type` | 是 | 必须是 `"file"` 以从磁盘加载提示 |1073| `type` | 是 | 必须是 `"file"` 以从磁盘加载提示词 |

1074| `path` | 是 | 包含系统提示的文件的路径 |1074| `path` | 是 | 包含系统提示词的文件的路径 |

1075 1075

1076<h3 id="settingsource">1076<h3 id="settingsource">

1077 `SettingSource`1077 `SettingSource`

1087| :- | :- | :- |1087| :- | :- | :- |

1091 1091

1092<h4 id="default-behavior">1092<h4 id="default-behavior">

1093 默认行为1093 默认行为

1094</h4>1094</h4>

1095 1095

1096当 `setting_sources` 被省略或为 `None` 且 `skills` 未设置时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。使用 `skills` 设置时，[`setting_sources`](#claudeagentoptions) 行描述当前默认值。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。有关更多信息，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)。1096当 `setting_sources` 被省略或为 `None` 且 `skills` 未设置时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。设置了 `skills` 时，[`setting_sources`](#claudeagentoptions) 行描述当前默认值。端点托管策略在所有情况下都会加载；当会话使用组织凭据在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器托管设置。有关更多信息，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)。

1097 1097

1098<h4 id="why-use-setting_sources">1098<h4 id="why-use-setting_sources">

1099 为什么使用 setting\_sources1099 为什么使用 setting\_sources

1121```1121```

1122 1122

1123<Note>1123<Note>

1124 在 Python SDK 0.1.59 及更早版本中，空列表的处理方式与省略选项相同，因此 `setting_sources=[]` 不会禁用文件系统设置。如果你需要空列表生效，请升级到较新版本。TypeScript SDK 不受影响。1124 在 Python SDK 0.1.59 及更早版本中，空列表的处理方式与省略选项相同，因此 `setting_sources=[]` 不会禁用文件系统设置。如果您需要空列表生效，请升级到较新版本。TypeScript SDK 不受影响。

1125</Note>1125</Note>

1126 1126

1127**仅加载特定设置源：**1127**仅加载特定设置源：**

1174asyncio.run(main())1174asyncio.run(main())

1175```1175```

1176 1176

1177要加载 CLAUDE.md 项目说明，在 `setting_sources` 中包含 `"project"`。见 [修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) 了解 CLAUDE.md 加载如何与系统提示选项交互。1177要加载 CLAUDE.md 项目说明，请在 `setting_sources` 中包含 `"project"`。见 [修改系统提示词](/docs/zh-CN/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) 了解 CLAUDE.md 加载如何与系统提示词选项交互。

1178 1178

1179<h4 id="settings-precedence">1179<h4 id="settings-precedence">

1180 设置优先级1180 设置优先级

1214 1214

1215| 字段 | 必需 | 描述 |1215| 字段 | 必需 | 描述 |

1216| :- | :- | :- |1216| :- | :- | :- |

1217| `description` | 是 | 何时使用此代理的自然语言描述 |1217| `description` | 是 | 何时使用此 Agent 的自然语言描述 |

1218| `prompt` | 是 | 代理的系统提示 |1218| `prompt` | 是 | Agent 的系统提示词 |

1219| `tools` | 否 | 允许的工具名称数组。如果省略，继承[子代理可用的每个工具](/docs/zh-CN/sub-agents#available-tools) |1219| `tools` | 否 | 允许的工具名称数组。如果省略，继承[子代理可用的每个工具](/docs/zh-CN/sub-agents#available-tools) |

1220| `disallowedTools` | 否 | 要从代理的工具集中移除的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |1220| `disallowedTools` | 否 | 要从 Agent 的工具集中移除的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |

1221| `model` | 否 | 此代理的模型覆盖。接受别名如 `"sonnet"`、`"opus"`、`"haiku"` 或 `"inherit"`，或完整模型 ID。当你省略它时，Claude Code 按[子代理模型顺序](/docs/zh-CN/sub-agents#choose-a-model)选择模型 |1221| `model` | 否 | 此 Agent 的模型覆盖。接受别名如 `"sonnet"`、`"opus"`、`"haiku"` 或 `"inherit"`，或完整模型 ID。当您省略它时，Claude Code 按[子代理模型顺序](/docs/zh-CN/sub-agents#choose-a-model)选择模型 |

1222| `skills` | 否 | 此代理可用的技能名称列表 |1222| `skills` | 否 | 启动时预加载到 Agent 上下文中的 skill 名称列表。未列出的 skill 仍可通过 Skill 工具调用 |

1223| `memory` | 否 | 此代理的内存源：`"user"`、`"project"` 或 `"local"` |1223| `memory` | 否 | 此 Agent 的记忆源：`"user"`、`"project"` 或 `"local"` |

1224| `mcpServers` | 否 | 此代理可用的 MCP 服务器。每个条目是服务器名称或内联 `{name: config}` 字典 |1224| `mcpServers` | 否 | 此 Agent 可用的 MCP 服务器。每个条目是服务器名称或内联 `{name: config}` 字典 |

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

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

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

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

1229| `permissionMode` | 否 | 此代理内工具执行的权限模式。[子代理继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定何时应用。见 [`PermissionMode`](#permissionmode) |1229| `permissionMode` | 否 | 此 Agent 内工具执行的权限模式。[子代理继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定何时应用。见 [`PermissionMode`](#permissionmode) |

1230 1230

1231<Note>1231<Note>

1232 `AgentDefinition` 字段名称使用 camelCase，如 `disallowedTools`、`permissionMode` 和 `maxTurns`。这些名称直接映射到与 TypeScript SDK 共享的线路格式。这与 `ClaudeAgentOptions` 不同，后者对等效的顶级字段（如 `disallowed_tools` 和 `permission_mode`）使用 Python snake\_case。因为 `AgentDefinition` 是数据类，传递 snake\_case 关键字在构造时会引发 `TypeError`。1232 `AgentDefinition` 字段名称使用 camelCase，如 `disallowedTools`、`permissionMode` 和 `maxTurns`。这些名称直接映射到与 TypeScript SDK 共享的线路格式。这与 `ClaudeAgentOptions` 不同，后者对等效的顶级字段（如 `disallowed_tools` 和 `permission_mode`）使用 Python snake\_case。因为 `AgentDefinition` 是数据类，传递 snake\_case 关键字在构造时会引发 `TypeError`。

1253 `EffortLevel`1253 `EffortLevel`

1254</h3>1254</h3>

1255 1255

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

1257 1257

1258```python theme={null}1258```python theme={null}

1259EffortLevel = Literal[1259EffortLevel = Literal[

1285 1285

1286返回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。1286返回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。

1287 1287

1288回调是 SDK 对交互式权限提示的替代：它仅在[权限评估流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解析为提示时调用。已由 `allowed_tools` 条目、设置允许规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要限制每个工具调用，改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。1288回调是 SDK 对交互式权限提示的替代：它仅在[权限评估流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解析为提示时调用。已由 `allowed_tools` 条目、设置中的允许规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要把关每个工具调用，请改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。

1289 1289

1290允许规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；见 [权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated) 了解其中哪些到达回调以及在 `dontAsk` 和 `auto` 模式下发生什么。1290允许规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；见 [权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated) 了解其中哪些会到达回调，以及在 `dontAsk` 和 `auto` 模式下会发生什么。

1291 1291

1292<h3 id="toolpermissioncontext">1292<h3 id="toolpermissioncontext">

1293 `ToolPermissionContext`1293 `ToolPermissionContext`

1315| `suggestions` | `list[PermissionUpdate]` | 来自 CLI 的权限更新建议。Bash 提示包括带有 `localSettings` 目标的建议，因此在 `updated_permissions` 中返回它会将规则写入 `.claude/settings.local.json` 并在会话间持久化。 |1315| `suggestions` | `list[PermissionUpdate]` | 来自 CLI 的权限更新建议。Bash 提示包括带有 `localSettings` 目标的建议，因此在 `updated_permissions` 中返回它会将规则写入 `.claude/settings.local.json` 并在会话间持久化。 |

1462| 变体 | 字段 | 描述 |1462| 变体 | 字段 | 描述 |

1463| :- | :- | :- |1463| :- | :- | :- |

1467 1467

1468可选的 `display` 字段控制思考文本是否返回为 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 输出中接收思考内容。Claude Code 不会向 Amazon Bedrock 或 Google Cloud 的 Agent Platform 发送 `display`，因此在这些提供商上，Opus 4.7 及更高版本即使你将 `display` 设置为 `"summarized"` 也会返回空 `ThinkingBlock` 输出。1468可选的 `display` 字段控制思考文本以 `"summarized"` 还是 `"omitted"` 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此请设置 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 输出中接收思考内容。Claude Code 在发往某些提供商（如 Amazon Bedrock 和 Google Cloud 的 Agent Platform）的请求中不包含 `display`。在这些提供商上，即使您将 `display` 设置为 `"summarized"`，Opus 4.7 及更高版本也会返回空的 `ThinkingBlock` 输出。

1469 1469

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

1471 1471

1472```python theme={null}1472```python theme={null}

1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

1485 `TaskBudget`1485 `TaskBudget`

1486</h3>1486</h3>

1487 1487

1488API 端任务预算（以令牌为单位），与 `ClaudeAgentOptions` 中的 `task_budget` 字段一起使用。1488API 端任务预算（以 token 为单位），与 `ClaudeAgentOptions` 中的 `task_budget` 字段一起使用。

1489 1489

1490```python theme={null}1490```python theme={null}

1491class TaskBudget(TypedDict):1491class TaskBudget(TypedDict):

1494 1494

1495| 字段 | 类型 | 描述 |1495| 字段 | 类型 | 描述 |

1496| :- | :- | :- |1496| :- | :- | :- |

1497| `total` | `int` | 任务的总令牌预算 |1497| `total` | `int` | 任务的总 token 预算 |

1498 1498

1499因为这是 `TypedDict`，将其作为普通字典传递，如 `ClaudeAgentOptions(task_budget={"total": 50000})`。1499因为这是 `TypedDict`，请将其作为普通字典传递，如 `ClaudeAgentOptions(task_budget={"total": 50000})`。

1500 1500

1501<h3 id="sdkbeta">1501<h3 id="sdkbeta">

1502 `SdkBeta`1502 `SdkBeta`

1577 `McpServerStatusConfig`1577 `McpServerStatusConfig`

1578</h3>1578</h3>

1579 1579

1580由 [`get_mcp_status()`](#methods) 报告的 MCP 服务器的配置。这是所有 [`McpServerConfig`](#mcpserverconfig) 传输变体加上用于通过 claude.ai 代理的服务器的仅输出 `claudeai-proxy` 变体的联合。1580由 [`get_mcp_status()`](#methods) 报告的 MCP 服务器的配置。这是所有 [`McpServerConfig`](#mcpserverconfig) 传输变体，加上用于通过 claude.ai 代理的服务器的仅输出 `claudeai-proxy` 变体的联合。

1581 1581

1582```python theme={null}1582```python theme={null}

1583McpServerStatusConfig = (1583McpServerStatusConfig = (

1606 `McpServerStatus`1606 `McpServerStatus`

1607</h3>1607</h3>

1608 1608

1609连接的 MCP 服务器的状态，包含在 [`McpStatusResponse`](#mcpstatusresponse) 中。1609已连接的 MCP 服务器的状态，包含在 [`McpStatusResponse`](#mcpstatusresponse) 中。

1610 1610

1611```python theme={null}1611```python theme={null}

1612class McpServerStatus(TypedDict):1612class McpServerStatus(TypedDict):

1626| `serverInfo` | `dict`（可选） | 服务器名称和版本（`{"name": str, "version": str}`） |1626| `serverInfo` | `dict`（可选） | 服务器名称和版本（`{"name": str, "version": str}`） |

1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig)（可选） | 服务器配置。与 [`McpServerConfig`](#mcpserverconfig) 形状相同（stdio、SSE、HTTP 或 SDK），加上通过 claude.ai 连接的服务器的 `claudeai-proxy` 变体 |1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig)（可选） | 服务器配置。与 [`McpServerConfig`](#mcpserverconfig) 形状相同（stdio、SSE、HTTP 或 SDK），加上通过 claude.ai 连接的服务器的 `claudeai-proxy` 变体 |

1631 1631

1632<h3 id="contextusageresponse">1632<h3 id="contextusageresponse">

1633 `ContextUsageResponse`1633 `ContextUsageResponse`

1634</h3>1634</h3>

1635 1635

1636来自 [`ClaudeSDKClient.get_context_usage()`](#methods) 的响应。这是 Claude Code 为交互式会话中的 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段，如 `color` 和 `gridRows`，Claude Code 使用这些字段来绘制 `/context` 使用网格。1636来自 [`ClaudeSDKClient.get_context_usage()`](#methods) 的响应。这是 Claude Code 在交互式会话中为 `/context` 命令呈现的相同负载，因此除了 token 计数外，它还携带显示字段，如 `color` 和 `gridRows`，Claude Code 使用这些字段来绘制 `/context` 使用网格。

1637 1637

1638Claude Code 通过向[令牌计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 发送多个请求来构建此有效负载。这些请求不会出现在消息流中，因此读取流的成本跟踪不会看到它们。在 Anthropic API 上，令牌计数不计费。1638Claude Code 通过向 [token 计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 发送多个请求来构建此负载。这些请求不会出现在消息流中，因此读取流的成本跟踪不会看到它们。在 Anthropic API 上，token 计数不计费。

1639 1639

1640```python theme={null}1640```python theme={null}

1641class ContextUsageResponse(TypedDict):1641class ContextUsageResponse(TypedDict):

1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]

1661```1661```

1662 1662

1663每个 `ContextUsageCategory` 条目携带 `name`、`tokens`、`color` 和可选的 `isDeferred` 标志。`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是测量使用情况的窗口。该窗口是模型的上下文窗口，或当应用一个时的较低自动压缩窗口，`rawMaxTokens` 携带与 `maxTokens` 相同的值。`apiUsage` 保存最新 API 响应的使用情况，而不是会话的运行总计。Claude Code 保持可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 键未设置，因此即使类型声明它们，也应该期望它们不存在。1663每个 `ContextUsageCategory` 条目携带 `name`、`tokens`、`color` 和可选的 `isDeferred` 标志。`totalTokens` 是会话当前的上下文使用量，`maxTokens` 是衡量该使用量所依据的窗口。该窗口是模型的上下文窗口，或在适用时较低的自动压缩窗口，`rawMaxTokens` 携带与 `maxTokens` 相同的值。`apiUsage` 保存最新 API 响应的使用情况，而不是会话的累计总数。Claude Code 不会设置可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 键，因此即使类型声明了它们，也应预期它们不存在。

1664 1664

1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">

1666 `SdkPluginConfig`1666 `SdkPluginConfig`

1688]1688]

1689```1689```

1690 1690

1691有关创建和使用插件的完整信息，见 [Plugins](/docs/zh-CN/agent-sdk/plugins)。1691有关创建和使用插件的完整信息，见 [插件](/docs/zh-CN/agent-sdk/plugins)。

1692 1692

1693<h2 id="message-types">1693<h2 id="message-types">

1694 消息类型1694 消息类型

1766| `model` | `str` | 生成响应的模型 |1766| `model` | `str` | 生成响应的模型 |

1840 1840

1841多个字段携带有关对话如何结束的诊断详情：1841多个字段携带有关对话如何结束的诊断详情：

1842 1842

1843* `is_error`：当对话以错误状态结束时为 `True`。在 `error_*` 子类型上始终为 `True`。在 `subtype="success"` 上，当最终模型请求失败时为 `True`，这意味着代理循环完成但最后一个 API 调用返回了错误。1843* `is_error`：当对话以错误状态结束时为 `True`。在 `error_*` 子类型上始终为 `True`。在 `subtype="success"` 上，当最终模型请求失败时为 `True`，这意味着 Agent 循环完成但最后一个 API 调用返回了错误。

1844* `api_error_status`：终止 API 错误的 HTTP 状态代码。当轮次结束时没有错误时为 `None`。仅在 `subtype="success"` 上填充。1844* `api_error_status`：终止 API 错误的 HTTP 状态代码。当轮次结束时没有错误时为 `None`。仅在 `subtype="success"` 上填充。

1845* `result`：在 `subtype="success"` 上为最终助手消息的文本，或在 `error_*` 子类型上为 `None`。当 `subtype="success"` 且 `is_error=True` 时，如果可用，此字段保存 API 错误字符串，但可能为空，因此请检查 `api_error_status` 和前面的 `AssistantMessage` 内容以获取详情。1845* `result`：在 `subtype="success"` 上为最终助手消息的文本，或在 `error_*` 子类型上为 `None`。当 `subtype="success"` 且 `is_error=True` 时，如果可用，此字段保存 API 错误字符串，但可能为空，因此请检查 `api_error_status` 和前面的 `AssistantMessage` 内容以获取详情。

1846* `errors`：循环级别的错误字符串，例如最大轮次消息。仅在 `error_*` 子类型上填充。1846* `errors`：循环级别的错误字符串，例如最大轮次消息。仅在 `error_*` 子类型上填充。

1847* `terminal_reason`：查询循环结束的原因，例如 `"completed"`、`"max_turns"`、`"api_error"`、`"aborted_streaming"` 或 `"aborted_tools"`。值为 `"aborted_streaming"` 或 `"aborted_tools"` 意味着轮次在完成前被中止。常见原因是 [`interrupt()`](#claudesdkclient) 和权限回调返回 [`PermissionResultDeny`](#permissionresultdeny) 且 `interrupt=True`。在早于该字段的 CLI 版本上为 `None`，在本地命令（如 `/voice` 或 `/usage`）的结果上为 `None`，这些命令绕过查询循环，或在会话严重失败时发出的合成错误结果上为 `None`。镜像 TypeScript SDK 的 [`SDKResultMessage.terminal_reason`](/docs/zh-CN/agent-sdk/typescript#sdkresultmessage)，其列出了完整的值集。1847* `terminal_reason`：查询循环结束的原因，例如 `"completed"`、`"max_turns"`、`"api_error"`、`"aborted_streaming"` 或 `"aborted_tools"`。值为 `"aborted_streaming"` 或 `"aborted_tools"` 意味着轮次在完成前被中止。常见原因是 [`interrupt()`](#claudesdkclient) 和权限回调返回 [`PermissionResultDeny`](#permissionresultdeny) 且 `interrupt=True`。在早于该字段的 CLI 版本上为 `None`，在本地命令（如 `/voice` 或 `/usage`）的结果上为 `None`，这些命令绕过查询循环，或在会话严重失败时发出的合成错误结果上为 `None`。镜像 TypeScript SDK 的 [`SDKResultMessage.terminal_reason`](/docs/zh-CN/agent-sdk/typescript#sdkresultmessage)，其列出了完整的值集。

1848* `origin`：触发此轮次的用户消息的来源。在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，检查此项以区分你自己的提示结果（其中 `origin` 为 `None` 或 `{"kind": "human"}`）与注入的轮次（如后台任务通知）的结果。需要 Python Agent SDK 0.2.137 或更高版本。1848* `origin`：触发此轮次的用户消息的来源。在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，检查此项以区分您自己的提示词结果（其中 `origin` 为 `None` 或 `{"kind": "human"}`）与注入的轮次（如后台任务通知）的结果。需要 Python Agent SDK 0.2.137 或更高版本。

1849 1849

1850`usage` 字典仅涵盖主代理循环，不包括子代理和其他嵌套或辅助模型调用。在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，值是按轮次的。优先使用 `model_usage` 进行令牌和成本计费。`usage` 字典在存在时包含以下键：1850`usage` 字典仅涵盖主 Agent 循环，不包括子代理和其他嵌套或辅助模型调用。在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，值是按轮次的。优先使用 `model_usage` 进行 token 和成本核算。`usage` 字典在存在时包含以下键：

1851 1851

1852| 键 | 类型 | 描述 |1852| 键 | 类型 | 描述 |

1853| - | - | - |1853| - | - | - |

1854| `input_tokens` | `int` | 顶级代理循环消耗的输入令牌。[子代理令牌不包括在内](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 `model_usage` 进行整树计费。 |1854| `input_tokens` | `int` | 顶级 Agent 循环消耗的输入 token。[子代理 token 不包括在内](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 `model_usage` 进行整树核算。 |

1855| `output_tokens` | `int` | 顶级代理循环生成的输出令牌。子代理令牌不包括在内。 |1855| `output_tokens` | `int` | 顶级 Agent 循环生成的输出 token。子代理 token 不包括在内。 |

1856| `cache_creation_input_tokens` | `int` | 用于创建新缓存条目的令牌。 |1856| `cache_creation_input_tokens` | `int` | 用于创建新缓存条目的 token。 |

1857| `cache_read_input_tokens` | `int` | 从现有缓存条目读取的令牌。 |1857| `cache_read_input_tokens` | `int` | 从现有缓存条目读取的 token。 |

1858 1858

1859`model_usage` 字典将模型名称映射到每个模型的使用情况。它涵盖通过查询管道进行的每个模型调用：主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）从 `model_usage` 中排除。将 `model_usage` 视为估计值，而不是计费声明。1859`model_usage` 字典将模型名称映射到每个模型的使用情况。它涵盖通过查询管道进行的每个模型调用：主循环、子代理和内部调用（如压缩和 Workflow Agent）。该管道外的辅助调用（如权限分类器和 token 计数请求）从 `model_usage` 中排除。将 `model_usage` 视为估计值，而不是计费声明。

1860 1860

1861在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，`model_usage` 和 `total_cost_usd` 在轮次间是累积的，因此读取最新结果而不是跨结果求和。调用恢复会话时，也会计算[从会话早期调用恢复的总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。有关重置，请参阅[在流式输入模式中跟踪成本](/docs/zh-CN/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)，有关清零结果，请参阅[在会话崩溃后恢复总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。1861在[流式输入模式](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)中，`model_usage` 和 `total_cost_usd` 在轮次间是累积的，因此读取最新结果而不是跨结果求和。调用恢复会话时，也会计算[从会话早期调用恢复的总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。有关重置，请参阅[在流式输入模式中跟踪成本](/docs/zh-CN/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)，有关清零结果，请参阅[在会话崩溃后恢复总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。

1862 1862

1864 1864

1865| 键 | 类型 | 描述 |1865| 键 | 类型 | 描述 |

1866| - | - | - |1866| - | - | - |

1867| `inputTokens` | `int` | 此模型的输入令牌。 |1867| `inputTokens` | `int` | 此模型的输入 token。 |

1868| `outputTokens` | `int` | 此模型的输出令牌。 |1868| `outputTokens` | `int` | 此模型的输出 token。 |

1869| `cacheReadInputTokens` | `int` | 此模型的缓存读取令牌。 |1869| `cacheReadInputTokens` | `int` | 此模型的缓存读取 token。 |

1870| `cacheCreationInputTokens` | `int` | 此模型的缓存创建令牌。 |1870| `cacheCreationInputTokens` | `int` | 此模型的缓存创建 token。 |

1871| `webSearchRequests` | `int` | 此模型进行的网络搜索请求。 |1871| `webSearchRequests` | `int` | 此模型进行的网络搜索请求。 |

1872| `thinkingTokens` | `int` | 此模型生成的思考令牌，已计入 `outputTokens`。在轮次在记录它的 Claude Code 版本上运行之前不存在，并且未在 TypedDict 上声明，因此使用 `.get()` 读取它。需要 Python Agent SDK 0.2.150 或更高版本，其附带的 CLI 记录它。 |1872| `thinkingTokens` | `int` | 此模型生成的思考 token，已计入 `outputTokens`。在轮次在记录它的 Claude Code 版本上运行之前不存在，并且未在 TypedDict 上声明，因此使用 `.get()` 读取它。需要 Python Agent SDK 0.2.150 或更高版本，其附带的 CLI 记录它。 |

1874| `contextWindow` | `int` | 此模型的上下文窗口大小。 |1874| `contextWindow` | `int` | 此模型的上下文窗口大小。 |

1875| `maxOutputTokens` | `int` | 此模型的最大输出令牌限制。 |1875| `maxOutputTokens` | `int` | 此模型的最大输出 token 限制。 |

1876| `canonicalModel` | `str` | 用于定价查询的规范模型 ID。可能与条目键入的原始模型字符串不同，例如特定于提供商的 ID 或别名。并非总是存在。 |1876| `canonicalModel` | `str` | 用于定价查询的规范模型 ID。可能与条目键入的原始模型字符串不同，例如特定于提供商的 ID 或别名。并非总是存在。 |

1877| `provider` | `str` | 提供此模型的 API 提供商，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。并非总是存在。 |1877| `provider` | `str` | 提供此模型的 API 提供商，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。并非总是存在。 |

1878| `costBasis` | `str` | 为此模型最新请求定价的价格表：`list` 表示标价，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，`unknown` 表示两者都与模型 ID 不匹配。并非总是存在，并且未在 TypedDict 上声明，因此使用 `.get()` 读取它。需要 Claude Code v2.1.246 或更高版本。 |

1878 1879

1879<h3 id="streamevent">1880<h3 id="streamevent">

1880 `StreamEvent`1881 `StreamEvent`

1978 `TaskStartedMessage`1979 `TaskStartedMessage`

1979</h3>1980</h3>

1980 1981

1981当后台任务启动时发出。后台任务是在主轮次之外跟踪的任何内容：后台 Bash 命令、[Monitor](#monitor) 监视、通过 Agent 工具生成的子代理或远程代理。`task_type` 字段告诉你是哪一个。此命名与 `Task` 到 `Agent` 工具重命名无关。1982当后台任务启动时发出。后台任务是在主轮次之外跟踪的任何内容：后台 Bash 命令、[Monitor](#monitor) 监视、通过 Agent 工具生成的子代理或远程 Agent。`task_type` 字段告诉您是哪一个。此命名与 `Task` 到 `Agent` 工具重命名无关。

1982 1983

1983```python theme={null}1984```python theme={null}

1984@dataclass1985@dataclass

2004 `TaskUsage`2005 `TaskUsage`

2005</h3>2006</h3>

2006 2007

2007后台任务的令牌和计时数据。2008后台任务的 token 和计时数据。

2008 2009

2009```python theme={null}2010```python theme={null}

2010class TaskUsage(TypedDict):2011class TaskUsage(TypedDict):

2035| :- | :- | :- |2036| :- | :- | :- |

2036| `task_id` | `str` | 任务的唯一标识符 |2037| `task_id` | `str` | 任务的唯一标识符 |

2037| `description` | `str` | 当前状态描述 |2038| `description` | `str` | 当前状态描述 |

2039| `uuid` | `str` | 唯一消息标识符 |2040| `uuid` | `str` | 唯一消息标识符 |

2040| `session_id` | `str` | 会话标识符 |2041| `session_id` | `str` | 会话标识符 |

2069| `uuid` | `str` | 唯一消息标识符 |2070| `uuid` | `str` | 唯一消息标识符 |

2070| `session_id` | `str` | 会话标识符 |2071| `session_id` | `str` | 会话标识符 |

2073 2074

2074当 CLI [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)时，该调用的工具结果仅保存占位符，该调用的真实结果在此消息中到达。在此类调用的 `"completed"` 通知上，CLI 添加 `resource_links` 键，列出工具通过引用返回的文件，具有与 [`UserMessage.tool_use_result`](#usermessage) 上的 `resourceLinks` 键相同的条目和限制。`resource_links` 键需要 Python Agent SDK 0.2.150 或更高版本和 Claude Code v2.1.257 或更高版本；该 SDK 版本附带的 CLI 满足 Claude Code 要求。2075当 CLI [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)时，该调用的工具结果仅保存占位符，该调用的真实结果在此消息中到达。在此类调用的 `"completed"` 通知上，CLI 添加 `resource_links` 键，列出工具通过引用返回的文件，具有与 [`UserMessage.tool_use_result`](#usermessage) 上的 `resourceLinks` 键相同的条目和限制。`resource_links` 键需要 Python Agent SDK 0.2.150 或更高版本和 Claude Code v2.1.257 或更高版本；该 SDK 版本附带的 CLI 满足 Claude Code 要求。

2075 2076

2153 错误类型2154 错误类型

2154</h2>2155</h2>

2155 2156

2156下面的类型定义了你的代码可以捕获的内容。对于与这些类型引发的错误消息相关的条目，包括每个错误的原因和修复方法，请参阅[故障排除](/docs/zh-CN/agent-sdk/troubleshooting)。2157下面的类型定义了您的代码可以捕获的内容。对于与这些类型引发的错误消息相关的条目，包括每个错误的原因和修复方法，请参阅[故障排除](/docs/zh-CN/agent-sdk/troubleshooting)。

2157 2158

2158<h3 id="claudesdkerror">2159<h3 id="claudesdkerror">

2159 `ClaudeSDKError`2160 `ClaudeSDKError`

2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""

2167```2168```

2168 2169

2169当单次 `query()` 以错误结果结束时，例如达到轮次限制错误，SDK 会在生成最终结果消息后引发 [`ResultError`](#resulterror)。Python Agent SDK 0.2.140 之前的版本引发的是不属于 `ClaudeSDKError` 子类的普通 `Exception`。2170当单次 `query()` 以错误结果结束时，例如达到轮次限制错误，SDK 会引发 [`ResultError`](#resulterror)。

2170 2171

2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219

2219当 Claude Code 进程因运行以错误结果结束而退出时引发，例如达到轮次限制错误或 API 错误。在最终 [`ResultMessage`](#resultmessage) 之后引发。`ResultError` 是 `ProcessError` 的子类，因此现有的 `except ProcessError` 处理程序也会捕获它。其属性包含该结果消息的字段，因此你可以根据运行失败的原因进行分支，而无需解析消息文本。需要 Python Agent SDK 0.2.140 或更高版本。2220当 Claude Code 进程因运行以错误[结果消息](#resultmessage)结束而退出时引发，例如达到轮次限制错误或 API 错误。`ResultError` 是 `ProcessError` 的子类，因此现有的 `except ProcessError` 处理程序也会捕获它。其属性包含该结果消息的字段，因此您可以根据运行失败的原因进行分支，而无需解析消息文本。需要 Python Agent SDK 0.2.140 或更高版本。

2220 2221

2221```python theme={null}2222```python theme={null}

2222class ResultError(ProcessError):2223class ResultError(ProcessError):

2229 data: dict[str, Any] # the raw result message payload2230 data: dict[str, Any] # the raw result message payload

2230```2231```

2231 2232

2232要区分失败，请在检查 `subtype` 之前先检查 `terminal_reason`。当最终请求失败时，例如 API 错误，Claude Code 会报告 `subtype` 为 `"success"`，原因在 `terminal_reason` 中，例如 `"api_error"`；当你设置的限制结束运行时，例如 `max_turns` 或 `max_budget_usd`，它会报告 `error_*` 子类型。2233要区分失败，请在检查 `subtype` 之前先检查 `terminal_reason`。当最终请求失败时，例如 API 错误，Claude Code 会报告 `subtype` 为 `"success"`，原因在 `terminal_reason` 中，例如 `"api_error"`；当您设置的限制结束运行时，例如 `max_turns` 或 `max_budget_usd`，它会报告 `error_*` 子类型。

2233 2234

2234<h3 id="clijsondecodeerror">2235<h3 id="clijsondecodeerror">

2235 `CLIJSONDecodeError`2236 `CLIJSONDecodeError`

2253 Hook 类型2254 Hook 类型

2254</h2>2255</h2>

2255 2256

2256有关使用 hooks 的综合指南，包括示例和常见模式，见 [Hooks 指南](/docs/zh-CN/agent-sdk/hooks)。2257有关使用 hook 的综合指南，包括示例和常见模式，见 [Hooks 指南](/docs/zh-CN/agent-sdk/hooks)。

2257 2258

2258<h3 id="hookevent">2259<h3 id="hookevent">

2259 `HookEvent`2260 `HookEvent`

2293参数：2294参数：

2294 2295

2295* `input`：强类型 hook 输入，具有基于 `hook_event_name` 的判别联合（见 [`HookInput`](#hookinput)）2296* `input`：强类型 hook 输入，具有基于 `hook_event_name` 的判别联合（见 [`HookInput`](#hookinput)）

2296* `tool_use_id`：可选工具使用标识符（用于工具相关的 hooks）2297* `tool_use_id`：可选工具使用标识符（用于工具相关的 hook）

2297* `context`：带有附加信息的 hook 上下文2298* `context`：带有附加信息的 hook 上下文

2298 2299

2299返回 [`HookJSONOutput`](#hookjsonoutput)。2300返回 [`HookJSONOutput`](#hookjsonoutput)。

2313 `HookMatcher`2314 `HookMatcher`

2314</h3>2315</h3>

2315 2316

2316用于将 hooks 匹配到特定事件或工具的配置。2317用于将 hook 匹配到特定事件或工具的配置。

2317 2318

2318```python theme={null}2319```python theme={null}

2319@dataclass2320@dataclass

2509| `agent_id` | `str` | 子代理的唯一标识符 |2510| `agent_id` | `str` | 子代理的唯一标识符 |

2510| `agent_transcript_path` | `str` | 子代理的记录文件路径 |2511| `agent_transcript_path` | `str` | 子代理的会话记录文件路径 |

2511| `agent_type` | `str` | 子代理的类型 |2512| `agent_type` | `str` | 子代理的类型 |

2512 2513

2513<h3 id="precompacthookinput">2514<h3 id="precompacthookinput">

2573 `PermissionRequestHookInput`2574 `PermissionRequestHookInput`

2574</h3>2575</h3>

2575 2576

2576`PermissionRequest` hook 事件的输入数据。允许 hooks 以编程方式处理权限决策。2577`PermissionRequest` hook 事件的输入数据。允许 hook 以编程方式处理权限决策。

2577 2578

2578```python theme={null}2579```python theme={null}

2579class PermissionRequestHookInput(BaseHookInput):2580class PermissionRequestHookInput(BaseHookInput):

2634 `HookSpecificOutput`2635 `HookSpecificOutput`

2635</h4>2636</h4>

2636 2637

2637事件特定输出类型的判别联合。`hookEventName` 字段确定哪些字段有效。有关每个 hook 事件的可用字段的完整详情，见 [使用 hooks 控制执行](/docs/zh-CN/agent-sdk/hooks#outputs)。2638事件特定的 `TypedDict` 输出类型的判别联合。`hookEventName` 字段确定哪些字段有效。有关每个 hook 事件的可用字段的完整详情，见 [使用 hook 控制执行](/docs/zh-CN/agent-sdk/hooks#outputs)。

2638 2639

2639```python theme={null}2640```python theme={null}

2640class PreToolUseHookSpecificOutput(TypedDict):2641class PreToolUseHookSpecificOutput(TypedDict):

2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]

2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]

2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]

2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

2653 2654

2654 2655

2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):

2708 Hook 使用示例2709 Hook 使用示例

2709</h3>2710</h3>

2710 2711

2711此示例注册两个 hooks：一个阻止危险的 bash 命令（如 `rm -rf /`），另一个记录所有工具使用以进行审计。安全 hook 仅在 Bash 命令上运行（通过 `matcher`），而日志 hook 在所有工具上运行。2712此示例注册两个 hook：一个阻止危险的 Bash 命令（如 `rm -rf /`），另一个记录所有工具使用以进行审计。安全 hook 仅在 Bash 命令上运行（通过 `matcher`），而日志 hook 在所有工具上运行。

2712 2713

2713```python theme={null}2714```python theme={null}

2714import asyncio2715import asyncio

2767 工具输入/输出类型2768 工具输入/输出类型

2768</h2>2769</h2>

2769 2770

2770所有内置 Claude Code 工具的输入/输出模式文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。2771内置 Claude Code 工具的输入/输出 schema 文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。

2771 2772

2772每个显示的输出是您从该工具的 [`UserMessage.tool_use_result`](#usermessage) 读取的值。关键名称完全按照 Claude Code 发出的方式出现。带有 `| None` 注释的关键字，以及带有"present when"或"optional"注释的关键字，在不适用时会被省略。2773每个显示的输出是您从该工具的 [`UserMessage.tool_use_result`](#usermessage) 读取的值。键名完全按照 Claude Code 发出的方式出现。标注了 `| None` 并带有"present when"或"optional"注释的键在不适用时会被省略。

2773 2774

2774<h3 id="agent">2775<h3 id="agent">

2775 Agent2776 Agent

2782```python theme={null}2783```python theme={null}

2783{2784{

2784 "description": str, # 任务的简短描述（3-5 个单词）2785 "description": str, # 任务的简短描述（3-5 个单词）

2785 "prompt": str, # 代理要执行的任务2786 "prompt": str, # Agent 要执行的任务

2786 "subagent_type": str | None, # 要使用的专门代理的类型2787 "subagent_type": str | None, # 要使用的专门 Agent 的类型

2788 "run_in_background": bool | None, # 代理默认在后台运行；设置为 False 以同步运行2789 "run_in_background": bool | None, # Agent 默认在后台运行；设置为 False 以同步运行

2789 "name": str | None, # 生成的代理的名称2790 "name": str | None, # 生成的 Agent 的名称

2790 "team_name": str | None, # 已弃用；被忽略2791 "team_name": str | None, # 已弃用；被忽略

2792 "isolation": "worktree" | "remote" | None, # 代理更改的隔离模式2793 "isolation": "worktree" | "remote" | None, # Agent 更改的隔离模式

2793}2794}

2794```2795```

2795 2796

2796启动一个新代理来自主处理复杂的多步骤任务。2797启动一个新 Agent 来自主处理复杂的多步骤任务。

2797 2798

2798**输出（状态：`"completed"`）：**2799**输出（状态：`"completed"`）：**

2799 2800

2850{2851{

2851 "status": "async_launched",2852 "status": "async_launched",

2852 "isAsync": bool | None, # 后台启动时为 True2853 "isAsync": bool | None, # 后台启动时为 True

2853 "agentId": str, # 启动的代理的 ID2854 "agentId": str, # 启动的 Agent 的 ID

2854 "description": str, # 任务描述2855 "description": str, # 任务描述

2855 "resolvedModel": str | None, # 后台转换时使用的模型2856 "resolvedModel": str | None, # 后台转换时使用的模型

2856 "modelsUsed": list[str] | None, # 后台转换前使用的模型，按顺序，连续重复被折叠2857 "modelsUsed": list[str] | None, # 后台转换前使用的模型，按顺序，连续重复被折叠

2857 "prompt": str, # 代理运行的提示2858 "prompt": str, # Agent 运行的提示词

2858 "outputFile": str, # 代理输出被写入的文件路径2859 "outputFile": str, # Agent 输出被写入的文件路径

2859 "canReadOutputFile": bool | None, # 输出文件是否可以直接读取2860 "canReadOutputFile": bool | None, # 输出文件是否可以直接读取

2860}2861}

2861```2862```

2866{2867{

2867 "status": "remote_launched",2868 "status": "remote_launched",

2868 "taskId": str, # 分派任务的 ID2869 "taskId": str, # 分派任务的 ID

2869 "sessionUrl": str, # 云会话的链接2870 "sessionUrl": str, # 云端会话的链接

2870 "description": str, # 任务描述2871 "description": str, # 任务描述

2871 "prompt": str, # 代理运行的提示2872 "prompt": str, # Agent 运行的提示词

2872 "outputFile": str, # 代理输出被写入的文件路径2873 "outputFile": str, # Agent 输出被写入的文件路径

2873}2874}

2874```2875```

2875 2876

2876返回来自子代理的结果。输出在 `status` 字段上进行区分：`"completed"` 用于完成的任务，`"async_launched"` 用于后台任务，`"remote_launched"` 用于 Claude Code 分派到云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 变体上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是当 Claude Code 使用 git 创建 worktree 时的分支。2877返回来自子代理的结果。输出在 `status` 字段上进行区分：`"completed"` 用于完成的任务，`"async_launched"` 用于后台任务，`"remote_launched"` 用于 Claude Code 分派到云端会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 变体上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是当 Claude Code 使用 git 创建 worktree 时的分支。

2877 2878

2878在 `completed` 变体上，`resolvedModel` 命名子代理启动时的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，它可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 变体上，`resolvedModel` 命名代理移到后台时使用的模型，因此在后台转换之前发生的交换会反映在那里。两个变体上的 `modelsUsed` 字段按顺序列出使用的模型，连续重复被折叠；仅当模型在运行中被交换时才设置。`modelsUsed` 和后台转换时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。2879在 `completed` 变体上，`resolvedModel` 命名子代理启动时的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，它可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 变体上，`resolvedModel` 命名 Agent 移到后台时使用的模型，因此在后台转换之前发生的交换会反映在那里。两个变体上的 `modelsUsed` 字段按顺序列出使用的模型，连续重复被折叠；仅当模型在运行中被交换时才设置。`modelsUsed` 和后台转换时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。

2879 2880

2880Claude Code 从子代理的最终 API 请求而不是整个运行中填充 `usage` 和 `totalTokens`。当存在时，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 是该请求的输出 token 中属于思考 token 的数量。`output_tokens_details` 键需要 Python SDK v0.2.136 或更高版本，它捆绑了 Claude Code v2.1.228。`fallback_credit` 键需要 Python SDK v0.2.162 或更高版本，它捆绑了 Claude Code v2.1.285。2881Claude Code 从子代理的最终 API 请求而不是整个运行中填充 `usage` 和 `totalTokens`。当存在时，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 是该请求的输出 token 中属于思考 token 的数量。`output_tokens_details` 键需要 Python SDK v0.2.136 或更高版本，它捆绑了 Claude Code v2.1.228。`fallback_credit` 键需要 Python SDK v0.2.162 或更高版本，它捆绑了 Claude Code v2.1.285。

2881 2882

2935 # 用户输入的自由形式回复而不是回答问题；当设置时，2936 # 用户输入的自由形式回复而不是回答问题；当设置时，

2936 # Claude 收到"用户回复：..."而不是答案列表2937 # Claude 收到"用户回复：..."而不是答案列表

2937 "annotations": dict[str, dict] | None, # 来自用户选择的每个问题"preview"和"notes"2938 "annotations": dict[str, dict] | None, # 来自用户选择的每个问题"preview"和"notes"

2938 "afkTimeoutMs": int | None, # 在用户不活动这么多毫秒后对话自动解决时设置；用户回答时不存在2939 "afkTimeoutMs": int | None, # 在用户不活动这么多毫秒后对话框自动解决时设置；用户回答时不存在

2939}2940}

2940```2941```

2941 2942

3078 "numLines": int, # 返回内容中的行数3079 "numLines": int, # 返回内容中的行数

3079 "startLine": int, # 内容开始的行号3080 "startLine": int, # 内容开始的行号

3080 "totalLines": int, # 文件中的总行数3081 "totalLines": int, # 文件中的总行数

3081 "truncatedByTokenCap": bool | None, # 当整个文件读取超过令牌上限且内容是第一页时出现且为 True3082 "truncatedByTokenCap": bool | None, # 当整个文件读取超过 token 上限且内容是第一页时出现且为 True

3082 },3083 },

3083}3084}

3084```3085```

3150 "file": {3151 "file": {

3151 "filePath": str,3152 "filePath": str,

3152 },3153 },

3153 "source": "seeded" | None, # 当较早的副本来自在启动时加载的 CLAUDE.md 或内存文件而不是 Read 调用时出现3154 "source": "seeded" | None, # 当较早的副本来自在启动时加载的 CLAUDE.md 或记忆文件而不是 Read 调用时出现

3154}3155}

3155```3156```

3156 3157

3324```python theme={null}3325```python theme={null}

3325{3326{

3326 "url": str, # 要从中获取内容的 URL3327 "url": str, # 要从中获取内容的 URL

3327 "prompt": str, # 在获取的内容上运行的提示3328 "prompt": str, # 在获取的内容上运行的提示词

3328}3329}

3329```3330```

3330 3331

3335 "bytes": int, # 获取的内容大小（字节）3336 "bytes": int, # 获取的内容大小（字节）

3336 "code": int, # HTTP 响应代码3337 "code": int, # HTTP 响应代码

3337 "codeText": str, # HTTP 响应代码文本3338 "codeText": str, # HTTP 响应代码文本

3338 "result": str, # 通过将提示应用于内容得到的处理结果3339 "result": str, # 通过将提示词应用于内容得到的处理结果

3339 "durationMs": int, # 获取和处理内容的时间（毫秒）3340 "durationMs": int, # 获取和处理内容的时间（毫秒）

3340 "url": str, # 被获取的 URL3341 "url": str, # 被获取的 URL

3341}3342}

3584 3585

3585```python theme={null}3586```python theme={null}

3586{3587{

3587 "plan": str # 用户要运行以获得批准的计划3588 "plan": str # 要提交给用户批准的计划

3588}3589}

3589```3590```

3590 3591

agent-sdk/structured-outputs.md +2 −2

Details

60 60

61要使用结构化输出，定义一个 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 来描述你想要的数据形状，然后通过 `outputFormat` 选项（TypeScript）或 `output_format` 选项（Python）将其传递给 `query()`。当代理完成时，结果消息包含一个 `structured_output` 字段，其中包含与你的 schema 匹配的验证数据。61要使用结构化输出，定义一个 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 来描述你想要的数据形状，然后通过 `outputFormat` 选项（TypeScript）或 `output_format` 选项（Python）将其传递给 `query()`。当代理完成时，结果消息包含一个 `structured_output` 字段，其中包含与你的 schema 匹配的验证数据。

62 62

~~63下面的示例要求代理研究 Anthropic 并返回公司名称、成立年份和总部作为结构化输出。~~63在运行本页上的示例之前，请按照[快速入门](/docs/zh-CN/agent-sdk/quickstart#setup)安装 Claude Agent SDK。下面的示例要求 Agent 研究 Anthropic 并返回公司名称、成立年份和总部作为结构化输出。

64 64

65<CodeGroup>65<CodeGroup>

66 ```typescript TypeScript theme={null}66 ```typescript TypeScript theme={null}

390 错误处理390 错误处理

391</h2>391</h2>

392 392

393结构化输出生成可能会失败，当代理无法生成与你的 schema 匹配的有效 JSON 时。这通常发生在 schema 对于任务来说太复杂、任务本身不明确或代理在尝试修复验证错误时达到重试限制时。它也可能在没有任何验证失败的情况下发生：[模型回退](/docs/zh-CN/model-config#automatic-model-fallback)可以在流中途收回已完成的输出，如果没有重试替换它，运行将以相同的错误结束。在调试你的 schema 之前，检查结果消息上的 `errors` 列表以区分这两个原因。393结构化输出生成可能会失败，当 Agent 无法生成与您的 schema 匹配的有效 JSON 时。这通常发生在 schema 对于任务来说太复杂、任务本身不明确或 Agent 在尝试修复验证错误时达到重试限制时。它也可能在没有任何验证失败的情况下发生：[模型回退](/docs/zh-CN/model-config#automatic-model-fallback)可以在流中途收回已完成的输出，如果没有重试替换它，运行将以相同的错误结束。在调试您的 schema 之前，检查错误结果消息上的 `errors` 列表以区分这两个原因。

394 394

395发生错误时，结果消息有一个 `subtype` 指示出了什么问题：395发生错误时，结果消息有一个 `subtype` 指示出了什么问题：

396 396

agent-sdk/typescript.md +4 −4

Details

718| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件中的条目如 `.mcp.json` 或 `~/.claude.json`，Claude Code 重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |718| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件中的条目如 `.mcp.json` 或 `~/.claude.json`，Claude Code 重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |

719| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，名称解析方式与 `reconnectMcpServer()` 相同。禁用服务器会断开其连接并移除其工具。有关每种服务器所需的 Claude Code 版本，请参阅 [`toggleMcpServer()`](#togglemcpserver) |719| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，名称解析方式与 `reconnectMcpServer()` 相同。禁用服务器会断开其连接并移除其工具。有关每种服务器所需的 Claude Code 版本，请参阅 [`toggleMcpServer()`](#togglemcpserver) |

720| `setMcpServers(servers)` | 动态替换此会话的 MCP 服务器集。使用 [`McpSetServersResult`](#mcpsetserversresult) 解决，命名添加和移除的服务器以及任何错误 |720| `setMcpServers(servers)` | 替换此方法所管理的 MCP 服务器：通过它添加的服务器以及[进程内 SDK 服务器](#createsdkmcpserver)。解析为一个 [`McpSetServersResult`](#mcpsetserversresult)，指明添加和移除了哪些服务器以及任何错误；该部分说明了哪些其他服务器会保持连接 |

721| `readMcpResource(serverName, uri)` | *Alpha.* 从连接的 MCP 服务器读取一个 MCP Apps `ui://` 资源，以便您的应用可以呈现工具的小部件。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 解决。需要 TypeScript Agent SDK v0.3.280 或更高版本 |721| `readMcpResource(serverName, uri)` | *Alpha.* 从连接的 MCP 服务器读取一个 MCP Apps `ui://` 资源，以便您的应用可以呈现工具的小部件。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 解决。需要 TypeScript Agent SDK v0.3.280 或更高版本 |

1337| `mcpServer` | `{ name: string; source: string }` | 对于 `mcp__*` 工具，提供它的 MCP 服务器及其服务器定义来自何处，具有 [`McpServerProvenance`](#mcpserverprovenance) 的字段。对于其他工具不存在。需要 Agent SDK v0.3.274 或更高版本 |1337| `mcpServer` | `{ name: string; source: string }` | 对于 `mcp__*` 工具，提供它的 MCP 服务器及其服务器定义来自何处，具有 [`McpServerProvenance`](#mcpserverprovenance) 的字段。对于其他工具不存在。需要 Agent SDK v0.3.274 或更高版本 |

5530 5530

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

5532 5532

5533* **调用未指定的服务器**：Claude Code 会保持插件提供的服务器继续运行。需要 Agent SDK v0.3.210 或更高版本。5533* **调用未指定的服务器**：在[云端会话](/docs/zh-CN/claude-code-on-the-web)之外，Claude Code 会断开先前 `setMcpServers()` 调用添加的服务器以及进程内 SDK 服务器的连接，并在 `removed` 中列出它们。其他服务器会继续运行，且不会列在 `removed` 中，其中包括来自 [`mcpServers`](#options) 选项的 stdio、HTTP 和 SSE 服务器、来自设置文件的服务器以及插件提供的服务器。

5534* **调用指定的服务器**：除 CLI 在启动时启动的内置服务器外，只有当正在运行的服务器的配置与您传入的配置不同时，Claude Code 才会替换它。5534* **调用指定的服务器**：对于先前 `setMcpServers()` 调用添加的 stdio、HTTP 或 SSE 服务器，只有当其配置与您传入的配置不同时，Claude Code 才会替换它。已以该名称注册的进程内 SDK 服务器会保持原样，因此要替换它，请在一次调用中将其省略，然后在下一次调用中添加它。

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

5536 5536

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

agent-view.md +1 −0

Details

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 删除因未推送提交而删除被拒绝的会话，丢弃 worktree 及其分支和提交。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.260 或更高版本 |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 删除因未推送提交而删除被拒绝的会话，丢弃 worktree 及其分支和提交。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.260 或更高版本 |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | 删除因 git 或 `WorktreeRemove` hook 无法删除其 worktree 而删除被拒绝的会话，无论如何删除 worktree 目录并在仓库中保留其分支。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.268 或更高版本 |820| `claude rm <id> --force-remove-worktree <worktree-id>` | 删除因 git 或 `WorktreeRemove` hook 无法删除其 worktree 而删除被拒绝的会话，无论如何删除 worktree 目录并在仓库中保留其分支。传递拒绝打印的确切值；参见 [删除会话会删除什么](#what-deleting-a-session-removes)。需要 v2.1.268 或更高版本 |

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

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

823 824

824`claude attach` 和 `claude logs` 可以使用运行中会话名称的一部分代替 ID，例如 `claude logs "auth refactor"`。传递名称需要 Claude Code v2.1.290 或更高版本。825`claude attach` 和 `claude logs` 可以使用运行中会话名称的一部分代替 ID，例如 `claude logs "auth refactor"`。传递名称需要 Claude Code v2.1.290 或更高版本。

agents.md +1 −1

Details

20 20

21三个更多的工具支持这项工作，但它们本身不是运行代理的方式：21三个更多的工具支持这项工作，但它们本身不是运行代理的方式：

22 22

23* [Worktrees](/docs/zh-CN/worktrees) 为每个会话提供单独的 git 检出，因此并行会话永远不会编辑相同的文件。将它们用于您自己运行的会话。代理视图会 [在编辑文件之前将分派的会话移到自己的 worktree 中](/docs/zh-CN/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自获得一个。23* [Worktree](/docs/zh-CN/worktrees) 为每个会话提供单独的 git 检出，因此并行会话各自编辑自己的文件副本。将它们用于您自己运行的会话。从 Agent 视图分派的会话会 [在编辑文件之前移到自己的 worktree 中](/docs/zh-CN/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自获得一个。

24* [跨会话消息传递](/docs/zh-CN/cross-session-messaging) 让 Claude 列出并消息传递您在这台机器上、另一台机器上或 [云中](/docs/zh-CN/claude-code-on-the-web) 的其他 Claude Code 会话，因此您自己运行的会话可以在彼此之间传递发现和状态。24* [跨会话消息传递](/docs/zh-CN/cross-session-messaging) 让 Claude 列出并消息传递您在这台机器上、另一台机器上或 [云中](/docs/zh-CN/claude-code-on-the-web) 的其他 Claude Code 会话，因此您自己运行的会话可以在彼此之间传递发现和状态。

25* [`/batch`](/docs/zh-CN/commands) 是一个 [skill](/docs/zh-CN/skills)，它让 Claude 将一个大型更改分成 5 到 30 个 worktree 隔离的子代理。它是子代理和 worktrees 的打包使用，不是一个单独的协调风格。25* [`/batch`](/docs/zh-CN/commands) 是一个 [skill](/docs/zh-CN/skills)，它让 Claude 将一个大型更改分成 5 到 30 个 worktree 隔离的子代理。它是子代理和 worktrees 的打包使用，不是一个单独的协调风格。

26 26

amazon-bedrock.md +1 −1

Details

681 681

682Amazon Bedrock 以二进制事件流格式流式传输 `InvokeModelWithResponseStream` 响应，标头为 `Content-Type: application/vnd.amazon.eventstream`。Claude Code 和 Amazon Bedrock 之间的网关或代理必须转发响应正文及其标头，包括 `Content-Type`，就像 Amazon Bedrock 发送的那样。682Amazon Bedrock 以二进制事件流格式流式传输 `InvokeModelWithResponseStream` 响应，标头为 `Content-Type: application/vnd.amazon.eventstream`。Claude Code 和 Amazon Bedrock 之间的网关或代理必须转发响应正文及其标头，包括 `Content-Type`，就像 Amazon Bedrock 发送的那样。

683 683

684如果网关将 `Content-Type` 重写为另一个值，Claude Code 会拒绝响应，错误以 `Bedrock streaming response has content-type` 开头，命名它收到的值。常见的重写是 `text/event-stream`，来自将流重新发出为服务器发送事件的集成。684如果网关将 `Content-Type` 重写为另一个值，Claude Code 会拒绝响应，错误以 `Bedrock streaming response has content-type` 开头，命名它收到的值。常见的重写是 `text/event-stream`，来自将流重新发出为服务器发送事件的集成。有关错误消息中提到的 `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` 变量，请参阅 [Bedrock streaming response has an unexpected content-type](/docs/zh-CN/errors#bedrock-streaming-response-has-an-unexpected-content-type)。

685 685

686如果网关删除或清空标头，Claude Code 会假设正文是 Amazon Bedrock 的事件流并对其进行解码，因此网关未修改地通过的正文会继续流式传输。686如果网关删除或清空标头，Claude Code 会假设正文是 Amazon Bedrock 的事件流并对其进行解码，因此网关未修改地通过的正文会继续流式传输。

687 687

auto-mode-config.md +1 −1

Details

347}347}

348```348```

349 349

350获取关于您的自定义 `allow`、`soft_deny` 和 `hard_deny` 规则的 AI 反馈：350获取关于您的自定义 `allow`、`soft_deny`、`hard_deny` 和 `environment` 条目的 AI 反馈：

351 351

352```bash theme={null}352```bash theme={null}

353claude auto-mode critique353claude auto-mode critique

chrome.md +1 −1

Details

343 343

344| 错误 | 原因 | 修复 |344| 错误 | 原因 | 修复 |

345| - | - | - |345| - | - | - |

346| "浏览器扩展程序未连接" | 本机消息传递主机无法到达扩展程序，或您的组织的 IP 允许列表拒绝了到 `bridge.claudeusercontent.com` 的连接 | 重新启动 Chrome 和 Claude Code，然后运行 `/chrome` 以重新连接。如果您的组织使用 IP 允许列表且错误仍然存在，请参阅[组织 IP 允许列表和代理出口](/docs/zh-CN/network-config#organization-ip-allowlists-and-proxy-egress) |346| "浏览器扩展程序未连接" | 本机消息传递主机无法到达扩展程序，或您的组织的 IP 允许列表拒绝了到 `bridge.claudeusercontent.com` 的连接 | 检查扩展程序登录的 claude.ai 账户是否与 Claude Code 相同，重新启动 Chrome 和 Claude Code，然后运行 `/chrome` 以重新连接。如果您的组织使用 IP 允许列表且错误仍然存在，请参阅[组织 IP 允许列表和代理出口](/docs/zh-CN/network-config#organization-ip-allowlists-and-proxy-egress) |

claude-apps-gateway.md +18 −14

Details

64</Note>64</Note>

65 65

66<h3 id="prerequisites">66<h3 id="prerequisites">

~~67 前置条件~~67 前提条件

68</h3>68</h3>

69 69

70在开始之前，请准备好以下内容：70在开始之前，请准备好以下内容：

73| - | - |73| - | - |

74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |

75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |

76| PostgreSQL 14 或更高版本 | 支持设备登录流，其中浏览器回调写入，轮询 CLI 读取，加上速率限制计数器。任何托管 Postgres 都可以，包括最小层级。在没有配置支出限制的情况下，网关存储几 KB 的短期身份验证状态；使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。 |76| PostgreSQL 11 或更高版本 | 支持设备登录流和速率限制计数器。托管 PostgreSQL 服务均可使用，包括最小层级；请参阅[支持哪些数据库](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)时，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 要求网关服务器上的 Claude Code 为 v2.1.290 或更高版本。PostgreSQL 项目已不再维护这些版本，因此请尽可能使用更新的版本。 |

~~77| 模型上游 | Amazon Bedrock 凭证、Claude Platform on AWS 凭证、Google Cloud 凭证、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |~~77| 模型上游 | Amazon Bedrock 凭据、Claude Platform on AWS 凭据、Google Cloud 凭据、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |

78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行并设置 `listen.public_url` 为外部源，两种情况都是如此。纯 `http://` 源仅在网关主机是环回时接受：`localhost`、`127.0.0.1` 或 `::1`。 |78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行，两种情况下都要将 `listen.public_url` 设置为外部源。在 `/login` 处，Claude Code 仅在网关主机是环回时才接受纯 `http://` 源：`localhost`、`127.0.0.1` 或 `::1`。 |

79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何公共地址都被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，[声明这些块](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那里的网关。 |79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何不在您所声明地址块内的公共地址都会被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，[声明这些块](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那里的网关。 |

80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |

81 81

82<h3 id="steps">82<h3 id="steps">

89 </Step>89 </Step>

90 90

91 <Step title="配置 PostgreSQL 数据库">91 <Step title="配置 PostgreSQL 数据库">

92 任何 Postgres 14 或更高版本都可以，包括最小的托管层级。网关在启动时运行自己的架构迁移，因此数据库角色需要创建和修改表的权限；请参阅 [`store`](/docs/zh-CN/claude-apps-gateway-config#store)。92 使用 PostgreSQL 11 或更高版本。最小的托管层级就足够了。网关在启动时运行自己的 schema 迁移，因此数据库角色需要创建和修改表的权限；请参阅 [`store`](/docs/zh-CN/claude-apps-gateway-config#store)。

93 </Step>93 </Step>

94 94

95 <Step title="编写 gateway.yaml">95 <Step title="编写 gateway.yaml">

120 upstreams:120 upstreams:

121 - provider: bedrock121 - provider: bedrock

122 region: us-east-1122 region: us-east-1

123 auth: {} # 空：AWS 默认凭证链123 auth: {} # 空：AWS 默认凭据链

124 # (IRSA, EC2/ECS task role, env vars, ~/.aws)124 # (IRSA, EC2/ECS task role, env vars, ~/.aws)

125 125

126 # 模型会自动按上游转换。内置目录126 # 模型会自动按上游转换。内置目录

133 此配置足以使用默认 Amazon Bedrock 模型目录进行工作登录循环。运行后，通过 [`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 添加按组 RBAC 和托管设置，通过 [`telemetry`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 添加遥测扇出，以及通过 [`models`](/docs/zh-CN/claude-apps-gateway-config#models) 添加多上游故障转移、预配置吞吐量 ARN 或非美国地区。133 此配置足以使用默认 Amazon Bedrock 模型目录进行工作登录循环。运行后，通过 [`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 添加按组 RBAC 和托管设置，通过 [`telemetry`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 添加遥测扇出，以及通过 [`models`](/docs/zh-CN/claude-apps-gateway-config#models) 添加多上游故障转移、预配置吞吐量 ARN 或非美国地区。

134 134

135 <Note>135 <Note>

136 Amazon Bedrock 上游需要一个 AWS 主体，具有对 `inference-profile/us.anthropic.*` ARN 和底层 `foundation-model/anthropic.*` ARN 的 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`，以及在 Bedrock 控制台的模型目录中为该账户提交的 Anthropic 一次性用例表单。使用 EKS 上的 IRSA、ECS 任务角色或 EC2 实例配置文件提供凭证，而不是静态密钥。[`upstreams` 参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)具有完整的 IAM 详情、跨云凭证矩阵以及其他提供商的 `auth` 块。136 Amazon Bedrock 上游需要一个 AWS 主体，具有对 `inference-profile/us.anthropic.*` ARN 和底层 `foundation-model/anthropic.*` ARN 的 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 权限。它还需要在 Bedrock 控制台的模型目录中为该账户提交 Anthropic 的一次性用例表单。

137

138 使用 EKS 上的 IRSA、ECS 任务角色或 EC2 实例配置文件提供凭据，而不是静态密钥。[`upstreams` 参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)具有完整的 IAM 详情、跨云凭据矩阵以及其他提供商的 `auth` 块。

137 </Note>139 </Note>

138 </Step>140 </Step>

139 141

150 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

151 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

152 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

153 # AWS 凭证：在生产中，省略这些并使用实例155 # AWS 凭据：在生产中，省略这些并使用实例

154 # 角色。对于本地 Compose 测试，传递您自己的：156 # 角色。对于本地 Compose 测试，传递您自己的：

155 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

156 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

168 volumes: { pgdata: }170 volumes: { pgdata: }

169 ```171 ```

170 172

171 网关是一个单一的 Linux 二进制文件，读取配置，连接到 Postgres 并应用其架构迁移，针对您的 IdP 运行 OIDC 发现，构建上游客户端，并开始侦听。启动对配置、Postgres 连接、OIDC 发现和上游客户端构造是失败关闭的。如果其中任何一个无法访问或配置错误，网关会以错误退出，而不是以降级状态提供流量。173 网关是一个单一的 Linux 二进制文件，读取配置，连接到 Postgres 并应用其 schema 迁移，针对您的 IdP 运行 OIDC 发现，构建上游客户端，并开始侦听。

174

175 启动对配置、Postgres 连接、OIDC 发现和上游客户端构造是失败关闭的。如果其中任何一个无法访问或配置错误，网关会以错误退出，而不是以降级状态提供流量。

172 176

173 成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭证在第一个请求时解析，而不是在启动时。177 成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭据在第一个请求时解析，而不是在启动时。

174 178

175 监视 stderr 以获取启动序列。日志行使用格式 `[gateway] <timestamp> <level> <message>`，审计事件是带有 `evt` 字段的单行 JSON，启动横幅（下面省略）在迁移和侦听行之间打印。新数据库每个架构迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：179 监视 stderr 以获取启动序列。日志行使用格式 `[gateway] <timestamp> <level> <message>`，审计事件是带有 `evt` 字段的单行 JSON，启动横幅（下面省略）在迁移和侦听行之间打印。新数据库每个 schema 迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：

176 180

177 ```text theme={null}181 ```text theme={null}

178 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}182 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

190 * 无法访问的 Postgres194 * 无法访问的 Postgres

191 * 没有 DDL 权限的 Postgres 角色195 * 没有 DDL 权限的 Postgres 角色

192 * 无法访问或无效的 OIDC 发现文档196 * 无法访问或无效的 OIDC 发现文档

193 * 配置架构违规，带有违规字段路径197 * 配置 schema 违规，带有违规字段路径

194 198

195 修复它并重新启动。199 修复它并重新启动。

196 200

249 </Step>253 </Step>

250 254

251 <Step title="登录开发人员">255 <Step title="登录开发人员">

252 最后一步发生在开发人员机器上，而不是服务器上。在该机器的[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)中将 `forceLoginMethod` 设置为 `"gateway"` 并将 `forceLoginGatewayUrl` 设置为您的网关的 `public_url`，然后运行 `/login`，在**Cloud gateway** 屏幕上按 Enter，并完成浏览器登录。下面的[设置网关 URL](#set-the-gateway-url)涵盖大规模分发两个密钥。256 最后一步发生在开发人员机器上，而不是服务器上。在该机器的[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)中将 `forceLoginMethod` 设置为 `"gateway"` 并将 `forceLoginGatewayUrl` 设置为您的网关的 `public_url`，然后运行 `/login`，在**Cloud gateway** 屏幕上按 Enter，并完成浏览器登录。下面的[设置网关 URL](#set-the-gateway-url)介绍如何将这两个键分发到每台开发人员机器。

253 </Step>257 </Step>

254</Steps>258</Steps>

255 259

claude-apps-gateway-config.md +3 −3

Details

158网关在启动时读取一次密钥和证书，因此更改后的文件仅在重启后生效。请按以下顺序轮换，以确保任何令牌请求都不会出示 IdP 中不存在的证书：158网关在启动时读取一次密钥和证书，因此更改后的文件仅在重启后生效。请按以下顺序轮换，以确保任何令牌请求都不会出示 IdP 中不存在的证书：

159 159

1601. 将新证书与旧证书一起上传到 IdP。1601. 将新证书与旧证书一起上传到 IdP。

1612. 替换 `gateway.yaml` 加载的密钥和证书文件，然后重启网关。1612. 替换 `gateway.yaml` 加载的密钥和证书文件，然后重启网关。如果您运行多个副本，可以使用[滚动重启](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)，因为在您删除旧证书之前，IdP 同时拥有这两个证书。

1623. 从 IdP 中删除旧证书。1623. 在每个副本都重启之后，从 IdP 中删除旧证书。

163 163

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 通过前向代理的 IdP 请求165 通过前向代理的 IdP 请求

227 227

228| 字段 | 必需 | 描述 |228| 字段 | 必需 | 描述 |

229| - | - | - |229| - | - | - |

230| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：设备授权集合点，浏览器回调写入和轮询 CLI 读取，需要跨副本状态。网关在启动和升级时运行自己的 schema 迁移，因此角色需要在目标 schema 上创建和更改表的权限。请参阅[升级](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。 |230| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL，只能包含一个主机，不能是逗号分隔的列表。网关在启动和升级时运行自己的 schema 迁移，因此角色需要在目标 schema 上创建和更改表的权限。请参阅[升级](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。 |

231| `username` | 否 | 覆盖 `postgres_url` 中的用户 |231| `username` | 否 | 覆盖 `postgres_url` 中的用户 |

232| `password` | 否 | 数据库凭据。在此设置而不是在 `postgres_url` 中，以便凭据保持在 URL 之外。接受任何字符并优先于 URL 凭据。 |232| `password` | 否 | 数据库凭据。在此设置而不是在 `postgres_url` 中，以便凭据保持在 URL 之外。接受任何字符并优先于 URL 凭据。 |

233| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，保守且对共享数据库友好。启用[支出限制](#admin)后，热路径每个推理请求执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 此值低于数据库的 `max_connections`。 |233| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，保守且对共享数据库友好。启用[支出限制](#admin)后，热路径每个推理请求执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 此值低于数据库的 `max_connections`。 |

claude-apps-gateway-deploy.md +7 −1

Details

249 Postgres249 Postgres

250</h3>250</h3>

251 251

252网关将其状态存储在 PostgreSQL 数据库中：

253

254* **数据库**：PostgreSQL 本身，自托管或托管均可，版本为[最低版本](/docs/zh-CN/claude-apps-gateway#prerequisites)或更高。仅实现 Postgres 协议的数据库（例如分布式 SQL 数据库）不受支持。

255* **地址**：`store.postgres_url` 接受一个主机。如果数据库有多个节点，请使用位于它们前面的地址，例如您的托管服务的端点、负载均衡器或虚拟 IP。设置一个比故障转移所需时间更长的[就绪宽限期](#readiness-grace-period)。

256

252网关持有五个数据表加上一个 `_migrations` 表，全部由其启动时迁移创建：257网关持有五个数据表加上一个 `_migrations` 表，全部由其启动时迁移创建：

253 258

254| 表 | 内容 | 保留 |259| 表 | 内容 | 保留 |

398| 启动退出，显示配置验证错误，命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |403| 启动退出，显示配置验证错误，命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

404| 启动退出：`store.postgres_url in <path> is not a URL the gateway can read`，或在 v2.1.290 之前仅显示 `Invalid URL` 或 `URI error` | 无法解析该 URL，例如因为它列出了多个主机，或其密码包含未编码的 `/`、`?`、`#` 或 `%` | 仅指定[一个主机](#postgres)，并将密码移到 [`store.password`](/docs/zh-CN/claude-apps-gateway-config#store) 中 |

400| 启动退出，在 `config.load` 后显示 OIDC 发现错误 | `oidc.issuer` 无法访问，或 TLS 链不受信任 | 检查发行者是否可从 pod 访问并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。如果 pod 也无法解析 IdP 的主机名，或代理拒绝 `CONNECT` 到 IP 地址，请参阅[仅代理出口](/docs/zh-CN/claude-apps-gateway-config#proxy-only-egress)，这需要 v2.1.277 或更高版本。 |406| 启动退出，在 `config.load` 后显示 OIDC 发现错误 | `oidc.issuer` 无法访问，或 TLS 链不受信任 | 检查发行者是否可从 pod 访问并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。如果 pod 也无法解析 IdP 的主机名，或代理拒绝 `CONNECT` 到 IP 地址，请参阅[仅代理出口](/docs/zh-CN/claude-apps-gateway-config#proxy-only-egress)，这需要 v2.1.277 或更高版本。 |

402| 日志：`could not connect to Postgres at boot, attempt 1 of 3` | 当网关启动时数据库无法访问，例如在网络仍在启动的冷实例上 | 如果网关随后完成启动，无需采取任何措施。当数据库无法访问时，网关在退出前尝试连接三次，间隔两秒。如果它以 `could not connect to Postgres` 退出，检查 `store.postgres_url` 和到数据库的网络路径。如果尝试超时而不是被拒绝，提高 [`store.connect_timeout_seconds`](/docs/zh-CN/claude-apps-gateway-config#store) 以给每个尝试更长的时间。 |408| 日志：`could not connect to Postgres at boot, attempt 1 of 3` | 当网关启动时数据库无法访问，例如在网络仍在启动的冷实例上 | 如果网关随后完成启动，无需采取任何措施。当数据库无法访问时，网关在退出前尝试连接三次，间隔两秒。如果它以 `could not connect to Postgres` 退出，检查 `store.postgres_url`（包括它是否只指定了一个主机）以及到数据库的网络路径。如果尝试超时而不是被拒绝，提高 [`store.connect_timeout_seconds`](/docs/zh-CN/claude-apps-gateway-config#store) 以给每个尝试更长的时间。 |

403| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝、id\_token 验证失败，或 `email_verified` 显式为 `false`，网关总是拒绝且无覆盖 | 检查 `allowed_email_domains` 和 IdP 是否返回已验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |409| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝、id\_token 验证失败，或 `email_verified` 显式为 `false`，网关总是拒绝且无覆盖 | 检查 `allowed_email_domains` 和 IdP 是否返回已验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |

404| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺少的电子邮件会创建没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上添加 `email` 作为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，例如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |410| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺少的电子邮件会创建没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上添加 `email` 作为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，例如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |

405| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以网关询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。网关回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的网关版本记录相同的行但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在网关 v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该设置项不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发出的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅[身份提供者设置](#identity-provider-setup)了解取消配置权衡。 |411| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以网关询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。网关回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的网关版本记录相同的行但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在网关 v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该设置项不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发出的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅[身份提供者设置](#identity-provider-setup)了解取消配置权衡。 |

claude-apps-gateway-on-aws.md +14 −11

Details

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```137 ```

138 138

139 ECS 还需要一个执行角色，ECS 代理本身使用它从 ECR 拉取镜像并注入稍后创建的 Secrets Manager 值。它与 gateway 的 AWS SDK 在运行时使用的任务角色分开：139 ECS 还需要一个执行角色，ECS Agent 本身使用它从 ECR 拉取镜像并注入稍后创建的 Secrets Manager 值。它与 gateway 的 AWS SDK 在运行时使用的任务角色分开：

140 140

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

142 aws iam create-role --role-name claude-gateway-execution \142 aws iam create-role --role-name claude-gateway-execution \

169 </Step>169 </Step>

170 170

171 <Step title="配置 Amazon RDS for PostgreSQL">171 <Step title="配置 Amazon RDS for PostgreSQL">

172 该实例在私有子网中运行，没有公共地址，存储加密打开。引擎版本固定为 Postgres 16，满足 gateway 支持的 PostgreSQL 14 下限，并保证下面的参数组系列与实例匹配。172 该实例在私有子网中运行 Postgres 16，没有公共地址，存储加密打开。

173 173

174 首先，创建将数据库放在私有子网中的子网组，以及具有 `rds.force_ssl=1` 的参数组，以便服务器拒绝明文连接。引擎版本固定一次，因为参数组的系列必须与实例运行的引擎主版本匹配：174 首先，创建将数据库放在私有子网中的子网组，以及具有 `rds.force_ssl=1` 的参数组，以便服务器拒绝明文连接。引擎版本固定一次，因为参数组的系列必须与实例运行的引擎主版本匹配：

175 175

218 </Step>218 </Step>

219 219

220 <Step title="编写 gateway.yaml">220 <Step title="编写 gateway.yaml">

221 `upstreams` 块使用 `auth: {}` 指向 Bedrock，因此 gateway 通过 ECS 上的任务角色或 EKS 上的 IRSA 角色从 AWS 默认凭证链进行身份验证。有关每个字段，请参阅[配置参考](/docs/zh-CN/claude-apps-gateway-config)。221 `upstreams` 块使用 `auth: {}` 指向 Bedrock，因此 gateway 通过 ECS 上的任务角色或 EKS 上的 IRSA 角色从 AWS 默认凭据链进行身份验证。有关每个字段，请参阅[配置参考](/docs/zh-CN/claude-apps-gateway-config)。

222 222

223 两个 `listen` 字段描述什么位于 gateway 前面：223 两个 `listen` 字段描述什么位于 gateway 前面：

224 224

255 255

256 store:256 store:

257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

258 # readiness_grace_seconds: 300 # 通过 RDS 故障转移保持通过健康检查258 # readiness_grace_seconds: 300 # 在 RDS 故障转移期间

259 # 保持通过健康检查

259 260

260 upstreams:261 upstreams:

261 - provider: bedrock262 - provider: bedrock

262 region: <your-region> # 匹配 $AWS_REGION 以便 IAM263 region: <your-region> # 匹配 $AWS_REGION 以便 IAM

263 # 策略的 ARN 涵盖它264 # 策略的 ARN 涵盖它

264 auth: {} # AWS 默认凭证链：265 auth: {} # AWS 默认凭据链：

265 # ECS 任务角色，或 EKS 上的 IRSA266 # ECS 任务角色，或 EKS 上的 IRSA

266 ```267 ```

267 268

288 字面 `--secret-string` 参数在每个命令运行时在进程表和审计/EDR 日志中可见。在共享或受监控的主机上，将值放在 `0600` 文件中，改为传递 `--secret-string file://<path>`。bundle 的 `setup.sh` 以相同的方式将机密值保持在进程 argv 之外，将 `0600` 临时文件传递给 `--cli-input-json`。289 字面 `--secret-string` 参数在每个命令运行时在进程表和审计/EDR 日志中可见。在共享或受监控的主机上，将值放在 `0600` 文件中，改为传递 `--secret-string file://<path>`。bundle 的 `setup.sh` 以相同的方式将机密值保持在进程 argv 之外，将 `0600` 临时文件传递给 `--cli-input-json`。

289 </Note>290 </Note>

290 291

291 与机密不同，`gateway.yaml` 本身不包含机密值，因为每个凭证在启动时通过 [`${VAR}` 或 `${file:...}` 扩展](/docs/zh-CN/claude-apps-gateway-config#secret-expansion)解析。一切如何到达容器因轨道而异：292 与机密不同，`gateway.yaml` 本身不包含机密值，因为每个凭据在启动时通过 [`${VAR}` 或 `${file:...}` 扩展](/docs/zh-CN/claude-apps-gateway-config#secret-expansion)解析。一切如何到达容器因轨道而异：

292 293

293 * 在 ECS 上，下一步的构建将 `gateway.yaml` 复制到镜像中的 `/etc/claude/gateway.yaml`，任务定义通过其 `secrets` 字段将三个机密作为环境变量注入，因此 YAML 引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。294 * 在 ECS 上，下一步的构建将 `gateway.yaml` 复制到镜像中的 `/etc/claude/gateway.yaml`，任务定义通过其 `secrets` 字段将三个机密作为环境变量注入，因此 YAML 引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

294 * 在 EKS 上，从 ConfigMap 挂载 `gateway.yaml` 并将机密作为文件挂载在 `/secrets`，引用为 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驱动程序的 AWS 提供程序从 Secrets Manager 获取 Kubernetes Secrets，或使用 `kubectl` 直接创建它们。295 * 在 EKS 上，从 ConfigMap 挂载 `gateway.yaml` 并将机密作为文件挂载在 `/secrets`，引用为 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驱动程序的 AWS 提供程序从 Secrets Manager 获取 Kubernetes Secrets，或使用 `kubectl` 直接创建它们。

311 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

312 ```313 ```

313 314

314 创建 ECR 存储库并将 Docker 登录到它。不可变标签意味着部署步骤固定的 `<version>` 标签以后不能被无声地重新指向不同的镜像：315 创建 ECR 仓库并将 Docker 登录到它。不可变标签意味着部署步骤固定的 `<version>` 标签以后不能被无声地重新指向不同的镜像：

315 316

316 ```bash theme={null}317 ```bash theme={null}

317 aws ecr create-repository --repository-name claude-gateway \318 aws ecr create-repository --repository-name claude-gateway \

424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

425 ```426 ```

426 427

427 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换。要通过短数据库中断（例如 RDS 故障转移）保持任务通过检查，请按照[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)中所述设置 `store.readiness_grace_seconds`，其中也涵盖了 `/healthz` 替代方案。428 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。

429

430 目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换。要通过短数据库中断（例如 RDS 故障转移）保持任务通过检查，请按照[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)中所述设置 `store.readiness_grace_seconds`，其中也涵盖了 `/healthz` 替代方案。

428 431

429 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。432 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。

430 433

431 通过在 Route 53 私有托管区域中为 gateway 的内部 DNS 名称别名到 ALB，并将 `listen.public_url` 设置为该主机名，为开发人员完成私有可解析主机名。ALB 自己的 `*.elb.amazonaws.com` 名称在内部 ALB 上解析为私有地址，但它不能携带您的 ACM 证书，因此使用您自己的名称。434 最后，为开发人员提供一个可私有解析的主机名：在 Route 53 私有托管区域中，将 gateway 的内部 DNS 名称别名到 ALB，并将 `listen.public_url` 设置为该主机名。ALB 自己的 `*.elb.amazonaws.com` 名称在内部 ALB 上解析为私有地址，但它不能携带您的 ACM 证书，因此使用您自己的名称。

432 435

433 在第一次登录之前，将 OAuth 客户端的授权重定向 URI 更新为 `<public_url>/oauth/callback`。更改 `public_url` 后，在新标签下重建并推送镜像，注册新的任务定义修订版本，然后重新部署。在 ECS 上，该设置位于镜像的嵌入式 `gateway.yaml` 中，gateway 仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。436 在第一次登录之前，将 OAuth 客户端的授权重定向 URI 更新为 `<public_url>/oauth/callback`。更改 `public_url` 后，在新标签下重建并推送镜像，注册新的任务定义修订版本，然后重新部署。在 ECS 上，该设置位于镜像的嵌入式 `gateway.yaml` 中，gateway 仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。

434 </Tab>437 </Tab>

436 <Tab title="EKS">439 <Tab title="EKS">

437 此轨道需要本地安装 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供程序和已安装 AWS Load Balancer Controller 的现有 EKS 集群。集群必须在 `$VPC_ID` 上，以便 pod 可以到达 RDS 私有端点，`claude-gateway-db` 安全组必须允许集群的 pod 或节点安全组而不是 `$GW_SG`。440 此轨道需要本地安装 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供程序和已安装 AWS Load Balancer Controller 的现有 EKS 集群。集群必须在 `$VPC_ID` 上，以便 pod 可以到达 RDS 私有端点，`claude-gateway-db` 安全组必须允许集群的 pod 或节点安全组而不是 `$GW_SG`。

438 441

439 在 EKS 上，gateway 通过 IRSA 而不是 ECS 角色获得其 Bedrock 凭证。IAM 步骤中的 `ecs-tasks.amazonaws.com` 信任策略在这里不适用；IRSA 需要一个信任策略在集群的 OIDC 提供程序上联合的角色，范围为 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一个步骤中创建该角色、附加策略并使用角色 ARN 注解 Kubernetes 服务账户。将 IAM 步骤中的两个策略文档转换为它可以附加的托管策略：442 在 EKS 上，gateway 通过 IRSA 而不是 ECS 角色获得其 Bedrock 凭据。IAM 步骤中的 `ecs-tasks.amazonaws.com` 信任策略在这里不适用；IRSA 需要一个信任策略在集群的 OIDC 提供程序上联合的角色，范围为 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一个步骤中创建该角色、附加策略并使用角色 ARN 注解 Kubernetes 服务账户。将 IAM 步骤中的两个策略文档转换为它可以附加的托管策略：

440 443

441 ```bash theme={null}444 ```bash theme={null}

442 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \445 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

475 </Step>478 </Step>

476 479

477 <Step title="将 gateway URL 推送到开发人员机器">480 <Step title="将 gateway URL 推送到开发人员机器">

478 gateway 现在正在运行，但开发人员在通过 MDM 部署的[托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)中设置 `forceLoginMethod` 和 `forceLoginGatewayUrl` 之前无法从 `/login` 到达它。开发人员无法手动在登录选择器中选择 gateway 选项。481 gateway 现在正在运行，但在 gateway URL 出现在开发人员的机器上之前，开发人员无法从 `/login` 到达它。在通过 MDM 部署到每台设备的[托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)中设置 `forceLoginMethod` 和 `forceLoginGatewayUrl`。登录选择器中没有可供开发人员手动选择的 gateway 选项。

479 </Step>482 </Step>

480</Steps>483</Steps>

481 484

claude-code-on-the-web.md +4 −2

Details

442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 账户登录。如果您使用 API 密钥进行身份验证，或者存储的账户详情已过期，您会看到以下情况之一：442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 账户登录。如果您使用 API 密钥进行身份验证，或者存储的账户详情已过期，您会看到以下情况之一：

443 443

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* 提示 API 密钥身份验证不足的消息445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* 在不带会话 ID 运行 `claude --teleport` 时，会话选择器中显示 `Error loading Claude Code sessions`446* 在不带会话 ID 运行 `claude --teleport` 时，会话选择器中显示 `Error loading Claude Code sessions`

447 447

448运行 `/login` 以使用您的 claude.ai 账户登录，然后重试该命令。如果错误中提到的是您的提供商，请参阅[错误表](#errors-when-sending-to-a-cloud-session)：云端会话无法通过第三方提供商使用。448在 shell 中运行 [`claude auth login`](/docs/zh-CN/cli-reference#cli-commands) 以使用您的 claude.ai 账户登录，然后重试该命令。在正在运行的会话中，`/login` 的作用相同。如果错误中提到的是您的提供商，请参阅[错误表](#errors-when-sending-to-a-cloud-session)：云端会话无法通过第三方提供商使用。

449

450在 v2.1.274 至 v2.1.289 版本中，登录消息为 `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`

449 451

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 Remote Control 会话已过期或访问被拒绝453 Remote Control 会话已过期或访问被拒绝

claude-directory.md +3 −3

Details

34 oneLiner: 'Project instructions Claude reads every session',34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> in place of a <C>CLAUDE.md</C></>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions39 example: `# Project conventions

40 40

1434 1434

1435在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。1435在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。

1436 1436

1437大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。如果您的存储库已经有一个 `AGENTS.md` 用于其他编码代理，Claude Code [可以自己读取它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起读取。目录的其余部分是可选的：根据需要添加 skills、rules 或 subagents。1437大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。如果您的仓库已经有一个供其他编码 Agent 使用的 `AGENTS.md`，Claude Code [可以读取它](/docs/zh-CN/memory#agents-md)来代替 `CLAUDE.md`。目录的其余部分是可选的：根据需要添加 skill、规则或子代理。

1438 1438

1439<h2 id="explore-the-directory">1439<h2 id="explore-the-directory">

1440 探索目录1440 探索目录

1454| - | - | - |1454| - | - | - |

1455| `managed-settings.json` | 系统级别，因操作系统而异 | 企业强制执行的设置，您无法覆盖，除了[狭窄的例外](/docs/zh-CN/settings#security-keys-where-the-stricter-value-applies)。请参阅[保存文件的位置](/docs/zh-CN/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。 |1455| `managed-settings.json` | 系统级别，因操作系统而异 | 企业强制执行的设置，您无法覆盖，除了[狭窄的例外](/docs/zh-CN/settings#security-keys-where-the-stricter-value-applies)。请参阅[保存文件的位置](/docs/zh-CN/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。 |

1458| 已安装的插件 | `~/.claude/plugins` | 克隆的市场、已安装的插件版本、`installed_plugins.json` 安装记录和每个插件的数据，由 `claude plugin` 命令管理。从您的 claude.ai 账户[同步的插件](/docs/zh-CN/plugins/loading#synced-plugins)下载到 `~/.claude/plugins/synced/`。对于从市场[`command` 源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source)以链接模式安装的插件，Claude Code 在此处存储链接而不是副本，插件的文件保留在命令打印的目录中。`command` 源需要 Claude Code v2.1.229 或更高版本。在您从本地路径添加的市场中按相对路径列出的插件也会[从其源目录就地加载](/docs/zh-CN/plugins/loading#find-plugins-on-disk)，而不是从缓存副本加载。请参阅[插件缓存](/docs/zh-CN/plugins/loading#find-plugins-on-disk)了解孤立版本如何被清理。 |1458| 已安装的插件 | `~/.claude/plugins` | 克隆的市场、已安装的插件版本、`installed_plugins.json` 安装记录和每个插件的数据，由 `claude plugin` 命令管理。从您的 claude.ai 账户[同步的插件](/docs/zh-CN/plugins/loading#synced-plugins)下载到 `~/.claude/plugins/synced/`。对于从市场[`command` 源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source)以链接模式安装的插件，Claude Code 在此处存储链接而不是副本，插件的文件保留在命令打印的目录中。`command` 源需要 Claude Code v2.1.229 或更高版本。在您从本地路径添加的市场中按相对路径列出的插件也会[从其源目录就地加载](/docs/zh-CN/plugins/loading#find-plugins-on-disk)，而不是从缓存副本加载。请参阅[插件缓存](/docs/zh-CN/plugins/loading#find-plugins-on-disk)了解孤立版本如何被清理。 |

1459 1459

1460`~/.claude` 还保存 Claude Code 在您工作时写入的数据：记录、提示历史、文件快照、缓存和日志。请参阅下面的[应用数据](#application-data)。1460`~/.claude` 还保存 Claude Code 在您工作时写入的数据：记录、提示历史、文件快照、缓存和日志。请参阅下面的[应用数据](#application-data)。

cli-reference.md +2 −0

Details

32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 通过从用户设置文件中删除 `autoMode` 部分来恢复默认 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 配置。在写入前提示确认；传递 `-y`/`--yes` 以跳过提示。来自 [托管设置](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的规则仍然适用。需要 Claude Code v2.1.212 或更高版本。请参阅 [检查默认值和您的有效配置](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 通过从用户设置文件中删除 `autoMode` 部分来恢复默认 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 配置。在写入前提示确认；传递 `-y`/`--yes` 以跳过提示。来自 [托管设置](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的规则仍然适用。需要 Claude Code v2.1.212 或更高版本。请参阅 [检查默认值和您的有效配置](/docs/zh-CN/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

34| `claude daemon logs` | 跟踪后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 的日志文件 `~/.claude/daemon.log`，在新行到达时将其打印出来，直到您按下 `Ctrl+C` | `claude daemon logs` |

35| `claude daemon run` | 在此终端的前台运行后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process)，并打印其日志 | `claude daemon run` |

35| `claude daemon stop --any` | 停止后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/docs/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | 停止后台会话 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/docs/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |

context-window.md +1 −1

Details

1586 1586

1587该会话通过具有代表性的令牌计数演示了一个现实的流程：1587该会话通过具有代表性的令牌计数演示了一个现实的流程：

1588 1588

1589* **在您输入任何内容之前**：CLAUDE.md、自动内存、MCP 工具名称和技能描述都加载到上下文中。[AGENTS.md 文件](/docs/zh-CN/memory#agents-md)也可以加载，无论是单独加载还是与 CLAUDE.md 一起加载。您自己的设置可能会在此处添加更多内容，例如[输出样式](/docs/zh-CN/output-styles)或来自 [`--append-system-prompt`](/docs/zh-CN/cli-reference) 的文本。1589* **在您输入任何内容之前**：CLAUDE.md、自动记忆、MCP 工具名称和 skill 描述都加载到上下文中。[AGENTS.md 文件](/docs/zh-CN/memory#agents-md)可以代替 CLAUDE.md 加载。您自己的设置可能会在此处添加更多内容，例如[输出样式](/docs/zh-CN/output-styles)或来自 [`--append-system-prompt`](/docs/zh-CN/cli-reference) 的文本。

1590* **当 Claude 工作时**：每个文件读取都会添加到上下文中，[路径范围的规则](/docs/zh-CN/memory#path-specific-rules)会自动与匹配的文件一起加载，并且[PostToolUse hook](/docs/zh-CN/hooks-guide)在每次编辑后触发。1590* **当 Claude 工作时**：每个文件读取都会添加到上下文中，[路径范围的规则](/docs/zh-CN/memory#path-specific-rules)会自动与匹配的文件一起加载，并且[PostToolUse hook](/docs/zh-CN/hooks-guide)在每次编辑后触发。

1591* **后续提示**：[子代理](/docs/zh-CN/sub-agents)在其自己的单独上下文窗口中处理研究，因此大文件读取不会进入您的窗口。只有摘要和一个小的元数据预告片返回。1591* **后续提示**：[子代理](/docs/zh-CN/sub-agents)在其自己的单独上下文窗口中处理研究，因此大文件读取不会进入您的窗口。只有摘要和一个小的元数据预告片返回。

1592* **在演练结束时**：您运行 `/compact`，它用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每个机制会发生什么。1592* **在演练结束时**：您运行 `/compact`，它用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每个机制会发生什么。

desktop.md +1 −1

Details

1092要查看你运行的桌面应用版本：1092要查看你运行的桌面应用版本：

1093 1093

1094* **macOS**：点击菜单栏中的 **Claude**，然后点击 **About Claude**1094* **macOS**：点击菜单栏中的 **Claude**，然后点击 **About Claude**

1095* **Windows**：点击 **Help**，然后点击 **About**1095* **Windows**：点击 **Help**，然后点击 **About Claude**

1096 1096

1097点击版本号将其复制到你的剪贴板。1097点击版本号将其复制到你的剪贴板。

1098 1098

desktop-ios-simulator.md +1 −1

Details

92* 使用 **Cmd+S** 保存屏幕截图或使用 **Cmd+R** 保存屏幕录制，使用窗格的捕获按钮或快捷键；文件保存到你的桌面92* 使用 **Cmd+S** 保存屏幕截图或使用 **Cmd+R** 保存屏幕录制，使用窗格的捕获按钮或快捷键；文件保存到你的桌面

93* 通过单击**Detach simulator** 停止流式传输设备而不关闭它，这会将窗格返回到其**Attach simulator** 状态93* 通过单击**Detach simulator** 停止流式传输设备而不关闭它，这会将窗格返回到其**Attach simulator** 状态

94 94

95要调整来自模拟器的视频流，请打开窗格的 **Display** 菜单。如果窗格对您的 Mac 造成压力，请降低**Frame rate** 或**Resolution**。这两项设置改变窗格显示设备的方式，而不是应用运行的方式。95如果窗格显示 **Display** 菜单，可以使用它来调整来自模拟器的视频流。如果窗格对您的 Mac 造成压力，请降低**Frame rate** 或**Resolution**。这两项设置改变窗格显示设备的方式，而不是应用运行的方式。

96 96

97你和 Claude 驱动同一设备，因此你的点击会改变 Claude 看到的应用状态。要让 Claude 检查特定屏幕，通过点击导航到它，然后提出要求。当 Claude 驱动设备时，窗格在屏幕上方显示**Claude is using this device** 徽章；在徽章清除之前暂停点击，以便结果反映应用而不是你的输入。97你和 Claude 驱动同一设备，因此你的点击会改变 Claude 看到的应用状态。要让 Claude 检查特定屏幕，通过点击导航到它，然后提出要求。当 Claude 驱动设备时，窗格在屏幕上方显示**Claude is using this device** 徽章；在徽章清除之前暂停点击，以便结果反映应用而不是你的输入。

98 98

env-vars.md +1 −0

Details

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

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

357| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-CN/plugins/mods/overview) 的文件更改时重新加载该 mod。重新加载适用于您使用 `--plugin-dir` 从目录加载的 mod，且在交互式会话中默认开启。设置为 `1` 可在非交互式会话中也开启，设置为 `0` 可在所有会话中关闭。需要 Claude Code v2.1.287 或更高版本。请参阅 [mod 设置和环境变量](/docs/zh-CN/plugins/mods/reference#settings-and-environment-variables) |

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

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程或无法向远程进行身份验证时跳过重新克隆尝试，并继续使用现有的市场检出。适用于离线或隔离网络环境，在这些环境中重新克隆也会以同样的方式失败。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |359| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程或无法向远程进行身份验证时跳过重新克隆尝试，并继续使用现有的市场检出。适用于离线或隔离网络环境，在这些环境中重新克隆也会以同样的方式失败。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

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

errors.md +2 −3

Details

197| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

198| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [无法获取组织 UUID](/docs/zh-CN/claude-code-on-the-web#unable-to-get-organization-uuid) |

387* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果轮次在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。388* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果轮次在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。

388* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不计入上述 10 次尝试预算。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束轮次。389* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不计入上述 10 次尝试预算。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束轮次。

389* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束轮次。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。390* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束轮次。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。

391* 在 Claude 完成思考或开始任何文本或工具调用之前，被 API 输出内容过滤器拦截的流式响应。Claude Code 会在重试预算内重新发送一次请求，如果过滤器也拦截了第二次响应，则显示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。

390* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。392* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。

391 * 当您使用 claude.ai 订阅登录时，这包括不携带您套餐配额头的 429 节流。在 v2.1.199 之前，Claude Code 仅对 API 密钥和企业登录重试这些节流。393 * 当您使用 claude.ai 订阅登录时，这包括不携带您套餐配额头的 429 节流。在 v2.1.199 之前，Claude Code 仅对 API 密钥和企业登录重试这些节流。

392* 因为输入加上 `max_tokens` 超过上下文限制而被拒绝的请求。以相同方式重新发送它会以相同方式失败，所以 Claude Code 使用减少的 `max_tokens` 重试，并在两种情况下停止重试并改为压缩：394* 因为输入加上 `max_tokens` 超过上下文限制而被拒绝的请求。以相同方式重新发送它会以相同方式失败，所以 Claude Code 使用减少的 `max_tokens` 重试，并在两种情况下停止重试并改为压缩：

405* [Amazon Bedrock 流式响应具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因为重写响应的网关或代理会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。407* [Amazon Bedrock 流式响应具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因为重写响应的网关或代理会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。

406* 失败的流式请求的非流式重试获得成功状态但 [body 中没有 Claude API 消息](#api-returned-an-empty-or-malformed-response)。Claude Code 以该错误结束轮次。408* 失败的流式请求的非流式重试获得成功状态但 [body 中没有 Claude API 消息](#api-returned-an-empty-or-malformed-response)。Claude Code 以该错误结束轮次。

407* 您的组织的策略检查拒绝的请求，其表现为携带拒绝消息的 `API Error:` 行。您的组织管理员使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）设置检查，消息以他们配置的说明结尾，或默认告诉您联系他们。Claude Code 不会将拒绝的请求重新发送到相同模型或 [备用模型](/docs/zh-CN/model-config#fallback-model-chains)，因为拒绝涉及请求的内容而不是模型。在 v2.1.239 之前，Claude Code 可以重新发送拒绝的请求，不流式传输或在配置的备用模型上，然后向您显示拒绝。409* 您的组织的策略检查拒绝的请求，其表现为携带拒绝消息的 `API Error:` 行。您的组织管理员使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）设置检查，消息以他们配置的说明结尾，或默认告诉您联系他们。Claude Code 不会将拒绝的请求重新发送到相同模型或 [备用模型](/docs/zh-CN/model-config#fallback-model-chains)，因为拒绝涉及请求的内容而不是模型。在 v2.1.239 之前，Claude Code 可以重新发送拒绝的请求，不流式传输或在配置的备用模型上，然后向您显示拒绝。

408* 被 API 输出内容过滤器拦截的响应。Claude Code 会立即显示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)，并且不会重试或重新发送该请求。

409 410

410<h3 id="what-you-see-while-claude-code-retries-or-waits">411<h3 id="what-you-see-while-claude-code-retries-or-waits">

411 Claude Code 重试或等待时您看到的内容412 Claude Code 重试或等待时您看到的内容

2905API Error: Output blocked by content filtering policy2906API Error: Output blocked by content filtering policy

2906```2907```

2907 2908

2908Claude Code 在拦截到达时立即显示错误，并在此结束请求。它不会重试请求、以非流式方式重新发送请求，也不会切换到[备用模型](/docs/zh-CN/model-config#fallback-model-chains)。在 v2.1.285 之前，Claude Code 可能会重新发送并重试被拦截的请求（有时持续数分钟），然后才向您显示错误。

~~2909~~

2910**要做什么：**2909**要做什么：**

2911 2910

2912* 重新表述您的上一条消息或采取不同的方法2911* 重新表述您的上一条消息或采取不同的方法

glossary.md +1 −1

Details

130 130

131一个 markdown 文件，包含您为 Claude 编写的持久指令，在每个会话开始时作为系统提示后的用户消息加载。在此处放置项目约定、架构笔记和"始终执行 X"规则。Project-root CLAUDE.md 在 [compaction](#compaction) 期间保留，之后从磁盘重新读取。131一个 markdown 文件，包含您为 Claude 编写的持久指令，在每个会话开始时作为系统提示后的用户消息加载。在此处放置项目约定、架构笔记和"始终执行 X"规则。Project-root CLAUDE.md 在 [compaction](#compaction) 期间保留，之后从磁盘重新读取。

132 132

133您可以在项目范围内的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、用户范围内的 `~/.claude/CLAUDE.md` 或作为组织的[托管策略](#managed-settings)放置 CLAUDE.md。所有发现的文件都被连接到上下文中，而不是相互覆盖，按从最广泛的范围到最具体的范围排序。Claude Code 也可以加载项目的 [AGENTS.md](#agents-md) 文件，单独或与 CLAUDE.md 一起。133您可以在项目作用域内的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、用户作用域内的 `~/.claude/CLAUDE.md` 或作为组织的[托管策略](#managed-settings)放置 CLAUDE.md。所有发现的文件都被连接到上下文中，而不是相互覆盖，按从最广泛的作用域到最具体的作用域排序。Claude Code 也可以加载项目的 [AGENTS.md](#agents-md) 文件来代替 CLAUDE.md。

134 134

135了解更多：[CLAUDE.md files](/docs/zh-CN/memory#claude-md-files)135了解更多：[CLAUDE.md files](/docs/zh-CN/memory#claude-md-files)

136 136

google-vertex-ai.md +2 −2

Details

210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

211```211```

212 212

213大多数模型版本都有对应的 `VERTEX_REGION_CLAUDE_*` 变量。有关完整列表，请参阅[环境变量参考](/docs/zh-CN/env-vars)。检查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以确定哪些模型支持全局端点与仅区域端点。213大多数模型版本都有对应的 `VERTEX_REGION_CLAUDE_*` 变量。有关完整列表，请参阅[环境变量参考](/docs/zh-CN/env-vars#variables)。检查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以确定哪些模型支持全局端点与仅区域端点。

214 214

215如果区域值的形状不像区域或位置名称，Claude Code 会将其视为未设置。例如，Claude Code 将包含斜杠、点或空格的值视为未设置。Claude Code 为每个变量回退到不同的源：215如果区域值的形状不像区域或位置名称，Claude Code 会将其视为未设置。例如，Claude Code 将包含斜杠、点或空格的值视为未设置。Claude Code 为每个变量回退到不同的源：

216 216

366* 验证该模型在您指定的位置可用。某些模型仅在 `global` 或多区域位置（如 `eu` 和 `us`）上提供，而不是在特定区域366* 验证该模型在您指定的位置可用。某些模型仅在 `global` 或多区域位置（如 `eu` 和 `us`）上提供，而不是在特定区域

367* 如果使用 `CLOUD_ML_REGION=global`，请检查您的模型是否在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中的"支持的功能"下支持全局端点。对于不支持全局端点的模型，请执行以下任一操作：367* 如果使用 `CLOUD_ML_REGION=global`，请检查您的模型是否在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中的"支持的功能"下支持全局端点。对于不支持全局端点的模型，请执行以下任一操作：

368 * 通过 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 指定支持的模型，或368 * 通过 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 指定支持的模型，或

369 * 使用 `VERTEX_REGION_<MODEL_NAME>` 环境变量设置区域或多区域位置369 * 使用该模型对应的 `VERTEX_REGION_CLAUDE_*` 变量设置区域或多区域位置，这些变量列于[环境变量参考](/docs/zh-CN/env-vars#variables)中

370 370

371如果您遇到 429 错误：371如果您遇到 429 错误：

372 372

hooks.md +4 −5

Details

63| `DirectoryAdded` | 当工作目录在会话中期通过 `/add-dir` 或 SDK `register_repo_root` 控制请求添加时 |63| `DirectoryAdded` | 当工作目录在会话中期通过 `/add-dir` 或 SDK `register_repo_root` 控制请求添加时 |

64| `FileChanged` | 当监视的文件在磁盘上更改时。`matcher` 字段指定要监视的文件名 |64| `FileChanged` | 当监视的文件在磁盘上更改时。`matcher` 字段指定要监视的文件名 |

65| `WorktreeCreate` | 当通过 `--worktree`、`isolation: "worktree"` 创建工作树时，或用于后台会话。替换默认的 git 行为 |65| `WorktreeCreate` | 当通过 `--worktree`、`isolation: "worktree"` 创建工作树时，或用于后台会话。替换默认的 git 行为 |

67| `PreCompact` | 在上下文压缩之前 |67| `PreCompact` | 在上下文压缩之前 |

68| `PostCompact` | 在上下文压缩完成后 |68| `PostCompact` | 在上下文压缩完成后 |

69| `PreModelSwitch` | 在 Claude Code 应用你或客户端请求的模型切换之前。可以阻止切换 |69| `PreModelSwitch` | 在 Claude Code 应用你或客户端请求的模型切换之前。可以阻止切换 |

3273 WorktreeRemove3273 WorktreeRemove

3274</h3>3274</h3>

3275 3275

3276在移除 worktree 时运行。这是 [WorktreeCreate](#worktreecreate) 对应的清理事件。该事件在以下情况下触发：3276当 Claude Code 清理由您的 [`WorktreeCreate`](#worktreecreate) hook 创建的 worktree 时运行。该事件在以下情况下触发：

3277 3277

3278* 您退出 `--worktree` 会话并选择将其移除3278* 您退出 `--worktree` 会话并选择删除 worktree

3279* 设置了 `isolation: "worktree"` 的子代理完成3279* 您删除在该 worktree 中运行的[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)

3280* 您删除了一个[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)，且其 worktree 由该 hook 创建

3281 3280

3282对于基于 git 的 worktree，Claude Code 会使用 `git worktree remove` 自动处理清理。如果您配置了 WorktreeCreate hook，请搭配一个 WorktreeRemove hook，以控制其所创建的 worktree 的清理：3281对于基于 git 的 worktree，Claude Code 会使用 `git worktree remove` 自动处理清理。如果您配置了 WorktreeCreate hook，请搭配一个 WorktreeRemove hook，以控制其所创建的 worktree 的清理：

3283 3282

hooks-guide.md +1 −1

Details

how-claude-code-works.md +1 −1

Details

76* **您的项目。** 您目录和子目录中的文件，以及其他地方有您许可的文件。76* **您的项目。** 您目录和子目录中的文件，以及其他地方有您许可的文件。

77* **您的终端。** 您可以运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果您可以从命令行做到，Claude 也可以。77* **您的终端。** 您可以运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果您可以从命令行做到，Claude 也可以。

78* **您的 git 状态。** 当前分支、未提交的更改和最近的提交历史。78* **您的 git 状态。** 当前分支、未提交的更改和最近的提交历史。

79* **您的 [CLAUDE.md](/docs/zh-CN/memory)。** 一个 markdown 文件，您可以在其中存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。如果您的存储库有用于其他编码代理的 AGENTS.md，Claude [可以自己读取](/docs/zh-CN/memory#agents-md)或与 CLAUDE.md 一起读取。79* **您的 [CLAUDE.md](/docs/zh-CN/memory)。** 一个 markdown 文件，您可以在其中存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。如果您的仓库有用于其他编码 Agent 的 AGENTS.md，Claude [可以读取它](/docs/zh-CN/memory#agents-md)来代替 CLAUDE.md。

80* **[自动内存](/docs/zh-CN/memory#auto-memory)。** Claude 在您工作时自动保存的学习内容，如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。80* **[自动内存](/docs/zh-CN/memory#auto-memory)。** Claude 在您工作时自动保存的学习内容，如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。

81* **您配置的扩展。** 用于外部服务的 [MCP servers](/docs/zh-CN/mcp)、用于工作流的 [skills](/docs/zh-CN/skills)、用于委派工作的 [subagents](/docs/zh-CN/sub-agents) 和用于浏览器交互的 [Claude in Chrome](/docs/zh-CN/chrome)。81* **您配置的扩展。** 用于外部服务的 [MCP servers](/docs/zh-CN/mcp)、用于工作流的 [skills](/docs/zh-CN/skills)、用于委派工作的 [subagents](/docs/zh-CN/sub-agents) 和用于浏览器交互的 [Claude in Chrome](/docs/zh-CN/chrome)。

82 82

memory.md +2 −2

Details

8 8

9每个 Claude Code 会话都以全新的上下文窗口开始。两种机制可以跨会话传递知识：9每个 Claude Code 会话都以全新的上下文窗口开始。两种机制可以跨会话传递知识：

10 10

~~11* **CLAUDE.md 文件**：您编写的指令，为 Claude 提供持久上下文。Claude 也可以读取存储库的 [`AGENTS.md` 文件](#agents-md)，单独使用或与 CLAUDE.md 一起使用~~11* **CLAUDE.md 文件**：您编写的指令，为 Claude 提供持久上下文。Claude 也可以读取仓库的 [`AGENTS.md` 文件](#agents-md)来代替 CLAUDE.md

12* **自动记忆**：Claude 根据您的更正和偏好自己编写的笔记12* **自动记忆**：Claude 根据您的更正和偏好自己编写的笔记

13 13

14本页面涵盖以下内容：14本页面涵盖以下内容：

15 15

16* [编写和组织 CLAUDE.md 文件](#claude-md-files)16* [编写和组织 CLAUDE.md 文件](#claude-md-files)

~~17* [使用现有 AGENTS.md](#agents-md) 作为您的项目指令，单独使用或与 CLAUDE.md 一起使用~~17* [使用现有 AGENTS.md](#agents-md) 作为您的项目指令

18* [使用 `.claude/rules/` 将规则范围限定为特定文件类型](#organize-rules-with-claude/rules/)18* [使用 `.claude/rules/` 将规则范围限定为特定文件类型](#organize-rules-with-claude/rules/)

19* [配置自动记忆](#auto-memory)，以便 Claude 自动记笔记19* [配置自动记忆](#auto-memory)，以便 Claude 自动记笔记

20* [故障排除](#troubleshoot-memory-issues)当指令未被遵循时20* [故障排除](#troubleshoot-memory-issues)当指令未被遵循时

overview.md +5 −5

Details

167 claude "commit my changes with a descriptive message"167 claude "commit my changes with a descriptive message"

168 ```168 ```

169 169

170 在 CI 中，你可以使用 [GitHub Actions](/docs/zh-CN/github-actions) 或 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) 自动化代码审查和问题分类。170 在 CI 中，您可以使用 [GitHub Actions](/docs/zh-CN/github-actions) 或 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) 自动化代码审查和问题分类。

171 </Accordion>171 </Accordion>

172 172

173 <Accordion title="使用 MCP 连接你的工具" icon="plug">173 <Accordion title="使用 MCP 连接您的工具" icon="plug">

174 [Model Context Protocol (MCP)](/docs/zh-CN/mcp) 是一个开放标准，用于将 AI 工具连接到外部数据源。使用 MCP，Claude Code 可以读取 Google Drive 中的设计文档、更新 Jira 中的工单、从 Slack 拉取数据，或使用你自己的自定义工具。[MCP 快速入门](/docs/zh-CN/mcp-quickstart)端到端连接你的第一个服务器。174 [Model Context Protocol (MCP)](/docs/zh-CN/mcp) 是一个开放标准，用于将 AI 工具连接到外部数据源。使用 MCP，Claude Code 可以读取 Google Drive 中的设计文档、更新 Jira 中的工单、从 Slack 拉取数据，或使用您自己的自定义工具。[MCP 快速入门](/docs/zh-CN/mcp-quickstart)将端到端地连接您的第一个服务器。

175 </Accordion>175 </Accordion>

176 176

177 <Accordion title="使用说明、skills 和 hooks 进行自定义" icon="sliders">177 <Accordion title="使用指令、skill 和 hook 进行自定义" icon="sliders">

178 [`CLAUDE.md`](/docs/zh-CN/memory) 是一个 markdown 文件，你可以将其添加到项目根目录，Claude Code 会在每个会话开始时读取它。使用它来设置编码标准、架构决策、首选库和审查清单。如果你的存储库已经有一个用于其他编码代理的 `AGENTS.md`，Claude Code [可以自己读取它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起读取。Claude 还会在工作时构建[自动内存](/docs/zh-CN/memory#auto-memory)，保存学习内容，跨会话使用，无需你编写任何内容。178 [`CLAUDE.md`](/docs/zh-CN/memory) 是一个 markdown 文件，您可以将其添加到项目根目录，Claude Code 会在每个会话开始时读取它。使用它来设置编码标准、架构决策、首选库和审查清单。如果您的仓库已经有一个供其他编码 Agent 使用的 `AGENTS.md`，Claude Code [可以读取它](/docs/zh-CN/memory#agents-md)来代替 `CLAUDE.md`。Claude 还会在工作时构建[自动记忆](/docs/zh-CN/memory#auto-memory)，跨会话保存所学内容，无需您编写任何内容。

179 179

180 创建 [skills](/docs/zh-CN/skills) 来打包你的团队可以共享的可重复工作流，如 `/review-pr` 或 `/deploy-staging`。180 创建 [skills](/docs/zh-CN/skills) 来打包你的团队可以共享的可重复工作流，如 `/review-pr` 或 `/deploy-staging`。

181 181

plugins/components.md +1 −1

Details

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735

736此代理名为 `my-plugin:security-reviewer`，用户可以使用 `@agent-my-plugin:security-reviewer` [显式调用它](/docs/zh-CN/sub-agents#invoke-subagents-explicitly)。名称形式是 `<plugin>:<name>`，其中 `<name>` 来自 frontmatter，或在没有时来自文件名。736此 Agent 名为 `my-plugin:security-reviewer`，用户可以使用 `@agent-my-plugin:security-reviewer` [显式调用它](/docs/zh-CN/sub-agents#invoke-subagents-explicitly)。名称形式是 `<plugin>:<name>`，其中 `<name>` 来自 frontmatter 的 `name` 字段，或在该字段缺失时来自文件名。

737 737

738`agents` 清单键替换 `agents/` 扫描。738`agents` 清单键替换 `agents/` 扫描。

739 739

plugins/mods/interface.md +5 −3

Details

428 428

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

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | 一个 flex 容器。接受布局属性，如 `flexDirection`、`columnGap`、`padding`、`borderStyle` 和 `width`。 | 到处 |431| `Box` | 一个 flex 容器。接受布局 prop，如 `flexDirection`、`columnGap`、`padding`、[`borderStyle`](/docs/zh-CN/plugins/mods/reference#box-border-styles) 和 `width`。 | 到处 |

432| `Text` | 样式化文本。接受 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主题键或颜色，如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到处 |432| `Text` | 样式化文本。接受 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主题键或颜色，如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到处 |

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

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

563许多窗格是一个文本字段，下面有一个列表。本部分中的示例是一个笔记窗格：输入一条笔记并按 Enter 添加它，每条笔记都有一个用于删除它的 `x` 按钮。添加两条笔记后，终端这样绘制窗格：563许多窗格是一个文本字段，下面有一个列表。本部分中的示例是一个笔记窗格：输入一条笔记并按 Enter 添加它，每条笔记都有一个用于删除它的 `x` 按钮。添加两条笔记后，终端这样绘制窗格：

564 564

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572

573顶部边框上的 `✕` 是 Claude Code 自己用于关闭窗格的标记。

574

573示例使用以下技术：575示例使用以下技术：

574 576

575* **获取输入的文本**：当用户按 Enter 时，`Input` 使用字段的文本调用 `onSubmit(value)`，并在每次更改时调用 `onInput(value)`577* **获取输入的文本**：当用户按 Enter 时，`Input` 使用字段的文本调用 `onSubmit(value)`，并在每次更改时调用 `onInput(value)`

plugins/mods/reference.md +23 −2

Details

242要使树适配其所在位置，请在 hook 中读取以下 prop：242要使树适配其所在位置，请在 hook 中读取以下 prop：

243 243

244* **`Pane` 或横栏的宽度**：按 `e.props.bodyColumns` 绘制244* **`Pane` 或横栏的宽度**：按 `e.props.bodyColumns` 绘制

245* **会话记录旁的 `Pane` 的高度**：当 `e.props.placement` 为 `'dock'` 时，`e.props.scroll.bodyRows` 是该窗格拥有的行数245* **会话记录旁的 `Pane` 的高度**：当 `e.props.placement` 为 `'dock'` 时，`e.props.scroll.bodyRows` 是该窗格可供您的树使用的行数

246* **输入框上方的 `Pane` 的高度**：当 `e.props.placement` 为 `'inline'` 时，窗格会随您的树增高，直到达到上限，而 `bodyRows` 就是该上限。[`$.ui.open` 的 `rows` 字段](/docs/zh-CN/plugins/mods/interface#open-a-pane-at-the-right-time)可请求不同的上限。246* **输入框上方的 `Pane` 的高度**：当 `e.props.placement` 为 `'inline'` 时，窗格会随您的树增高，直到达到上限，而 `bodyRows` 就是该上限。[`$.ui.open` 的 `rows` 字段](/docs/zh-CN/plugins/mods/interface#open-a-pane-at-the-right-time)可请求不同的上限。

247 247

248比窗格更高的树会整体滚动。248比窗格更高的树会整体滚动。

255 255

256| 元素 | 主要 prop | 终端 | Desktop |256| 元素 | 主要 prop | 终端 | Desktop |

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

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

259| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |259| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |

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

261| `Link` | `href`、`label` | ✓ | ✓ |261| `Link` | `href`、`label` | ✓ | ✓ |

270 270

271更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。271更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。

272 272

273<h3 id="box-border-styles">

274 `Box` 边框样式

275</h3>

276

277要在 `Box` 周围绘制边框，请将其 `borderStyle` 设置为以下名称之一，例如 `borderStyle: 'round'`。每一行说明终端针对该名称绘制的内容，并展示边框的上边缘。

278

279| `borderStyle` | 终端绘制的内容 | 上边缘 |

280| :- | :- | :- |

281| `'single'` | 直角细线 | `┌──┐` |

282| `'double'` | 双线 | `╔══╗` |

283| `'round'` | 圆角细线 | `╭──╮` |

284| `'bold'` | 粗线 | `┏━━┓` |

285| `'singleDouble'` | 上下为细线，左右两侧为双线 | `╓──╖` |

286| `'doubleSingle'` | 上下为双线，左右两侧为细线 | `╒══╕` |

287| `'classic'` | ASCII 字符 `+`、`-` 和 `\|` | `+--+` |

288| `'arrow'` | 指向 `Box` 内部的箭头 | `↘↓↓↙` |

289| `'dashed'` | 虚线，四角留空 | `╌╌` |

290| `'quote'` | 左侧一条竖条 `▎`，其他三边为空白单元格 | 空白 |

291

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

293

273<h2 id="limits">294<h2 id="limits">

274 限制295 限制

275</h2>296</h2>

plugins/troubleshooting.md +1 −0

Details

17 17

18 * **为什么作用域、缓存和优先级的行为方式如此**：阅读 [Plugin loading reference](/docs/zh-CN/plugins/loading)18 * **为什么作用域、缓存和优先级的行为方式如此**：阅读 [Plugin loading reference](/docs/zh-CN/plugins/loading)

19 * **查找标志、字段或命令**：使用 [plugin commands reference](/docs/zh-CN/plugins/cli-reference)、[manifest reference](/docs/zh-CN/plugins/manifest-reference) 或 [marketplace reference](/docs/zh-CN/plugins/marketplace-reference)19 * **查找标志、字段或命令**：使用 [plugin commands reference](/docs/zh-CN/plugins/cli-reference)、[manifest reference](/docs/zh-CN/plugins/manifest-reference) 或 [marketplace reference](/docs/zh-CN/plugins/marketplace-reference)

20 * **`hooks module not loaded` 或 `hooks module did not load` 消息**：该插件是一个 [mod](/docs/zh-CN/plugins/mods/overview)，请阅读 [The mod doesn't load](/docs/zh-CN/plugins/mods/troubleshoot#the-mod-doesn’t-load)

20</Note>21</Note>

21 22

22搜索您看到的确切消息。每条消息都列在产生它的阶段下，这不一定是您运行的命令。例如，安装可能因为市场缺失而失败，所以该消息在 [Add a marketplace](#add-a-marketplace) 下。23搜索您看到的确切消息。每条消息都列在产生它的阶段下，这不一定是您运行的命令。例如，安装可能因为市场缺失而失败，所以该消息在 [Add a marketplace](#add-a-marketplace) 下。

quickstart.md +5 −5

Details

37 <Tab title="原生安装（推荐）">37 <Tab title="原生安装（推荐）">

38 **macOS、Linux、WSL：**38 **macOS、Linux、WSL：**

39 39

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

41 curl -fsSL https://claude.ai/install.sh | bash41 curl -fsSL https://claude.ai/install.sh | bash

42 ```42 ```

43 43

44 **Windows PowerShell：**44 **Windows PowerShell：**

45 45

~~46 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~46 ```powershell theme={null}

47 irm https://claude.ai/install.ps1 | iex47 irm https://claude.ai/install.ps1 | iex

48 ```48 ```

49 49

50 **Windows CMD：**50 **Windows CMD：**

51 51

~~52 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~52 ```batch theme={null}

53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

54 ```54 ```

55 55

67 </Tab>67 </Tab>

68 68

69 <Tab title="Homebrew">69 <Tab title="Homebrew">

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

71 brew install --cask claude-code71 brew install --cask claude-code

72 ```72 ```

73 73

79 </Tab>79 </Tab>

80 80

81 <Tab title="WinGet">81 <Tab title="WinGet">

~~82 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~82 ```powershell theme={null}

83 winget install Anthropic.ClaudeCode83 winget install Anthropic.ClaudeCode

84 ```84 ```

85 85

self-hosted-environments-testing.md +1 −1

Details

104 示例脚本104 示例脚本

105</h2>105</h2>

106 106

107下面的脚本针对 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的测试环境的 `ccpool_...` ID，显示在管理页面上的环境详细信息对话框中或由[创建环境调用](#create-a-dedicated-test-environment)返回）运行完整循环，并对每个回复中的哨兵短语进行断言。从您希望会话在其中工作的存储库的 git 检出运行它，在此主机上启动运行器后，安装捕获 hook 并导出 `E2E_REPLY_DIR`。107下面的脚本针对 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的测试环境的 `ccpool_...` ID，显示在管理页面上的环境详细信息对话框中或由[创建环境调用](#create-a-dedicated-test-environment)返回）运行完整循环，并对每个回复中的哨兵短语进行断言。从您希望会话在其中工作的仓库的 git 检出运行它，在此主机上启动运行器后，安装捕获 hook 并导出 `E2E_REPLY_DIR`。首先，按照[从 CI 进行身份验证](#authenticate-from-ci)中的说明，在运行该脚本的机器上使用 claude.ai 账户登录。如果未登录，第一次分派将失败，并出现诸如 `Unable to get organization UUID for cloud session creation` 之类的错误。

108 108

109```bash theme={null}109```bash theme={null}

110#!/usr/bin/env bash110#!/usr/bin/env bash

server-managed-settings.md +1 −1

Details

43 <Step title="打开管理控制台">43 <Step title="打开管理控制台">

44 在 claude.ai 控制台中，转到 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。44 在 claude.ai 控制台中，转到 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。

45 45

46 如果链接将您重定向到其他 Organization settings 页面而不是 Claude Code 页面，则说明您的账户没有所需的角色。Admin 和其他非 Owner 角色无法查看或编辑托管设置，因此请要求您的组织中的 Owner 或 Primary Owner 进行更改。请参阅[访问控制](#access-control)。46 在 Team 或 Enterprise 组织中，如果页面显示您没有访问权限，请让 [Owner 或 Primary Owner](#access-control) 进行更改。

47 </Step>47 </Step>

48 48

49 <Step title="定义您的设置">49 <Step title="定义您的设置">

sessions.md +3 −3

Details

83* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。83* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。

84* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。84* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。

85* VS Code：扩展的对话面板。该表仅涵盖以计划模式结束的对话；对于其余部分，请参阅[恢复过去的对话](/docs/zh-CN/vs-code#resume-past-conversations)。85* VS Code：扩展的对话面板。该表仅涵盖以计划模式结束的对话；对于其余部分，请参阅[恢复过去的对话](/docs/zh-CN/vs-code#resume-past-conversations)。

86* 启动时的会话选择器：您从[会话选择器](#use-the-session-picker)中选择的会话，无论您是使用 `claude --resume` 单独打开它、`claude --from-pr` 还是与多个会话匹配的名称。Claude Code 不恢复存储的权限模式。它在从同一命令行启动新会话的权限模式中启动会话。86* 启动时的会话选择器：您从[会话选择器](#use-the-session-picker)中选择的会话，无论您是单独使用 `claude --resume`、使用 `claude --from-pr`，还是使用与多个会话匹配的名称打开它。Claude Code 以从同一命令行启动新会话时的权限模式启动该会话，但以计划模式结束的会话会以计划模式恢复，除非您传递 `--permission-mode`、`--dangerously-skip-permissions` 或 `--fork-session`。不会恢复其他存储的权限模式。

~~87* 会话内的 `/resume`，带或不带参数：Claude Code 不恢复存储的权限模式。您切换到的对话继续在您当前会话所在的权限模式中。~~87* 会话内的 `/resume`，带或不带参数：您切换到的对话继续使用您当前会话所在的权限模式，但以计划模式结束的对话会以计划模式恢复，即使您使用 `--permission-mode` 或 `--dangerously-skip-permissions` 启动了 Claude Code。如果该对话在本次运行 Claude Code 期间已经打开过，例如您开始时的对话，或您通过 `/clear` 或 `/resume` 离开的对话，则它会改为继续使用您当前的权限模式。

88 88

89在非交互式和 VS Code 路径上恢复计划模式需要 Claude Code v2.1.246 或更高版本。每一行命名会话结束的权限模式、您通过哪个终端、非交互式和 VS Code 路径恢复它，以及 Claude Code 启动恢复会话的权限模式。89在非交互式和 VS Code 路径上恢复计划模式需要 Claude Code v2.1.246 或更高版本。每一行命名会话结束的权限模式、您通过哪个终端、非交互式和 VS Code 路径恢复它，以及 Claude Code 启动恢复会话的权限模式。

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 终端 | 新会话会启动的权限模式。要再次[绕过权限](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，在启动时使用其启动标志之一或[用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 启用它 |93| `bypassPermissions` | 终端 | 新会话会启动的权限模式。要再次[绕过权限](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，在启动时使用其启动标志之一或[用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 启用它 |

~~94| `plan` | 终端 | 新会话会启动的权限模式 |~~94| `plan` | 终端 | 计划模式。使用 `--fork-session` 时，为新会话会启动的权限模式 |

95| `auto` | 终端 | `auto`，仅当您的帐户仍然满足[自动模式要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时 |95| `auto` | 终端 | `auto`，仅当您的帐户仍然满足[自动模式要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时 |

96| Manual | 终端 | 当新会话会从[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)以自动模式启动时，手动模式。当来自设置文件的 `defaultMode` [生效](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)时，Claude Code 在该模式中启动恢复的会话 |96| Manual | 终端 | 当新会话会从[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)以自动模式启动时，手动模式。当来自设置文件的 `defaultMode` [生效](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)时，Claude Code 在该模式中启动恢复的会话 |

sub-agents.md +2 −2

Details

310 310

311| Field | 必需 | Description |311| Field | 必需 | Description |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 是 | 唯一标识符，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-CN/hooks#subagentstart) 将此值作为 `agent_type` 接收。文件名不必匹配。名称不能包含 `:`，这是为 [plugin-scoped identifiers](/docs/zh-CN/plugins/overview) 保留的，例如 `my-plugin:reviewer`。Claude Code 不加载名称包含一个的文件，并向调试日志记录错误。在 v2.1.218 之前，这样的名称被接受 |313| `name` | 是 | 最多 256 个字符的唯一标识符，例如 `code-reviewer` 或 `reviewer-v2`。[Hook](/docs/zh-CN/hooks#subagentstart) 以 `agent_type` 的形式接收此值。文件名不必与之一致。名称不能包含 `:`，该字符保留用于[插件作用域标识符](/docs/zh-CN/plugins/overview)，例如 `my-plugin:reviewer` |

314| `description` | 是 | Claude 何时应该委托给此 subagent |314| `description` | 是 | Claude 何时应该委托给此 subagent |

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

348 348

349* **没有 `name`**：Claude Code 将文件视为保存在您的代理旁边的文档。349* **没有 `name`**：Claude Code 将文件视为保存在您的代理旁边的文档。

350* **一个开始 `---` 不是文件的第一行**：Claude Code 读取文件为没有 frontmatter，并将其视为文档。350* **一个开始 `---` 不是文件的第一行**：Claude Code 读取文件为没有 frontmatter，并将其视为文档。

351* **一个以 `-` 开头或包含 `:` 的 `name`**：Claude Code 跳过文件并向调试日志写入错误。请参阅上表中的 `name` 行。351* **`name` 以 `-` 开头、包含 `:` 或超过 256 个字符**：Claude Code 跳过该文件，并向调试日志写入一条错误。

352* **一个 `name` 但没有 `description`**：Claude Code 跳过文件并向调试日志写入原因。352* **一个 `name` 但没有 `description`**：Claude Code 跳过文件并向调试日志写入原因。

353* **不解析的 YAML**：Claude Code 从文件读取没有字段，跳过它，并向调试日志写入解析错误。353* **不解析的 YAML**：Claude Code 从文件读取没有字段，跳过它，并向调试日志写入解析错误。

354 354

vs-code.md +1 −1

Details

606| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。对于共享配置，请改用 Claude Code 设置。仅当值为绝对路径时，[`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 条目才会生效；扩展不会展开 `~`，并且会忽略相对路径值。 |606| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。对于共享配置，请改用 Claude Code 设置。仅当值为绝对路径时，[`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 条目才会生效；扩展不会展开 `~`，并且会忽略相对路径值。 |

609| `claudeProcessWrapper` | - | 用于启动 Claude 进程的可执行文件。当存在时，捆绑的二进制路径作为参数传递。如果扩展构建不包含您的平台的二进制文件，请将其设置为单独安装的 `claude` 二进制文件。在包装的设置中，对话以手动模式开始，除非您设置了 `initialPermissionMode` 或在之前的对话中选择了手动、自动编辑或自动，因为扩展会跳过那里的设置和内置默认步骤；请参阅[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)。激活时出现"不支持的平台"错误意味着您的平台没有捆绑的二进制文件；请参阅[哪些平台有预构建的二进制文件](/docs/zh-CN/troubleshoot-install#native-binary-not-found-after-npm-install)。 |609| `claudeProcessWrapper` | - | 用于启动 Claude 进程的可执行文件。当存在时，捆绑的二进制路径作为参数传递。如果扩展构建不包含您的平台的二进制文件，请将其设置为单独安装的 `claude` 二进制文件。 |

610 610

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 使用屏幕阅读器612 使用屏幕阅读器

worktrees.md +3 −1

Details

6 6

7> 在单独的 git worktrees 中隔离并行 Claude Code 会话，以便更改不会相互冲突。涵盖 `--worktree` 标志、子代理隔离、`.worktreeinclude`、清理和非 git VCS hooks。7> 在单独的 git worktrees 中隔离并行 Claude Code 会话，以便更改不会相互冲突。涵盖 `--worktree` 标志、子代理隔离、`.worktreeinclude`、清理和非 git VCS hooks。

8 8

9[git worktree](https://git-scm.com/docs/git-worktree) 是一个单独的工作目录，具有自己的文件和分支，但与主检出共享相同的存储库历史和远程。在自己的 worktree 中运行每个 Claude Code 会话意味着一个会话中的编辑永远不会触及另一个会话中的文件，因此一个会话可以构建功能，而第二个会话可以修复错误。9[git worktree](https://git-scm.com/docs/git-worktree) 是一个单独的工作目录，具有自己的文件和分支，但与主检出共享相同的仓库历史和远程。在各自的 worktree 中运行每个 Claude Code 会话，可以为其提供一份单独的文件副本用于编辑，因此一个会话可以构建功能，而第二个会话可以修复错误。

10 10

11<Note>11<Note>

12 Worktrees 需要 git 存储库；对于其他版本控制系统，请[配置 hooks 来替换 git 逻辑](#non-git-version-control)。在[桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions)中，启动会话时选择 **worktree** 选项，为其提供自己的 worktree。12 Worktrees 需要 git 存储库；对于其他版本控制系统，请[配置 hooks 来替换 git 逻辑](#non-git-version-control)。在[桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions)中，启动会话时选择 **worktree** 选项，为其提供自己的 worktree。

104* **Git 重定向**：Claude Code 阻止将 git 重定向到主检出的 Bash 或 Monitor 命令。重定向可以通过 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 变量，或在运行 git 之前 `cd` 到主检出来进行。104* **Git 重定向**：Claude Code 阻止将 git 重定向到主检出的 Bash 或 Monitor 命令。重定向可以通过 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 变量，或在运行 git 之前 `cd` 到主检出来进行。

105* **命令形状**：当 Claude Code 无法从命令文本验证命令运行的任何 git 保持在 worktree 内时，它会阻止 Bash 或 Monitor 命令。例如，当命令名称在运行时计算、语法无法解析，或当诸如 `${!name}` 或 `${ command; }` 之类的扩展可能运行文本中未明确说明的命令时，就会发生这种情况。Claude Code 告诉 Claude 如何重写被拒绝的命令，例如将其分割成普通的单独命令。您无法关闭此检查。105* **命令形状**：当 Claude Code 无法从命令文本验证命令运行的任何 git 保持在 worktree 内时，它会阻止 Bash 或 Monitor 命令。例如，当命令名称在运行时计算、语法无法解析，或当诸如 `${!name}` 或 `${ command; }` 之类的扩展可能运行文本中未明确说明的命令时，就会发生这种情况。Claude Code 告诉 Claude 如何重写被拒绝的命令，例如将其分割成普通的单独命令。您无法关闭此检查。

106 106

107这些检查读取编辑所针对的路径、命令运行所在的目录以及命令的文本。它们都不会跟踪 shell 命令写入了哪些文件，因此，在主检出中写入文件但并未在那里运行 git 的命令（例如 `cp` 或 shell 重定向）不会被这些检查拒绝。Claude Code 会像对待任何其他 shell 命令一样对待该命令，因此它是直接运行还是向您发出提示，取决于您的[权限模式](/docs/zh-CN/permission-modes)和规则。

108

107检查适用于您启动 Claude Code 的存储库。它们也涵盖链接的 worktree 链接自的主检出。对于 PowerShell 命令，Claude Code 仅应用工作目录检查。109检查适用于您启动 Claude Code 的存储库。它们也涵盖链接的 worktree 链接自的主检出。对于 PowerShell 命令，Claude Code 仅应用工作目录检查。

108 110

109Claude 将每个拒绝视为命名 worktree 并说明如何继续的工具错误。有关被拒绝的命令，请参阅[拒绝消息的含义以及如何清除它](/docs/zh-CN/errors#command-blocked-by-the-worktree-isolation-checks)。111Claude 将每个拒绝视为命名 worktree 并说明如何继续的工具错误。有关被拒绝的命令，请参阅[拒绝消息的含义以及如何清除它](/docs/zh-CN/errors#command-blocked-by-the-worktree-isolation-checks)。

Documentation 2026-10-06 23:59 UTC to 2026-10-07 16:59 UTC