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 +16 −9

Details

186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);

187});187});

188 188

189for await (const message of claimedQuery) {189try {

190 for await (const message of claimedQuery) {

190 console.log(message);191 console.log(message);

192 }

193} catch (error) {

194 // 声明被拒绝后，已声明的查询在产出错误结果后会抛出异常

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

191}196}

192```197```

193 198

718| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件中的条目如 `.mcp.json` 或 `~/.claude.json`，Claude Code 重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |723| `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) |724| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，名称解析方式与 `reconnectMcpServer()` 相同。禁用服务器会断开其连接并移除其工具。有关每种服务器所需的 Claude Code 版本，请参阅 [`toggleMcpServer()`](#togglemcpserver) |

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

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

844 849

845`options.cwd` 是必需的。声明也可以设置 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的标志设置覆盖、`appendSystemPrompt`、`title`、`agents` 和 `env` 中的每个会话令牌。850`options.cwd` 是必需的。声明也可以设置 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的标志设置覆盖、`appendSystemPrompt`、`title`、`agents` 和 `env` 中的每个会话令牌。

846 851

847Claude Code 可以拒绝声明，例如对于不存在的文件夹或其项目设置设置 `env`、`agent` 或 `model` 的文件夹。当 `claimed` 拒绝消息以 `option_not_applied` 开头时，会话运行时不带您请求的 `model` 或 `maxThinkingTokens`。在任何其他拒绝后，您的提示尚未运行，因此改为使用 `query()` 启动会话。852Claude Code 可能会拒绝认领，例如针对不存在的文件夹，或项目设置中设置了 `env`、`agent` 或 `model` 的文件夹。被拒绝后，`claim()` 已发送的提示词会得到一个文本以 `not_claimed` 开头的错误结果，随后返回的查询会抛出异常。请将查询的循环包裹在 try 块中，以便在抛出异常后继续执行。当 `claimed` 以 `option_not_applied` 开头的消息拒绝时，会话正在运行，但未使用您请求的 `model` 或 `maxThinkingTokens`。对于其他任何拒绝，您的提示词都尚未运行，因此请改用 `query()` 启动会话。

848 853

849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`

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

3788};3793};

3789```3794```

3790 3795

3791将代码审查发现报告为结构化列表，以便 Claude Code 可以呈现它们而不是将其打印为文本。`level` 是审查运行的工作量级别。发现按最严重优先排序，每次调用最多 32 个，当没有发现存活时数组为空。需要 Claude Code v2.1.196 或更高版本。3796将代码审查发现报告为结构化列表，以便 Claude Code 可以呈现它们而不是将其打印为文本。发现按最严重优先排序，每次调用最多 32 个，当没有发现保留下来时数组为空。需要 Claude Code v2.1.196 或更高版本。

3797

3798`level` 是可选的，包含 Claude 为该审查报告的 effort 级别。Claude Code 不会将其与审查实际运行时的级别进行比较，因此两者可能不同。

3792 3799

3793每个发现包含这些字段：3800每个发现包含这些字段：

3794 3801

4838};4845};

4839```4846```

4840 4847

4841返回报告的发现数、审查运行的工作量级别以及为结果正文回显的发现。需要 Claude Code v2.1.196 或更高版本。回显的 `short_summary` 字段需要 Claude Code v2.1.212 或更高版本。4848返回报告的发现数、Claude 传入的 `level` 值以及为结果正文回显的发现。需要 Claude Code v2.1.196 或更高版本。回显的 `short_summary` 字段需要 Claude Code v2.1.212 或更高版本。

4842 4849

4843<h3 id="artifact-2">4850<h3 id="artifact-2">

4844 Artifact4851 Artifact

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

5460```5467```

5461 5468

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

5463 5470

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

5465 `SpawnedProcess`5472 `SpawnedProcess`

5530 5537

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

5532 5539

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

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

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

5536 5543

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

authentication.md +1 −1

Details

12 登录 Claude Code12 登录 Claude Code

13</h2>13</h2>

14 14

15[安装 Claude Code](/docs/zh-CN/setup#install-claude-code) 后，在终端中运行 `claude`。首次启动时，Claude Code 会打开浏览器窗口供您登录。如果您已设置 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会跳过登录提示，改为要求您批准该密钥。15[安装 Claude Code](/docs/zh-CN/setup#install-claude-code) 后，在终端中运行 `claude`。首次启动时，Claude Code 会打开浏览器窗口供您登录。如果您已设置 `ANTHROPIC_API_KEY` 环境变量，并在 Claude Code 询问是否使用该密钥时批准了它，Claude Code 会跳过登录提示。

16 16

17如果浏览器没有自动打开，请按 `c` 将登录 URL 复制到剪贴板，然后将其粘贴到浏览器中。17如果浏览器没有自动打开，请按 `c` 将登录 URL 复制到剪贴板，然后将其粘贴到浏览器中。

18 18

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 +5 −3

Details

416* **隔离的虚拟机**：每个会话在隔离的、Anthropic 管理的 VM 中运行。你的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话改为在你自己的基础设施上运行，其中隔离是你的部署的责任416* **隔离的虚拟机**：每个会话在隔离的、Anthropic 管理的 VM 中运行。你的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话改为在你自己的基础设施上运行，其中隔离是你的部署的责任

417* <span id="default-allowed-domains" />**网络访问控制**：在 Anthropic 托管的环境中，网络访问默认受限，可以禁用。请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)了解访问级别、[默认允许的域](/docs/zh-CN/cloud-environments#default-allowed-domains)和不通过允许列表的流量。在自托管环境中，你在自己的网络边界处限制会话出口。当在禁用网络访问的情况下运行时，Claude Code 仍然可以与 Anthropic API 通信，这可能允许数据从 VM 中退出。417* <span id="default-allowed-domains" />**网络访问控制**：在 Anthropic 托管的环境中，网络访问默认受限，可以禁用。请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)了解访问级别、[默认允许的域](/docs/zh-CN/cloud-environments#default-allowed-domains)和不通过允许列表的流量。在自托管环境中，你在自己的网络边界处限制会话出口。当在禁用网络访问的情况下运行时，Claude Code 仍然可以与 Anthropic API 通信，这可能允许数据从 VM 中退出。

418* **凭证保护**：在 Anthropic 托管的环境中，git 凭证和签名密钥保持在沙箱外，代理使用作用域凭证代表会话进行身份验证。在自托管环境中，你的部署提供 git 凭证；请参阅[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)418* **凭证保护**：在 Anthropic 托管的环境中，git 凭证和签名密钥保持在沙箱外，代理使用作用域凭证代表会话进行身份验证。在自托管环境中，你的部署提供 git 凭证；请参阅[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)

419* **API 凭证**：在 Pro 和 Max 计划的 Anthropic 托管环境中，你[添加到云环境](/docs/zh-CN/cloud-environments#add-api-credentials)的密钥保持在沙箱外，以相同的方式，在它们离开会话后附加到匹配的请求。自托管环境没有 API 凭证，Team 和 Enterprise 计划还没有419* **网络密钥**：在 Pro 和 Max 计划的 Anthropic 托管环境中，您[添加到云环境](/docs/zh-CN/cloud-environments#add-api-credentials)的密钥以相同的方式保持在沙箱外，在请求离开会话后附加到匹配的请求。自托管环境没有网络密钥，Team 和 Enterprise 计划目前也还没有

420* **安全分析**：代码在会话的隔离环境内分析和修改，然后创建 PR420* **安全分析**：代码在会话的隔离环境内分析和修改，然后创建 PR

421 421

422<h2 id="troubleshooting">422<h2 id="troubleshooting">

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 +8 −8

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

164 icon: 'folder',164 icon: 'folder',

165 color: '#9B7BC4',165 color: '#9B7BC4',

166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',

167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],

169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],

170 docsLink: '/en/memory#organize-rules-with-claude/rules/',170 docsLink: '/en/memory#organize-rules-with-claude/rules/',

176 color: '#9B7BC4',176 color: '#9B7BC4',

177 badge: 'committed',177 badge: 'committed',

178 oneLiner: 'Test conventions scoped to test files',178 oneLiner: 'Test conventions scoped to test files',

179 when: <>Loaded when Claude reads a file matching the <C>paths:</C> globs below</>,179 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> globs below</>,

180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,

181 example: `---181 example: `---

182paths:182paths:

197 color: '#9B7BC4',197 color: '#9B7BC4',

198 badge: 'committed',198 badge: 'committed',

199 oneLiner: 'API conventions scoped to backend code',199 oneLiner: 'API conventions scoped to backend code',

200 when: <>Loaded when Claude reads a file matching the <C>paths:</C> glob below</>,200 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> glob below</>,

201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is editing API routes.</>,201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is working on API routes.</>,

202 example: `---202 example: `---

203paths:203paths:

204 - "src/api/**/*.ts"204 - "src/api/**/*.ts"

605 icon: 'folder',605 icon: 'folder',

606 color: '#9B7BC4',606 color: '#9B7BC4',

607 oneLiner: 'User-level rules that apply to every project',607 oneLiner: 'User-level rules that apply to every project',

608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',

610 docsLink: '/en/memory#organize-rules-with-claude/rules/',610 docsLink: '/en/memory#organize-rules-with-claude/rules/',

611 children: []611 children: []

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

claude-projects.md +45 −45

Details

57* **项目对话**：一个长期运行的会话，Claude 充当协调员。它接收您发送的内容，决定什么成为线程，并跟踪它启动的每个线程。它看到线程报告回来的内容，而不是它们采取的每一步。57* **项目对话**：一个长期运行的会话，Claude 充当协调员。它接收您发送的内容，决定什么成为线程，并跟踪它启动的每个线程。它看到线程报告回来的内容，而不是它们采取的每一步。

58* **线程**：工作者。每个都是一个单独的会话，有自己的上下文窗口，完成一项工作并在完成时报告回对话。云线程在自己的分支上工作，当工作需要时打开拉取请求。58* **线程**：工作者。每个都是一个单独的会话，有自己的上下文窗口，完成一项工作并在完成时报告回对话。云线程在自己的分支上工作，当工作需要时打开拉取请求。

59* **每个云线程开始时的内容**：59* **每个云线程开始时的内容**：

