Documentation — Spybara

admin-setup.md +1 −1

Details

78 78

79Desktop 在每次 WSL 会话启动时读取策略，因此在部署后无需重启应用。79Desktop 在每次 WSL 会话启动时读取策略，因此在部署后无需重启应用。

80 80

81如果设备仍然拒绝 WSL 会话，请在该设备上的 Claude Desktop 中打开 **Help > Troubleshooting > Show Logs in Explorer**，这会将其日志文件夹的副本保存到 Downloads。在该副本中搜索 `main.log` 中的 `[wslPolicyGate] denying WSL session`。拒绝的原因在括号中，例如 `(cli-file-present)`。如果 Claude Desktop 是用 `.exe` 安装程序安装的，您也可以在 `%APPDATA%\Claude\logs\main.log` 处读取实时文件。81如果设备仍然拒绝 WSL 会话，请在该设备上的 Claude Desktop 中打开 **Help > Troubleshooting > Show Logs in File Explorer**，这会将其日志文件夹的副本保存到 Downloads。在该副本中搜索 `main.log` 中的 `[wslPolicyGate] denying WSL session`。拒绝的原因在括号中，例如 `(cli-file-present)`。

82 82

83启用 WSL 会话后，将您的托管设置扩展到它们：83启用 WSL 会话后，将您的托管设置扩展到它们：

84 84

advisor.md +8 −8

Details

87Claude Code 在该会话中使用该标志而不是 `advisorModel` 设置。它不会在 `claude --help` 中列出 `--advisor`。如果以下任何情况成立，Claude Code 在启动时会以错误退出：87Claude Code 在该会话中使用该标志而不是 `advisorModel` 设置。它不会在 `claude --help` 中列出 `--advisor`。如果以下任何情况成立，Claude Code 在启动时会以错误退出：

88 88

89* 会话的主模型不支持顾问89* 会话的主模型不支持顾问

~~90* 请求的模型（例如 Haiku）无法充当顾问~~90* 请求的模型（例如 Haiku 4.5）无法充当顾问

91* 您的组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了请求的模型91* 您的组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了请求的模型

92* 您请求了 Fable，而您的账户仍然需要[使用额度同意](#fable-advisor-and-usage-credits)92* 您请求了 Fable，而您的账户仍然需要[使用额度同意](#fable-advisor-and-usage-credits)

93 93

103 103

104| 主模型 | 接受的顾问 |104| 主模型 | 接受的顾问 |

105| - | - |105| - | - |

106| Haiku 4.5 | Fable、Opus、Sonnet |106| Haiku 4.5 | Fable、Opus、Sonnet、Haiku 5.5 |

107| Sonnet 4.6 | Fable、Opus、Sonnet |107| Sonnet 4.6 | Fable、Opus、Sonnet、Haiku 5.5 |

108| Opus 4.6 | Fable、Opus、Sonnet 5 或更高版本 |108| Opus 4.6 | Fable、Opus、Sonnet 5 或更高版本、Haiku 5.5 |

109| Sonnet 5 | Fable、Opus 4.7 或更高版本、Sonnet 5 或更高版本 |109| Sonnet 5 或 Haiku 5.5 | Fable、Opus 4.7 或更高版本、Sonnet 5 或更高版本、Haiku 5.5 |

110| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更高版本、Sonnet 5.5 |110| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更高版本、Sonnet 5.5 |

111| Sonnet 5.5 | Fable、Opus 5 或更高版本、Sonnet 5.5 |111| Sonnet 5.5 | Fable、Opus 5 或更高版本、Sonnet 5.5 |

112| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更高版本 |112| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更高版本 |

113| Fable 5 | Fable 5.1 或 Fable 5 |113| Fable 5 | Fable 5.1 或 Fable 5 |

114| Fable 5.1 | Fable 5.1 |114| Fable 5.1 | Fable 5.1 |

115 115

116Fable 5.1 需要 Claude Code v2.1.257 或更高版本。Fable 模型需要 [Fable 访问权限](/docs/zh-CN/model-config#work-with-fable)。将 Sonnet 5.5 作为 Opus 4.7 或 Opus 4.8 主模型的顾问需要 Claude Code v2.1.287 或更高版本。116Fable 5.1 需要 Claude Code v2.1.257 或更高版本。Fable 模型需要 [Fable 访问权限](/docs/zh-CN/model-config#work-with-fable)。将 Sonnet 5.5 作为 Opus 4.7 或 Opus 4.8 主模型的顾问需要 Claude Code v2.1.287 或更高版本。将 Haiku 5.5 作为主模型或顾问需要 Claude Code v2.1.293 或更高版本。

117 117

118将顾问设置为 `fable`、`opus` 或 `sonnet`。这些别名解析为 Claude Code 为每个模型系列[内置的默认版本](/docs/zh-CN/model-config#model-aliases)，该版本随新的 Claude Code 版本而推进。您也可以传递完整的模型 ID，例如 `claude-opus-5-5`。Haiku 可以调用顾问，但不能充当顾问。118将顾问设置为 `fable`、`opus` 或 `sonnet`。这些别名解析为 Claude Code 为每个模型系列[内置的默认版本](/docs/zh-CN/model-config#model-aliases)，该版本随新的 Claude Code 版本而推进。您也可以传递完整的模型 ID，例如 `claude-opus-5-5` 或 `claude-haiku-5-5`。Haiku 4.5 可以调用顾问，但不能充当顾问。

119 119

120子代理继承配置的顾问，并对其自己的模型应用相同的配对检查。120子代理继承配置的顾问，并对其自己的模型应用相同的配对检查。

121 121

202顾问工具需要以下所有条件：202顾问工具需要以下所有条件：

203 203

204* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/docs/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。如果网关或其上游不识别顾问工具，请参阅[自动重试和错误转发](/docs/zh-CN/llm-gateway-protocol#automatic-retry-and-error-forwarding)了解 Claude Code 如何响应。204* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/docs/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。如果网关或其上游不识别顾问工具，请参阅[自动重试和错误转发](/docs/zh-CN/llm-gateway-protocol#automatic-retry-and-error-forwarding)了解 Claude Code 如何响应。

205* **支持的主模型**：Fable、Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 Haiku 4.5。请参阅[选择顾问模型](#choose-an-advisor-model)了解每个顾问接受的模型。205* **支持的主模型**：Fable、Opus 4.6 或更高版本、Sonnet 4.6 或更高版本、Haiku 4.5 或 Haiku 5.5。请参阅[选择顾问模型](#choose-an-advisor-model)了解每个主模型接受哪些顾问。

206* **功能标志获取**：Claude Code 通过从 Anthropic 获取的功能标志来启用顾问。在设置了关闭标志获取的变量（例如 `DISABLE_TELEMETRY`）的会话中，顾问保持关闭状态。请参阅[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。206* **功能标志获取**：Claude Code 通过从 Anthropic 获取的功能标志来启用顾问。在设置了关闭标志获取的变量（例如 `DISABLE_TELEMETRY`）的会话中，顾问保持关闭状态。请参阅[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。

207 207

208<h2 id="turn-the-advisor-off">208<h2 id="turn-the-advisor-off">

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 +139 −138

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) 了解详情 |

953| `forward_subagent_text` | `bool` | `False` | 在消息流中转发子代理文本和思考块。没有此选项，Claude Code 会发出子代理 `tool_use` 和 `tool_result` 块，但不会发出文本或思考。需要 Python Agent SDK 0.2.140 或更高版本 |953| `forward_subagent_text` | `bool` | `False` | 在消息流中转发子代理文本和思考块。没有此选项时，Claude Code 会省略在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的文本和思考块。有关嵌套子代理、带有 `context: fork` 的 skill 以及各自所需的 Claude Code 版本，见 [跟踪子代理消息](/docs/zh-CN/headless#follow-subagent-messages)。需要 Python Agent SDK 0.2.140 或更高版本 |

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 不会将您的 `display` 值传递给某些提供商，例如 Amazon Bedrock 和 Google Cloud 的 Agent Platform。在这些提供商上，即使您将 `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 +228 −220

Details

6 6

7> TypeScript Agent SDK 的完整 API 参考，包括所有函数、类型和接口。7> TypeScript Agent SDK 的完整 API 参考，包括所有函数、类型和接口。

8 8

~~9<script src="/docs/components/typescript-sdk-type-links.js" defer />~~

11<h2 id="installation">9<h2 id="installation">

12 安装10 安装

13</h2>11</h2>

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

187});185});

188 186

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

188 for await (const message of claimedQuery) {

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

190 }

191} catch (error) {

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

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

191}194}

192```195```

193 196

539| 属性 | 类型 | 默认值 | 描述 |542| 属性 | 类型 | 默认值 | 描述 |

540| :- | :- | :- | :- |543| :- | :- | :- | :- |

542| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录。SDK 将每个条目作为 `--add-dir` 传递给 Claude Code，因此使用 `project` 设置源时，Claude Code 也会[加载目录的 skills、commands 和 subagents](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) |545| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录。SDK 会将每个条目作为 `--add-dir` 传递给 Claude Code，因此在使用 `project` 设置源时，Claude Code 还会[加载该目录的 skill、命令和子代理](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) |

546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时需要，可在启动时或稍后通过 `setPermissionMode()` 设置。参见[计划模式](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan)了解它如何与 `permissionMode: 'plan'` 交互 |549| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时必需，无论是在启动时还是之后通过 `setPermissionMode()` 设置。有关它与 `permissionMode: 'plan'` 的交互方式，请参阅[计划模式](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan) |

547| `allowedTools` | `string[]` | `[]` | 自动批准而无需提示的工具。这不会限制 Claude 仅使用这些工具。如果您在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择加入该会话。其他未列出的工具会根据 `permissionMode` 和 `canUseTool` 处理。使用 `disallowedTools` 来阻止工具。参见[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |550| `allowedTools` | `string[]` | `[]` | 无需提示即可自动批准的工具。这不会将 Claude 限制为只能使用这些工具。如果您在此处指定了某个[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)，Claude Code 也会为该会话启用它。其他未列出的工具将交由 `permissionMode` 和 `canUseTool` 处理。使用 `disallowedTools` 来阻止工具。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)转向提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。参见 [`CanUseTool`](#canusetool) 了解详情 |552| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示环节时调用。对于由 `allowedTools`、允许规则或 `permissionMode` 自动批准的调用，不会调用此函数。允许规则不会预先批准[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。详情请参阅 [`CanUseTool`](#canusetool) |

554| `disallowedTools` | `string[]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 会从 Claude 的上下文中移除该工具。作用域规则如 `"Bash(rm *)"` 会保留工具可用，并在每个权限模式中拒绝匹配的调用，包括 `bypassPermissions`，针对[按写入方式](/docs/zh-CN/permissions#bash-rule-limits)的命令。参见[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |557| `disallowedTools` | `string[]` | `[]` | 要拒绝的工具。像 `"Bash"` 这样的裸名称会将该工具从 Claude 的上下文中移除。像 `"Bash(rm *)"` 这样的限定规则会保留该工具可用，但在所有权限模式（包括 `bypassPermissions`）下拒绝匹配的调用，匹配基于[命令的书写形式](/docs/zh-CN/permissions#bash-rule-limits)。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

557| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置时，这会替换子进程环境而不是与 `process.env` 合并，因此传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留继承的变量如 `PATH`。参见[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)了解此模式的示例，以及[环境变量](/docs/zh-CN/env-vars)了解底层 CLI 读取的变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |560| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置后，它会替换子进程环境，而不是与 `process.env` 合并，因此请传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留 `PATH` 等继承的变量。有关此模式的示例，请参阅[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)；有关底层 CLI 读取的变量，请参阅[环境变量](/docs/zh-CN/env-vars)。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 可在 User-Agent 标头中标识您的应用 |

560| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他参数 |563| `extraArgs` | `Record<string, string \| null>` | `{}` | 附加参数 |

563| `forwardSubagentText` | `boolean` | `false` | 转发 subagent 文本和思考块作为助手和用户消息，设置 `parent_tool_use_id`，以便消费者可以呈现嵌套的转录。没有此选项，Claude Code 会发出 subagent `tool_use` 和 `tool_result` 块，但不会发出文本或思考。来自每个嵌套深度的 subagents 的消息在 Claude Code v2.1.219 及更高版本上转发；在 v2.1.219 之前，仅出现来自深度-1 subagents 的消息。来自分叉 skill 生成的 subagents 和嵌套分叉 skills 的消息需要 v2.1.275 或更高版本 |566| `forwardSubagentText` | `boolean` | `false` | 将子代理的文本和思考块作为设置了 `parent_tool_use_id` 的 assistant 和 user 消息转发，以便使用方渲染嵌套的会话记录。如果不使用此选项，Claude Code 会省略在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的文本和思考块。有关嵌套子代理、带有 `context: fork` 的 skill 以及各自所需的 Claude Code 版本，请参阅[跟踪子代理消息](/docs/zh-CN/headless#follow-subagent-messages) |

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

565| `includeHookEvents` | `boolean` | `false` | 在消息流中包含 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命周期事件始终包含，不需要此选项。某些 hook 事件，如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，即使使用此选项也不会产生 `SDKHookStartedMessage`。对于这些事件，Claude Code 仍会在运行超过一秒的命令 hook 产生输出时发出 `SDKHookProgressMessage`，并仅在[在后台运行的 hook](/docs/zh-CN/hooks#run-hooks-in-the-background) 完成时发出 `SDKHookResponseMessage` |568| `includeHookEvents` | `boolean` | `false` | 在消息流中以 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 的形式包含 hook 生命周期事件。`SessionStart` 和 `Setup` hook 的生命周期事件始终会包含，无需此选项。某些 hook 事件（例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）即使启用此选项也永远不会产生 `SDKHookStartedMessage`。对于这些事件，当运行超过一秒的命令 hook 产生输出时，Claude Code 仍会发出 `SDKHookProgressMessage`，并且仅在[在后台运行的](/docs/zh-CN/hooks#run-hooks-in-the-background) hook 完成时才发出 `SDKHookResponseMessage` |

568| `managedSettings` | `Settings` | `undefined` | 您的主机进程提供给生成的会话的策略层设置。在具有管理员部署的托管设置的机器上，Claude Code 会忽略这些，除非管理员的最高优先级托管源设置 `parentSettingsBehavior: 'merge'`，并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时永远不会合并。合并的值通过仅限制性过滤器；[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)涵盖过滤器允许的内容和 `allowManaged*Only` 锁。设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的主机有三个键直接从此有效负载读取：其在 Claude Code v2.1.222 或更高版本上的[模型配置](/docs/zh-CN/model-config#restrict-model-selection)、当没有托管源在 v2.1.246 或更高版本上设置时的 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing)，以及其在 v2.1.247 或更高版本上的 `ENABLE_TOOL_SEARCH` env 条目 |571| `managedSettings` | `Settings` | `undefined` | 由您的宿主进程提供给所生成会话的策略层级设置。在部署了管理员托管设置的机器上，除非管理员优先级最高的托管源设置了 `parentSettingsBehavior: 'merge'`，否则 Claude Code 会忽略这些设置；并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时，永远不会合并它们。合并的值会经过一个仅限收紧的过滤器；[限制父级设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)介绍了过滤器允许的内容以及 `allowManaged*Only` 锁定。设置了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的宿主会改为直接从此负载中读取三个键：在 Claude Code v2.1.222 或更高版本中读取其[模型配置](/docs/zh-CN/model-config#restrict-model-selection)；在 v2.1.246 或更高版本中，当没有托管源设置 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 时读取该键；在 v2.1.247 或更高版本中读取其 `ENABLE_TOOL_SEARCH` env 条目 |

572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |

574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 处理 MCP 引出请求的回调。当 MCP 服务器请求用户输入且没有 hook 首先处理时调用。未提供时，未处理的引出请求会自动拒绝 |577| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用于处理 MCP elicitation 请求的回调。当 MCP 服务器请求用户输入且没有 hook 先行处理时调用。未提供时，未处理的 elicitation 请求会被自动拒绝 |

575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 为代理结果定义输出格式。参见[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)了解详情 |578| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 定义 Agent 结果的输出格式。详情请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs) |

576| `outputStyle` | `string` | `undefined` | 不是 `Options` 字段。改为在内联 [`settings`](/docs/zh-CN/settings) 对象或设置文件中设置 `outputStyle`。参见[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style) |579| `outputStyle` | `string` | `undefined` | 不是 `Options` 字段。请改为在内联 [`settings`](/docs/zh-CN/settings) 对象或设置文件中设置 `outputStyle`。请参阅[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style) |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 谁回答权限提示：`'host'` 将它们路由到您的 [`canUseTool`](#canusetool) 回调或 `permissionPromptToolName` 工具，`'none'` [拒绝会提示的调用](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更高版本 |583| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 由谁回答权限提示：`'host'` 将其路由到您的 [`canUseTool`](#canusetool) 回调或 `permissionPromptToolName` 工具，`'none'` 则[拒绝本应触发提示的调用](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更高版本 |

584| `projectConfigRoot` | `string` | `undefined` | `cwd` 是其 worktree 的受信任检出的绝对路径。Claude Code 从此目录而不是 `cwd` 读取项目设置、`.mcp.json` 和项目的 `.claude/` commands、agents、skills、workflows、routines 和 output styles，并将 `CLAUDE_PROJECT_DIR` 设置为它。Hooks、helper scripts 如 `apiKeyHelper` 和 stdio MCP 服务器以此目录作为其工作目录启动。`CLAUDE.md` 文件和 `.claude/rules/` 仍从 `cwd` 加载。需要 Claude Code v2.1.275 或更高版本 |587| `projectConfigRoot` | `string` | `undefined` | `cwd` 作为其 worktree 的受信任检出目录的绝对路径。Claude Code 会从此目录而不是 `cwd` 读取项目设置、`.mcp.json` 以及项目 `.claude/` 中的命令、Agent、skill、工作流、Routine 和输出样式，并将 `CLAUDE_PROJECT_DIR` 设置为此目录。hook、`apiKeyHelper` 等辅助脚本以及 stdio MCP 服务器会以此目录作为工作目录启动。`CLAUDE.md` 文件和 `.claude/rules/` 仍从 `cwd` 加载。需要 Claude Code v2.1.275 或更高版本 |

585| `promptSuggestions` | `boolean` | `false` | 启用提示建议。在一个轮次后，Claude Code 发出一个 `prompt_suggestion` 消息，携带预测的下一个用户提示。Claude Code 对某些轮次不生成建议，例如当您的账户接近或达到使用限制时。参见[Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions) |588| `promptSuggestions` | `boolean` | `false` | 启用提示词建议。每轮结束后，Claude Code 会发出一条 `prompt_suggestion` 消息，其中包含预测的下一条用户提示词。对于某些轮次，Claude Code 不会生成建议，例如当您的账户接近或已达到用量限制时。请参阅[Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions) |

587| `resumeDropsTurn` | `string` | `undefined` | 使用 `resumeSessionAt`：截断恢复打算丢弃的轮次的提示 UUID。当丢弃的范围包含任何不可归因于该轮次的内容（如吸收的排队消息或任务通知）时，Claude Code 拒绝恢复，并在拒绝消息中命名 `--resume-drops-turn` 标志。仅 Agent SDK 和打印模式恢复读取该对。需要 Claude Code v2.1.223 或更高版本 |590| `resumeDropsTurn` | `string` | `undefined` | 与 `resumeSessionAt` 配合使用：截断式恢复打算丢弃的轮次的提示词 UUID。当被丢弃的范围包含任何无法归属于该轮次的内容（例如已吸收的排队消息或任务通知）时，Claude Code 会拒绝恢复，并在拒绝消息中指明 `--resume-drops-turn` 标志。只有 Agent SDK 和 print 模式的恢复会读取这对参数。需要 Claude Code v2.1.223 或更高版本 |

594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)无论如何都会加载；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。参见[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |597| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有来源） | 控制要加载哪些文件系统设置。传递 `[]` 可禁用用户、项目和本地设置。[端点托管策略](/docs/zh-CN/managed-settings#delivery-mechanisms)无论如何都会加载；当会话在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上使用组织凭据进行身份验证时，会获取服务器托管设置。请参阅[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

595| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skills。传递 `'all'` 以启用每个发现的 skill，或传递 skill 名称列表。仅传递精确名称。在 Agent SDK v0.3.221 或更高版本上，SDK 在启动 Claude Code 进程之前会以错误拒绝格式错误和通配符形式的名称。设置时，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您也传递 `tools`，在该列表中包含 `'Skill'`。参见[Skills](/docs/zh-CN/agent-sdk/skills) |598| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skill。传递 `'all'` 以启用所有发现的 skill，或传递 skill 名称列表。仅传递精确名称。在 Agent SDK v0.3.221 或更高版本中，SDK 会在启动 Claude Code 进程之前以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您同时传递了 `tools`，请在该列表中包含 `'Skill'`。请参阅 [Skills](/docs/zh-CN/agent-sdk/skills) |

599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获得自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。传递字符串数组，在静态和每个请求部分之间使用导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量，以[缓存自定义提示的静态部分](/docs/zh-CN/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话的上下文移到第一个用户消息中，以[更好地跨机器重用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 以在每个请求上重建提示而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定义提示上设置 `snapshot`，传递 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |602| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最简提示词） | 系统提示词配置。传递字符串以使用自定义提示词，或传递 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示词。传递字符串数组，并在静态部分与每请求部分之间放置导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量，即可[缓存自定义提示词的静态部分](/docs/zh-CN/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以附加额外指令进行扩展，并设置 `excludeDynamicSections: true` 将每会话上下文移到第一条用户消息中，以[在不同机器间更好地复用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 可在每次请求时重新构建提示词，而不是[复用会话在首次请求时记录的提示词](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定义提示词上设置 `snapshot`，请使用 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |

600| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任务预算（令牌）。设置时，模型被告知其剩余令牌预算，以便它可以调整工具使用速度并在限制前完成 |603| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端的任务预算（以 token 计）。设置后，模型会被告知其剩余的 token 预算，以便控制工具使用节奏并在达到限制前收尾 |

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

603| `toolAliases` | `Record<string, string>` | `undefined` | 将内置工具名称映射到 MCP 工具名称，以便 Claude 调用您的 MCP 实现而不是内置的。例如，`{ Bash: 'mcp__workspace__bash' }` |606| `toolAliases` | `Record<string, string>` | `undefined` | 将内置工具名称映射到 MCP 工具名称，使 Claude 调用您的 MCP 实现来代替内置工具。例如 `{ Bash: 'mcp__workspace__bash' }` |

605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。传递工具名称数组或使用预设以获得 Claude Code 的默认工具 |608| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。传递工具名称数组，或使用预设以获取 Claude Code 的默认工具 |

606| `verbatimPrompts` | `boolean` | `false` | 按写入方式传递每个提示。SDK 使用 `client_composed: true` 发送每个用户消息。参见 [`client_composed`](#sdkusermessage) 了解 Claude Code 在这些消息上跳过的内容。当您的提示文本包含最终用户未输入的内容时使用此选项。对于每轮控制，将其关闭并改为在单个流消息上设置 `client_composed`。需要 TypeScript Agent SDK v0.3.280 或更高版本和 Claude Code v2.1.248 或更高版本；与这些 SDK 版本捆绑的 Claude Code 版本满足 Claude Code 要求 |609| `verbatimPrompts` | `boolean` | `false` | 按原样传递每条提示词。SDK 会以 `client_composed: true` 发送每条用户消息。有关 Claude Code 对这些消息跳过的处理，请参阅 [`client_composed`](#sdkusermessage)。当您的提示词文本包含并非最终用户输入的内容时，请使用此选项。如需按轮次控制，请保持其关闭，并改为在单条流式消息上设置 `client_composed`。需要 TypeScript Agent SDK v0.3.280 或更高版本以及 Claude Code v2.1.248 或更高版本；这些 SDK 版本捆绑的 Claude Code 版本满足 Claude Code 的版本要求 |

607 610

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

609 处理缓慢或停滞的 API 响应612 处理缓慢或停滞的 API 响应

610</h4>613</h4>

611 614

612CLI 子进程读取多个环境变量，这些变量控制 API 超时和停滞检测。通过 `env` 选项传递它们：615CLI 子进程会读取若干控制 API 超时和停滞检测的环境变量。请通过 `env` 选项传递它们：

613 616

614```typescript theme={null}617```typescript theme={null}

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

627});630});

628```631```

629 632

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

631* `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` 并移除此变量的上限。634* `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`，并取消此变量的上限。

632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagents 的停滞监视器。当流监视器打开时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。关闭流监视器时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滞看门狗。当流看门狗开启时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，除非您调高该变量，否则合计为 `600000`。当流看门狗关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。

633 636

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

635* `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 的操作，基于响应进展的程度。638* `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)。

636 639

637 当监视器等待 `ANTHROPIC_BASE_URL` 后面的网关用保活 ping 保持打开的响应时，设置 `includePartialMessages` 的主机继续接收 `ping` [流事件](#sdkpartialassistantmessage)，因此将这些帧读作活跃性而不是在沉默时超时会话。在 v2.1.257 之前，帧在最后一个真实流事件后 5 分钟停止。640 当看门狗等待一个由 `ANTHROPIC_BASE_URL` 背后的网关通过 keep-alive ping 保持打开的响应时，设置了 `includePartialMessages` 的宿主会持续收到 `ping` [流事件](#sdkpartialassistantmessage)，因此请将这些帧视为存活信号，而不是因为静默而使会话超时。在 v2.1.257 之前，这些帧会在最后一个真实流事件 5 分钟后停止。

638 641

639<h3 id="query-object">642<h3 id="query-object">

640 `Query` 对象643 `Query` 对象

696 699

697| 方法 | 描述 |700| 方法 | 描述 |

698| :- | :- |701| :- | :- |

699| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 能力时，使用列出中断到达时待处理的消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |702| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中声明了 `interrupt_receipt_v1` 能力时，会以一个 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 完成，其中列出中断到达时仍处于待处理状态的消息。在 v2.1.205 之前的 CLI 上以 `undefined` 完成 |

700| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。参见[文件检查点](/docs/zh-CN/agent-sdk/file-checkpointing) |703| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 可预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件检查点功能](/docs/zh-CN/agent-sdk/file-checkpointing) |

705| `updateSettings(source, settings)` | 将一个允许列表的键写入项目的本地设置文件或您的用户设置文件，以便该值对后续会话持久化。参见 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |708| `updateSettings(source, settings)` | 将一个允许列表中的键写入项目的本地设置文件或您的用户设置文件，使该值在之后的会话中保持有效。请参阅 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更高版本，其捆绑了 Claude Code v2.1.257 |

707| `reinitialize()` | 重新发送 `initialize` 控制请求到运行的 CLI 并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |710| `reinitialize()` | 向正在运行的 CLI 重新发送 `initialize` 控制请求，并返回新的结果，而不是首次连接时缓存的结果。在传输中断之后（例如断开连接后重新附加到会话）使用它，以便待处理的权限请求再次到达您的 `canUseTool` 回调。请让回调对每个请求 ID 保持幂等，因为响应丢失的请求会被再次分派。需要 Claude Code v2.1.195 或更高版本 |

708| `supportedCommands()` | 返回可用的命令。从 Agent SDK v0.3.216 开始，列表反映中期会话命令更改；参见 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |711| `supportedCommands()` | 返回可用的命令。从 Agent SDK v0.3.216 起，该列表会反映会话中途的命令变更；请参阅 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |

712| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同，使用不出现在消息流中的令牌计数 API 请求计算；参见[这些请求如何处理](#sdkcontrolgetcontextusageresponse)。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |715| `getContextUsage(opts?)` | 返回一个 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具细分会话的上下文窗口使用情况。使用默认的 `detail` 时，其数据与交互式会话中 `/context` 显示的相同，通过不会出现在消息流中的 token 计数 API 请求计算得出；请参阅[这些请求的处理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |

713| `readFile(path, options?)` | 从会话的文件系统读取文件。Claude Code 根据 `cwd` 解析路径；[`readFile()` 可以读取什么](#what-readfile-can-read)列出它提供的文件。传递 `{ maxBytes }` 以更改读取上限（默认 1 MB，上限 10 MB）和 `{ encoding: 'base64' }` 用于二进制文件如图像。使用 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 解决，或在权限拒绝、文件丢失或传输错误时为 `null`。需要 TypeScript SDK v0.2.121 或更高版本 |716| `readFile(path, options?)` | 从会话的文件系统中读取文件。Claude Code 会相对于 `cwd` 解析路径；[`readFile()` 可以读取的内容](#what-readfile-can-read)列出了它可提供的文件。传递 `{ maxBytes }` 可更改读取上限（默认 1 MB，最大 10 MB），对于图像等二进制文件传递 `{ encoding: 'base64' }`。以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 完成；在权限被拒绝、文件不存在或传输错误时以 `null` 完成。需要 TypeScript SDK v0.2.121 或更高版本 |

714| `reloadPlugins(options?)` | 从磁盘重新加载插件，以便您在中期会话安装或编辑的插件到达运行的会话。使用 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 解决，列出会话的命令、subagents、插件和 MCP 服务器状态。需要 Agent SDK v0.2.85 或更高版本。[`holdOnCacheImpact` 选项](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更高版本 |717| `reloadPlugins(options?)` | 从磁盘重新加载插件，使您在会话中途安装或编辑的插件作用于正在运行的会话。以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 完成，其中列出会话的命令、子代理、插件和 MCP 服务器状态。需要 Agent SDK v0.2.85 或更高版本。[`holdOnCacheImpact` 选项](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更高版本 |

715| `reloadSkills()` | 从磁盘重新加载 skills，以便您在中期会话添加或编辑的 skills 对运行的会话可用。使用 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 解决，列出重新加载后可用的 skills。需要 Agent SDK v0.3.163 或更高版本 |718| `reloadSkills()` | 从磁盘重新加载 skill，使您在会话中途添加或编辑的 skill 可供正在运行的会话使用。以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 完成，其中列出重新加载后可用的 skill。需要 Agent SDK v0.3.163 或更高版本 |

716| `reloadOutputStyles()` | 从磁盘重新读取[输出样式](/docs/zh-CN/output-styles)，以便您在中期会话添加或编辑的样式文件对运行的会话可用。使用 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 解决，列出重新加载后可用的样式名称。需要 Agent SDK v0.3.261 或更高版本 |719| `reloadOutputStyles()` | 从磁盘重新读取[输出样式](/docs/zh-CN/output-styles)，使您在会话中途添加或编辑的样式文件可供正在运行的会话使用。以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 完成，其中列出重新加载后可用的样式名称。需要 Agent SDK v0.3.261 或更高版本 |

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

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

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

725 728

726<h4 id="applyflagsettings">729<h4 id="applyflagsettings">

727 `applyFlagSettings()`730 `applyFlagSettings()`

728</h4>731</h4>

729 732

730在运行的会话上更改[设置](/docs/zh-CN/settings)而无需重启查询。当没有专用设置器的设置需要在中期会话更改时使用，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。733在不重启查询的情况下更改正在运行的会话的[设置](/docs/zh-CN/settings)。当某个没有专用设置方法的设置需要在会话中途更改时使用它，例如在 Agent 读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是针对这两个键的专用设置方法；`applyFlagSettings()` 是通用形式，接受设置键的任意子集，在此处传递 `model` 的行为与 `setModel()` 相同。

731 734

732仅某些键在中期会话生效：735只有部分键会在会话中途生效：

733 736

734* **在下一轮应用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 也会在下一轮应用该代理的模型覆盖和 hooks。其系统提示在下一轮应用，或在[重用记录的系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)的会话中，一旦会话被压缩。737* **在下一轮生效**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 还会在下一轮应用该 Agent 的模型覆盖和 hook。其系统提示词在下一轮生效；或者，在[复用已记录系统提示词](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)的会话中，在会话被压缩后生效。

735* **在当前轮应用**：`model`。如果您在 Claude 处理轮次时切换 `model`，Claude 已在生成的响应在旧模型上完成，轮次的其余部分（从 Claude Code 对模型的下一个调用开始）使用新模型。Subagents 保持自己的模型。在 v2.1.212 之前，中期切换等待下一轮。738* **在当前轮次生效**：`model`。如果您在 Claude 处理某一轮时切换 `model`，Claude 正在生成的回复会使用旧模型完成，而该轮的其余部分（从 Claude Code 对模型发起的下一次调用开始）会使用新模型。子代理保留各自的模型。在 v2.1.212 之前，轮次中途的切换会等到下一轮才生效。

736* **中期会话无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，启动新会话。739* **会话中途无效**：系统提示词选项。这些选项在启动时解析一次，因此即使调用成功，正在运行的会话也会保留原始值。要更改它们，请启动新会话。

737 740

738`effortLevel` 接受[努力级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它请求 `xhigh` 努力与[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)打开。`applyFlagSettings()` 声明 `effortLevel` 没有该值，因此在 TypeScript 中传递 `{ ultracode: true, effortLevel: "xhigh" }` 以获得相同结果，或仅 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键以在会话的当前努力级别打开 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。在 v2.1.284 之前，仅 `ultracode` 键也将级别设置为 `xhigh`。741`effortLevel` 接受一个 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它还接受 `"ultracode"`，表示请求 `xhigh` effort 并开启 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)。`applyFlagSettings()` 声明的 `effortLevel` 不包含该值，因此在 TypeScript 中请传递 `{ ultracode: true, effortLevel: "xhigh" }` 以获得相同效果，或者单独传递 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键，以在会话当前的 effort 级别下开启 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，并且只被 `applyFlagSettings()` 接受，设置文件中的 `effortLevel` 键不接受该值。在 v2.1.284 之前，单独传递 `ultracode` 键也会将级别设置为 `xhigh`。

739 742

740值被写入标志设置层，合并到 `query()` 的内联 `settings` 选项在启动时设置的内容上。这与[页面优先级部分](#settings-precedence)调用的编程选项相同的层。743这些值会写入标志设置层，合并在 `query()` 的内联 `settings` 选项于启动时设置的值之上。这与[本页优先级部分](#settings-precedence)所称的编程选项属于同一层级。

741 744

742连续调用浅合并顶级键。第二个调用 `{ permissions: {...} }` 替换来自先前调用的整个 `permissions` 对象，而不是深度合并到其中。745连续调用会对顶层键进行浅合并。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。

743 746

744要清除您使用 `applyFlagSettings()` 设置的键，为该键传递 `null`。大多数键然后首先回退到 `query()` 的 `settings` 选项在启动时设置的值，然后回退到较低优先级源。清除的 `model` 重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)，即使设置文件设置 `model`。传递 `undefined` 无效，因为 JSON 序列化会丢弃它。747要清除通过 `applyFlagSettings()` 设置的键，请为该键传递 `null`。大多数键随后会先回退到 `query()` 的 `settings` 选项在启动时设置的值，然后回退到优先级更低的来源。被清除的 `model` 会重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)，即使设置文件设置了 `model` 也是如此。传递 `undefined` 没有效果，因为 JSON 序列化会将其丢弃。

745 748

746除 `model` 外的三个键重置会话状态而不是回退：749除 `model` 外，还有三个键会重置会话状态，而不是回退：

747 750

748* `effortLevel: null` 将会话返回到模型的默认努力级别，而不是 `query()` 的 `effort` 选项或设置文件中的 `effortLevel`。751* `effortLevel: null` 会将会话恢复为模型的默认 effort 级别，而不是 `query()` 的 `effort` 选项或设置文件中的 `effortLevel`。

749* `agent: null` 从下一轮开始不使用代理运行主线程，而不是恢复 `query()` 的 `agent` 选项或设置文件中的 `agent`。如果清除的代理应用了自己的模型，会话返回到在启动时解决的模型。752* `agent: null` 会从下一轮开始在不使用任何 Agent 的情况下运行主线程，而不是恢复 `query()` 的 `agent` 选项或设置文件中的 `agent`。如果被清除的 Agent 曾应用自己的模型，会话会恢复为启动时解析的模型。

750* `ultracode: null` 关闭 ultracode，如 `false` 一样，而不是恢复设置文件中的 `ultracode` 值。会话保持其当前努力级别，因此在同一调用中传递 `effortLevel` 以更改它。753* `ultracode: null` 会关闭 ultracode（与 `false` 的效果相同），而不是恢复设置文件中的 `ultracode` 值。会话保留其当前的 effort 级别，因此如需更改，请在同一次调用中传递 `effortLevel`。

751 754

752仅在流式输入模式下可用，与 `setModel()` 和 `setPermissionMode()` 相同的约束。755仅在流式输入模式下可用，与 `setModel()` 和 `setPermissionMode()` 的限制相同。

753 756

754下面的示例在中期会话切换活动模型，然后清除覆盖，以便模型重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)。757下面的示例在会话中途切换活动模型，然后清除覆盖，使模型重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)。

755 758

756```typescript theme={null}759```typescript theme={null}

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

766```769```

767 770

768<Note>771<Note>

769 `applyFlagSettings()` 仅限 TypeScript。Python SDK 不公开等效方法。772 `applyFlagSettings()` 仅适用于 TypeScript。Python SDK 未提供等效方法。

770</Note>773</Note>

771 774

772<h4 id="updatesettings">775<h4 id="updatesettings">

773 `updateSettings()`776 `updateSettings()`

774</h4>777</h4>

775 778

776将一个允许列表的键写入磁盘上的设置文件，以便该值对加载该源的后续会话持久化。每个源接受一个键，具有字符串值：779将一个允许列表中的键写入磁盘上的设置文件，使该值在之后加载该来源的会话中保持有效。每个来源接受一个键，值为字符串：

777 780

778* **`"localSettings"`**：接受 `outputStyle` 并将其合并到项目的本地设置文件 `.claude/settings.local.json`。新样式在会话的下一个请求上生效。781* **`"localSettings"`**：接受 `outputStyle`，并将其合并到项目的本地设置文件 `.claude/settings.local.json` 中。新样式会在会话的下一次请求时生效。

779* **`"userSettings"`**：接受 `effortLevel` 并将其保存为会话当前模型的默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，在您的用户设置文件中的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下。传递 `max` 不写任何内容，因为 `max` 仅限会话。运行的会话无论如何都保持其当前努力级别，因此当您也想更改那个时调用 [`applyFlagSettings()`](#applyflagsettings)。此源需要 TypeScript SDK v0.3.277 或更高版本，它捆绑 Claude Code v2.1.277。782* **`"userSettings"`**：接受 `effortLevel`，并将其保存为会话当前模型的默认 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)，位于您用户设置文件的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下。传递 `max` 不会写入任何内容，因为 `max` 仅限会话使用。无论哪种情况，正在运行的会话都会保留其当前的 effort 级别，因此如果您也想更改它，请调用 [`applyFlagSettings()`](#applyflagsettings)。此来源需要 TypeScript SDK v0.3.277 或更高版本，其捆绑了 Claude Code v2.1.277。

780 783

781当请求携带任何其他键、会话在远程传输上运行以及会话的 [`settingSources`](#options) 排除您命名的源时，调用拒绝。不支持删除键。784当请求携带任何其他键、会话通过远程传输运行，或会话的 [`settingSources`](#options) 排除了您指定的来源时，调用会被拒绝。不支持删除键。

782 785

783<h4 id="togglemcpserver">786<h4 id="togglemcpserver">

784 `toggleMcpServer()`787 `toggleMcpServer()`

785</h4>788</h4>

786 789

787禁用服务器会断开其连接，并从会话中移除其工具。对于您在会话中途添加的服务器和进程内服务器，这取决于您的 Claude Code 版本：790禁用服务器会断开其连接并从会话中移除其工具。对于您在会话中途添加的服务器和进程内服务器，这取决于您的 Claude Code 版本：

788 791

789* 您在会话中途通过 `setMcpServers()` 添加的 stdio、SSE 或 HTTP 服务器：移除其工具需要 Claude Code v2.1.285 或更高版本。792* 您在会话中途通过 `setMcpServers()` 添加的 stdio、SSE 或 HTTP 服务器：移除其工具需要 Claude Code v2.1.285 或更高版本。

790* 您通过 [`createSdkMcpServer()`](#createsdkmcpserver) 创建的进程内服务器，无论您是在 `mcpServers` 中还是通过 `setMcpServers()` 传入：断开其连接并移除其工具需要 Claude Code v2.1.286 或更高版本。禁用此类服务器还会使其仍在运行的工具调用失败，因此 Claude 会立即收到每个调用的错误结果，而无需等待您的处理程序返回。793* 您通过 [`createSdkMcpServer()`](#createsdkmcpserver) 创建的进程内服务器，无论是通过 `mcpServers` 还是 `setMcpServers()` 传递：断开其连接并移除其工具需要 Claude Code v2.1.286 或更高版本。禁用此类服务器还会使其仍在运行的工具调用失败，因此 Claude 会立即收到每个调用的错误结果，而无需等待您的处理程序返回。

791 794

792<h3 id="warmquery">795<h3 id="warmquery">

793 `WarmQuery`796 `WarmQuery`

794</h3>797</h3>

795 798

796由 [`startup()`](#startup) 返回的句柄。子进程已生成并初始化，因此在此句柄上调用 `query()` 将提示直接写入准备好的进程，无启动延迟。799由 [`startup()`](#startup) 返回的句柄。子进程已经生成并完成初始化，因此在此句柄上调用 `query()` 会将提示词直接写入已就绪的进程，没有启动延迟。

797 800

798```typescript theme={null}801```typescript theme={null}

799interface WarmQuery extends AsyncDisposable {802interface WarmQuery extends AsyncDisposable {

808 811

809| 方法 | 描述 |812| 方法 | 描述 |

810| :- | :- |813| :- | :- |

813 816

814`WarmQuery` 实现 `AsyncDisposable`，因此可以与 `await using` 一起使用以自动清理。817`WarmQuery` 实现了 `AsyncDisposable`，因此可以与 `await using` 一起使用以实现自动清理。

815 818

816<h3 id="spareprocess">819<h3 id="spareprocess">

817 `SpareProcess`820 `SpareProcess`

818</h3>821</h3>

819 822

820*Alpha.* 由 [`prewarm()`](#prewarm) 返回的句柄：一个已启动但尚未绑定到会话的 Claude Code 进程，可以声明一次。需要 TypeScript Agent SDK v0.3.282 或更高版本。823*Alpha。* 由 [`prewarm()`](#prewarm) 返回的句柄：一个已启动但尚未绑定到会话的 Claude Code 进程，可以被认领一次。需要 TypeScript Agent SDK v0.3.282 或更高版本。

821 824

822```typescript theme={null}825```typescript theme={null}

823interface SpareProcess extends AsyncDisposable {826interface SpareProcess extends AsyncDisposable {

837 840

838| 成员 | 描述 |841| 成员 | 描述 |

839| :- | :- |842| :- | :- |

840| `claim({ prompt, options })` | 将备用绑定到 `options.cwd` 中的会话并发送其第一条消息。同步返回 [`Query`](#query-object)，如 `query()` 一样。每个 `SpareProcess` 只能调用一次 |843| `claim({ prompt, options })` | 将备用进程绑定到 `options.cwd` 中的会话并发送其第一条消息。与 `query()` 一样同步返回一个 [`Query`](#query-object)。只能调用一次 |

841| `claimed` | 一旦 Claude Code 接受声明就使用会话的工作目录和 ID 解决。当 Claude Code 拒绝声明、进程在声明前退出或关闭时拒绝，以及当会话运行时不带您请求的 `model` 或 `maxThinkingTokens` 时，消息以 `option_not_applied` 开头拒绝 |844| `claimed` | 在 Claude Code 接受认领后，以会话的工作目录和 ID 完成。在以下情况下拒绝：Claude Code 拒绝认领；进程先已退出或被关闭；以及会话在未使用您所请求的 `model` 或 `maxThinkingTokens` 的情况下运行（此时消息以 `option_not_applied` 开头） |

844 847

845`options.cwd` 是必需的。声明也可以设置 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的标志设置覆盖、`appendSystemPrompt`、`title`、`agents` 和 `env` 中的每个会话令牌。848`options.cwd` 为必填项。认领还可以设置 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的标志设置覆盖层、`appendSystemPrompt`、`title`、`agents`，以及 `env` 中的每会话令牌。

846 849

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

848 851

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

850 `SDKControlInitializeResponse`853 `SDKControlInitializeResponse`

874};877};

875```878```

876 879

877`hooks_applied` 报告 Claude Code 是否注册了 `initialize` 请求携带的 `hooks`。SDK 在会话启动时发送该请求一次，在每个 [`reinitialize()`](#query-object) 调用上再次发送。该字段需要 Agent SDK v0.3.238 或更高版本。880`hooks_applied` 报告 Claude Code 是否注册了 `initialize` 请求所携带的 `hooks`。SDK 会在会话启动时发送一次该请求，并在每次调用 [`reinitialize()`](#query-object) 时再次发送。该字段需要 Agent SDK v0.3.238 或更高版本。

878 881

879当请求不携带 hooks 时，Claude Code 省略该字段。当请求携带 hooks 时，值取决于请求是否是会话的第一个初始化，以及对于重复的，它如何到达会话：882当请求未携带 hook 时，Claude Code 会省略该字段。当请求携带了 hook 时，其值取决于该请求是否为会话的首次 initialize，以及对于重复的 initialize，它是如何到达会话的：

880 883

881* `true`：Claude Code 注册了 hooks。会话的第一个初始化返回此值。通过 CLI 的 stdin 发送的重复初始化也返回 `true`。在这种情况下，新请求中的 hooks 替换之前注册的 hooks。884* `true`：Claude Code 注册了这些 hook。会话的首次 initialize 返回此值。通过 CLI 的 stdin 发送的重复 initialize 也返回 `true`。在这种情况下，新请求中的 hook 会替换先前注册的 hook。

882* `false`：Claude Code 忽略了 hooks。发送到远程会话的重复初始化返回此值，因此加入会话的第二个客户端无法替换第一个客户端注册的 hooks。885* `false`：Claude Code 忽略了这些 hook。发送到远程会话的重复 initialize 返回此值，因此加入会话的第二个客户端无法替换第一个客户端注册的 hook。

883 886

884在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。887在 Agent SDK v0.3.238 之前，响应从不携带该字段，并且 Claude Code 在每次重复 initialize 时都会忽略 `hooks`。

885 888

886请求的 `sdkMcpServerManifests` 字段和响应的 `sdk_mcp_manifests_parked` 字段用于您通过 [`createSdkMcpServer()`](#createsdkmcpserver) 创建的进程内 [SDK MCP 服务器](/docs/zh-CN/agent-sdk/custom-tools)。您的应用不会设置或读取这两个字段。889请求的 `sdkMcpServerManifests` 字段和响应的 `sdk_mcp_manifests_parked` 字段用于您通过 [`createSdkMcpServer()`](#createsdkmcpserver) 创建的进程内 [SDK MCP 服务器](/docs/zh-CN/agent-sdk/custom-tools)。您的应用不需要设置或读取这两个字段。

887 890

888响应始终报告 `fast_mode_state`，当某些东西阻止[快速模式](/docs/zh-CN/fast-mode)时，`fast_mode_disabled_reason` 在其旁边携带原因代码，以便您可以解释阻止的状态而不是重新推导可用性。两种行为都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，当快速模式不可用时响应省略 `fast_mode_state`，从不携带原因。有关原因代码及其含义，参见结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。891响应始终会报告 `fast_mode_state`，并且当有因素阻止[快速模式](/docs/zh-CN/fast-mode)时，`fast_mode_disabled_reason` 会随之携带原因代码，因此您可以解释被阻止的状态，而无需重新推断可用性。这两种行为都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，当快速模式不可用时，响应会省略 `fast_mode_state`，并且从不携带原因。有关原因代码及其含义，请参阅结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。

889 892

890成功 `initialize` 的控制响应包装器也携带 `pending_permission_requests` 数组。该字段在响应包装器本身上，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流的相同 `{ type: "control_request", request_id, request }` 形状。893成功的 `initialize` 的控制响应包装器还携带一个 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不在上述 `SDKControlInitializeResponse` 负载中。每个条目都是一条完整的 `control_request` 消息，其 `{ type: "control_request", request_id, request }` 结构与会话运行期间为权限请求流式发送的结构相同。

891 894

892数组列出此 Claude Code 进程已发出且尚未解决的权限请求。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新传递。幂等处理重复的请求 ID，因为条目可以重复回调已在连接断开前接收的请求。895该数组列出此 Claude Code 进程已发出但尚未解决的权限请求。SDK 会为您读取该数组，并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输中断后触发的重新投递相同。请以幂等方式处理重复的请求 ID，因为某个条目可能重复了回调在连接断开前已收到的请求。

893 896

894数组在成功 `initialize` 响应上始终存在，当此进程没有未解决的权限请求时为空。需要 Claude Code v2.1.268 或更高版本。较早的版本可能省略该字段，因此如果您自己解析线路协议，将缺失字段视为较旧的 CLI 而不是没有待处理的证明。897该数组在成功的 `initialize` 响应中始终存在，当此进程没有未解决的权限请求时为空。需要 Claude Code v2.1.268 或更高版本。更早的版本可能会省略该字段，因此如果您自行解析线路协议，请将缺失该字段视为较旧的 CLI，而不是视为没有待处理请求的证据。

895 898

896<h3 id="sdkcontrolinterruptresponse">899<h3 id="sdkcontrolinterruptresponse">

897 `SDKControlInterruptResponse`900 `SDKControlInterruptResponse`

898</h3>901</h3>

899 902

900中断收据：[`interrupt()`](#query-object) 在通告 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中 `interrupt_receipt_v1` 能力的 CLI 上解决的值。需要 Claude Code v2.1.205 或更高版本。较早的 CLI 使用空成功有效负载回答中断，因此 `interrupt()` 解决为 `undefined`。903中断回执：在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中声明了 `interrupt_receipt_v1` 能力的 CLI 上，[`interrupt()`](#query-object) 完成时返回的值。需要 Claude Code v2.1.205 或更高版本。更早的 CLI 会以空的成功负载响应中断，因此 `interrupt()` 会以 `undefined` 完成。

901 904

902```typescript theme={null}905```typescript theme={null}

903type SDKControlInterruptResponse = {906type SDKControlInterruptResponse = {

906};909};

907```910```

908 911

909`still_queued` 列出中断到达时待处理的用户消息的 UUID：仍在队列中的消息，加上 Claude Code 已从队列中取出用于下一轮的任何消息。一旦会话的第一轮开始，Claude Code 在中断后处理列出的消息，除非您首先取消它们，并可以将多个合并为一轮。如果您在第一轮开始前中断，Claude Code 在轮次开始时立即中止它，该轮次中列出的消息不会获得响应。912`still_queued` 列出中断到达时仍处于待处理状态的用户消息的 UUID：仍在队列中的消息，以及 Claude Code 已从队列中取出准备用于下一轮的消息。一旦会话的第一轮已经开始，除非您先取消，否则 Claude Code 会在中断之后处理列出的消息，并且可能将多条消息合并为一轮。如果您在第一轮开始之前中断，Claude Code 会在该轮开始后立即中止它，该轮中列出的消息将不会得到回复。

910 913

911使用收据决定是否重新发送任何内容。未取消的列出消息进入对话，无论是否获得响应，因此重新发送它会将其传递给 Claude 两次。914请使用回执来决定是否需要重新发送任何内容。未被您取消的列出消息无论是否得到回复都会进入对话，因此重新发送会使其两次传递给 Claude。

912 915

913使用这些注意事项解释列表：916解读该列表时请注意以下事项：

914 917

915* 仅出现使用 UUID 入队的消息。空数组不意味着没有其他内容会运行。918* 只有带 UUID 入队的消息才会出现。空数组并不意味着不会再运行其他内容。

916* 仅列出主线程消息。寻址到 subagent 的消息超出范围。919* 只列出主线程消息。发送给子代理的消息不在范围内。

917* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/docs/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID 而不是将其视为错误。920* 列表可能包含您的客户端从未发送过的 UUID，例如[定时任务](/docs/zh-CN/scheduled-tasks)触发器。请忽略您无法识别的 UUID，而不是将其视为错误。

918 921

919直接驱动 CLI 控制协议的客户端（而不是通过 `interrupt()`）可以在 `interrupt` 控制请求上设置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中使用 `interrupt_cancel_queued_v1` 能力通告支持；较早的 CLI 忽略该字段并让排队的消息照常运行。这样的中断也取消每条会否则在 `still_queued` 下列出的消息：收据在 `cancelled` 下列出它们，`still_queued` 为空，它们都不运行。922直接驱动 CLI 控制协议（而不是通过 `interrupt()`）的客户端可以在 `interrupt` 控制请求上设置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本通过 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中的 `interrupt_cancel_queued_v1` 能力声明支持；较旧的 CLI 会忽略该字段，并照常运行排队的消息。这样的中断还会取消原本会列在 `still_queued` 下的每条消息：回执改为将它们列在 `cancelled` 下，`still_queued` 为空，并且这些消息都不会运行。

920 923

921`cancelled` 列表携带与 `still_queued` 相同的注意事项。`interrupt()` 方法从不发送 `cancel_queued`，因此它解决的收据不携带 `cancelled`。924`cancelled` 列表的注意事项与 `still_queued` 相同。`interrupt()` 方法从不发送 `cancel_queued`，因此它完成时返回的回执不携带 `cancelled`。

922 925

923收据是处理中断时的快照，在干净中断上它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。读取收据而不是在该结果后检查队列：循环立即启动下一个排队轮次，因此您在结果后检查的队列已更改。926回执是在处理中断时拍摄的快照，在干净的中断中，它会在被中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。请读取回执，而不是在该结果之后检查队列：循环会立即开始下一个排队的轮次，因此您在结果之后检查的队列已经发生了变化。

924 927

925<h3 id="sdkcontrolgetcontextusageresponse">928<h3 id="sdkcontrolgetcontextusageresponse">

926 `SDKControlGetContextUsageResponse`929 `SDKControlGetContextUsageResponse`

927</h3>930</h3>

928 931

929[`getContextUsage()`](#query-object) 的返回类型。使用默认 `detail`，这是 Claude Code 在交互式会话中为 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段如 `color` 和 `gridRows`，Claude Code 使用这些字段绘制 `/context` 使用网格。932[`getContextUsage()`](#query-object) 的返回类型。使用默认的 `detail` 时，这与 Claude Code 在交互式会话中为 `/context` 命令渲染的负载相同，因此除 token 计数外，它还携带 `color` 和 `gridRows` 等显示字段，Claude Code 使用这些字段绘制 `/context` 用量网格。

930 933

931方法的可选 `detail` 参数选择 Claude Code 如何计数每个类别。`detail` 参数需要 Agent SDK v0.3.257 或更高版本。934该方法的可选 `detail` 参数决定 Claude Code 如何统计每个类别。`detail` 参数需要 Agent SDK v0.3.257 或更高版本。

932 935

933* **`'full'`**：默认值。Claude Code 使用[令牌计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 请求计数每个类别。这些请求不出现在消息流中，因此读取流的成本跟踪不会看到它们。在 Anthropic API 上，令牌计数不计费。936* **`'full'`**：默认值。Claude Code 使用 [token 计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 请求统计每个类别。这些请求不会出现在消息流中，因此读取消息流的成本跟踪不会看到它们。在 Anthropic API 上，token 计数不收费。

934* **`'summary'`**：传递 `{ detail: 'summary' }` 以从最后一个响应的使用情况和本地估计获得答案。没有令牌计数请求出去，每个类别的数字是近似的。937* **`'summary'`**：传递 `{ detail: 'summary' }` 以改为根据上一次响应的用量和本地估算得出结果。不会发出任何 token 计数请求，各类别的数值为近似值。

935 938

936当您发送 `/context` 作为提示而不是调用方法时，Claude Code 将 [`SDKContextUsage`](#sdkcontextusage) 有效负载附加到传递结果的助手消息的 `context_usage` 字段。该字段需要 Agent SDK v0.3.232 或更高版本。939当您将 `/context` 作为提示词发送而不是调用该方法时，Claude Code 会将一个 [`SDKContextUsage`](#sdkcontextusage) 负载附加到传递结果的 assistant 消息的 `context_usage` 字段。该字段需要 Agent SDK v0.3.232 或更高版本。

937 940

938```typescript theme={null}941```typescript theme={null}

939type SDKControlGetContextUsageResponse = {942type SDKControlGetContextUsageResponse = {

1030};1033};

1031```1034```

1032 1035

1033从集合字段读取令牌归属：1036从集合字段中读取 token 归属：

1034 1037

1035* `categories` 保存每个类别的总计。每个条目的 `kind` 使用与 [`SDKContextUsageCategory`](#sdkcontextusagecategory) 相同的值对行进行分类。在其上对行进行分类而不是在显示 `name` 上。该字段需要 Agent SDK v0.3.268 或更高版本。1038* `categories` 保存各类别的总计。每个条目的 `kind` 使用与 [`SDKContextUsageCategory`](#sdkcontextusagecategory) 相同的值对该行进行分类。请依据它而不是显示用的 `name` 来对行进行分类。该字段需要 Agent SDK v0.3.268 或更高版本。

1036* `mcpTools` 和 `agents` 将令牌归属于单个 MCP 工具和 subagents。1039* `mcpTools` 和 `agents` 将 token 归属到各个 MCP 工具和子代理。

1037* `memoryFiles` 列出每个加载的内存文件及其成本。1040* `memoryFiles` 列出每个已加载的记忆文件及其开销。

1038* `skills.skillFrontmatter` 将 skill 列表的令牌归属于每个包含的 skill。每个 skill 的计数测量每个 skill 的列表条目，因为 Claude Code 实际发送它，可能比 skill 的完整前言更短。比较 `skills.totalSkills` 与 `skills.includedSkills` 以查看是否每个发现的 skill 都进入了列表。1041* `skills.skillFrontmatter` 将 skill 列表的 token 归属到每个被包含的 skill。每个 skill 的计数衡量的是 Claude Code 实际发送的该 skill 列表条目，可能比该 skill 的完整 frontmatter 更短。比较 `skills.totalSkills` 与 `skills.includedSkills`，可查看是否每个发现的 skill 都进入了列表。

1039 1042

1040`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是使用情况测量的窗口。该窗口是模型的上下文窗口，或应用自动压缩时的较低自动压缩窗口。`rawMaxTokens` 携带与 `maxTokens` 相同的值，`percentage` 是 `totalTokens` 作为该窗口的四舍五入百分比。`apiUsage` 保存最新 API 响应的使用情况，而不是会话的运行总计。1043`totalTokens` 是会话当前的上下文用量，`maxTokens` 是衡量该用量所依据的窗口。该窗口是模型的上下文窗口，或者在适用时为更低的自动压缩窗口。`rawMaxTokens` 与 `maxTokens` 的值相同，`percentage` 是 `totalTokens` 占该窗口的百分比（四舍五入）。`apiUsage` 保存最近一次 API 响应的用量，而不是会话的累计总量。

1041 1044

1042Claude Code 保留可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 诊断未设置，因此即使类型声明它们也期望它们不存在。1045Claude Code 不会设置可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 诊断字段，因此即使类型中声明了它们，也应预期它们不存在。

1043 1046

1044<h3 id="sdkcontrolreadfileresponse">1047<h3 id="sdkcontrolreadfileresponse">

1045 `SDKControlReadFileResponse`1048 `SDKControlReadFileResponse`

1056};1059};

1057```1060```

1058 1061

1059`contents` 保存文件文本，或当您请求 `encoding: 'base64'` 时的 base64 数据；响应的 `encoding` 字段在这种情况下设置为 `'base64'`。`absPath` 是解决的绝对路径。`truncated` 在文件长于 `maxBytes` 上限且内容在该限制处被切割时设置。1062`contents` 保存文件文本；当您请求 `encoding: 'base64'` 时则保存 base64 数据，此时响应的 `encoding` 字段会被设置为 `'base64'`。`absPath` 是解析后的绝对路径。当文件长度超过 `maxBytes` 上限且内容在该限制处被截断时，会设置 `truncated`。

1060 1063

1061<h4 id="what-readfile-can-read">1064<h4 id="what-readfile-can-read">

1062 `readFile()` 可以读取什么1065 `readFile()` 可以读取的内容

1063</h4>1066</h4>

1064 1067

1065`readFile()` 提供的文件集比 Read 工具更窄：1068`readFile()` 提供的文件范围比 Read 工具更窄：

1066 1069

1067* 会话工作目录之一内的常规文件，例如 `cwd` 和 `additionalDirectories`1070* 位于会话某个工作目录（例如 `cwd` 和 `additionalDirectories`）内的常规文件

1068* Claude Code 自己的一些文件用于会话，例如工具结果1071* Claude Code 为该会话保存的少量自身文件，例如工具结果

1069 1072

1070Read 拒绝和询问规则仍会阻止匹配的路径，广泛的 Read allow 规则不会向 `readFile()` 打开文件系统的其余部分。对于任何其他内容，调用使用 `null` 解决。1073`Read` 的拒绝和询问规则仍会阻止匹配的路径，而宽泛的 `Read` 允许规则不会向 `readFile()` 开放文件系统的其余部分。对于其他任何内容，调用都会以 `null` 完成。

1071 1074

1072<h3 id="sdkcontrolreloadpluginsresponse">1075<h3 id="sdkcontrolreloadpluginsresponse">

1073 `SDKControlReloadPluginsResponse`1076 `SDKControlReloadPluginsResponse`

1096};1099};

1097```1100```

1098 1101

1099集合字段描述调用后的会话：1102集合字段描述调用之后的会话：

1100 1103

1101* `commands`、`agents` 和 `mcpServers`：会话的命令、subagents 和 MCP 服务器状态，采用 `supportedCommands()`、`supportedAgents()` 和 `mcpServerStatus()` 返回的相同形状。`supportedAgents()` 继续返回在初始化时捕获的列表，因此在此处读取 `agents` 以获得重新加载后的集合1104* `commands`、`agents` 和 `mcpServers`：会话的命令、子代理和 MCP 服务器状态，其结构与 `supportedCommands()`、`supportedAgents()` 和 `mcpServerStatus()` 返回的结构相同。`supportedAgents()` 会继续返回初始化时捕获的列表，因此要获取重新加载后的集合，请在此处读取 `agents`

1102* `plugins`：每个加载的插件及其 `name` 和安装 `path`。`version` 重复插件的清单声明的内容，是插件作者控制的，因此在信任前验证它。当清单未声明任何内容时省略1105* `plugins`：每个已加载的插件及其 `name` 和安装 `path`。`version` 复述插件清单中声明的内容，由插件作者控制，因此在信任之前请先验证。当清单未声明版本时会省略该字段

1103* `error_count`：加载插件的错误数1106* `error_count`：加载插件时产生的错误数量

1104 1107

1105传递 `{ holdOnCacheImpact: true }` 到 `reloadPlugins()` 以保持会使对话的提示缓存失效的重新加载，而不是应用它。Claude Code 运行交互式 `/reload-plugins` 命令在[警告缓存成本](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)前进行的检查。该选项需要 Agent SDK v0.3.268 或更高版本。比 v2.1.268 旧的 Claude Code 可执行文件，例如您指向 `pathToClaudeCodeExecutable` 的，忽略该选项并应用重新加载。1108向 `reloadPlugins()` 传递 `{ holdOnCacheImpact: true }`，可在重新加载会使对话的提示缓存失效时将其挂起而不应用。Claude Code 会运行交互式 `/reload-plugins` 命令在[警告缓存开销](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)之前所做的检查。该选项需要 Agent SDK v0.3.268 或更高版本。早于 v2.1.268 的 Claude Code 可执行文件（例如您通过 `pathToClaudeCodeExecutable` 指向的可执行文件）会忽略该选项并应用重新加载。

1106 1109

1107当您传递选项时，读取 `held` 以了解发生了什么：1110传递该选项后，请读取 `held` 以了解发生了什么：

1108 1111

1109* `true`：重新加载未应用，集合字段描述会话仍然是什么。`cache_impact` 说应用会改变什么。要无论如何应用，再次调用 `reloadPlugins()` 而不使用选项。1112* `true`：重新加载未被应用，集合字段描述的是会话的当前状态。`cache_impact` 说明应用后会发生哪些变化。如果仍要应用，请在不带该选项的情况下再次调用 `reloadPlugins()`。

1110* `false`：检查发现没有缓存影响，重新加载已应用。1113* `false`：检查未发现缓存影响，重新加载已被应用。

1111* 不存在：您未传递选项，或 Claude Code 可执行文件比 v2.1.268 旧并应用了重新加载。1114* 不存在：您没有传递该选项，或者 Claude Code 可执行文件早于 v2.1.268 并已应用重新加载。

1112 1115

1113`cache_impact` 仅与 `held: true` 一起存在。`mcp_servers_added` 和 `mcp_servers_removed` 命名重新加载会注册或删除的插件 MCP 服务器，作为作用域 `plugin:<plugin>:<server>` 名称。名称是插件作者编写的，因此在显示前验证它们。`lsp_tool_change` 说应用是否会添加或移除 LSP 工具，或 `null` 当它都不做时。`may-` 形式意味着检查无法完全看到待处理的插件集。1116`cache_impact` 仅与 `held: true` 一同出现。`mcp_servers_added` 和 `mcp_servers_removed` 以限定的 `plugin:<plugin>:<server>` 名称列出重新加载将注册或移除的插件 MCP 服务器。这些名称由插件作者编写，因此在显示之前请先验证。`lsp_tool_change` 说明应用后是否会添加或移除 LSP 工具，如果两者都不会发生则为 `null`。`may-` 形式表示检查无法完全看到待处理的插件集合。

1114 1117

1115<h3 id="sdkcontrolreloadskillsresponse">1118<h3 id="sdkcontrolreloadskillsresponse">

1116 `SDKControlReloadSkillsResponse`1119 `SDKControlReloadSkillsResponse`

1124};1127};

1125```1128```

1126 1129

1127`skills` 列出重新加载后可用的 skills，采用 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 形状。1130`skills` 以与 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 结构列出重新加载后可用的 skill。

1128 1131

1129<h3 id="sdkcontrolreloadoutputstylesresponse">1132<h3 id="sdkcontrolreloadoutputstylesresponse">

1130 `SDKControlReloadOutputStylesResponse`1133 `SDKControlReloadOutputStylesResponse`

1158};1161};

1159```1162```

1160 1163

1161传递 `readMcpResource()` 服务器名称如 `mcpServerStatus()` 报告的和 `ui://` URI，例如工具在其 [`_meta`](#mcpserverstatus) 中声明的 `ui.resourceUri`。调用对任何其他 URI 方案拒绝，对于您的应用自己托管的 [SDK MCP 服务器](#createsdkmcpserver)，以及对于未连接的服务器。当初始化消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 时可用。1164向 `readMcpResource()` 传递 `mcpServerStatus()` 所报告的服务器名称以及一个 `ui://` URI，例如工具在其 [`_meta`](#mcpserverstatus) 中声明的 `ui.resourceUri`。对于任何其他 URI 方案、您的应用自行托管的 [SDK MCP 服务器](#createsdkmcpserver)以及未连接的服务器，调用都会被拒绝。当 init 消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 时可用。

1162 1165

1163每个 `contents` 条目是服务器发送的一个内容项，减去 `com.anthropic/` 前缀下的任何 `_meta` 键，这是为 Claude Code 保留的。`blob` 为二进制项保存 base64 数据，`_meta` 是项目自己的 `_meta`，MCP Apps 服务器在其中放置资源的 `ui.csp` 和 `ui.permissions`。1166每个 `contents` 条目都是服务器发送的一个内容项，但会去掉 `com.anthropic/` 前缀下的任何 `_meta` 键，该前缀保留给 Claude Code 使用。`blob` 保存二进制项的 base64 数据，`_meta` 是该项自身的 `_meta`，MCP Apps 服务器会在其中放置资源的 `ui.csp` 和 `ui.permissions`。

1164 1167

1165内容是不受信任的第三方 HTML，因此在沙箱中呈现它们。1168这些内容是不受信任的第三方 HTML，因此请在沙箱中渲染它们。

1166 1169

1167<h3 id="agentdefinition">1170<h3 id="agentdefinition">

1168 `AgentDefinition`1171 `AgentDefinition`

1169</h3>1172</h3>

1170 1173

1171以编程方式定义的 subagent 的配置。1174以编程方式定义的子代理的配置。

1172 1175

1173```typescript theme={null}1176```typescript theme={null}

1174type AgentDefinition = {1177type AgentDefinition = {

1192 1195

1193| 字段 | 必需 | 描述 |1196| 字段 | 必需 | 描述 |

1194| :- | :- | :- |1197| :- | :- | :- |

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

1196| `tools` | 否 | 允许的工具名称数组。如果省略，继承[可用于 subagents 的每个工具](/docs/zh-CN/sub-agents#available-tools)。要将 Skills 预加载到代理的上下文中，使用 `skills` 字段而不是在此处列出 `'Skill'` |1199| `tools` | 否 | 允许的工具名称数组。如果省略，则继承所有[子代理可用的工具](/docs/zh-CN/sub-agents#available-tools)。要将 Skills 预加载到 Agent 的上下文中，请使用 `skills` 字段，而不是在此处列出 `'Skill'` |

1197| `disallowedTools` | 否 | 要为此代理明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |1200| `disallowedTools` | 否 | 要为此 Agent 明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 会移除该服务器的所有工具，`mcp__*` 会移除任何服务器的所有 MCP 工具 |

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

1199| `model` | 否 | 此代理的模型覆盖。接受别名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 或完整模型 ID。`'inherit'` 使用主模型。当您省略它时，Claude Code 在[subagent 模型顺序](/docs/zh-CN/sub-agents#choose-a-model)中选择模型 |1202| `model` | 否 | 此 Agent 的模型覆盖。接受 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 等别名，或完整的模型 ID。`'inherit'` 使用主模型。省略时，Claude Code 会按照[子代理模型顺序](/docs/zh-CN/sub-agents#choose-a-model)选择模型 |

1200| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |1203| `mcpServers` | 否 | 此 Agent 的 MCP 服务器规范 |

1201| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |1204| `skills` | 否 | 要预加载到 Agent 上下文中的 skill 名称数组 |

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

1203| `maxTurns` | 否 | 停止前的最大代理轮次数（API 往返） |1206| `maxTurns` | 否 | 停止前的最大 agentic 轮次数（API 往返次数） |

1204| `background` | 否 | 当调用时作为非阻止后台任务运行此代理 |1207| `background` | 否 | 被调用时将此 Agent 作为非阻塞的后台任务运行 |

1205| `omitClaudeMd` | 否 | 当作为 subagent 运行时不使用用户、项目和本地 CLAUDE.md 文件运行此代理；托管策略文件仍加载。用于从 Agent 工具提示获取所需一切的代理。当此代理作为主线程代理运行时忽略。需要 TypeScript Agent SDK v0.3.271 或更高版本 |1208| `omitClaudeMd` | 否 | 当此 Agent 作为子代理运行时，不加载用户、项目和本地 CLAUDE.md 文件；托管策略文件仍会加载。适用于从 Agent 工具提示词中获取所需全部内容的 Agent。当此 Agent 作为主线程 Agent 运行时忽略。需要 TypeScript Agent SDK v0.3.271 或更高版本 |

1206| `memory` | 否 | 此代理的内存源：`'user'`、`'project'` 或 `'local'` |1209| `memory` | 否 | 此 Agent 的记忆来源：`'user'`、`'project'` 或 `'local'` |

1207| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |1210| `effort` | 否 | 此 Agent 的推理 effort 级别。接受命名级别或整数 |

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

1209| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示的关键提醒 |1212| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示词中的关键提醒 |

1210 1213

1211<h3 id="agentmcpserverspec">1214<h3 id="agentmcpserverspec">

1212 `AgentMcpServerSpec`1215 `AgentMcpServerSpec`

1213</h3>1216</h3>

1214 1217

1215指定可用于 subagent 的 MCP 服务器。可以是服务器名称（引用父级 `mcpServers` 配置中的服务器的字符串）或内联服务器配置记录，将服务器名称映射到配置。1218指定子代理可用的 MCP 服务器。可以是服务器名称（引用父级 `mcpServers` 配置中某个服务器的字符串），也可以是将服务器名称映射到配置的内联服务器配置记录。

1216 1219

1217```typescript theme={null}1220```typescript theme={null}

1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1221type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1219```1222```

1220 1223

1222 1225

1223<h3 id="settingsource">1226<h3 id="settingsource">

1224 `SettingSource`1227 `SettingSource`

1225</h3>1228</h3>

1226 1229

1227控制 SDK 加载设置的基于文件系统的配置源。1230控制 SDK 从哪些基于文件系统的配置来源加载设置。

1228 1231

1229```typescript theme={null}1232```typescript theme={null}

1230type SettingSource = "user" | "project" | "local";1233type SettingSource = "user" | "project" | "local";

1233| 值 | 描述 | 位置 |1236| 值 | 描述 | 位置 |

1234| :- | :- | :- |1237| :- | :- | :- |

1238 1241

1239<h4 id="default-behavior">1242<h4 id="default-behavior">

1240 默认行为1243 默认行为

1241</h4>1244</h4>

1242 1245

1243当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。参见[`settingSources` 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都读取的输入，以及如何禁用它们。1246当省略 `settingSources` 或其为 `undefined` 时，`query()` 会加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地设置。有关无论此选项如何都会读取的输入以及如何禁用它们，请参阅 [settingSources 不控制的内容](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)。

1244 1247

1245<h4 id="why-use-settingsources">1248<h4 id="why-use-settingsources">

1246 为什么使用 settingSources1249 为什么使用 settingSources

1258});1261});

1259```1262```

1260 1263

1261**仅加载特定设置源：**1264**仅加载特定的设置来源：**

1262 1265

1263```typescript theme={null}1266```typescript theme={null}

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

1272});1275});

1273```1276```

1274 1277

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

1276 1279

1277<h4 id="settings-precedence">1280<h4 id="settings-precedence">

1278 设置优先级1281 设置优先级

1279</h4>1282</h4>

1280 1283

1281当加载多个源时，设置以此优先级合并（最高到最低）：1284当加载多个来源时，设置按以下优先级合并（从高到低）：

1282 1285

12831. 本地设置（`.claude/settings.local.json`）12861. 本地设置（`.claude/settings.local.json`）

12842. 项目设置（`.claude/settings.json`）12872. 项目设置（`.claude/settings.json`）

12853. 用户设置（`~/.claude/settings.json`）12883. 用户设置（`~/.claude/settings.json`）

1286 1289

1287编程选项如 `agents`、`allowedTools` 和 `settings` 覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。1290`agents`、`allowedTools` 和 `settings` 等编程选项会覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。

1288 1291

1289<h3 id="permissionmode">1292<h3 id="permissionmode">

1290 `PermissionMode`1293 `PermissionMode`

1306 1309

1307用于控制工具使用的自定义权限函数类型。1310用于控制工具使用的自定义权限函数类型。

1308 1311

1309该函数是交互式权限提示的 SDK 替代品：仅当[权限评估流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时调用。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）预批准的工具调用从不调用它。要限制每个工具调用，改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。1312该函数是 SDK 中交互式权限提示的替代方案：仅当[权限评估流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)的结果为提示时才会调用它。已被 `allowedTools` 条目、设置中的允许规则或权限模式（例如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要对每个工具调用进行把关，请改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。

1310 1313

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

1312 1315

1313```typescript theme={null}1316```typescript theme={null}

1314type CanUseTool = (1317type CanUseTool = (

1331 1334

1332| 选项 | 类型 | 描述 |1335| 选项 | 类型 | 描述 |

1333| :- | :- | :- |1336| :- | :- | :- |

1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建议的权限更新，以便用户不会再次被提示此工具。Bash 提示包括带有 `localSettings` [目标](#permissionupdatedestination)的建议，因此在 `updatedPermissions` 中返回它会将规则写入 `.claude/settings.local.json` 并跨会话持久化。 |1338| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建议的权限更新，使用户不会因此工具再次收到提示。Bash 提示包含一个[目标](#permissionupdatedestination)为 `localSettings` 的建议，因此在 `updatedPermissions` 中返回它会将规则写入 `.claude/settings.local.json`，并在会话之间持久保留。 |

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

~~1344~~ 1347

1345回调通常通过返回 [`PermissionResult`](#permissionresult) 解决请求，SDK 将其写回其传输作为 `control_response`。仅当您的应用已通过其自己的通道为此请求发送 `control_response`（回显 `requestId`）时才返回 `null`；SDK 然后跳过写入响应到其传输。在任何其他情况下返回 `null` 会使工具调用无限期阻止，因为从不发送 `control_response` 且权限提示不超时。1348回调通常通过返回 [`PermissionResult`](#permissionresult) 来处理请求，SDK 会将其作为 `control_response` 通过其传输通道写回。仅当您的应用程序已通过自己的通道为此请求发送了 `control_response`（并回传了 `requestId`）时，才返回 `null`；此时 SDK 会跳过向其传输通道写入响应。在任何其他情况下返回 `null` 都会使工具调用无限期阻塞，因为永远不会发送 `control_response`，而权限提示不会超时。

1346 1349

1347`requestId` 选项和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。1350`requestId` 选项和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。

1348 1351

1384 1387

1385| 字段 | 类型 | 描述 |1388| 字段 | 类型 | 描述 |

1386| :- | :- | :- |1389| :- | :- | :- |

1388 1391

1389<h3 id="mcpserverconfig">1392<h3 id="mcpserverconfig">

1390 `McpServerConfig`1393 `McpServerConfig`

1478 1481

1479| 字段 | 类型 | 描述 |1482| 字段 | 类型 | 描述 |

1480| :- | :- | :- |1483| :- | :- | :- |

1484 1487

1485**示例：**1488**示例：**

1486 1489

1491];1494];

1492```1495```

1493 1496

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

1495 1498

1496<h2 id="message-types">1499<h2 id="message-types">

1497 消息类型1500 消息类型

3788};3791};

3789```3792```

3790 3793

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

3795

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

3792 3797

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

3794 3799

4838};4843};

4839```4844```

4840 4845

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

4842 4847

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

4844 Artifact4849 Artifact

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

5460```5465```

5461 5466

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` 块。5467可选的 `display` 字段控制思考文本以 `"summarized"` 还是 `"omitted"` 方式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此请设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不会将您的 `display` 值传递给某些提供商，例如 Amazon Bedrock 和 Google Cloud 的 Agent Platform。在这些提供商上，即使您将 `display` 设置为 `"summarized"`，Opus 4.7 及更高版本也会返回空的 `thinking` 块。

5463 5468

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

5465 `SpawnedProcess`5470 `SpawnedProcess`

5530 5535

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

5532 5537

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

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

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

5536 5541

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

5851 tasks: {5856 tasks: {

5852 task_id: string;5857 task_id: string;

5853 task_type: string;5858 task_type: string;

5859 subagent_type?: string;

5854 description: string;5860 description: string;

5855 ambient?: boolean;5861 ambient?: boolean;

5856 }[];5862 }[];

5859};5865};

5860```5866```

5861 5867

5868在 [`task_type`](#sdktaskstartedmessage) 为 `"local_agent"` 的条目上，`subagent_type` 指明子代理类型，例如 `general-purpose` 或自定义子代理的名称。该字段需要 Agent SDK v0.3.293 或更高版本。

5869

5862<h3 id="sdkthinkingtokensmessage">5870<h3 id="sdkthinkingtokensmessage">

5863 `SDKThinkingTokensMessage`5871 `SDKThinkingTokensMessage`

5864</h3>5872</h3>

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

Details

188 188

189缓存涵盖上述所有凭证选项，除了 Amazon Bedrock API 密钥，它不使用提供程序链。要在每个请求上解析链，请改为设置 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-CN/env-vars)。189缓存涵盖上述所有凭证选项，除了 Amazon Bedrock API 密钥，它不使用提供程序链。要在每个请求上解析链，请改为设置 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-CN/env-vars)。

190 190

191链的每次解析在 60 秒后超时。如果链中的某个步骤停滞，例如等待无法接收的输入的 `credential_process` 帮助程序，请求会失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)。如果您的链运行合法需要更长时间的交互式登录，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 和 MFA，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制。在 v2.1.207 之前，停滞的凭证解析会使请求无限期等待。191填充缓存的解析在 60 秒后超时。如果链中的某个步骤停滞，例如等待无法接收的输入的 `credential_process` 帮助程序，请求会失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)。如果您的链运行合法需要更长时间的交互式登录，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 和 MFA，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制。设置 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 后，每个 API 请求解析链时不受此限制。

192 192

193除了使用 Amazon Bedrock API 密钥进行身份验证外，[设置向导](#sign-in-with-bedrock)对它在验证您的凭证时进行的每个 AWS 调用以及每个模型检查之前的凭证查找应用相同的限制。在凭证验证期间，超过限制的检查会失败并显示 [`Timed out after 60s waiting for AWS`](/docs/zh-CN/errors#bedrock-setup-verification-timed-out-waiting-for-aws)。193除了使用 Amazon Bedrock API 密钥进行身份验证外，[设置向导](#sign-in-with-bedrock)对它在验证您的凭证时进行的每个 AWS 调用以及每个模型检查之前的凭证查找应用相同的限制。在凭证验证期间，超过限制的检查会失败并显示 [`Timed out after 60s waiting for AWS`](/docs/zh-CN/errors#bedrock-setup-verification-timed-out-waiting-for-aws)。

194 194

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

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

376| 其他任何地方 | 通过 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 环境变量传递凭据，或在 `auth:` 中使用 `${VAR}` 扩展显式设置它们 |376| 其他任何地方 | 通过 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 环境变量传递凭据，或在 `auth:` 中使用 `${VAR}` 扩展显式设置它们 |

377| 区域 | `region:` 是 API 端点区域。跨区域推理配置文件跨地理位置（美国、欧盟、亚太）路由，无论您选择哪一个。对于非美国地区或预配吞吐量 ARN，添加带有正确的按上游 ID 的 [`models:`](#models) 块。 |377| 区域 | `region:` 是 API 端点区域。跨区域推理配置文件跨地理位置（美国、欧盟、亚太）路由，无论您选择哪一个。对于非美国地区或预配吞吐量 ARN，添加带有正确的按上游 ID 的 [`models:`](#models) 块。 |

378 378

379<a id="apply-an-amazon-bedrock-guardrail" />

380

379<h5 id="apply-an-amazon-bedrock-guardrail">381<h5 id="apply-an-amazon-bedrock-guardrail">

380 应用 Amazon Bedrock 防护栏382 应用 Amazon Bedrock 防护栏

381</h5>383</h5>

921 923

922 两个传播时钟适用：924 两个传播时钟适用：

923 925

924 * **策略内容**：编辑策略并重新部署在连接的客户端的下一个托管设置轮询中到达，在一小时内，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)926 * **策略内容**：编辑策略并重新部署在连接的 Claude Code 客户端的下一个托管设置轮询中到达，在一小时内，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)

925 * **组成员身份**：更改用户的组成员身份更改哪个策略匹配他们。这在下一个会话重新铸造时生效，意味着下一个静默刷新，受 `session.ttl_hours` 限制。927 * **组成员身份**：更改用户的组成员身份更改哪个策略匹配他们。这在下一个会话重新铸造时生效，意味着下一个静默刷新，受 `session.ttl_hours` 限制。

928

929 Claude Desktop 遵循[其自己的时间表](#when-a-policy-change-reaches-claude-desktop)。

926</Note>930</Note>

927 931

928<h4 id="start-sessions-on-a-model-the-policy-allows">932<h4 id="start-sessions-on-a-model-the-policy-allows">

1086 需要网关服务器上的 Claude Code v2.1.203 或更高版本，以及显式选择加入：`/user/bootstrap` 返回 404，除非与用户匹配的策略携带 `desktop` 键。空 `desktop: {}` 选择一个策略，`match: {}` 基础层上的 `desktop` 键选择继承它的每个策略。审计日志将每个请求记录为 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。1090 需要网关服务器上的 Claude Code v2.1.203 或更高版本，以及显式选择加入：`/user/bootstrap` 返回 404，除非与用户匹配的策略携带 `desktop` 键。空 `desktop: {}` 选择一个策略，`match: {}` 基础层上的 `desktop` 键选择继承它的每个策略。审计日志将每个请求记录为 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。

1087</Note>1091</Note>

1088 1092

1089网关从匹配策略的 `cli` 块和顶级网关配置派生响应的大部分：1093如果您不部署 Claude Desktop，请完全从您的策略中省略 `desktop`；网关然后从每个用户的 `/user/bootstrap` 返回 404。

1094

1095<h5 id="settings-the-gateway-derives-for-claude-desktop">

1096 网关为 Claude Desktop 派生的设置

1097</h5>

1098

1099网关从匹配策略的 `cli` 块和顶级网关配置派生引导响应的大部分：

1090 1100

1091* 模型列表，来自 `availableModels`。[Claude Desktop 中的扩展上下文](#extended-context-in-claude-desktop)介绍每个模型的 1M 上下文选项1101* 模型列表，来自 `availableModels`。[Claude Desktop 中的扩展上下文](#extended-context-in-claude-desktop)介绍每个模型的 1M 上下文选项

1092* 禁用的工具，来自裸工具名称 `permissions.deny` 条目。如果您在策略的 `desktop` 块中设置 `disabledBuiltinTools`，网关提供您的值和派生列表的并集，因此您可以通过这种方式禁用更多工具，但无法重新启用您通过 `permissions.deny` 禁用的工具1102* 禁用的工具，来自裸工具名称 `permissions.deny` 条目。如果您在策略的 `desktop` 块中设置 `disabledBuiltinTools`，网关提供您的值和派生列表的并集，因此您可以通过这种方式禁用更多工具，但无法重新启用您通过 `permissions.deny` 禁用的工具

1099 1109

1100网关省略没有 Claude Desktop 等效项的键，例如 `hooks` 和范围权限规则，如 `Bash(npm *)`，来自引导响应。1110网关省略没有 Claude Desktop 等效项的键，例如 `hooks` 和范围权限规则，如 `Bash(npm *)`，来自引导响应。

1101 1111

1102添加可选的 `desktop` 块与 `cli` 一起直接设置 Claude Desktop 设置。从 Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)编写设置为平面键名。省略 Claude Desktop 仅从 MDM 或本地文件读取的键，例如 `bootstrapUrl`；网关在启动时拒绝它们。在 v2.1.232 之前，网关接受 11 个固定的功能门键的列表，例如 `chatTabEnabled` 和 `disableAutoUpdates`，并在启动时拒绝每个其他键。在 v2.1.227 之前，网关也在启动时拒绝 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。1112<h5 id="set-claude-desktop-settings-directly">

1113 直接设置 Claude Desktop 设置

1114</h5>

1115

1116添加可选的 `desktop` 块与 `cli` 一起直接设置 Claude Desktop 设置。从 Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)编写设置为平面键名。省略 Claude Desktop 仅从 MDM 或本地文件读取的键，例如 `bootstrapUrl`；网关在启动时拒绝它们。

1117

1118此示例为 `eng-contractors` 组在其 `cli` 设置之外设置三个 Claude Desktop 键：

1103 1119

1104```yaml theme={null}1120```yaml theme={null}

1105managed:1121managed:

1114 banner: { text: "Contractor build: internal use only" }1130 banner: { text: "Contractor build: internal use only" }

1115```1131```

1116 1132

1117每个键都是可选的；Claude Desktop 为您省略的任何键应用其自己的默认值。网关在启动时根据 Claude Desktop 本身使用的配置 schema 验证每个 `desktop` 块，因此错误在网关启动时显示为命名该键的错误，而不是到达每个连接的桌面。网关在块包含以下内容时在启动时失败：1133每个键都是可选的；Claude Desktop 为您省略的任何键应用其自己的默认值。

1134

1135<h5 id="what-the-gateway-rejects-at-boot">

1136 网关在启动时拒绝的内容

1137</h5>

1138

1139网关在启动时根据 Claude Desktop 本身使用的配置 schema 验证每个 `desktop` 块，因此错误在网关启动时显示为命名该键的错误，而不是到达每个连接的桌面。网关在块包含以下内容时在启动时失败：

1118 1140

1119* 未知键1141* 未知键

1120* 识别的键，其值 Claude Desktop 会拒绝或静默删除，例如空值或嵌套条目内的拼写错误的子键。在 v2.1.260 之前，网关静默删除 `managedMcpServers` 或 `orgPluginSettings` 条目的嵌套对象内的拼写错误字段，而不是在启动时失败。1142* 识别的键，其值 Claude Desktop 会拒绝或静默删除，例如空值或嵌套条目内的拼写错误的子键。在 v2.1.260 之前，网关静默删除 `managedMcpServers` 或 `orgPluginSettings` 条目的嵌套对象内的拼写错误字段，而不是在启动时失败。

1123 1145

1124如果您使用已弃用的值或条目形状，例如没有 `transport` 的 `managedMcpServers` 条目，网关启动并记录命名替换的警告。1146如果您使用已弃用的值或条目形状，例如没有 `transport` 的 `managedMcpServers` 条目，网关启动并记录命名替换的警告。

1125 1147

1148在 v2.1.232 之前，网关接受 11 个固定的功能门键的列表，例如 `chatTabEnabled` 和 `disableAutoUpdates`，并在启动时拒绝每个其他键。在 v2.1.227 之前，网关也在启动时拒绝 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。

1149

1150<h5 id="keys-that-need-a-later-gateway-or-claude-desktop-version">

1151 需要更高版本网关或 Claude Desktop 的键

1152</h5>

1153

1126网关根据与其已安装版本捆绑的 schema 验证 `desktop` 块，就像它对 `cli` 块所做的那样。要交付由较新 Claude Desktop 版本引入的设置，首先升级网关。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要网关服务器上的 Claude Code v2.1.260 或更高版本以及成员机器上的 Claude Desktop 1.37937.0 或更高版本。1154网关根据与其已安装版本捆绑的 schema 验证 `desktop` 块，就像它对 `cli` 块所做的那样。要交付由较新 Claude Desktop 版本引入的设置，首先升级网关。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要网关服务器上的 Claude Code v2.1.260 或更高版本以及成员机器上的 Claude Desktop 1.37937.0 或更高版本。

1127 1155

1128`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要网关服务器上的 Claude Code v2.1.281 或更高版本。`microsoftAuthBroker` 的 `required` 值和 Microsoft 365 `managedMcpServers` 条目的 `continuousAccessEvaluation` 字段也是如此。早于 `required` 值的 Claude Desktop 版本将其读取为 `disabled`，因此仅在每个成员的 Claude Desktop 支持它后才设置 `required`。Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次读取每个键的版本。1156`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要网关服务器上的 Claude Code v2.1.281 或更高版本。`microsoftAuthBroker` 的 `required` 值和 Microsoft 365 `managedMcpServers` 条目的 `continuousAccessEvaluation` 字段也是如此。早于 `required` 值的 Claude Desktop 版本将其读取为 `disabled`，因此仅在每个成员的 Claude Desktop 支持它后才设置 `required`。Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次读取每个键的版本。

1129 1157

1130如果您在策略的 `desktop` 块中设置 `orgPluginSettings`，网关以 Claude Desktop 1.15200.0 及更高版本读取的数组形式提供它。较旧的桌面忽略数组并强制执行没有插件工具策略，因此在您依赖它之前将成员更新到 1.15200.0 或更高版本。1158如果您在策略的 `desktop` 块中设置 `orgPluginSettings`，网关以 Claude Desktop 1.15200.0 及更高版本读取的数组形式提供它。较旧的桌面忽略数组并强制执行没有插件工具策略，因此在您依赖它之前将成员更新到 1.15200.0 或更高版本。

1131 1159

1160<h5 id="how-a-role-policy-inherits-the-base-desktop-block">

1161 角色策略如何继承基础 `desktop` 块

1162</h5>

1163

1132网关从策略的 `desktop` 块不设置的 `match: {}` 全部捕获的 `desktop` 块填充键，与它填充策略的 `cli` 块的方式相同。如果您在基础和角色策略中都设置 `disabledBuiltinTools` 或 `builtinToolPolicy`，网关保留基础的限制：1164网关从策略的 `desktop` 块不设置的 `match: {}` 全部捕获的 `desktop` 块填充键，与它填充策略的 `cli` 块的方式相同。如果您在基础和角色策略中都设置 `disabledBuiltinTools` 或 `builtinToolPolicy`，网关保留基础的限制：

1133 1165

1134* `disabledBuiltinTools`：网关使用基础列表和策略列表的并集1166* `disabledBuiltinTools`：网关使用基础列表和策略列表的并集

1136 1168

1137对于每个其他键，如果您在角色策略中设置它，网关使用角色策略的值。网关替换数组或嵌套对象（如 `banner`）整体，因此如果您在角色策略中设置 `banner.text`，网关删除基础的 `banner.backgroundColor`。1169对于每个其他键，如果您在角色策略中设置它，网关使用角色策略的值。网关替换数组或嵌套对象（如 `banner`）整体，因此如果您在角色策略中设置 `banner.text`，网关删除基础的 `banner.backgroundColor`。

1138 1170

1139如果您不部署 Claude Desktop，请完全从您的策略中省略 `desktop`；网关然后从每个用户的 `/user/bootstrap` 返回 404。1171<h5 id="when-a-policy-change-reaches-claude-desktop">

1172 策略更改何时到达 Claude Desktop

1173</h5>

1174

1175在您使用更改后的策略重新部署网关后，Claude Desktop 仅在下次启动时应用大多数设置：

1176

1177* **已关闭**：Claude Desktop 在启动时获取引导响应，因此更改从下次启动起生效

1178* **已打开**：Claude Desktop 默认每 10 分钟检查一次响应是否有更改，并在不重启的情况下应用少数设置。对于其余设置，例如 [`skillCreationEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#skillcreationenabled)，用户会在侧边栏中看到 **Relaunch Claude Desktop** 卡片，并在重启应用之前保留先前的配置。默认在 24 小时后，Claude Desktop 会显示重启对话框，并在 2 分钟无活动后自行重启

1179

1180要缩短这 24 小时，请在策略的 `desktop` 块中设置 [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours)。您需要网关服务器上的 Claude Code v2.1.260 或更高版本，以及成员机器上的 Claude Desktop 1.40609.0 或更高版本。设置为 `0` 时，Claude Desktop 一发现更改就会显示该对话框。

1140 1181

1141<h4 id="extended-context-in-claude-desktop">1182<h4 id="extended-context-in-claude-desktop">

1142 Claude Desktop 中的扩展上下文1183 Claude Desktop 中的扩展上下文

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 +10 −12

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 探索目录

1452 1452

1453| 文件 | 位置 | 用途 |1453| 文件 | 位置 | 用途 |

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` | 系统级别，因操作系统而异 | 企业强制执行的设置，您自己的设置文件和 `--settings` 值无法覆盖这些设置，除了[狭窄的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)。请参阅[保存文件的位置](/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)。

1487<Note>1487<Note>

1488 有几件事可以覆盖您在这些文件中放入的内容：1488 有几件事可以覆盖您在这些文件中放入的内容：

1489 1489

1490 * 您的组织部署的[托管设置](/docs/zh-CN/server-managed-settings)优先于所有内容，除了[设置优先级下的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)1490 * 您的组织部署的[托管设置](/docs/zh-CN/server-managed-settings)优先于所有设置文件和 `--settings` 值，[设置优先级下的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)除外

1491 * CLI 标志（如 `--permission-mode` 或 `--settings`）在该会话中覆盖 `settings.json`1491 * CLI 标志（如 `--permission-mode` 或 `--settings`）在该会话中覆盖 `settings.json`

1492 * 某些环境变量优先于其等效设置，但这会有所不同：检查[环境变量参考](/docs/zh-CN/env-vars)以了解每个变量1492 * 某些环境变量优先于其等效设置，但这会有所不同：检查[环境变量参考](/docs/zh-CN/env-vars)以了解每个变量

1493 1493

1708 1708

1709传递 `--all` 而不是路径以一次清除所有项目的状态，这会直接删除 `history.jsonl` 而不是过滤它。传递 `-i` 以逐项逐步执行删除计划。1709传递 `--all` 而不是路径以一次清除所有项目的状态，这会直接删除 `history.jsonl` 而不是过滤它。传递 `-i` 以逐项逐步执行删除计划。

1710 1710

1711在脚本中，请检查输出，而不仅仅是退出状态。删除了计划中所有内容的运行会以 `Purged N item(s)` 结尾。请将该行视为成功的标志。

~~1712~~

1713该命令不理会 `shell-snapshots/` 和 `backups/`，因为这些不是项目范围的，并在计划输出中警告它们。如果有人在该机器上运行过 [`/heapdump`](/docs/zh-CN/troubleshooting#high-cpu-or-memory-usage)，也请删除它写入的 `.heapsnapshot` 文件。堆快照包含完整的对话以及进程持有的所有凭据，保留扫描和清除都不会触及它。1711该命令不理会 `shell-snapshots/` 和 `backups/`，因为这些不是项目范围的，并在计划输出中警告它们。如果有人在该机器上运行过 [`/heapdump`](/docs/zh-CN/troubleshooting#high-cpu-or-memory-usage)，也请删除它写入的 `.heapsnapshot` 文件。堆快照包含完整的对话以及进程持有的所有凭据，保留扫描和清除都不会触及它。

1714 1712

1715您也可以手动删除上面的任何应用数据路径，除了 [state files to keep](#state-files-to-keep)。新会话不受影响。下表显示您对过去会话失去的内容。1713您也可以手动删除上面的任何应用数据路径，除了 [state files to keep](#state-files-to-keep)。新会话不受影响。下表显示您对过去会话失去的内容。

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

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

95| `--fallback-model` | 启用当主模型过载或不可用（例如已停用的模型）时自动回退到指定的模型。接受按顺序尝试的逗号分隔列表。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。要在会话之间保持模型链，请使用 [`fallbackModel` 设置](/docs/zh-CN/settings-reference#fallbackmodel)，此标志会覆盖该设置 | `claude --fallback-model sonnet,haiku` |97| `--fallback-model` | 启用当主模型过载或不可用（例如已停用的模型）时自动回退到指定的模型。接受按顺序尝试的逗号分隔列表。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。要在会话之间保持模型链，请使用 [`fallbackModel` 设置](/docs/zh-CN/settings-reference#fallbackmodel)，此标志会覆盖该设置 | `claude --fallback-model sonnet,haiku` |

97| `--forward-subagent-text` | 在输出流中将[子代理](/docs/zh-CN/sub-agents)文本和思考块作为设置了 `parent_tool_use_id` 的 `assistant` 和 `user` 消息发出，以便您可以重建每个子代理的会话记录。没有此标志，Claude Code 会省略在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的文本和思考块。需要 `--print` 和 `--output-format stream-json`。Claude Code 也转发来自[嵌套子代理](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的消息，将 `parent_tool_use_id` 设置为启动每个子代理的 Agent 或 Skill 工具调用的 ID；这需要 Claude Code v2.1.219 或更高版本，分叉 skill 生成的子代理的消息以及嵌套分叉 skill 的消息需要 v2.1.275 或更高版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars) 环境变量启用相同的行为。需要 Claude Code v2.1.211 或更高版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |99| `--forward-subagent-text` | 在输出流中将[子代理](/docs/zh-CN/sub-agents)文本和思考块作为设置了 `parent_tool_use_id` 的 `assistant` 和 `user` 消息发出，以便您可以重建每个子代理的会话记录。没有此标志，Claude Code 会省略在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的文本和思考块。需要 `--print` 和 `--output-format stream-json`。有关嵌套子代理、分叉 skill 以及各自所需的版本，请参阅[跟踪子代理消息](/docs/zh-CN/headless#follow-subagent-messages)。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars) 环境变量启用相同的行为。需要 Claude Code v2.1.211 或更高版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

98| `--from-pr` | 打开会话选择器，过滤到链接到特定 Pull Request 的会话。接受 PR 编号、GitHub 或 GitHub Enterprise PR URL、GitLab merge request URL 或 Bitbucket Pull Request URL。当 Claude 创建 Pull Request 时，会话会自动链接 | `claude --from-pr 123` |100| `--from-pr` | 打开会话选择器，过滤到链接到特定 Pull Request 的会话。接受 PR 编号、GitHub 或 GitHub Enterprise PR URL、GitLab merge request URL 或 Bitbucket Pull Request URL。当 Claude 创建 Pull Request 时，会话会自动链接 | `claude --from-pr 123` |

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

cloud-environments.md +92 −76

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 代理会将密钥添加到发往您所列主机的请求中，因此密钥本身始终位于 VM 之外。

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

272* **Git 凭证**：VM 内的 git 客户端使用范围受限的凭证，代理验证并将其交换为您的实际 GitHub 令牌。272* **Git 凭证**：VM 内的 git 客户端使用范围受限的凭证，代理验证并将其交换为您的实际 GitHub 令牌。

273* **API 请求**：来自内置 GitHub 工具的请求，以及来自 [`proxy-injected` 占位符](#work-with-github-issues-and-pull-requests)下的 `gh` 的请求，会在替换为您的真实凭证后发出。273* **API 请求**：来自内置 GitHub 工具的请求，以及来自 [`proxy-injected` 占位符](#work-with-github-issues-and-pull-requests)下的 `gh` 的请求，会在替换为您的真实凭证后发出。

274* **推送限制**：代理会拒绝分支删除，以及推送分支以外的任何内容（例如标签）。它不限制推送可以更新哪些分支。如需限制，请在 GitHub 上使用分支保护规则或规则集。274* **推送限制**：代理会拒绝分支删除，以及推送分支以外的任何内容（例如标签）。它不限制推送可以更新哪些分支。如需限制，请在 GitHub 上使用分支保护规则或规则集。

275* **存储库范围**：GitHub API 和发布资产请求仅能到达附加到会话的存储库，因此从未附加的存储库下载发布资产的设置脚本会收到 403。275* **仓库范围**：代理为附加到会话的仓库处理 GitHub API 请求。针对其他仓库的 API 请求会收到 403，其消息以 `GitHub access to` 开头并包含 `is not enabled for this session`。

276* **GraphQL 限制**：代理仅提供一组固定的 GraphQL 操作用于拉取请求工作流。代理在 GraphQL 端点上拒绝所有其他内容，返回 403，显示 `This GraphQL query is not enabled for this session`，并命名 REST 回退 `gh api repos/{owner}/{repo}/...`。无论您提供的凭证如何，限制都适用于通过代理的每个请求，因此您设置的 `GH_TOKEN` 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。276* **GraphQL 限制**：代理会拒绝发往 GitHub GraphQL 端点的请求，返回 403，其消息以 `GitHub GraphQL is not available from Claude Code sessions` 开头，并指明 REST 回退方式 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）也会收到相同的 403。无论您提供的凭据如何，限制都适用于通过代理的每个请求，因此您设置的 `GH_TOKEN` 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。

277 277

278来自公开存储库的已提交文件通过 `raw.githubusercontent.com` 到达，改由[安全代理](#security-proxy)处理。该域在默认 [Trusted 列表](#default-allowed-domains)中，因此除非环境的[访问级别](#access-levels)排除它，否则这些文件保持可访问。278来自公开存储库的已提交文件通过 `raw.githubusercontent.com` 到达，改由[安全代理](#security-proxy)处理。该域在默认 [Trusted 列表](#default-allowed-domains)中，因此除非环境的[访问级别](#access-levels)排除它，否则这些文件保持可访问。

279 279

285 285

286* 防范恶意请求286* 防范恶意请求

287* 速率限制和滥用防范287* 速率限制和滥用防范

288* 增强安全性的内容过滤

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

290 288

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

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

293</h2>291</h2>

294 292

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)对长时间运行的工作的限制。293在 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 294

297<Note>295<Note>

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

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

303</h3>301</h3>

304 302

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

306 304

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

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

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

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

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

313| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |311| 您的仓库的 `.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 |312| 在您的仓库的 `.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) |313| 您组织的[服务器托管设置](/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` | 否 | 位于您的机器上，不在存储库中 |314| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在仓库中。请参阅[添加个人偏好而无需提交到仓库](#add-personal-preferences-without-committing-to-the-repo) |

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

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

319| 您使用 `claude mcp add` 在默认本地范围或用户范围添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是存储库。请使用 `claude mcp add --scope project` 添加服务器，它会写入存储库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个存储库的会话会加载它 |317| 您使用 `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 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |318| 您的仓库的 `.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 计划中的任何密钥，保留在环境变量中 |319| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为[网络密钥](#add-api-credentials) | 您在环境中添加一次密钥，Agent 代理会将其附加到发往您列出的主机的请求。Agent 代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |

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

~~323~~ 321

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

~~325~~ 323

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

325

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

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

328</h4>

329

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

331

332```bash theme={null}

333#!/bin/bash

334mkdir -p ~/.claude

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

336Use conventional commit messages.

337EOF

338```

339

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

341

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

327 343

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

329 已安装的工具345 已安装的工具

330</h3>346</h3>

331 347

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

333 349

334| 类别 | 包含 |350| 类别 | 包含 |

335| :- | :- |351| :- | :- |

347 363

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

349 365

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

351 367

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

353 369

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

355 371

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

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

358</h3>374</h3>

359 375

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

361 377

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

363 379

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

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

366 382

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

368 384

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

370 386

371GitHub 的 [`gh` CLI](https://cli.github.com) 已预安装。如果您需要内置工具未涵盖的 `gh` 命令，例如 `gh release` 或 `gh workflow run`，请让 Claude 运行它。`gh` 会自动读取 `GH_TOKEN`，因此您不需要运行 `gh auth login`。387GitHub 的 [`gh` CLI](https://cli.github.com) 已预安装。如果您需要内置工具未涵盖的 GitHub 操作，请让 Claude 使用 `gh api` 调用 REST API。使用 REST API 的 `gh` 子命令（例如 `gh workflow list`）也可以工作。代理会[拒绝使用 GraphQL 的子命令](#github-proxy)，例如 `gh pr` 和 `gh issue`。`gh` 会自动读取 `GH_TOKEN`，因此您不需要运行 `gh auth login`。

372 388

373<h3 id="link-output-back-to-the-session">389<h3 id="link-output-back-to-the-session">

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

375</h3>391</h3>

376 392

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

378 394

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

380 396

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

382 398

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

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

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

389</h3>405</h3>

390 406

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

392 408

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

394 运行测试410 运行测试

395</h4>411</h4>

396 412

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

398 414

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

400 启动服务416 启动服务

424 资源限制440 资源限制

425</h3>441</h3>

426 442

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

428 444

429* 4 vCPU445* 4 vCPU

430* 16 GB RAM446* 16 GB RAM

431* 30 GB 磁盘447* 30 GB 磁盘

432 448

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

434 450

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

436 时间限制452 时间限制

437</h3>453</h3>

438 454

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

440 456

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

442 458

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` 毫秒以上会延长该限制以及前台默认值。459 当命令达到其[超时](/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 强制执行超时。460* **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)涵盖如何保持在该时间以下。461* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。

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

447 463

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

449 465

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

451 设置脚本467 设置脚本

code-review.md +1 −1

Details

379 调整工作量和参数379 调整工作量和参数

380</h3>380</h3>

381 381

382传递一个[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)以权衡覆盖范围和置信度。在 `low` 和 `medium` 处，审查仅报告它最有信心的发现，因此您看到更少的误报；`high` 到 `max` 扩大覆盖范围，可能包括审查不太确定的发现。382传递一个 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)以权衡覆盖范围和置信度。在 `low` 级别，审查报告它最有信心的发现，因此您看到更少的误报。从 `medium` 到 `max`，审查会扩大覆盖范围。

383 383

384当您不输入级别时，审查重用您上次输入的 `low` 到 `max` 的级别，即使在较早的会话中，Claude Code 显示一个通知，例如 `Reusing high effort, the level you typed last time`。输入一个级别，例如 `/code-review high`，以更改后续运行重用的内容；您在非交互式 `-p` 运行中传递的级别不会更新它。`ultra` 既不更新也不使用记住的级别。如果您从未输入过级别，审查使用会话的当前工作量。在 v2.1.223 之前，没有级别的 `/code-review` 总是使用会话的当前工作量。384当您不输入级别时，审查重用您上次输入的 `low` 到 `max` 的级别，即使在较早的会话中，Claude Code 显示一个通知，例如 `Reusing high effort, the level you typed last time`。输入一个级别，例如 `/code-review high`，以更改后续运行重用的内容；您在非交互式 `-p` 运行中传递的级别不会更新它。`ultra` 既不更新也不使用记住的级别。如果您从未输入过级别，审查使用会话的当前工作量。在 v2.1.223 之前，没有级别的 `/code-review` 总是使用会话的当前工作量。

385 385

context-window.md +10 −10

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

1599 1599

1600| 机制 | 压缩后 |1600| 机制 | 压缩后 |

1601| :- | :- |1601| :- | :- |

1602| 系统提示和输出样式 | 两者仍然适用 |1602| 系统提示词和输出样式 | 两者仍然适用 |

1603| 项目根目录 CLAUDE.md 和无范围规则 | 从磁盘重新注入 |1603| 项目根目录 CLAUDE.md 和无范围规则 | 从磁盘重新注入 |

1604| 自动内存 | 从磁盘重新注入 |1604| 自动记忆 | 从磁盘重新注入 |

1605| [Git 状态快照](/docs/zh-CN/settings-reference#includegitinstructions) | Claude Code 从您的存储库读取一个新的 |1605| [Git 状态快照](/docs/zh-CN/settings-reference#includegitinstructions) | Claude Code 从您的仓库读取一个新的 |

1606| Claude 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中编写的计划 | 从磁盘重新注入 |1606| Claude 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中编写的计划 | 从磁盘重新注入 |

1608| 子目录中的嵌套 CLAUDE.md | Claude Code [按需](/docs/zh-CN/memory#how-claude-md-files-load)重新加载它们 |1608| 子目录中的嵌套 CLAUDE.md | Claude Code [按需](/docs/zh-CN/memory#how-claude-md-files-load)重新加载它们 |

1609| Claude 读取或编辑的文件 | Claude Code 重新读取最多五个，最近修改的优先 |1609| Claude 读取或编辑的文件 | Claude Code 重新读取最多五个，最近修改的优先 |

1610| 调用的技能主体 | 重新注入，每个技能上限为 5,000 个令牌，总计 25,000 个令牌；最旧的首先删除 |1610| 调用的 skill 主体 | 重新注入，每个 skill 上限为 5,000 个 token，总计 25,000 个 token；最旧的首先删除 |

1611| [后台命令](/docs/zh-CN/interactive-mode#background-bash-commands)和后台[子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) | 继续运行。Claude Code 提醒 Claude 哪些仍在运行，以便它不会启动重复的 |1611| [后台命令](/docs/zh-CN/interactive-mode#background-bash-commands)和后台[子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) | 继续运行。Claude Code 提醒 Claude 哪些仍在运行，以便它不会启动重复的 |

1612| Hooks 添加的上下文 | 与对话的其余部分一起总结 |1612| hook 先前添加的上下文 | 与对话的其余部分一起总结 |

1613| 匹配 `compact` 源的 [SessionStart hooks](/docs/zh-CN/hooks-guide#re-inject-context-after-compaction) | Claude Code 运行它们并将其输出添加到压缩的上下文中 |1613| 匹配 `compact` 源的 [SessionStart hooks](/docs/zh-CN/hooks-guide#re-inject-context-after-compaction) | Claude Code 运行它们并将其输出添加到压缩的上下文中 |

1614 1614

1615压缩后立即，Claude Code 重新读取最多五个 Claude 在会话中读取或编辑的文件，选择最近修改的文件。超过 5,000 个令牌的文件作为路径引用返回，不包含其内容，显示为 `Referenced file` 而不是 `Read`。1615压缩后立即，Claude Code 重新读取最多五个 Claude 在会话中读取或编辑的文件，选择最近修改的文件。超过 5,000 个 token 的文件作为路径引用返回，不包含其内容，显示为 `Referenced file` 而不是 `Read`。

1616 1616

1617路径范围的规则和嵌套的 CLAUDE.md 文件在读取其触发文件时加载到消息历史中，因此压缩会将它们与其他所有内容一起总结。如果规则必须在压缩过程中保持不变，请删除 `paths:` frontmatter 或将其移动到项目根目录 CLAUDE.md。1617路径范围的规则和嵌套的 CLAUDE.md 文件在 Claude 读取、写入或编辑其触发文件时加载到消息历史中，因此压缩会将它们与其他所有内容一起总结。如果规则必须在压缩过程中保持不变，请删除 `paths:` frontmatter 或将其移动到项目根目录 CLAUDE.md。

1618 1618

1619技能主体在压缩后重新注入，但大型技能会被截断以适应每个技能的上限，一旦超过总预算，最旧的调用技能就会被删除。截断保留文件的开头，因此请将最重要的指令放在 `SKILL.md` 的顶部附近。1619skill 主体在压缩后重新注入，但大型 skill 会被截断以适应每个 skill 的上限，一旦超过总预算，最旧的已调用 skill 就会被删除。截断保留文件的开头，因此请将最重要的指令放在 `SKILL.md` 的顶部附近。

1620 1620

1621<h2 id="when-your-context-fills-up">1621<h2 id="when-your-context-fills-up">

1622 当您的上下文填满时1622 当您的上下文填满时

1632* **在任务之间清除**：切换到不相关的工作时运行 `/clear`。旧对话会挤出您接下来需要的文件，并在每条消息上花费令牌。1632* **在任务之间清除**：切换到不相关的工作时运行 `/clear`。旧对话会挤出您接下来需要的文件，并在每条消息上花费令牌。

1633* **委托大型读取**：将研究发送给[子代理](/docs/zh-CN/sub-agents)，以便文件内容保留在其上下文窗口中，而不是您的。1633* **委托大型读取**：将研究发送给[子代理](/docs/zh-CN/sub-agents)，以便文件内容保留在其上下文窗口中，而不是您的。

1634 1634

1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5 及更高版本、Haiku 5.5、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万 token 的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。

1636 1636

1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值，请参阅[Sonnet 5.5 和 Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window)，以及[网关后面的上下文窗口](/docs/zh-CN/model-config#context-window-behind-a-gateway)，了解当您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](/docs/zh-CN/llm-gateway)时 Claude Code 如何调整窗口大小。1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值，请参阅[Sonnet 5.5 和 Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window)，以及[网关后面的上下文窗口](/docs/zh-CN/model-config#context-window-behind-a-gateway)，了解当您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](/docs/zh-CN/llm-gateway)时 Claude Code 如何调整窗口大小。

1638 1638

costs.md +29 −29

Details

249* Agent 团队默认被禁用。在您的[settings.json](/docs/zh-CN/settings)或环境中设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 以启用它们。请参阅[启用 agent 团队](/docs/zh-CN/agent-teams#enable-agent-teams)。249* Agent 团队默认被禁用。在您的[settings.json](/docs/zh-CN/settings)或环境中设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 以启用它们。请参阅[启用 agent 团队](/docs/zh-CN/agent-teams#enable-agent-teams)。

250 250

251<h2 id="reduce-token-usage">251<h2 id="reduce-token-usage">

252 减少令牌使用252 减少 token 使用

253</h2>253</h2>

254 254

255令牌成本随上下文大小而扩展：Claude 处理的上下文越多，您使用的令牌就越多。Claude Code 通过 [prompt caching](/docs/zh-CN/prompt-caching)（减少重复内容（如系统提示）的成本）和 auto-compact（在接近上下文限制时总结对话历史）自动优化成本。255token 成本随上下文大小而扩展：Claude 处理的上下文越多，您使用的 token 就越多。Claude Code 通过[提示缓存](/docs/zh-CN/prompt-caching)（减少重复内容（如系统提示词）的成本）和自动压缩（在接近上下文限制时总结对话历史）自动优化成本。

256 256

257以下策略可帮助您保持上下文较小并降低每条消息的成本。257以下策略可帮助您保持上下文较小并降低每条消息的成本。

258 258

260 主动管理上下文260 主动管理上下文

261</h3>261</h3>

262 262

263使用 `/usage` 检查您当前的令牌使用情况，或[配置您的状态行](/docs/zh-CN/statusline#context-window-usage)以连续显示它。263使用 `/usage` 检查您当前的 token 使用情况，或[配置您的状态栏](/docs/zh-CN/statusline#context-window-usage)以持续显示它。

264 264

265* **在任务之间清除**：在切换到不相关的工作时，使用 `/clear` 重新开始。陈旧的上下文会在随后的每条消息上浪费 token。在清除之前使用 `/rename`，以便您稍后可以找到该会话，然后使用 `/resume` 返回到它。265* **在任务之间清除**：在切换到不相关的工作时，使用 `/clear` 重新开始。陈旧的上下文会在随后的每条消息上浪费 token。在清除之前使用 `/rename`，以便您稍后可以找到该会话，然后使用 `/resume` 返回到它。

266* **添加自定义 compaction 指令**：`/compact Focus on code samples and API usage` 告诉 Claude 在总结期间保留什么。266* **添加自定义压缩指令**：`/compact Focus on code samples and API usage` 告诉 Claude 在总结期间保留什么。

267 267

268您还可以在项目根目录的 CLAUDE.md 文件中自定义 compaction 行为：268您还可以在项目根目录的 CLAUDE.md 文件中自定义压缩行为：

269 269

270```markdown theme={null}270```markdown theme={null}

271# Compact instructions271# Compact instructions

277 选择正确的模型277 选择正确的模型

278</h3>278</h3>

279 279

280Sonnet 处理大多数编码任务效果很好，成本低于 Opus。为复杂的架构决策或多步推理保留 Opus。使用 `/model` 在会话中途切换模型，或在 `/config` 中设置默认值。对 Opus 的切换也适用于[继承您会话模型的 subagents](/docs/zh-CN/model-config#setting-your-model)。对于简单的 subagent 任务，在您的 [subagent 配置](/docs/zh-CN/sub-agents#choose-a-model)中指定 `model: haiku`。280Sonnet 处理大多数编码任务效果很好，成本低于 Opus。为复杂的架构决策或多步推理保留 Opus。使用 `/model` 在会话中途切换模型，或在 `/config` 中设置默认值。对 Opus 的切换也适用于[继承您会话模型的子代理](/docs/zh-CN/model-config#setting-your-model)。对于简单的子代理任务，在您的[子代理配置](/docs/zh-CN/sub-agents#choose-a-model)中指定 `model: haiku`。

281 281

282<h3 id="reduce-mcp-server-overhead">282<h3 id="reduce-mcp-server-overhead">

283 减少 MCP server 开销283 减少 MCP 服务器开销

284</h3>284</h3>

285 285

286MCP 工具定义[默认被延迟](/docs/zh-CN/mcp#scale-with-mcp-tool-search)，因此只有工具名称和服务器指令进入上下文，直到 Claude 使用特定工具。运行 `/context` 查看占用空间的内容。286MCP 工具定义[默认被延迟](/docs/zh-CN/mcp#scale-with-mcp-tool-search)，因此只有工具名称和服务器指令进入上下文，直到 Claude 使用特定工具。运行 `/context` 查看占用空间的内容。

287 287

288* **在可用时优先使用 CLI 工具**：`gh`、`aws`、`gcloud` 和 `sentry-cli` 等工具比 MCP servers 更节省上下文，因为它们不添加任何每工具列表。Claude 可以直接运行 CLI 命令。288* **在可用时优先使用 CLI 工具**：`gh`、`aws`、`gcloud` 和 `sentry-cli` 等工具仍比 MCP 服务器更节省上下文，因为它们不添加任何每工具列表。Claude 可以直接运行 CLI 命令。

289* **禁用未使用的 servers**：运行 `/mcp` 查看配置的 servers 并禁用您未积极使用的任何 servers。289* **禁用未使用的服务器**：运行 `/mcp` 查看已配置的服务器，并禁用您未积极使用的任何服务器。

290 290

291<h3 id="install-code-intelligence-plugins-for-typed-languages">291<h3 id="install-code-intelligence-plugins-for-typed-languages">

292 为类型化语言安装代码智能插件292 为类型化语言安装代码智能插件

295[代码智能插件](/docs/zh-CN/plugins/code-intelligence)为 Claude 提供精确的符号导航，而不是基于文本的搜索，减少在探索不熟悉的代码时不必要的文件读取。单个"转到定义"调用替代了可能需要的 grep 后跟读取多个候选文件。已安装的语言服务器还会在编辑后自动报告类型错误，因此 Claude 无需运行编译器即可捕获错误。295[代码智能插件](/docs/zh-CN/plugins/code-intelligence)为 Claude 提供精确的符号导航，而不是基于文本的搜索，减少在探索不熟悉的代码时不必要的文件读取。单个"转到定义"调用替代了可能需要的 grep 后跟读取多个候选文件。已安装的语言服务器还会在编辑后自动报告类型错误，因此 Claude 无需运行编译器即可捕获错误。

296 296

297<h3 id="offload-processing-to-hooks-and-skills">297<h3 id="offload-processing-to-hooks-and-skills">

298 将处理卸载到 hooks 和 skills298 将处理卸载到 hook 和 skill

299</h3>299</h3>

300 300

301自定义 [hooks](/docs/zh-CN/hooks)可以在 Claude 看到数据之前对其进行预处理。Claude 不是读取 10,000 行日志文件来查找错误，hook 可以 grep `ERROR` 并仅返回匹配的行，将上下文从数万个令牌减少到数百个。301自定义 [hook](/docs/zh-CN/hooks) 可以在 Claude 看到数据之前对其进行预处理。Claude 不是读取 10,000 行日志文件来查找错误，hook 可以 grep `ERROR` 并仅返回匹配的行，将上下文从数万个 token 减少到数百个。

302 302

303[skill](/docs/zh-CN/skills)可以为 Claude 提供领域知识，这样它就不必进行探索。例如，"codebase-overview" skill 可以描述您的项目架构、关键目录和命名约定。当 Claude 调用该 skill 时，它会立即获得此上下文，而不是花费令牌读取多个文件来理解结构。303[skill](/docs/zh-CN/skills) 可以为 Claude 提供领域知识，这样它就不必进行探索。例如，"codebase-overview" skill 可以描述您的项目架构、关键目录和命名约定。当 Claude 调用该 skill 时，它会立即获得此上下文，而不是花费 token 读取多个文件来理解结构。

304 304

305例如，此 PreToolUse hook 过滤测试输出以仅显示失败：305例如，此 PreToolUse hook 过滤测试输出以仅显示失败：

306 306

307<Tabs>307<Tabs>

308 <Tab title="settings.json">308 <Tab title="settings.json">

309 将此添加到您的 [settings.json](/docs/zh-CN/settings#where-settings-live)以在每个 Bash 命令之前运行 hook：309 将此添加到您的 [settings.json](/docs/zh-CN/settings#where-settings-live)，以在每个 Bash 命令之前运行 hook：

310 310

311 ```json theme={null}311 ```json theme={null}

312 {312 {

350要验证设置，运行 `/hooks` 并检查 hook 是否出现在 PreToolUse 下。您也可以使用 `claude --debug-file ./claude-debug.txt` 启动 Claude Code 并要求 Claude 运行 `npm test`。当 hook 重写命令时，该日志文件包含一个 `modified tool input keys` 行，列出 `command` 和其他 Bash 输入字段。350要验证设置，运行 `/hooks` 并检查 hook 是否出现在 PreToolUse 下。您也可以使用 `claude --debug-file ./claude-debug.txt` 启动 Claude Code 并要求 Claude 运行 `npm test`。当 hook 重写命令时，该日志文件包含一个 `modified tool input keys` 行，列出 `command` 和其他 Bash 输入字段。

351 351

352<h3 id="move-instructions-from-claude-md-to-skills">352<h3 id="move-instructions-from-claude-md-to-skills">

353 将指令从 CLAUDE.md 移动到 skills353 将指令从 CLAUDE.md 移动到 skill

354</h3>354</h3>

355 355

356您的 [CLAUDE.md](/docs/zh-CN/memory)文件在会话开始时加载到上下文中。如果它包含特定工作流的详细指令（如 PR 审查或数据库迁移），即使您在做不相关的工作时，这些令牌也会存在。[Skills](/docs/zh-CN/skills)仅在调用时按需加载，因此将专门指令移动到 skills 中可以保持您的基础上下文较小。目标是通过仅包含必要内容来将 CLAUDE.md 保持在 200 行以下。356您的 [CLAUDE.md](/docs/zh-CN/memory) 文件在会话开始时加载到上下文中。如果它包含特定工作流的详细指令（如 PR 审查或数据库迁移），即使您在做不相关的工作时，这些 token 也会存在。[Skills](/docs/zh-CN/skills) 仅在调用时按需加载，因此将专门指令移动到 skill 中可以保持您的基础上下文较小。目标是通过仅包含必要内容来将 CLAUDE.md 保持在 200 行以下。

357 357

358<h3 id="adjust-extended-thinking">358<h3 id="adjust-extended-thinking">

359 调整扩展思考359 调整扩展思考

360</h3>360</h3>

361 361

362扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考令牌作为输出令牌计费，默认预算可能是每个请求数万个令牌，具体取决于模型。362扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考 token 作为输出 token 计费，默认预算可能是每个请求数万个 token，具体取决于模型。

363 363

364对于不需要深度推理的更简单任务，您可以通过在 `/effort` 中或在 `/model` 中降低 [effort level](/docs/zh-CN/model-config#adjust-effort-level)、或在 `/config` 中禁用思考来降低成本。您无法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考，它们始终使用扩展思考。364对于不需要深度推理的更简单任务，您可以通过使用 `/effort` 或在 `/model` 中降低 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)、或在 `/config` 中禁用思考来降低成本。您无法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上关闭思考，它们始终使用扩展思考。

365 365

366在具有[固定思考预算](/docs/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以通过设置 `MAX_THINKING_TOKENS` [环境变量](/docs/zh-CN/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）来降低预算。自适应推理模型忽略非零预算，因此请改用 effort levels。366在具有[固定思考预算](/docs/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以通过设置 `MAX_THINKING_TOKENS` [环境变量](/docs/zh-CN/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）来降低预算。自适应推理模型忽略非零预算，因此请改用 effort 级别。

367 367

368<h3 id="delegate-verbose-operations-to-subagents">368<h3 id="delegate-verbose-operations-to-subagents">

369 将冗长的操作委托给 subagents369 将冗长的操作委托给子代理

370</h3>370</h3>

371 371

372运行测试、获取文档或处理日志文件可能会消耗大量上下文。将这些委托给 [subagents](/docs/zh-CN/sub-agents#isolate-high-volume-operations)，以便冗长的输出保留在 subagent 的上下文中，而只有摘要返回到您的主对话。372运行测试、获取文档或处理日志文件可能会消耗大量上下文。将这些委托给[子代理](/docs/zh-CN/sub-agents#isolate-high-volume-operations)，以便冗长的输出保留在子代理的上下文中，而只有摘要返回到您的主对话。

373 373

374subagent 自己的请求仍然会消耗您的使用量。为了在这些请求上花费更少，[为 subagent 选择更小的模型](/docs/zh-CN/sub-agents#choose-a-model)或[在一个模型上运行每个 subagent](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。374子代理自己的请求仍然会消耗您的使用量。为了在这些请求上花费更少，[为子代理选择更小的模型](/docs/zh-CN/sub-agents#choose-a-model)或[在一个模型上运行每个子代理](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。

375 375

376<h3 id="manage-agent-team-costs">376<h3 id="manage-agent-team-costs">

377 管理 agent 团队成本377 管理 agent team 成本

378</h3>378</h3>

379 379

380当队友在 plan mode 中运行时，Agent 团队使用的令牌大约是标准会话的 7 倍，因为每个队友维护自己的上下文窗口并作为单独的 Claude 实例运行。保持团队任务小且独立，以限制每个队友的令牌使用。有关详细信息，请参阅 [agent 团队](/docs/zh-CN/agent-teams)。380当队友在计划模式中运行时，agent team 使用的 token 大约是标准会话的 7 倍，因为每个队友维护自己的上下文窗口并作为单独的 Claude 实例运行。保持团队任务小且独立，以限制每个队友的 token 使用。有关详细信息，请参阅 [agent team](/docs/zh-CN/agent-teams)。

381 381

382<h3 id="write-specific-prompts">382<h3 id="write-specific-prompts">

383 编写具体的提示383 编写具体的提示词

384</h3>384</h3>

385 385

386模糊的请求（如"改进此代码库"）会触发广泛扫描。具体的请求（如"向 auth.ts 中的登录函数添加输入验证"）让 Claude 能够以最少的文件读取高效地工作。386模糊的请求（如"改进此代码库"）会触发广泛扫描。具体的请求（如"向 auth.ts 中的登录函数添加输入验证"）让 Claude 能够以最少的文件读取高效地工作。

389 高效处理复杂任务389 高效处理复杂任务

390</h3>390</h3>

391 391

392对于较长或更复杂的工作，这些习惯有助于避免因走错路而浪费的令牌：392对于较长或更复杂的工作，这些习惯有助于避免因走错路而浪费的 token：

393 393

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

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

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

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

398 398

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

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

deep-links.md +9 −3

Details

166 注册和支持的平台166 注册和支持的平台

167</h2>167</h2>

168 168

169Claude Code 在你第一次在 macOS、Linux 和 Windows 上发送交互式会话的第一个提示时向你的操作系统注册 `claude-cli://` 处理程序。启动 `claude` 并在不发送提示的情况下退出不会注册处理程序。你不需要运行单独的安装命令。注册仅写入用户级位置：169在 macOS、Linux 和 Windows 上，当您在交互式会话中发送第一个提示词时，Claude Code 会向您的操作系统注册 `claude-cli://` 处理程序。启动 `claude` 并在不发送提示词的情况下退出不会注册处理程序。您不需要运行单独的安装命令。注册仅写入用户级位置：

170 170

171| 平台 | 处理程序位置 |171| 平台 | 处理程序位置 |

172| - | - |172| - | - |

176 176

177处理程序在检测到的终端模拟器中启动 Claude Code。在 macOS 上，Claude Code 记住你最近交互式会话中的终端并重复使用它，支持 iTerm2、Ghostty、kitty、Alacritty、WezTerm 和 Terminal.app。在 Linux 上，它遵守 `$TERMINAL` 环境变量，然后是 `x-terminal-emulator`，然后是常见模拟器的列表。在 Windows 上，它优先选择 Windows Terminal，然后是 PowerShell，然后是 `cmd.exe`。177处理程序在检测到的终端模拟器中启动 Claude Code。在 macOS 上，Claude Code 记住您最近交互式会话中的终端并重复使用它，支持 iTerm2、Ghostty、kitty、Alacritty、WezTerm 和 Terminal.app。在 Linux 上，它遵守 `$TERMINAL` 环境变量，然后是 `x-terminal-emulator`，然后是常见模拟器的列表。在 Windows 上，它优先选择 Windows Terminal，然后是 PowerShell，然后是 `cmd.exe`。

178 178

179要完全防止注册，在 `settings.json` 中将 [`disableDeepLinkRegistration`](/docs/zh-CN/settings-reference#disabledeeplinkregistration) 设置为 `"disable"`。要在整个组织中强制执行此操作，使用户无法重新启用它，请改为在[托管设置](/docs/zh-CN/server-managed-settings)中设置它。179要完全防止注册，在 `settings.json` 中将 [`disableDeepLinkRegistration`](/docs/zh-CN/settings-reference#disabledeeplinkregistration) 设置为 `"disable"`。要在整个组织中强制执行此操作，使用户无法重新启用它，请改为在[托管设置](/docs/zh-CN/server-managed-settings)中设置它。Claude Code 的 `disableDeepLinkRegistration` 设置仅适用于 `claude-cli://` 链接。

180 180

181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">

182 打开 VS Code 标签页而不是终端182 打开 VS Code 标签页而不是终端

184 184

185VS Code 扩展在 `vscode://anthropic.claude-code/open` 注册自己的处理程序，它打开一个 Claude Code 编辑器标签页而不是终端窗口。请参阅[从其他工具启动 VS Code 标签页](/docs/zh-CN/vs-code#launch-a-vs-code-tab-from-other-tools)了解该 URL 的参数。185VS Code 扩展在 `vscode://anthropic.claude-code/open` 注册自己的处理程序，它打开一个 Claude Code 编辑器标签页而不是终端窗口。请参阅[从其他工具启动 VS Code 标签页](/docs/zh-CN/vs-code#launch-a-vs-code-tab-from-other-tools)了解该 URL 的参数。

186 186

187<h2 id="open-a-claude-desktop-session-on-an-ssh-connection">

188 在 SSH 连接上打开 Claude Desktop 会话

189</h2>

190

191Claude Desktop 会自行处理其 `claude://` 链接。要通过 SSH 在远程机器上打开 Desktop 会话，请参阅[通过链接打开 SSH 会话](/docs/zh-CN/desktop#open-an-ssh-session-from-a-link)。

192

187<h2 id="troubleshooting">193<h2 id="troubleshooting">

188 故障排除194 故障排除

189</h2>195</h2>

desktop.md +59 −8

Details

108 自动模式可用性108 自动模式可用性

109</h4>109</h4>

110 110

111自动模式对 Anthropic API 上的所有用户可用，需要 Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 [Fable 模型](/docs/zh-CN/model-config#work-with-fable)。组织管理员可以使用[托管设置](#managed-settings)中的 `disableAutoMode` 键关闭自动模式。111自动模式对 Anthropic API 上的所有用户可用，需要 Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本、Haiku 5.5，或 [Fable 模型](/docs/zh-CN/model-config#work-with-fable)。组织管理员可以使用[托管设置](#managed-settings)中的 `disableAutoMode` 键关闭自动模式。

112 112

113在将 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自动模式也默认可用；有关支持的模型，请参阅 [Bedrock、Agent Platform 或 Foundry 上的自动模式](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。113在将 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自动模式也默认可用；有关支持的模型，请参阅 [Bedrock、Agent Platform 或 Foundry 上的自动模式](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。

114 114

225 在终端中运行命令225 在终端中运行命令

226</h3>226</h3>

227 227

228集成终端让您无需切换到另一个应用即可在会话旁运行命令。点击会话标题栏中的 **Terminal**，或在 macOS 或 Windows 上按 **Ctrl+\`**。终端在您的会话工作目录中打开，并与 Claude 共享相同的环境，因此 `npm test` 或 `git status` 等命令看到 Claude 正在编辑的相同文件。要打开第二个终端选项卡，点击终端窗格标题中的 **+** 或右键点击聊天中的文件夹来选择 **Open in terminal**。终端仅在本地会话中可用。228集成终端让您无需切换到另一个应用即可在会话旁运行命令。点击会话标题栏中的 **Terminal**，或在 macOS 或 Windows 上按 **Ctrl+\`**。终端在您的会话工作目录中打开，并与 Claude 共享相同的环境，因此 `npm test` 或 `git status` 等命令看到 Claude 正在编辑的相同文件。要打开第二个终端选项卡，点击终端窗格标题中的 **+** 或右键点击聊天中的文件夹来选择 **Open in terminal**。终端在本地和 [SSH](#ssh-sessions) 会话中可用。

229 229

230<h3 id="open-and-edit-files">230<h3 id="open-and-edit-files">

231 打开和编辑文件231 打开和编辑文件

743 743

744要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。744要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。

745 745

746[Extended thinking](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。在 Anthropic API 上，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0` 来关闭思考；这对 Opus 5.5、Sonnet 5.5 或 Fable 模型没有影响，它们始终使用 extended thinking。在 Anthropic API 上关闭思考后，Claude Code 发送努力级别 `high` 而不是更高级别给它知道的[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。746[扩展思考](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但会使用额外的 token。在 Anthropic API 上，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0` 来关闭思考；这对 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型没有影响，它们始终使用扩展思考。在 Anthropic API 上关闭思考后，Claude Code 会向它已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5）发送努力级别 `high`，而不是更高级别。

747 747

748在具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型上，对于为正数的 `MAX_THINKING_TOKENS` 值，Claude Code 会忽略该数值本身，因为思考深度改由自适应推理控制。在 Opus 4.6 和 Sonnet 4.6 上，将 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 设置为 `1` 可使用固定思考预算；Fable 模型、Sonnet 5 及更高版本以及 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。748在具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型上，对于为正数的 `MAX_THINKING_TOKENS` 值，Claude Code 会忽略该数值本身，因为思考深度改由自适应推理控制。在 Opus 4.6 和 Sonnet 4.6 上，将 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 设置为 `1` 可使用固定思考预算；Fable 模型、Sonnet 5 及更高版本、Haiku 5.5 以及 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。

749 749

750<h4 id="local-sessions-on-managed-devices">750<h4 id="local-sessions-on-managed-devices">

751 托管设备上的本地会话751 托管设备上的本地会话

783 783

784远程机器必须运行 Linux 或 macOS。Desktop 在你第一次连接时会自动在远程机器上安装 Claude Code。连接后，SSH 会话支持权限模式、connectors、plugins 和 MCP servers。784远程机器必须运行 Linux 或 macOS。Desktop 在你第一次连接时会自动在远程机器上安装 Claude Code。连接后，SSH 会话支持权限模式、connectors、plugins 和 MCP servers。

785 785

786<h4 id="open-an-ssh-session-from-a-link">

787 通过链接打开 SSH 会话

788</h4>

789

790`claude://code/new` 链接会打开 Desktop 的新会话页面，并且可以指定一个 SSH 连接。将此类链接放入运维手册、仪表板或 wiki 页面中，即可打开已为正确的机器和文件夹设置好的 Desktop。对于会去除此类链接的平台，请参阅[链接显示为纯文本而不可点击](/docs/zh-CN/deep-links#the-link-renders-as-plain-text-instead-of-being-clickable)。

791

792SSH 链接需要 Claude Desktop v2.110.0 或更高版本。

793

794以下链接指定了 `build.example.com` 上的用户 `dev`、端口 2222 和文件夹 `/srv/payments`，并填入一条提示词：

795

796```text theme={null}

797claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

798```

799

800SSH 链接接受以下参数，其中只有 `ssh_host` 是必需的：

801

802| 参数 | 值 |

803| :- | :- |

804| `ssh_host` | `host` 或 `user@host`，写法与 **SSH host** 字段相同。该值不能以 `-` 开头，主机部分只能包含字母、数字、`.`、`_`、`:` 和 `-` |

805| `ssh_port` | 1 到 65535 之间的端口号 |

806| `ssh_folder` | 远程机器上的文件夹。以 `/` 或 `~/` 开头，或使用 `~` |

807| `q` | 用于输入框的 URL 编码文本 |

808

809`~/.ssh/config` 中的别名仅对拥有该条目的人可用作 `ssh_host`。要匹配用户已有的连接，请在链接中使用与该连接相同的用户、主机和端口。

810

811当您打开链接时，Desktop 会在选择连接之前要求您确认：

812

813* **您已有的连接**：如果主机、用户和端口与您的某个连接匹配，Desktop 会询问是否使用它，并向您显示该连接的名称和主机，如果链接指定了文件夹，还会显示文件夹。

814* **新连接**：否则，Desktop 会打开用于添加 SSH 连接的对话框。当您添加连接时，Desktop 会在保存任何内容之前询问是否连接，并向您显示链接中的主机，如果链接指定了端口和文件夹，还会显示它们。

815

816在您确认之前，Desktop 不会保存链接中的主机、端口或文件夹，也不会使用它们选择或打开连接。如果已经选择了某个 SSH 连接，新会话页面仍可以像没有链接时一样自行连接到该连接，即使链接指定了相同的主机也是如此。链接不能携带密钥文件、密码或命令。

817

818任何人都可以编写链接，因此请检查它填入的内容：

819

820* **确认之前**：检查主机和文件夹。

821* **发送之前**：检查提示词和所选环境。

822

823Desktop 会在链接打开时填入提示词，替换您尚未发送的任何文本，并且绝不会替您发送。它将提示词视为纯文本，因此开头的 `/` 或 `!` 以及 `@` 文件提及不会作为命令或提及生效。如果您取消，提示词会保留在输入框中，您之前选择的环境也不会改变。

824

825链接不会绕过 [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to)。Desktop 会在连接时检查允许列表。

826

827如果链接打开了 Desktop 却没有出现关于连接的对话框，请检查是否存在以下原因之一：

828

829* **您已退出登录**：请登录，然后再次打开链接。

830* **另一个对话框处于打开状态**：关闭它，然后再次打开链接。

831* **链接无效**：Desktop 会显示一条消息说明需要修正的内容，并且不会填入提示词。

832* **Desktop 版本早于 v2.110.0**：早期版本会忽略 SSH 参数，仅带着提示词打开新会话页面。

833* **SSH 会话已关闭**：如果您的管理员将允许列表设置为空数组，Desktop 会拒绝 SSH 链接。

834

786<h4 id="pre-configure-ssh-connections-for-your-team">835<h4 id="pre-configure-ssh-connections-for-your-team">

787 为你的团队预配置 SSH 连接836 为你的团队预配置 SSH 连接

788</h4>837</h4>

805}854}

806```855```

807 856

808每个条目需要 `id`、`name` 和 `sshHost`。`sshPort` 和 `sshIdentityFile` 字段是可选的。用户也可以将 `sshConfigs` 添加到他们自己的 `~/.claude/settings.json`，这是通过对话框添加的连接存储的位置。857每个条目需要 `id`、`name` 和 `sshHost`。`sshPort` 和 `sshIdentityFile` 字段是可选的。用户也可以将 `sshConfigs` 添加到他们自己的 `~/.claude/settings.json`。

809 858

810<h4 id="restrict-which-ssh-hosts-users-can-connect-to">859<h4 id="restrict-which-ssh-hosts-users-can-connect-to">

811 限制用户可以连接的 SSH 主机860 限制用户可以连接的 SSH 主机

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

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

918| `disableSshSavedPasswords` | 设置为 `true` 以阻止 Desktop 提供记住 SSH 密码的选项，并阻止其使用或显示之前保存的密码。启用此设置不会删除这些密码。仅从托管设置中读取。需要 Claude Desktop v1.49585.0 或更高版本。 |

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

870 920

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

872 922

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

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

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

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

877 927

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

885 设备管理策略935 设备管理策略

886</h3>936</h3>

887 937

888IT 团队可以通过 macOS 上的 MDM 或 Windows 上的组策略管理桌面应用。可用的策略包括启用或禁用 Claude Code 功能、控制自动更新和设置自定义部署 URL。938IT 团队可以通过 macOS 上的 MDM、Windows 上的组策略或 Linux 上的策略文件管理桌面应用。可用的策略包括启用或禁用 Claude Code 功能、在 macOS 和 Windows 上控制自动更新以及设置自定义部署 URL。

889 939

890* **macOS**：通过使用 Jamf 或 Kandji 等工具的 `com.anthropic.claudefordesktop` 偏好域配置940* **macOS**：通过使用 Jamf 或 Kandji 等工具的 `com.anthropic.claudefordesktop` 偏好域配置

891* **Windows**：通过 `SOFTWARE\Policies\Claude` 处的注册表配置941* **Windows**：通过 `SOFTWARE\Policies\Claude` 处的注册表配置

942* **Linux**：通过位于 `/etc/claude-desktop/managed-settings.json` 的 root 所有的文件配置，该文件以 JSON 对象形式保存策略键。如果除 root 之外的任何人可以写入该文件或其所在文件夹，Desktop 将拒绝使用该文件。它与 Claude Code 的[托管设置文件](/docs/zh-CN/managed-settings)是不同的文件。

892 943

893<h3 id="network-access-requirements">944<h3 id="network-access-requirements">

894 网络访问要求945 网络访问要求

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

1093 1144

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

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

1096 1147

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

1098 1149

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 +281 −277

Details

93}93}

94```94```

95 95

96Claude Code 会按原样将这些值复制到其环境中。这些值不经过任何 shell 处理，因此 `~` 或 `$HOME` 等简写会保持输入时的原样。对于接受路径的变量（例如 `CLAUDE_CONFIG_DIR`），请写入绝对路径：`"CLAUDE_CONFIG_DIR": "/home/you/.claude-work"`。

96您选择的文件控制变量应用于谁：98您选择的文件控制变量应用于谁：

97 99

98| 文件 | 应用于 |100| 文件 | 应用于 |

124 变量126 变量

125</h2>127</h2>

126 128

127数值类变量（例如超时时间、token 预算和重试次数）除纯数字外，还接受科学记数法和数字分隔符写法，除非某个变量所在行注明它仅接受纯数字。例如，Claude Code 将 `2e3` 读取为 2000，将 `64_000` 读取为 64000。在 v2.1.211 之前，这些写法可能会在没有任何提示的情况下设置一个小得多的值，例如 `1e6` 会将超时时间设置为 1。129超时时间、token 预算和重试次数等数值变量除了接受纯数字外，还接受科学计数法和数字分隔符写法，除非该变量所在行注明只接受纯数字。例如，Claude Code 将 `2e3` 读作 2000，将 `64_000` 读作 64000。在 v2.1.211 之前，这些写法可能会在无提示的情况下设置一个小得多的值，例如 `1e6` 会将超时时间设置为 1。

128 130

129<Note>131<Note>

130 对于用于启用或关闭某项行为的变量，设置 `1`、`true`、`yes` 或 `on` 可启用该行为，设置 `0`、`false`、`no` 或 `off` 可关闭该行为，不区分大小写。132 对于用于启用或关闭某项行为的变量，设置为 `1`、`true`、`yes` 或 `on` 可启用，设置为 `0`、`false`、`no` 或 `off` 可关闭，不区分大小写。

131 133

132 有些变量只检查您是否设置了它们，因此任何非空值（包括 `0`）都会启用该行为；要关闭该行为，需取消设置该变量或将其设为空值。以下变量按此方式工作：134 有些变量只检查是否已设置，因此任何非空值（包括 `0`）都会启用该行为；要关闭该行为，请取消设置该变量或将其设置为空值。以下变量采用这种方式：

133 135

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`137 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`141 * `IS_DEMO`

140 142

141 还有一个变量有其自己的规则：`FORCE_HYPERLINK` 读取的是数字，因此只有 `0` 会将其关闭。每个变量所在行也会说明其自身的规则。143 另有一个变量有自己的规则：`FORCE_HYPERLINK` 读取一个数字，因此只有 `0` 会将其关闭。每个变量所在行也会说明其自身的规则。

142</Note>144</Note>

143 145

144| 变量 | 用途 |146| 变量 | 用途 |

145| :- | :- |147| :- | :- |

146| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，也会使用此密钥，而不是您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）下，只要存在该密钥就始终会使用它。在交互模式下，系统会提示您批准该密钥一次，之后它才会覆盖您的订阅。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |148| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，也会使用此密钥，而不是您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）下，只要存在该密钥，就始终使用它。在交互模式下，系统会提示您批准该密钥一次，之后它才会覆盖您的订阅。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |

148| `ANTHROPIC_AWS_API_KEY` | 用于 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS Console 中生成。作为 `x-api-key` 发送，并优先于 AWS SigV4 |150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS Console 中生成。作为 `x-api-key` 发送，并优先于 AWS SigV4 |

149| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 按照[与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code)解析区域 |151| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 按照[与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code)解析区域 |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 必需。每个请求都会将其作为 `anthropic-workspace-id` 标头发送 |152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 必需。作为 `anthropic-workspace-id` 标头随每个请求发送 |

151| `ANTHROPIC_BASE_URL` | 覆盖 API 端点，以便通过代理或网关路由请求。当设置为非第一方主机时，[MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)默认处于禁用状态。如果您的代理会转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 将被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为一致 |153| `ANTHROPIC_BASE_URL` | 覆盖 API 端点，以通过代理或网关路由请求。当设置为非第一方主机时，默认禁用 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。如果您的代理会转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 将被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为一致 |

152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |

153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |

154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 优先尝试的跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而不是根据 AWS 区域推导出的前缀。在 AWS GovCloud 区域中会被忽略。需要 Claude Code v2.1.224 或更高版本。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 优先尝试的跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而不是从 AWS 区域派生的前缀。在 AWS GovCloud 区域中会被忽略。需要 Claude Code v2.1.224 或更高版本。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |

155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层级](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层级](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |

156| `ANTHROPIC_BETAS` | 要包含在 API 请求中的其他 `anthropic-beta` 标头值的逗号分隔列表。Claude Code 已经会发送其所需的 beta 标头；使用此变量可在 Claude Code 添加原生支持之前选择加入某个 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方式，包括 Claude.ai 订阅 |158| `ANTHROPIC_BETAS` | 要包含在 API 请求中的额外 `anthropic-beta` 标头值的逗号分隔列表。Claude Code 已经会发送其所需的 beta 标头；在 Claude Code 添加原生支持之前，可使用此变量选择加入某项 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方式，包括 Claude.ai 订阅 |

157| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求中的自定义标头（`Name: Value` 格式，多个标头以换行分隔）。如果名称或值包含 HTTP 标头无法承载的字符（例如弯引号或零宽空格），请求将失败，并显示一个按位置标识该名称-值对的错误。需要 Claude Code v2.1.227 或更高版本。[无效的请求标头值](/docs/zh-CN/errors#invalid-request-header-value)列出了确切的字符集以及该检查的运行位置。如果某个值设置了凭据、组织或租户、路由或 API 行为相关的标头（例如 `Authorization` 或 `Host`），当它由服务器托管设置下发时，会被视为[需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。如果此类值来自项目设置或本地设置，则遵循[`env` 值何时生效的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |159| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求中的自定义标头（`Name: Value` 格式，多个标头以换行分隔）。如果名称或值包含 HTTP 标头无法承载的字符，例如弯引号或零宽空格，请求将失败，并显示一条按位置标识该键值对的错误。需要 Claude Code v2.1.227 或更高版本。[Invalid request header value](/docs/zh-CN/errors#invalid-request-header-value) 列出了确切的字符集以及检查的运行位置。设置凭据、组织或租户、路由或 API 行为标头（例如 `Authorization` 或 `Host`）的值，在由服务器托管设置下发时，算作[需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。在项目或本地设置中，此类值遵循[何时应用 `env` 值的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要作为自定义条目添加到 `/model` 选择器中的模型 ID。使用此变量可让非标准或网关特定的模型可供选择，而无需替换内置别名。请参阅[模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要作为自定义条目添加到 `/model` 选择器中的模型 ID。可使用此变量让非标准或网关专用的模型变为可选，而无需替换内置别名。请参阅[模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [能识别该 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，该条目显示模型名称，否则显示模型 ID |162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [能识别该 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，条目显示模型名称，否则显示模型 ID |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自定义模型所支持的[功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自定义模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析到的模型 ID，也是 Claude Code 在第三方提供商上进行[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)时识别为 Fable 模型的 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析到的模型 ID，也是 Claude Code 在第三方提供商上进行[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)时识别为 Fable 模型的 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Fable 模型的显示描述。未设置时，该行显示以 `Custom Fable model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Fable 模型的显示描述。未设置时，该行显示以 `Custom Fable model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定的 Fable 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定的 Fable 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Fable 模型所支持的[功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Fable 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析到的模型 ID，也用于[后台功能](/docs/zh-CN/costs#background-token-usage)。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析到的模型 ID，也用于[后台功能](/docs/zh-CN/costs#background-token-usage)。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Haiku 模型的显示描述。未设置时，该行显示以 `Custom Haiku model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Haiku 模型的显示描述。未设置时，该行显示以 `Custom Haiku model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定的 Haiku 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定的 Haiku 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Haiku 模型所支持的[功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Haiku 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动时使用的模型。需要 Claude Code v2.1.236 或更高版本。请参阅[为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |172| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动时使用的模型。需要 Claude Code v2.1.236 或更高版本。请参阅[为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |

171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析到的模型 ID，也是 `opusplan` 在计划模式处于活动状态时使用的模型。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析到的模型 ID，也是 `opusplan` 在计划模式激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Opus 模型的显示描述。未设置时，该行显示以 `Custom Opus model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Opus 模型的显示描述。未设置时，该行显示以 `Custom Opus model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定的 Opus 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定的 Opus 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Opus 模型所支持的[功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Opus 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析到的模型 ID，也是 `opusplan` 在计划模式未处于活动状态时使用的模型。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析到的模型 ID，也是 `opusplan` 在计划模式未激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Sonnet 模型的显示描述。未设置时，该行显示以 `Custom Sonnet model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Sonnet 模型的显示描述。未设置时，该行显示以 `Custom Sonnet model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定的 Sonnet 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定的 Sonnet 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Sonnet 模型所支持的[功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Sonnet 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 会选择联合凭据，其优先级高于您的 `/login` 凭据。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 会选择联合凭据，其优先级高于您的 `/login` 凭据。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

180| `ANTHROPIC_FOUNDRY_API_KEY` | 用于 Microsoft Foundry 身份验证的 API 密钥（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_API_KEY` | 用于 Microsoft Foundry 身份验证的 API 密钥（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用于 Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭据链。请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用于 Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭据链。请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |

182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如 `my-resource`）。Claude Code [会拒绝 URL 或主机名](/docs/zh-CN/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如 `my-resource`）。Claude Code [会拒绝 URL 或主机名](/docs/zh-CN/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

185| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。请将其与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。请将其与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

186| `ANTHROPIC_PROFILE` | 用于身份验证的 Anthropic 配置文件名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 或[在没有 API 密钥的情况下登录 Console 账户](/docs/zh-CN/authentication#sign-in-without-an-api-key)所创建的配置文件。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |188| `ANTHROPIC_PROFILE` | 用于身份验证的 Anthropic 配置文件名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 或[在没有 API 密钥的情况下登录 Console 账户](/docs/zh-CN/authentication#sign-in-without-an-api-key)所创建的配置文件。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时，覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，仅当同时设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才会生效，因为否则 Amazon Bedrock 会在会话所在区域使用[默认 Sonnet 模型或主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions)运行后台任务 |190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时，覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，仅当同时设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才生效，因为否则 Amazon Bedrock 会在会话区域中使用[默认 Sonnet 模型或主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions)运行后台任务 |

189| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) |191| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) |

190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求所发往的 GCP 项目 ID。请参阅[配置 GCP 凭据](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求所发往的 GCP 项目 ID。请参阅[配置 GCP 凭据](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |

191| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)的工作区 ID。当您的联合规则的范围涵盖多个工作区时设置此项，以便令牌交换知道要以哪个工作区为目标 |193| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作区 ID。当您的联合规则作用于多个工作区时设置此变量，以便令牌交换知道要定位哪个工作区 |

192| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的响应体空闲超时，该超时会在没有字节到达时中止流式模型响应。设置为 `0` 可关闭该超时，例如当缓慢的[网关](/docs/zh-CN/llm-gateway)或本地模型在数据块之间暂停超过 5 分钟时；设置为 `1` 可对所有提供商保持启用。未设置时，该超时在直连 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 以及设置了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的提供商上生效。[流式看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs)独立于它运行，即使您在此处设置了 `0`，它们也会中止长时间的静默暂停 |194| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的响应体空闲超时，该超时会在没有字节到达时中止流式模型响应。设置为 `0` 可关闭该超时，例如当缓慢的[网关](/docs/zh-CN/llm-gateway)或本地模型在数据块之间暂停超过 5 分钟时；设置为 `1` 可在所有提供商上保持启用。未设置时，该超时在直接 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 以及设置了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的提供商上生效。[流式看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs)独立于它运行，即使您在此处设置了 `0`，也会中止长时间的静默暂停 |

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

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

195| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间，以毫秒为单位（默认值：120000，即 2 分钟）。超过 30 分钟的默认值还会成为无人值守会话中[后台命令的默认时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |197| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间（毫秒）（默认值：120000，即 2 分钟）。超过 30 分钟的默认值也会成为无人值守会话中[后台命令的默认时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |

196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回到命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。请参阅[输出限制](/docs/zh-CN/tools-reference#output-limits) |198| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。请参阅[输出限制](/docs/zh-CN/tools-reference#output-limits) |

197| `BASH_MAX_TIMEOUT_MS` | 模型可以为前台 Bash 或 PowerShell 工具命令设置的最大超时时间，以毫秒为单位（默认值：600000，即 10 分钟）。有效上限为此值与 `BASH_DEFAULT_TIMEOUT_MS` 中的较大者。超过 2 小时的有效上限还会成为无人值守会话中[后台命令的最大时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |199| `BASH_MAX_TIMEOUT_MS` | 模型可为前台 Bash 或 PowerShell 工具命令设置的最大超时时间（毫秒）（默认值：600000，即 10 分钟）。有效上限为此值与 `BASH_DEFAULT_TIMEOUT_MS` 中的较大者。超过 2 小时的有效上限也会成为无人值守会话中[后台命令时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)的最大值。后台时间限制需要 Claude Code v2.1.285 或更高版本 |

198| `BETA_TRACING_ENDPOINT` | [详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)的 OTLP/HTTP 端点：设置 `ENABLE_BETA_TRACING_DETAILED=1` 后，日志和追踪数据会发送到此处，而不是发送到已配置的导出器。请在您的 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |200| `BETA_TRACING_ENDPOINT` | 用于[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)的 OTLP/HTTP 端点：在设置 `ENABLE_BETA_TRACING_DETAILED=1` 时，日志和追踪会发送到该端点，而不是已配置的导出器。请在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

199| `CCR_FORCE_BUNDLE` | 设置为 `1` 可强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 打包并上传您的本地仓库，而不是从其远程仓库克隆 |201| `CCR_FORCE_BUNDLE` | 设置为 `1` 可强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 打包并上传您的本地仓库，而不是从其远程克隆 |

200| `CLAUDECODE` | 在 Claude Code 生成的子进程（Bash 和 PowerShell 工具、tmux 会话、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令、stdio [MCP 服务器](/docs/zh-CN/mcp)子进程）中设置为 `1`。IDE 扩展也会在其集成终端中设置此变量。用于检测脚本是否正在 Claude Code 生成的子进程中运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内部运行，请改用 `CLAUDE_CODE_CHILD_SESSION` |202| `CLAUDECODE` | 在 Claude Code 生成的子进程（Bash 和 PowerShell 工具、tmux 会话、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令、stdio [MCP 服务器](/docs/zh-CN/mcp)子进程）中设置为 `1`。IDE 扩展也会在其集成终端中设置此变量。用于检测脚本是否在 Claude Code 生成的子进程中运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内部生成，请改用 `CLAUDE_CODE_CHILD_SESSION` |

201| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在自动继续之前多少毫秒显示屏幕倒计时。默认值 `20000`（20 秒），上限为自动继续超时时间。除非启用了自动继续，否则不起作用；请参阅 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |203| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在自动继续前多少毫秒显示屏幕倒计时。默认值 `20000`（20 秒），上限为自动继续超时时间。除非启用了自动继续，否则无效；请参阅 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |

202| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您介入即自动继续。自动继续默认处于关闭状态；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置 `0` 不会关闭超时，而是会立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认处于启用状态，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您参与即自动继续。自动继续默认关闭；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置 `0` 不会关闭超时，而是立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认启用，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。适用于希望从空白状态开始的 SDK 用户。这还会移除 `general-purpose`，即 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此类调用随后会失败，并显示 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于希望从零开始的 SDK 用户很有用。这也会移除 `general-purpose`，即当 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此类调用随后将失败并显示 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间，以毫秒为单位。默认值 `600000`（10 分钟）；如果您在流式看门狗启用时调高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，如[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。计时器会在每个流式进度事件时重置；如果在该时间窗口内没有收到任何进度，Claude Code 会中止该子代理并向父级报告停滞 |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间（毫秒）。默认值 `600000`（10 分钟）；如果您在流式看门狗启用时提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，如[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。计时器会在每个流式进度事件时重置；如果在该时间窗口内没有进度到达，Claude Code 会中止该子代理并向父级报告停滞 |

206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（如 `50`）可更早压缩；此变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（例如 `50`）可更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前进行压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |

207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台运行。启用后，子代理在运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本中，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台运行](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台化。启用后，子代理运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本上，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台化](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |

208| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待时间上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |210| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待时间上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |

209| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 可渲染适合屏幕阅读器的输出：不带装饰性边框或动画的纯文本。设置为 `0` 可强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |211| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 可渲染适合屏幕阅读器的输出：不带装饰性边框或动画的纯文本。设置为 `0` 可强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在启动确认行之后暂缓首次界面渲染的毫秒数，以便您的屏幕阅读器能在新输出打断之前完整朗读该行。默认值 `3000`。设置 `0` 可立即渲染。Claude Code 将暂缓时间上限设为 `600000`（10 分钟）。您的第一次按键会提前结束暂缓。需要 Claude Code v2.1.217 或更高版本 |212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在启动确认行之后推迟首次界面渲染的毫秒数，以便您的屏幕阅读器在新输出打断之前完整朗读该行。默认值 `3000`。设置 `0` 可立即渲染。Claude Code 将推迟时间上限设为 `600000`（10 分钟）。您的第一次按键会提前结束推迟。需要 Claude Code v2.1.217 或更高版本 |

212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲看门狗的超时时间，以毫秒为单位；设置后，对于该看门狗，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不会改变事件级看门狗。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲看门狗的超时时间（毫秒）；设置后，对于该看门狗，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，并保持事件级看门狗不变。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | 某个文件的路径，外部工具（例如锁屏监听器）会在您解锁屏幕时创建该文件，并在您锁屏时删除它。该文件存在期间，Claude Code 会跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，这样您在主动使用计算机时就不会收到推送。当该文件不存在或无法读取时，通知会照常发送。Claude Code 在每个触发推送的事件发生时检查一次该文件，而不是轮询它。需要 Claude Code v2.1.181 或更高版本 |215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一个文件的路径，该文件由外部工具（例如锁屏监听器）在您解锁屏幕时创建、在您锁定屏幕时删除。当该文件存在时，Claude Code 会跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，这样您在主动使用计算机时就不会收到推送。当该文件不存在或无法读取时，通知照常发送。Claude Code 在每次触发推送的事件时检查一次该文件，而不是轮询。需要 Claude Code v2.1.181 或更高版本 |

215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 可从通过 `--add-dir` 指定的目录加载记忆文件。加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，附加目录不会加载记忆文件 |217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 可从通过 `--add-dir` 指定的目录加载记忆文件。加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，附加目录不会加载记忆文件 |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中每一帧都重绘整个屏幕，而不是发送增量更新。如果全屏模式显示过时或错位的文本片段，请使用此设置。Claude Code 会在 Windows 上为后台会话和 [Agent 视图](/docs/zh-CN/agent-view)自动启用此功能 |218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中每帧重绘整个屏幕，而不是发送增量更新。如果全屏模式显示过时或错位的文本片段，请使用此选项。Claude Code 会在 Windows 上为后台会话和 [Agent 视图](/docs/zh-CN/agent-view)自动启用此选项 |

217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 可在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 未将该模型 ID 识别为支持 effort。在通过 [LLM 网关](/docs/zh-CN/llm-gateway)或以自定义标识符提供模型的第三方提供商进行路由时使用此变量。在 API 层面拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍会被排除在外，以免请求失败 |219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 可在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 未将该模型 ID 识别为支持 effort。通过 [LLM 网关](/docs/zh-CN/llm-gateway)或以自定义标识符提供模型的第三方提供商路由时使用此选项。在 API 层拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍会被排除，因此请求不会失败 |

218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭据的时间间隔，以毫秒为单位（使用 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 时） |220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭据的时间间隔（毫秒）（使用 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 时） |

219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 可阻止 Claude Code 在发布新的 [Artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 可阻止 Claude Code 在发布新的 [Artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 可阻止 Claude 读取和回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[关闭 Artifact](/docs/zh-CN/artifacts#availability) 时不起作用。需要 Claude Code v2.1.221 或更高版本 |222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 可阻止 Claude 读取和回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[关闭 Artifact](/docs/zh-CN/artifacts#availability) 时无效。需要 Claude Code v2.1.221 或更高版本 |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 可阻止 Claude [自行回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 可阻止 Claude [自行回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |

222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 可从系统提示词开头省略[归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块包含客户端版本和提示词指纹。无论如何设置，直连 Anthropic API 时的缓存都不受影响。在某些直连配置中，即使您设置了 `0`，Claude Code 仍会在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器请求中保留该块。请在[系统提示词归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)中查看此情况涵盖哪些连接和凭据。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含一个每个请求各不相同的令牌，因此在这些版本上，当您的 LLM 网关基于请求体进行缓存或将请求转发给第三方提供商时，或者当您直接连接到 Microsoft Foundry 时，请将其设置为 `0` |224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 可从系统提示词开头省略[归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块包含客户端版本和提示词指纹。无论如何设置，直接连接 Anthropic API 时的缓存都不受影响。在某些直接连接配置中，即使您设置了 `0`，Claude Code 也会在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器请求中保留该块。请在[系统提示词归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)中查看此情况涵盖哪些连接和凭据。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含每个请求各不相同的 token，因此在这些版本上，当您的 LLM 网关根据请求体进行缓存或将请求转发给第三方提供商时，或者当您直接连接到 Microsoft Foundry 时，请将其设置为 `0` |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 为单位设置[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，范围为 `100000` 到 `1000000`。仅接受纯整数，例如 `500000`：像 `500k` 这样的值会被读取为 `500`，并被限制为 100K 的最小值。有效窗口还受模型上下文窗口的上限约束。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态栏的 `used_percentage` 始终以模型的完整上下文窗口为基准进行衡量，因此一旦设置了此变量，该百分比就不再能指示何时会运行压缩 |226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 为单位设置[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，范围为 `100000` 到 `1000000`。仅接受纯整数，例如 `500000`：像 `500k` 这样的值会被读作 `500`，并被限制为 100K 的最小值。有效窗口还会以模型的上下文窗口为上限。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态栏的 `used_percentage` 始终根据模型的完整上下文窗口计算，因此一旦设置了此变量，该百分比就不再表示何时会进行压缩 |

225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/docs/zh-CN/vs-code)。默认情况下，在受支持 IDE 的集成终端中启动时，Claude Code 会自动连接。设置为 `false` 可阻止此行为。设置为 `true` 可在自动检测失败时（例如 tmux 遮蔽了父终端时）强制尝试连接。优先于 [`autoConnectIde`](/docs/zh-CN/settings-reference#autoconnectide) 全局配置设置 |227| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/docs/zh-CN/vs-code)。默认情况下，在受支持的 IDE 集成终端中启动时，Claude Code 会自动连接。设置为 `false` 可阻止此行为。设置为 `true` 可在自动检测失败时（例如 tmux 遮蔽了父终端）强制尝试连接。优先于 [`autoConnectIde`](/docs/zh-CN/settings-reference#autoconnectide) 全局配置设置 |

226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否请求服务器[审查自动模式操作](/docs/zh-CN/permission-modes#server-side-classifier-review)。设置为 `0` 可改用 Claude Code 自己的分类器请求。在直连 Anthropic API 时，需要 v2.1.281 或更高版本。链接的章节列出了未设置该变量时哪些会话会请求服务器，以及从哪个版本开始。需要 Claude Code v2.1.271 或更高版本 |228| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否请求服务器[审查自动模式操作](/docs/zh-CN/permission-modes#server-side-classifier-review)。设置为 `0` 可改用 Claude Code 自己的分类器请求。在直接连接 Anthropic API 时，需要 v2.1.281 或更高版本。链接的章节列出了在未设置该变量时哪些会话会请求服务器，以及从哪个版本开始。需要 Claude Code v2.1.271 或更高版本 |

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭据提供程序链生成凭据的时间（以毫秒为单位），超时后请求会失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当凭据链中的某个步骤确实需要更长时间时（例如通过 `aws-vault` 之类的包装器进行带 MFA 的基于浏览器的 SSO 登录），请调高此值。适用于 Claude Code 使用默认链进行签名的所有场景：[Amazon Bedrock](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更高版本 |229| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭据提供程序链生成凭据的时间（毫秒），超时后请求将失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当链中某个步骤确实需要更长时间时，请提高此值，例如通过 `aws-vault` 等包装器进行带 MFA 的基于浏览器的 SSO 登录。适用于 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |

228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 设置为 `0` 可关闭 [Bash 命令运行期间已更改文件的 diff](/docs/zh-CN/hooks#bash)，设置为 `1` 可在所有权限模式下记录该 diff。优先于 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置。需要 Claude Code v2.1.269 或更高版本 |230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 设置为 `0` 可关闭[在 Bash 命令运行期间所更改文件的 diff](/docs/zh-CN/hooks#bash)，设置为 `1` 可在每种权限模式下记录它。优先于 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置。需要 Claude Code v2.1.269 或更高版本 |

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 设置为 `0` 可让非交互会话在每个轮次结束时向其宿主报告空闲状态，即使后台工作仍在运行。默认情况下，当后台 Agent 或[工作流](/docs/zh-CN/workflows)运行等后台工作仍处于活动状态时，会话在轮次结束后仍会持续报告运行状态。这可以防止监视该状态的宿主（例如远程会话列表）在工作进行中宣布 Claude 正在等待您的输入。后台 shell 命令（例如开发服务器）不会保持运行状态。运行状态这一默认行为以及 `0` 选择退出需要 Claude Code v2.1.269 或更高版本；在更早的版本上，设置 `1` 可保持运行状态 |231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 设置为 `0` 可使非交互会话在每个轮次结束时向其宿主报告空闲状态，即使后台工作仍在运行。默认情况下，当后台 Agent 或[工作流](/docs/zh-CN/workflows)运行等后台工作仍处于活动状态时，会话在轮次结束后会继续报告运行状态。这可以防止监视该状态的宿主（例如远程会话列表）在工作进行中宣布 Claude 正在等待您的输入。后台 shell 命令（例如开发服务器）不会保持运行状态。运行状态默认值和 `0` 选择退出需要 Claude Code v2.1.269 或更高版本；在更早的版本上，请设置 `1` 以保持运行状态 |

230| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 当会话具有活动的 [Remote Control](/docs/zh-CN/remote-control) 连接时，在 Bash 工具和 [hook 命令](/docs/zh-CN/hooks)子进程中自动设置，并在连接结束时移除。该值是 `session_` 形式的会话 ID，与会话的 `claude.ai/code` URL 中出现的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在[云端会话](/docs/zh-CN/claude-code-on-the-web)中，请改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 当会话具有活动的 [Remote Control](/docs/zh-CN/remote-control) 连接时，在 Bash 工具和 [hook 命令](/docs/zh-CN/hooks)子进程中自动设置，并在连接结束时移除。其值为 `session_` 形式的会话 ID，与会话的 `claude.ai/code` URL 中出现的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在[云端会话](/docs/zh-CN/claude-code-on-the-web)中，请改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 可让 Claude Code 将 `0x08` 字节（也写作 `^H`）读取为普通 Backspace，设置为 `1` 可将其读取为 Ctrl+Backspace。任一值都会替换平台默认行为。默认情况下，Claude Code 在 Windows 上将其读取为 Ctrl+Backspace（`TERM_PROGRAM` 为 `mintty` 或 `TERM` 为 `cygwin` 时除外），在 macOS 和 Linux 上将其读取为普通 Backspace。在 [Backspace 会删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 终端中，请设置 `0` |233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 可让 Claude Code 将 `0x08` 字节（也写作 `^H`）读作普通 Backspace，设置为 `1` 则读作 Ctrl+Backspace。任一值都会替换平台默认值。默认情况下，Claude Code 在 Windows 上将其读作 Ctrl+Backspace（`TERM_PROGRAM` 为 `mintty` 或 `TERM` 为 `cygwin` 时除外），在 macOS 和 Linux 上读作普通 Backspace。在 [Backspace 会删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 终端中，请设置 `0` |

232| `CLAUDE_CODE_CERT_STORE` | TLS 连接所用 CA 证书来源的逗号分隔列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件，或通过 npm 安装时的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store)。默认值为 `bundled,system` |234| `CLAUDE_CODE_CERT_STORE` | 用于 TLS 连接的 CA 证书来源的逗号分隔列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件，或 npm 安装时的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store)。默认值为 `bundled,system` |

233| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令以及[状态栏](/docs/zh-CN/statusline)命令生成的子进程中设置为 `1`。不会为 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程设置，因为它们是长期运行的，生命周期长于生成它们的会话。与 `CLAUDECODE` 不同，此变量仅由 Claude Code 本身在启动子进程时设置，而不会由 IDE 扩展设置，因此它能可靠地区分嵌套会话与在 IDE 集成终端中启动的顶层 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 会被自动排除在 `--resume`、`--continue`、向上箭头历史记录和 `claude agents` 列表之外。非交互的 `claude -p` 会话仍会持久保存。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆盖此排除行为。需要 Claude Code v2.1.172 或更高版本 |235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令和[状态栏](/docs/zh-CN/statusline)命令生成的子进程中设置为 `1`。不会为 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程设置，因为这些子进程长期运行，生命周期超过生成它们的会话。与 `CLAUDECODE` 不同，此变量仅在 Claude Code 自身启动子进程时设置，IDE 扩展不会设置，因此它可以可靠地区分嵌套会话与在 IDE 集成终端中启动的顶层 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 会自动从 `--resume`、`--continue`、向上箭头历史记录和 `claude agents` 列表中排除。非交互式 `claude -p` 会话仍会持久化。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆盖此排除。需要 Claude Code v2.1.172 或更高版本 |

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，现在不起任何作用。以前用于为流式 API 请求的连接、TLS 和响应标头阶段单独设置超时时间。请使用 `API_TIMEOUT_MS` 设置每个请求的超时时间。关于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，现在不起任何作用。以前用于为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时时间。请使用 `API_TIMEOUT_MS` 设置每个请求的超时时间。关于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是一个文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志可同时完成这两项。默认为 `~/.claude/debug/<session-id>.txt` |240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志可同时完成这两项操作。默认为 `~/.claude/debug/<session-id>.txt` |

239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最低日志级别。取值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 可包含大量诊断信息（例如完整的状态栏命令输出），或提高到 `error` 以减少干扰信息 |241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最低日志级别。可选值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 可包含大量诊断信息，例如完整的状态栏命令输出；或提高到 `error` 以减少干扰 |

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 可禁用 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用，并且对于使用原生 1M 窗口的模型（例如 [Sonnet 5.5](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window) 和 Fable 模型），Claude Code 会将其上的会话限制在 200K 窗口；关于如何强制执行此限制，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。适用于有合规要求的企业环境。关于它在为无法识别的 `[1m]` 模型 ID 校正窗口方面的作用，请参阅[为网关或自定义模型 ID 校正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 可禁用 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context)支持。设置后，模型选择器中将不提供 1M 模型变体，并且 Claude Code 会将使用原生 1M 窗口的模型（例如 [Sonnet 5.5](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window) 和 Fable 模型）上的会话限制为 200K 窗口；有关如何强制执行此限制，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。适用于有合规要求的企业环境。关于它在为无法识别的 `[1m]` 模型 ID 修正窗口方面的作用，请参阅[为网关或自定义模型 ID 修正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 可在 Opus 4.6 和 Sonnet 4.6 上禁用[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)，并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对 [Fable 模型](/docs/zh-CN/model-config#extended-thinking)、Sonnet 5 及更高版本或 Opus 4.7 及更高版本没有影响，这些模型始终使用自适应推理 |243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 可在 Opus 4.6 和 Sonnet 4.6 上禁用[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)，并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对 [Fable 模型](/docs/zh-CN/model-config#extended-thinking)、Sonnet 5 及更高版本、Haiku 5.5 或 Opus 4.7 及更高版本无效，这些模型始终使用自适应推理 |

242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 可阻止 Claude Code 跨管理员来源按键合并[托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的 `env` 块，这样只会应用最高优先级来源的整个 `env` 块，与 v2.1.223 之前的行为相同。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置的 `env` 块下发的副本。需要 Claude Code v2.1.223 或更高版本 |244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 可阻止 Claude Code 跨管理员来源按键合并[托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的 `env` 块，从而像 v2.1.223 之前那样，只应用优先级最高的来源的整个 `env` 块。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.223 或更高版本 |

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 可禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令将不可用，任何已配置的 `advisorModel` 都会被忽略，`--advisor` 标志会被接受但不起作用，因此传递该标志的现有脚本可继续正常运行而不会报错 |245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 可禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令将不可用，任何已配置的 `advisorModel` 都会被忽略，`--advisor` 标志仍被接受但不起作用，因此传递该标志的现有脚本可以继续运行而不会出错 |

244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 可关闭[后台 Agent 和 Agent 视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 以及按需启动的监管进程。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 可关闭[后台 Agent 和 Agent 视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 以及按需 supervisor。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |

245| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 可禁用[全屏渲染](/docs/zh-CN/fullscreen)并使用经典的主屏幕渲染器。对话会保留在终端的原生回滚缓冲区中，因此 `Cmd+f` 和 tmux 复制模式可照常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-CN/settings-reference#tui) 设置。您也可以使用 `/tui default` 进行切换。不适用于从 [Agent 视图](/docs/zh-CN/agent-view)打开的后台会话，这些会话始终使用全屏渲染 |247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 可禁用[全屏渲染](/docs/zh-CN/fullscreen)并使用经典的主屏幕渲染器。对话保留在终端的原生回滚缓冲区中，因此 `Cmd+f` 和 tmux 复制模式照常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-CN/settings-reference#tui) 设置。您也可以使用 `/tui default` 切换。不适用于从 [Agent 视图](/docs/zh-CN/agent-view)打开的后台会话，这些会话始终使用全屏渲染 |

246| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 可关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具会将会话输出作为私有网页发布到 claude.ai 上。设置后，任何设置文件都无法重新启用该工具。如要改为通过设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 键也可将其关闭 |248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 可关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具会将会话输出作为私有网页发布到 claude.ai 上。一旦设置，任何设置文件都无法重新启用该工具。如果要改为通过设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 键也可将其关闭 |

248| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 设置为 `1` 可让 Claude Code 进程自行运行其 [`gcpAuthRefresh`](/docs/zh-CN/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-CN/settings-reference#awsauthrefresh) 命令，而不是在另一个进程运行该命令时等待。需要 Claude Code v2.1.286 或更高版本 |250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 设置为 `1` 可让 Claude Code 进程自行运行其 [`gcpAuthRefresh`](/docs/zh-CN/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-CN/settings-reference#awsauthrefresh) 命令，而不是在另一个进程运行该命令时等待。需要 Claude Code v2.1.286 或更高版本 |

249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 可禁用[自动记忆](/docs/zh-CN/memory#auto-memory)。设置为 `0` 可强制启用自动记忆，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 原本会禁用它。禁用后，Claude 不会创建或加载自动记忆文件 |251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 可禁用[自动记忆](/docs/zh-CN/memory#auto-memory)。设置为 `0` 可强制启用自动记忆，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 本会禁用它。禁用后，Claude 不会创建或加载自动记忆文件 |

250| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台运行以及 Ctrl+B 快捷键 |252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台化以及 Ctrl+B 快捷键 |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 会假定是网关从一个其他方面未经修改的响应中丢弃了该标头，因此它会解码响应体，流式传输得以继续工作。仅当网关还会将流重新以服务器发送事件的形式输出时才设置此项；此时 Claude Code 会将没有该标头的响应体作为服务器发送事件读取。需要 Claude Code v2.1.239 或更高版本 |253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假定是网关从原本未经修改的响应中丢弃了该标头，因此它会解码响应体，流式输出可继续正常工作。仅当网关还会将流重新以服务器发送事件形式发出时才设置此变量；届时 Claude Code 会改为将无标头的响应体读作服务器发送事件。需要 Claude Code v2.1.239 或更高版本 |

252| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否带有 `application/vnd.amazon.eventstream` content-type 的检查。没有此变量时，如果响应带有不同的 content-type，Claude Code 会使请求失败，并显示指明该类型的错误，这意味着[网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。请将网关配置为原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否带有 `application/vnd.amazon.eventstream` content-type 的检查。如果不设置此变量，当响应带有不同的 content-type 时，Claude Code 会使请求失败，并显示一条指出该类型的错误，这意味着[网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。请配置网关原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |

253| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 后，当[监管进程](/docs/zh-CN/agent-view#the-supervisor-process)停止、重启或更新[后台会话](/docs/zh-CN/agent-view)的进程时，会停止该会话正在运行的后台 shell 命令、动态工作流，以及（从 v2.1.198 开始）后台子代理，而不是将它们移交给该会话的下一个进程。仅影响此移交：使用 `←` 或 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，仍会延续进行中的工作，而 `CLAUDE_DISABLE_ADOPT` 会同时关闭这两者。需要 Claude Code v2.1.196 或更高版本 |255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 可在 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 停止、重启或更新[后台会话](/docs/zh-CN/agent-view)的进程时，停止该会话正在运行的后台 shell 命令、动态工作流以及（自 v2.1.198 起）后台子代理，而不是将它们移交给该会话的下一个进程。仅影响这一移交：使用 `←` 或 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，仍会延续正在进行的工作，而 `CLAUDE_DISABLE_ADOPT` 会同时关闭这两者。需要 Claude Code v2.1.196 或更高版本 |

254| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有轮次或子代理在运行时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上不起作用。需要 Claude Code v2.1.193 或更高版本 |256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有正在运行的轮次或子代理时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上无效。需要 Claude Code v2.1.193 或更高版本 |

255| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 随附的 [skill](/docs/zh-CN/skills) 和工作流：随附 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 将其隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 随附的 [skill](/docs/zh-CN/skills) 和工作流：随附的 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 将其隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |

256| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具，同时省略系统提示词中的 Chrome 部分以及 `/claude-in-chrome` [随附 skill](/docs/zh-CN/skills#bundled-skills)。适用于嵌入 Claude Code 并提供自有浏览器指导的宿主。需要 Claude Code v2.1.257 或更高版本 |258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具，同时省略系统提示词中的 Chrome 部分以及 `/claude-in-chrome` [随附 skill](/docs/zh-CN/skills#bundled-skills)。适用于嵌入 Claude Code 并提供自己的浏览器指导的宿主。需要 Claude Code v2.1.257 或更高版本 |

258| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[定时任务](/docs/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具将不可用，所有已安排的任务都会停止触发，包括在会话中途已在运行的任务 |260| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[定时任务](/docs/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具将不可用，任何已安排的任务都会停止触发，包括会话中途已在运行的任务 |

259| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 可关闭[关键路径删除](/docs/zh-CN/permission-modes#critical-paths)提示的时间限制。之后，在 `auto` 模式下，Claude Code 会将这些删除操作发送给分类器；在 `bypassPermissions` 模式下，提示会一直等待您的回答。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置的 `env` 块下发的副本。需要 Claude Code v2.1.281 或更高版本 |261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 可关闭[关键路径删除](/docs/zh-CN/permission-modes#critical-paths)提示的时间限制。这样，在 `auto` 模式下，Claude Code 会改为将这些删除操作发送给分类器，而在 `bypassPermissions` 模式下，提示会等待您的回答。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |

260| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中去除预发布的 `anthropic-beta` 请求标头、与之配对的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具架构字段。当代理网关因 `anthropic-beta` 标头报告 `Unexpected value(s)` 错误或报告 `Extra inputs are not permitted` 错误而拒绝请求时，请使用此变量。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)列出了此变量移除的内容（包括 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)）以及 Claude Code 仍会继续发送的内容 |262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中剥离预发布的 `anthropic-beta` 请求标头、与之配套的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具架构字段。当代理网关以 `anthropic-beta` 标头的 `Unexpected value(s)` 错误或 `Extra inputs are not permitted` 错误拒绝请求时，请使用此选项。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)列出了该变量移除的内容（包括 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)）以及 Claude Code 仍会发送的内容 |

261| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 会改用其搜索工具或通用子代理进行探索，[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。要在 Agent SDK 或非交互模式中移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 会改用其搜索工具或 general-purpose 子代理进行探索，[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。要在 Agent SDK 或非交互模式中移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |

263| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 可禁用“How is Claude doing?”会话质量调查。当设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新选择启用。要设置抽样率而不是完全禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。请参阅[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 可禁用 "How is Claude doing?" 会话质量调查。当设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新选择启用。要设置采样率而不是直接禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。请参阅[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |

264| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 可禁用文件[检查点功能](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 可禁用文件[检查点功能](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |

265| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 可从 Claude 的上下文中移除内置的提交和 PR 工作流说明以及 git 状态快照。在使用您自己的 git 工作流 skill 时很有用。设置后，优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 可从 Claude 的上下文中移除内置的提交和 PR 工作流指令以及 git 状态快照。在使用您自己的 git 工作流 skill 时很有用。设置后优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |

266| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 设置为 `1` 可阻止 Claude Code 读取通过 `-c` 传递给 shell 的脚本（例如 `bash -c 'rm -rf ~'`）来检查[关键路径](/docs/zh-CN/permission-modes#removals-inside-nested-commands-and-inline-scripts)删除。Claude Code 仍会检查这些脚本中 shell 变量和位置参数形式的目标，其他关键路径检查也会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置的 `env` 块下发的副本。需要 Claude Code v2.1.288 或更高版本 |268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 设置为 `1` 可阻止 Claude Code 读取通过 `-c` 传递给 shell 的脚本（例如 `bash -c 'rm -rf ~'`）来检查[关键路径](/docs/zh-CN/permission-modes#removals-inside-nested-commands-and-inline-scripts)删除操作。Claude Code 仍会检查这些脚本中的 shell 变量和位置参数目标，其他关键路径检查也会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.288 或更高版本 |

267| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 可阻止在 Anthropic API 上将 Opus 4.0 和 4.1 自动重新映射到当前 Opus 版本。在您有意固定使用较旧的模型时使用。该重新映射不会在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 可阻止在 Anthropic API 上将 Opus 4.0 和 4.1 自动重新映射到当前 Opus 版本。当您有意固定使用较旧的模型时使用。该重新映射不会在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |

268| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 设置为 `1` 后，当您的账户在会话中途失去对该会话模型的访问权限时，[Amazon Bedrock](/docs/zh-CN/amazon-bedrock#when-a-model-is-disabled-mid-session) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 不会切换到较旧的模型，被拒绝的请求会立即失败。您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)仍会在发生该拒绝时切换，[启动时模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)也仍会在启动时回退。需要 Claude Code v2.1.285 或更高版本 |270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 设置为 `1` 可阻止 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#when-a-model-is-disabled-mid-session) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 在您的账户于会话中途失去对会话模型的访问权限时切换到较旧的模型；被拒绝的请求将立即失败。您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)仍会在该拒绝发生时切换，[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)仍会在启动时回退。需要 Claude Code v2.1.285 或更高版本 |

269| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此设置可保留终端原生的选中即复制行为 |271| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项可保留终端原生的选中即复制行为 |

270| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用点击、拖动和悬停处理，同时保留鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 中正常工作，但不希望点击定位光标、展开工具输出或打开链接时，请使用此设置。同时设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用单击、拖动和悬停处理，同时保留鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内正常工作，但不希望单击来定位光标、展开工具输出或打开链接时，请使用此选项。两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |

271| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 可阻止 Claude Code 在 API 请求因连接级错误（例如连接重置或 TLS 握手错误）而失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置时或下次启动时加载轮换后的文件。需要 Claude Code v2.1.232 或更高版本 |273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 可阻止 Claude Code 在 API 请求因连接级错误（例如连接重置或 TLS 握手错误）失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置时或下次启动时加载轮换后的文件。需要 Claude Code v2.1.232 或更高版本 |

272| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（例如 `1`）可禁用非必要的网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status)检查，以及[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)检查等可用性检查。它还会停止[插件 `command` 来源的后台运行](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)，这些是本地命令而不是网络流量，但由于它们可能触发依赖安装，因此也会被停止。**将其设置为 `0` 或 `false` 仍会禁用此类流量**，这与大多数开关变量不同；要重新允许此类流量，请取消设置该变量。还会禁用功能标志获取，这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。官方插件市场自动安装不在此范围内；请使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 将其禁用。不影响[网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，后者有其自己的选择启用方式 |274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（例如 `1`）可禁用非必要的网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status)检查，以及[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)检查等可用性检查。它还会停止[插件 `command` 来源的后台运行](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)，这些是本地命令而非网络流量，但它们可能会触发依赖安装。**将其设置为 `0` 或 `false` 仍会禁用此流量**，这与大多数开关变量不同；需取消设置该变量才能再次允许。还会禁用功能标志获取，这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。官方插件市场的自动安装不在此范围内；请使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 禁用它。不影响[网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，后者有自己的选择启用机制 |

274| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 可让 `PushNotification` 工具在您正在终端中输入或终端处于焦点状态时仍然发送桌面通知。默认情况下，当该工具检测到最近的键盘活动或终端焦点时，会同时跳过桌面通知和[移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此服务器在检测到您处于活动状态时仍可抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 可在您正在终端中输入或终端处于焦点时，仍然发送 `PushNotification` 工具的桌面通知。默认情况下，当该工具检测到最近的键盘活动或终端焦点时，会同时跳过桌面通知和[移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此当服务器检测到您处于活动状态时，仍可抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |

275| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 可禁用官方插件市场的自动注册。Claude Code 会在即将注册该市场时读取此变量，通常是在机器首次交互式启动期间。如果此时已设置该变量，Claude Code 会永久跳过注册。之后取消设置该变量不会撤销此跳过。您可以随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 来注册该市场 |277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 可禁用官方插件市场的自动注册。Claude Code 在即将注册该市场时读取此变量，通常是在计算机首次交互式启动期间。如果此时设置了该变量，Claude Code 会永久跳过注册。之后取消设置该变量不会撤销此跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可注册该市场 |

276| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 后，在 Claude Code 将权限请求发送到 Agent SDK 的 `canUseTool` 回调的会话中（Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的），Claude Code 不会运行您[针对未回答权限请求的 `Notification` hook](/docs/zh-CN/hooks#notification)。在终端会话中不起作用。需要 Claude Code v2.1.233 或更高版本 |278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 可阻止 Claude Code 运行您的[针对未回答权限请求的 `Notification` hook](/docs/zh-CN/hooks#notification)，仅适用于 Claude Code 将这些请求发送到 Agent SDK 的 `canUseTool` 回调的会话，Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的。在终端会话中无效。需要 Claude Code v2.1.233 或更高版本 |

278| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 设置为 `1` 可关闭 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)的一项检查，该检查会拒绝在[系统路径](/docs/zh-CN/permission-modes#remove-item-in-powershell)（例如驱动器根目录或您的主目录）上使用 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase`。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.283 或更高版本 |280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 设置为 `1` 可关闭 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)的一项检查，该检查会拒绝对[系统路径](/docs/zh-CN/permission-modes#remove-item-in-powershell)（例如驱动器根目录或您的主目录）使用 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase`。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.283 或更高版本 |

279| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 设置为 `1` 可关闭[安全分类器标记请求时的自动模型切换](/docs/zh-CN/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置所控制的行为 |281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 设置为 `1` 可关闭[安全分类器标记请求时的自动模型切换](/docs/zh-CN/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置所控制的行为 |

280| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 设置为 `1` 可阻止 Claude Code 发送结构化输出的 `output_config.format` 字段以及与之配对的 `anthropic-beta` 值，适用于其上游会拒绝这些内容的 [LLM 网关](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。这会保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 所关闭的其他预发布功能。需要 Claude Code v2.1.288 或更高版本 |282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 设置为 `1` 可阻止 Claude Code 发送结构化输出的 `output_config.format` 字段以及与之配套的 `anthropic-beta` 值，适用于其上游会拒绝它们的 [LLM 网关](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。这会保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 所关闭的其他预发布功能。需要 Claude Code v2.1.288 或更高版本 |

281| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 设置为 `1` 可关闭对目标完全是命令替换输出的递归 `rm`（例如 `rm -rf "$(pwd)"`）的[关键路径](/docs/zh-CN/permission-modes#critical-paths)检查。其他关键路径检查会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置的 `env` 块下发的副本。需要 Claude Code v2.1.281 或更高版本 |283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 设置为 `1` 可关闭针对目标完全来自命令替换输出的递归 `rm`（例如 `rm -rf "$(pwd)"`）的[关键路径](/docs/zh-CN/permission-modes#critical-paths)检查。其他关键路径检查会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |

282| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 可禁用基于对话上下文的终端标题自动更新。这还会跳过用于[生成会话标题](/docs/zh-CN/sessions#name-your-sessions)的后台小型/快速模型请求 |284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 可禁用基于对话上下文的自动终端标题更新。这也会跳过用于[生成会话标题](/docs/zh-CN/sessions#name-your-sessions)的后台小型/快速模型请求 |

283| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 可从 API 请求中完全省略 `thinking` 参数。这是针对会拒绝该参数的代理和网关的兼容性选项。在默认进行思考的模型上，省略该参数意味着模型可能仍会思考。要在 Anthropic API 上明确禁用[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。这两个变量都无法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考，因为这些模型的思考无法关闭。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同样会省略该参数，因此这两个变量在那里的行为相同 |285| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 可从 API 请求中完全省略 `thinking` 参数。这是针对会拒绝该参数的代理和网关的兼容性选项。在默认进行思考的模型上，省略该参数意味着模型仍可能进行思考。要在 Anthropic API 上明确禁用[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。这两个变量都无法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上关闭思考，这些模型不支持关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同样会省略该参数，因此这两个变量在那里的行为相同 |

284| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 可在 Claude Code 无法识别模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）时跳过主动[自动压缩](/docs/zh-CN/costs#reduce-token-usage)。没有此变量时，Claude Code 会按照它为该 ID 假定的上下文窗口进行压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 则可以校正所假定的窗口；关于每个变量的适用场景，请参阅[为网关或自定义模型 ID 校正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更高版本 |286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 可在 Claude Code 无法识别模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）时跳过主动[自动压缩](/docs/zh-CN/costs#reduce-token-usage)。如果不设置此变量，Claude Code 会按照它为该 ID 假定的上下文窗口进行压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改为修正假定的窗口；有关各变量的适用情况，请参阅[为网关或自定义模型 ID 修正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更高版本 |

285| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用虚拟滚动，并渲染会话记录中的每条消息。如果在全屏模式下滚动时，本应显示消息的位置出现空白区域，请使用此设置 |287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用虚拟滚动，并渲染会话记录中的每条消息。如果在全屏模式下滚动时，应显示消息的位置出现空白区域，请使用此选项 |

286| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 设置为 `1` 可关闭 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 工具仍然可用。需要 Claude Code v2.1.285 或更高版本 |288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 设置为 `1` 可关闭 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 工具仍然可用。需要 Claude Code v2.1.285 或更高版本 |

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

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

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

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

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

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

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

294| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 可在发往 Anthropic 的非必要流量被阻止时，将“How is Claude doing?”会话质量调查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时适用，否则不起作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈策略优先于此变量 |296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 可在发往 Anthropic 的非必要流量被阻止时，将“How is Claude doing?”会话质量调查路由到您自己的 [OpenTelemetry collector](/docs/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的 collector。在此模式下不会向 Anthropic 发送任何调查数据。在设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时适用，否则不起作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈策略优先 |

295| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 Claude 生成时从 API 流式传输。关闭此功能时，较大的工具输入（例如较长的文件写入）只有在 Claude 生成完毕后才会到达，看起来可能像是卡住了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，按模型在所部署的容器支持时启用。设置为 `0` 可选择退出。通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 经由代理路由时，设置为 `1` 可强制启用。在 Microsoft Foundry 和[网关](/docs/zh-CN/llm-gateway)连接上默认关闭 |297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 Claude 生成时从 API 流式传输。关闭后，大型工具输入（例如长文件写入）只有在 Claude 生成完毕后才会到达，看起来可能像是卡住了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，在已部署容器支持的模型上按模型启用。设置为 `0` 可选择退出。通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 经由代理路由时，设置为 `1` 可强制启用。在 Microsoft Foundry 和[网关](/docs/zh-CN/llm-gateway)连接上默认关闭 |

296| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 当 `ANTHROPIC_BASE_URL` 指向与 Anthropic 兼容的网关（如 LiteLLM、Kong 或内部代理）时，设置为 `1` 可从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为否则由共享 API 密钥支持的网关会向每个用户显示该密钥可访问的所有模型。发现的模型仍会按会话接收到的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表进行过滤；请通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)下发该列表，因为[服务器托管下发在网关配置上不可用](/docs/zh-CN/server-managed-settings#platform-availability) |298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 当 `ANTHROPIC_BASE_URL` 指向与 Anthropic 兼容的网关（例如 LiteLLM、Kong 或内部代理）时，设置为 `1` 可从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为否则由共享 API 密钥支持的网关会向每个用户显示该密钥可访问的所有模型。发现的模型仍会按会话收到的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表进行筛选；请通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)下发该列表，因为[网关配置不支持服务器托管下发](/docs/zh-CN/server-managed-settings#platform-availability) |

298| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 可关闭提示词建议，即出现在输入框中的灰色预测内容。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，`/config` 中的 **Prompt suggestions** 开关写入的就是该设置。当您的账户接近或达到用量限制时，Claude Code 也会[暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 可在达到限制之前保持建议开启。需要 Claude Code v2.1.238 或更高版本。请参阅[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 可关闭提示词建议，即出现在输入框中的灰色预测内容。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，`/config` 中的 **Prompt suggestions** 开关写入的正是该设置。当您的账户接近或达到用量限制时，Claude Code 也会[暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 可使建议保持开启，直到达到限制。需要 Claude Code v2.1.238 或更高版本。请参阅[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |

299| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在[具有任务跟踪工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中提供哪些任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 可改用旧版 `TodoWrite` 工具。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |301| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在[具备任务跟踪工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中提供哪些任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 可改用旧版 `TodoWrite` 工具。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |

300| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 可启用用于指标和日志记录的 OpenTelemetry 数据收集。配置 OTel 导出器之前必须设置。请在您的 shell、用户设置或托管设置中设置。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage) |302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 可启用用于指标和日志记录的 OpenTelemetry 数据收集。在配置 OTel 导出器之前必须设置。可在 shell、用户设置或托管设置中设置。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage) |

301| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 可在所有模型上获得任务跟踪工具。如果不设置，Claude Code 默认仅在 [Task 工具可用性](/docs/zh-CN/tools-reference#task-tool-availability)下列出的模型上提供这些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍然决定使用 Task 工具还是 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 可在所有模型上获得任务跟踪工具。如果不设置，Claude Code 默认仅在 [Task 工具可用性](/docs/zh-CN/tools-reference#task-tool-availability)下列出的模型上提供这些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍用于选择 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |

304| `CLAUDE_CODE_EXTRA_BODY` | 要合并到每个 API 请求正文顶层的 JSON 对象。适用于传递 Claude Code 未直接公开的特定于提供商的参数。在 shell 中导出的值也适用于您通过 `claude agents` 或 `--bg` 派发的[后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话会忽略 shell 导出的值，而使用后台监督进程所继承的副本 |306| `CLAUDE_CODE_EXTRA_BODY` | 要合并到每个 API 请求正文顶层的 JSON 对象。适用于传递 Claude Code 未直接公开的提供商特定参数。在 shell 中导出的值也适用于您通过 `claude agents` 或 `--bg` 派发的[后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话会忽略 shell 导出的值，而使用后台监管进程所继承的副本 |

306| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 可强制持久化会话记录、提示词历史记录和 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内部启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话，或最初由 Claude Code 的 Bash 工具启动的后台启动器）导致真正的顶层会话被误判为嵌套会话时使用。从 v2.1.178 开始，Claude Code 会自动检测 tmux 的情况并忽略继承的标记，因此 tmux 不再需要此变量。在 v2.1.169 及更早版本中同样有效；在 v2.1.170 和 v2.1.171 中不起作用，因为这两个版本移除了它所覆盖的嵌套会话检测 |308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 可强制持久化会话记录、提示词历史并注册到 `claude agents`，即使该 `claude` 是从另一个 Claude Code 会话内部启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话，或最初由 Claude Code 的 Bash 工具启动的后台启动器）导致真正的顶层会话被误判为嵌套会话时使用。自 v2.1.178 起，Claude Code 会自动检测 tmux 的情况并忽略继承的标记，因此 tmux 不再需要此变量。在 v2.1.169 及更早版本中同样有效；在 v2.1.170 和 v2.1.171 中不起作用，因为这两个版本移除了它所覆盖的嵌套会话检测 |

307| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 当您的终端支持删除线但未被自动检测到时（例如通过 SSH 连接且未转发 `TERM_PROGRAM`），设置为 `1` 可强制对 Claude 回复中的 `~~text~~` 进行删除线渲染。否则，未检测到的终端会显示字面的 `~~` 标记，而不是将文本渲染为删除线。需要 Claude Code v2.1.186 或更高版本 |309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 可在终端支持但未被自动检测到时（例如通过 SSH 且未转发 `TERM_PROGRAM`），强制将 Claude 回复中的 `~~text~~` 渲染为删除线。如果不设置，未被检测到的终端会显示字面的 `~~` 标记，而不会将文本渲染为删除线。需要 Claude Code v2.1.186 或更高版本 |

308| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 当您的终端支持 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)但未被自动检测到时，设置为 `1` 可强制启用该功能。适用于 Emacs `eat` 等实现了 BSU/ESU 但不响应能力探测的模拟器。在 tmux 下不起作用。与切换到[全屏渲染](/docs/zh-CN/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此变量不会更改渲染器 |310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 可在终端支持但未被自动检测到时，强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。适用于 Emacs `eat` 等实现了 BSU/ESU 但不响应能力探测的终端模拟器。在 tmux 下不起作用。与切换到[全屏渲染](/docs/zh-CN/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此变量不会更改渲染器 |

309| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，该模式让 Claude 自行生成[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，默认仅在交互式会话中开启。设置为 `1` 可在 `claude -p` 和 Agent SDK 中也开启该模式，设置为 `0` 可在所有类型的会话中关闭该模式。无论 fork 模式是否开启，您都可以运行 `/subtask`。交互式会话中的默认开启需要 Claude Code v2.1.232 或更高版本；在更早的版本中，请将该变量设置为 `1` 以开启 fork 模式 |311| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，该模式允许 Claude 自行生成[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，默认仅在交互式会话中开启。设置为 `1` 可同时在 `claude -p` 和 Agent SDK 中开启，设置为 `0` 可在所有类型的会话中关闭。无论分叉模式是否开启，您都可以运行 `/subtask`。交互式会话中的默认开启需要 Claude Code v2.1.232 或更高版本；在更早的版本中，请将该变量设置为 `1` 以开启分叉模式 |

310| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 可在 `claude -p --output-format stream-json` 输出中发出[子代理](/docs/zh-CN/sub-agents)的文本和思考块，与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志的行为相同。当某个 harness 调用 `claude` 且无法自行传递该标志时使用此变量。该标志在使用 stream-json 输出的非交互模式之外会报错退出，而此变量在这些情况下会被忽略，因此在进程范围内设置时，嵌套调用仍可正常工作。需要 Claude Code v2.1.211 或更高版本 |312| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 可在 `claude -p --output-format stream-json` 输出中发出[子代理](/docs/zh-CN/sub-agents)的文本和思考块，行为与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志相同。当调用 `claude` 的框架无法自行传递该标志时，请使用此变量。该标志在非交互模式且使用 stream-json 输出之外会报错退出，而此变量在这些情况下会被忽略，因此在进程范围内设置它时，嵌套调用仍能正常工作。需要 Claude Code v2.1.211 或更高版本 |

311| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 设置为 `1` 可在自定义代理或第三方提供商（如 Amazon Bedrock 或 Claude Platform on AWS）上发送[网关提示标头](/docs/zh-CN/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`。设置为 `0` 可在所有连接上停止发送这些标头，包括直接连接到 Anthropic API 的情况，Claude Code 在该情况下默认会发送它们。需要 Claude Code v2.1.273 或更高版本 |313| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 设置为 `1` 可在自定义代理或第三方提供商（例如 Amazon Bedrock 或 Claude Platform on AWS）上发送[网关提示标头](/docs/zh-CN/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`。设置为 `0` 可在所有连接上停止发送这些标头，包括直接连接到 Anthropic API 的情况，Claude Code 默认会在此类连接上发送它们。需要 Claude Code v2.1.273 或更高版本 |

312| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 开启的[网关模型发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)请求的超时时间（毫秒）（默认值：`3000`）。当您的网关在启动时需要超过三秒才能响应 `/v1/models` 时，请调高此值。仅接受纯数字；`0`、负值和其他写法会保持默认值。需要 Claude Code v2.1.269 或更高版本 |314| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 开启的[网关模型发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)请求的超时时间（毫秒）（默认值：`3000`）。当您的网关在启动时需要超过三秒才能响应 `/v1/models` 时，请调高此值。仅接受纯数字；`0`、负值和其他写法将保留默认值。需要 Claude Code v2.1.269 或更高版本 |

313| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。当 Git Bash 已安装但不在您的 PATH 中时使用。如果该路径不存在，或文件名不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 会忽略该变量，像未设置时一样自动检测 Git Bash，并记录一条使用 `--debug` 时可见的警告。在 v2.1.219 之前，路径不存在时 Claude Code 会在启动时退出，并且会将任何现有文件用作 shell，而不检查它是否为 bash 或 sh。请参阅 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |315| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。当已安装 Git Bash 但其不在 PATH 中时使用。如果该路径不存在，或文件名不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 会忽略该变量并像未设置一样自动检测 Git Bash，同时记录一条可通过 `--debug` 查看的警告。在 v2.1.219 之前，路径不存在时 Claude Code 会在启动时退出，并且会将任何已存在的文件用作 shell，而不检查它是否为 bash 或 sh。请参阅 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |

314| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 可在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)时从结果中排除点文件。默认包含。不影响 `@` 文件自动补全、`ls`、Grep 或 Read |316| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 可在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)时从结果中排除点文件。默认包含。不影响 `@` 文件自动补全、`ls`、Grep 或 Read |

315| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 可使 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括被 gitignore 忽略的文件。不影响 `@` 文件自动补全，它有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |317| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 可使 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括被 gitignore 忽略的文件。不影响 `@` 文件自动补全，后者有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |

317| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以让活动目标等待多少分钟，超过后 Claude Code 会[请 Claude 检查它](/docs/zh-CN/goal#background-work-defers-evaluation)。默认值 `30`。设置 `0` 可关闭检查。请以纯数字给出整分钟数，最大为 `10080`，即一周。Claude Code 会将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |319| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以让活动目标等待多少分钟，之后 Claude Code 会[请 Claude 检查该目标](/docs/zh-CN/goal#background-work-defers-evaluation)。默认值 `30`。设置为 `0` 可关闭检查。请以纯数字给出整分钟数，最大为 `10080`，即一周。Claude Code 会将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |

318| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 设置为 `0` 可关闭对发送到 `api.anthropic.com` 的 Claude API、遥测和 [Artifact](/docs/zh-CN/artifacts) 发布请求体的 gzip 压缩。默认情况下，Claude Code 会在直接连接时压缩大型请求体，而在您通过代理发送请求、配置客户端证书或设置 `NODE_EXTRA_CA_CERTS` 时跳过压缩。如果 Claude Code 无法检测到的 [TLS 检查代理](/docs/zh-CN/network-config#ca-certificate-store)错误处理压缩请求，请使用 `0` |320| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 设置为 `0` 可关闭对发送到 `api.anthropic.com` 的 Claude API、遥测和 [Artifact](/docs/zh-CN/artifacts) 发布请求正文的 gzip 压缩。默认情况下，Claude Code 会在直接连接上压缩较大的请求正文，而在您通过代理发送请求、配置客户端证书或设置 `NODE_EXTRA_CA_CERTS` 时跳过压缩。如果 Claude Code 无法检测到的 [TLS 检查代理](/docs/zh-CN/network-config#ca-certificate-store)错误处理压缩请求，请使用 `0` |

321| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 可跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |323| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 可跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |

323| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒绝再生成子代理之前，一个会话中可以同时运行的[子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)数量（默认值：20）。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该变量可以调整上限，但不能禁用上限。需要 Claude Code v2.1.217 或更高版本 |325| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一个会话中可以同时运行多少个[子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)，超过后 Agent 工具将拒绝再生成新的子代理（默认值：20）。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该变量可以调整上限，但不能禁用上限。需要 Claude Code v2.1.217 或更高版本 |

324| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为当前模型假定的上下文窗口大小。从 v2.1.193 开始，其应用方式取决于 Claude Code 如何解析模型 ID；请参阅[为网关或自定义模型 ID 更正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。当通过 `ANTHROPIC_BASE_URL` 路由到某个模型，而该模型的上下文窗口与其名称对应的内置大小不匹配时，请使用此变量 |326| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为当前模型假定的上下文窗口大小。自 v2.1.193 起，其应用方式取决于 Claude Code 如何解析模型 ID；请参阅[为网关或自定义模型 ID 更正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。当通过 `ANTHROPIC_BASE_URL` 路由到某个模型，而其上下文窗口与该名称对应的内置大小不匹配时使用 |

325| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 发送给模型的每个 MCP 工具描述和每个 MCP 服务器指令的最大长度（字符数）（默认值：2048）。Claude Code 会[截断更长的文本](/docs/zh-CN/mcp#for-mcp-server-authors)。接受以纯数字表示的正整数。其他任何值都会被忽略并应用默认值。需要 Claude Code v2.1.280 或更高版本 |327| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 发送给模型的每个 MCP 工具描述和每个 MCP 服务器指令的最大长度（字符数）（默认值：2048）。Claude Code 会[截断更长的文本](/docs/zh-CN/mcp#for-mcp-server-authors)。接受以纯数字表示的正整数。其他任何值都会被忽略并应用默认值。需要 Claude Code v2.1.280 或更高版本 |

326| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数。默认值和上限因模型而异；请参阅[最大输出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。如果值超过模型的上限，Claude Code 会将其降至上限。对于 Claude Code 无法解析为已知模型的模型 ID，默认值为 32000，上限为 128000。增大此值会减少触发[自动压缩](/docs/zh-CN/costs#reduce-token-usage)之前可用的有效上下文窗口 |328| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数。默认值和上限因模型而异；请参阅[最大输出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 会将超过模型上限的值降至该上限。对于 Claude Code 无法解析为已知模型的模型 ID，默认值为 32000，上限为 128000。增大此值会减少触发[自动压缩](/docs/zh-CN/costs#reduce-token-usage)之前可用的有效上下文窗口 |

327| `CLAUDE_CODE_MAX_RETRIES` | 覆盖失败 API 请求的重试次数（默认值：10）。从 v2.1.186 开始上限为 15；从 v2.1.199 开始，`CLAUDE_CODE_RETRY_WATCHDOG` 会提高默认值并取消上限。对于需要在较长服务中断期间持续等待的无人值守会话，请改为设置 `CLAUDE_CODE_RETRY_WATCHDOG` |329| `CLAUDE_CODE_MAX_RETRIES` | 覆盖失败 API 请求的重试次数（默认值：10）。自 v2.1.186 起上限为 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 会提高默认值并移除上限。对于需要等待较长时间服务中断的无人值守会话，请改为设置 `CLAUDE_CODE_RETRY_WATCHDOG` |

328| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中移除，现在不起作用。此前用于限制 Claude 在一个会话中可通过 Agent 工具生成的[子代理](/docs/zh-CN/sub-agents)总数（默认值：200）；超过上限的生成会失败并显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit)和[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)仍然适用 |330| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已在 v2.1.224 中移除，现在不起作用。以前用于限制 Claude 在一个会话中可通过 Agent 工具生成的[子代理](/docs/zh-CN/sub-agents)总数（默认值：200）；超过上限时生成会失败并显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit)和[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)仍然适用 |

329| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话之下允许的[子代理层数](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) （默认值：3）。在默认值下，子代理可以生成自己的子代理，而位于第三层的子代理不能再继续生成；设置 `1` 可关闭嵌套。在 v2.1.217 至 v2.1.218 中，默认值为 1，因此除非您提高限制，否则子代理无法生成自己的子代理；v2.1.219 将默认值提高到 3。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该限制可以调整但不能移除。需要 Claude Code v2.1.217 或更高版本 |331| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话之下允许的[子代理层数](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)（默认值：3）。在默认值下，子代理可以生成自己的子代理，而位于第三层的子代理不能再继续生成；设置为 `1` 可关闭嵌套。在 v2.1.217 至 v2.1.218 中，默认值为 1，因此除非您提高限制，否则子代理无法生成自己的子代理；v2.1.219 将默认值提高到 3。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该限制可以调整但不能移除。需要 Claude Code v2.1.217 或更高版本 |

331| `CLAUDE_CODE_MAX_TURNS` | 在未传递显式限制时，限制 agentic 轮次的数量。等同于传递 [`--max-turns`](/docs/zh-CN/cli-reference#cli-flags)，两者同时设置时后者优先。非正整数的值会在启动时被拒绝并报错，而不是被视为无上限 |333| `CLAUDE_CODE_MAX_TURNS` | 在未传递显式限制时，限制 agentic 轮次的数量。等同于传递 [`--max-turns`](/docs/zh-CN/cli-reference#cli-flags)，两者都设置时该标志优先。不是正整数的值会在启动时被拒绝并报错，而不会被视为无上限 |

332| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一个会话可以发起的 [WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 调用总数上限（默认值：200）。当 Claude 达到上限时，后续的 WebSearch 调用会返回一条通知，告知它使用已收集的信息继续。接受没有上界的正整数。其他任何值都会被忽略并应用默认值，因此该上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |334| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一个会话可以进行的 [WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 调用总数上限（默认值：200）。当 Claude 达到上限时，后续的 WebSearch 调用会返回一条通知，告知它使用已收集的信息继续。接受没有上限的正整数。其他任何值都会被忽略并应用默认值，因此该上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |

334| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在运行的 MCP 工具调用[转为后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)之前经过的时间（毫秒）（默认值：120000，即 2 分钟）。设置为 `0` 可关闭自动转入后台。需要 Claude Code v2.1.212 或更高版本 |336| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在运行的 MCP 工具调用[转为后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)之前经过的时间（毫秒）（默认值：120000，即 2 分钟）。设置为 `0` 可关闭自动转入后台。需要 Claude Code v2.1.212 或更高版本 |

335| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非交互](/docs/zh-CN/headless)会话的第一轮等待仍在连接中的 MCP 服务器的时长（毫秒），用于替代默认的[第一轮等待](/docs/zh-CN/agent-sdk/mcp#connection-timing)。设置后，该等待涵盖所有待连接的服务器。设置为 `0` 可跳过等待。无论此值如何，[`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 服务器都保留其自身的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更高版本 |337| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非交互](/docs/zh-CN/headless)会话的第一个轮次等待仍在连接中的 MCP 服务器的时长（毫秒），用于替代默认的[首轮等待](/docs/zh-CN/agent-sdk/mcp#connection-timing)。设置后，等待将涵盖所有待连接的服务器。设置为 `0` 可跳过等待。无论取何值，[`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 服务器都会保留其自身的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更高版本 |

336| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内既没有发送响应也没有发送进度通知时，工具调用会报错中止，而不是等待整体的 `MCP_TOOL_TIMEOUT`。覆盖各传输方式的默认值：网络服务器为 300000（5 分钟），stdio 服务器为 1800000（30 分钟）。设置为 `0` 可禁用空闲检查。低于 1000 的值会被提高到一秒，且该值的上限为实际生效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少为 1000 的单服务器 `timeout` 会将该服务器的空闲窗口提高到至少为 `timeout` 的值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器不受空闲超时限制 |338| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这段时间内既未发送响应也未发送进度通知时，工具调用会中止并报错，而不是等待整体的 `MCP_TOOL_TIMEOUT`。覆盖各传输方式的默认值：网络服务器为 300000（5 分钟），stdio 服务器为 1800000（30 分钟）。设置为 `0` 可禁用空闲检查。低于 1000 的值会提高到一秒，且该值以生效的 `MCP_TOOL_TIMEOUT` 为上限。`.mcp.json` 中至少为 1000 的单服务器 `timeout` 会将该服务器的空闲窗口提高到至少为该 `timeout` 值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器不受空闲超时限制 |

337| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 会在绑定套接字时将该套接字的路径导出给 hook 和 Bash 命令。在启动时即开启消息功能的会话中，Claude Code 会在任何 hook 运行之前绑定套接字。计算机上的其他会话会将消息投递到此路径。每个会话导出自己的套接字，而不是从父会话继承的套接字，到达该套接字的消息会经过会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)。设置中的 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |339| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 在绑定套接字时会将该套接字的路径导出给 hook 和 Bash 命令。在启动时即开启消息功能的会话中，Claude Code 会在任何 hook 运行之前绑定套接字。机器上的其他会话会将消息投递到此路径。每个会话导出自己的套接字，而不是从父会话继承的套接字，到达该套接字的消息会经过该会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)。设置文件中的 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |

338| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 会将此会话专属令牌与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起导出给 hook 和 Bash 命令。向套接字发送内容的脚本可以将 `{"type":"auth","token":"<token>"}` 作为第一行发送，以证明它属于该会话。在原生 Windows 上，Claude Code 要求必须发送此行，并会关闭任何未以有效的此行开头的连接。[自有子进程规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)说明了 Claude Code 何时会查验该令牌。每个会话导出自己的令牌，绝不会使用从父会话继承的令牌。设置中的 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |340| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 会将此每会话令牌与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起导出给 hook 和 Bash 命令。向套接字发送消息的脚本可以将 `{"type":"auth","token":"<token>"}` 作为第一行发送，以证明它属于该会话。在原生 Windows 上，Claude Code 要求必须有这一行，并会关闭任何未以有效的此行开头的连接。[自有子进程规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)说明了 Claude Code 何时会查验该令牌。每个会话导出自己的令牌，绝不会继承父会话的令牌。设置文件中的 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |

340| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 可使 `/init` 运行交互式设置流程。该流程会先询问要生成哪些文件（包括 CLAUDE.md、skill 和 hook），然后再探索代码库并写入这些文件。如果不设置此变量，`/init` 会自动生成 CLAUDE.md 而不进行询问 |342| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 可使 `/init` 运行交互式设置流程。该流程会先询问要生成哪些文件（包括 CLAUDE.md、skill 和 hook），然后再探索代码库并写入这些文件。如果不设置此变量，`/init` 会自动生成 CLAUDE.md 而不进行询问 |

341| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 可通过第二个非阻塞文件描述符写入终端输出，这样停止读取的终端（例如暂停的 tmux 控制模式窗格或停滞的 SSH 连接）就不会在会话中途冻结 Claude Code。在 stdout 为终端时适用于 macOS、Linux 和 WSL。需要 Claude Code v2.1.261 或更高版本 |343| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 可通过第二个非阻塞文件描述符写入终端输出，这样停止读取的终端（例如已暂停的 tmux 控制模式窗格或停滞的 SSH 连接）就不会让 Claude Code 在会话中途冻结。在 stdout 为终端时适用于 macOS、Linux 和 WSL。需要 Claude Code v2.1.261 或更高版本 |

342| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](/docs/zh-CN/errors#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求在第一次超时时即失败。默认未设置，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制这些重新发送。有关超时时间，请参阅[调整重试行为](/docs/zh-CN/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |344| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](/docs/zh-CN/errors#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求会在首次超时时失败。默认未设置，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制这些重新发送。有关超时时间，请参阅[调整重试行为](/docs/zh-CN/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |

343| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 可启用[全屏渲染](/docs/zh-CN/fullscreen)，这是一项研究预览功能，可减少闪烁并在长对话中保持内存占用平稳。覆盖 [`tui`](/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 进行切换 |345| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 可启用[全屏渲染](/docs/zh-CN/fullscreen)，这是一项研究预览功能，可减少闪烁并在长对话中保持内存占用平稳。覆盖 [`tui`](/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 进行切换 |

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

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

346| `CLAUDE_CODE_OAUTH_TOKEN` | 用于 claude.ai 身份验证的 OAuth 访问令牌。在 SDK 和自动化环境中可替代 `/login`。优先于存储在钥匙串中的凭据。可使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成。除非您运行 [`/login`](/docs/zh-CN/authentication#authentication-precedence)，否则 Claude Code 会在整个会话中使用您设置的令牌。要替换过期的令牌，请生成新令牌并重新启动 |348| `CLAUDE_CODE_OAUTH_TOKEN` | 用于 claude.ai 身份验证的 OAuth 访问令牌。在 SDK 和自动化环境中可替代 `/login`。优先于钥匙串中存储的凭据。可使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成。除非您运行 [`/login`](/docs/zh-CN/authentication#authentication-precedence)，否则 Claude Code 会在整个会话中使用您设置的令牌。要替换已过期的令牌，请生成新令牌并重新启动 |

347| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，现在不起作用。此前用于将[快速模式](/docs/zh-CN/fast-mode)固定到 Claude Opus 4.6，而不是当前默认模型。Opus 4.6 不再支持快速模式 |349| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，现在不起作用。以前用于将[快速模式](/docs/zh-CN/fast-mode)固定到 Claude Opus 4.6，而不是当前的默认模型。Opus 4.6 不再支持快速模式 |

348| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承载内容的 OpenTelemetry 属性（模型响应、工具内容、系统提示词、原始 API 正文）的最大长度，包括截断标记，以 UTF-16 代码单元计（默认值：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才调高此值，或调低此值以减少遥测量。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage) |350| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承载内容的 OpenTelemetry 属性（模型响应、工具内容、系统提示词、原始 API 正文）的最大长度，包含截断标记，以 UTF-16 代码单元计（默认值：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才调高此值，或调低此值以减少遥测数据量。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage) |

349| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 可将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下，这些错误仅在使用 `--debug` 时显示，因此配置错误的导出器（例如 Prometheus 端口冲突）在其他情况下会静默失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage) |351| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 可将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下，这些错误仅在使用 `--debug` 时显示，因此配置错误的导出器（例如 Prometheus 端口冲突）否则会静默失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage) |

350| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry span 的超时时间（毫秒）（默认值：5000）。请参阅[监控](/docs/zh-CN/monitoring-usage) |352| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry span 的超时时间（毫秒）（默认值：5000）。请参阅[监控](/docs/zh-CN/monitoring-usage) |

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

352| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成工作的超时时间（毫秒）（默认值：2000）。如果退出时指标丢失，请调高此值。请参阅[监控](/docs/zh-CN/monitoring-usage) |354| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（毫秒）（默认值：2000）。如果退出时指标丢失，请增大此值。请参阅[监控](/docs/zh-CN/monitoring-usage) |

353| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 可让 Claude Code 在有新版本可用时在后台运行包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器仍只显示升级命令而不运行它。请参阅[自动更新](/docs/zh-CN/setup#auto-updates) |355| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 可让 Claude Code 在有新版本可用时于后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器仍会显示升级命令而不运行它。请参阅[自动更新](/docs/zh-CN/setup#auto-updates) |

354| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用 Perforce 感知的写保护。设置后，如果目标文件缺少所有者写入位（Perforce 会清除已同步文件的该位，直到 `p4 edit` 将其打开），Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示。这可以防止 Claude Code 绕过 Perforce 变更跟踪 |356| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 打开它们。这可以防止 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) |358| `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_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒）（默认值：120000）。对于大型仓库或较慢的网络连接，请调高此值。请参阅 [Git clone timed out](/docs/zh-CN/plugins/troubleshooting#git-clone-timed-out-after-120s) |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制当 [mod](/docs/zh-CN/plugins/mods/overview) 的文件发生变化时 Claude Code 是否重新加载该 mod。重新加载适用于您通过 `--plugin-dir` 从目录加载的 mod，在交互式会话中默认开启。设置为 `1` 可在非交互式会话中也开启，设置为 `0` 可在所有会话中关闭。需要 Claude Code v2.1.287 或更高版本。请参阅 [mod 设置和环境变量](/docs/zh-CN/plugins/mods/reference#settings-and-environment-variables) |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程或无法向远程进行身份验证时跳过重新克隆尝试，并继续使用现有的市场检出。适用于离线或隔离网络环境，在这些环境中重新克隆也会以同样的方式失败。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒）（默认值：120000）。对于大型仓库或较慢的网络连接，请增大此值。请参阅 [Git clone timed out](/docs/zh-CN/plugins/troubleshooting#git-clone-timed-out-after-120s) |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 简写来源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何未为 `github.com` 配置 SSH 密钥的环境 |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法连接到远程或无法通过远程身份验证时，跳过重新克隆尝试并继续使用现有的市场检出。适用于离线或隔离网络环境，在这些环境中重新克隆也会以同样的方式失败。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

360| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用它可将预先填充的插件目录打包到容器镜像中。Claude Code 会在启动时从这些目录注册市场，并使用预先缓存的插件而无需重新克隆。请参阅[为容器预先填充插件](/docs/zh-CN/plugins/org#seed-containers-and-ci) |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 简写源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何未为 `github.com` 配置 SSH 密钥的环境 |

361| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 可阻止 Claude Code 在为工具调用、hook 和状态栏命令启动 PowerShell 时传递 `-ExecutionPolicy Bypass`，转而遵循计算机的有效执行策略。默认情况下，Claude Code 会在进程作用域绕过执行策略，以便 `.ps1` 脚本和模块导入能在默认为 Restricted 的 Windows 安装上正常工作。无论此设置如何，进程作用域的绕过都不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |363| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。用于将预填充的插件目录打包到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而无需重新克隆。请参阅[为容器预填充插件](/docs/zh-CN/plugins/org#seed-containers-and-ci) |

362| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless#background-tasks-at-exit)下，最后一轮之后空闲等待后台工作（例如子代理和工作流）的上限（毫秒）。每当 Claude 用一轮来处理后台结果时，空闲等待都会重新计时。默认值：`600000`，即 10 分钟。当空闲等待达到上限时，Claude Code 会停止等待剩余的后台任务并退出。设置为 `0` 可无限期等待。此上限独立于适用于普通后台 shell 的五秒宽限期。需要 Claude Code v2.1.182 或更高版本 |364| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 可阻止 Claude Code 在为工具调用、hook 和状态栏命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，转而遵循机器的有效执行策略。默认情况下，Claude Code 会在进程作用域绕过执行策略，以便 `.ps1` 脚本和模块导入能在默认为 Restricted 的 Windows 安装上正常工作。无论此设置如何，进程作用域的绕过都不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |

363| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过以 argv 前缀形式给出的企业启动器（如 `/opt/corp/launcher`）来启动 Claude Code 从其自身二进制文件启动的进程，例如托管 [Agent 视图](/docs/zh-CN/agent-view)会话的后台服务。请在用户设置或[托管设置](/docs/zh-CN/managed-settings)的 `env` 块中设置，而不是作为 shell 导出，以便分离的后台服务能够继承它；项目设置和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，该设置需要 Claude Code v2.1.210 或更高版本；两者同时设置时，此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置自己的启动器。在 Windows 上会被忽略。有关值格式、启动器涵盖的范围以及启动器必须满足的约定，请参阅[在企业启动器后运行 Claude Code](/docs/zh-CN/corporate-launcher)。需要 Claude Code v2.1.208 或更高版本 |365| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless#background-tasks-at-exit)下，最后一个轮次之后空闲等待后台工作（例如子代理和工作流）的上限（毫秒）。每当 Claude 用一个轮次处理后台结果时，空闲等待都会重新计时。默认值：`600000`，即 10 分钟。当空闲等待达到上限时，Claude Code 会停止等待剩余的后台任务并退出。设置为 `0` 可无限期等待。此上限独立于适用于普通后台 shell 的五秒宽限期。需要 Claude Code v2.1.182 或更高版本 |

364| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置，用于选择 Claude Code 存储该会话的会话记录和自动记忆的 `projects/` 目录名称，以替代从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 会将它们存储在 `/srv/tenant-a/projects/work/` 下。未设置 `CLAUDE_CONFIG_DIR` 时，Claude Code 会忽略此变量，并且仅从您启动 `claude` 的环境中读取它，绝不会从[设置文件的 `env` 块](#in-settings-files)中读取。请参阅[自行命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |366| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过以 argv 前缀形式给出的企业启动器（例如 `/opt/corp/launcher`）启动 Claude Code 从其自身二进制文件启动的进程，例如托管 [agent view](/docs/zh-CN/agent-view) 会话的后台服务。请在用户设置或[托管设置](/docs/zh-CN/managed-settings)的 `env` 块中设置，而不是作为 shell 导出，以便分离的后台服务能够继承它；项目设置和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，该设置需要 Claude Code v2.1.210 或更高版本；两者都设置时此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置自己的启动器。在 Windows 上会被忽略。有关值格式、启动器涵盖的范围以及启动器必须满足的约定，请参阅[在企业启动器后运行 Claude Code](/docs/zh-CN/corporate-launcher)。需要 Claude Code v2.1.208 或更高版本 |

365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），为主对话选择[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：包括您的交互式、`-p` 和 SDK 轮次，以及与它们内联运行的辅助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |367| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置，用于选择 Claude Code 存储该会话的会话记录和自动记忆所用的 `projects/` 目录名称，以替代根据工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 会将它们存储在 `/srv/tenant-a/projects/work/` 下。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 会忽略此变量，并且只从您启动 `claude` 的环境中读取它，绝不会从[设置文件的 `env` 块](#in-settings-files)中读取。请参阅[自行命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |

366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 当 `ANTHROPIC_BASE_URL` 指向自定义代理时，设置为 `1` 可传播 W3C 追踪上下文。传播范围包括模型请求和 HTTP MCP 请求上的 `traceparent` 标头，以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅在直接连接到 Anthropic API 时才启用传播。在 v2.1.152 中添加。请参阅[追踪（beta）](/docs/zh-CN/monitoring-usage#traces-beta) |368| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），以选择主对话的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：包括您的交互式、`-p` 和 SDK 轮次，以及与它们内联运行的辅助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |

367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代其管理模型提供商路由的宿主平台设置。设置后，Claude Code 会忽略设置文件中的提供商选择、端点和身份验证变量，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，因此用户设置无法覆盖宿主的路由。Claude Code 还会忽略[托管设置](/docs/zh-CN/managed-settings)中的模型选择键，例如 `model`、`fallbackModel` 和 `modelOverrides`，无论它们由哪个托管来源下发，从而使宿主的模型配置优先于过时的托管模型固定设置。Claude Code 还会忽略托管 `env` 块中的模型选择变量，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列；托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非宿主提供了自己的允许列表。Claude Code 还会跳过它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry 等第三方提供商上原本会应用的自动遥测退出，因此遥测遵循标准的 `DISABLE_TELEMETRY` 退出方式。请参阅[按 API 提供商划分的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |369| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 当 `ANTHROPIC_BASE_URL` 指向自定义代理时，设置为 `1` 可传播 W3C 跟踪上下文。传播范围包括模型请求和 HTTP MCP 请求上的 `traceparent` 标头，以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅在直接连接到 Anthropic API 时启用传播。在 v2.1.152 中添加。请参阅[跟踪（beta）](/docs/zh-CN/monitoring-usage#traces-beta) |

368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 设置为 `1` 可允许代理执行 DNS 解析，而不是由调用方执行。适用于应由代理处理主机名解析的环境，需手动选择启用 |370| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代其管理模型提供商路由的宿主平台设置。设置后，Claude Code 会忽略设置文件中的提供商选择、端点和身份验证变量，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，因此用户设置无法覆盖宿主的路由。无论由哪个托管来源下发，Claude Code 还会忽略[托管设置](/docs/zh-CN/managed-settings)中的模型选择键，例如 `model`、`fallbackModel` 和 `modelOverrides`，因此宿主的模型配置优先于过时的托管模型固定设置。Claude Code 还会忽略托管 `env` 块中的模型选择变量，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列；托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非宿主提供了自己的允许列表。Claude Code 还会跳过其在第三方提供商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上原本会应用的自动遥测退出，因此遥测遵循标准的 `DISABLE_TELEMETRY` 退出方式。请参阅[按 API 提供商划分的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |

370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云端会话](/docs/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此变量可构造指回会话记录的链接。请参阅[将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |372| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为[云端会话](/docs/zh-CN/claude-code-on-the-web)运行时自动设置为 `true`。可从 hook 或设置脚本中读取此值，以检测是否处于云端会话中 |

371| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 可在受限模式下启动会话，等同于传递 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags)。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.248 或更高版本 |373| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云端会话](/docs/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值可构造指回会话记录的链接。请参阅[将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |

372| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 可在上一个会话于轮次中途结束时自动恢复。用于 SDK 模式，使模型无需 SDK 重新发送提示词即可继续。要关闭此功能，请取消设置该变量或将其设置为 `0`。关于 VS Code 聊天面板，请参阅[重新加载后继续对话](/docs/zh-CN/vs-code#continue-conversations-after-a-reload) |374| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 可在受限模式下启动会话，与传递 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 相同。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.248 或更高版本 |

373| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，若要在恢复时自动继续，其最后一条会话记录消息所允许的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示没有界限，但最后一个请求因 API 错误而失败的轮次只有在该错误发生不到六小时时才会恢复。正值会对所有轮次（包括这些轮次）设置界限；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此变量，以免针对旧会话记录重新启动时重新运行过时的提示词。当 Claude Code 重新启动一个崩溃的、从交互式会话继承了对话的 [Agent 视图](/docs/zh-CN/agent-view)会话时，它会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |375| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 可在上一个会话于轮次中途结束时自动恢复。用于 SDK 模式，使模型无需 SDK 重新发送提示词即可继续。要关闭此功能，请取消设置该变量或将其设置为 `0`。有关 VS Code 聊天面板，请参阅[重新加载后继续对话](/docs/zh-CN/vs-code#continue-conversations-after-a-reload) |

374| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 发送给 Claude 的继续消息，该消息用于 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续被中断的轮次（而非重新发送其提示词）时，或您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时。默认为 `Continue from where you left off.`。空字符串会使用默认值 |376| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，恢复时可自动继续所允许的最后一条会话记录消息的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示无界限，但最后一个请求因 API 错误而失败的轮次，仅在该错误发生不足六小时时才会恢复。正值会限制所有轮次，包括这类轮次；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此值，以免针对旧会话记录重启时重新运行过时的提示词。当 Claude Code 重启一个从交互式会话继承了对话的已崩溃 [agent view](/docs/zh-CN/agent-view) 会话时，它会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |

375| `CLAUDE_CODE_RETRY_WATCHDOG` | 适用于评估框架、CI 作业或远程工作程序等无人值守会话，设置为 `1`。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度已耗尽的 `429` 时，Claude Code 会立即失败，即使该错误来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，看门狗会无限期重试这些错误。关于快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。看门狗在两次尝试之间最多退避 5 分钟，或者当响应带有速率限制重置时间时一直等到限制重置，因此达到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本中，它还会将其他瞬态错误（例如服务器错误、超时和连接断开）的默认重试次数提高到 300，约相当于三小时的退避，并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时取消其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |377| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 在 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续中断的轮次（而不是重新发送其提示词）时，或在您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时，发送给 Claude 的继续消息。默认为 `Continue from where you left off.`。空字符串会使用默认值 |

376| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可以安全模式启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆都不会加载，用于对损坏的配置进行故障排除。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 以及策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |378| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于无人值守的会话（例如评估框架、CI 作业或远程工作进程），请设置为 `1`。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度耗尽的 `429` 时，Claude Code 会立即失败，即使该错误来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，看门狗会无限期重试这些错误。有关快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。看门狗在两次尝试之间最多退避 5 分钟，或者在响应带有速率限制重置时间时一直等到限制重置，因此达到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本中，它还会将其他暂时性错误（例如服务器错误、超时和连接中断）的默认重试次数提高到 300（大约三小时的退避时间），并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时移除其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |

377| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象，用于在设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时限制每个会话中特定脚本可被调用的次数。键是与命令文本匹配的子字符串；值是整数形式的调用次数限制。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此像 `./scripts/deploy.sh $(evil)` 这样的 shell 扩展技巧仍会计入上限。通过 `xargs` 或 `find -exec` 进行的运行时扇出不会被检测到；这是一项纵深防御控制 |379| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可在安全模式下启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆均不会加载，用于排除损坏配置的故障。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 和策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |

378| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受最大为 20 的任意正值，包括小于 1 的小数值（例如 `0.5`），以便在已经放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每一格只发送一个滚轮事件且不进行放大，请设置为 `3` 以与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在该终端中使用自己的滚动处理 |380| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象，用于在设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时限制特定脚本在每个会话中可被调用的次数。键是与命令文本进行匹配的子字符串；值是整数调用次数限制。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此像 `./scripts/deploy.sh $(evil)` 这样的 shell 展开技巧仍会计入上限。无法检测通过 `xargs` 或 `find -exec` 进行的运行时扇出；这是一项纵深防御控制 |

379| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 可为会话关闭 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 可在您的账户已有访问权限的情况下开启该功能；该变量本身无法授予访问权限，其他关闭反馈的开关（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |381| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受不超过 20 的任何正值，包括小于 1 的小数值（例如 `0.5`），以便在已放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每格发送一个滚轮事件且不做放大，设置为 `3` 可与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在其中使用自己的滚动处理 |

382| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 可为会话关闭 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 可在您的账户已有访问权限的情况下开启它；该变量本身无法授予访问权限，其他关闭反馈的开关（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |

380| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) hook 的时间预算（毫秒）。该值也是每个未设置自身 `timeout` 的 hook 的超时时间。适用于会话退出、`/clear` 以及通过交互式 `/resume` 切换会话。默认预算为 1.5 秒，会自动提高到设置文件中配置的最高单个 hook `timeout`，最多 60 秒。插件提供的 hook 上的超时时间不会提高预算 |383| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) hook 的时间预算（毫秒）。该值也是每个未设置自身 `timeout` 的 hook 的超时时间。适用于会话退出、`/clear` 以及通过交互式 `/resume` 切换会话。默认预算为 1.5 秒，会自动提高到设置文件中配置的最高单个 hook `timeout`，最多 60 秒。插件提供的 hook 上的超时时间不会提高预算 |

381| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks)子进程以及 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和 hook，它与 hook JSON 输入中的 `session_id` 字段一致，并会在 `/clear` 时更新。MCP 服务器子进程会保留其启动时的 ID。使用 `--resume <session-id>` 时，它会收到恢复后的 ID，与 hook 和 Bash 一致。使用 `--continue` 或不带显式 ID 的 `--resume` 时，它可能会收到初始启动时的 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话关联起来 |384| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks)子进程以及 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和 hook，它与 hook JSON 输入中的 `session_id` 字段一致，并在 `/clear` 时更新。MCP 服务器子进程保留其生成时的 ID。使用 `--resume <session-id>` 时，它会收到恢复的 ID，与 hook 和 Bash 一致。使用 `--continue` 或不带显式 ID 的 `--resume` 时，它可能会收到初始启动 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话关联起来 |

382| `CLAUDE_CODE_SHELL` | 设置 Claude Code 运行 Bash 工具命令所用的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shell。如果该值不是可用的 `bash` 或 `zsh` 路径，Claude Code 会忽略它并回退到自动检测。自动检测会在您的 `$SHELL` 指向 `bash` 或 `zsh` 时使用它，否则会在您的 `PATH` 和标准安装位置中先查找可用的 `zsh`，再查找 `bash`，并选择找到的第一个 |385| `CLAUDE_CODE_SHELL` | 设置 Claude Code 运行 Bash 工具命令所使用的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shell。如果该值不是可用的 `bash` 或 `zsh` 路径，Claude Code 会忽略它并回退到自动检测。自动检测在 `$SHELL` 指向 `bash` 或 `zsh` 时使用它，否则会在 `PATH` 和标准安装位置中先选择找到的第一个可用 `zsh`，然后是 `bash` |

383| `CLAUDE_CODE_SHELL_PREFIX` | 包装 Claude Code 所生成 shell 命令的命令前缀，适用于：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令以及 stdio [MCP 服务器](/docs/zh-CN/mcp)启动命令。PowerShell hook 和 exec 形式的 hook 运行时不带前缀。适用于日志记录或审计。设置为 `/path/to/logger.sh` 这样的裸可执行文件路径时，每条命令会以 `/path/to/logger.sh '<command>'` 的形式运行。包装器会在 `$1` 中以单个经过 shell 引用的参数接收命令行，因此包装器必须用 shell 重新求值 `$1`，例如 `exec bash -c "$1"`。将 `$1` 当作裸可执行文件路径会导致传递 `npx -y <package>` 等参数的 stdio MCP 服务器出错。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用（包括环境设置），而不仅仅是 Claude 运行的命令 |386| `CLAUDE_CODE_SHELL_PREFIX` | 包装 Claude Code 生成的 shell 命令的命令前缀：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令以及 stdio [MCP 服务器](/docs/zh-CN/mcp)启动命令。PowerShell hook 和 exec 形式的 hook 运行时不带前缀。适用于日志记录或审计。设置一个单纯的可执行文件路径（例如 `/path/to/logger.sh`）会以 `/path/to/logger.sh '<command>'` 的形式运行每个命令。包装器在 `$1` 中以单个经 shell 引用的参数接收命令行，因此包装器必须用 shell 重新求值 `$1`，例如 `exec bash -c "$1"`。将 `$1` 视为单纯的可执行文件路径会导致传递 `npx -y <package>` 等参数的 stdio MCP 服务器出错。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用（包括环境设置），而不仅是 Claude 运行的命令 |

384| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 可使用最小系统提示词运行，并且仅提供 Bash、文件读取和文件编辑工具。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用对 hook、skill、自定义命令、子代理、已安装插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现。通过 `--add-dir` 传递的目录中的 skill 仍会加载。不会读取 OAuth 令牌和钥匙串凭据，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |387| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 可使用精简的系统提示词运行，并仅提供 Bash、文件读取和文件编辑工具。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用对 hook、skill、自定义命令、子代理、已安装插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现。通过 `--add-dir` 传入的目录中的 skill 仍会加载。不会读取 OAuth 令牌和钥匙串凭据，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |

385| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 可在任何模型上使用更短的系统提示词和简化的工具描述。设置为 `0`、`false`、`no` 或 `off` 可选择退出，即使在实验或服务器配置原本会启用它的模型上也是如此。完整的工具集、hook、MCP 服务器和 CLAUDE.md 发现仍保持启用 |388| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 可在任何模型上使用更短的系统提示词和简化的工具描述。设置为 `0`、`false`、`no` 或 `off` 可选择退出，即使在实验或服务器配置原本会启用它的模型上也是如此。完整的工具集、hook、MCP 服务器和 CLAUDE.md 发现仍保持启用 |

386| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 为 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 跳过客户端身份验证，适用于自行对请求进行签名的网关 |389| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 为 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 跳过客户端身份验证，适用于自行签署请求的网关 |

387| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 可关闭从 AWS 默认凭据提供程序链解析出的凭据的进程内缓存，使 Claude Code 在每次 API 请求时都解析该链。关闭缓存后，基于 SSO 的配置文件会在每次请求时向 IAM Identity Center 请求凭据。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |390| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 可关闭对从 AWS 默认凭据提供程序链解析出的凭据的进程内缓存，使 Claude Code 在每个 API 请求时都解析该链。关闭缓存后，基于 SSO 的配置文件会在每个请求时向 IAM Identity Center 请求凭据。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |

389| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 可将失败的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查视为可用，适用于阻止该检查直接请求 `api.anthropic.com` 的网络。Claude Code 仍会遵循“已被您的组织禁用”的响应 |392| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 可将失败的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查视为可用，适用于阻止该检查直接向 `api.anthropic.com` 发出请求的网络。Claude Code 仍会遵循“已被您的组织禁用”的响应 |

390| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 可跳过客户端的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查，适用于拦截该检查请求而不是拒绝它的代理。当您的组织禁用了快速模式时，API 仍会拒绝快速模式请求 |393| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 可跳过客户端的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查，适用于拦截而非拒绝该检查请求的代理。当您的组织禁用了快速模式时，API 仍会拒绝快速模式请求 |

391| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 为 Microsoft Foundry 跳过 Azure 身份验证，适用于会注入自己的 `Authorization` 标头的代理或网关。Claude Code 发送请求时不附带 Azure 凭据，并保留您提供的 `Authorization` 标头（例如通过 `ANTHROPIC_CUSTOM_HEADERS` 提供）。设置了 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时会被忽略。在 v2.1.203 之前，除非同时设置了 API 密钥，否则此变量会导致 Microsoft Foundry 客户端无法发送请求 |394| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 为 Microsoft Foundry 跳过 Azure 身份验证，适用于注入自己的 `Authorization` 标头的代理或网关。Claude Code 发送请求时不带 Azure 凭据，并保留您提供的 `Authorization` 标头（例如通过 `ANTHROPIC_CUSTOM_HEADERS` 提供）。设置了 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时会被忽略。在 v2.1.203 之前，除非同时设置了 API 密钥，否则此变量会导致 Microsoft Foundry 客户端无法发送请求 |

393| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 上的[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)会在此计算机上记住它们发现您的账户无法调用哪些模型，最长保留一天。设置为 `1` 可关闭这一记忆功能。需要 Claude Code v2.1.285 或更高版本 |396| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 上的[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)会在本机上记住它们发现您的账户无法调用的模型，最长保留一天。设置为 `1` 可关闭这一记忆功能。需要 Claude Code v2.1.285 或更高版本 |

394| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 可跳过将提示词历史记录和会话记录写入磁盘。设置此变量后启动的会话不会出现在 `--resume`、`--continue` 或上箭头历史记录中。适用于临时的脚本化会话 |397| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 可跳过将提示词历史和会话记录写入磁盘。设置此变量后启动的会话不会出现在 `--resume`、`--continue` 或上箭头历史中。适用于临时的脚本化会话 |

396| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 可让使用 `--output-format stream-json` 启动的会话，在原本仅以 stderr 输出结束的启动失败情况下，写入一条[说明 Claude Code 拒绝启动原因的结果消息](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更高版本 |399| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 可让使用 `--output-format stream-json` 启动的会话，在原本仅以 stderr 输出结束的启动失败情况下，写入一条[说明 Claude Code 拒绝启动原因的结果消息](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更高版本 |

397| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) hook 可连续阻止轮次结束的最大次数，超过后 Claude Code 会覆盖它并强制结束该轮次（默认值：8）。设置为 `0` 可禁用该上限。如果您的 hook 确实需要更多迭代才能完成，请调高此值 |400| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) hook 可连续阻止轮次结束的最大次数，超过后 Claude Code 会覆盖它并仍然结束该轮次（默认值：8）。设置为 `0` 可禁用此上限。如果您的 hook 确实需要更多次迭代才能完成，请提高此值 |

398| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友以及[工作流](/docs/zh-CN/workflows) Agent 在未通过其他方式分配模型时使用的默认模型。接受 `haiku` 等别名或完整模型名称。有两个来源优先于它：Claude 生成 Agent 时传递的模型，以及 Agent 定义中的 `model` 字段（包括 `inherit`）。要改变这一点，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。完整顺序请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)。将其设置为 `inherit` 与不设置相同。在 v2.1.251 之前，此变量会同时覆盖每次调用的模型和定义中的 `model` 字段 |401| `CLAUDE_CODE_SUBAGENT_MODEL` | 未通过其他方式指定模型的[子代理](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows) Agent 的默认模型。接受 `haiku` 等别名或完整模型名称。有两个来源优先于它：Claude 在生成 Agent 时传递的模型，以及 Agent 定义中的 `model` 字段（包括 `inherit`）。要改变这一点，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。完整顺序请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)。将其设置为 `inherit` 与不设置相同。在 v2.1.251 之前，此变量会同时覆盖每次调用的模型和定义中的 `model` 字段 |

399| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 可将同一个模型强制应用于子代理、队友和工作流 Agent。[在同一模型上运行所有子代理](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)说明了具体是哪个模型。需要 Claude Code v2.1.257 或更高版本 |402| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 可强制子代理、队友和工作流 Agent 使用同一个模型。[让所有子代理使用同一个模型](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)说明了具体使用哪个模型。需要 Claude Code v2.1.257 或更高版本 |

400| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），为主对话之外的请求选择[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，例如[子代理](/docs/zh-CN/sub-agents)、工作流和后台工作。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |403| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），以选择主对话之外的请求（例如[子代理](/docs/zh-CN/sub-agents)、工作流和后台工作）的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |

401| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 可从 Claude Code 启动的子进程（例如 Bash 命令、hook 和 stdio MCP 服务器）的环境中剥离凭据。清理会根据变量名或变量值识别凭据，并保留 GitHub 令牌和代理设置。请参阅[子进程环境清理会移除哪些内容](#what-the-subprocess-environment-scrub-removes)。配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此变量 |404| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 可从 Claude Code 启动的子进程（例如 Bash 命令、hook 和 stdio MCP 服务器）的环境中剥离凭据。清理会根据变量名或变量值识别凭据，并保留 GitHub 令牌和代理设置。请参阅[子进程环境清理会移除哪些内容](#what-the-subprocess-environment-scrub-removes)。配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此变量 |

402| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）下设置为 `1`，可在第一次查询之前等待插件安装完成。否则，插件会在后台安装，在第一轮中可能不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合使用可限制等待时间 |405| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）下设置为 `1`，可在第一个查询之前等待插件安装完成。否则，插件会在后台安装，可能在第一个轮次中不可用。可与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合使用以限制等待时间 |

403| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（毫秒）。超时后，Claude Code 会在没有插件的情况下继续并记录一条错误。没有默认值：不设置此变量时，同步安装会一直等待直到完成 |406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（毫秒）。超过后，Claude Code 会在没有插件的情况下继续运行并记录一条错误。没有默认值：如果不设置此变量，同步安装会一直等到完成 |

404| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 标志的非交互模式下设置为 `1`，可让 Claude Code 在该次运行中下载为您的 claude.ai 账户启用的 skill，并在运行第一次查询之前等待它们的列表，最长等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。下载本身会在后台完成，Claude 在调用某个 skill 时会等待该 skill 下载完成。需要 claude.ai 身份验证。使用 claude.ai 账户登录的终端会话无需此变量即可将这些 skill [下载](/docs/zh-CN/skills#where-synced-skills-load)到 `~/.claude/skills/synced/`，并大约每 10 分钟重新同步一次，因此仅当某次 `-p` 运行需要在第一次查询时就使用您最新的 skill 时才需设置此变量。在 v2.1.273 之前，终端会话仅在设置了此变量的 `-p` 运行中下载这些 skill。`synced` 文件夹名称[为此下载保留](/docs/zh-CN/skills#where-skills-live)。在 v2.1.227 之前，skill 会直接下载到 `~/.claude/skills/`。Claude Code 会对[下载的 skill 应用额外规则](/docs/zh-CN/skills#how-synced-skills-behave)，例如不在您的计算机上运行其 `!` 命令 |407| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 标志的非交互模式下设置为 `1`，可使 Claude Code 在该次运行中下载为您的 claude.ai 账户启用的 skill，并在运行第一次查询之前等待其列表，最长等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身份验证。使用 claude.ai 账户登录的终端会话无需此变量即可[同步这些 skill](/docs/zh-CN/skills#where-synced-skills-load)，因此仅当 `-p` 运行需要在第一次查询时使用您当前的 skill 时才设置它 |

405| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当基于 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 构建的应用重新加载 skill 时，在会话中途运行的 skill 重新同步的超时时间（毫秒）（默认值：30000）。超时后，重新加载会使用已到达的 skill 继续，其余下载在后台完成 |408| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当基于 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 构建的应用重新加载 skill 时，会话中途运行的 skill 重新同步的超时时间（毫秒）（默认值：30000）。超过后，重新加载会使用已到达的 skill 继续，剩余的下载在后台完成 |

406| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 设置了 `CLAUDE_CODE_SYNC_SKILLS` 时，第一次查询等待初始 skill 列表的超时时间（毫秒）（默认值：5000）。超时后，第一次查询会使用已到达的 skill 运行。无论哪种情况，下载都会在后台完成，Claude 在调用某个 skill 时会等待该 skill 下载完成 |409| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 设置了 `CLAUDE_CODE_SYNC_SKILLS` 时，第一个查询等待初始 skill 列表的超时时间（毫秒）（默认值：5000）。超过后，第一个查询会使用已到达的 skill 运行。无论哪种情况，下载都会在后台完成，Claude 在调用某个 skill 时会等待该 skill 下载完成 |

407| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 可禁用 diff 输出中的语法高亮。当颜色干扰您的终端设置时很有用。要同时禁用代码块和文件预览中的高亮，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |410| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 可在 diff 输出中禁用语法高亮。当颜色干扰您的终端设置时很有用。要同时在代码块和文件预览中禁用高亮，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |

408| `CLAUDE_CODE_TASK_LIST_ID` | 在会话之间共享任务列表。在[具有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，在多个 Claude Code 实例中设置相同的 ID，即可在共享任务列表上协作。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |411| `CLAUDE_CODE_TASK_LIST_ID` | 在会话之间共享任务列表。在[具备 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，在多个 Claude Code 实例中设置相同的 ID，即可在共享任务列表上协作。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |

409| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒为单位，覆盖非交互式会话在退出时等待其 [agent team](/docs/zh-CN/agent-teams) 完成拆除的时长。接受 1000 至 60000；超出范围的值会被忽略并应用默认值 10000。需要 Claude Code v2.1.206 或更高版本 |412| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆盖非交互式会话在退出时等待其 [agent team](/docs/zh-CN/agent-teams) 完成拆除的时长（毫秒）。接受 1000 到 60000；超出范围的值会被忽略并应用默认值 10000。需要 Claude Code v2.1.206 或更高版本 |

410| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上会在此路径后追加 `/claude-{uid}/`，在 Windows 上追加 `/claude/`。默认值：macOS 上为 `/tmp`，Linux 和 Windows 上为 `os.tmpdir()`。在 macOS 和 Linux 上，当您的覆盖值是较长路径时，[沙箱隔离](/docs/zh-CN/sandboxing)的 Bash 子进程会收到系统默认目录下一个较短的备用 `$TMPDIR`，因为某些工具在临时路径过长时会失败。未使用沙箱的 Bash 命令会在您的 shell 设置了 `$TMPDIR` 时继承它。在原生 Windows 上，当您的 shell 未设置 `$TMPDIR` 时，引用 `$TMPDIR` 的 Bash 命令会收到您的覆盖值，如果您未设置覆盖值则收到 `%TEMP%`。Claude Code 自身的临时文件始终使用您的覆盖值。请在您的 shell、用户设置或托管设置中设置。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |413| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上会将 `/claude-{uid}/` 附加到此路径，在 Windows 上附加 `/claude/`。默认值：macOS 上为 `/tmp`，Linux 和 Windows 上为 `os.tmpdir()`。在 macOS 和 Linux 上，当您的覆盖值是较长路径时，[沙箱化](/docs/zh-CN/sandboxing)的 Bash 子进程会在系统默认位置下收到一个较短的备用 `$TMPDIR`，因为某些工具在临时路径过长时会失败。未沙箱化的 Bash 命令会在您的 shell 设置了 `$TMPDIR` 时继承它。在原生 Windows 上，当您的 shell 未设置 `$TMPDIR` 时，引用 `$TMPDIR` 的 Bash 命令会收到您的覆盖值，如果您未设置覆盖值，则收到 `%TEMP%`。Claude Code 自身的临时文件始终使用您的覆盖值。可在 shell、用户设置或托管设置中设置。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

411| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任意非空值（例如 `1`）可在 tmux 中允许 24 位真彩色输出。**设置为 `0` 或 `false` 仍会允许真彩色**，这与大多数开关变量不同；取消设置该变量可恢复 256 色限制。默认情况下，当设置了 `$TMUX` 时，Claude Code 会限制为 256 色，因为除非经过配置，否则 tmux 不会透传真彩色转义序列。请在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 之后设置此变量。其他 tmux 设置请参阅[终端配置](/docs/zh-CN/terminal-config) |414| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任何非空值（例如 `1`）可允许在 tmux 中输出 24 位真彩色。**将其设置为 `0` 或 `false` 仍会允许真彩色**，这与大多数开/关变量不同；取消设置该变量可恢复 256 色限制。默认情况下，当设置了 `$TMUX` 时，Claude Code 会限制为 256 色，因为除非经过配置，否则 tmux 不会透传真彩色转义序列。请在将 `set -ga terminal-overrides ',*:Tc'` 添加到 `~/.tmux.conf` 之后设置此变量。有关其他 tmux 设置，请参阅[终端配置](/docs/zh-CN/terminal-config) |

412| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为以逗号分隔的进程类型列表，Claude Code 会将这些类型[排除在工具内存上限之外](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。设置 `none` 可对所有类型施加上限，或设置 `all-new` 仅对 Bash、PowerShell 和 Monitor 工具命令施加上限。无论您列出什么，Claude Code 都会让 Bash、PowerShell 和 Monitor 工具命令受该上限约束。需要 Claude Code v2.1.246 或更高版本 |415| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为以逗号分隔的进程类型列表，Claude Code 会将这些类型的进程[排除在工具内存上限之外](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。设置为 `none` 可对所有类型施加上限，设置为 `all-new` 则仅对 Bash、PowerShell 和 Monitor 工具命令施加上限。无论您列出什么，Claude Code 都会让 Bash、PowerShell 和 Monitor 工具命令受该上限约束。需要 Claude Code v2.1.246 或更高版本 |

413| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为 `4G` 等大小，可[限制 Bash 和 PowerShell 工具命令可使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更高版本中还包括 Monitor 工具命令。请以纯数字写入大小，单独的数字表示字节数，也可带 `K`、`M`、`G` 或 `T` 后缀。设置 `0` 或 `off` 可关闭上限。一旦 Claude Code 启动的第一个进程已开启或关闭上限，更改后的值将在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |416| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为 `4G` 等大小可[限制 Bash 和 PowerShell 工具命令可使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更高版本中还包括 Monitor 工具命令。请用纯数字书写大小，单独的数字表示字节数，也可以带 `K`、`M`、`G` 或 `T` 后缀。设置为 `0` 或 `off` 可关闭上限。一旦 Claude Code 启动的第一个进程开启或关闭了上限，更改后的值将在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |

414| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 设置为 `1` 可限制长时间运行的 `-p` 或 Agent SDK 会话的[会话记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的增长大小。每次压缩之后，一旦文件大于 5 MB，Claude Code 会移除该次压缩之前的历史记录。无论文件是否经过裁剪，恢复会话都会还原相同的对话。请在您启动 Claude Code 的环境中设置它，因为设置中的 `env` 块无法开启它。需要 Claude Code v2.1.287 或更高版本 |417| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 设置为 `1` 可限制长时间运行的 `-p` 或 Agent SDK 会话的[会话记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的增长大小。每次压缩后，一旦文件超过 5 MB，Claude Code 会删除该次压缩之前的历史记录。无论文件是否被裁剪，恢复会话都会还原相同的对话。请在启动 Claude Code 的环境中设置它，因为设置文件的 `env` 块无法开启它。需要 Claude Code v2.1.287 或更高版本 |

415| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消其转发给远程客户端（例如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 宿主）的对话框，或取消[被搁置的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的批准对话框之前的截止时间（毫秒）；权限提示和 `AskUserQuestion` 问题使用各自的流程，不受其控制。在 Claude Code v2.1.236 或更高版本中，它还会限制可能在无人值守状态下运行的会话中于会话中途出现的 [Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)和[非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions)介绍了完整的被搁置消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值会禁用截止时间 |418| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消转发给远程客户端（例如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 宿主）的对话框，或取消[被暂扣的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的批准对话框之前的截止时间（毫秒）；权限提示和 `AskUserQuestion` 问题使用各自的流程，不受其约束。在 Claude Code v2.1.236 或更高版本中，它还会在可能无人值守运行的会话中限制会话中途出现的 [Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)和[非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions)涵盖了完整的暂扣消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值会禁用截止时间 |

420| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 可使用 Node.js 文件 API 而不是 ripgrep 来发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此变量。不影响 Grep 或文件搜索工具 |423| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 可使用 Node.js 文件 API 而不是 ripgrep 来发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |

421| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安装 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 可禁用。在安装了 Git Bash 的 Windows 上，该工具对 claude.ai 和 Console 账户默认开启；设置为 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 会话中启用它，设置为 `0` 可关闭它。在 Linux、macOS 和 WSL 上，设置为 `1` 可启用它，这要求您的 `PATH` 中有 `pwsh`。在 Windows 上启用后，Claude 可以原生运行 PowerShell 命令，而不必经由 Git Bash 路由。请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |424| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安装 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 可将其禁用。在已安装 Git Bash 的 Windows 上，该工具对 claude.ai 和 Console 账户默认开启；在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 会话中，设置为 `1` 可将其启用，设置为 `0` 可将其关闭。在 Linux、macOS 和 WSL 上，设置为 `1` 可将其启用，这要求 `PATH` 中存在 `pwsh`。在 Windows 上启用后，Claude 可以原生运行 PowerShell 命令，而无需通过 Git Bash 中转。参见 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |

423| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置为 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 缓存每个已获取 URL 响应的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他写法都会保留默认值。Claude Code 每次启动时读取一次该值，因此在设置的 `env` 块中所做的更改会在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |426| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 将每个已获取 URL 的响应保留在缓存中的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他写法都会保留默认值。Claude Code 每次启动时只读取一次该值，因此在设置的 `env` 块中所做的更改会在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |

424| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载完成的时间上限（以毫秒为单位），包括其跟随的任何重定向。到时仍未完成的下载会以截止时间错误失败。默认值为 `300000`，即五分钟。设置为 `0` 可取消该限制。仅接受纯数字；小数或任何其他写法都会保留默认值。需要 Claude Code v2.1.268 或更高版本 |427| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载完成（包括其跟随的所有重定向）的最长时间上限，以毫秒为单位。到时仍未完成的下载会因截止时间错误而失败。默认值为 `300000`，即五分钟。设置为 `0` 可取消该限制。仅接受纯数字；小数或任何其他写法都会保留默认值。需要 Claude Code v2.1.268 或更高版本 |

425| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 当 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1` 时，Claude Code 每次提醒 Claude 检查仍在运行的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)之前等待的时长。接受一个或多个以逗号分隔的等待时间，以整秒为单位，范围从 `1` 到 `86400`，例如 `600` 或 `600,1800,3600`。每个值是距下一次提醒的等待时间，最后一个值会重复使用。仅接受纯数字；任何其他值或写法都视为未设置。未设置时不会发送提醒。需要 Claude Code v2.1.283 或更高版本 |428| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 当 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1` 时，Claude Code 在每次提醒 Claude 检查仍在运行的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)之前等待的时间。接受一个或多个以逗号分隔的等待时间，单位为整秒，范围为 `1` 到 `86400`，例如 `600` 或 `600,1800,3600`。每个值表示下一次提醒之前的等待时间，最后一个值会重复使用。仅接受纯数字；任何其他值或写法都视为未设置。未设置时不会发出提醒。需要 Claude Code v2.1.283 或更高版本 |

426| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 单次[工作流](/docs/zh-CN/workflows)运行同时执行的 Agent 数量，范围从 `1` 到 `256`。默认情况下，一次运行最多同时执行 16 个 Agent，当 Claude Code 可用的 CPU 较少时会更少；排队中的 `agent()` 调用会等待空闲槽位。每个正在运行的 Agent 的会话记录都保存在 Claude Code 的内存中，因此较高的值会增加内存使用量。仅接受纯数字；超出范围的值和其他写法会保留默认值。需要 Claude Code v2.1.269 或更高版本 |429| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 单次[工作流](/docs/zh-CN/workflows)运行同时执行的 Agent 数量，范围为 `1` 到 `256`。默认情况下，一次运行最多同时执行 16 个 Agent，当 Claude Code 可用的 CPU 较少时会更少；排队的 `agent()` 调用会等待空闲槽位。每个正在运行的 Agent 的会话记录都保留在 Claude Code 的内存中，因此较高的值会增加内存使用量。仅接受纯数字；超出范围的值和其他写法都会保留默认值。需要 Claude Code v2.1.269 或更高版本 |

427| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的时间上限（以毫秒为单位）。当扇出启动多个共享同一[提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会让除第一个 Agent 之外的所有 Agent 最多等待这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在未缓存的情况下处理它。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 从不等待。需要 Claude Code v2.1.229 或更高版本 |430| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的最长时间上限，以毫秒为单位。当一次扇出启动多个共享[提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会让除第一个 Agent 之外的所有 Agent 最多等待这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在无缓存的情况下处理该前缀。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 永远不会等待。需要 Claude Code v2.1.229 或更高版本 |

428| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。有关凭据，请参阅 [Claude Code 存储凭据的位置](/docs/zh-CN/authentication#credential-management)。适用于同时运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |431| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。关于凭据，请参见 [Claude Code 存储凭据的位置](/docs/zh-CN/authentication#credential-management)。适用于并行运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。请在 shell、用户设置或托管设置中设置它。在设置文件中，请填写[绝对路径](#in-settings-files)。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

429| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续。Claude Code 会在转入后台之前请您确认，然后停止原本会被延续的任务。需要 Claude Code v2.1.195 或更高版本 |432| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续下去。Claude Code 会在转入后台之前请您确认，然后停止原本会延续的任务。需要 Claude Code v2.1.195 或更高版本 |

430| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](/docs/zh-CN/hooks) 的 `effort.level` 字段一致。仅在当前模型支持 effort 参数时设置 |433| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](/docs/zh-CN/hooks) 的 `effort.level` 字段一致。仅当当前模型支持 effort 参数时才会设置 |

431| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 可强制启用字节级流式空闲看门狗，设置为 `0` 可强制禁用。`0` 还会在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，默认对直连 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的连接启用看门狗，也对通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](/docs/zh-CN/gateways)连接上的流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使保活 ping 仍在到达，事件级看门狗也可能在那里报告停滞。有关超时以及各计时器如何相互作用，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |434| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 可强制启用字节级流式空闲看门狗，设置为 `0` 可强制禁用。`0` 还会在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，该看门狗默认在直连 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的连接上启用，并在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](/docs/zh-CN/gateways)连接上对流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使仍有 keep-alive ping 到达，事件级看门狗也可能在这些连接上报告停滞。关于超时时间以及各计时器之间的相互作用，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

432| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲看门狗，这也会在 Bedrock 流式请求上启用[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间 |435| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲看门狗，这也会在 Bedrock 流式请求上启用[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间 |

433| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用。未设置时，看门狗默认对所有提供商开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；有关与其并行运行的其他停滞计时器，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |436| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用。未设置时，该看门狗对所有提供商默认开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上则为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；关于与其并行运行的其他停滞计时器，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

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

435| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个[后台会话](/docs/zh-CN/agent-view)中设置为该会话的 `~/.claude/jobs/<id>` 目录。该会话运行的 shell 命令会继承它。请将临时文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 在该目录中的 `Write` 和 `Edit` 调用不会请求权限，并且该目录会在会话被删除时移除 |438| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个[后台会话](/docs/zh-CN/agent-view)中设置为该会话的 `~/.claude/jobs/<id>` 目录。会话运行的 shell 命令会继承该变量。请将临时文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 在该目录中的 `Write` 和 `Edit` 调用不会提示请求权限，并且该目录会在会话被删除时一并移除 |

436| `CLAUDE_PID` | Claude Code 在其派生的子进程中将此变量设置为自身的进程 ID，这些子进程包括：Bash 和 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 集成使用它来拒绝会匹配 Claude Code 进程本身的 `pkill` 模式；请参阅[错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。可在您自己的脚本中读取它，以有意识地识别父 Claude Code 进程或向其发送信号。需要 Claude Code v2.1.214 或更高版本 |439| `CLAUDE_PID` | Claude Code 会在其派生的子进程（Bash 和 PowerShell 工具命令以及 hook 命令）中将此变量设置为自身的进程 ID。在 Linux 上，Bash 工具的 shell 集成会用它来拒绝会匹配到 Claude Code 进程自身的 `pkill` 模式；请参见[错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的脚本中读取它，以便有意地识别父 Claude Code 进程或向其发送信号。需要 Claude Code v2.1.214 或更高版本 |

437| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。`--remote-control-session-name-prefix` CLI 标志可为单次调用设置相同的值 |440| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您计算机的主机名，生成类似 `myhost-graceful-unicorn` 的名称。`--remote-control-session-name-prefix` CLI 标志可为单次调用设置相同的值 |

438| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上，流式请求第一个响应字节的截止时间（以毫秒为单位）。有关 Claude Code 如何限制该值、它为大型请求体增加的额外时间，以及未设置时如何选择截止时间，请参阅 [No response from API](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |441| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上，流式请求首个响应字节的截止时间，以毫秒为单位。关于 Claude Code 如何限制该值、为大型请求体额外增加的时间，以及在您未设置该变量时如何选择截止时间，请参见 [No response from API](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |

439| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲看门狗关闭停滞连接之前的超时时间（以毫秒为单位）。当您显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值会被静默提升至该最小值，以容纳扩展思考停顿和代理缓冲，并且字节级看门狗会将该值的上限设为 30 分钟。对于字节级看门狗，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量。有关各看门狗在未设置时的默认值，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |442| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲看门狗关闭停滞连接之前的超时时间，以毫秒为单位。当您显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值会被静默提升到该下限，以吸收扩展思考的停顿和代理缓冲，并且字节级看门狗会将该值上限设为 30 分钟。对于字节级看门狗，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量。关于每个看门狗在未设置时的默认值，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

440| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，现在不起任何作用。此前用于限制由[子代理](/docs/zh-CN/sub-agents)启动的[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)可运行的时长（以毫秒为单位），默认为 60 分钟。请参阅[后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |443| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，现在不起任何作用。以前用于限制由[子代理](/docs/zh-CN/sub-agents)启动的[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)可运行的时长，以毫秒为单位，默认值为 60 分钟。请参见[后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |

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

443| `DISABLE_AUTO_COMPACT` | 设置为 `1` 可禁用接近上下文限制时的自动压缩。手动 `/compact` 命令仍然可用。适用于希望明确控制何时进行压缩的情况。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |446| `DISABLE_AUTO_COMPACT` | 设置为 `1` 可禁用接近上下文限制时的自动压缩。手动 `/compact` 命令仍然可用。适用于您希望显式控制何时进行压缩的情况。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |

446| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 可隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 安装检查 skill 及其 `/checkup` 别名。适用于不应让用户在会话中运行安装诊断的托管部署。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量隐藏的是 `/doctor` 诊断屏幕命令 |449| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 可隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。适用于不希望用户在会话中运行设置诊断的托管部署。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量会隐藏 `/doctor` 诊断界面命令 |

449| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 可禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。还会禁用通过同一途径提交报告的 `/bug` 和 `/share`；在 v2.1.212 之前，它们是 `/feedback` 的别名，因此该命令在所有名称下都会被禁用。也接受旧名称 `DISABLE_BUG_COMMAND` |452| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 可禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。还会禁用 `/bug` 和 `/share`，它们通过相同的途径进行报告；在 v2.1.212 之前，它们是 `/feedback` 的别名，因此该命令在所有名称下都会被禁用。也接受旧名称 `DISABLE_BUG_COMMAND` |

450| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 可禁用 GrowthBook 功能标志获取，并对每个标志使用代码中的默认值。这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。设置为 `0` 或 `false` 会保持获取开启。除非同时设置了 `DISABLE_TELEMETRY`，否则遥测事件日志记录保持开启 |453| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 可禁用 GrowthBook 功能标志获取，并对每个标志使用代码中的默认值。这会导致 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。将其设置为 `0` 或 `false` 会保持获取开启。除非同时设置了 `DISABLE_TELEMETRY`，否则遥测事件日志记录仍保持开启 |

452| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 可隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时该命令已被隐藏 |455| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 可隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时已默认隐藏 |

453| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 可阻止发送 interleaved-thinking beta 标头。适用于您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情况 |456| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 可阻止发送 interleaved-thinking beta 标头。适用于您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情况 |

458| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 可为[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)禁用提示缓存，无论其在何处运行 |461| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 可为[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)禁用提示缓存，无论它在何处运行 |

461| `DISABLE_TELEMETRY` | 设置为任意非空值（例如 `1`）可选择退出遥测。**设置为 `0` 或 `false` 仍会选择退出**，这与大多数开关变量不同；取消设置该变量可重新启用遥测。遥测事件不包含代码、文件路径或 Bash 命令等用户数据。还会禁用[功能标志获取](#features-that-need-feature-flag-fetching)。请参阅[为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |464| `DISABLE_TELEMETRY` | 设置为任意非空值（例如 `1`）可选择退出遥测。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会选择退出**；取消设置该变量即可重新开启遥测。遥测事件不包含代码、文件路径或 Bash 命令等用户数据。还会禁用[功能标志获取](#features-that-need-feature-flag-fetching)。请参见[为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |

462| `DISABLE_UPDATES` | 设置为 `1` 可阻止所有更新，包括手动执行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。适用于通过您自己的渠道分发 Claude Code 且用户不应自行更新的情况 |465| `DISABLE_UPDATES` | 设置为 `1` 可阻止所有更新，包括手动执行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。适用于通过您自己的渠道分发 Claude Code 且用户不应自行更新的情况 |

464| `DO_NOT_TRACK` | 设置为 `1` 可选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启；Claude Code 遵循此变量，是因为它是许多开发者 CLI 都认可的跨工具约定 |467| `DO_NOT_TRACK` | 设置为 `1` 可选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启，并且会遵循这一被许多开发者 CLI 认可的跨工具约定 |

465| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，并将 `BETA_TRACING_ENDPOINT` 设置为您的 OTLP/HTTP 收集器端点，即可开启[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)，这会添加包含内容的 span 属性和 `claude_code.hook` span。交互式 CLI 会话还要求您的组织已列入该 beta 的允许列表。这两个变量在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中都会被忽略 |468| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，并将 `BETA_TRACING_ENDPOINT` 设置为您的 OTLP/HTTP 收集器端点，即可开启[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)，它会添加包含内容的 span 属性以及 `claude_code.hook` span。交互式 CLI 会话还要求您的组织已被列入该 beta 的允许列表。这两个变量在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中都会被忽略 |

466| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 可阻止 Claude Code 获取 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对已登录用户默认启用。若要按项目或按组织禁用，请改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |469| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 可阻止 Claude Code 获取 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对已登录用户默认启用。如需按项目或按组织禁用，请改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |

467| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 可请求 1 小时的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，而不是默认的 5 分钟。适用于 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 Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 用户。在所含用量范围内的订阅用户会在[主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)上自动获得 1 小时 TTL。正在使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的订阅用户可以设置此变量以保持 1 小时 TTL。1 小时缓存写入按更高费率计费。若要改为按请求类别选择 TTL，请使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |470| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 可请求 1 小时的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，而不是默认的 5 分钟。适用于 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 Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 用户。在包含用量范围内的订阅用户会在[主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)上自动获得 1 小时 TTL。使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的订阅用户可以设置此变量以保留 1 小时 TTL。1 小时缓存写入按更高费率计费。如需改为按请求类别选择 TTL，请使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |

469| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟加载所有 MCP 工具。但在早于 Claude 4.5 代的 Google Cloud's Agent Platform 模型上、在托管于 Azure 的 Microsoft Foundry 部署上，以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，仍会预先加载这些工具。`true` 始终延迟加载并发送 beta 标头，但上述 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支持 `tool_reference` 的代理上，请求会失败。`auto` 在工具定义所占空间不超过上下文的 10% 时预先加载。`auto:N` 设置自定义阈值，例如 `auto:5` 表示 5%。`false` 预先加载所有工具。设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 时，您自行设置的值会被忽略。在 v2.1.221 之前，除非您将此变量设置为 `true`，否则 Claude Code 会在 Google Cloud's Agent Platform 上为所有模型禁用工具搜索 |472| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟加载所有 MCP 工具。但在 Google Cloud's Agent Platform 上早于 Claude 4.5 代的模型、托管在 Azure 上的 Microsoft Foundry 部署，以及 `ANTHROPIC_BASE_URL` 指向非第一方主机时，它仍会预先加载这些工具。`true` 始终延迟加载并发送 beta 标头，但上述 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支持 `tool_reference` 的代理上，请求会失败。`auto` 在工具定义占上下文不超过 10% 时预先加载。`auto:N` 设置自定义阈值，例如 `auto:5` 表示 5%。`false` 预先加载所有工具。设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 时，您自行设置的值会被忽略。在 v2.1.221 之前，除非您将此变量设置为 `true`，否则 Claude Code 会为 Google Cloud's Agent Platform 上的所有模型禁用工具搜索 |

470| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任意非空值（例如 `1`），可使 Claude Code 在未配置备用模型时，对所有模型在遇到重复过载错误时停止重试。**设置为 `0` 或 `false` 仍会启用此行为**，这与大多数开关变量不同；取消设置该变量可恢复默认的重试行为。若不设置，当您使用 API 密钥或[第三方提供商](/docs/zh-CN/third-party-integrations)而非 Claude 订阅进行身份验证时，Claude Code 仅在其识别为 Opus、Fable 或 Mythos 的模型上以这种方式停止重试。在 Claude Code v2.1.160 或更高版本上，Claude Code 会在任何主模型遇到重复过载错误时切换到您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，因此此变量不影响切换到备用模型 |473| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任意非空值（例如 `1`）后，在未配置备用模型时，Claude Code 会对所有模型在反复出现过载错误时停止重试。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会启用此行为**；取消设置该变量即可恢复默认的重试行为。如果不设置，当您使用 API 密钥或[第三方提供商](/docs/zh-CN/third-party-integrations)而非 Claude 订阅进行身份验证时，Claude Code 仅会对其识别为 Opus、Fable 或 Mythos 的模型以这种方式停止重试。在 Claude Code v2.1.160 或更高版本中，任何主模型反复出现过载错误时，Claude Code 都会切换到您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，因此此变量不影响切换到备用模型 |

472| `FORCE_HYPERLINK` | 设置为 `1` 可在您的终端支持但未被自动检测到时启用可点击的 OSC 8 超链接，设置为 `0` 可禁用超链接。未设置时，Claude Code 仅在检测到终端支持时启用超链接。Claude Code 将此值解析为数字而非布尔值，因此 `false`、`no` 或 `off` 等值会启用超链接而不是禁用。即使 Claude Code 无法检测到终端支持（例如通过 SSH 时），页脚中的 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status)也会渲染为超链接。设置为 `0` 可将该徽章渲染为纯文本 |475| `FORCE_HYPERLINK` | 当您的终端支持可点击的 OSC 8 超链接但未被自动检测到时，设置为 `1` 可启用它们，设置为 `0` 可禁用它们。未设置时，Claude Code 仅在检测到终端支持时才启用超链接。Claude Code 将此值解析为数字而非布尔值，因此 `false`、`no` 或 `off` 等值会启用超链接，而不是禁用。即使 Claude Code 无法检测到终端支持（例如通过 SSH 连接时），页脚的 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status)也会渲染为超链接。设置为 `0` 可将徽章渲染为纯文本 |

473| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 可强制使用 5 分钟的提示缓存 TTL，即使原本会应用 1 小时 TTL。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |476| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 可强制使用 5 分钟的提示缓存 TTL，即使原本会应用 1 小时 TTL。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |

476| `IS_DEMO` | 设置为任意非空值（例如 `1`）可启用演示模式：在标题栏和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过新手引导。**设置为 `0` 或 `false` 仍会启用演示模式**，这与大多数开关变量不同；取消设置该变量可将其关闭。适用于直播或录制会话时 |479| `IS_DEMO` | 设置为任意非空值（例如 `1`）可启用演示模式：在标题栏和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过新手引导。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会启用演示模式**；取消设置该变量即可将其关闭。适用于直播或录制会话时 |

477| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：25000）。当输出超过 10,000 个 token 时，Claude Code 会显示警告。声明了 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具会改为对文本内容使用该字符限制，但这些工具返回的图像内容仍受此变量约束。对于没有该注解的工具，超过 50,000 个字符的成功文本结果无论此变量如何设置，都会被[保存到文件](/docs/zh-CN/mcp#mcp-output-limits-and-warnings) |480| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：25000）。当输出超过 10,000 个 token 时，Claude Code 会显示警告。声明了 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具会改为对文本内容使用该字符限制，但这些工具返回的图像内容仍受此变量约束。对于没有该注解的工具，超过 50,000 个字符的成功文本结果会被[保存到文件](/docs/zh-CN/mcp#mcp-output-limits-and-warnings)，与此变量无关 |

478| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 标志的非交互模式下，当模型响应未通过 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 验证时，Claude Code 允许的尝试次数；在达到该次数的失败尝试且没有有效输出后，运行失败。当[工作流](/docs/zh-CN/workflows)子代理的结构化输出未通过验证时，也适用相同的上限。默认为 5，即一次初始尝试加四次重试 |481| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 标志的非交互模式下，当模型响应未通过 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 校验时，Claude Code 允许的尝试次数；在达到该次数的失败尝试且没有有效输出后，运行将失败。当[工作流](/docs/zh-CN/workflows)子代理的结构化输出未通过校验时，同样适用此上限。默认值为 5，即一次首次尝试加四次重试 |

479| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 预算。Claude Code 将其上限设为比请求的最大输出 token 数少一个 token，且绝不低于 1,024。有关该限制的设置方式，请参阅 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未设置且已启用思考时，支持[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型会自行选择思考深度，其他模型则使用该上限。设置为 `0` 可在 Anthropic API 上禁用思考，但 Opus 5.5、Sonnet 5.5 和 Fable 模型除外，这些模型无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`0` 会改为省略 `thinking` 参数。在 Anthropic API 上关闭思考时，对于 Claude Code 已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 会发送 effort `high` 而不是更高的级别。对于正值，Claude Code 在自适应推理模型上会忽略该数字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 关闭了自适应推理 |482| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 预算。Claude Code 会将其上限设为比请求的最大输出 token 数少一个 token，且绝不低于 1,024。关于该限制的设置方式，请参见 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未设置且已启用思考时，支持[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型会自行选择思考深度，其他模型则使用该上限。设置为 `0` 可在 Anthropic API 上禁用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型除外，这些模型无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`0` 会改为省略 `thinking` 参数。在 Anthropic API 上关闭思考后，对于 Claude Code 已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 会发送 effort `high`，而不是更高的级别。对于正值，Claude Code 在自适应推理模型上会忽略数值本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 关闭了自适应推理 |

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

481| `MCP_CONNECTION_NONBLOCKING` | 控制启动时是否在第一次查询之前等待 MCP 服务器连接。MCP 启动默认为非阻塞：服务器在后台连接，其工具在连接完成后即可使用。设置为 `0` 可使 Claude Code 在第一次查询之前等待服务器连接。配置了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器无论如何仍会使启动等待，除非其由[发现缓存](/docs/zh-CN/mcp#server-status-detail)提供，因为构建第一个提示词时其工具必须已经存在。在不带 `--input-format stream-json` 的非交互模式（`-p`）下，无论此变量如何设置，Claude Code 也会在第一个轮次之前等待仍处于挂起状态的服务器。当您显式传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待的截止时间更长；有关已缓存服务器的例外情况，请参阅该标志的条目 |484| `MCP_CONNECTION_NONBLOCKING` | 控制启动时是否在第一次查询之前等待 MCP 服务器连接。MCP 启动默认是非阻塞的：服务器在后台连接，其工具在连接完成后即可使用。设置为 `0` 可让 Claude Code 在第一次查询之前等待服务器连接。配置了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器无论如何仍会让启动等待，除非它们由[发现缓存](/docs/zh-CN/mcp#server-status-detail)提供，因为构建第一个提示词时必须已存在它们的工具。在未使用 `--input-format stream-json` 的非交互模式（`-p`）下，无论此变量如何设置，Claude Code 也会在第一轮之前等待仍处于待定状态的服务器。当您显式传入 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待的截止时间更长；关于已缓存服务器的例外情况，请参见该标志的条目 |

482| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 启动在生成工具列表快照之前等待连接批次的时长（以毫秒为单位，默认：5000）。适用于 `MCP_CONNECTION_NONBLOCKING=0` 时，或标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器。截止时仍处于挂起状态的服务器会继续在后台连接。不同于 `MCP_TIMEOUT`，后者限制的是单个服务器的连接尝试 |485| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 启动在对工具列表进行快照之前等待连接批次的时长，以毫秒为单位（默认：5000）。在 `MCP_CONNECTION_NONBLOCKING=0` 时或对于标记了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器适用。到截止时间时仍处于待定状态的服务器会继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制的是单个服务器的连接尝试 |

483| `MCP_DISCOVERY_CACHE` | 开启或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。开启缓存后，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，Claude Code 会在其第一次工具调用时连接该服务器，而不是在启动时连接。缓存默认关闭，除非逐步推出已为您的账户启用了它。设置为 `1` 可将其开启，设置为 `0` 可在逐步推出已启用它的情况下仍保持关闭。在 v2.1.238 之前，缓存默认开启。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |486| `MCP_DISCOVERY_CACHE` | 开启或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。开启缓存后，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，并且 Claude Code 会在其第一次工具调用时而不是在启动时连接它。除非逐步推出已为您的账户启用该缓存，否则缓存默认关闭。设置为 `1` 可将其开启，设置为 `0` 可在推出已启用的情况下仍保持关闭。在 v2.1.238 之前，缓存默认开启。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |

484| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的最长存留时间（以秒为单位）（默认：14400，即 4 小时）。在某次启动时，如果条目的存留时间超过该值，Claude Code 会将其丢弃并在启动时连接服务器，与关闭缓存时的行为相同。Claude Code 将该值的上限设为 7 天。在 v2.1.238 之前，默认值为 86400，即 24 小时，且 Claude Code 不限制该值 |487| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的最长存在时间，以秒为单位（默认：14400，即 4 小时）。在启动时，如果条目早于此时长，Claude Code 会丢弃它并在启动时连接该服务器，与关闭缓存时的行为相同。Claude Code 将该值上限设为 7 天。在 v2.1.238 之前，默认值为 86400，即 24 小时，并且 Claude Code 不限制该值 |

485| `MCP_DISCOVERY_CACHE_STRIKES` | 在某次启动时，如果[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的存留时间超过 `MCP_DISCOVERY_CACHE_TTL_S`，Claude Code 会在后台刷新它。此变量设置在 Claude Code 丢弃该条目并改为在下次启动时连接服务器之前，允许连续失败的刷新次数（默认：1）。如果您的网络连接偶尔中断，可以调高此值，以免一次刷新失败就丢弃该条目。需要 Claude Code v2.1.238 或更高版本 |488| `MCP_DISCOVERY_CACHE_STRIKES` | 在启动时，如果某个[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目早于 `MCP_DISCOVERY_CACHE_TTL_S`，Claude Code 会在后台刷新它。此变量设置连续多少次刷新失败后，Claude Code 会丢弃该条目并改为在下次启动时连接该服务器（默认：1）。如果您的网络连接偶尔中断，请调高此值，以免一次刷新失败就丢弃条目。需要 Claude Code v2.1.238 或更高版本 |

486| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目而不刷新它的秒数（默认：900）。在某次启动时，如果条目的存留时间超过该值，Claude Code 仍会使用它，但会在后台刷新。一旦条目的存留时间超过 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 会改为将其丢弃。Claude Code 将该值的上限设为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，默认为 4 小时。在 v2.1.238 之前，Claude Code 不限制该值 |489| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 在不刷新的情况下使用[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的秒数（默认：900）。在启动时，如果条目早于此时长，Claude Code 仍会使用它，但会在后台刷新。一旦条目早于 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 会改为丢弃它。Claude Code 将该值上限设为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，默认为 4 小时。在 v2.1.238 之前，Claude Code 不限制该值 |

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

488| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)上有效，控制 Claude Code 是否探测服务器对 MCP 协议修订版 2026-07-28 的支持。设置为 `auto` 可探测 HTTP、claude.ai 连接器和 stdio 服务器，设置为 `legacy` 则不探测任何服务器。未设置该变量时，Claude Code 会探测 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)中所述的服务器。任何其他值都会被忽略，并在调试日志中写入警告。需要 Claude Code v2.1.221 或更高版本 |491| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)上，控制 Claude Code 是否探测服务器是否支持 MCP 协议修订版 2026-07-28。设置为 `auto` 可探测 HTTP、claude.ai 连接器和 stdio 服务器，设置为 `legacy` 则不探测任何服务器。未设置该变量时，Claude Code 会探测 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)中所述的服务器。任何其他值都会被忽略，并在调试日志中记录警告。需要 Claude Code v2.1.221 或更高版本 |

490| `MCP_SDK_GENERATION` | 固定此进程用于连接 MCP 服务器的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1`，基于 MCP TypeScript SDK 1.x 构建；或 `v2`，基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 构建。未设置该变量时，Claude Code 从该部分所列的版本开始使用 v2。在 Claude Code v2.1.221 或更高版本上，v2 运行时会检查 MCP OAuth 服务器在其授权响应中返回的颁发者，如果不匹配，登录会失败，并显示以 `Issuer mismatch in authorization response` 开头的错误。v1 运行时不执行此检查。如果您设置了无法识别的值，Claude Code 会忽略它并向调试日志写入警告。Claude Code 每个进程只读取一次该值。需要 Claude Code v2.1.218 或更高版本 |493| `MCP_SDK_GENERATION` | 固定此进程连接 MCP 服务器时所使用的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1` 基于 MCP TypeScript SDK 1.x 构建，`v2` 基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 构建。未设置该变量时，从该部分列出的版本开始，Claude Code 使用 v2。在 Claude Code v2.1.221 或更高版本中，v2 运行时会检查 MCP OAuth 服务器在其授权响应中返回的 issuer，如果不匹配，登录会失败并显示以 `Issuer mismatch in authorization response` 开头的错误。v1 运行时不执行此检查。如果您设置了无法识别的值，Claude Code 会忽略它并在调试日志中写入警告。Claude Code 每个进程只读取一次该值。需要 Claude Code v2.1.218 或更高版本 |

493| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（以毫秒为单位，默认：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求默认还会在 60 秒后超时；将此变量或单个服务器的 `timeout` 设置为高于 60000 的值，可提高该单请求限制。较低的值仍会缩短整体工具执行超时时间，但单请求限制保持为 60 秒。Stdio 和 WebSocket 服务器没有单请求计时器。`.mcp.json` 中单个服务器的 `timeout` 字段会为该服务器覆盖此值。单个服务器的 `timeout` 若至少为 1000，还会为该服务器的工具调用设置最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 绝不会更早中止这些调用；此下限需要 Claude Code v2.1.203 或更高版本。对于环境变量，低于 1000 的值会被提升为一秒；对于单个服务器的字段，低于 1000 的值会被忽略 |496| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间，以毫秒为单位（默认：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求默认还会在 60 秒后超时；将此变量或按服务器的 `timeout` 设置为大于 60000 可提高该单请求限制。较低的值仍会缩短整体工具执行超时时间，但单请求限制保持为 60 秒。Stdio 和 WebSocket 服务器没有单请求计时器。`.mcp.json` 中按服务器的 `timeout` 字段会为该服务器覆盖此值。至少为 1000 的按服务器 `timeout` 还会设置该服务器工具调用的最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 绝不会更早地中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于环境变量，低于 1000 的值会被提升为一秒；对于按服务器字段，低于 1000 的值会被忽略 |

495| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 对属性值长度的限制。Claude Code 会将携带内容的遥测属性上限设为此值与 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的较小者，以使截断标记保持在 SDK 限制之内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，且所设置的最小值适用于所有信号。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |498| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 的属性值长度限制。Claude Code 会将包含内容的遥测属性上限设为此值与 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中较小的一个，以使截断标记保持在 SDK 限制之内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，并且所设置的最小值适用于所有信号。需要 Claude Code v2.1.214 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |

496| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 可在 `assistant_response` OpenTelemetry 日志事件中包含模型的回复文本。未设置时，Claude Code 改用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 可在设置了 `OTEL_LOG_USER_PROMPTS` 的情况下仍保持回复脱敏。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。需要 Claude Code v2.1.193 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |499| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 可在 `assistant_response` OpenTelemetry 日志事件中包含模型的回复文本。未设置时，Claude Code 改为使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 可在设置了 `OTEL_LOG_USER_PROMPTS` 的情况下仍保持回复被脱敏。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。需要 Claude Code v2.1.193 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |

497| `OTEL_LOG_MANAGED_SETTINGS` | 设置为 `1` 可将脱敏后的托管设置以及脱敏前设置的 SHA-256 摘要添加到 `managed_settings_resolved` OpenTelemetry 日志事件中。默认禁用。在您的 shell、用户设置或托管设置中设置它；项目或本地设置中的值不会将其开启。需要 Claude Code v2.1.274 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#managed-settings-resolved-event) |500| `OTEL_LOG_MANAGED_SETTINGS` | 设置为 `1` 可将脱敏后的托管设置以及脱敏前设置的 SHA-256 摘要添加到 `managed_settings_resolved` OpenTelemetry 日志事件中。默认禁用。请在 shell、用户设置或托管设置中设置它；项目设置或本地设置中的值不会将其开启。需要 Claude Code v2.1.274 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#managed-settings-resolved-event) |

498| `OTEL_LOG_RAW_API_BODIES` | 将 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出。设置为 `1` 可发出在内容限制处截断的内联正文，或设置为 `file:<dir>` 将未截断的正文写入磁盘，并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用于配置内容限制，默认为 60 KB。默认禁用；正文包含完整的对话历史。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |501| `OTEL_LOG_RAW_API_BODIES` | 将 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出。设置为 `1` 可发出按内容限制截断的内联正文，设置为 `file:<dir>` 可将未截断的正文写入磁盘并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用于配置内容限制，默认为 60 KB。默认禁用；正文包含完整的对话历史。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参见[监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |

499| `OTEL_LOG_TOOL_CONTENT` | 设置为 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具内容。span 属性在[各自的开关](/docs/zh-CN/monitoring-usage#new-context-gates)控制下携带工具内容。需要启用[追踪](/docs/zh-CN/monitoring-usage#traces-beta)。默认禁用以保护敏感数据。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage#tool-output-span-event) |502| `OTEL_LOG_TOOL_CONTENT` | 设置为 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具内容。span 属性在[各自的开关](/docs/zh-CN/monitoring-usage#new-context-gates)下携带工具内容。需要[追踪](/docs/zh-CN/monitoring-usage#traces-beta)。默认禁用以保护敏感数据。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage#tool-output-span-event) |

500| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 可在 OpenTelemetry 指标、追踪和日志中包含工具输入参数；MCP 服务器名称；用户编写的工作流名称；工具失败时的原始错误字符串；`api_refusal` 事件上的拒绝 `category`；[费用和 token 指标](/docs/zh-CN/monitoring-usage#cost-counter)上真实的 Agent、skill、插件和 MCP 服务器名称；以及其他工具详细信息。默认禁用以保护 PII。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage) |503| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 可在 OpenTelemetry 指标、追踪和日志中包含工具输入参数；MCP 服务器名称；用户编写的工作流名称；工具失败时的原始错误字符串；`api_refusal` 事件上的拒绝 `category`；[费用和 token 指标](/docs/zh-CN/monitoring-usage#cost-counter)上真实的 Agent、skill、插件和 MCP 服务器名称；以及其他工具详细信息。默认禁用以保护个人身份信息。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage) |

501| `OTEL_LOG_USER_PROMPTS` | 设置为 `1` 可在 OpenTelemetry 追踪和日志中包含用户提示词文本。默认禁用（提示词会被脱敏）。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage) |504| `OTEL_LOG_USER_PROMPTS` | 设置为 `1` 可在 OpenTelemetry 追踪和日志中包含用户提示词文本。默认禁用（提示词会被脱敏）。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage) |

503| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 可在指标属性中包含会话入口点（默认：排除）。在 v2.1.152 中添加。请参阅[监控](/docs/zh-CN/monitoring-usage) |506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 可在指标属性中包含会话入口点（默认：排除）。在 v2.1.152 中添加。请参见[监控](/docs/zh-CN/monitoring-usage) |

504| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 可为 OpenTelemetry 指标和事件添加标识会话所在仓库的 `vcs.*` 属性（默认：排除）。需要 Claude Code v2.1.269 或更高版本。请参阅[仓库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 可为 OpenTelemetry 指标和事件添加标识会话所在仓库的 `vcs.*` 属性（默认：排除）。需要 Claude Code v2.1.269 或更高版本。请参见[仓库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |

505| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 起，Claude Code 会将 `OTEL_RESOURCE_ATTRIBUTES` 中的键附加到指标数据点标签上。设置为 `false` 可排除它们（默认：包含）。请参阅[监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 起，Claude Code 会将 `OTEL_RESOURCE_ATTRIBUTES` 键附加到指标数据点标签上。设置为 `false` 可将其排除（默认：包含）。请参见[监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |

508| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖向 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill)显示的 skill 元数据的字符预算。该预算按上下文窗口的 1% 动态缩放，备用值为 8,000 个字符。保留旧名称是为了向后兼容 |511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖向 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill)显示的 skill 元数据的字符预算。该预算按上下文窗口的 1% 动态缩放，回退值为 8,000 个字符。保留旧名称是为了向后兼容 |

509| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，现在不起任何作用，其所控制大小的 `TaskOutput` 工具也一并移除。此前用于设置 `TaskOutput` 工具保留的[后台任务](/docs/zh-CN/tools-reference#background-commands)输出的最大字符数。Claude 现在改为使用 `Read` 读取后台任务的输出文件 |512| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中与其所限定大小的 `TaskOutput` 工具一起移除，现在不起任何作用。以前用于设置 `TaskOutput` 工具保留的[后台任务](/docs/zh-CN/tools-reference#background-commands)输出的最大字符数。Claude 现在改用 `Read` 读取后台任务的输出文件 |

533| `VERTEX_REGION_CLAUDE_HAIKU_5_5` | 使用 Google Cloud's Agent Platform 时覆盖 Claude Haiku 5.5 的区域。在 v2.1.293 中添加 |

530 534

531还支持标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定于信号的变体）。有关配置详情，请参阅[监控](/docs/zh-CN/monitoring-usage)。535同样支持标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定于信号的变体）。有关配置详情，请参见[监控](/docs/zh-CN/monitoring-usage)。

532 536

533请在您的 shell、用户设置或托管设置中设置 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用于启用导出、选择导出目标或捕获内容的 OpenTelemetry 变量。Claude Code [会在项目和本地设置中忽略这些变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)，但该部分所述的关闭值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及导出间隔、超时和压缩相关变量（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在项目和本地设置中仍然有效。537请在 shell、用户设置或托管设置中设置 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用于开启导出、选择导出目标或捕获内容的 OpenTelemetry 变量。Claude Code [会在项目设置和本地设置中忽略它们](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)，该部分所述的关闭值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及导出间隔、超时和压缩相关变量（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在项目设置和本地设置中仍然生效。

534 538

535<h2 id="what-the-subprocess-environment-scrub-removes">539<h2 id="what-the-subprocess-environment-scrub-removes">

536 子进程环境清理会移除哪些内容540 子进程环境清理会移除哪些内容

errors.md +4 −5

Details

131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [网络](#host-not-allowed-in-a-cloud-session) |131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [网络](#host-not-allowed-in-a-cloud-session) |

133| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/zh-CN/cloud-environments#github-proxy) |133| `403` with `GitHub GraphQL is not available from Claude Code sessions` in a cloud session | [GitHub proxy](/docs/zh-CN/cloud-environments#github-proxy) |

134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [网络](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [网络](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [网络](#sessions-ended-while-this-machine-was-offline) |136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [网络](#sessions-ended-while-this-machine-was-offline) |

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 查看快速模式支出出现的位置

feature-availability.md +4 −4

Details

220</table>220</table>

221 221

222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 适用于 Claude 4 及更高版本的模型。<br />222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 适用于 Claude 4 及更高版本的模型。<br />

223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在这些提供商上，auto mode 仅支持 Claude Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型。请参阅 [Auto mode 配置](/docs/zh-CN/auto-mode-config)。有关会话在这些提供商上启动时所处的权限模式，请参阅[会话启动时的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，这些提供商上的 auto mode 还需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了该要求。<br />223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在这些提供商上，自动模式仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型。请参阅 [Auto mode 配置](/docs/zh-CN/auto-mode-config)。有关会话在这些提供商上启动时所处的权限模式，请参阅[会话启动时的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，这些提供商上的 auto mode 还需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了该要求。<br />

224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您与云提供商的协议约束。<br />224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您与云提供商的协议约束。<br />

225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 仅限仪表板和 API。[贡献指标](/docs/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。<br />225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 仅限仪表板和 API。[贡献指标](/docs/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。<br />

226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 在 macOS 和 Linux 上需要 Claude Code v2.1.224 或更高版本，包括 WSL 2 内的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更高版本。使用 API 密钥身份验证时，消息传递仅限同一台机器。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry 上，消息传递仅限同一台机器，需要 Claude Code v2.1.248 或更高版本。Claude 只能从连接到 [Remote Control](/docs/zh-CN/remote-control) 的会话中找到您的 [cloud sessions](/docs/zh-CN/claude-code-on-the-web) 和其他机器上的会话。要连接，您需要 claude.ai 登录和其他 [Remote Control 要求](/docs/zh-CN/remote-control#requirements)。请参阅[在其他机器上发送消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 在 macOS 和 Linux 上需要 Claude Code v2.1.224 或更高版本，包括 WSL 2 内的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更高版本。使用 API 密钥身份验证时，消息传递仅限同一台机器。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry 上，消息传递仅限同一台机器，需要 Claude Code v2.1.248 或更高版本。Claude 只能从连接到 [Remote Control](/docs/zh-CN/remote-control) 的会话中找到您的 [cloud sessions](/docs/zh-CN/claude-code-on-the-web) 和其他机器上的会话。要连接，您需要 claude.ai 登录和其他 [Remote Control 要求](/docs/zh-CN/remote-control#requirements)。请参阅[在其他机器上发送消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。

244 **部分支持：**244 **部分支持：**

245 245

246 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)246 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

247 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型247 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型

248 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>248 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>

249 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 AWS 协议约束249 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 AWS 协议约束

250 250

270 270

271 * [Desktop](/docs/zh-CN/desktop)：通过[托管设置](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)271 * [Desktop](/docs/zh-CN/desktop)：通过[托管设置](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

272 * [Web search](/docs/zh-CN/tools-reference#websearch-tool-behavior)：Claude 4 及更高版本的模型272 * [Web search](/docs/zh-CN/tools-reference#websearch-tool-behavior)：Claude 4 及更高版本的模型

273 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型273 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型

274 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>274 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>

275 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Google Cloud 协议约束275 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Google Cloud 协议约束

276 276

284 284

285 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)285 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

286 * [Web search](/docs/zh-CN/tools-reference#websearch-tool-behavior)：[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)仅286 * [Web search](/docs/zh-CN/tools-reference#websearch-tool-behavior)：[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)仅

287 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型287 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型

288 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>288 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>

289 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Azure 协议约束289 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Azure 协议约束

290 290

glossary.md +13 −13

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

196 Effort level196 Effort level

197</h3>197</h3>

198 198

199一个设置，控制自适应推理，让模型决定是否以及在每一步上进行多少思考。更高的努力意味着更多的思考 tokens 和更深入的推理；更低的努力更快且更便宜。Effort 在 Fable 模型、Opus 4.6 及更高版本以及 Sonnet 4.6 及更高版本上受支持。199一个设置，控制自适应推理，让模型决定是否以及在每一步上进行多少思考。更高的 effort 意味着更多的思考 token 和更深入的推理；更低的 effort 更快且更便宜。Effort 在 Fable 模型、Opus 4.6 及更高版本、Sonnet 4.6 及更高版本以及 Haiku 5.5 上受支持。

200 200

201了解更多：[调整 effort level](/docs/zh-CN/model-config#adjust-effort-level)201了解更多：[调整 effort level](/docs/zh-CN/model-config#adjust-effort-level)

202 202

380 Sandboxing380 Sandboxing

381</h3>381</h3>

382 382

383Bash 工具的操作系统级文件系统和网络隔离。命令在您预先定义的边界内运行，因此 Claude 可以在其中自由工作，无需每个命令的批准提示。Sandboxing 是与 [permission rules](#permission-rule) 分开的一层。383Bash 工具的操作系统级文件系统和网络隔离。命令在您预先定义的边界内运行，因此 Claude 可以在其中自由工作，无需每个命令的批准提示。沙箱隔离是与 [permission rules](#permission-rule) 分开的一层。

384 384

385了解更多：[Sandboxing](/docs/zh-CN/sandboxing)385了解更多：[Sandboxing](/docs/zh-CN/sandboxing)

386 386

388 Session388 Session

389</h3>389</h3>

390 390

391与您当前目录相关的对话，具有自己独立的 [context window](#context-window)。会话可以使用 `claude -c` 恢复，使用 `--fork-session` 分叉以在新会话 ID 下保留历史，或在终端中并行运行。运行 `/clear` 启动新会话；前一个会话保持存储并可通过 `/resume` 获得。每个会话的记录存储在 `~/.claude/projects/` 下。391与您当前目录相关的对话，具有自己独立的 [上下文窗口](#context-window)。会话可以使用 `claude -c` 恢复，使用 `--fork-session` 分叉以在新会话 ID 下保留历史，或在终端中并行运行。运行 `/clear` 启动新会话；前一个会话保持存储并可通过 `/resume` 获得。每个会话的会话记录存储在 `~/.claude/projects/` 下。

392 392

393了解更多：[使用会话](/docs/zh-CN/how-claude-code-works#work-with-sessions)393了解更多：[使用会话](/docs/zh-CN/how-claude-code-works#work-with-sessions)

394 394

396 Settings layers396 Settings layers

397</h3>397</h3>

398 398

399Claude Code 读取配置的层次结构，按优先级顺序从最高到最低：[managed policy](#managed-settings)、命令行参数、`.claude/settings.local.json` 处的本地设置、`.claude/settings.json` 处的项目设置，然后是 `~/.claude/settings.json` 处的用户设置。数组跨层合并；更高层的标量覆盖较低的。请参阅 [Settings precedence](/docs/zh-CN/settings#settings-precedence)。399Claude Code 读取配置的层次结构，按优先级顺序从最高到最低：[managed policy](#managed-settings)、通过 `--settings` 标志传递的设置、`.claude/settings.local.json` 处的本地设置、`.claude/settings.json` 处的项目设置，然后是 `~/.claude/settings.json` 处的用户设置。数组跨层合并；更高层的标量覆盖较低的。请参阅 [Settings precedence](/docs/zh-CN/settings#settings-precedence)。

400 400

401了解更多：[Settings files](/docs/zh-CN/settings#where-settings-live)401了解更多：[Settings files](/docs/zh-CN/settings#where-settings-live)

402 402

404 Skill404 Skill

405</h3>405</h3>

406 406

407一个 `SKILL.md` 文件，包含 Claude 添加到其工具包中的指令、知识或工作流。Claude 在相关时自动加载 skill，或您可以使用 `/skill-name` 直接调用它。Skills 遵循 Agent Skills 开放标准；Claude Code 使用调用控制和 subagent 执行扩展它。407一个 `SKILL.md` 文件，包含 Claude 添加到其工具包中的指令、知识或工作流。Claude 在相关时自动加载 skill，或您可以使用 `/skill-name` 直接调用它。Skills 遵循 Agent Skills 开放标准；Claude Code 使用调用控制和子代理执行扩展它。

408 408

409Skills 是自定义命令的推荐后继。`.claude/commands/deploy.md` 处的文件和 `.claude/skills/deploy/SKILL.md` 处的文件都创建 `/deploy` 并以相同方式工作；现有命令文件继续工作。409Skills 是自定义命令的推荐后继。`.claude/commands/deploy.md` 处的文件和 `.claude/skills/deploy/SKILL.md` 处的文件都创建 `/deploy` 并以相同方式工作；现有命令文件继续工作。

410 410

414 Subagent414 Subagent

415</h3>415</h3>

416 416

417一个专门的 AI 助手，在其自己的上下文窗口中运行，具有自定义系统提示、特定工具访问和独立权限。它处理委派任务并向主对话返回摘要。使用 subagents 将大型探索保留在主上下文之外或运行并行研究。Subagent 保持在生成它的会话内。要在您自己运行的单独会话之间传递发现，请使用 [cross-session messaging](/docs/zh-CN/cross-session-messaging)。417一个专门的 AI 助手，在其自己的上下文窗口中运行，具有自定义系统提示词、特定工具访问和独立权限。它处理委派任务并向主对话返回摘要。使用子代理将大型探索保留在主上下文之外或运行并行研究。子代理保持在生成它的会话内。要在您自己运行的单独会话之间传递发现，请使用 [cross-session messaging](/docs/zh-CN/cross-session-messaging)。

418 418

419内置 subagents 包括 Explore、Plan 和通用目的。419内置子代理包括 Explore、Plan 和通用目的。

420 420

421了解更多：[创建自定义 subagents](/docs/zh-CN/sub-agents)421了解更多：[创建自定义子代理](/docs/zh-CN/sub-agents)

422 422

423<h3 id="surface">423<h3 id="surface">

424 Surface424 Surface

425</h3>425</h3>

426 426

427您访问 Claude Code 的任何地方：CLI、VS Code、JetBrains、Desktop 或 claude.ai。所有 surfaces 共享相同的引擎。您机器上的会话读取您的本地 CLAUDE.md、settings 和 skills；[cloud sessions](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup) 从您的存储库的新克隆开始，不读取您机器上的 `~/.claude/`。Slack 和 Chrome 扩展是连接到 surface 的集成，而不是 surfaces 本身。427您访问 Claude Code 的任何地方：CLI、VS Code、JetBrains、Desktop 或 claude.ai。所有使用入口共享相同的引擎。您机器上的会话读取您的本地 CLAUDE.md、设置和 skills；[云端会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup) 从您的仓库的新克隆开始，不读取您机器上的 `~/.claude/`。Slack 和 Chrome 扩展是连接到使用入口的集成，而不是使用入口本身。

428 428

429了解更多：[平台和集成](/docs/zh-CN/platforms)429了解更多：[平台和集成](/docs/zh-CN/platforms)

430 430

432 System prompt432 System prompt

433</h3>433</h3>

434 434

435Claude Code 在每个请求之前发送给您的对话的指令，涵盖 Claude 如何使用工具、安全行为和格式化响应。您可以使用 `--append-system-prompt` 添加到系统提示或使用 `--system-prompt` 替换它。系统提示是 [prompt cache](/docs/zh-CN/prompt-caching#how-the-cache-is-organized) 的第一层。435Claude Code 在每个请求之前发送给您的对话的指令，涵盖 Claude 如何使用工具、安全行为和格式化回复。您可以使用 `--append-system-prompt` 添加到系统提示词或使用 `--system-prompt` 替换它。系统提示词是 [prompt cache](/docs/zh-CN/prompt-caching#how-the-cache-is-organized) 的第一层。

436 436

437您的 [CLAUDE.md](#claude-md) 文件和您的 [output style](#output-style) 的指令不是系统提示的一部分。Claude Code 在对话中将它们作为 [system reminders](#system-reminder) 传递。437您的 [CLAUDE.md](#claude-md) 文件和您的 [output style](#output-style) 的指令不是系统提示词的一部分。Claude Code 在对话中将它们作为 [system reminders](#system-reminder) 传递。

438 438

439了解更多：[System prompt flags](/docs/zh-CN/cli-reference#system-prompt-flags)439了解更多：[System prompt flags](/docs/zh-CN/cli-reference#system-prompt-flags)

440 440

453 453

454在记录的 API 请求中，系统提醒出现在用户消息内的 `<system-reminder>` 标签中，或在某些模型上作为具有 `system` 角色的单独消息。454在记录的 API 请求中，系统提醒出现在用户消息内的 `<system-reminder>` 标签中，或在某些模型上作为具有 `system` 角色的单独消息。

455 455

456了解更多：[Claude Code 在系统提示之外添加的上下文](/docs/zh-CN/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)456了解更多：[Claude Code 在系统提示词之外添加的上下文](/docs/zh-CN/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)

457 457

458<h2 id="t">458<h2 id="t">

459 T459 T

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

headless.md +22 −6

Details

219 跟踪 subagent 消息219 跟踪 subagent 消息

220</h4>220</h4>

221 221

222来自 [subagents](/docs/zh-CN/sub-agents) 的消息在流中显示为 `assistant` 和 `user` 消息，其 `parent_tool_use_id` 字段是生成 subagent 的工具调用的 ID。来自主对话的消息在该字段中携带 `null`。222来自[子代理](/docs/zh-CN/sub-agents)以及[在子代理中运行](/docs/zh-CN/skills#run-skills-in-a-subagent)的 skill 的消息在流中显示为 `assistant` 和 `user` 消息。其 `parent_tool_use_id` 字段表明每条消息属于哪次运行。来自主对话的消息在该字段中为 `null`。

223 223

224来自在 [前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) 运行的 subagent 的第一条消息是携带驱动它的提示的 `user` 消息。在该第一条消息之后，Claude Code 发出：224来自 forked skill 或在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的第一条消息是一条 `user` 消息，携带驱动它的提示词或 skill 内容。在该第一条消息之后，Claude Code 发出：

225 225

226* **默认情况下**：subagent 的 `tool_use` 和 `tool_result` 块。226* **默认情况下**：该次运行的 `tool_use` 和 `tool_result` 块。

227* **使用 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars)**：subagent 的文本和思考块也是如此，因此您可以重建每个 subagent 的记录。这需要 Claude Code v2.1.211 或更高版本。227* **使用 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars) 时**：还包括该次运行的文本和思考块，因此您可以重建每次运行的会话记录。

228 228

229当您启用任一选项时，Claude Code 从 [每个嵌套深度的 subagents](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 转发消息，无论每个 subagent 是使用 Agent 工具生成的还是作为 [forked skill](/docs/zh-CN/skills#run-skills-in-a-subagent) 启动的。forked skill 生成的 subagents 的消息，以及在 subagent 或另一个 forked skill 内启动的 forked skills，需要 Claude Code v2.1.275 或更高版本。在 `parent_tool_use_id` 中，嵌套 subagent 的消息携带启动它的 Agent 或 Skill 工具调用的 ID，因此您可以通过跟踪这些 ID 来重建完整的嵌套树。在 v2.1.219 之前，来自嵌套 subagents 的消息不会出现在流中。229当您启用任一选项时，Claude Code 会转发来自[每个嵌套深度的子代理](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的消息，无论每个子代理是使用 Agent 工具生成的还是作为 forked skill 启动的。在 `parent_tool_use_id` 中，嵌套子代理的消息携带启动它的 Agent 或 Skill 工具调用的 ID，因此您可以通过跟踪这些 ID 来重建完整的嵌套树。

230 230

231[在 subagent 中运行](/docs/zh-CN/skills#run-skills-in-a-subagent) 的 Skills 在流中以相同的方式出现：forked skill 的第一条消息是携带驱动运行的 skill 内容的 `user` 消息。如果您启用任一选项，流也会携带 forked skill 的文本和思考块。在 v2.1.265 之前，只有 forked skill 的 `tool_use` 和 `tool_result` 块出现在流中。231由 Claude 通过工具调用启动的运行携带该工具调用的 ID。通过将 `/<skill-name>` 作为提示词传递而启动的 forked skill 没有工具调用，因此其消息改为携带 `forked-command-` 值，并在其完成后到达。请在第一列中查找运行的启动方式：

232

233| 运行的启动方式 | `parent_tool_use_id` | 其消息何时到达 |

234| :- | :- | :- |

235| Claude 从主对话调用 Agent 工具 | 该 Agent `tool_use` 块的 ID | 在子代理工作期间 |

236| Claude 从主对话为 forked skill 调用 Skill 工具 | 该 Skill `tool_use` 块的 ID | 在 forked skill 工作期间 |

237| 您将 `/<skill-name>` 作为提示词传递 | 以 `forked-command-` 开头的值 | 在 forked skill 完成后一起按顺序到达 |

238

239对于从提示词启动的 forked skill，请按 `forked-command-` 前缀匹配 `parent_tool_use_id`，因为其后的名称可能与您输入的名称不同。

240

241如果流中缺少其中某些消息，请将您的 Claude Code 版本与以下最低版本进行对照：

242

243* **`--forward-subagent-text` 和 `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`**：v2.1.211 或更高版本

244* **在每个嵌套深度转发**：v2.1.219 或更高版本

245* **Claude 从主对话使用 Skill 工具启动的 forked skill**：其 `tool_use` 和 `tool_result` 块需要 v2.1.86 或更高版本，其第一条 `user` 消息以及文本和思考块需要 v2.1.265 或更高版本

246* **forked skill 生成的子代理的消息，以及在子代理或另一个 forked skill 内启动的 forked skill 的消息**：v2.1.275 或更高版本

247* **通过将 `/<skill-name>` 作为提示词传递而启动的 forked skill 的消息**：v2.1.287 或更高版本

232 248

233<h4 id="handle-api-retries">249<h4 id="handle-api-retries">

234 处理 API 重试250 处理 API 重试

hooks.md +8 −6

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 会话](/docs/zh-CN/worktrees#start-claude-in-a-worktree)，并在 Claude Code 提示时选择删除该 worktree

3279* 设置了 `isolation: "worktree"` 的子代理完成3279* 您退出一个尚未[命名](/docs/zh-CN/sessions#name-your-sessions)的交互式 worktree 会话，Claude Code 未发现已更改或未跟踪的文件，并在不提示您的情况下删除该 worktree

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

3281

3282Claude Code 使用 git 查找已更改或未跟踪的文件，因此对于不是 git checkout 或不在 git checkout 内的 worktree，即使目录中有未提交的工作，它也找不到任何文件。请在 WorktreeRemove hook 删除任何内容之前检查这类工作。

3281 3283

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

3283 3285

3284* **没有 WorktreeRemove hook**：当您退出 `--worktree` 会话并选择移除时，Claude Code 会回退为对 WorktreeCreate hook 返回的路径执行 `git worktree remove --force`，因此 git 能识别的 worktree 会被移除。git 无法识别的 worktree（例如您的 hook 使用非 git 版本控制系统创建的 worktree）会保留在磁盘上。关于删除[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)时如何处理由 hook 创建的 worktree，请参阅 Agent 视图的删除规则。3286* **没有 WorktreeRemove hook**：当 Claude Code 在您退出 worktree 会话时删除该 worktree，它会回退到对 WorktreeCreate hook 返回的路径执行 `git worktree remove --force`，因此 git 能识别的 worktree 会被删除。git 无法识别的 worktree（例如您的 hook 使用非 git 版本控制系统创建的 worktree）会保留在磁盘上。关于删除[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)时如何处理由 hook 创建的 worktree，请参阅 agent view 的删除规则。

3285* **Hook 以 0 退出**：该 worktree 视为已移除。Claude Code 不会从 hook 读取其他任何内容，因此请确保您的 hook 已删除该目录。3287* **Hook 以 0 退出**：该 worktree 视为已移除。Claude Code 不会从 hook 读取其他任何内容，因此请确保您的 hook 已删除该目录。

3286* **Hook 以非零值退出**：如果 `worktree_path` 处的目录在之后仍然存在，则移除失败，worktree 保留在磁盘上，且不会回退到 git。在以非零值退出之前已删除目录的 hook 视为已移除。关于失败的报告方式，请参阅 [WorktreeRemove 输入](#worktreeremove-input)。3288* **Hook 以非零值退出**：如果 `worktree_path` 处的目录在之后仍然存在，则移除失败，worktree 保留在磁盘上，且不会回退到 git。在以非零值退出之前已删除目录的 hook 视为已移除。关于失败的报告方式，请参阅 [WorktreeRemove 输入](#worktreeremove-input)。

3287 3289

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

interactive-mode.md +1 −1

Details

42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |

43| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环通过 `default`（在模式指示器中标记为 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions` 然后 `auto`。从 `auto`，第一次按下切换到 `default`。请参阅[权限模式](/docs/zh-CN/permission-modes)。在文件权限提示上，相同的键会关闭打开的[注释字段](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，它会选择允许该操作在会话其余部分的选项，当提示提供该选项时 |43| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环通过 `default`（在模式指示器中标记为 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions` 然后 `auto`。从 `auto`，第一次按下切换到 `default`。请参阅[权限模式](/docs/zh-CN/permission-modes)。在文件权限提示上，相同的键会关闭打开的[注释字段](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，它会选择允许该操作在会话其余部分的选项，当提示提供该选项时 |

47 47

48<h3 id="text-editing">48<h3 id="text-editing">

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

mobile.md +1 −1

Details

89移动客户端涵盖了会话需要的大部分内容，但有一些限制：89移动客户端涵盖了会话需要的大部分内容，但有一些限制：

90 90

91* **仅限本地命令**：仅在终端界面中运行的命令，例如 `/plugin` 和 `/resume`，无法从应用程序中工作。[远程控制限制](/docs/zh-CN/remote-control#limitations)列出了从移动设备工作的命令以及它们的行为如何不同。91* **仅限本地命令**：仅在终端界面中运行的命令，例如 `/plugin` 和 `/resume`，无法从应用程序中工作。[远程控制限制](/docs/zh-CN/remote-control#limitations)列出了从移动设备工作的命令以及它们的行为如何不同。

92* **权限模式**：云会话在模式下拉菜单中提供接受编辑、Plan 和 Auto，远程控制会话提供 Manual、接受编辑和 Plan。在任何情况下，您都无法从应用程序中选择 Bypass permissions，也无法为远程控制会话选择 Auto。请参阅[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)。92* **权限模式**：云端会话提供接受编辑、Plan 和 Auto，Remote Control 会话提供 Manual、接受编辑、Plan 和 Auto。在任何一种情况下，您都无法从应用程序中选择 Bypass permissions。有关 Auto 何时可用，请参阅[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)。

93* **Dispatch 计划**：Dispatch 需要 Pro 或 Max 计划，在 Team 或 Enterprise 上不可用。93* **Dispatch 计划**：Dispatch 需要 Pro 或 Max 计划，在 Team 或 Enterprise 上不可用。

94 94

95<h2 id="related-resources">95<h2 id="related-resources">

model-config.md +36 −23

Details

43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |

44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |

45 45

~~46`opus` 和 `sonnet` 别名解析到的版本取决于提供商：~~46`opus`、`sonnet` 和 `haiku` 别名在 Anthropic API 上解析到最新版本，在其他一些提供商上解析到较早的版本：

47 47

~~48| 提供商 | `opus` | `sonnet` |~~48| 提供商 | `opus` | `sonnet` | `haiku` |

~~49| :- | :- | :- |~~49| :- | :- | :- | :- |

54 54

55<span id="fable-alias-resolution" />55<span id="fable-alias-resolution" />

56 56

58 58

59未配置为提供 `claude-fable-5-1` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.1，请使用 `/model claude-fable-5-1` 选择它。59未配置为提供 `claude-fable-5-1` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.1，请使用 `/model claude-fable-5-1` 选择它。

60 60

~~61当别名解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来获得较新的模型。~~61当 `opus` 或 `sonnet` 解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来使用较新的模型。

62 62

63较早的版本将这些别名解析到较旧的模型。有关每个别名更改的版本，请参阅[版本历史](#version-history)。63较早的版本将这些别名解析到较旧的模型。有关每个别名更改的版本，请参阅[版本历史](#version-history)。

64 64

65别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。65别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

66 66

67<Note>67<Note>

68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本，Opus 5.5 需要 v2.1.280 或更高版本。如果来自较旧版本的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本，Opus 5.5 需要 v2.1.280 或更高版本。如果从较旧版本对其中某个模型的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。使用 Haiku 5.5 时请使用 v2.1.293 或更高版本。运行 `claude update` 进行升级。

69</Note>69</Note>

70 70

71<h3 id="work-with-fable">71<h3 id="work-with-fable">

156 156

157当 Claude Code 与 Anthropic API 通信时（直接或通过代理它的 [LLM 网关](/docs/zh-CN/llm-gateway)），`/model` 选择器中的价格会出现，行上的价格是该行选择的模型的价格。在[第三方提供商](/docs/zh-CN/third-party-integrations)（如 Amazon Bedrock）和 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，你的提供商或网关决定你支付的费用，所以选择器行不显示价格。价格仅是显示标签；它不影响行选择哪个模型或你的提供商计费的内容。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 列表价格，行可能显示与其选择的模型不同的模型的价格。157当 Claude Code 与 Anthropic API 通信时（直接或通过代理它的 [LLM 网关](/docs/zh-CN/llm-gateway)），`/model` 选择器中的价格会出现，行上的价格是该行选择的模型的价格。在[第三方提供商](/docs/zh-CN/third-party-integrations)（如 Amazon Bedrock）和 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，你的提供商或网关决定你支付的费用，所以选择器行不显示价格。价格仅是显示标签；它不影响行选择哪个模型或你的提供商计费的内容。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 列表价格，行可能显示与其选择的模型不同的模型的价格。

158 158

159使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话保持它们保存记录时使用的模型，无论当前 `model` 设置如何。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。这可以防止另一个会话的 `/model` 选择在恢复时改变模型。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，根本不会恢复记录模型，会话通过正常的优先级顺序解析其模型。159使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话会保持保存会话记录时所使用的模型。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，完全不会恢复会话记录中的模型，会话会通过正常的优先级顺序解析其模型。

160

161如果您的 `model` 设置为 `haiku`，在 Haiku 模型上保存的会话会在 `haiku` 当前解析到的模型上恢复。例如，当 `haiku` 解析到 Haiku 5.5 后，在 Haiku 4.5 上保存的会话会在 Haiku 5.5 上恢复。

160 162

161你为新启动使用 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 也可以，在其部分中列出的条件下。163你为新启动使用 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 也可以，在其部分中列出的条件下。

162 164

645| 模型 | 级别 |647| 模型 | 级别 |

646| :- | :- |648| :- | :- |

650 652

651如果您设置活动模型不支持的级别，Claude Code 会回退到不高于您所设级别的最高支持级别。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。您的组织或您自己的设置也可以限制模型提供的级别；请参阅[组织 effort 限制](#organization-effort-limits)。653如果您设置活动模型不支持的级别，Claude Code 会回退到不高于您所设级别的最高支持级别。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。您的组织或您自己的设置也可以限制模型提供的级别；请参阅[组织 effort 限制](#organization-effort-limits)。

654 656

6551. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）6571. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）

6562. 您的设置：您为模型保存的级别或 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级6582. 您的设置：您为模型保存的级别或 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级

6573. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5 和 Sonnet 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认 effort 级别时，当您运行该模型时该级别是默认值。自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。6593. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认 effort 级别时，当您运行该模型时该级别是默认值。自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。

658 660

659Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。661Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。

660 662

709| 级别 | 何时使用 |711| 级别 | 何时使用 |

710| :- | :- |712| :- | :- |

711| `low` | 快速交换，您审查每个结果，例如头脑风暴、初稿或小改动如重命名 |713| `low` | 快速交换，您审查每个结果，例如头脑风暴、初稿或小改动如重命名 |

715| `max` | 您想让 Claude 自己完成的难题，例如发现安全漏洞。`max` 可能显示收益递减，容易过度思考，所以在广泛采用前测试 |717| `max` | 您想让 Claude 自己完成的难题，例如发现安全漏洞。`max` 可能显示收益递减，容易过度思考，所以在广泛采用前测试 |

753 755

754自适应推理使思考在每一步上可选，因此 Claude 可以更快地响应常规提示词，并为受益于它的步骤保留更深入的思考。如果您想要 Claude 比当前级别产生的更频繁或更少地思考，您可以直接在您的提示词或 `CLAUDE.md` 中说出来；模型在其 effort 设置内响应该指导。756自适应推理使思考在每一步上可选，因此 Claude 可以更快地响应常规提示词，并为受益于它的步骤保留更深入的思考。如果您想要 Claude 比当前级别产生的更频繁或更少地思考，您可以直接在您的提示词或 `CLAUDE.md` 中说出来；模型在其 effort 设置内响应该指导。

755 757

756Fable 模型、Sonnet 5 及更高版本和 Opus 4.7 及更高版本始终使用自适应推理。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。758Fable 模型、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本始终使用自适应推理。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。

757 759

758在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/docs/zh-CN/env-vars)。760在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/docs/zh-CN/env-vars)。

759 761

767| :- | :- |769| :- | :- |

770| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars)，这在 Anthropic API 上关闭思考，除了 Opus 5.5、Sonnet 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 改为省略 `thinking` 参数，自适应推理模型可能仍然思考 |772| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars)，这在 Anthropic API 上关闭思考，除了 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 改为省略 `thinking` 参数，自适应推理模型可能仍然思考 |

771 773

772您不能在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考。对于这些模型，会话切换和 `/config` 行显示 `Thinking can't be turned off`，而不是提供切换，保存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在那里没有效果。在这些模型上，模型根据 effort 级别按步骤决定思考多少。保存的设置在您切换到接受它的模型时再次应用。774您不能在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上关闭思考。对于这些模型，会话切换和 `/config` 行显示 `Thinking can't be turned off`，而不是提供切换，保存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在那里没有效果。在这些模型上，模型根据 effort 级别按步骤决定思考多少。保存的设置在您切换到接受它的模型时再次应用。

773 775

774Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块，因此如果您想要完整摘要在展开时可用，在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考 token 付费，即使折叠或编辑。776Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块，因此如果您想要完整摘要在展开时可用，在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考 token 付费，即使折叠或编辑。

775 777

779 扩展上下文781 扩展上下文

780</h3>782</h3>

781 783

782Fable 5.1、Fable 5、Sonnet 5 及更高版本、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万 token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，用于具有大型代码库的长会话。784Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万 token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，用于具有大型代码库的长会话。

783 785

784在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更高版本和 Opus 4.7 及更高版本在每个套餐上运行 1M 窗口，包括 Pro。您不需要为这些模型上的 1M 窗口选择 `[1m]` 变体或打开使用额度。Fable 使用本身可以在某些套餐上计费到使用额度；请参阅[Fable 和使用额度](#fable-and-usage-credits)。786在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本在每个套餐上运行 1M 窗口，包括 Pro。您不需要为这些模型上的 1M 窗口选择 `[1m]` 变体或打开使用额度。Fable 使用本身可以在某些套餐上计费到使用额度；请参阅[Fable 和使用额度](#fable-and-usage-credits)。

785 787

786Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的套餐。在 Max、Team 和 Enterprise 套餐上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅套餐上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。788Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的套餐。在 Max、Team 和 Enterprise 套餐上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅套餐上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。

787 789

795 797

796<span id="context-window-behind-a-gateway" />798<span id="context-window-behind-a-gateway" />

797 799

798如果您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](/docs/zh-CN/llm-gateway)或另一个代理，Claude Code 给每个它识别的模型与该模型在 Anthropic API 上具有的相同上下文窗口。Fable 5.1、Fable 5、Sonnet 5 及更高版本和 Opus 4.7 及更高版本获得 1M 窗口，没有 `[1m]` 变体可选择，仅通过其 `[1m]` 变体达到 1M 的模型（如 Opus 4.6）在没有它的情况下运行在 200K。Claude Code 无法检测网关或其后面的服务器强制的更低限制。如果您的网关拒绝超过 200K token 的请求，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars)，以便所有模型上的会话都[在该边界处压缩](#set-the-auto-compact-window)。800如果您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](/docs/zh-CN/llm-gateway)或另一个代理，Claude Code 给每个它识别的模型与该模型在 Anthropic API 上具有的相同上下文窗口。Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本获得 1M 窗口，没有 `[1m]` 变体可选择，仅通过其 `[1m]` 变体达到 1M 的模型（如 Opus 4.6）在没有它的情况下运行在 200K。Claude Code 无法检测网关或其后面的服务器强制的更低限制。如果您的网关拒绝超过 200K token 的请求，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars)，以便所有模型上的会话都[在该边界处压缩](#set-the-auto-compact-window)。

799 801

800要关闭 1M 上下文，设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 1M 模型变体。在具有原生 1M 窗口的模型上，例如 Sonnet 5 和 Fable 模型，它也将模型视为具有 200K 上下文窗口：802要关闭 1M 上下文，设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 1M 模型变体。在具有原生 1M 窗口的模型上，例如 Sonnet 5 和 Fable 模型，它也将模型视为具有 200K 上下文窗口：

801 803

804 806

805在 v2.1.223 之前，Claude Code 仅将 Sonnet 5、Opus 4.8 和 Opus 5 会话限制在 200K。请参阅[环境变量](/docs/zh-CN/env-vars)。807在 v2.1.223 之前，Claude Code 仅将 Sonnet 5、Opus 4.8 和 Opus 5 会话限制在 200K。请参阅[环境变量](/docs/zh-CN/env-vars)。

806 808

8071M 上下文窗口使用标准模型定价，超过 200K 的 token 没有溢价。对于扩展上下文包含在您的订阅中的套餐，使用仍由您的订阅覆盖。对于通过使用额度访问扩展上下文的套餐，token 计费到使用额度。8091M 上下文窗口使用标准模型定价，超过 200K 的 token 没有溢价，但 Haiku 5.5 除外，它[在提示词超过 100K token 时费用更高](#haiku-5-5-context-window-and-pricing)。对于扩展上下文包含在您的订阅中的套餐，使用仍由您的订阅覆盖。对于通过使用额度访问扩展上下文的套餐，token 计费到使用额度。

808 810

809如果您的账户支持 1M 上下文，该选项会出现在最新版本的 Claude Code 的 `/model` 选择器中。如果您看不到它，请重新启动您的会话，在第三方提供商上检查您的部署是否使用 `ANTHROPIC_DEFAULT_*_MODEL` 变量[固定了模型](#pin-models-for-third-party-deployments)。811如果您的账户支持 1M 上下文，该选项会出现在最新版本的 Claude Code 的 `/model` 选择器中。如果您看不到它，请重新启动您的会话，在第三方提供商上检查您的部署是否使用 `ANTHROPIC_DEFAULT_*_MODEL` 变量[固定了模型](#pin-models-for-third-party-deployments)。

810 812

831 833

832* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有原生 1M 窗口的每个模型上的会话限制在 200K 窗口；请参阅[扩展上下文](#extended-context)了解该限制如何被强制执行。对于需要限制上下文的部署很有用。834* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有原生 1M 窗口的每个模型上的会话限制在 200K 窗口；请参阅[扩展上下文](#extended-context)了解该限制如何被强制执行。对于需要限制上下文的部署很有用。

833 835

836<h4 id="haiku-5-5-context-window-and-pricing">

837 Haiku 5.5 上下文窗口和定价

838</h4>

839

840在 Anthropic API 上，Haiku 5.5 在每个套餐上都运行 1M 上下文窗口，没有 `[1m]` 后缀可选择。其模型 ID 为 `claude-haiku-5-5`。要使用它，请在会话中运行 `/model claude-haiku-5-5`，或在 shell 中使用 `claude --model claude-haiku-5-5` 启动 Claude Code。

841

842当 Haiku 5.5 请求的提示词超过 100K token 时，每 token 的费用更高。两种费率请参阅 [Anthropic 定价](https://platform.claude.com/docs/en/about-claude/pricing)。

843

844会话默认在约 967K token 时自动压缩。要更早压缩，请为该模型[设置更小的自动压缩窗口](#set-the-auto-compact-window)。

845

834<h2 id="context-window-and-auto-compaction">846<h2 id="context-window-and-auto-compaction">

835 上下文窗口和自动压缩847 上下文窗口和自动压缩

836</h2>848</h2>

865* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩877* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩

866* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上878* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上

867* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩879* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩

868* 使用原生 1M 窗口运行的模型在窗口填满之前进行压缩，默认情况下约为 967K 令牌。在 Anthropic API 上，这些包括 Sonnet 5、Fable 模型以及 Opus 4.7 及更高版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，请参阅[为第三方部署固定模型](#pin-models-for-third-party-deployments)以了解哪些模型使用该窗口。在自定义 `ANTHROPIC_BASE_URL` 后面，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)880* 使用原生 1M 窗口运行的模型在窗口填满之前进行压缩，默认情况下约为 967K token。在 Anthropic API 上，这些包括 Sonnet 5、Haiku 5.5、Fable 模型以及 Opus 4.7 及更高版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，请参阅[为第三方部署固定模型](#pin-models-for-third-party-deployments)以了解哪些模型使用该窗口。在自定义 `ANTHROPIC_BASE_URL` 后面，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)

869* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)881* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)

870 882

871<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">883<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

1093 1105

1094| 版本 | 更改 |1106| 版本 | 更改 |

1095| :- | :- |1107| :- | :- |

1108| v2.1.293 | `haiku` 在 Anthropic API 上解析为 Haiku 5.5 |

1096| v2.1.284 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5.5 |1109| v2.1.284 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5.5 |

1097| v2.1.280 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Opus 5.5 |1110| v2.1.280 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Opus 5.5 |

1098| v2.1.257 | `fable` 解析为 Fable 5.1，Claude 应用网关会话中除外 |1111| v2.1.257 | `fable` 解析为 Fable 5.1，Claude 应用网关会话中除外 |

1100| v2.1.207 | `opus` 在 AWS 上的 Claude Platform、Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.8 |1113| v2.1.207 | `opus` 在 AWS 上的 Claude Platform、Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.8 |

1101| v2.1.197 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5 |1114| v2.1.197 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5 |

1102| v2.1.154 | `opus` 在 Anthropic API 上解析为 Opus 4.8 |1115| v2.1.154 | `opus` 在 Anthropic API 上解析为 Opus 4.8 |

1103| 更早版本 | `opus` 在 AWS 上的 Claude Platform 上解析为 Opus 4.7，在 Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.6。`fable` 在每个提供商上解析为 Fable 5 |1116| 更早版本 | `opus` 在 AWS 上的 Claude Platform 上解析为 Opus 4.7，在 Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.6。`fable` 在每个提供商上解析为 Fable 5，`haiku` 在每个提供商上解析为 Haiku 4.5 |

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

permission-modes.md +4 −4

Details

233 </Tab>233 </Tab>

234 234

235 <Tab title="Web and mobile">235 <Tab title="Web and mobile">

236 在 [claude.ai/code](https://claude.ai/code) 或移动应用中使用提示框旁边的模式下拉菜单。权限提示出现在 claude.ai 中以供批准。显示哪些模式取决于会话在何处运行：236 在 [claude.ai/code](https://claude.ai/code) 上，使用输入框旁边的模式下拉菜单。在移动应用中，点击输入框中的 **+** 按钮，然后点击 **Permission**。云端会话和 Remote Control 会话提供不同的权限模式：

237 237

238 * **[Cloud sessions](/docs/zh-CN/claude-code-on-the-web)**：Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Manual。云会话仍然遵守设置中的 `defaultMode: "acceptEdits"`。Auto 模式仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。238 * **[Cloud sessions](/docs/zh-CN/claude-code-on-the-web)**：Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Manual。云会话仍然遵守设置中的 `defaultMode: "acceptEdits"`。Auto 模式仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。

239 * **[Remote Control](/docs/zh-CN/remote-control) sessions** 在您的本地机器上：Manual、Accept edits 和 Plan（对于您自己启动的会话），您无法从应用中选择 Auto 或 Bypass permissions。对于在您的计算机上运行的项目线程，请参阅[在您自己的计算机上运行线程](/docs/zh-CN/claude-projects#run-a-thread-on-your-own-computer)。239 * **[Remote Control](/docs/zh-CN/remote-control) sessions** 在您的本地机器上：Manual、Accept edits、Plan 和 Auto（对于您自己启动的会话），您无法从应用中选择 Bypass permissions。要使用 Auto，会话必须满足自动模式的[可用性要求](#eliminate-prompts-with-auto-mode)。对于在您的计算机上运行的项目线程，请参阅[在您自己的计算机上运行线程](/docs/zh-CN/claude-projects#run-a-thread-on-your-own-computer)。

240 * 除了 Bypass permissions，下拉菜单显示本地会话所在的权限模式，包括从终端设置的模式。它在应用或终端中权限模式更改时更新。240 * 除了 Bypass permissions，下拉菜单显示本地会话所在的权限模式，包括从终端设置的模式。它在应用或终端中权限模式更改时更新。

241 * 由[桌面应用](/docs/zh-CN/desktop)或 [VS Code 扩展](/docs/zh-CN/vs-code)托管的会话在权限模式更改时向 claude.ai 报告，与在终端中托管的会话相同。241 * 由[桌面应用](/docs/zh-CN/desktop)或 [VS Code 扩展](/docs/zh-CN/vs-code)托管的会话在权限模式更改时向 claude.ai 报告，与在终端中托管的会话相同。

242 * 在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 连接的会话根本不报告其权限模式，因此 claude.ai 和移动应用可能显示会话不在的权限模式。不匹配仅影响标签。Claude Code 从会话的实际权限模式生成权限提示，它们仍然出现在应用中以供批准。242 * 在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 连接的会话根本不报告其权限模式，因此 claude.ai 和移动应用可能显示会话不在的权限模式。不匹配仅影响标签。Claude Code 从会话的实际权限模式生成权限提示，它们仍然出现在应用中以供批准。

333 333

334* **计划**：所有计划。334* **计划**：所有计划。

335* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭该功能。335* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭该功能。

336* **模型**：在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，需要 Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 [Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本以及 Fable 模型。较旧的模型（包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型）在任何提供商上均不受支持。336* **模型**：在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，需要 Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本、Haiku 5.5，或 [Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型。较旧的模型（包括 Sonnet 4.5、Opus 4.5、Haiku 4.5 和 claude-3 模型）在任何提供商上均不受支持。

337* **提供商**：在 Anthropic API、Claude Platform on AWS、Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 Claude apps gateway 会话中默认可用。337* **提供商**：在 Anthropic API、Claude Platform on AWS、Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 Claude apps gateway 会话中默认可用。

338 338

339如果 Claude Code 报告自动模式不可用，请首先检查这些要求，以及是否有任何设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭了自动模式，或者服务器可能拒绝了您账户的自动模式。收到上述任一答复的会话会在会话结束前一直保持自动模式关闭，因此请稍后启动新会话。339如果 Claude Code 报告自动模式不可用，请首先检查这些要求，以及是否有任何设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭了自动模式，或者服务器可能拒绝了您账户的自动模式。收到上述任一答复的会话会在会话结束前一直保持自动模式关闭，因此请稍后启动新会话。

348 348

349在 [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 apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，自动模式默认可用。当没有其他内容设置权限模式时，在该部分表格所列的版本上，它也是[内置初始权限模式](#which-mode-a-session-starts-in)。要自行选择初始权限模式，请按照[以不同的权限模式启动](#start-in-a-different-mode)中的说明设置 `permissions.defaultMode`，或从 VS Code 扩展的模式指示器中选择权限模式。349在 [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 apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，自动模式默认可用。当没有其他内容设置权限模式时，在该部分表格所列的版本上，它也是[内置初始权限模式](#which-mode-a-session-starts-in)。要自行选择初始权限模式，请按照[以不同的权限模式启动](#start-in-a-different-mode)中的说明设置 `permissions.defaultMode`，或从 VS Code 扩展的模式指示器中选择权限模式。

350 350

351在这些提供商上，仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本以及 Fable 模型。在任何其他模型上，会话将改为以 Manual 模式启动。351在这些提供商上，仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型。在任何其他模型上，会话将改为以 Manual 模式启动。在这些提供商上将自动模式与 Haiku 5.5 一起使用需要 Claude Code v2.1.293 或更高版本。

352 352

353要阻止开发者使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会将 `auto` 从 `Shift+Tab` 循环中移除，并且使用 `--permission-mode auto` 启动的会话将改为以 Manual 模式启动。当该设置从[管理员部署的来源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达一个已在自动模式下运行的会话时，该会话会退出自动模式，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，正在运行的会话会保持自动模式直到会话结束。353要阻止开发者使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会将 `auto` 从 `Shift+Tab` 循环中移除，并且使用 `--permission-mode auto` 启动的会话将改为以 Manual 模式启动。当该设置从[管理员部署的来源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达一个已在自动模式下运行的会话时，该会话会退出自动模式，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，正在运行的会话会保持自动模式直到会话结束。

354 354

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

Details

14 缓存的组织方式14 缓存的组织方式

15</h2>15</h2>

16 16

17每次在 Claude Code 中发送消息时，它都会发出一个新的 API 请求。模型在请求之间不会记住任何内容，因此 Claude Code 会重新发送完整的上下文：系统提示、你的项目上下文、所有之前的消息和工具结果，以及你的新消息。新内容被附加在末尾，这意味着每个请求的大部分内容与前一个请求相同。Prompt caching 是 API 避免重新处理未更改部分的方式。17每次在 Claude Code 中发送消息时，它都会发出一个新的 API 请求。模型在请求之间不会记住任何内容，因此 Claude Code 会重新发送完整的上下文：系统提示词、您的项目上下文、所有之前的消息和工具结果，以及您的新消息。新内容被附加在末尾，这意味着每个请求的大部分内容与前一个请求相同。提示缓存是 API 避免重新处理未更改部分的方式。

18 18

19API 通过将每个请求的开始部分（称为前缀）与最近处理的内容进行匹配来进行缓存。在正常的回合中，前缀是整个前一个请求，只有最新的交互是新的。匹配是精确的，因此前缀中任何地方的更改都会重新计算其后的所有内容。没有按文件或按段的缓存。有关底层机制，请参阅 API 参考中的 [how prompt caching works](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)。19API 通过将每个请求的开始部分（称为前缀）与最近处理的内容进行匹配来进行缓存。在正常的轮次中，前缀是整个前一个请求，只有最新的交互是新的。匹配是精确的，因此前缀中任何地方的更改都会重新计算其后的所有内容。没有按文件或按段的缓存。有关底层机制，请参阅 API 参考中的[提示缓存的工作原理](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)。

20 20

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="Four turns shown as growing horizontal bars. Each turn's request contains everything from the previous turn plus the latest exchange appended at the end. On turns two and three, the unchanged prefix is read from cache and only the new exchange is processed. On turn four, the system prompt changed, so the prefix no longer matches and the entire request is reprocessed and written." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四个轮次显示为逐渐增长的水平条。每个轮次的请求包含上一轮次的所有内容，并在末尾附加最新的交互。在第二轮和第三轮中，未更改的前缀从缓存中读取，只有新的交互被处理。在第四轮中，系统提示词发生了更改，因此前缀不再匹配，整个请求被重新处理并写入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="Four turns shown as growing horizontal bars. Each turn's request contains everything from the previous turn plus the latest exchange appended at the end. On turns two and three, the unchanged prefix is read from cache and only the new exchange is processed. On turn four, the system prompt changed, so the prefix no longer matches and the entire request is reprocessed and written." width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四个轮次显示为逐渐增长的水平条。每个轮次的请求包含上一轮次的所有内容，并在末尾附加最新的交互。在第二轮和第三轮中，未更改的前缀从缓存中读取，只有新的交互被处理。在第四轮中，系统提示词发生了更改，因此前缀不再匹配，整个请求被重新处理并写入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24

~~25为了充分利用前缀匹配，Claude Code 对每个请求进行排序，使得在回合之间很少更改的内容首先出现：~~25为了充分利用前缀匹配，Claude Code 对每个请求进行排序，使得在轮次之间很少更改的内容首先出现：

26 26

~~27| Layer | Content | Changes when |~~27| 层 | 内容 | 何时更改 |

28| - | - | - |28| - | - | - |

~~31| Conversation | Your messages, Claude's responses, tool results | Every turn |~~31| 对话 | 您的消息、Claude 的回复、工具结果 | 每个轮次 |

32 32

33对对话层的更改会使系统提示和项目上下文保持缓存。对系统提示的更改会使所有内容失效，因为所有后续内容现在位于不同的前缀后面。第三列给出了常见的触发器，而不是详尽的列表，下面的部分涵盖了完整的集合。33对对话层的更改会使系统提示词和项目上下文保持缓存。对系统提示词的更改会使所有内容失效，因为所有后续内容现在位于不同的前缀后面。第三列给出了常见的触发条件，而不是详尽的列表，下面的部分涵盖了完整的集合。

34 34

35前缀匹配规则解释了本页上的大多数行为。例如，[Plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 和 [skill loading](/docs/zh-CN/skills) 将其指令作为对话消息附加，因此缓存的前缀保持完整。35前缀匹配规则解释了本页上的大多数行为。例如，[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)和 [skill 加载](/docs/zh-CN/skills)将其指令作为对话消息附加，因此缓存的前缀保持完整。

36 36

~~37两个设置不在层表中出现，但仍然影响缓存的内容：~~37有两个设置不在层表中出现，但仍然影响缓存的内容：

38 38

~~39* **Model**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的 [Switching models](#switching-models)。~~39* **模型**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的[切换模型](#switching-models)。

40* **Effort level**：在大多数模型上，每个努力级别都有自己的缓存，因此在会话中途更改努力级别会重新计算整个请求。在具有 API 密钥或 Claude 订阅的 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上，缓存默认保持完整。请参阅下面的 [Changing effort level](#changing-effort-level)。40* **effort 级别**：在大多数模型上，每个 effort 级别都有自己的缓存，因此在会话中途更改 effort 级别会重新计算整个请求。在使用 API 密钥或 Claude 订阅的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，缓存默认保持完整。请参阅下面的[更改 effort 级别](#changing-effort-level)。

41 41

42<Tip>42<Tip>

~~43 在会话顶部选择你的模型和努力级别，然后在任务之间的自然中断处保存 `/compact`。你在任务中途进行的更改越少，缓存命中率就越高。~~43 在会话开始时选择您的模型和 effort 级别，然后将 `/compact` 留到任务之间的自然间歇时使用。在任务中途进行的更改越少，缓存命中率就越高。

44</Tip>44</Tip>

45 45

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

47 缓存的位置47 缓存的位置

48</h3>48</h3>

49 49

~~50缓存发生在服务器端，在为你的模型提供服务的任何基础设施中。位置取决于你的身份验证方式：~~50缓存发生在服务器端，在为您的模型提供服务的基础设施中。具体位置取决于您的身份验证方式：

51 51

52* **API key、Claude subscription 或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)**：缓存位于 Anthropic 的基础设施中，通过 [Claude API](https://platform.claude.com/docs) 访问52* **API 密钥、Claude 订阅或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)**：缓存位于 Anthropic 的基础设施中，通过 [Claude API](https://platform.claude.com/docs) 访问

~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：缓存位于你的云提供商的服务基础设施中~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：缓存位于您的云提供商的服务基础设施中

54* **Microsoft Foundry**：取决于部署的 [hosting option](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)。在 Azure 上托管的部署在 Azure 基础设施上提供；在 Anthropic 上托管的部署在 Anthropic 的基础设施上提供54* **Microsoft Foundry**：取决于部署的[托管选项](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)。Hosted on Azure 部署在 Azure 基础设施上提供服务；Hosted on Anthropic 部署在 Anthropic 的基础设施上提供服务

~~55* **Custom `ANTHROPIC_BASE_URL` 或 [LLM gateway](/docs/zh-CN/llm-gateway)**：缓存位于你的请求被转发的地方，缓存是否有效取决于网关~~55* **自定义 `ANTHROPIC_BASE_URL` 或 [LLM 网关](/docs/zh-CN/llm-gateway)**：缓存位于您的请求被转发到的地方，缓存是否有效取决于网关

56 56

57Claude Code 还在对话中途附加系统上下文，例如文件更改通知，并在所有提供商和连接上标记该块以进行缓存，除非你设置了 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)，在这种情况下该块被发送为未缓存。57Claude Code 还会在对话中途附加系统上下文，例如文件更改通知，并在所有提供商和连接上标记该块以进行缓存，除非您设置了 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)，在这种情况下该块将以未缓存的方式发送。

58 58

59在提供商自己的端点、Amazon Bedrock 及其 [Mantle endpoint](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，缓存该块的方式与 Claude API 相同。59在提供商自己的端点上，Amazon Bedrock 及其 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)、Google Cloud 的 Agent Platform 和 Microsoft Foundry 缓存该块的方式与 Claude API 相同。

60 60

61当你的请求通过 [LLM gateway](/docs/zh-CN/llm-gateway)、自定义 `ANTHROPIC_BASE_URL` 或云提供商基础 URL 覆盖（例如 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/zh-CN/env-vars)）时，缓存的内容取决于网关如何处理 Claude Code 发送的 [`cache_control` markers](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)：61当您的请求通过 [LLM 网关](/docs/zh-CN/llm-gateway)、自定义 `ANTHROPIC_BASE_URL` 或云提供商基础 URL 覆盖（例如 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/zh-CN/env-vars)）时，缓存的内容取决于网关如何处理 Claude Code 发送的 [`cache_control` 标记](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)：

62 62

~~63* **原样转发它们**：该块和你的对话缓存方式与在提供商自己的端点上相同。~~63* **原样转发标记**：该块和您的对话的缓存方式与在提供商自己的端点上相同。

64* **使用命名 `cache_control` 的 `400` 错误拒绝标记的请求**：Claude Code 重新发送请求，将标记从块移到你的最后一条对话消息上，并在对话的其余部分保持在那里。该块作为未缓存的输入计费；你的对话保持缓存。64* **以指明 `cache_control` 的 `400` 错误拒绝带标记的请求**：Claude Code 会重新发送请求，将标记从该块移到您的最后一条对话消息上，并在对话的其余部分保持在那里。该块作为未缓存的输入计费；您的对话保持缓存。

65* **在返回成功时删除标记**：你的整个对话历史在每个回合上都作为未缓存的输入计费。将块形式的系统内容转换为纯字符串的网关以相同的方式删除标记。65* **删除标记但返回成功**：您的整个对话历史在每个轮次上都作为未缓存的输入计费。将块形式的系统内容转换为纯字符串的网关也会以相同的方式丢弃标记。

66 66

67有关每个提供商存储和处理的内容，请参阅 [data usage](/docs/zh-CN/data-usage)。无论缓存位于何处，条目在不活动期间后过期，下面的 [Cache lifetime](#cache-lifetime) 涵盖了 TTL 以及如何延长它。67有关每个提供商存储和处理的内容，请参阅[数据使用](/docs/zh-CN/data-usage)。无论缓存位于何处，条目都会在一段时间不活动后过期，下面的[缓存生命周期](#cache-lifetime)涵盖了 TTL 以及如何延长它。

68 68

69<h2 id="actions-that-invalidate-the-cache">69<h2 id="actions-that-invalidate-the-cache">

70 使缓存失效的操作70 使缓存失效的操作

71</h2>71</h2>

72 72

73这些操作可能导致下一个请求缓存未命中。您会看到一次速度较慢、成本更高的回合，之后新的前缀会被缓存。一旦您了解它们的成本，大多数操作都可以在任务中途避免。模型切换可能看起来没有成本，直到您注意到随后的速度较慢的回合。73这些操作可能导致下一个请求部分或全部缓存未命中。您会看到一次速度较慢、成本更高的轮次，之后新的前缀会被缓存。一旦您了解它们的成本，大多数操作都可以在任务中途避免。模型切换可能看起来没有成本，直到您注意到随后速度较慢的轮次。

74 74

75* [切换模型](#switching-models)75* [切换模型](#switching-models)

~~76* [更改工作量级别](#changing-effort-level)~~76* [更改 effort 级别](#changing-effort-level)

77* [启用快速模式](#turning-on-fast-mode)77* [启用快速模式](#turning-on-fast-mode)

78* [连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)78* [连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)

79* [启用或禁用插件](#enabling-or-disabling-a-plugin)79* [启用或禁用插件](#enabling-or-disabling-a-plugin)

88 88

89每个模型都有自己的缓存。使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 切换意味着下一个请求会读取整个对话历史记录而没有缓存命中，即使内容相同。89每个模型都有自己的缓存。使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 切换意味着下一个请求会读取整个对话历史记录而没有缓存命中，即使内容相同。

90 90

91当您在终端运行 `/model` 时，Claude Code 会要求您确认切换，但仅限于缓存仍然温暖且新模型不是产生最后一个响应的模型时。缓存在 Claude Code 在此对话中最后一次发送请求或 Claude 最后一次响应后的一个[缓存 TTL](#cache-lifetime) 内保持温暖。一旦该时间过去，缓存就会过期，因此 Claude Code 会在不询问的情况下进行切换。91当您在终端运行 `/model` 时，Claude Code 会要求您确认切换，但仅限于缓存仍然温暖且新模型不是产生最后一个回复的模型时。缓存在 Claude Code 在此对话中最后一次发送请求或 Claude 最后一次回复后的一个[缓存 TTL](#cache-lifetime) 内保持温暖。一旦该时间过去，缓存就会过期，因此 Claude Code 会在不询问的情况下进行切换。

92 92

93在 v2.1.238 之前，Claude Code 不检查缓存 TTL，即使在缓存过期后也会询问。93在 v2.1.238 之前，Claude Code 不检查缓存 TTL，即使在缓存过期后也会询问。

94 94

95您也可以通过 [PreModelSwitch hook](/docs/zh-CN/hooks#premodelswitch-decision-control) 要求此确认或跳过它。95您也可以通过 [PreModelSwitch hook](/docs/zh-CN/hooks#premodelswitch-decision-control) 要求此确认或跳过它。

96 96

97[`opusplan` 模型设置](/docs/zh-CN/model-config#opusplan-model-setting)在计划模式下解析为 Opus，在执行期间解析为 Sonnet，因此每个计划模式切换都是一个模型切换并启动新的缓存。97[`opusplan` 模型设置](/docs/zh-CN/model-config#opusplan-model-setting)在计划模式下解析为 Opus，在执行期间解析为 Sonnet，因此每次切换计划模式都是一次模型切换并启动新的缓存。

98 98

99[Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上的自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)也是一个模型切换。当安全分类器在具有回退模型的类别中标记请求时，Claude Code 会在该模型上重新运行请求，会话继续进行。99Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上的[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)也是一次模型切换。当安全分类器将某个请求标记为属于具有备用模型的类别时，Claude Code 会在该模型上重新运行请求，会话也会在该模型上继续。

100 100

101当技能或命令的 frontmatter 命名一个[`model`](/docs/zh-CN/skills#frontmatter-reference)不同于会话当前模型的模型时，该回合也是一个模型切换：下一个请求读取整个对话历史记录而没有缓存命中。会话模型在您的下一个提示时恢复。`context: fork` 技能设置[分叉子代理的模型](/docs/zh-CN/skills#run-skills-in-a-subagent)。101当 skill 或命令的 frontmatter 指定的 [`model`](/docs/zh-CN/skills#frontmatter-reference) 不同于会话当前模型时，该轮次也是一次模型切换：下一个请求读取整个对话历史记录而没有缓存命中。会话模型在您的下一个提示词时恢复。`context: fork` skill 则设置的是[分叉子代理的模型](/docs/zh-CN/skills#run-skills-in-a-subagent)。

102 102

103<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

104 更改工作量级别104 更改 effort 级别

105</h3>105</h3>

106 106

107在大多数模型上，在会话中途更改[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。107在大多数模型上，在会话中途更改 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。

108 108

109在 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上使用 API 密钥或 Claude 订阅时，更改工作量会保持缓存，Claude Code 会在不询问的情况下应用新级别。这不适用于 Amazon Bedrock、Google Cloud 的 Agent Platform 或[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)，或当您设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置时。109在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上使用 API 密钥或 Claude 订阅时，更改 effort 会保持缓存，Claude Code 会在不询问的情况下应用新级别。这不适用于 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway)，也不适用于您设置了 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置的情况。

110 110

111在 v2.1.260 之前，在 Fable 5.1 上使用 API 密钥或 Claude 订阅更改工作量也会使缓存失效。111在 v2.1.260 之前，在 Fable 5.1 上使用 API 密钥或 Claude 订阅更改 effort 也会使缓存失效。

112 112

113<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

114 启用快速模式114 启用快速模式

115</h3>115</h3>

116 116

117启用[快速模式](/docs/zh-CN/fast-mode)会添加一个请求标头，该标头是缓存键的一部分，因此 Claude Code 发送的启用快速模式的第一个请求会读取整个对话历史记录而没有缓存命中。Claude Code 在回合开始时设置该标头一次，并为整个回合保持它，因此当您在 Claude 工作时启用快速模式时，标头的缓存未命中发生在您下一个回合的第一个请求上。这些未缓存的输入令牌按[快速模式费率](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)计费，这就是为什么在会话开始时启用它的成本比在长会话深处启用它的成本要低。如果您当前的模型不支持快速模式，启用快速模式也会[切换您的模型](#switching-models)，该切换从运行回合中的下一个请求开始启动新的缓存。117启用[快速模式](/docs/zh-CN/fast-mode)会添加一个请求标头，该标头是缓存键的一部分，因此 Claude Code 在启用快速模式后发送的第一个请求会读取整个对话历史记录而没有缓存命中。Claude Code 在轮次开始时设置该标头一次，并在整个轮次中保持它，因此当您在 Claude 工作时启用快速模式，标头导致的缓存未命中会发生在您下一轮次的第一个请求上。这些未缓存的输入 token 按[快速模式费率](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)计费，这就是为什么在会话开始时启用它比在长会话的后段启用它成本更低。如果您当前的模型不支持快速模式，启用快速模式也会[切换您的模型](#switching-models)，该切换本身会从当前运行轮次中的下一个请求开始启动新的缓存。

118 118

119成本每个对话应用一次。在第一个快速模式回合之后，Claude Code 继续发送标头，仅改变请求的速度设置，这不是缓存键的一部分。关闭快速模式、[速率限制后自动回退到标准速度](/docs/zh-CN/fast-mode#handle-rate-limits)以及稍后重新启用它都会保持缓存。如果您在会话中途[用完使用额度](/docs/zh-CN/fast-mode#handle-rate-limits)，Claude Code 会以相同的方式在标准速度下重试每个被拒绝的快速模式请求，因此此回退也会保持缓存。`/clear` 和 `/compact` 会重置此设置，因为它们无论如何都会在这些点重建缓存。119该成本每个对话只产生一次。在第一个快速模式轮次之后，Claude Code 会继续发送该标头，仅改变请求的速度设置，而速度设置不是缓存键的一部分。关闭快速模式、[速率限制后自动回退到标准速度](/docs/zh-CN/fast-mode#handle-rate-limits)以及稍后重新启用它都会保持缓存。如果您在会话中途[用完使用额度](/docs/zh-CN/fast-mode#handle-rate-limits)，Claude Code 会以相同的方式在标准速度下重试每个被拒绝的快速模式请求，因此此回退也会保持缓存。`/clear` 和 `/compact` 会重置此状态，因为它们无论如何都会在这些时间点重建缓存。

120 120

121<h3 id="connecting-or-removing-an-mcp-server">121<h3 id="connecting-or-removing-an-mcp-server">

122 连接或移除 MCP 服务器122 连接或移除 MCP 服务器

123</h3>123</h3>

124 124

125工具定义位于系统提示层，因此当请求中的工具定义集在回合之间发生变化时，缓存会失效。切换[顾问工具](/docs/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，因此启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/docs/zh-CN/mcp)更改是否执行此操作取决于是否[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)延迟会话的 MCP 工具，这是支持的模型上的默认设置：125工具定义位于系统提示词层，因此当请求中的工具定义集在轮次之间发生变化时，缓存会失效。切换[顾问工具](/docs/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，因此启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/docs/zh-CN/mcp)的更改是否会导致缓存失效，取决于[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)是否延迟加载会话的 MCP 工具，这是受支持模型上的默认行为：

126 126

127* **工具延迟**：Claude Code 为整个对话保持来自对话第一个请求的工具列表，因此服务器在会话中途连接或断开连接不会干扰已缓存的任何内容。在第一个请求后完成连接的服务器提供其工具作为 Claude 按需加载的延迟定义。127* **工具延迟加载**：Claude Code 在整个对话中保持对话第一个请求中的工具列表，因此服务器在会话中途连接或断开连接不会干扰任何已缓存的内容。在第一个请求之后才完成连接的服务器会将其工具作为延迟定义提供，由 Claude 按需加载。

128* **工具加载到前缀中**：添加定义会使缓存失效，移除定义也会。这适用于当[工具搜索低于其 `auto` 阈值、被禁用或不可用](/docs/zh-CN/mcp#configure-tool-search)时，例如在 Google Cloud 的 Agent Platform 模型早于 Claude 4.5 代、具有自定义 `ANTHROPIC_BASE_URL` 网关或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)一旦 Claude Code 检测到部署拒绝工具搜索时。128* **工具预先加载**：添加定义会使缓存失效，有意移除定义也会。这适用于[工具搜索低于其 `auto` 阈值、被禁用或不可用](/docs/zh-CN/mcp#configure-tool-search)的情况，例如在 Google Cloud 的 Agent Platform 上使用早于 Claude 4.5 代的模型、使用自定义 `ANTHROPIC_BASE_URL` 网关，或在 Microsoft Foundry [托管于 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上且 Claude Code 检测到该部署拒绝工具搜索时。

129 129

130没有工具搜索，中途服务器更改是否使缓存失效取决于更改的内容。对于每个更改，此表给出缓存是否保持以及下一个请求中工具定义发生的情况。130没有工具搜索时，会话中途的服务器更改是否使缓存失效取决于更改的内容。对于每种更改，下表给出缓存是否保持以及下一个请求中工具定义的变化情况。

131 131

132| 中途更改 | 缓存 | 下一个请求中的工具定义 |132| 会话中途的更改 | 缓存 | 下一个请求中的工具定义 |

133| - | - | - |133| - | - | - |

134| 服务器连接，或[动态工具更新](/docs/zh-CN/mcp#dynamic-tool-updates)添加工具 | 失效 | 添加新定义 |134| 服务器连接，或[动态工具更新](/docs/zh-CN/mcp#dynamic-tool-updates)添加工具 | 失效 | 添加新定义 |

135| 服务器在您没有采取任何操作的情况下断开连接，例如 stdio 服务器的进程退出 | 保持 | 服务器的定义保持不变。对其工具之一的调用返回错误而不是运行 |135| 服务器在您未执行任何操作的情况下断开，例如 stdio 服务器的进程退出 | 保持 | 服务器的定义保持不变。对其工具的调用会返回错误而不是运行 |

136| 远程服务器在连接断开后[自动重新连接](/docs/zh-CN/mcp#automatic-reconnection) | 保持，除非在服务器重新连接时发送的请求添加了 `WaitForMcpServers` 工具，这会使缓存失效一次 | 服务器的定义保持不变。在服务器重新连接时发送的请求可以在对话尚未列出时添加 `WaitForMcpServers`，然后该工具对对话的其余部分保持列出 |136| 远程服务器在连接断开后[自动重新连接](/docs/zh-CN/mcp#automatic-reconnection) | 保持，除非在服务器重新连接期间发送的请求添加了 `WaitForMcpServers` 工具，这会使缓存失效一次 | 服务器的定义保持不变。如果对话尚未列出 `WaitForMcpServers`，在服务器重新连接期间发送的请求可能会添加它，之后该工具会在对话的其余部分保持列出 |

137| 您故意移除工具，例如使用[拒绝规则](#denying-an-entire-tool)或通过在 `/mcp` 中禁用其服务器 | 失效 | 定义被移除 |137| 您有意移除工具，例如使用[拒绝规则](#denying-an-entire-tool)或在 `/mcp` 中禁用其服务器 | 失效 | 定义被移除 |

138 138

139当您恢复其工具加载到前缀中的对话时，其中一个 MCP 服务器仍然可以在第一个请求发出时连接。如果记录的对话记录了该服务器的工具定义，该请求会按记录包含它们，因此当服务器以相同的工具完成连接时它不会改变。139当您恢复一个工具加载到前缀中的对话时，在第一个请求发出时，其中某个 MCP 服务器可能仍在连接中。如果会话记录中记录了该服务器的工具定义，该请求会按记录包含它们，因此当服务器以相同的工具完成连接时，请求不会发生变化。

140 140

141编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，这是服务器连接或断开连接的时候。141编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，届时服务器才会连接或断开连接。

142 142

143<h3 id="enabling-or-disabling-a-plugin">143<h3 id="enabling-or-disabling-a-plugin">

144 启用或禁用插件144 启用或禁用插件

145</h3>145</h3>

146 146

147当您启用或禁用[插件](/docs/zh-CN/plugins/overview)时，更改的成本取决于插件提供的组件类型。下面的情况涵盖每个组件类型、Claude Code 何时应用更改以及在同一会话中再次禁用插件时发生的情况。147当您启用或禁用[插件](/docs/zh-CN/plugins/overview)时，更改的成本取决于插件提供的组件类型。下面的情况涵盖每种组件类型、Claude Code 何时应用更改，以及在同一会话中再次禁用插件时会发生什么。

148 148

149<h4 id="plugin-components-that-keep-the-cache">149<h4 id="plugin-components-that-keep-the-cache">

150 保持缓存的插件组件150 保持缓存的插件组件

151</h4>151</h4>

152 152

153Claude Code 永远不会为插件的技能、命令、代理、hooks、监视器或主题使缓存失效。它在现有对话之后附加其内容，因此下一个请求为该内容付费，并仍然从缓存中读取其之前的所有内容。153Claude Code 永远不会因插件的 skill、命令、Agent、hook、监视器或主题而使缓存失效。它会将这些内容附加在现有对话之后，因此下一个请求只需为这些内容付费，其之前的所有内容仍从缓存中读取。

154 154

155<h4 id="plugins-that-provide-mcp-servers">155<h4 id="plugins-that-provide-mcp-servers">

156 提供 MCP 服务器的插件156 提供 MCP 服务器的插件

157</h4>157</h4>

158 158

159当您启用或禁用提供[MCP 服务器](/docs/zh-CN/plugins/components#mcp-servers)的插件时，Claude Code 遵循与[连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)相同的规则。159当您启用或禁用提供 [MCP 服务器](/docs/zh-CN/plugins/components#mcp-servers)的插件时，Claude Code 遵循与[连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)相同的规则。

160 160

161<h4 id="code-intelligence-plugins">161<h4 id="code-intelligence-plugins">

162 代码智能插件162 代码智能插件

168 插件更改何时应用168 插件更改何时应用

169</h4>169</h4>

170 170

171您在 `/plugin` 菜单中所做的更改会通过 [`/reload-plugins`](/docs/zh-CN/plugins/cli-reference#reload-plugins) 进行，Claude Code 在您关闭菜单时为您运行。您需要付费，无论是附加公告还是完整重新读取，都在更改应用后的第一个回合。Claude Code 也可以自行应用更改：171您在 `/plugin` 菜单中所做的更改会通过 [`/reload-plugins`](/docs/zh-CN/plugins/cli-reference#reload-plugins) 应用，Claude Code 会在您关闭菜单时为您运行它。无论是附加公告还是完整重新读取，您都会在更改应用后的第一个轮次中支付该成本。Claude Code 也可以自行应用更改：

172 172

173* 对于具有 `command` 源的插件，Claude Code [可以自行重新加载插件](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)。173* 对于具有 `command` 源的插件，Claude Code [可以自行重新加载插件](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)。

174* 当您[从 `/plugin` 界面安装插件](/docs/zh-CN/plugins/install#install-a-plugin)时，Claude Code 可以在安装期间激活它。安装摘要会告诉您它是否这样做了。174* 当您[从 `/plugin` 界面安装插件](/docs/zh-CN/plugins/install#install-a-plugin)时，Claude Code 可以在安装期间激活它。安装摘要会告诉您是否已激活。

175* 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)时，Claude Code 会在移动过程中应用新目录的设置启用的插件，而不会出现保持 `/reload-plugins` 的完整重新读取警告。175* 当您在 v2.1.246 或更高版本上[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)时，Claude Code 会在移动过程中应用新目录的设置所启用的插件，而不会出现会搁置 `/reload-plugins` 的完整重新读取警告。

176* 在交互式会话中，当您在使用 `--plugin-dir` 传递的[插件文件夹](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session)中添加或移除插件时，更改会立即应用。如果应用它会触发完整重新读取，Claude Code 会保持更改并显示通知以运行 `/reload-plugins`。需要 Claude Code v2.1.265 或更高版本。176* 在交互式会话中，当您在使用 `--plugin-dir` 传入的[插件文件夹](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session)中添加或移除插件时，更改会立即应用。如果应用它会触发完整重新读取，Claude Code 会搁置该更改，并显示一条通知提示运行 `/reload-plugins`。需要 Claude Code v2.1.265 或更高版本。

177 177

178当 `/reload-plugins` 运行且重新加载会触发完整重新读取时，Claude Code 会显示警告并不应用重新加载。运行 `/reload-plugins --force` 以无论如何应用它。178当 `/reload-plugins` 运行且重新加载会触发完整重新读取时，Claude Code 会显示警告且不应用重新加载。运行 `/reload-plugins --force` 可强制应用。

179 179

180`/reload-plugins` 也在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 和[非交互式模式](/docs/zh-CN/headless)与 `-p`，当您直接将其输入到会话中时。需要 Claude Code v2.1.260 或更高版本。180当您直接在会话中输入 `/reload-plugins` 时，它也可以在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 以及使用 `-p` 的[非交互模式](/docs/zh-CN/headless)。需要 Claude Code v2.1.260 或更高版本。

181 181

182在这些会话中，重新加载应用除了插件 MCP 服务器更改之外的所有内容，这些[在您的下一个会话中生效](/docs/zh-CN/plugins/cli-reference#reload-plugins)，因此永远不会在会话中途成本完整重新读取。182在这些会话中，重新加载会应用除插件 MCP 服务器更改之外的所有内容，插件 MCP 服务器更改会[在您的下一个会话中生效](/docs/zh-CN/plugins/cli-reference#reload-plugins)，因此永远不会在会话中途导致完整重新读取的成本。

183 183

184<h4 id="plugins-you-enable-and-then-disable-in-one-session">184<h4 id="plugins-you-enable-and-then-disable-in-one-session">

185 您在一个会话中启用然后禁用的插件185 您在一个会话中启用然后禁用的插件

186</h4>186</h4>

187 187

188当您禁用您在会话中较早启用的插件时，Claude Code 会恢复之前的请求形状。如果该前缀仍在其[缓存生命周期](#cache-lifetime)内，下一个请求会读取较旧的缓存条目而不是重建。188当您禁用在会话中较早启用的插件时，Claude Code 会恢复之前的请求形状。如果该前缀仍在其[缓存生命周期](#cache-lifetime)内，下一个请求会读取较旧的缓存条目而不是重建。

189 189

190<h3 id="denying-an-entire-tool">190<h3 id="denying-an-entire-tool">

191 拒绝整个工具191 拒绝整个工具

192</h3>192</h3>

193 193

194如果您添加一个裸工具名称如 `Bash` 或 `WebFetch` 作为[拒绝规则](/docs/zh-CN/permissions#manage-permissions)，Claude 无法从您的下一个请求开始调用该工具，无论您是通过 `/permissions` 添加规则还是通过[直接编辑设置文件](/docs/zh-CN/settings#when-edits-take-effect)。这包括您在回合中途通过 `/permissions` 添加的规则。194如果您将 `Bash` 或 `WebFetch` 这样的裸工具名称添加为[拒绝规则](/docs/zh-CN/permissions#manage-permissions)，从您的下一个请求开始，Claude 将无法调用该工具，无论您是通过 `/permissions` 添加规则，还是[直接编辑设置文件](/docs/zh-CN/settings#when-edits-take-effect)。这也包括您在轮次中途通过 `/permissions` 添加的规则。

195 195

196当[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)处于活动状态时，这是支持的模型上的默认设置，请求的工具定义不会改变，缓存的前缀会存活。当工具搜索不可用或被禁用时，Claude Code 会从下一个请求中移除定义，这会使缓存失效，稍后移除规则也会。196当[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)处于活动状态时（这是受支持模型上的默认行为），请求的工具定义不会改变，缓存的前缀会保留。当工具搜索不可用或被禁用时，Claude Code 会从下一个请求中移除该定义，这会使缓存失效，之后移除该规则也会。

197 197

198只有在工具名称位置匹配的拒绝规则才会以这种方式阻止工具：裸工具名称、等效的 `Bash(*)` 形式或[工具名称 glob](/docs/zh-CN/permissions#tool-name-wildcards) 如 `"*"`。匹配仅 MCP 工具的 glob，例如 `"mcp__*"`，以相同的方式阻止这些工具。作用域拒绝规则如 `Bash(rm *)`，以及所有允许和询问规则，不会改变 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。198只有在工具名称位置匹配的拒绝规则才会以这种方式阻止工具：裸工具名称、等效的 `Bash(*)` 形式，或 `"*"` 这样的[工具名称 glob](/docs/zh-CN/permissions#tool-name-wildcards)。仅匹配 MCP 工具的 glob（例如 `"mcp__*"`）会以相同的方式阻止这些工具。`Bash(rm *)` 这样的限定范围拒绝规则，以及所有允许和询问规则，不会改变 Claude 看到的工具。Claude Code 会在 Claude 尝试调用时检查它们，保持前缀完整。

199 199

200<h3 id="compacting-the-conversation">200<h3 id="compacting-the-conversation">

201 压缩对话201 压缩对话

202</h3>202</h3>

203 203

204[压缩](/docs/zh-CN/context-window#what-survives-compaction)用摘要替换您的消息历史记录。根据设计，这会使对话层失效，因为下一个请求有一个新的、更短的历史记录，不与旧的共享前缀。Claude Code 重用系统提示层，除非对话是[在保持会以其他方式改变的系统提示的同时恢复的](#resuming-a-session)；在这种情况下，第一次压缩会切换到当前提示，该层重建一次。它从磁盘重新加载项目上下文，仅当 CLAUDE.md 和内存自会话开始以来未改变时才缓存命中。204[压缩](/docs/zh-CN/context-window#what-survives-compaction)会用摘要替换您的消息历史记录。按照设计，这会使对话层失效，因为下一个请求拥有一个新的、更短的历史记录，与旧的历史记录不共享前缀。Claude Code 会重用系统提示词层，除非该对话是[在保留了原本会改变的系统提示词的情况下恢复的](#resuming-a-session)；在这种情况下，第一次压缩会切换到当前的提示词，该层会重建一次。它会从磁盘重新加载项目上下文，仅当 CLAUDE.md 和记忆自会话开始以来未改变时才会命中缓存。

205 205

206为了生成摘要，Claude Code 发送一个单独的请求，其系统提示、工具和历史记录与您的对话相同，加上作为最终用户消息附加的摘要指令。当缓存温暖时，该请求从缓存中读取您的前缀，因此中途 `/compact` 的成本是上下文大小建议的一小部分，并花费大部分时间生成摘要。206为了生成摘要，Claude Code 会发送一个单独的请求，其系统提示词、工具和历史记录与您的对话相同，并附加一条摘要指令作为最后的用户消息。当缓存温暖时，该请求会从缓存中读取您的前缀，因此会话中途的 `/compact` 成本只是上下文大小所暗示成本的一小部分，其大部分时间都花在生成摘要上。

207 207

208在超过[缓存生命周期](#cache-lifetime)的中断后，没有缓存可读，因此摘要请求将重新处理完整历史记录作为未缓存的输入。这就是为什么当您[恢复旧会话](/docs/zh-CN/sessions#resume-from-a-summary)时 `/compact` 成本最高。在温暖和冷的情况下，压缩后的回合仅为更短的摘要重建对话缓存，因此该回合不是缓慢的部分。208在超过[缓存生命周期](#cache-lifetime)的中断之后，已没有缓存可读，因此摘要请求会将完整历史记录作为未缓存的输入重新处理。这就是为什么在您[恢复旧会话](/docs/zh-CN/sessions#resume-from-a-summary)时 `/compact` 的成本最高。无论缓存温暖还是已冷，压缩后的轮次都只需为短得多的摘要重建对话缓存，因此该轮次并不是耗时的部分。

209 209

210<Tip>210<Tip>

211 当您丢弃的上下文是您不再需要的内容时，压缩对您有利。要选择其开销发生的时间，请在工作中的自然中断处（例如任务之间）运行 `/compact`，而不是等待自动压缩在任务中途触发。如果您走上了一条想要完全放弃的路径，[`/rewind`](#rewinding-the-conversation)到较早的回合。重新绕回截断回到已缓存的前缀，而不是像压缩那样构建新的。211 当您丢弃的上下文是您不再需要的内容时，压缩对您有利。要选择其开销发生的时间，请在工作中的自然间歇处（例如任务之间）运行 `/compact`，而不是等待自动压缩在任务中途触发。如果您走上了一条想要完全放弃的路径，请改用 [`/rewind`](#rewinding-the-conversation) 回退到较早的轮次。回退会截断回到一个已缓存的前缀，而不是像压缩那样构建新的前缀。

212</Tip>212</Tip>

213 213

214<h3 id="accumulating-many-images">214<h3 id="accumulating-many-images">

215 积累许多图像215 积累许多图像

216</h3>216</h3>

217 217

218API 限制每个请求可以携带多少图像和 PDF。有关当前数字，请参阅 API 文档中的[请求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也限制请求中图像和 PDF 的总大小，因此大型屏幕截图比小型屏幕截图更快达到限制。218API 限制每个请求可以携带的图像和 PDF 数量。有关当前数值，请参阅 API 文档中的[请求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 还会限制请求中图像和 PDF 的总大小，因此大型屏幕截图会比小型屏幕截图以更少的数量达到限制。

219 219

220当下一个请求会超过任一限制时，Claude Code 会从它发送的内容中移除一批最旧的图像和 PDF，这为更多内容腾出空间，然后才需要再次移除任何内容。Claude 无法再看到移除的图像。如果 Claude 再次需要其中一个，请再次共享它。220当下一个请求会超过任一限制时，Claude Code 会从其发送的内容中移除一批最旧的图像和 PDF，从而为更多内容腾出空间，之后才需要再次移除。Claude 将无法再看到被移除的图像。如果 Claude 再次需要其中某张，请重新分享它。

221 221

222移除图像会改变保存它们的消息，因此下一个请求会从这些消息中最早的开始重新处理对话。因为 Claude Code 一次移除一批，您会看到每批一个较慢的回合，而不是每个新屏幕截图一个。222移除图像会改变包含它们的消息，因此下一个请求会从这些消息中最早的一条开始重新处理对话。由于 Claude Code 每次移除一批，您会看到每批一个较慢的轮次，而不是每张新屏幕截图一个。

223 223

224<h3 id="upgrading-claude-code">224<h3 id="upgrading-claude-code">

225 升级 Claude Code225 升级 Claude Code

226</h3>226</h3>

227 227

228新的 Claude Code 版本通常会更新系统提示或工具定义，因此升级后您启动的第一个对话从顶部构建其缓存。[自动更新](/docs/zh-CN/setup#auto-updates)在后台下载新版本，但在下一次启动时应用它们，从不在会话中途，因此您会看到这是重启后的未缓存第一个回合，而不是会话中的惊喜。设置 `DISABLE_AUTOUPDATER=1` 以控制何时应用升级。228新的 Claude Code 版本通常会更新系统提示词或工具定义，因此升级后您开始的第一个对话会从头构建其缓存。[自动更新](/docs/zh-CN/setup#auto-updates)会在后台下载新版本，但在下一次启动时才应用，从不在会话中途应用，因此您会在重启后看到一个未缓存的首个轮次，而不会在会话中途遇到意外。设置 `DISABLE_AUTOUPDATER=1` 以控制何时应用升级。

229 229

230<Note>230<Note>

231 有关恢复您在升级前启动的对话的成本，请参阅[恢复会话](#resuming-a-session)。231 有关恢复您在升级前开始的对话的成本，请参阅[恢复会话](#resuming-a-session)。

232</Note>232</Note>

233 233

234<h2 id="actions-that-keep-the-cache">234<h2 id="actions-that-keep-the-cache">

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

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="定义您的设置">

149 设置优先级149 设置优先级

150</h3>150</h3>

151 151

152服务器管理的设置和[端点管理的设置](/docs/zh-CN/managed-settings#delivery-mechanisms)都占据 Claude Code [设置层次结构](/docs/zh-CN/settings#settings-precedence)中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数，除了[托管设置优先级的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)。152服务器管理的设置和[端点管理的设置](/docs/zh-CN/managed-settings#delivery-mechanisms)都占据 Claude Code [设置层次结构](/docs/zh-CN/settings#settings-precedence)中的最高层。您在此处设置的键优先于用户自己的设置文件中或 `--settings` 值中的同一键，[托管设置优先级的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)除外。

153 153

154在托管层内，Claude Code 默认使用首先传递至少一个策略键的源，首先检查服务器管理的设置，然后检查端点管理的设置，除了[接下来涵盖的例外键](#per-key-exceptions-across-managed-sources)。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)包含完整的排名、控制键的例外以及适用于每个源的选择加入。154在托管层内，Claude Code 默认使用首先传递至少一个策略键的源，首先检查服务器管理的设置，然后检查端点管理的设置，除了[接下来涵盖的例外键](#per-key-exceptions-across-managed-sources)。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)包含完整的排名、控制键的例外以及适用于每个源的选择加入。

155 155

sessions.md +47 −45

Details

14 恢复会话14 恢复会话

15</h2>15</h2>

16 16

~~17会话在您工作时持续保存到[本地文本记录文件](#export-and-locate-session-data)，因此您可以在退出或运行 `/clear` 后返回到一个会话。使用这些入口点：~~17会话在您工作时持续保存到[本地会话记录文件](#export-and-locate-session-data)，因此您可以在退出或运行 `/clear` 后返回到一个会话。使用这些入口点：

18 18

19| 命令 | 功能 |19| 命令 | 功能 |

20| :- | :- |20| :- | :- |

22| `claude --resume` | 打开[会话选择器](#use-the-session-picker) |22| `claude --resume` | 打开[会话选择器](#use-the-session-picker) |

23| `claude --resume <name>` | 直接恢复命名的会话 |23| `claude --resume <name>` | 直接恢复命名的会话 |

26| `/resume` | 从活跃会话内切换到不同的对话 |26| `/resume` | 从活跃会话内切换到不同的对话 |

27 27

28Claude Code 将使用 [`claude -p`](/docs/zh-CN/headless) 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话排除在会话选择器和 `claude --continue` 之外。您仍然可以通过将其会话 ID 传递给 `claude --resume <session-id>` 来恢复它。使用 `claude --continue` 时，Claude Code 也会跳过[第一个提示是 `/loop` 的会话](#where-the-session-picker-looks)。当您运行 [`claude -p --continue`](/docs/zh-CN/headless#continue-conversations) 时，Claude Code 包括 `-p`、SDK 和 `/loop` 会话。28Claude Code 将使用 [`claude -p`](/docs/zh-CN/headless) 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话排除在会话选择器和 `claude --continue` 之外。您仍然可以通过将其会话 ID 传递给 `claude --resume <session-id>` 来恢复它。使用 `claude --continue` 时，Claude Code 也会跳过[第一个提示词是 `/loop` 的会话](#where-the-session-picker-looks)。当您运行 [`claude -p --continue`](/docs/zh-CN/headless#continue-conversations) 时，Claude Code 包括 `-p`、SDK 和 `/loop` 会话。

29 29

30您可以从任何目录运行 `claude --resume <session-id>`，因此可以恢复在其他地方启动或使用 [`/cd`](/docs/zh-CN/commands) 移动过的会话。Claude Code 按以下顺序查找该 ID：30您可以从任何目录运行 `claude --resume <session-id>`，因此可以恢复在其他地方启动或使用 [`/cd`](/docs/zh-CN/commands) 移动过的会话。Claude Code 按以下顺序查找该 ID：

31 31

42 恢复正在运行的后台会话42 恢复正在运行的后台会话

43</h3>43</h3>

44 44

45当您使用 `claude --resume` 或 `/resume` 恢复的对话属于仍在运行的[后台会话](/docs/zh-CN/agent-view)时，Claude Code 会打开运行中的会话本身。在命令行上使用 `--bg` 时，恢复改为[后台调度](/docs/zh-CN/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 拒绝并告诉您使用 `claude attach <id>` 打开会话，或首先使用 `claude stop <id>` 停止它。45当您使用 `claude --resume` 或 `/resume` 恢复的对话属于仍在运行的[后台会话](/docs/zh-CN/agent-view)时，Claude Code 会打开运行中的会话本身。在命令行上使用 `--bg` 时，恢复改为[后台调度](/docs/zh-CN/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 会拒绝并告诉您使用 `claude attach <id>` 打开会话，或首先使用 `claude stop <id>` 停止它。

46 46

47* **从您的 shell**：`claude --resume <session>` 在同一终端中对该会话运行 [`claude attach`](/docs/zh-CN/agent-view#attach-to-a-session)，而不是加载文本记录本身。您在命令行上传递的提示，如 `claude --resume <session> "check the tests too"`，首先作为其下一轮转到会话，Claude Code 在附加之前打印 `Sent your prompt to the background session (<id>); opening it…`。`claude -p --resume <session> "prompt"` 在终端中输入时执行相同操作，因此 `-p` 不会保持该运行非交互式。47* **从您的 shell**：`claude --resume <session>` 在同一终端中对该会话运行 [`claude attach`](/docs/zh-CN/agent-view#attach-to-a-session)，而不是自行加载会话记录。您在命令行上传递的提示词，如 `claude --resume <session> "check the tests too"`，会首先作为下一轮发送到该会话，Claude Code 在附加之前打印 `Sent your prompt to the background session (<id>); opening it…`。在终端中输入的 `claude -p --resume <session> "prompt"` 执行相同操作，因此 `-p` 不会使该运行保持非交互式。

48 48

~~49 当命令行具有以下任何内容时，Claude Code 不会打开会话：~~49 当命令行包含以下任何内容时，Claude Code 不会打开会话：

50 50

51 * 管道或重定向的输入或输出51 * 管道或重定向的输入或输出

52 * 配置会话的标志，例如 `--permission-mode`、`--model` 或 `--settings`52 * 配置会话的标志，例如 `--permission-mode`、`--model` 或 `--settings`

53 * 读取输出的标志，例如 `--output-format json` 或 `--json-schema`53 * 读取输出的标志，例如 `--output-format json` 或 `--json-schema`

54 * 限制或倒带运行的标志，例如 `--max-turns` 或 `--max-budget-usd`54 * 限制或倒带运行的标志，例如 `--max-turns` 或 `--max-budget-usd`

55 55

56 使用这些中的任何一个，或当[代理视图被关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，Claude Code 不发送任何内容并以状态 1 退出，打印会话在后台运行以及打开它的 `claude attach <id>` 命令，或当它无法确定 ID 时告诉您在 `claude agents` 中找到它。添加 `--fork-session` 以恢复对话的副本。要在您自己的会话中继续对话本身，应用您的标志，运行 `claude stop <id>`，然后重复该命令。56 使用这些中的任何一个，或当 [Agent 视图被关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，Claude Code 不发送任何内容并以状态 1 退出，打印会话正在后台运行以及打开它的 `claude attach <id>` 命令，或在无法确定 ID 时告诉您在 `claude agents` 中找到它。添加 `--fork-session` 以改为恢复对话的副本。要在您自己的会话中继续对话本身并应用您的标志，请运行 `claude stop <id>`，然后重复该命令。

57 57

58 以 `/` 或 `!` 开头的提示不会被发送，会话等待您回答问题时的任何提示也不会。在这两种情况下，Claude Code 都不会打开会话，消息包括 `Your prompt was not sent to it` 和原因。58 以 `/` 或 `!` 开头的提示词不会被发送，会话等待您回答问题时的任何提示词也不会。在这两种情况下，Claude Code 都不会打开会话，消息中包括 `Your prompt was not sent to it` 和原因。

59* **从会话内**：`/resume` 将您当前的对话移到后台，并将此终端附加到运行中的会话，打印 `Opening "<title>", running in the background (<id>)`。在空提示上按 `←` 返回代理视图，这也列出您离开的对话。当当前对话无法移到后台时，例如因为您已附加到后台会话或会话持久性已关闭，`/resume` 会打印 `claude attach` 命令以改为运行。59* **从会话内**：`/resume` 将您当前的对话移到后台，并将此终端附加到运行中的会话，打印 `Opening "<title>", running in the background (<id>)`。在空输入框中按 `←` 返回 Agent 视图，其中也列出您离开的对话。当当前对话无法移到后台时，例如因为您已附加到后台会话或会话持久化已关闭，`/resume` 会打印应改为运行的 `claude attach` 命令。

60 60

61<h3 id="what-a-resumed-session-restores">61<h3 id="what-a-resumed-session-restores">

62 恢复的会话恢复的内容62 恢复的会话恢复的内容

63</h3>63</h3>

64 64

~~65当 Claude Code 从其文本记录加载对话时，恢复的会话会恢复对话以及保存在其中的状态：~~65当 Claude Code 从其会话记录加载对话时，恢复的会话会恢复对话以及保存在其中的状态：

66 66

67* 对话历史：完整历史，包括工具调用和结果。如果工具在上一个进程结束时仍在运行（例如在崩溃中），当您恢复时它不会完成或再次运行。Claude 会看到该调用被标记为在记录其结果之前被切断，并被告知在再次运行之前检查它是否生效，除非设置了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars#variables)。在 v2.1.281 之前，Claude Code 会从对话中删除切断的调用或将其显示为您中断的调用。67* 对话历史：完整历史，包括工具调用和结果。如果工具在上一个进程结束时仍在运行（例如在崩溃中），当您恢复时它不会完成或再次运行。Claude 会看到该调用被标记为在记录其结果之前被切断，并被告知在再次运行之前检查它是否已生效，除非设置了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars#variables)。在 v2.1.281 之前，Claude Code 会从对话中删除被切断的调用，或将其作为您中断的调用显示给 Claude。

68* 模型：会话继续使用它正在使用的模型。当模型已被停用或不被 `availableModels` 允许时，模型不会被恢复；当在启动时通过 `--model` 标志或 `ANTHROPIC_MODEL` 系列环境变量选择模型时；或在使用特定于提供商的部署 ID 的提供商上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/third-party-integrations)；请参阅[模型配置](/docs/zh-CN/model-config#setting-your-model)了解解析顺序。68* 模型：会话继续使用它之前使用的模型，[设置模型](/docs/zh-CN/model-config#setting-your-model)中所述的情况除外。

69* Agent：使用 [`--agent`](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 或 `agent` 设置启动的会话继续作为该 agent，保持其工具限制和模型。在恢复时传递 `--agent` 以选择不同的；对于任一情况下的系统提示，请参阅[恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 在两个地方查找 agent：会话的原始目录（前提是您已[信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)）和您恢复的目录，因此项目范围的 agent 在您从另一个目录恢复时仍会加载。如果 Claude Code 在任一位置都找不到 agent，会话会以默认工具恢复并显示[警告，命名该 agent](/docs/zh-CN/errors#session-agent-no-longer-available)。69* Agent：使用 [`--agent`](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 或 `agent` 设置启动的会话继续作为该 Agent 运行，保持其工具限制和模型。在恢复时传递 `--agent` 以选择不同的 Agent；关于任一情况下的系统提示词，请参阅[恢复对话中的系统提示词标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 在两个地方查找 Agent：会话的原始目录（前提是您已[信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)），然后是您恢复时所在的目录，因此项目范围的 Agent 在您从另一个目录恢复时仍会加载。如果 Claude Code 在任一位置都找不到该 Agent，会话会以默认工具恢复并显示[指明该 Agent 的警告](/docs/zh-CN/errors#session-agent-no-longer-available)。

70* 权限模式：如果您从终端使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时）恢复，不带 `-p`，Claude Code 会恢复会话所在的权限模式，除了[恢复时的权限模式](#permission-mode-on-resume)中的情况，这也涵盖会话选择器、`/resume` 和使用 `claude -p` 恢复。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。70* 权限模式：如果您从终端使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时）恢复，且不带 `-p`，Claude Code 会恢复会话所在的权限模式，[恢复时的权限模式](#permission-mode-on-resume)中的情况除外，该部分也涵盖会话选择器、`/resume` 和使用 `claude -p` 恢复。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。

~~71* 活跃目标：会话结束时仍然活跃的[目标](/docs/zh-CN/goal#resume-with-an-active-goal)会继续；其轮次计数、计时器和令牌支出基线重置。~~71* 活跃目标：会话结束时仍然活跃的[目标](/docs/zh-CN/goal#resume-with-an-active-goal)会延续；其轮次计数、计时器和 token 支出基线会重置。

~~72* 计划任务：[未过期的任务](/docs/zh-CN/scheduled-tasks#limitations)会被恢复。后台 Bash 和监视任务不会。~~72* 定时任务：[未过期的任务](/docs/zh-CN/scheduled-tasks#limitations)会被恢复。后台 Bash 和监视任务不会。

73* 后台工作：[后台子 agent](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)、后台 Bash 命令或[工作流](/docs/zh-CN/workflows)在上一个进程结束时未完成，会在恢复的文本记录中显示为未完成的注记。Claude Code 不会从这些注记启动轮次；Claude 会在您的下一个提示中读取它们。73* 后台工作：随上一个进程结束的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)、后台 Bash 命令或[工作流](/docs/zh-CN/workflows)，会在恢复的会话记录中显示为未完成的注记。Claude Code 不会因这些注记启动轮次；Claude 会随您的下一个提示词读取它们。

74 74

75并非原始启动的每个配置标志都会被恢复。如果会话依赖于 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 添加的目录，在恢复时再次传递它们；使用 `/add-dir` 在会话中期添加的目录也不会被恢复，尽管会话选择器仍然使用它们来定位会话。标准设置文件（如 `settings.json` 和 `settings.local.json`）在启动时重新读取，因此驻留在其中的配置不需要再次传递。对于 `--system-prompt` 和 `--append-system-prompt`，请参阅[恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。75并非原始启动的每个配置标志都会被恢复。如果会话依赖于 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 添加的目录，请在恢复时再次传递它们；在会话中途使用 `/add-dir` 添加的目录也不会被恢复，尽管会话选择器仍然使用它们来定位会话。标准设置文件（如 `settings.json` 和 `settings.local.json`）会在启动时重新读取，因此存放在其中的配置不需要再次传递。关于 `--system-prompt` 和 `--append-system-prompt`，请参阅[恢复对话中的系统提示词标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

76 76

77<h4 id="permission-mode-on-resume">77<h4 id="permission-mode-on-resume">

78 恢复时的权限模式78 恢复时的权限模式

79</h4>79</h4>

80 80

81Claude Code 启动恢复会话的权限模式取决于您如何恢复。下面的情况适用于 Claude Code 从其文本记录加载对话时；当您[打开仍在运行的后台会话](#resume-a-running-background-session)时，该会话保持它所在的权限模式。81Claude Code 以何种权限模式启动恢复的会话取决于您如何恢复。下面的情况适用于 Claude Code 从其会话记录加载对话时；当您改为[打开仍在运行的后台会话](#resume-a-running-background-session)时，该会话保持它所在的权限模式。

82 82

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 改为以该模式启动恢复的会话 |

100

101<a id="resume-in-plan-mode-with-p" />

100 102

101<h5 id="resume-in-plan-mode-with-p">103<h5 id="resume-in-plan-mode-with-p">

102 使用 `-p` 在计划模式中恢复104 使用 `-p` 在计划模式中恢复

103</h5>105</h5>

104 106

105`claude -p --resume` 或 `claude -p --continue` 运行仅在所有这些条件都成立时才在计划模式中恢复：107`claude -p --resume` 或 `claude -p --continue` 运行仅在以下所有条件都成立时才以计划模式恢复：

106 108

107* 您传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，不传递 [`--permission-prompts none`](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)，以便 Claude Code 可以呈现计划以供批准109* 您传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，且不传递 [`--permission-prompts none`](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)，以便 Claude Code 可以呈现计划以供批准

108* 您不传递 `--permission-mode` 或 `--dangerously-skip-permissions`110* 您不传递 `--permission-mode` 或 `--dangerously-skip-permissions`

109* 您不传递 `--fork-session`111* 您不传递 `--fork-session`

110* 运行不是通过[频道](/docs/zh-CN/channels)启动的112* 运行不是通过[频道](/docs/zh-CN/channels)启动的

113 从摘要恢复115 从摘要恢复

114</h3>116</h3>

115 117

116在 Pro 或 Max 计划上，当您恢复已不活跃超过约一小时且超过 100,000 个令牌的会话时，Claude Code 会恢复对话，然后在您发送第一条消息之前打开一个对话框。到那时，会话的[提示缓存](/docs/zh-CN/prompt-caching#cache-lifetime)已过期，因此无论您选择对话框的哪个选项，下一个请求都会处理完整历史一次。118在 Pro 或 Max 计划上，当您恢复已不活跃超过约一小时且超过 100,000 个 token 的会话时，Claude Code 会恢复对话，然后在您发送第一条消息之前打开一个对话框。到那时，会话的[提示缓存](/docs/zh-CN/prompt-caching#cache-lifetime)已过期，因此无论您选择对话框的哪个选项，下一个请求都会处理一次完整历史。

117 119

118对话框提供三种方式来继续会话。它们在每个会话向后续请求转发多少对话方面有所不同，这是在保留每个细节和每个请求发送更少令牌之间的权衡：120对话框提供三种继续会话的方式。它们的区别在于各自向后续请求携带多少对话内容，这是在保留每个细节与每个请求发送更少 token 之间的权衡：

119 121

120* **从摘要恢复**：立即运行 [`/compact`](/docs/zh-CN/context-window#what-survives-compaction)。Claude Code 通过完整历史发送一个摘要请求，然后用摘要、您最近的交换和最多五个最近读取的文件替换历史。后续请求会转发摘要而不是完整历史。122* **从摘要恢复**：立即运行 [`/compact`](/docs/zh-CN/context-window#what-survives-compaction)。Claude Code 针对完整历史发送一个摘要请求，然后用摘要、您最近的交互和最多五个最近读取的文件替换历史。后续请求携带摘要而不是完整历史。

121* **按原样恢复完整会话**：加载未更改的对话。在您发送第一条消息后，Claude Code 重新处理并重新缓存完整历史，然后在缓存保持温暖时从缓存中重新读取它以进行后续请求。123* **按原样恢复完整会话**：加载未更改的对话。在您发送第一条消息后，Claude Code 重新处理并重新缓存完整历史，然后在缓存保持有效期间，后续请求从缓存中重新读取它。

122* **不再问我**：恢复完整会话并停止在所有未来恢复中显示对话框。124* **不再询问**：恢复完整会话，并在以后所有恢复中不再显示该对话框。

123 125

124按原样恢复会保持对话的每个细节可用，每个请求的成本随对话的大小而扩展。从摘要恢复在每个后续请求上成本更低，因为它转发摘要而不是完整历史，但摘要遗漏的任何内容都不再在 Claude 的上下文中。请参阅[为什么长会话中的使用量会增加](/docs/zh-CN/costs#why-usage-climbs-in-a-long-session)了解该每个请求成本的来源。126按原样恢复会保持对话的每个细节可用，每个请求的成本随对话的大小而增长。从摘要恢复在每个后续请求上成本更低，因为它携带摘要而不是完整历史，但摘要遗漏的任何内容都不再位于 Claude 的上下文中。请参阅[为什么长会话中的使用量会增加](/docs/zh-CN/costs#why-usage-climbs-in-a-long-session)了解该每个请求成本的来源。

125 127

126<h3 id="where-the-session-picker-looks">128<h3 id="where-the-session-picker-looks">

127 会话选择器查看的位置129 会话选择器查看的位置

132* 来自当前 worktree 的会话，包括[后台会话](/docs/zh-CN/agent-view)，在列表中标记为 `bg`134* 来自当前 worktree 的会话，包括[后台会话](/docs/zh-CN/agent-view)，在列表中标记为 `bg`

133* 在其他地方启动但使用 `/add-dir` 添加了当前目录的会话135* 在其他地方启动但使用 `/add-dir` 添加了当前目录的会话

134 136

135使用 `Ctrl+W` 扩展到存储库的所有 worktrees，或使用 `Ctrl+A` 扩展到此计算机上的每个项目。137使用 `Ctrl+W` 扩展到仓库的所有 worktrees，或使用 `Ctrl+A` 扩展到此计算机上的每个项目。

136 138

137第一个提示是 [`/loop`](/docs/zh-CN/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 命令的会话不会出现在选择器中，`claude --continue` 也会跳过它们。在对话中稍后运行 `/loop` 不会隐藏会话。在 v2.1.211 之前，对话早期的 `/loop` 运行会永久隐藏选择器中的会话。139第一个提示词是 [`/loop`](/docs/zh-CN/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 命令的会话不会出现在选择器中，`claude --continue` 也会跳过它们。在对话中稍后运行 `/loop` 不会隐藏会话。在 v2.1.211 之前，在对话早期运行 `/loop` 会使该会话永久从选择器中隐藏。

138 140

139使用 [`/cd`](/docs/zh-CN/commands) 移动会话会将其重新定位到新目录的项目存储，因此之后它会出现在该目录的选择器中。从 v2.1.196 开始，移动的会话在崩溃或强制退出后会保持不在旧目录的选择器中。在较早的版本中，当旧路径包含下划线等特殊字符时，在不干净的退出后，它也可能在旧目录的列表中重新出现。141使用 [`/cd`](/docs/zh-CN/commands) 移动会话会将其重新定位到新目录的项目存储，因此之后它会出现在该目录的选择器中。从 v2.1.196 开始，移动的会话即使在崩溃或强制退出后也不会出现在旧目录的选择器中。在较早的版本中，当旧路径包含下划线等特殊字符时，在非正常退出后，它也可能重新出现在旧目录的列表中。

140 142

141从同一存储库的另一个 worktree 选择会话时，Claude Code 会在原地恢复它；当会话自己的 worktree 不再存在时，Claude Code [在您的当前目录中恢复它](/docs/zh-CN/worktrees#resume-a-worktree-session)。从不相关项目选择会话时，Claude Code 会将 `cd` 和恢复命令复制到您的剪贴板。如果该项目的目录不再存在，Claude Code 会在您的当前目录中恢复会话，而不是复制会失败的 `cd` 命令。143从同一仓库的另一个 worktree 选择会话时，Claude Code 会在原地恢复它；当会话自己的 worktree 不再存在时，Claude Code 会[在您的当前目录中恢复它](/docs/zh-CN/worktrees#resume-a-worktree-session)。从不相关项目选择会话时，Claude Code 会改为将 `cd` 和恢复命令复制到您的剪贴板。如果该项目的目录不再存在，Claude Code 会在您的当前目录中恢复会话，而不是复制会失败的 `cd` 命令。

142 144

143按名称恢复会跨当前存储库及其 worktrees 解析。两种形式都查找精确匹配并直接恢复它，即使它位于不同的 worktree 中：145按名称恢复会在当前仓库及其 worktrees 范围内解析。两种形式都会查找精确匹配并直接恢复，即使它位于不同的 worktree 中：

144 146

145| 命令 | 精确匹配 | 模糊名称 |147| 命令 | 精确匹配 | 模糊名称 |

146| :- | :- | :- |148| :- | :- | :- |

settings.md +6 −4

Details

411 411

412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。

413 413

659 659

660按顺序，最高优先级优先：660按顺序，最高优先级优先：

661 661

6621. **托管设置**：您的组织部署的设置，通过 `managed-settings.json` 文件、MDM 策略或来自 claude.ai 控制台的[服务器管理设置](/docs/zh-CN/server-managed-settings)。您设置的任何内容都不会覆盖它们：您使用 `--settings` 传递的键不会覆盖相同的托管键，`--model` 等标志仅从您的组织允许的模型中选择。托管 `model` 设置每个会话启动的模型，您仍然可以使用 `/model` 切换；锁定是 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels)，它限制 `/model`、`--model` 和您自己文件中的 `model` 键。当您的组织传递多个托管来源时，[托管层内的优先级](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的规则说 Claude Code 从每个读取什么。6621. **托管设置**：您的组织部署的设置，通过 `managed-settings.json` 文件、MDM 策略或来自 claude.ai 控制台的[服务器管理设置](/docs/zh-CN/server-managed-settings)。您自己的设置文件或 `--settings` 中的任何内容都不会覆盖托管键，`--model` 等标志仅从您的组织允许的模型中选择。托管 [`model`](/docs/zh-CN/settings-reference#model) 是起始默认值，而不是锁定；锁定是 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 和 [`deniedModels`](/docs/zh-CN/settings-reference#deniedmodels)。当您的组织传递多个托管来源时，[托管层内的优先级](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的规则说明 Claude Code 从每个来源读取什么。

6632. **命令行参数**：您在从终端启动 `claude` 时传递的标志，用于一个会话；请参阅[为一个会话更改设置](#change-a-setting-for-one-session)。Claude Code 使用与其他级别相同的规则将您使用 `--settings <file-or-json>` 传递的 JSON 与您的设置文件合并：它在此处设置的键优先于本地、项目或用户设置中的相同键，省略的键保持较低级别的值。6632. **命令行**：您在启动 `claude` 时使用 `--settings <file-or-json>` 传递的 JSON，仅用于该会话；请参阅[为一个会话更改设置](#change-a-setting-for-one-session)。您在此处设置的键会覆盖项目和用户设置文件中的相同键，省略的键保留这些文件中的值。其他标志（如 `--model`）为会话设置某一项内容，不属于此堆栈；[设置参考](/docs/zh-CN/settings-reference)上的键条目说明哪些标志会覆盖它。

6643. **项目本地设置** (`.claude/settings.local.json`)：您对此项目的个人设置。6643. **项目本地设置** (`.claude/settings.local.json`)：您对此项目的个人设置。

6654. **共享项目设置** (`.claude/settings.json`)：您的团队检入源代码管理的设置。6654. **共享项目设置** (`.claude/settings.json`)：您的团队检入源代码管理的设置。

6665. **用户设置** (`~/.claude/settings.json`)：您对每个项目的个人设置。6665. **用户设置** (`~/.claude/settings.json`)：您对每个项目的个人设置。

767 767

768两件事阻止 `.claude/settings.json` 中的键为克隆它的每个人应用：768两件事阻止 `.claude/settings.json` 中的键为克隆它的每个人应用：

769 769

770* **Claude Code 忽略存储库文件中的键。** 在[设置索引](/docs/zh-CN/settings-reference#settings-index)的作用域列中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。这些键永远不会从共享文件应用，除了少数几个存储库文件仍然可以关闭的。每个这些条目在其作用域行上说明。`Global config` 键仅从 `~/.claude.json` 应用。770* **Claude Code 忽略仓库文件中的键。** 在[设置索引](/docs/zh-CN/settings-reference#settings-index)的作用域列中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。这些键永远不会从共享文件应用，除了少数几个仓库文件仍然可以关闭的。每个这些条目在其作用域行上说明。`Global config` 键仅从 `~/.claude.json` 应用。

771 771

772 在 `env` 键内，遥测导出变量也永远不会从共享文件应用，除了少数关闭值；请参阅[Claude Code 在 `env` 中忽略的变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)。772 在 `env` 键内，遥测导出变量也永远不会从共享文件应用，除了少数关闭值；请参阅[Claude Code 在 `env` 中忽略的变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)。

773* **键等待信任。** `permissions.allow` 规则、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多数 [`env`](/docs/zh-CN/settings-reference#env) 值仅在每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。`deny` 和 `ask` 规则立即应用。773* **键等待信任。** `permissions.allow` 规则、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多数 [`env`](/docs/zh-CN/settings-reference#env) 值仅在每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。`deny` 和 `ask` 规则立即应用。

793| [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) | 来自任何作用域的 `false`，以及来自任何作用域的 `disableArtifact: true` | 即使托管来源设置 `true` 也被尊重；没有什么打开[Artifact 工具](/docs/zh-CN/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更高版本 |793| [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) | 来自任何作用域的 `false`，以及来自任何作用域的 `disableArtifact: true` | 即使托管来源设置 `true` 也被尊重；没有什么打开[Artifact 工具](/docs/zh-CN/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更高版本 |

795| [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 来自任何作用域的 `true` | 即使托管来源设置 `false` 也被尊重。需要 Claude Code v2.1.257 或更高版本 |

796| [`autoMode.classifyAllShell`](/docs/zh-CN/settings-reference#automode-classifyallshell) | 来自 `~/.claude/settings.json` 或 `--settings` 的 `true` | 即使托管来源设置 `false` 也被尊重 |

795| [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使托管来源设置 `true` 也被尊重；项目或本地 `true` 被忽略 |797| [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使托管来源设置 `true` 也被尊重；项目或本地 `true` 被忽略 |

796| [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更严格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在托管、`--settings` 和用户值上被尊重；不是更严格的项目或本地值被忽略 |798| [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更严格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在托管、`--settings` 和用户值上被尊重；不是更严格的项目或本地值被忽略 |

797| [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |799| [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

settings-reference.md +1 −1

Details

870 870

871通过将其设置为 `false` 来为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking)。默认情况下思考是打开的，所以 `true` 不会改变任何内容。大多数人通过 `/config` 而不是编辑文件来设置这个。871通过将其设置为 `false` 来为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking)。默认情况下思考是打开的，所以 `true` 不会改变任何内容。大多数人通过 `/config` 而不是编辑文件来设置这个。

872 872

873在总是思考的模型上，如 Opus 5.5、Sonnet 5.5 和 Fable 模型，`false` 没有效果。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 省略 `thinking` 参数而不是关闭思考，因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时，Claude Code 会发送努力 `high` 而不是更高级别给它知道[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，如 Opus 5。873在总是思考的模型上，如 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型，`false` 没有效果。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 省略 `thinking` 参数而不是关闭思考，因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时，对于 Claude Code 已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（如 Opus 5），Claude Code 会发送 effort `high` 而不是更高级别。

874 874

875* **Scope**: [`Any file`](#scopes)875* **Scope**: [`Any file`](#scopes)

876* **Type**: Boolean876* **Type**: Boolean

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

skills.md +7 −2

Details

237 237

238在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些 skills。238在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些 skills。

239 239

240在您的终端中，Claude Code 在您使用 claude.ai 账户登录的会话中同步这些 skills。会话启动时，Claude Code 在后台将您账户的 skills 下载到 `~/.claude/skills/synced/` 中，然后在会话运行时大约每 10 分钟检查一次 claude.ai 是否有更改。当检查发现 skill 在 claude.ai 上被添加、编辑或关闭时，Claude Code 在运行的会话中添加、更新或删除它，无需重新启动。终端会话中的同步需要 Claude Code v2.1.273 或更高版本。240在您的终端中，Claude Code 在您使用 claude.ai 账户登录的会话中同步这些 skill。会话启动时，Claude Code 在后台将您账户的 skill 下载到 `~/.claude/skills/synced/` 中，然后在会话运行期间检查 claude.ai 是否有更改。当检查发现 skill 在 claude.ai 上被添加、编辑或关闭时，Claude Code 在运行的会话中添加、更新或删除它，无需重新启动。终端会话中的同步需要 Claude Code v2.1.273 或更高版本。

241 241

242同步永远不会延迟启动，因为 Claude 仅在调用 skill 时等待其下载。因此，短 [非交互式](/docs/zh-CN/headless) 运行可能在新添加的 skill 下载之前完成，在这种情况下，稍后的会话会下载它。要使非交互式运行下载您的 skills 并在回答提示之前等待列表，请将 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 设置为 `1`。242会话空闲时，检查运行得不那么频繁：

243

244* **当您或 Claude 在会话中工作时**：大约每 10 分钟运行一次检查。

245* **当会话空闲时**：大约每 40 分钟运行一次检查。当您再次在会话中输入时，如果上次检查已超过 10 分钟，Claude Code 会在几分钟内进行检查。

246

247同步永远不会延迟启动，因为 Claude 仅在调用 skill 时等待其下载。因此，短 [非交互式](/docs/zh-CN/headless) 运行可能在新添加的 skill 下载之前完成，在这种情况下，稍后的会话会下载它。要使非交互式运行下载您的 skill 并在回答提示词之前等待列表，请将 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 设置为 `1`。在 v2.1.273 之前，终端会话仅在设置了此变量的 `-p` 运行中下载它们。

243 248

244Claude Code 仅在使用您的 claude.ai 账户登录的会话中同步，并 [从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。它不在这些会话中同步：249Claude Code 仅在使用您的 claude.ai 账户登录的会话中同步，并 [从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。它不在这些会话中同步：

245 250

sub-agents.md +4 −4

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

1164 1164

1165* 子代理完成时，Claude 会收到其 Agent ID。1165* 子代理完成时，Claude 会收到其 Agent ID。

1166* 内置的 Explore 和 Plan Agent 是一次性的，不返回 Agent ID，因此 Claude 无法恢复它们。需要继续工作时，请使用 `general-purpose` 或自定义子代理。1166* 内置的 Explore 和 Plan Agent 是一次性的，不返回 Agent ID，因此 Claude 无法恢复它们。需要继续工作时，请使用 `general-purpose` 或自定义子代理。

1167* 当子代理因达到 [`maxTurns`](#supported-frontmatter-fields) 限制而停止时，Claude Code 会将返回的输出标记为部分结果。对于会返回 Agent ID 的子代理，Claude Code 还会在结果中注明 Claude 可以向该子代理发送消息，让它从停止处继续。1167* 当子代理因达到 [`maxTurns`](#supported-frontmatter-fields) 限制而停止时，Claude Code 会将返回的输出标记为部分结果，Claude 可以恢复该子代理以继续其工作。

1168 1168

1169Claude 使用 `SendMessage` 工具，以 Agent 的 ID 或名称作为 `to` 字段来恢复它。`SendMessage` 不要求启用 [agent teams](/docs/zh-CN/agent-teams)；只有 `shutdown_request` 和 `plan_approval_response` 等结构化团队协议消息才需要。除了子代理和队友之外，在启用了跨会话消息的会话中，Claude 还可以使用同一工具向[您的其他 Claude Code 会话](/docs/zh-CN/cross-session-messaging)发送消息，无论它们在本机还是[其他机器上](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。1169Claude 使用 `SendMessage` 工具，以 Agent 的 ID 或名称作为 `to` 字段来恢复它。`SendMessage` 不要求启用 [agent teams](/docs/zh-CN/agent-teams)；只有 `shutdown_request` 和 `plan_approval_response` 等结构化团队协议消息才需要。除了子代理和队友之外，在启用了跨会话消息的会话中，Claude 还可以使用同一工具向[您的其他 Claude Code 会话](/docs/zh-CN/cross-session-messaging)发送消息，无论它们在本机还是[其他机器上](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。

1170 1170

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 +25 −10

Details

40 40

41该扩展也可以安装在其他 VS Code 分支中，如 Devin Desktop 或 Kiro。在编辑器的扩展视图中搜索"Claude Code"，或从 [Open VSX 注册表](https://open-vsx.org/extension/Anthropic/claude-code) 安装。如果您的编辑器无法安装该扩展，请[安装 CLI](/docs/zh-CN/quickstart) 并在其集成终端中运行 `claude`。CLI 可在任何终端中使用。41该扩展也可以安装在其他 VS Code 分支中，如 Devin Desktop 或 Kiro。在编辑器的扩展视图中搜索"Claude Code"，或从 [Open VSX 注册表](https://open-vsx.org/extension/Anthropic/claude-code) 安装。如果您的编辑器无法安装该扩展，请[安装 CLI](/docs/zh-CN/quickstart) 并在其集成终端中运行 `claude`。CLI 可在任何终端中使用。

42 42

43要在开发容器中运行 Claude Code，请参阅[开发容器](/docs/zh-CN/devcontainer)。

43<Note>如果安装后扩展没有出现，请重启 VS Code 或从命令面板运行"Developer: Reload Window"。</Note>45<Note>如果安装后扩展没有出现，请重启 VS Code 或从命令面板运行"Developer: Reload Window"。</Note>

44 46

45<h2 id="get-started">47<h2 id="get-started">

606| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。对于共享配置，请改用 Claude Code 设置。仅当值为绝对路径时，[`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 条目才会生效；扩展不会展开 `~`，并且会忽略相对路径值。 |608| `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)。 |611| `claudeProcessWrapper` | - | 用于启动 Claude 进程的可执行文件。当存在时，捆绑的二进制路径作为参数传递。如果扩展构建不包含您的平台的二进制文件，请将其设置为单独安装的 `claude` 二进制文件。 |

610 612

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

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

786启用自动编辑权限后，Claude Code 可以修改 VS Code 配置文件（如 `settings.json` 或 `tasks.json`），VS Code 可能会自动执行这些文件。为了在处理不受信任的代码时降低风险：788启用自动编辑权限后，Claude Code 可以修改 VS Code 配置文件（如 `settings.json` 或 `tasks.json`），VS Code 可能会自动执行这些文件。为了在处理不受信任的代码时降低风险：

787 789

788* 为不受信任的工作区启用 [VS Code 受限模式](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode)790* 为不受信任的工作区启用 [VS Code 受限模式](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode)

789* 使用手动模式而不是自动编辑或自动编辑791* 编辑时使用手动模式，而不是自动编辑模式或自动模式

790* 在接受更改之前仔细审查更改792* 在接受更改之前仔细审查更改

791 793

792<h3 id="the-built-in-ide-mcp-server">794<h3 id="the-built-in-ide-mcp-server">

793 内置 IDE MCP 服务器795 内置 IDE MCP 服务器

794</h3>796</h3>

795 797

796当扩展处于活动状态时，它运行一个本地 MCP 服务器，CLI 会自动连接到该服务器。这是 CLI 在 VS Code 的原生 diff 查看器中打开 diff、读取您当前的 `@`-mentions 选择，以及——当您在 Jupyter notebook 中工作时——要求 VS Code 执行单元格的方式。798当扩展处于活动状态时，它运行一个本地 MCP 服务器，CLI 会自动连接到该服务器。这是 CLI 在 VS Code 的原生 diff 查看器中打开 diff、读取您当前的选择以用于 `@`-mentions，以及——当您在 Jupyter notebook 中工作时——要求 VS Code 执行单元格的方式。

797 799

798服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置的。但是，如果您的组织使用 `PreToolUse` hook 来允许列表 MCP 工具，您需要知道它的存在。800服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置的。但是，如果您的组织使用 `PreToolUse` hook 将 MCP 工具加入允许列表，您需要知道它的存在。

799 801

800**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。802**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示词中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，会话记录会显示一行 `⧉ Selected N lines from <file>`。

801 803

802如果您[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)，它会保留您按下 `Enter` 时的选择，无论您之后选择什么。804如果您[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)，它会保留您按下 `Enter` 时的选择，无论您之后选择什么。

803 805

807 809

808**传输和身份验证。** 服务器绑定到 `127.0.0.1` 上的随机端口，范围在 10000–65535，端口不可配置。传输是未加密的 `ws://`；因为套接字仅限于本地回环，任何可以捕获流量的进程也可以从锁文件中读取令牌，所以 TLS 不会增加保护。每次扩展激活都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。锁文件在 `0700` 目录中具有 `0600` 权限，因此只有运行 VS Code 的用户才能读取它。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将写入 `$CLAUDE_CONFIG_DIR/ide/` 目录。810**传输和身份验证。** 服务器绑定到 `127.0.0.1` 上的随机端口，范围在 10000–65535，端口不可配置。传输是未加密的 `ws://`；因为套接字仅限于本地回环，任何可以捕获流量的进程也可以从锁文件中读取令牌，所以 TLS 不会增加保护。每次扩展激活都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。锁文件在 `0700` 目录中具有 `0600` 权限，因此只有运行 VS Code 的用户才能读取它。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将写入 `$CLAUDE_CONFIG_DIR/ide/` 目录。

809 811

810**暴露给模型的工具。** 服务器托管十几个工具，但只有两个对模型可见。其余的是 CLI 用于自己的 UI 的内部 RPC——打开 diff、读取选择、保存文件——在工具列表到达 Claude 之前被过滤掉。812**暴露给模型的工具。** 服务器托管十几个工具，但只有两个对模型可见。其余的是 CLI 用于自己的 UI 的内部 RPC，例如打开 diff、读取选择和保存文件。它们在工具列表到达 Claude 之前被过滤掉。

811 813

812| 工具名称（如 hooks 所见） | 功能 | 只读 |814| 工具名称（如 hook 所见） | 功能 | 只读 |

813| - | - | - |815| - | - | - |

814| `mcp__ide__getDiagnostics` | 返回语言服务器诊断——VS Code 的问题面板中的错误和警告。可选地限定到一个文件。 | 是 |816| `mcp__ide__getDiagnostics` | 返回语言服务器诊断：VS Code 的问题面板中的错误和警告。可选地限定到一个文件。 | 是 |

815| `mcp__ide__executeCode` | 在活动 Jupyter notebook 的内核中运行 Python 代码。请参阅下面的确认流程。 | 否 |817| `mcp__ide__executeCode` | 在活动 Jupyter notebook 的内核中运行 Python 代码。请参阅下面的确认流程。 | 否 |

816 818

817**聊天面板中的诊断。** 在聊天面板中，使用 Claude Code v2.1.285 或更高版本时，Claude 通过一个名为 `claude-vscode` 的独立内置服务器读取 VS Code 的问题面板。Claude 可以向它请求某个文件中的当前错误和警告，或者 VS Code 具有诊断信息的所有文件中的当前错误和警告。819**聊天面板中的诊断。** 在聊天面板中，使用 Claude Code v2.1.285 或更高版本时，Claude 通过一个名为 `claude-vscode` 的独立内置服务器读取 VS Code 的问题面板。Claude 可以向它请求某个文件中的当前错误和警告，或者 VS Code 具有诊断信息的所有文件中的当前错误和警告。

833 835

834`Read` 拒绝规则不涵盖这两个工具中的任何一个，因此请像示例那样使用[拒绝规则](/docs/zh-CN/permissions#mcp)按名称阻止它们。836`Read` 拒绝规则不涵盖这两个工具中的任何一个，因此请像示例那样使用[拒绝规则](/docs/zh-CN/permissions#mcp)按名称阻止它们。

835 837

836**Jupyter 执行始终先询问。** `mcp__ide__executeCode` 无法静默运行任何内容。在每次调用时，代码被插入为活动 notebook 末尾的新单元格，VS Code 将其滚动到视图中，原生快速选择器要求您**执行**或**取消**。取消——或用 `Esc` 关闭选择器——会向 Claude 返回错误，不会运行任何内容。当没有活动 notebook、未安装 Jupyter 扩展 (`ms-toolsai.jupyter`) 或内核不是 Python 时，该工具也会直接拒绝。838**Jupyter 执行始终先询问。** `mcp__ide__executeCode` 无法静默运行任何内容。在每次调用时，代码被插入为活动 notebook 末尾的新单元格，VS Code 将其滚动到视图中，原生快速选择器要求您**执行**或**取消**。取消或用 `Esc` 关闭选择器，会向 Claude 返回错误，不会运行任何内容。当没有活动 notebook、未安装 Jupyter 扩展 (`ms-toolsai.jupyter`) 或内核不是 Python 时，该工具也会直接拒绝。

837 839

838<Note>840<Note>

839 快速选择器确认与 `PreToolUse` hooks 分开。`mcp__ide__executeCode` 的允许列表条目让 Claude *提议*运行单元格；VS Code 内的快速选择器是让它*实际*运行的原因。841 快速选择器确认与 `PreToolUse` hook 分开。`mcp__ide__executeCode` 的允许列表条目让 Claude *提议*运行单元格；VS Code 内的快速选择器是让它*实际*运行的原因。

840</Note>842</Note>

841 843

842<a id="troubleshooting" />844<a id="troubleshooting" />

845 修复常见问题847 修复常见问题

846</h2>848</h2>

847 849

850登录、网络和启动错误在安装故障排除页面和错误参考页面中有各自的条目。请在表格中找到您看到的内容，然后点击相应链接。

851

852| 您看到的内容 | 前往位置 |

853| - | - |

854| 登录后出现 `API Error: 403 Request not allowed` | [登录后出现 403 Forbidden](/docs/zh-CN/troubleshoot-install#403-forbidden-after-login) |

855| 已经登录后仍被要求再次登录 | [未登录或令牌已过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) |

856| 云提供商凭据在终端中可用，但在扩展程序中不可用 | [Bedrock、Agent Platform 或 Foundry 凭据未加载](/docs/zh-CN/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) |

857| `SSL certificate verification failed` 或 `Self-signed certificate detected` | [SSL 证书错误](/docs/zh-CN/errors#ssl-certificate-errors) |

858| `Claude Code process exited with code 1` 或其他代码 | [Claude Code process exited with code N](/docs/zh-CN/errors#claude-code-process-exited-with-code-n) |

859| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](/docs/zh-CN/errors#could-not-locate-the-claude-cli-on-path) |

860| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](/docs/zh-CN/errors#the-connection-to-claude-code-ended-before-this-message-completed) |

861| 在 VS Code 的集成终端中找不到 `claude` | [在 VS Code 中运行 CLI](#run-cli-in-vs-code) |

862

848<h3 id="extension-won’t-install">863<h3 id="extension-won’t-install">

849 扩展程序无法安装864 扩展程序无法安装

850</h3>865</h3>

web-quickstart.md +2 −2

Details

50| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 |50| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 |

51| **需要 GitHub** | 是，或通过 `--cloud` [捆绑本地仓库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 |51| **需要 GitHub** | 是，或通过 `--cloud` [捆绑本地仓库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 |

52| **断开连接时继续运行** | 是 | 否 | 当会话在您的机器上保持打开时 |52| **断开连接时继续运行** | 是 | 否 | 当会话在您的机器上保持打开时 |

55 55

56请参阅[终端快速入门](/docs/zh-CN/quickstart)、[Desktop 应用](/docs/zh-CN/desktop)或 [Remote Control](/docs/zh-CN/remote-control) 文档来设置本地会话。56请参阅[终端快速入门](/docs/zh-CN/quickstart)、[Desktop 应用](/docs/zh-CN/desktop)或 [Remote Control](/docs/zh-CN/remote-control) 文档来设置本地会话。

150 </Step>150 </Step>

151 151

152 <Step title="选择权限模式">152 <Step title="选择权限模式">

153 输入旁边的模式下拉菜单显示会话将在其中运行的模式：153 [权限模式控件](/docs/zh-CN/permission-modes#switch-permission-modes)显示会话将在其中运行的权限模式：

154 154

155 * **Auto**：分类器审查 Claude 的操作，而不是询问您。当您的组织允许自动模式且所选模型支持它时出现155 * **Auto**：分类器审查 Claude 的操作，而不是询问您。当您的组织允许自动模式且所选模型支持它时出现

156 * **Accept edits**：Claude 进行更改并推送分支而无需停止以获得批准156 * **Accept edits**：Claude 进行更改并推送分支而无需停止以获得批准

workflows.md +6 −1

Details

522 522

523要为整个组织关闭工作流，在[托管设置](/docs/zh-CN/server-managed-settings)中设置 `"disableWorkflows": true`，或使用[Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)页面上的切换。523要为整个组织关闭工作流，在[托管设置](/docs/zh-CN/server-managed-settings)中设置 `"disableWorkflows": true`，或使用[Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)页面上的切换。

524 524

525当工作流被禁用时，捆绑工作流命令和 `/workflow-authoring` skill 不可用，`ultracode` 关键字不再触发运行，**Ultracode** 切换从 `/effort` 中移除。一个已在进行中的运行会继续进行。525当工作流被禁用时：

526

527* `/workflows`、工作流命令和 `/workflow-authoring` skill 不可用

528* `ultracode` 关键字不再触发运行，**Ultracode** 开关会从 `/effort` 中移除

529

530已在进行中的运行会继续进行。

526 531

527关闭工作流也会使[ultracode](#let-claude-decide-with-ultracode)不可用。没有托管设置单独排除 ultracode：无论它在哪里[可用](/docs/zh-CN/model-config#when-ultracode-is-available)，用户可以使用 `/effort ultracode` 打开它。[努力上限](/docs/zh-CN/model-config#organization-effort-limits)降低了启用 ultracode 的会话运行的努力级别，但不会关闭 ultracode。532关闭工作流也会使[ultracode](#let-claude-decide-with-ultracode)不可用。没有托管设置单独排除 ultracode：无论它在哪里[可用](/docs/zh-CN/model-config#when-ultracode-is-available)，用户可以使用 `/effort ultracode` 打开它。[努力上限](/docs/zh-CN/model-config#organization-effort-limits)降低了启用 ultracode 的会话运行的努力级别，但不会关闭 ultracode。

528 533

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 21:59 UTC