~~60 * 项目的代码库和文件，加上其[说明和记忆](#give-a-project-standing-context)~~60 * 项目的仓库和文件，加上其[说明和记忆](#give-a-project-standing-context)

~~61 * `CLAUDE.md` 和[项目每个代码库](#what-threads-pick-up-from-your-repositories)中的 skills，以及在有一个代码库的项目中，该代码库的权限规则和 hooks~~61 * `CLAUDE.md` 和[项目每个仓库](#what-threads-pick-up-from-your-repositories)中的 skill，以及在只有一个仓库的项目中，该仓库的权限规则和 hook

62 * 您 claude.ai 账户上的[连接器](#get-skills-plugins-connectors-and-tools-into-threads)62 * 您 claude.ai 账户上的[连接器](#get-skills-plugins-connectors-and-tools-into-threads)

~~63 * 一个[云环境](#choose-an-environment-for-threads)，设置其网络访问、环境变量、API 凭证和已安装的工具~~63 * 一个[云环境](#choose-an-environment-for-threads)，设置其网络访问、环境变量、网络密钥和已安装的工具

64* **Overview 窗格**：您在其中[一次看到所有线程](#see-what-needs-you-in-overview)以及哪些需要您。其他标签页是 **Library**（用于您添加的文件和线程生成的文件）、**Pull requests**（用于线程打开的文件）和 **Routines**（用于项目中的计划工作）。64* **Overview 窗格**：您在其中[一次看到所有线程](#see-what-needs-you-in-overview)以及哪些需要您。其他标签页是 **Library**（用于您添加的文件和线程生成的文件）、**Pull requests**（用于线程打开的文件）和 **Routines**（用于项目中的计划工作）。

65 65

66云线程不会从您自己机器上的 Claude Code 设置中获取任何内容。[将 skills、plugins、连接器和工具放入线程](#get-skills-plugins-connectors-and-tools-into-threads)涵盖了如何为它们提供它们可能缺少的内容。66云线程不会从您自己机器上的 Claude Code 设置中获取任何内容。[将 skills、plugins、连接器和工具放入线程](#get-skills-plugins-connectors-and-tools-into-threads)涵盖了如何为它们提供它们可能缺少的内容。

92 92

93* **计划**：您在 Pro 或 Max 上，**Projects** 显示在您的侧边栏中。93* **计划**：您在 Pro 或 Max 上，**Projects** 显示在您的侧边栏中。

94* **GitHub，如果项目将处理代码**：您的代码在 github.com 上而不是 GitHub Enterprise Server、GitLab 或 Bitbucket 上，您连接的 GitHub 账户对其有推送访问权限，Claude GitHub App 已安装在其上。如果您使用 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 连接了 GitHub，该令牌让您的其他云会话可以访问代码库，但对于项目线程来说还不够，项目线程需要 Claude GitHub App。[设置 GitHub 访问](#set-up-github-access)有相关步骤。94* **GitHub，如果项目将处理代码**：您的代码在 github.com 上而不是 GitHub Enterprise Server、GitLab 或 Bitbucket 上，您连接的 GitHub 账户对其有推送访问权限，Claude GitHub App 已安装在其上。如果您使用 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 连接了 GitHub，该令牌让您的其他云会话可以访问代码库，但对于项目线程来说还不够，项目线程需要 Claude GitHub App。[设置 GitHub 访问](#set-up-github-access)有相关步骤。

95* **网络、凭证和工具**：这些来自项目的[云环境](#choose-an-environment-for-threads)。默认环境已经可以访问[常见的包注册表](/docs/zh-CN/cloud-environments#default-allowed-domains)，因此仅在工作需要其他域、密钥或未预装的工具时检查此项。如果工作需要 MCP 服务器，检查它是否在您的 [claude.ai 连接器](https://claude.ai/customize/connectors)中显示为已连接。95* **网络、密钥和工具**：对于云端线程，这些来自项目的[云环境](#choose-an-environment-for-threads)。默认环境已经可以访问[常见的包注册表](/docs/zh-CN/cloud-environments#default-allowed-domains)，因此仅在工作需要其他域、密钥或未预装的工具时检查此项。如果工作需要 MCP 服务器，检查它是否在您的 [claude.ai 连接器](https://claude.ai/customize/connectors)中显示为已连接。

96 96

97<h3 id="start-a-new-project-from-scratch">97<h3 id="start-a-new-project-from-scratch">

98 从头开始启动新项目98 从头开始启动新项目

316 给项目提供常规上下文316 给项目提供常规上下文

317</h2>317</h2>

318 318

319项目记忆、项目说明和项目的代码库、文件和环境跨线程携带上下文。您设置每个一次。319项目记忆、项目说明以及项目的仓库、文件和环境会跨线程携带上下文。每一项您只需设置一次。

320 320

321| 上下文 | 它携带什么 | 您如何设置它 |321| 上下文 | 它携带什么 | 您如何设置它 |

322| :- | :- | :- |322| :- | :- | :- |

323| 项目记忆 | Claude 关于项目的笔记，例如要求、决定和陷阱，存储为文件。每个云线程在启动时读取索引文件 `MEMORY.md`，并在需要时打开其他文件 | 在项目对话或任何云线程中要求 Claude 记住要求、决定或陷阱，或忘记一个。在 **Project settings > Memory** 中读取、编辑和删除文件 |323| 项目记忆 | Claude 关于项目的笔记，例如要求、决定和陷阱，存储为文件。每个云线程在启动时读取索引文件 `MEMORY.md`，并在需要时打开其他文件 | 在项目对话或任何云线程中要求 Claude 记住要求、决定或陷阱，或忘记一个。在 **Project settings > Memory** 中读取、编辑和删除文件 |

325| 代码库、文件和环境 | 每个云线程克隆的代码库、每个线程可以在 `/mnt/project-files` 下读取的文件夹和文件，以及线程运行的云环境 | 代码库和环境在 **Project settings > Environment** 中，或在对话中要求 Claude 将代码库添加到项目。[文件和文件夹](#add-files-and-folders)来自 **Overview** 中 **Library** 标签页上的 **Add** |325| 仓库、文件和环境 | 每个云线程克隆的仓库、它可以在 `/mnt/project-files` 下读取的文件夹和文件，以及它运行的云环境 | 仓库和环境在 **Project settings > Environment** 中设置，或在对话中要求 Claude 将仓库添加到项目。[文件和文件夹](#add-files-and-folders)通过 **Overview** 中 **Library** 标签页上的 **Add** 添加 |

326 326

327**Project settings > Memory** 在 **Auto memory** 下列出这些文件，因为 Claude 在项目中工作时自己写入它们。它们与 Claude Code 在您机器上保留的[自动记忆](/docs/zh-CN/memory)分开，即使两者都使用 `MEMORY.md` 索引。项目记忆也与项目代码库中的 `CLAUDE.md` 文件分开。每个云线程在启动时仍然从其克隆中读取那些 `CLAUDE.md` 文件，因此将关于代码库的说明放在其 `CLAUDE.md` 中，将关于项目的笔记放在项目记忆中。327**Project settings > Memory** 在 **Auto memory** 下列出这些文件，因为 Claude 在项目中工作时自己写入它们。它们与 Claude Code 在您机器上保留的[自动记忆](/docs/zh-CN/memory)是分开的，即使两者都使用 `MEMORY.md` 索引。项目记忆也与项目仓库中的 `CLAUDE.md` 文件分开。每个云线程在启动时仍然从其克隆中读取那些 `CLAUDE.md` 文件，因此将关于仓库的说明放在其 `CLAUDE.md` 中，将关于项目的笔记放在项目记忆中。

328 328

329<h3 id="write-project-instructions">329<h3 id="write-project-instructions">

330 编写项目说明330 编写项目说明

331</h3>331</h3>

332 332

333项目说明是每个新线程开始的简报。点击项目标题中的齿轮图标打开 **Project settings**，然后转到 **Memory > Project instructions**。有用的简报涵盖：333项目说明是每个新线程开始时的简报。点击项目标题中的齿轮图标打开 **Project settings**，然后转到 **Memory > Project instructions**。有用的简报涵盖：

334 334

335* 项目的目的335* 项目的目的

336* 工作发生的地方：哪些代码库、从哪个分支开始、如何命名拉取请求336* 工作发生的地方：哪些仓库、从哪个分支开始、如何命名 Pull Request

337* 线程在调用完成之前如何检查自己的工作337* 线程在宣布完成之前如何检查自己的工作

338* 当它需要的东西缺失时该做什么338* 当它需要的东西缺失时该做什么

339* 什么需要您的批准339* 什么需要先获得您的批准

340 340

341例如：341例如：

342 342

343```text theme={null}343```text theme={null}

344此项目将支付 API 的 p95 延迟保持在 200 毫秒以下：分析、查询和缓存修复，以及随之而来的依赖升级，在 payments-api 代码库中。344This project holds p95 latency for the payments API under 200 ms: profiling, query and caching fixes, and the dependency upgrades that come with them, in the payments-api repository.

345 345

346- 从 main 分支并为每个线程打开一个草稿拉取请求。346- Branch from main and open one draft pull request per thread.

347- 在您调用工作完成之前，运行 `make test` 和 `make lint` 并在您的最终消息中粘贴摘要行。347- Before you call work done, run `make test` and `make lint` and paste the summary lines in your final message.

348- 如果您无法到达您需要的东西，例如代码库、密钥、API 或连接器，请在您的第一条消息中准确说出缺失的内容并停止。不要替代、模拟或猜测。348- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.

349- 不要在没有在线程中询问我的情况下合并、强制推送或更改 CI 配置。349- Don't merge, force-push, or change CI configuration without asking me in the thread.

350```350```

351 351

352关于一个代码库的规则，例如其构建命令，属于该代码库的 `CLAUDE.md`，每个云线程在代码库是项目的一部分时启动时读取。一旦工作进行中，当您纠正线程时，也告诉 Claude 记住纠正：它进入[项目记忆](#give-a-project-standing-context)，后续云线程从它开始。352关于某个仓库的规则，例如其构建命令，应放在该仓库的 `CLAUDE.md` 中；当该仓库属于项目时，每个云线程都会读取它。工作开始后，当您纠正某个线程时，也告诉 Claude 记住这个纠正：它会进入[项目记忆](#give-a-project-standing-context)，之后的云线程启动时就会带有它。

353 353

354<h3 id="decide-which-repositories-to-add">354<h3 id="decide-which-repositories-to-add">

355 决定要添加哪些代码库355 决定要添加哪些仓库

356</h3>356</h3>

357 357

358您添加到项目的代码库在每个云线程中都带有其中的所有内容、其代码、`CLAUDE.md` 和 skills。您不添加的代码库仍在范围内：当其任务需要时，云线程可以将一个添加到自己。大多数项目同时使用两者：358您添加到项目的仓库会连同其中的所有内容（代码、`CLAUDE.md` 和 skill）出现在每个云线程中。您未添加的仓库仍在可及范围内：当任务需要时，云线程可以将其添加到自身。大多数项目两者兼用：

359 359

360* **将其添加到项目**，在 **New project** 对话框中、**Project settings > Environment** 中，或通过在对话中要求 Claude 将其添加到项目。从那时起，每个云线程克隆它并从其 `CLAUDE.md` 和 skills 加载开始，无论任务是否涉及它。从一个代码库转到多个也改变了线程从每个代码库的 `.claude/settings.json` 中获取什么；请参阅[线程从您的代码库中获取什么](#what-threads-pick-up-from-your-repositories)。360* **将其添加到项目**，可在 **New project** 对话框中、**Project settings > Environment** 中，或在对话中要求 Claude 将其添加到项目。从那时起，每个云线程都会克隆它，并在启动时加载其 `CLAUDE.md` 和 skill，无论任务是否涉及它。从一个仓库增加到多个仓库也会改变线程从每个仓库的 `.claude/settings.json` 中获取的内容；请参阅[线程从您的仓库中获取什么](#what-threads-pick-up-from-your-repositories)。

361* **将其留下，让线程在需要时添加它。** 其任务需要项目没有的代码库的云线程可以将其添加到自己，线程中的注释说它仅被添加到此线程。克隆发生在任务的中途，因此该代码库的 `CLAUDE.md` 和 skills 在线程启动时不存在。下一个线程再次启动时没有它。线程添加的代码库需要与项目代码库相同的[先决条件](#check-the-prerequisites)：Claude GitHub App 安装在其上并从您的 GitHub 账户推送访问。361* **不添加，让线程在需要时自行添加。** 如果云线程的任务需要项目中没有的仓库，它可以将其添加到自身，线程中会有一条说明，表明该仓库仅被添加到此线程。克隆发生在任务中途，因此线程启动时该仓库的 `CLAUDE.md` 和 skill 并不存在。下一个线程启动时不会有它。以这种方式添加的仓库需要与项目仓库相同的[前提条件](#check-the-prerequisites)：在其上安装 Claude GitHub App，并且您的 GitHub 账户具有推送权限。

362 362

363项目根本不需要代码库。其云线程仍然可以研究、编写文档和在自己的沙箱中编写和运行代码，并将文件提交到 **Library** 标签页。那里的任何云线程也可以在任务需要时将代码库添加到自己。363项目完全可以不包含仓库。其云线程仍然可以进行研究、编写文档，以及在自己的沙箱中编写和运行代码，并将文件交付到 **Library** 标签页。当任务需要时，它的任何云线程仍然可以将仓库添加到自身。

364 364

365一旦项目有了代码库，Claude 只能从项目已经使用的 GitHub 所有者添加代码库，无论它是将一个添加到项目还是线程将一个添加到自己。要引入来自不同所有者的代码库，请自己在 **Project settings > Environment** 中将其添加到项目。365一旦项目有了仓库，无论是将仓库添加到项目还是线程将仓库添加到自身，Claude 都只能添加项目已使用的 GitHub 所有者下的仓库。要引入来自不同所有者的仓库，请自己在 **Project settings > Environment** 中将其添加到项目。

366 366

367对于跨越许多代码库的项目，例如一个具有服务器、网络、移动和桌面代码的功能，添加几乎每个任务涉及的一个或两个代码库，并在[项目说明](#write-project-instructions)中命名其他代码库，以便 Claude 知道其余代码在哪里。云线程然后启动小，仅为需要它们的任务拉入其他代码库。367对于跨越许多仓库的项目，例如一个包含服务器、Web、移动和桌面代码的功能，请添加几乎每个任务都会涉及的一两个仓库，并在[项目说明](#write-project-instructions)中列出其他仓库，以便 Claude 知道其余代码在哪里。这样云线程启动时规模较小，仅在需要时为相应任务拉入其他仓库。

368 368

369<h3 id="add-files-and-folders">369<h3 id="add-files-and-folders">

370 添加文件和文件夹370 添加文件和文件夹

371</h3>371</h3>

372 372

373在 **New project** 对话框的 **Context** 字段中添加您想要线程读取的文件和文件夹，或之后使用 **Overview** 中 **Library** 标签页上的 **Add**。以下限制适用于您添加的内容：373在 **New project** 对话框的 **Context** 字段中添加您希望线程读取的文件和文件夹，或之后使用 **Overview** 中 **Library** 标签页上的 **Add**。以下限制适用于您添加的内容：

374 374

375* **Library 标签页**：一次选择最多 100 个文件和 2 GB，单个文件最多 480 MB。375* **Library 标签页**：一次选择最多 100 个文件和 2 GB，单个文件最多 480 MB。

376* **New project 对话框**：超过 30 MB 的文件被跳过，因此在创建项目后从 **Library** 标签页添加较大的文件。376* **New project 对话框**：超过 30 MB 的文件会被跳过，因此请在创建项目后从 **Library** 标签页添加较大的文件。

377* **文件夹**：当您从任一位置添加文件夹时，项目接收其前 100 个文件的副本，最多 200 MB，不包括任何超过 30 MB 的文件、隐藏文件或 `node_modules`。项目最多可以容纳 10 个文件夹和 Google Drive 文件夹的组合，单个文件不计入该限制。377* **文件夹**：当您从任一位置添加文件夹时，项目会收到其前 100 个文件的副本，最多 200 MB，不包括任何超过 30 MB 的文件、隐藏文件或 `node_modules`。一个项目最多可容纳 10 个文件夹和 Google Drive 文件夹（合计），单个文件不计入该限制。

378* **上传后的更改**：上传是副本，因此您之后在计算机上所做的更改不会到达项目，直到您再次上传文件并在询问现有名称时选择 **Replace**。378* **上传后的更改**：上传的是副本，因此您之后在计算机上所做的更改不会同步到项目，直到您再次上传该文件并在询问现有名称时选择 **Replace**。

379 379

380<h3 id="what-threads-pick-up-from-your-repositories">380<h3 id="what-threads-pick-up-from-your-repositories">

381 线程从您的代码库中获取什么381 线程从您的仓库中获取什么

382</h3>382</h3>

383 383

384每个云线程克隆项目中的每个代码库并从所有代码库加载 `CLAUDE.md` 和 skills。权限规则、hooks 和 `env` 仅来自线程启动的目录中的 `.claude/settings.json`：在有一个代码库时在代码库内，在有多个时在克隆上方，其中没有代码库的文件被读取。384每个云线程会克隆项目中的每个仓库，并从所有仓库加载 `CLAUDE.md` 和 skill。权限规则、hook 和 `env` 仅来自线程启动目录中的 `.claude/settings.json`：当项目只有一个仓库时，该目录位于仓库内；当有多个仓库时，该目录位于各克隆的上层，此时不会读取任何仓库的该文件来获取这些内容。

385 385

387| :- | :- | :- |387| :- | :- | :- |

389| `.claude/` 下的 Skills、agents 和 commands | 加载 | 从每个代码库加载 |389| `.claude/` 下的 skill、Agent 和命令 | 加载 | 从每个仓库加载 |

391| 在 `.claude/settings.json` 中定义的权限规则、hooks 和 `env` | 适用于线程，除了[没有云会话遵守](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)的 `env` 键 | 不适用 |391| 在 `.claude/settings.json` 中定义的权限规则、hook 和 `env` | 适用于线程，但[任何云端会话都不遵循](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)的 `env` 键除外 | 不适用 |

392 392

393在有多个代码库的项目中，每个克隆作为[附加目录](/docs/zh-CN/memory#load-from-additional-directories)附加到线程，`CLAUDE.md` 加载打开，这就是为什么每个代码库的 `CLAUDE.md` 和 skills 在启动时加载，即使线程在它们上方启动。在这样的项目中，将常规规则放在项目说明中，并通过[云环境](#choose-an-environment-for-threads)为线程提供环境变量。393在有多个仓库的项目中，每个克隆都作为[附加目录](/docs/zh-CN/memory#load-from-additional-directories)附加到线程，并启用了 `CLAUDE.md` 加载，这就是为什么即使线程在它们的上层启动，每个仓库的 `CLAUDE.md` 和 skill 仍会在启动时加载。在这样的项目中，请将常规规则放在项目说明中，并通过[云环境](#choose-an-environment-for-threads)为线程提供环境变量。

394 394

395<h3 id="choose-an-environment-for-threads">395<h3 id="choose-an-environment-for-threads">

396 为线程选择环境396 为线程选择环境

397</h3>397</h3>

398 398

399每个新云线程在项目的[云环境](/docs/zh-CN/cloud-environments)中启动。环境设置线程可以到达哪些域、它们有哪些环境变量、哪些 API 凭证被添加到它们的请求中，以及设置脚本在 Claude 启动之前安装什么。云线程使用默认的 Anthropic 托管环境，直到您在 **Project settings > Environment** 中选择一个。399每个新云线程都在项目的[云环境](/docs/zh-CN/cloud-environments)中启动。环境决定线程可以访问哪些域、它们拥有哪些环境变量、哪些网络密钥会被添加到它们的请求中，以及设置脚本在 Claude 启动之前安装什么。在您于 **Project settings > Environment** 中选择环境之前，云线程使用默认的 Anthropic 托管环境。

400 400

401如果云线程需要到达内部 API 或私有包注册表，或需要您的机器通常持有的令牌，请更改环境而不是项目：请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)、[添加 API 凭证](/docs/zh-CN/cloud-environments#add-api-credentials)和[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。401如果云线程需要访问内部 API 或私有包注册表，或需要您的机器通常持有的令牌，请更改环境而不是项目：请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)、[添加网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)和[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。

402 402

403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

404 将 skills、plugins、connectors 和工具放入线程404 将 skill、插件、连接器和工具引入线程

405</h3>405</h3>

406 406

407云线程没有仅在您机器上安装的 skills、MCP 服务器、plugins 和工具。线程通过[远程控制](/docs/zh-CN/remote-control)在您的机器上运行 Claude 使用那里安装的内容。要使这些中的每一个对云线程可用：407云线程不具备仅安装在您机器上的 skill、MCP 服务器、插件和工具。Claude 通过 [Remote Control](/docs/zh-CN/remote-control) 在您机器上运行的线程会使用那里安装的内容。要让这些内容对云线程可用：

408 408

409* Skills、subagents 和 commands：将它们提交到您添加到项目的代码库，例如 `.claude/skills/<skill-name>/SKILL.md` 处的 skill。每个云线程克隆项目中的每个代码库并从每个代码库加载 `.claude/skills/`、`.claude/agents/` 和 `.claude/commands/`，因此提交到一个代码库的 skill 在每个云线程中可用。云线程也加载您为 claude.ai 账户启用的 skills。409* skill、子代理和命令：将它们提交到您已添加到项目的仓库，例如位于 `.claude/skills/<skill-name>/SKILL.md` 的 skill。每个云线程会克隆项目中的每个仓库，并从每个仓库加载 `.claude/skills/`、`.claude/agents/` 和 `.claude/commands/`，因此提交到一个仓库的 skill 在每个云线程中都可用。云线程还会加载您为 claude.ai 账户启用的 skill。

410* Plugins：在 **Project settings > Plugins** 中添加它们；它们加载到每个新云线程中。代码库在其 `.claude/settings.json` 中声明的 Plugins [不在云线程中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。410* 插件：在 **Project settings > Plugins** 中添加它们；它们会加载到每个新云线程中。仓库在其 `.claude/settings.json` 中声明的插件[不会在云线程中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

411* MCP 服务器：云线程从您 claude.ai 账户上的连接器获取其 MCP 工具，这些是您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 一次连接的 MCP 服务器，或通过 **Project settings > Environment** 中的 **Manage connectors** 链接。每个云线程可以使用所有这些而无需每个项目的设置。项目对话本身没有连接器，因此将需要一个的工作作为云线程的任务发送。在有一个代码库的项目中，云线程也从该代码库的[`.mcp.json`](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)加载 MCP 服务器。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)列出了云会话的规则和关闭连接器的设置。411* MCP 服务器：云线程从您 claude.ai 账户上的连接器获取 MCP 工具，这些连接器是您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 或通过 **Project settings > Environment** 中的 **Manage connectors** 链接一次性连接的 MCP 服务器。每个云线程都可以使用所有这些连接器，无需按项目设置。项目对话本身没有连接器，因此请将需要连接器的工作作为任务发送给云线程。在只有一个仓库的项目中，云线程还会从该仓库的 [`.mcp.json`](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup) 加载 MCP 服务器。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code) 列出了云端会话的规则以及关闭连接器的设置。

412* 命令行工具和包：在环境的[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)中安装它们。412* 命令行工具和包：在环境的[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)中安装它们。

413 413

414要查看运行云线程在 claude.ai/code 有哪些连接器，请打开线程并从其消息框旁的 **+** 菜单中选择 **Connectors**。在那里关闭连接器会将其从该线程中移除，并且将其保存为您的账户默认值，因此新线程和 claude.ai 聊天在您重新打开它之前启动时没有它。云线程在您向其发送下一条消息后获取您添加或重新连接的连接器。414要在 claude.ai/code 查看正在运行的云线程拥有哪些连接器，请打开该线程，并从其消息框旁的 **+** 菜单中选择 **Connectors**。在那里关闭某个连接器会将其从该线程中移除，并将此保存为您的账户默认值，因此在您重新打开它之前，新线程和 claude.ai 聊天启动时都不会带有它。在您向云线程发送下一条消息后，它才会获取您新添加或重新连接的连接器。

415 415

416<h2 id="project-settings-reference">416<h2 id="project-settings-reference">

417 项目设置参考417 项目设置参考

590</h2>590</h2>

591 591

592* [在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)：每个云线程背后的云会话如何工作，包括 GitHub 访问选项和拉取请求上的自动修复592* [在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)：每个云线程背后的云会话如何工作，包括 GitHub 访问选项和拉取请求上的自动修复

593* [配置云环境](/docs/zh-CN/cloud-environments)：更改云线程可以在网络上到达什么，为它们提供环境变量和 API 凭证，并使用设置脚本安装工具593* [配置云环境](/docs/zh-CN/cloud-environments)：更改云线程可以在网络上到达什么，为它们提供环境变量和网络密钥，并使用设置脚本安装工具

594* [使用例程自动化工作](/docs/zh-CN/routines)：例程的时间表、触发器和管理，包括 Claude 从项目创建的那些594* [使用例程自动化工作](/docs/zh-CN/routines)：例程的时间表、触发器和管理，包括 Claude 从项目创建的那些

595* [使用代理视图管理多个代理](/docs/zh-CN/agent-view)：当工作需要仅您的机器可以到达的工具或服务时，在您自己的机器上运行和跟踪多个会话595* [使用代理视图管理多个代理](/docs/zh-CN/agent-view)：当工作需要仅您的机器可以到达的工具或服务时，在您自己的机器上运行和跟踪多个会话

596* [Projects redesigned: from folder to conversation](https://claude.com/blog/projects-redesigned)：发布公告，带有使项目成为与 Claude 对话的思考596* [Projects redesigned: from folder to conversation](https://claude.com/blog/projects-redesigned)：发布公告，带有使项目成为与 Claude 对话的思考

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

cloud-environments.md +89 −71

Details

10 云环境适用于[云会话](/docs/zh-CN/claude-code-on-the-web)，这些会话在 Pro、Max 和 Team 计划上可用，以及具有[高级席位或 Chat + Claude Code 席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)的 Enterprise 用户。10 云环境适用于[云会话](/docs/zh-CN/claude-code-on-the-web)，这些会话在 Pro、Max 和 Team 计划上可用，以及具有[高级席位或 Chat + Claude Code 席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)的 Enterprise 用户。

11</Note>11</Note>

12 12

13每个[云会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用的[API 凭证](#add-api-credentials)而不会看到它们，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。13每个[云端会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用但无法看到的[网络密钥](#add-api-credentials)，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。

14 14

15相同的环境适用于您启动云会话的任何地方：[Desktop 应用](/docs/zh-CN/desktop)、[Claude 移动应用](/docs/zh-CN/mobile)、浏览器中的 [claude.ai/code](https://claude.ai/code)、终端中搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)、[例程](/docs/zh-CN/routines)和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。这些界面中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。15相同的环境适用于您启动云会话的任何地方：[Desktop 应用](/docs/zh-CN/desktop)、[Claude 移动应用](/docs/zh-CN/mobile)、浏览器中的 [claude.ai/code](https://claude.ai/code)、终端中搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)、[例程](/docs/zh-CN/routines)和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。这些界面中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。

16 16

58 <Step title="添加或编辑环境">58 <Step title="添加或编辑环境">

59 选择**Cloud**来列出你的环境。然后选择**Add cloud environment**，或悬停在现有环境上并选择右侧出现的设置图标。59 选择**Cloud**来列出你的环境。然后选择**Add cloud environment**，或悬停在现有环境上并选择右侧出现的设置图标。

60 60

~~61 对话框包括名称、网络访问级别、环境变量和设置脚本。当你在Pro或Max计划上编辑现有的云环境时，对话框还包括[API凭证](#add-api-credentials)。~~61 对话框包括名称、网络访问级别、环境变量和设置脚本。当您在 Pro 或 Max 计划上编辑现有的云环境时，对话框还包括[网络机密](#add-api-credentials)。

62 62

63 <Frame>63 <Frame>

64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment对话框。一个Name字段，占位符为Default，一个Network access选择器设置为Trusted，带有网络策略和访问级别的链接，一个Environment variables框显示.env格式占位符文本，并注明值对使用该环境的任何人都可见，一个Setup script框描述为在新会话启动时运行的Bash脚本，在Claude Code启动之前，以及Cancel和Create environment按钮。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment对话框。一个Name字段，占位符为Default，一个Network access选择器设置为Trusted，带有网络策略和访问级别的链接，一个Environment variables框显示.env格式占位符文本，并注明值对使用该环境的任何人都可见，一个Setup script框描述为在新会话启动时运行的Bash脚本，在Claude Code启动之前，以及Cancel和Create environment按钮。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

91 91

92云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。92云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。

93 93

94使用该环境的任何人都可以读取这些值。在Pro和Max计划上，对于代理可以附加到请求的键，请改用[API凭证](#add-api-credentials)。[从不获得凭证的请求](#requests-that-never-get-the-credential)在那里列出。94使用该环境的任何人都可以读取这些值。在 Pro 和 Max 计划上，对于 Agent 代理可以附加到请求中的密钥，请改用[网络机密](#add-api-credentials)。[永远不会获得机密的请求](#requests-that-never-get-the-credential)在该处列出。

95 95

96<h3 id="add-api-credentials">96<h3 id="add-api-credentials">

~~97 添加API凭证~~97 添加网络机密

98</h3>98</h3>

99 99

100API凭证是你存储在云环境上的API密钥或令牌，这样Claude可以从环境中的任何会话调用该API，而无需看到密钥。Anthropic的代理在每个请求离开会话的VM后，将密钥添加到你列出的主机的请求中。密钥永远不会到达Claude、它运行的命令或会话的环境变量。100网络机密是您存储在云环境中的 API 密钥或令牌，使 Claude 可以从该环境中的任何会话调用该 API，而无需看到密钥。每个请求离开会话的 VM 后，Anthropic 的 Agent 代理会将密钥添加到发往您所列主机的请求中。密钥永远不会到达 Claude、它运行的命令或会话的环境变量。

101 101

102API凭证在Pro和Max计划上可用。它们在Team和Enterprise计划上还不可用，所以**API credentials**部分不会出现在这些计划的环境对话框中。102网络机密适用于 Pro 和 Max 计划。它们目前尚不适用于 Team 或 Enterprise 计划，因此在这些计划上，环境对话框中不会出现 **Network secrets** 部分。

103 103

104<h4 id="requirements">104<h4 id="requirements">

105 要求105 要求

106</h4>106</h4>

107 107

108其中两个决定你是否可以添加凭证，两个决定代理在添加后是否可以使用它：108其中两项决定您是否可以添加机密，另外两项决定添加后 Agent 代理是否可以使用它：

109 109

110* **Role**：你的claude.ai组织中的组织管理员角色110* **Role**：你的claude.ai组织中的组织管理员角色

111 * 在Team和Enterprise上，所有者持有它，管理员没有111 * 在Team和Enterprise上，所有者持有它，管理员没有

112 * 在Pro和Max上，你在自己的组织中持有它112 * 在Pro和Max上，你在自己的组织中持有它

113* **Environment type**：一个已经存在的Anthropic托管的云环境。[自托管环境](/docs/zh-CN/self-hosted-environments)没有API凭证113* **Environment type**：一个已存在的 Anthropic 托管云环境。[自托管环境](/docs/zh-CN/self-hosted-environments)没有网络机密

114* **API reachability**：API接受来自互联网的连接，因为请求来自Anthropic的网络114* **API reachability**：API接受来自互联网的连接，因为请求来自Anthropic的网络

115* **Encryption keys**：如果你的组织使用客户管理的加密密钥，你无法保存凭证115* **Encryption keys**：如果您的组织使用客户管理的加密密钥，则无法保存网络机密

116 116

117<h4 id="add-a-credential">117<h4 id="add-a-credential">

118 添加凭证118 添加机密

119</h4>119</h4>

120 120

121凭据需要逐个添加，添加后无法编辑。要更改凭据的主机或值，请将其删除后重新添加。121机密需要逐个添加，添加后无法编辑。要更改机密的主机或值，请将其删除后重新添加。

122 122

123<Steps>123<Steps>

124 <Step title="打开环境的 API 凭据">124 <Step title="打开环境的网络机密">

125 在 [claude.ai/code](https://claude.ai/code) [打开环境进行编辑](#configure-your-environment)。在 **Edit environment** 对话框中，找到 **API credentials** 部分。您会看到环境上已有的凭据，每个凭据都附有其适用的主机。125 在 [claude.ai/code](https://claude.ai/code) [打开环境进行编辑](#configure-your-environment)。在 **Edit environment** 对话框中，找到 **Network secrets** 部分。您会看到环境中已有的机密，每个机密都附有其适用的主机。

126 </Step>126 </Step>

127 127

128 <Step title="添加凭据">128 <Step title="添加机密">

129 选择 **Add credential** 并填写表单。对于在请求头中传输的 API 密钥，保留默认的 **Credential type**，即 **Bearer**，并填写以下字段：129 选择 **Add secret** 并填写表单。对于在请求头中传输的 API 密钥，保留默认的 **Credential type**，即 **Bearer**，并填写以下字段：

130 130

131 * **Name**：凭证的标签，例如`Internal billing API`131 * **Name**：机密的标签，例如 `Internal billing API`

132 * **Allowed websites**：API的主机，例如`api.example.com`。前导`*.`匹配每个子域132 * **Allowed websites**：API 的主机，例如 `api.example.com`。前导 `*.` 匹配所有子域

133 * **Custom headers**：一行用于携带密钥的头。该行以`Authorization`作为头的**Name**和`Bearer`作为其**Prefix**开始；将密钥本身粘贴为**Value**。对于采用裸值的头（如`X-Api-Key`），更改名称并清除前缀133 * **Custom headers**：用于携带密钥的请求头占一行。该行默认以 `Authorization` 作为请求头的 **Name**，以 `Bearer` 作为其 **Prefix**；将密钥本身粘贴为 **Value**。对于接受裸值的请求头（如 `X-Api-Key`），请更改名称并清除前缀

134 134

135 对于以其他方式进行身份验证的API，选择不同的**Credential type**。该列表与[Claude Tag](https://claude.com/docs/claude-tag/overview)（Team和Enterprise计划的Slack集成）为[connections](https://claude.com/docs/claude-tag/admins/add-connections)提供的列表相同。135 对于以其他方式进行身份验证的 API，请选择不同的 **Credential type**。该列表与 [Claude Tag](https://claude.com/docs/claude-tag/overview)（适用于 Team 和 Enterprise 计划的 Slack 集成）为 [connections](https://claude.com/docs/claude-tag/admins/add-connections) 提供的列表相同。

136 </Step>136 </Step>

137 137

138 <Step title="保存凭证">138 <Step title="保存机密">

139 选择**Connect**。凭证出现在列表中，带有其主机，保存时不需要对话框的**Save changes**按钮。保存后你无法再次查看该值。139 选择 **Connect**。机密会连同其主机一起出现在列表中，无需点击对话框的 **Save changes** 按钮即已保存。保存后您无法再次查看该值。

140 </Step>140 </Step>

141</Steps>141</Steps>

142 142

143要确认凭证有效，请在环境中启动会话并要求Claude调用API，例如使用`curl`。API的响应就像密钥在请求中一样，密钥不会出现在会话的环境变量或任何文件中。如果列表将凭证标记为**Not sent**，其下方的注释会说明原因和解决方法。两个主机重叠但不完全匹配的凭证不会获得标记，代理只会发送其中一个。143要确认机密是否有效，请在该环境中启动会话并让 Claude 调用 API，例如使用 `curl`。API 的响应就如同请求中带有密钥一样，而密钥不会出现在会话的环境变量或任何文件中。如果列表将某个机密标记为 **Not sent**，其下方的说明会解释原因和处理方法。两个主机重叠但不完全匹配的机密不会显示标记，而 Agent 代理只会发送其中一个。

144 144

145<h4 id="which-requests-get-the-credential">145<h4 id="which-requests-get-the-credential">

146 哪些请求获得凭证146 哪些请求会获得机密

147</h4>147</h4>

148 148

149当请求的主机与你在该凭证上列出的主机匹配时，代理会将凭证附加到请求。会话可以到达这些主机，即使环境的[网络访问级别](#access-levels)不允许，除了[从不获得凭证的主机](#requests-that-never-get-the-credential)。凭证适用于在环境中运行的每个会话，无论谁启动它，直到你删除它。149当请求的主机与您在某个机密上列出的主机匹配时，Agent 代理会将该机密附加到请求中。即使环境的[网络访问级别](#access-levels)原本不允许访问这些主机，会话也可以访问它们，但[永远不会获得机密的主机](#requests-that-never-get-the-credential)除外。机密适用于在该环境中运行的每个会话，无论由谁启动，直到您将其删除。

150 150

151<h4 id="requests-that-never-get-the-credential">151<h4 id="requests-that-never-get-the-credential">

152 从不获得凭证的请求152 永远不会获得机密的请求

153</h4>153</h4>

154 154

155代理永远不会将你添加的凭证附加到这些请求：155Agent 代理永远不会将您添加的机密附加到以下请求：

156 156

157* **GitHub**：[GitHub代理](#github-proxy)改为对GitHub的请求进行身份验证，所以你不需要为它提供API凭证157* **GitHub**：[GitHub 代理](#github-proxy)会代为对发往 GitHub 的请求进行身份验证，因此您无需为其设置网络机密

158* **Anthropic API和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io`和`proxy.golang.org`158* **Anthropic API和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io`和`proxy.golang.org`

159* **Setup script请求**：Claude Code在启动时连接到代理，在[setup script](#setup-scripts)运行后159* **Setup script请求**：Claude Code在启动时连接到代理，在[setup script](#setup-scripts)运行后

160* **Claude Code的遥测导出**：Claude Code自己发送其[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是通过它运行的命令，该请求不会通过代理160* **Claude Code的遥测导出**：Claude Code自己发送其[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是通过它运行的命令，该请求不会通过代理

179 179

180* 已经在环境中运行的会话继续工作。180* 已经在环境中运行的会话继续工作。

181* 环境从选择器和`/remote-env`中消失，所以你无法为新会话选择它。181* 环境从选择器和`/remote-env`中消失，所以你无法为新会话选择它。

182* 环境上的API凭证在其运行的会话中保持附加。删除你不再需要的任何凭证，然后再归档。182* 环境中的网络机密在其正在运行的会话中仍保持附加状态。请在归档前删除不再需要的机密。

183* 没有新会话可以在任何表面上的归档环境中启动。如果该环境是你保存的[CLI默认值](#select-an-environment-from-the-cli)，当你的列表有一个时，Claude Code会在Anthropic托管的环境中启动CLI云会话，否则在你列表中不是[Remote Control bridge环境](#the-default-environment)的第一个环境中启动。任何显式配置了该环境的东西，例如[routine](/docs/zh-CN/routines#environments-and-network-access)，无法在其中启动新会话。将其指向另一个环境。183* 没有新会话可以在任何表面上的归档环境中启动。如果该环境是你保存的[CLI默认值](#select-an-environment-from-the-cli)，当你的列表有一个时，Claude Code会在Anthropic托管的环境中启动CLI云会话，否则在你列表中不是[Remote Control bridge环境](#the-default-environment)的第一个环境中启动。任何显式配置了该环境的东西，例如[routine](/docs/zh-CN/routines#environments-and-network-access)，无法在其中启动新会话。将其指向另一个环境。

184 184

185<h3 id="organization-shared-environments">185<h3 id="organization-shared-environments">

197 197

198所有者在[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)单独选择组织的[默认环境](#the-default-environment)。198所有者在[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)单独选择组织的[默认环境](#the-default-environment)。

199 199

200每个成员在共享环境中的会话都读取其变量，所以不要在其中包含秘密。[API凭证](#add-api-credentials)给予会话一个它们无法读取的密钥，在Team或Enterprise计划上还不可用。200每个成员在共享环境中的会话都会读取其变量，因此请勿在其中包含机密信息。[网络机密](#add-api-credentials)可以为会话提供其无法读取的密钥，但目前尚不适用于 Team 或 Enterprise 计划。

201 201

202<h3 id="set-the-environment-a-claude-tag-channel-uses">202<h3 id="set-the-environment-a-claude-tag-channel-uses">

203 设置Claude Tag频道使用的环境203 设置Claude Tag频道使用的环境

239 239

240* GitHub，通过其[单独的代理](#github-proxy)240* GitHub，通过其[单独的代理](#github-proxy)

241* 您启用的 [MCP 连接器](#network-access)，其流量通过 Anthropic 的服务器传输241* 您启用的 [MCP 连接器](#network-access)，其流量通过 Anthropic 的服务器传输

242* 您在环境的 [API 凭证](#add-api-credentials)上列出的主机，除了[代理跳过的主机](#requests-that-never-get-the-credential)242* 您在环境的[网络密钥](#add-api-credentials)上列出的主机，除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)

243* Anthropic API，用于 Claude Code 自己的请求，即使在 **None** 下也是如此，如[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下所述243* Anthropic API，用于 Claude Code 自己的请求，即使在 **None** 下也是如此，如[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下所述

244 244

245<h3 id="allow-specific-domains">245<h3 id="allow-specific-domains">

254registry.example.com254registry.example.com

255```255```

256 256

257此环境中的会话现在可以访问 `api.example.com`、`internal.example.com` 的任何子域和 `registry.example.com`，但无法通过会话的网络访问其他域。[GitHub 流量](#github-proxy)、[MCP 连接器流量](#network-access)和对环境 [API 凭证](#add-api-credentials)的主机的请求（除了[代理跳过的主机](#requests-that-never-get-the-credential)）不经过此允许列表。前导 `*.` 匹配每个子域。要同时保留 [Trusted 域](#default-allowed-domains)，请勾选 **Also include default list of common package managers**；不勾选则只允许您列出的内容。257此环境中的会话现在可以访问 `api.example.com`、`internal.example.com` 的任何子域和 `registry.example.com`，但无法通过会话的网络访问其他域。[GitHub 流量](#github-proxy)、[MCP 连接器流量](#network-access)和对环境[网络密钥](#add-api-credentials)的主机的请求（除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)）不经过此允许列表。前导 `*.` 匹配每个子域。要同时保留 [Trusted 域](#default-allowed-domains)，请勾选 **Also include default list of common package managers**；不勾选则只允许您列出的内容。

258 258

259如果您的组织使用[工件](/docs/zh-CN/artifacts#availability)，会话读取工件时不需要在列表中包含 `*.frame.claudeusercontent.com`。当列表中没有该主机时，Claude Code 通过会话与 Anthropic 的连接读取工件内容。在两种情况下保留允许列表中的主机：259如果您的组织使用[工件](/docs/zh-CN/artifacts#availability)，会话读取工件时不需要在列表中包含 `*.frame.claudeusercontent.com`。当列表中没有该主机时，Claude Code 通过会话与 Anthropic 的连接读取工件内容。在两种情况下保留允许列表中的主机：

260 260

289* 所请求主机名的 DNS 级审计踪迹289* 所请求主机名的 DNS 级审计踪迹

290 290

291<h2 id="what’s-available-in-cloud-sessions">291<h2 id="what’s-available-in-cloud-sessions">

292 云会话中可用的内容292 云端会话中可用的内容

293</h2>293</h2>

294 294

295在 Anthropic 托管的环境中，每个会话都会获得一台运行 Ubuntu 24.04 的全新虚拟机 (VM)（x86\_64 架构），无论您自己的操作系统和 CPU 架构是什么，您的存储库已克隆，常见的工具链已预安装。当依赖项提供预编译的二进制文件（例如具有本机扩展的 Ruby gem 或预构建的 Python wheel）时，请使用其 x86\_64 Linux 构建以匹配 VM。本节涵盖 Anthropic 托管的默认值、内置 GitHub 工具、如何[运行测试和服务](#run-tests-start-services-and-add-packages)、每台 VM 获得的[资源限制](#resource-limits)，以及[时间限制](#time-limits)对长时间运行的工作的限制。295在 Anthropic 托管的环境中，每个会话都会获得一台运行 Ubuntu 24.04 的全新虚拟机 (VM)（x86\_64 架构），无论您自己的操作系统和 CPU 架构是什么，您的仓库已克隆，常见的工具链已预安装。当依赖提供预编译的二进制文件（例如具有本机扩展的 Ruby gem 或预构建的 Python wheel）时，请使用其 x86\_64 Linux 构建版本以匹配 VM。本节涵盖 Anthropic 托管的默认值、内置 GitHub 工具、如何[运行测试和服务](#run-tests-start-services-and-add-packages)、每台 VM 获得的[资源限制](#resource-limits)，以及长时间运行的工作的[时间限制](#time-limits)。

296 296

297<Note>297<Note>

298 您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的运行器上运行，使用您的运行器镜像提供的工具。298 您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的运行器上运行，使用您的运行器镜像提供的工具。

302 您的设置中会保留的内容302 您的设置中会保留的内容

303</h3>303</h3>

304 304

305云会话从您存储库的全新克隆开始。您提交到存储库的任何内容都可用。您只在自己机器上安装或配置的任何内容在会话中都不可用。您组织的策略通过[服务器管理的设置](/docs/zh-CN/server-managed-settings)单独到达。305云端会话从您仓库的全新克隆开始。您提交到仓库的任何内容都可用。您只在自己机器上安装或配置的任何内容在会话中都不可用。您组织的策略通过[服务器托管设置](/docs/zh-CN/server-managed-settings)单独到达。

306 306

307| | 在云会话中可用 | 原因 |307| | 在云端会话中可用 | 原因 |

308| :- | :- | :- |308| :- | :- | :- |

309| 您的存储库的 `CLAUDE.md` | 是 | 克隆的一部分 |309| 您的仓库的 `CLAUDE.md` | 是 | 克隆的一部分 |

310| 您的存储库的 `.claude/settings.json` hooks 和权限规则 | 是，在具有一个存储库的会话中 | 克隆的一部分。具有多个存储库的会话（包括[项目](/docs/zh-CN/claude-projects#what-threads-pick-up-from-your-repositories)线程）在克隆上方启动，不读取它们 |310| 您的仓库的 `.claude/settings.json` hook 和权限规则 | 是，在具有一个仓库的会话中 | 克隆的一部分。具有多个仓库的会话（包括[项目](/docs/zh-CN/claude-projects#what-threads-pick-up-from-your-repositories)线程）在克隆上方启动，不读取它们 |

312| 您的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |312| 您的仓库的 `.claude/rules/` | 是 | 克隆的一部分 |

313| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |313| 您的仓库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |

314| 在您的存储库的 `.claude/settings.json` 中声明的 plugins 和 marketplaces | 否 | 云会话不会安装存储库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的 plugins，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的 marketplaces 的 plugins |314| 在您的仓库的 `.claude/settings.json` 中声明的插件和市场 | 否 | 云端会话不会安装仓库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的插件，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的市场的插件 |

315| 您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings) | 是，除了在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话中 | 在会话启动时从 Anthropic 的服务器获取。请参阅 [Surface coverage](/docs/zh-CN/model-config#surface-coverage) 了解 `availableModels` 在云会话中如何强制执行。通过 MDM 或管理配置文件部署到您设备的设置不适用，因为会话在 Anthropic 管理的 VM 上运行；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，会话也会读取运行器镜像中的管理设置文件，根据 [Claude Code 如何组合管理来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) |315| 您组织的[服务器托管设置](/docs/zh-CN/server-managed-settings) | 是，除了在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话中 | 在会话启动时从 Anthropic 的服务器获取。请参阅[使用入口覆盖范围](/docs/zh-CN/model-config#surface-coverage)了解 `availableModels` 在云端会话中如何强制执行。通过 MDM 或托管设置文件部署到您设备的设置不适用，因为会话在 Anthropic 管理的 VM 上运行；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，会话也会读取运行器镜像中的托管设置文件，根据 [Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) |

316| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在存储库中 |316| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在仓库中。请参阅[添加个人偏好而无需提交到仓库](#add-personal-preferences-without-committing-to-the-repo) |

317| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在存储库中。请改为将它们提交到存储库的 `.claude/` 目录。云会话会自动加载您在 claude.ai 上启用的技能 |317| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在仓库中。请改为将它们提交到仓库的 `.claude/` 目录。云端会话会自动加载您在 claude.ai 上启用的 skill |

318| 仅在您的用户设置中启用的 plugins | 否 | 用户范围的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |318| 仅在您的用户设置中启用的插件 | 否 | 用户作用域的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |

319| 您使用 `claude mcp add` 在默认本地范围或用户范围添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是存储库。请使用 `claude mcp add --scope project` 添加服务器，它会写入存储库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个存储库的会话会加载它 |319| 您使用 `claude mcp add` 在默认本地作用域或用户作用域添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是仓库。请使用 `claude mcp add --scope project` 添加服务器，它会写入仓库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个仓库的会话会加载它 |

320| 您的存储库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |320| 您的仓库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |

321| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为 [API 凭证](#add-api-credentials) | 您在环境中添加一次密钥，代理会将其附加到您列出的主机的请求。代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |321| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为[网络密钥](#add-api-credentials) | 您在环境中添加一次密钥，Agent 代理会将其附加到发往您列出的主机的请求。Agent 代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |

322| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云会话中执行 |322| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云端会话中执行 |

~~323~~ 323

324要在云会话中提供您自己的配置，请将其提交到存储库。324要在云端会话中提供您自己的配置，请将其提交到仓库。

~~325~~ 325

326任何使用环境的人都可以读取其环境变量和设置脚本。对话框在**环境变量**下的注释说明了这一点，并警告不要在那里放置密钥。在 Pro 和 Max 计划中，存储代理可以附加的密钥作为 [API 凭证](#add-api-credentials)。326任何使用环境的人都可以读取其环境变量和设置脚本。对话框在**环境变量**下的注释说明了这一点，并警告不要在那里放置密钥。在 Pro 和 Max 计划中，请改为将 Agent 代理可以附加的密钥存储为[网络密钥](#add-api-credentials)。

327

328<h4 id="add-personal-preferences-without-committing-to-the-repo">

329 添加个人偏好而无需提交到仓库

330</h4>

331

332在 Anthropic 托管的环境中，对于您不希望放入共享仓库的偏好，请添加一个写入 `~/.claude/CLAUDE.md` 的[设置脚本](#setup-scripts)。Claude Code 会在会话中将该文件作为[用户指令](/docs/zh-CN/memory#choose-where-to-put-claude-md-files)加载。以下示例设置了一项提交信息偏好：

333

334```bash theme={null}

335#!/bin/bash

336mkdir -p ~/.claude

337cat > ~/.claude/CLAUDE.md <<'EOF'

338Use conventional commit messages.

339EOF

340```

341

342请将该脚本放在您自己的某个环境上，而不是[共享环境](#organization-shared-environments)上。

343

344在下一个云端会话中运行 `/context`，并确认 `/root/.claude/CLAUDE.md` 出现在 **Memory files** 下。

327 345

328<h3 id="installed-tools">346<h3 id="installed-tools">

329 已安装的工具347 已安装的工具

330</h3>348</h3>

331 349

332云会话预安装了常见的语言运行时、构建工具和数据库。下表按类别总结了包含的内容。350云端会话预安装了常见的语言运行时、构建工具和数据库。下表按类别总结了包含的内容。

333 351

334| 类别 | 包含 |352| 类别 | 包含 |

335| :- | :- |353| :- | :- |

347 365

348¹ Bun 已安装，但在包获取时存在已知的[代理兼容性问题](#install-dependencies-with-a-sessionstart-hook)。366¹ Bun 已安装，但在包获取时存在已知的[代理兼容性问题](#install-dependencies-with-a-sessionstart-hook)。

349 367

350要获取此表中大多数工具的版本，请让 Claude 在云会话中运行 `check-tools`。它是安装在会话 VM 上的 shell 命令，不是斜杠命令；您让 Claude 运行是因为 [Claude 为您运行所有 VM 命令](#run-tests-start-services-and-add-packages)。对于它不报告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，请让 Claude 运行该工具自己的版本命令，例如 `psql --version`。368要获取此表中大多数工具的版本，请让 Claude 在云端会话中运行 `check-tools`。它是安装在会话 VM 上的 shell 命令，不是您以 `/` 输入的命令；您让 Claude 运行是因为 [Claude 为您运行所有 VM 命令](#run-tests-start-services-and-add-packages)。对于它不报告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，请让 Claude 运行该工具自己的版本命令，例如 `psql --version`。

351 369

352Node.js 版本安装在 `/opt/node20`、`/opt/node21` 和 `/opt/node22`，默认情况下 22 在 `PATH` 上。要使用不同的版本，请让 Claude 将该版本的 `bin` 目录（例如 `/opt/node20/bin`）前置到 `PATH`。370Node.js 版本安装在 `/opt/node20`、`/opt/node21` 和 `/opt/node22`，默认情况下 22 在 `PATH` 上。要使用不同的版本，请让 Claude 将该版本的 `bin` 目录（例如 `/opt/node20/bin`）前置到 `PATH`。

353 371

354此列表之外的工具链，例如 .NET SDK，即使其包注册表在[默认允许列表](#default-allowed-domains)上也不会预安装。请使用[设置脚本](#setup-scripts)安装它们。372此列表之外的工具链，例如 .NET SDK，即使其包注册表在[默认允许列表](#default-allowed-domains)上也不会预安装。请使用[设置脚本](#setup-scripts)安装它们。

355 373

356<h3 id="work-with-github-issues-and-pull-requests">374<h3 id="work-with-github-issues-and-pull-requests">

357 使用 GitHub 问题和拉取请求375 使用 GitHub 问题和 Pull Request

358</h3>376</h3>

359 377

360云会话包括内置 GitHub 工具，让 Claude 无需任何设置即可读取问题、列出拉取请求、获取差异和发布评论。这些工具通过 [GitHub 代理](#github-proxy)，使用您在 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)下设置的任何方法进行身份验证，因此您的令牌永远不会进入容器。378云端会话包括内置 GitHub 工具，让 Claude 无需任何设置即可读取问题、列出 Pull Request、获取 diff 和发布评论。这些工具通过 [GitHub 代理](#github-proxy)，使用您在 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)下配置的任何方法进行身份验证，因此您的令牌永远不会进入容器。

361 379

362您可以在[环境设置](#set-environment-variables)中自己设置 `GH_TOKEN` 或 `GITHUB_TOKEN`，或者两者都不设置，让 [GitHub 代理](#github-proxy)为您进行身份验证：380您可以在[环境设置](#set-environment-variables)中自己设置 `GH_TOKEN` 或 `GITHUB_TOKEN`，或者两者都不设置，让 [GitHub 代理](#github-proxy)为您进行身份验证：

363 381

364* 如果您设置了令牌，它会原封不动地传递到容器中，因此您的脚本和 GitHub 的 [`gh` CLI](https://cli.github.com) 会直接使用它。382* 如果您设置了令牌，它会原封不动地传递到容器中，因此您的脚本和 GitHub 的 [`gh` CLI](https://cli.github.com) 会直接使用它。

365* 如果您都不设置，则由 [GitHub 代理](#github-proxy)为您的会话处理身份验证，这两个变量在 Claude 运行的命令中读取为占位符字符串 `proxy-injected`，代理在出站 GitHub 请求上替换为您的真实凭证。`gh` 无需您自己的令牌即可工作，但直接读取 `GITHUB_TOKEN` 的脚本会得到占位符，而不是可用的令牌。383* 如果您都不设置，且由 [GitHub 代理](#github-proxy)为您的会话处理身份验证，这两个变量在 Claude 运行的命令中读取为占位符字符串 `proxy-injected`，代理在出站 GitHub 请求上替换为您的真实凭据。`gh` 无需您自己的令牌即可工作，但直接读取 `GITHUB_TOKEN` 的脚本会得到占位符，而不是可用的令牌。

366 384

367您设置的令牌是普通环境变量，因此使用环境的任何人都可以读取它；代理路径将凭证保留在环境配置和会话 VM 之外。385您设置的令牌是普通环境变量，因此使用环境的任何人都可以读取它；代理路径将凭据保留在环境配置和会话 VM 之外。

368 386

369要检查哪种情况适用于您的会话，请让 Claude 运行 `echo $GH_TOKEN`。387要检查哪种情况适用于您的会话，请让 Claude 运行 `echo $GH_TOKEN`。

370 388

374 将输出链接回会话392 将输出链接回会话

375</h3>393</h3>

376 394

377每个云会话在 claude.ai 上都有一个转录 URL，会话可以从 `CLAUDE_CODE_REMOTE_SESSION_ID` 环境变量读取自己的 ID。使用它在 PR 正文、提交消息、Slack 帖子或生成的报告中放置可追溯的链接，以便审阅者可以打开生成它们的运行。395每个云端会话在 claude.ai 上都有一个会话记录 URL，会话可以从 `CLAUDE_CODE_REMOTE_SESSION_ID` 环境变量读取自己的 ID。使用它在 PR 正文、提交信息、Slack 帖子或生成的报告中放置可追溯的链接，以便审阅者可以打开生成它们的运行。

378 396

379Claude 在云会话中创建的提交包括 `Claude-Session: <url>` git 尾注，PR 正文在单独一行包括会话 URL。要省略尾注和 PR 正文链接，请将 [`attribution.sessionUrl`](/docs/zh-CN/settings-reference#attribution-sessionurl) 设置为 `false`。397Claude 在云端会话中创建的提交包括 `Claude-Session: <url>` git 尾注，PR 正文在单独一行包括会话 URL。要省略尾注和 PR 正文链接，请将 [`attribution.sessionUrl`](/docs/zh-CN/settings-reference#attribution-sessionurl) 设置为 `false`。

380 398

381要在提交或 PR 以外的内容中包含会话链接，例如 Claude 发布的 Slack 消息或它编写的报告文件，请让 Claude 运行以下命令并使用其输出。该命令将环境变量值中的 `cse_` 前缀转换为转录 URL 预期的 `session_` 前缀：399要在提交或 PR 以外的内容中包含会话链接，例如 Claude 发布的 Slack 消息或它编写的报告文件，请让 Claude 运行以下命令并使用其输出。该命令将环境变量值中的 `cse_` 前缀转换为会话记录 URL 预期的 `session_` 前缀：

382 400

383```bash theme={null}401```bash theme={null}

384echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"402echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

388 运行测试、启动服务和添加包406 运行测试、启动服务和添加包

389</h3>407</h3>

390 408

391您无法进入会话 VM 的 shell。Claude 为您运行每个命令，因此请将本节中的工作表述为您提示中的请求。409您无法进入会话 VM 的 shell。Claude 为您运行每个命令，因此请将本节中的任务表述为您提示词中的请求。

392 410

393<h4 id="run-tests">411<h4 id="run-tests">

394 运行测试412 运行测试

395</h4>413</h4>

396 414

397Claude 在处理工作的过程中运行测试。在您的提示中提出要求，例如"修复 `tests/` 中的失败测试"或"在每次更改后运行 pytest"。随[预安装的工具链](#installed-tools)提供的测试运行器（例如 pytest 和 cargo test）无需额外设置即可工作。您的项目声明为依赖项的运行器（例如 jest）会随您的依赖项一起安装。415Claude 在处理任务的过程中运行测试。在您的提示词中提出要求，例如"修复 `tests/` 中的失败测试"或"在每次更改后运行 pytest"。随[预安装的工具链](#installed-tools)提供的测试运行器（例如 pytest 和 cargo test）无需额外设置即可工作。您的项目声明为依赖的运行器（例如 jest）会随您的依赖一起安装。

398 416

399<h4 id="start-services">417<h4 id="start-services">

400 启动服务418 启动服务

424 资源限制442 资源限制

425</h3>443</h3>

426 444

427Anthropic 托管环境中的云会话运行时具有可能随时间变化的近似资源上限：445Anthropic 托管环境中的云端会话运行时具有可能随时间变化的近似资源上限：

428 446

429* 4 vCPU447* 4 vCPU

430* 16 GB RAM448* 16 GB RAM

431* 30 GB 磁盘449* 30 GB 磁盘

432 450

433VM 可能会停止需要明显更多内存的工作，例如大型构建工作或内存密集型测试。对于超出这些限制的工作负载，请使用 [Remote Control](/docs/zh-CN/remote-control) 在您自己的硬件上运行 Claude Code，或在[自托管环境](/docs/zh-CN/self-hosted-environments)中运行云会话，该环境在您的组织运营的计算上。451VM 可能会停止需要明显更多内存的任务，例如大型构建作业或内存密集型测试。对于超出这些限制的工作负载，请使用 [Remote Control](/docs/zh-CN/remote-control) 在您自己的硬件上运行 Claude Code，或在[自托管环境](/docs/zh-CN/self-hosted-environments)中运行云端会话，该环境在您的组织运营的计算资源上。

434 452

435<h3 id="time-limits">453<h3 id="time-limits">

436 时间限制454 时间限制

437</h3>455</h3>

438 456

439在 Anthropic 托管的环境中，这些时间限制适用于云会话中的长时间运行的工作，例如构建、安装或测试运行。每个条目链接到定义该限制的部分。457在 Anthropic 托管的环境中，这些时间限制适用于云端会话中的长时间运行的工作，例如构建、安装或测试运行。每个条目链接到定义该限制的部分。

440 458

441* **Claude 运行的命令**：云环境不设置自己的命令超时，因此 Bash 工具的默认值适用。Claude 默认等待 2 分钟的命令，最多可以要求 10 分钟。459* **Claude 运行的命令**：云环境不设置自己的命令超时时间，因此 Bash 工具的默认值适用。Claude 默认为前台命令等待 2 分钟，最多可以要求 10 分钟。

442 460

443 当命令达到其[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)时，Claude Code [将其移到后台](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 开头。以这种方式移动的命令可以继续运行最多 30 分钟，然后 Claude Code 在其[后台时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)处停止它。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为 `1800000` 毫秒以上会延长该限制以及前台默认值。461 当命令达到其[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)时，Claude Code [将其移到后台](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 开头。以这种方式移动的命令可以继续运行最多 30 分钟，然后 Claude Code 在其[后台时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)处停止它。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为 `1800000` 毫秒以上会延长该限制以及前台默认值。

444* **SessionStart hooks**：Claude Code 在 600 秒后取消 `command` hook，除非您在 hook 条目上设置 [`timeout`](/docs/zh-CN/hooks#common-fields)（以秒为单位）。Claude Code 不会对您使用 [`async: true`](/docs/zh-CN/hooks#run-hooks-in-the-background) 运行的 hook 强制执行超时。462* **SessionStart hook**：Claude Code 在 600 秒后取消 `command` hook，除非您在 hook 条目上设置 [`timeout`](/docs/zh-CN/hooks#common-fields)（以秒为单位）。Claude Code 不会对您使用 [`async: true`](/docs/zh-CN/hooks#run-hooks-in-the-background) 运行的 hook 强制执行超时。

445* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。463* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。

446* **空闲会话**：会话在一段时间不活动后停止，其 VM 被回收。[设置环境变量](#set-environment-variables)描述会话在每种情况下会获取什么，[环境已过期](/docs/zh-CN/claude-code-on-the-web#environment-expired)涵盖如何重新打开 VM 被回收的会话。464* **空闲会话**：在几分钟没有活动后，会话的 VM 会暂停并保存其文件，暂停的 VM 之后可能会被回收。[设置环境变量](#set-environment-variables)描述会话在每种情况下会获取什么，[环境已过期](/docs/zh-CN/claude-code-on-the-web#environment-expired)涵盖如何重新打开 VM 被回收的会话。

447 465

448要为环境的会话提高命令超时，请将 [`BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables) 添加到其[环境变量](#set-environment-variables)。两者都采用毫秒。例如，`BASH_DEFAULT_TIMEOUT_MS=600000` 使 10 分钟成为默认值。466要为环境的会话提高命令超时时间，请将 [`BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables) 添加到其[环境变量](#set-environment-variables)。两者都采用毫秒。例如，`BASH_DEFAULT_TIMEOUT_MS=600000` 使 10 分钟成为默认值。

449 467

450<h2 id="setup-scripts">468<h2 id="setup-scripts">

451 设置脚本469 设置脚本

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`，它用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每个机制会发生什么。

costs.md +1 −1

Details

394* **对复杂任务使用 plan mode**：按 Shift+Tab 进入 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)，然后再进行实现。Claude 探索代码库并提出一个方法供您批准，防止当初始方向错误时的昂贵返工。394* **对复杂任务使用 plan mode**：按 Shift+Tab 进入 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)，然后再进行实现。Claude 探索代码库并提出一个方法供您批准，防止当初始方向错误时的昂贵返工。

395* **尽早纠正方向**：如果 Claude 开始朝错误的方向发展，按 Escape 立即停止。使用 `/rewind` 或双击 Escape 将对话和代码恢复到之前的 checkpoint。395* **尽早纠正方向**：如果 Claude 开始朝错误的方向发展，按 Escape 立即停止。使用 `/rewind` 或双击 Escape 将对话和代码恢复到之前的 checkpoint。

396* **给出验证目标**：在您的提示中包含测试用例、粘贴屏幕截图或定义预期输出。当 Claude 可以验证自己的工作时，它会在您需要请求修复之前捕获问题。396* **给出验证目标**：在您的提示中包含测试用例、粘贴屏幕截图或定义预期输出。当 Claude 可以验证自己的工作时，它会在您需要请求修复之前捕获问题。

397* **增量测试**：编写一个文件，测试它，然后继续。这会在问题便宜时尽早捕获问题。397* **增量测试**：编写一个文件，测试它，然后继续。这样可以尽早发现问题。

398 398

399<h2 id="background-token-usage">399<h2 id="background-token-usage">

400 后台令牌使用400 后台令牌使用

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 +3 −4

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 重试或等待时您看到的内容

2299 2300

2300**要做什么：**2301**要做什么：**

2301 2302

2302* 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像，或当许多图像在上下文中时最多 2000 像素。2303* 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像，或当上下文中有超过 20 张图像时最多 3000 像素。

2303* 拍摄相关区域的更紧密屏幕截图，而不是整个屏幕2304* 拍摄相关区域的更紧密屏幕截图，而不是整个屏幕

2304 2305

2305<h3 id="unable-to-resize-image">2306<h3 id="unable-to-resize-image">

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* 重新表述您的上一条消息或采取不同的方法

fast-mode.md +1 −1

Details

88 88

89快速模式定价在整个 1M 令牌上下文窗口中是固定的。有关要比较的标准 Opus 费率，请参阅 [Claude 定价参考](https://platform.claude.com/docs/zh-CN/about-claude/pricing)。89快速模式定价在整个 1M 令牌上下文窗口中是固定的。有关要比较的标准 Opus 费率，请参阅 [Claude 定价参考](https://platform.claude.com/docs/zh-CN/about-claude/pricing)。

90 90

91在对话中首次启用快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入令牌价格。对话进行得越深入，成本就越高，因此从一开始就启用快速模式更便宜。该成本每个对话只应用一次，因此稍后关闭快速模式再打开不会重复收费。有关机制，请参阅 [快速模式如何与提示缓存交互](/docs/zh-CN/prompt-caching#turning-on-fast-mode)。91在对话中首次启用快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入 token 价格。对话进行得越深入，成本就越高，因此在对话开始时启用快速模式的费用最低。该成本每个对话只应用一次，因此稍后关闭快速模式再打开不会重复收费。有关机制，请参阅 [快速模式如何与提示缓存交互](/docs/zh-CN/prompt-caching#turning-on-fast-mode)。

92 92

93<h3 id="see-where-fast-mode-spend-appears">93<h3 id="see-where-fast-mode-spend-appears">

94 查看快速模式支出出现的位置94 查看快速模式支出出现的位置

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

keybindings.md +3 −2

Details

299| :- | :- | :- |299| :- | :- | :- |

306| `footer:close` | x | 停止选定的 [Agent](/docs/zh-CN/sub-agents#observe-and-steer-running-forks) 或 [工作流](/docs/zh-CN/workflows#manage-runs)；如果它已不再运行，则关闭其所在行 |

306| `footer:dismiss` | (未绑定) | 绑定键到此操作没有效果，命名它的 `keybindings.json` 保持有效。在 v2.1.281 之前，Backspace 和 Delete 被绑定到它，并从页脚中关闭选定的 artifact 链接。 |307| `footer:dismiss` | (未绑定) | 绑定键到此操作没有效果，命名它的 `keybindings.json` 保持有效。在 v2.1.281 之前，Backspace 和 Delete 被绑定到它，并从页脚中关闭选定的 artifact 链接。 |

307 308

308选定页脚项时（例如提示下方的代理面板中的一行），即使您在 `Chat` 上下文中将 `Enter` 重新绑定到 `chat:queueSubmit` 或 `chat:newline`，`Enter` 也会打开它。309选定页脚项时（例如提示下方的代理面板中的一行），即使您在 `Chat` 上下文中将 `Enter` 重新绑定到 `chat:queueSubmit` 或 `chat:newline`，`Enter` 也会打开它。

llm-gateway-connect.md +8 −1

Details

216* **由管理员分发**：如果您的组织已[部署配置](/docs/zh-CN/llm-gateway-rollout#distribute-through-managed-settings)，桌面应用通过网关路由，无需您进行任何设置216* **由管理员分发**：如果您的组织已[部署配置](/docs/zh-CN/llm-gateway-rollout#distribute-through-managed-settings)，桌面应用通过网关路由，无需您进行任何设置

217* **本地配置**：对于没有管理员分发配置的设备，打开帮助 → 故障排除 → 启用开发者模式，这将重新启动应用并显示开发者菜单。然后打开开发者 → 配置第三方推理并输入您的网关基础 URL。管理员分发的配置优先级更高，使此表单为只读217* **本地配置**：对于没有管理员分发配置的设备，打开帮助 → 故障排除 → 启用开发者模式，这将重新启动应用并显示开发者菜单。然后打开开发者 → 配置第三方推理并输入您的网关基础 URL。管理员分发的配置优先级更高，使此表单为只读

218 218

219启用网关配置后，桌面应用仅在您的本地机器上运行会话：环境选择器不提供 SSH 会话或 Anthropic 托管的云环境，[远程控制](/docs/zh-CN/remote-control)不可用。要通过网关在远程主机上使用 Claude Code，请在该主机上运行 CLI，并在那里设置[`ANTHROPIC_BASE_URL` 和网关凭证](#set-the-base-url-and-credential)。219启用网关配置后，环境选择器不提供 Anthropic 托管的云环境，并且 [Remote Control](/docs/zh-CN/remote-control) 不可用。

220

221在网关配置下，SSH 会话处于 beta 阶段，需要 Claude Desktop v1.40609.0 或更高版本。连接之前，请检查允许列表和网关地址：

222

223* **允许的主机**：SSH 会话默认关闭。要启用它们，您或您的管理员需要在第三方推理配置的 [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/configuration#sshhostallowlist) 键中列出允许的主机

224* **网关地址**：远程机器会自行连接网关，因此位于您计算机 `localhost` 上的网关不适用于 SSH 会话

225

226请参阅 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。您也可以在远程主机上运行 CLI，并在那里设置 [`ANTHROPIC_BASE_URL` 和网关凭据](#set-the-base-url-and-credential)。

220 227

221如果桌面应用显示 `Gateway was unreachable`，应用在启动时无法到达配置的基础 URL；使用上面的 [curl 测试](#verify-the-connection)检查 URL 和网络路径。228如果桌面应用显示 `Gateway was unreachable`，应用在启动时无法到达配置的基础 URL；使用上面的 [curl 测试](#verify-the-connection)检查 URL 和网络路径。

222 229

managed-mcp.md +17 −5

Details

347 `serverUrl` 条目如何匹配347 `serverUrl` 条目如何匹配

348</h4>348</h4>

349 349

350URL 支持在模式中的任何位置使用 `*` 通配符，包括方案。主机名匹配不区分大小写，忽略尾部 FQDN 点，因此 `https://Mcp.Example.com/*` 匹配 `https://mcp.example.com/api`。路径保持区分大小写。350URL 支持 `*` 通配符，包括以 `*` 作为整个方案。主机名匹配不区分大小写，忽略尾部 FQDN 点，因此 `https://Mcp.Example.com/*` 匹配 `https://mcp.example.com/api`。路径保持区分大小写。如果未指定端口，主机名的写法决定该模式仅匹配方案的默认端口还是所有端口：

351

352* **完整写出的主机名**：仅默认端口，`https` 为 443，`http` 为 80

353* **包含 `*` 的主机名**：所有端口

351 354

352下表显示常见模式允许的内容：355下表显示常见模式允许的内容：

353 356

354| 模式 | 允许 |357| 模式 | 允许 |

355| :- | :- |358| :- | :- |

356| `https://mcp.example.com/*` | 特定域上的所有路径 |359| `https://mcp.example.com/*` | 特定域上的所有路径，仅限端口 443 |

358| `https://*.example.com/*` | `example.com` 的任何子域 |361| `https://mcp.example.com:8443/*` | 该域上的所有路径，仅限端口 8443 |

362| `https://mcp.example.com:*/*` | 该域上任何端口（包括 443）的所有路径 |

363| `https://*.example.com/*` | `example.com` 的任何子域，任何端口 |

359| `http://localhost:*/*` | localhost 上的任何端口 |364| `http://localhost:*/*` | localhost 上的任何端口 |

360| `*://mcp.example.com/*` | 到特定域的任何方案 |365| `*://mcp.example.com/*` | 到特定域的任何方案，每个方案仅限其默认端口 |

366

367`deniedMcpServers` 中的条目以相同方式匹配端口，因此请根据需要阻止的端口和方案为 `staging.example.com` 选择条目：

368

369* `https://staging.example.com/*`：仅阻止该主机上端口 443 的 `https` 服务器，因此不会阻止位于 `https://staging.example.com:8443/api` 的服务器

370* `https://staging.example.com:*/*`：阻止该主机上所有端口的 `https` 服务器

371* `*://staging.example.com:*/*`：阻止该主机的任何方案和任何端口

361 372

362<h4 id="how-policy-entries-expand">373<h4 id="how-policy-entries-expand">

363 `serverCommand` 和 `serverUrl` 条目中的环境变量374 `serverCommand` 和 `serverUrl` 条目中的环境变量

529 | :- | :- |540 | :- | :- |

543 | `https://staging.example.com:8443/api` 处的 HTTP 服务器 | 允许：匹配允许列表 URL 模式，[此端口上无拒绝列表匹配](#how-serverurl-entries-match) |

533</Accordion>545</Accordion>

534 546

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)当指令未被遵循时

monitoring-usage.md +1 −1

Details

551* **服务器管理的设置**：将它们添加到您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 `env` 块中。Claude Code 在启动时会在[服务器管理的设置适用](/docs/zh-CN/model-config#surface-coverage)的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。551* **服务器管理的设置**：将它们添加到您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 `env` 块中。Claude Code 在启动时会在[服务器管理的设置适用](/docs/zh-CN/model-config#surface-coverage)的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。

552* **环境的变量**：将它们添加到云环境的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。552* **环境的变量**：将它们添加到云环境的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。

553 553

554任何使用环境的人都可以读取其变量，因此不要在其中放置凭证，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器令牌。环境上的 [API 凭证](/docs/zh-CN/cloud-environments#add-api-credentials)也无法帮助，因为 Claude Code 自己的遥测导出是[从不获得凭证的请求](/docs/zh-CN/cloud-environments#requests-that-never-get-the-credential)之一。如果您的收集器需要凭证，请改为通过服务器管理的设置配置整个导出，因为当您在那里设置凭证时，[Claude Code 会删除在托管设置外设置的端点变量](#how-managed-settings-lock-the-otlp-destination)。554任何使用环境的人都可以读取其变量，因此不要在其中放置凭据，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器令牌。环境上的[网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)也无济于事，因为 Claude Code 自己的遥测导出是[从不获得该密钥的请求](/docs/zh-CN/cloud-environments#requests-that-never-get-the-credential)之一。如果您的收集器需要凭据，请改为通过服务器管理的设置配置整个导出，因为当您在那里设置凭据时，[Claude Code 会删除在托管设置外设置的端点变量](#how-managed-settings-lock-the-otlp-destination)。

555 555

556在为云会话配置遥测时，请记住这些约束：556在为云会话配置遥测时，请记住这些约束：

557 557

overview.md +10 −8

Details

32 curl -fsSL https://claude.ai/install.sh | bash32 curl -fsSL https://claude.ai/install.sh | bash

33 ```33 ```

34 34

35 在 Windows 上，当您在 PowerShell 中时，您的提示符显示 `PS C:\`；当您在 CMD 中时，提示符显示 `C:\`（没有 `PS`）。

35 **Windows PowerShell：**37 **Windows PowerShell：**

36 38

37 ```powershell theme={null}39 ```powershell theme={null}

46 48

47 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。49 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

48 50

49 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。51 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

50 52

51 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。53 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他任何错误，请参阅[排查安装问题](/docs/zh-CN/troubleshoot-install#find-your-error)以匹配错误并获得修复方案和替代安装方法。

52 54

53 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。55 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。

54 56

89 claude91 claude

90 ```92 ```

91 93

92 首次使用时，系统会提示你登录。如果你已设置 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会跳过登录提示，改为要求你批准该密钥。就这样！[继续快速入门 →](/docs/zh-CN/quickstart)94 首次使用时，Claude Code 会提示您登录。如果您已设置 `ANTHROPIC_API_KEY` 环境变量，并在 Claude Code 询问是否使用该密钥时予以批准，Claude Code 将跳过登录提示。[继续快速入门 →](/docs/zh-CN/quickstart)

93 95

94 <Tip>96 <Tip>

95 查看[高级设置](/docs/zh-CN/setup)了解安装选项、手动更新或卸载说明。如果遇到问题，请访问[安装故障排除](/docs/zh-CN/troubleshoot-install)。97 查看[高级设置](/docs/zh-CN/setup)了解安装选项、手动更新或卸载说明。如果遇到问题，请访问[安装故障排除](/docs/zh-CN/troubleshoot-install)。

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

168 ```170 ```

169 171

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

171 </Accordion>173 </Accordion>

172 174

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

175 </Accordion>177 </Accordion>

176 178

177 <Accordion title="使用说明、skills 和 hooks 进行自定义" icon="sliders">179 <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)，保存学习内容，跨会话使用，无需你编写任何内容。180 [`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 181

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

181 183

plugin-evals.md +21 −17

Details

60这两组运行称为 with-arm 和 without-arm；[与无插件基线比较](#compare-against-a-no-plugin-baseline)涵盖了哪些用例仅运行 with-arm 以及评分器如何在两个 arm 之间评分。60这两组运行称为 with-arm 和 without-arm；[与无插件基线比较](#compare-against-a-no-plugin-baseline)涵盖了哪些用例仅运行 with-arm 以及评分器如何在两个 arm 之间评分。

61 61

62<h2 id="create-your-first-eval-suite">62<h2 id="create-your-first-eval-suite">

~~63 创建你的第一个 eval 套件~~63 创建您的第一个 eval 套件

64</h2>64</h2>

65 65

~~66本演练为你自己的插件编写一个用例，运行它，并读取结果。在开始之前，请确保你有：~~66本演练为您自己的插件编写一个用例，运行它，并读取结果。在开始之前，请确保您具备：

67 67

~~68* Claude Code v2.1.269 或更高版本和其他[要求](#requirements)~~68* Claude Code v2.1.269 或更高版本以及其他[要求](#requirements)

~~69* 在你的插件根目录打开的终端，即包含 `plugin.json` 或 `.claude-plugin/plugin.json` 的目录~~69* 在插件根目录打开的终端，即包含 `plugin.json` 或 `.claude-plugin/plugin.json` 的目录

~~70* 插件中你想测试的一个技能，以及用户会输入的应该触发它的请求~~70* 插件中您想测试的一个 skill，以及一条用户会输入且应触发该 skill 的请求

71 71

72<Steps>72<Steps>

73 <Step title="创建用例">73 <Step title="创建用例">

77 claude plugin eval init77 claude plugin eval init

78 ```78 ```

79 79

80 如果 Claude Code 还不信任此目录，它首先会询问 `Trust this plugin directory?`；回答 `y`。然后打开一个交互式 Claude Code 会话。Claude 读取你的插件并询问你好的结果是什么样的，提议应该和不应该触发插件的提示，为每个设计评分器，试运行一次以检查它们的行为，并在 `evals/` 下为每个提示写一个用例目录，每个都以其提示命名。当 Claude 告诉你套件已准备好时，使用 `/exit` 或 Ctrl+D 退出该会话以返回到你的 shell。80 如果 Claude Code 尚未信任此目录，它首先会询问 `Trust this plugin directory?`；回答 `y`。

81 81

82 如果你已经在插件根目录打开了 Claude Code 会话，你可以改为要求 Claude 在那里运行 `claude plugin eval init`。Claude 运行命令，然后在该对话中询问你相同的问题。82 随后会打开一个交互式 Claude Code 会话。Claude 读取您的插件并询问您理想的结果是什么样的，提议应该和不应该触发插件的提示词，为每个提示词设计评分器，试运行一次以检查它们的行为，并在 `evals/` 下为每个提示词写入一个用例目录，每个目录以其提示词命名。

83 83

~~84 如果你宁愿自己编写一个用例以准确查看文件包含的内容，请按照[手动编写用例](#write-a-case-manually)进行，然后回到这里运行它。~~84 当 Claude 告诉您套件已准备好时，使用 `/exit` 或 Ctrl+D 退出该会话以返回 shell。

86 如果您已经在插件根目录打开了 Claude Code 会话，也可以改为让 Claude 在那里运行 `claude plugin eval init`。Claude 会运行该命令，然后在该对话中询问您相同的问题。

88 如果您更愿意自己编写用例以准确了解文件包含的内容，请按照[手动编写用例](#write-a-case-manually)操作，然后回到这里运行它。

85 </Step>89 </Step>

86 90

87 <Step title="运行套件">91 <Step title="运行套件">

~~88 回到你的 shell 中的插件根目录，运行 `evals/` 下的每个用例：~~92 回到插件根目录下的 shell，运行 `evals/` 下的每个用例：

89 93

90 ```bash theme={null}94 ```bash theme={null}

91 claude plugin eval .95 claude plugin eval .

92 ```96 ```

93 97

94 你已经在第 1 步中信任了此目录，所以运行立即开始。如果你改为手动编写了用例，运行首先会询问 `Trust this plugin directory? [y/N]`；回答 `y`。[运行可以访问什么](#security)解释了你同意的内容。98 您已经在第 1 步中信任了此目录，所以运行会立即开始。如果您改为手动编写了用例，运行首先会询问 `Trust this plugin directory? [y/N]`；回答 `y`。[运行可以访问什么](#security)解释了您所同意的内容。

95 99

96 每个用例使用你的插件运行三次，不使用插件运行三次，所以一个用例是六次运行。当每次运行完成时，会打印一条进度线，显示该运行的分数和每个评分器的判决。100 每个用例在加载插件的情况下运行三次，在不加载插件的情况下运行三次，因此一个用例共六次运行。每次运行完成时，会打印一行进度，显示该运行的分数和每个评分器的判定。

97 </Step>101 </Step>

98 102

99 <Step title="读取摘要">103 <Step title="读取摘要">

100 当套件完成时，你会看到一个摘要表，然后是报告的位置：104 套件完成后，您会看到一个摘要表，随后是报告的位置：

101 105

102 ```text theme={null}106 ```text theme={null}

103 CASE WITH W/OUT Δ RUNS COST NOTES107 CASE WITH W/OUT Δ RUNS COST NOTES

108 Published: https://claude.ai/... · keep local next time with --no-publish112 Published: https://claude.ai/... · keep local next time with --no-publish

109 ```113 ```

110 114

111 `WITH` 是加载你的插件的用例分数，`W/OUT` 是不加载插件的分数，正的 `Δ` 意味着插件提高了分数。`COST` 是模型调用的列表价格估计，`NOTES` 显示最高权重失败评分器的解释，或来自 with-arm 的运行错误。115 `WITH` 是加载插件时该用例的分数，`W/OUT` 是不加载插件时的分数，正的 `Δ` 表示插件提高了分数。`COST` 是模型调用按标价估算的费用，`NOTES` 显示 with-arm 中权重最高的失败评分器的解释或该运行的错误。

112 </Step>116 </Step>

113 117

114 <Step title="打开报告并迭代">118 <Step title="打开报告并迭代">

115 打开 `Published:` URL，或当没有 `Published:` 行出现时打开 `Report:` 路径，以查看每个评分器对每次运行的判决和解释，以及对于 `llm` 评分器的评判的投票和它评判的摘录。`Published:` 行仅在你的账户可以[发布报告](#html-report)时出现。119 打开 `Published:` URL，或在没有 `Published:` 行时打开 `Report:` 路径，以查看每个评分器对每次运行的判定和解释，对于 `llm` 评分器还可查看评判者的投票及其评判的摘录。`Published:` 行仅在您的账户可以[发布报告](#html-report)时出现。

116 120

117 最常见的第一个发现是 `Δ` 接近零，用例的 `tool_used: Skill` 评分器失败，这意味着 Claude 在自然措辞上没有选择你的技能。调整技能的 [`description`](/docs/zh-CN/skills#frontmatter-reference)，再次运行 `claude plugin eval .`，并进行比较。121 最常见的首个发现是 `Δ` 接近零且用例的 `tool_used: Skill` 评分器失败，这意味着 Claude 在自然措辞下没有选择您的 skill。调整该 skill 的 [`description`](/docs/zh-CN/skills#frontmatter-reference)，再次运行 `claude plugin eval .`，并进行比较。

118 122

119 要廉价地迭代单个用例，运行单个 arm 一次。单次运行噪声很大，所以在信任任何更改之前，在默认三次运行时确认它。使用一个 arm，表格显示 `SCORE` 和 `PASS%` 列而不是 `WITH`、`W/OUT` 和 `Δ`：123 要以更少的运行次数迭代单个用例，可以只运行单个 arm 一次。单次运行噪声较大，因此在信任任何更改之前，请以默认的三次运行进行确认。只运行一个 arm 时，表格显示 `SCORE` 和 `PASS%` 列，而不是 `WITH`、`W/OUT` 和 `Δ`：

120 124

121 ```bash theme={null}125 ```bash theme={null}

122 claude plugin eval . --case <case-name> --runs 1 --ablation none126 claude plugin eval . --case <case-name> --runs 1 --ablation none

123 ```127 ```

124 128

125 将 `<case-name>` 替换为 `evals/` 下的目录名之一。129 将 `<case-name>` 替换为 `evals/` 下的某个目录名。

126 </Step>130 </Step>

127</Steps>131</Steps>

128 132

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

prompt-caching.md +1 −1

Details

328| 主对话 | 一小时 | 五分钟 |328| 主对话 | 一小时 | 五分钟 |

329| 其他所有内容 | 五分钟，除了服务器控制的助手请求获得一小时 | 五分钟 |329| 其他所有内容 | 五分钟，除了服务器控制的助手请求获得一小时 | 五分钟 |

330 330

331一旦您超过计划的使用限制，Claude Code 使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您需要为该使用付费，所以 Claude Code 将主对话降低到更便宜的五分钟 TTL。要在那里保持一小时 TTL，[自己选择 TTL](#choose-the-ttl-yourself)。331一旦您超过套餐的用量限制，Claude Code 开始使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您需要为该用量付费，所以 Claude Code 将主对话降低到五分钟 TTL，其缓存写入费率更低。要在那里保持一小时 TTL，[自己选择 TTL](#choose-the-ttl-yourself)。

332 332

333<h3 id="choose-the-ttl-yourself">333<h3 id="choose-the-ttl-yourself">

334 自己选择 TTL334 自己选择 TTL

quickstart.md +63 −97

Details

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

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

4 4

~~5# 快速开始~~5# 快速入门

6 6

~~7> 欢迎使用 Claude Code！~~7> 在终端中安装 Claude Code，完成登录，并使用 CLI 探索您的代码库、进行第一次代码更改。

8 8

~~9本快速开始指南将在几分钟内让您使用 AI 驱动的编码辅助。完成本指南后，您将了解如何使用 Claude Code 完成常见的开发任务。~~9本快速入门介绍终端中的 Claude Code：安装 CLI、在第一个会话中登录，以及在您自己的项目中使用它完成常见的开发任务。

10 10

11<Note>11<Note>

12 默认配置下，Claude Code 需要能够访问 claude.ai 和 Anthropic API 等端点才能完成安装、登录和正常使用。在中国大陆的网络环境中，这些端点可能无法直接访问。开始前，请先确认所在网络能够连通这些服务。企业代理配置以及 Amazon Bedrock 等第三方提供商的网络要求，请参阅[网络配置](/docs/zh-CN/network-config#network-access-requirements)。12 默认配置下，Claude Code 需要能够访问 claude.ai 和 Anthropic API 等端点才能完成安装、登录和正常使用。在中国大陆的网络环境中，这些端点可能无法直接访问。开始前，请先确认所在网络能够连通这些服务。企业代理配置以及 Amazon Bedrock 等第三方提供商的网络要求，请参阅[网络配置](/docs/zh-CN/network-config#network-access-requirements)。

19确保您拥有：19确保您拥有：

20 20

21* 打开的终端或命令提示符21* 打开的终端或命令提示符

~~22 * 如果您之前从未使用过终端，请查看[终端指南](/docs/zh-CN/terminal-guide)~~

23* 一个可以使用的代码项目22* 一个可以使用的代码项目

24* 一个 [Claude 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq)（Pro、Max、Team 或 Enterprise）、[Claude Console](https://platform.claude.com/) 账户，或通过[支持的云提供商](/docs/zh-CN/third-party-integrations)的访问权限23* 一个 [Claude 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq)（Pro、Max、Team 或 Enterprise）、[Claude Console](https://platform.claude.com/) 账户，或通过[支持的云提供商](/docs/zh-CN/third-party-integrations)的访问权限

25 24

26<Note>25<Note>

27 本指南涵盖终端 CLI。Claude Code 也可在[网页](https://claude.ai/code)、[桌面应用](/docs/zh-CN/desktop)、[VS Code](/docs/zh-CN/vs-code) 和 [JetBrains IDE](/docs/zh-CN/jetbrains)、[Slack](/docs/zh-CN/slack) 中使用，以及通过 [GitHub Actions](/docs/zh-CN/github-actions) 和 [GitLab](/docs/zh-CN/gitlab-ci-cd) 进行 CI/CD。查看[所有界面](/docs/zh-CN/overview#use-claude-code-everywhere)。26 以下情况在其他页面中介绍：

28 * **从未使用过终端**：请从[终端指南](/docs/zh-CN/terminal-guide)开始

29 * **希望在终端以外的地方使用 Claude Code**：Claude Code 也可在[网页](https://claude.ai/code)、[桌面应用](/docs/zh-CN/desktop)、[VS Code](/docs/zh-CN/vs-code) 和 [JetBrains IDE](/docs/zh-CN/jetbrains)、[Slack](/docs/zh-CN/slack) 中使用，以及通过 [GitHub Actions](/docs/zh-CN/github-actions) 和 [GitLab](/docs/zh-CN/gitlab-ci-cd) 在 CI/CD 中使用。查看[所有界面](/docs/zh-CN/overview#use-claude-code-everywhere)。

28</Note>30</Note>

29 31

30<h2 id="step-1-install-claude-code">32<h2 id="step-1-install-claude-code">

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

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

39 41

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

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

42 ```44 ```

43 45

46 在 Windows 上，当您在 PowerShell 中时，您的提示符显示 `PS C:\`；当您在 CMD 中时，提示符显示 `C:\`（没有 `PS`）。

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

45 49

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

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

48 ```52 ```

49 53

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

51 55

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

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

54 ```58 ```

55 59

56 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。60 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

57 61

58 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。62 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

59 63

60 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。64 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他任何错误，请参阅[排查安装问题](/docs/zh-CN/troubleshoot-install#find-your-error)以匹配错误并获得修复方案和替代安装方法。

61 65

62 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。66 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。

63 67

67 </Tab>71 </Tab>

68 72

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

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

71 brew install --cask claude-code75 brew install --cask claude-code

72 ```76 ```

73 77

79 </Tab>83 </Tab>

80 84

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

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

83 winget install Anthropic.ClaudeCode87 winget install Anthropic.ClaudeCode

84 ```88 ```

85 89

99 103

100该命令会打印一个版本号，后面跟着 `(Claude Code)`。104该命令会打印一个版本号，后面跟着 `(Claude Code)`。

101 105

102<h2 id="step-2-log-in-to-your-account">106<h2 id="step-2-start-your-first-session">

103 步骤 2：登录您的账户107 步骤 2：开始您的第一个会话

104</h2>108</h2>

105 109

106Claude Code 需要账户才能使用。使用 `claude` 命令启动交互式会话，首次使用时系统会提示您登录：110在任意项目目录中打开终端并启动 Claude Code：

107 111

108```bash theme={null}112```bash theme={null}

113cd /path/to/your/project

109claude114claude

110```115```

111 116

112对于 Claude 订阅或 Console 账户，请按照提示在浏览器中完成身份验证。如果您已设置 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会跳过登录提示，改为要求您批准该密钥。要稍后切换账户或重新身份验证，请在运行的会话中输入 `/login`：117将 `/path/to/your/project` 替换为您要处理的项目路径。

113 118

114```text wrap theme={null}119首次使用时，Claude Code 会提示您登录。对于 Claude 订阅或 Console 账户，请按照提示在浏览器中完成身份验证。如果您已设置 `ANTHROPIC_API_KEY` 环境变量，并且在 Claude Code 询问是否使用该密钥时予以批准，Claude Code 将跳过登录提示。

115/login

116```

117 120

118您可以使用以下任何账户类型登录：121您可以使用以下任一账户类型登录：

119 122

120* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推荐）123* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推荐）

121* [Claude Console](https://platform.claude.com/)（具有预付费额度的 API 访问）。首次登录时，Console 中会自动为集中成本跟踪创建一个"Claude Code"工作区。124* [Claude Console](https://platform.claude.com/)（使用预付额度的 API 访问）。首次登录时，系统会在 Console 中自动创建一个"Claude Code"工作区，用于集中跟踪费用。

122* [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/docs/zh-CN/third-party-integrations)（企业云提供商）125* [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](/docs/zh-CN/third-party-integrations)（企业云服务提供商）

123* 自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)（如果您的组织运行一个）：您的管理员会预先配置网关 URL，`/login` 会直接在 **Cloud gateway** 屏幕上打开，供您使用企业 SSO 登录126* 自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)（如果您的组织部署了该网关）：管理员会预先配置网关 URL，`/login` 将直接打开 **Cloud gateway** 界面，供您使用企业 SSO 登录

~~124~~

125登录后，您的凭证将被存储，您无需再次登录。详细了解 [凭证管理](/docs/zh-CN/authentication#credential-management)。

~~126~~

127<h2 id="step-3-start-your-first-session">

128 步骤 3：启动您的第一个会话

129</h2>

~~130~~

131在任何项目目录中打开您的终端并启动 Claude Code：

~~132~~

133```bash theme={null}

134cd /path/to/your/project

135claude

136```

137 127

138将 `/path/to/your/project` 替换为您要处理的项目的路径。128登录后，您的凭据会被保存，无需再次登录。如需了解更多信息，请参阅[凭据管理](/docs/zh-CN/authentication#credential-management)。

139 129

140您将看到 Claude Code 提示符，其中显示版本、当前模型和上方显示的工作目录。输入 `/help` 查看可用命令，或输入 `/resume` 继续之前的对话。130随后将显示 Claude Code 提示符，其上方会显示版本、当前模型和工作目录。输入 `/help` 查看可用命令，或输入 `/resume` 继续之前的对话。如需稍后切换账户或重新进行身份验证，请在运行中的会话内输入 `/login`。

141 131

142<h2 id="step-4-ask-your-first-question">132<h2 id="step-3-ask-your-first-question">

143 步骤 4：提出您的第一个问题133 步骤 3：提出您的第一个问题

144</h2>134</h2>

145 135

146让我们从理解您的代码库开始。尝试以下命令之一：136尝试以下命令之一：

147 137

148```text wrap theme={null}138```text wrap theme={null}

149what does this project do?139what does this project do?

150```140```

151 141

152Claude 将分析您的文件并提供摘要。您也可以提出更具体的问题：142Claude 将分析您的文件并提供摘要。您还可以提出更具体的问题：

153 143

154```text wrap theme={null}144```text wrap theme={null}

155what technologies does this project use?145what technologies does this project use?

163explain the folder structure153explain the folder structure

164```154```

165 155

166您也可以询问 Claude 关于其自身功能的问题：156您还可以询问 Claude 有关其自身功能的问题：

167 157

168```text wrap theme={null}158```text wrap theme={null}

169what can Claude Code do?159what can Claude Code do?

178```168```

179 169

180<Note>170<Note>

181 Claude Code 根据需要读取您的项目文件。您不必手动添加上下文。171 Claude Code 会根据需要读取您的项目文件。您无需手动添加上下文。

182</Note>172</Note>

183 173

184<h2 id="step-5-make-your-first-code-change">174<h2 id="step-4-make-your-first-code-change">

185 步骤 5：进行您的第一次代码更改175 步骤 4：进行您的第一次代码更改

186</h2>176</h2>

187 177

188现在让我们让 Claude Code 进行一些实际的编码。尝试一个简单的任务：178尝试一个小任务：

189 179

190```text wrap theme={null}180```text wrap theme={null}

191在主文件中添加一个 hello world 函数181add a hello world function to the main file

192```182```

193 183

194Claude Code 找到适当的文件并向您显示更改。如果它在进行更改前询问，请选择**是**以批准。184Claude Code 会找到合适的文件并向您展示更改。如果它在进行更改前征求确认，请选择 **Yes** 以批准。

195 185

196使用 Claude Code v2.1.283 或更高版本，auto 模式是交互式终端会话的[内置起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：分类器审查操作而不是您，Claude 在不询问的情况下编辑大多数文件并运行大多数命令。在早期版本上，auto 模式仅在 Pro、Max 和 Team 计划上是内置起始权限模式。对于安装后立即启动的会话，请参阅[安装或升级后的首个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)。186会话的[权限模式](/docs/zh-CN/permission-modes)决定了 Claude 可以在不事先询问您的情况下执行哪些操作。随时按 `Shift+Tab` 即可切换当前会话的权限模式。

~~197~~

198<Note>

199 您的设置或您的组织可以设置不同的起始权限模式。[会话启动时的权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)列出了相关内容。随时按 `Shift+Tab` 切换您所在会话的权限模式。

200</Note>

201 187

202<h2 id="step-6-use-git-with-claude-code">188<h2 id="step-5-use-git-with-claude-code">

203 步骤 6：在 Claude Code 中使用 Git189 步骤 5：在 Claude Code 中使用 Git

204</h2>190</h2>

205 191

206Claude Code 使 Git 操作变得对话式：192Claude Code 让 Git 操作变得像对话一样简单：

207 193

208```text wrap theme={null}194```text wrap theme={null}

209我更改了哪些文件？195what files have I changed?

210```196```

211 197

212```text wrap theme={null}198```text wrap theme={null}

213用描述性消息提交我的更改199commit my changes with a descriptive message

214```200```

215 201

216您也可以提示更复杂的 Git 操作：202您还可以通过提示词执行更复杂的 Git 操作：

217 203

218```text wrap theme={null}204```text wrap theme={null}

219创建一个名为 feature/quickstart 的新分支205create a new branch called feature/quickstart

220```206```

221 207

222```text wrap theme={null}208```text wrap theme={null}

223显示我最后的 5 次提交209show me the last 5 commits

224```210```

225 211

226```text wrap theme={null}212```text wrap theme={null}

227帮我解决合并冲突213help me resolve merge conflicts

228```214```

229 215

230<h2 id="step-7-fix-a-bug-or-add-a-feature">216<h2 id="step-6-fix-a-bug-or-add-a-feature">

231 步骤 7：修复错误或添加功能217 步骤 6：修复 bug 或添加功能

232</h2>218</h2>

233 219

234Claude 擅长调试和功能实现。

~~235~~

236用自然语言描述您想要的内容：220用自然语言描述您想要的内容：

237 221

238```text wrap theme={null}222```text wrap theme={null}

239向用户注册表单添加输入验证223add input validation to the user registration form

240```224```

241 225

242或修复现有问题：226或修复现有问题：

243 227

244```text wrap theme={null}228```text wrap theme={null}

245有一个错误，用户可以提交空表单 - 修复它229there's a bug where users can submit empty forms - fix it

246```230```

247 231

248Claude Code 将：232<h2 id="step-7-test-out-other-common-workflows">

~~249~~ 233 步骤 7：试用其他常见工作流

250* 定位相关代码

251* 理解上下文

252* 实现解决方案

253* 如果可用，运行测试

~~254~~

255<h2 id="step-8-test-out-other-common-workflows">

256 步骤 8：尝试其他常见工作流

257</h2>234</h2>

258 235

259有多种方式可以与 Claude 一起工作：236您可以通过多种方式与 Claude 协作：

260 237

261**重构代码**238**重构代码**

262 239

283```260```

284 261

285<Tip>262<Tip>

286 像与有帮助的同事交谈一样与 Claude 交谈。描述您想要实现的目标，它将帮助您实现。263 像与一位乐于助人的同事交流一样与 Claude 对话。描述您想要实现的目标，它会帮助您达成。

287</Tip>264</Tip>

288 265

289<h2 id="essential-commands">266<h2 id="essential-commands">

361 338

362现在您已经学习了基础知识，探索更多高级功能：339现在您已经学习了基础知识，探索更多高级功能：

363 340

364<CardGroup cols={2}>341* [Claude Code 如何工作](/docs/zh-CN/how-claude-code-works)：了解智能体循环、内置工具以及 Claude Code 如何与您的项目交互

365 <Card title="Claude Code 如何工作" icon="microchip" href="/docs/zh-CN/how-claude-code-works">342* [最佳实践](/docs/zh-CN/best-practices)：通过有效的提示和项目设置获得更好的结果

366 了解代理循环、内置工具以及 Claude Code 如何与您的项目交互343* [常见工作流](/docs/zh-CN/common-workflows)：常见任务的分步指南

367 </Card>344* [扩展 Claude Code](/docs/zh-CN/features-overview)：使用 CLAUDE.md、skill、hook、MCP 等进行自定义

~~368~~

369 <Card title="最佳实践" icon="star" href="/docs/zh-CN/best-practices">

370 通过有效的提示和项目设置获得更好的结果

371 </Card>

~~372~~

373 <Card title="常见工作流" icon="graduation-cap" href="/docs/zh-CN/common-workflows">

374 常见任务的分步指南

375 </Card>

376 345

377 <Card title="扩展 Claude Code" icon="puzzle-piece" href="/docs/zh-CN/features-overview">346有关安装选项、手动更新或卸载说明，请参阅[高级设置](/docs/zh-CN/setup)。

378 使用 CLAUDE.md、skills、hooks、MCP 等进行自定义

379 </Card>

380</CardGroup>

381 347

382<h2 id="getting-help">348<h2 id="getting-help">

383 获取帮助349 获取帮助

384</h2>350</h2>

385 351

386* **在 Claude Code 中**：输入 `/help` 或询问"我如何..."352* **在 Claude Code 中**：输入 `/help` 或询问"我如何..."

387* **文档**：您在这里！浏览其他指南353* **文档**：浏览本站的其他指南

388* **课程**：参加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和 [Claude Academy](https://academy.claude.com/) 上的其他免费自学课程354* **课程**：参加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和 [Claude Academy](https://academy.claude.com/) 上的其他免费自学课程

389* **社区**：加入 [Discord 服务器](https://www.anthropic.com/discord) 获取提示和支持355* **社区**：加入 [Discord 服务器](https://www.anthropic.com/discord) 获取提示和支持

remote-control.md +1 −1

Details

365</h2>365</h2>

366 366

367* **每个交互式进程只能有一个远程会话**：在服务器模式之外，每个 Claude Code 实例一次只支持一个远程会话。使用[服务器模式](#start-a-remote-control-session)从单个进程运行多个并发会话。367* **每个交互式进程只能有一个远程会话**：在服务器模式之外，每个 Claude Code 实例一次只支持一个远程会话。使用[服务器模式](#start-a-remote-control-session)从单个进程运行多个并发会话。

368* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出桌面应用或 VS Code，或以其他方式停止 `claude` 进程，会话将离线，直到您[恢复它](#resume-sessions-after-stopping-the-server)。要在断开 SSH 连接后保持远程机器上的会话运行，请在 `tmux` 或 `screen` 内启动它。368* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 Desktop 应用或 VS Code，或以其他方式停止 `claude` 进程，会话将离线，直到您[将其恢复](#resume-sessions-after-stopping-the-server)。如果您在远程机器上的终端中运行 `claude`，请在 `tmux` 或 `screen` 中启动它，以便在断开 SSH 连接后会话仍保持运行。

369* **服务器模式中的崩溃会话**：如果由 `claude remote-control` 提供的会话崩溃，请从连接的设备向其发送消息。Claude Code 会再次提供它。您不必重启服务器。需要 Claude Code v2.1.238 或更高版本。369* **服务器模式中的崩溃会话**：如果由 `claude remote-control` 提供的会话崩溃，请从连接的设备向其发送消息。Claude Code 会再次提供它。您不必重启服务器。需要 Claude Code v2.1.238 或更高版本。

370* **已连接会话上的 HTTP 403 拒绝**：一旦交互式会话连接，当您的机器和 Anthropic 服务器之间的某个地方返回 HTTP 403 时（在 VPN 或网络更改后可能发生），Claude Code 会重试最多三分钟。如果拒绝持续更长时间，Claude Code 会断开连接，原因会说明是什么拒绝了：网络边缘，或您自己网络上的代理、VPN 或防火墙。370* **已连接会话上的 HTTP 403 拒绝**：一旦交互式会话连接，当您的机器和 Anthropic 服务器之间的某个地方返回 HTTP 403 时（在 VPN 或网络更改后可能发生），Claude Code 会重试最多三分钟。如果拒绝持续更长时间，Claude Code 会断开连接，原因会说明是什么拒绝了：网络边缘，或您自己网络上的代理、VPN 或防火墙。

371* **扩展网络中断**：如果您的机器处于唤醒状态但无法到达网络，接下来的操作取决于模式：371* **扩展网络中断**：如果您的机器处于唤醒状态但无法到达网络，接下来的操作取决于模式：

routines.md +1 −1

Details

93 为例程选择一个 [cloud environment](/docs/zh-CN/cloud-environments)。环境控制云会话可以访问的内容：93 为例程选择一个 [cloud environment](/docs/zh-CN/cloud-environments)。环境控制云会话可以访问的内容：

94 94

95 * **Network access**：设置每次运行期间可用的互联网访问级别95 * **Network access**：设置每次运行期间可用的互联网访问级别

96 * **Environment variables**：提供 Claude 可以在每次运行期间使用的值。它们 [对使用该环境的任何人都可见](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 计划上，将 Claude 在运行期间调用的 API 的密钥存储为 [API credentials](/docs/zh-CN/cloud-environments#add-api-credentials)。该部分还列出了从不获得凭证的请求96 * **Environment variables**：提供 Claude 在每次运行期间可以使用的值。它们[对使用该环境的任何人都可见](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 计划上，请改为将 Claude 在运行期间调用的 API 的密钥存储为[网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)。该部分还列出了永远不会获得密钥的请求

97 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/docs/zh-CN/cloud-environments#environment-caching)，因此脚本不会在每个会话上重新运行97 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/docs/zh-CN/cloud-environments#environment-caching)，因此脚本不会在每个会话上重新运行

98 98

99 提供了一个 **Default** 环境，具有 **Trusted** 网络访问，允许仅通过会话网络的 [default allowlist](/docs/zh-CN/cloud-environments#default-allowed-domains) 的包注册表、云提供商 API、容器注册表和常见开发域。您添加到例程的 Connectors 通过 Anthropic 的服务器到达其服务，因此不需要更改允许列表。如果您的例程需要直接到达您自己的服务或该列表之外的域，请在运行前编辑环境的 [network access](/docs/zh-CN/cloud-environments#network-access)。要使用单独的环境，请先 [create one](/docs/zh-CN/cloud-environments#configure-your-environment)。99 提供了一个 **Default** 环境，具有 **Trusted** 网络访问，允许仅通过会话网络的 [default allowlist](/docs/zh-CN/cloud-environments#default-allowed-domains) 的包注册表、云提供商 API、容器注册表和常见开发域。您添加到例程的 Connectors 通过 Anthropic 的服务器到达其服务，因此不需要更改允许列表。如果您的例程需要直接到达您自己的服务或该列表之外的域，请在运行前编辑环境的 [network access](/docs/zh-CN/cloud-environments#network-access)。要使用单独的环境，请先 [create one](/docs/zh-CN/cloud-environments#configure-your-environment)。

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 在该模式中启动恢复的会话 |

setup.md +5 −3

Details

49 curl -fsSL https://claude.ai/install.sh | bash49 curl -fsSL https://claude.ai/install.sh | bash

50 ```50 ```

51 51

52 在 Windows 上，当您在 PowerShell 中时，您的提示符显示 `PS C:\`；当您在 CMD 中时，提示符显示 `C:\`（没有 `PS`）。

52 **Windows PowerShell：**54 **Windows PowerShell：**

53 55

54 ```powershell theme={null}56 ```powershell theme={null}

63 65

64 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。66 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

65 67

66 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。68 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

67 69

68 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。70 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他任何错误，请参阅[排查安装问题](/docs/zh-CN/troubleshoot-install#find-your-error)以匹配错误并获得修复方案和替代安装方法。

69 71

70 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。72 建议在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安装 Git for Windows，Claude Code 将使用 PowerShell 作为 shell 工具。WSL 设置不需要 Git for Windows。

71 73

204 206

205Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)）使用 Claude Code。207Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)）使用 Claude Code。

206 208

207安装后，通过运行 `claude` 并按照浏览器提示登录。如果设置了 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会提示您一次以批准该密钥，而不是打开浏览器。有关所有账户类型和团队设置选项，请参阅[身份验证](/docs/zh-CN/authentication)。209安装后，通过运行 `claude` 并按照浏览器提示登录。如果设置了 `ANTHROPIC_API_KEY` 环境变量，并且在 Claude Code 询问是否使用该密钥时您批准了它，Claude Code 将跳过登录提示。有关所有账户类型和团队设置选项，请参阅[身份验证](/docs/zh-CN/authentication)。

208 210

209<h2 id="update-claude-code">211<h2 id="update-claude-code">

210 更新 Claude Code212 更新 Claude Code

sub-agents.md +3 −3

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

1279| 权限 | 提示在您的终端中出现 | [提示在后台运行时在您的主会话中出现](#run-subagents-in-foreground-or-background) |1279| 权限 | 提示在您的终端中出现 | [提示在后台运行时在您的主会话中出现](#run-subagents-in-foreground-or-background) |

1281 1281

1282因为分叉的系统提示和工具定义与父级相同，其第一个请求重用父级的 [prompt cache](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。这使得分叉比为需要相同上下文的任务生成新 subagent 更便宜。1282因为分叉的系统提示词和工具定义与父级相同，其第一个请求重用父级的[提示缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。由于这种重用，对于需要相同上下文的任务，分叉的成本低于新的子代理。

1283 1283

1284当 Claude 通过 Agent 工具生成分叉时，它可以传递 `isolation: "worktree"` 以便分叉的文件编辑被写入单独的 git worktree 而不是您的检出。分叉无法生成进一步的分叉。1284当 Claude 通过 Agent 工具生成分叉时，它可以传递 `isolation: "worktree"` 以便分叉的文件编辑被写入单独的 git worktree 而不是您的检出。分叉无法生成进一步的分叉。

1285 1285

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 19:00 UTC