Documentation — Spybara

admin-setup.md +13 −11

Details

36| Google Vertex AI | 您希望继承现有的 GCP 合规控制和计费 |36| Google Vertex AI | 您希望继承现有的 GCP 合规控制和计费 |

37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |

38 38

39某些 Claude Code 功能需要 Claude.ai 账户。[Claude Code on the web](/zh-CN/claude-code-on-the-web)、[Routines](/zh-CN/routines)、[Code Review](/zh-CN/code-review)、[Remote Control](/zh-CN/remote-control) 和 [Chrome extension](/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Bedrock、Vertex 或 Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。39某些 Claude Code 功能需要 claude.ai 账户。[Claude Code on the web](/zh-CN/claude-code-on-the-web)、[Routines](/zh-CN/routines)、[Code Review](/zh-CN/code-review)、[Remote Control](/zh-CN/remote-control) 和 [Chrome extension](/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Bedrock、Vertex 或 Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。

40 40

41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/zh-CN/authentication) 中。41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/zh-CN/authentication) 中。

42 42

46 决定设置如何到达设备46 决定设置如何到达设备

47</h2>47</h2>

48 48

~~49托管设置定义优先于本地开发人员配置的策略。Claude Code 按优先级顺序检查以下四个来源，并应用返回非空配置的第一个。~~49托管设置定义优先于本地开发人员配置的策略。Claude Code 按优先级顺序检查以下四个来源，并应用返回非空配置的第一个，但有一个例外：当任何管理员控制的来源设置了一小组[跨源锁定键](/zh-CN/settings#settings-precedence)（例如沙箱允许列表锁定）时，这些键会被遵守。

50 50

51| 机制 | 传递 | 优先级 | 平台 |51| 机制 | 传递 | 优先级 | 平台 |

52| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-- | :------------ |52| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-- | :------------ |

53| Server-managed | Claude.ai 管理控制台 | 最高 | 全部 |53| Server-managed | claude.ai 管理控制台，或用于网关登录的自托管 [Claude apps gateway](/zh-CN/claude-apps-gateway) | 最高 | 全部 |

55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux 和 WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | 中 | 全部 |55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux 和 WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | 中 | 全部 |

57 57

58Server-managed 设置在身份验证时到达设备，并在活跃会话期间每小时刷新一次，无需端点基础设施。它们需要 Claude for Teams 或 Enterprise 计划，因此在其他提供商上的部署需要改用基于文件或操作系统级别的机制之一。58已配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 会抢占所有四个来源：其输出成为该运行的唯一托管配置。请参阅[设置优先级](/zh-CN/settings#settings-precedence)。

59 59

60如果您的组织混合使用提供商，请为 Claude.ai 用户配置 [server-managed settings](/zh-CN/server-managed-settings) 加上 [file-based 或 plist/registry 回退](/zh-CN/settings#settings-files)，以便其他用户仍然接收托管策略。60Server-managed 设置在身份验证时到达设备，并在活跃会话期间每小时刷新一次，无需端点基础设施。通过 claude.ai 管理控制台传递需要 Claude for Teams 或 Enterprise 计划。在 Bedrock、Vertex AI 或 Foundry 上的部署可以通过运行 [Claude apps gateway](/zh-CN/claude-apps-gateway) 获得相同的远程传递，或改用基于文件或操作系统级别的机制之一。

61 61

62plist 和 HKLM 注册表位置适用于任何提供商，并且由于需要管理员权限才能写入，因此可以抵抗篡改。Windows 用户注册表中的 HKCU 可以在没有提升权限的情况下写入，因此将其视为便利默默认值而不是执行通道。62如果您的组织混合使用提供商，请为 claude.ai 用户配置 [server-managed settings](/zh-CN/server-managed-settings) 加上 [file-based 或 plist/registry 回退](/zh-CN/settings#settings-files)，以便其他用户仍然接收托管策略。

64plist 和 HKLM 注册表位置适用于任何提供商，并且由于需要管理员权限才能写入，因此可以抵抗篡改。Windows 用户注册表中的 HKCU 可以在没有提升权限的情况下写入，因此将其视为便利默认值而不是执行通道。

63 65

64默认情况下，WSL 仅读取 `/etc/claude-code` 处的 Linux 文件路径。要将您的 Windows 注册表和 `C:\Program Files\ClaudeCode` 策略扩展到同一台机器上的 WSL，请在这些仅限管理员的 Windows 来源之一中设置 [`wslInheritsWindowsSettings: true`](/zh-CN/settings#available-settings)。66默认情况下，WSL 仅读取 `/etc/claude-code` 处的 Linux 文件路径。要将您的 Windows 注册表和 `C:\Program Files\ClaudeCode` 策略扩展到同一台机器上的 WSL，请在这些仅限管理员的 Windows 来源之一中设置 [`wslInheritsWindowsSettings: true`](/zh-CN/settings#available-settings)。

65 67

66无论您选择哪种机制，托管值都优先于用户和项目设置。数组设置（如 `permissions.allow` 和 `permissions.deny`）合并来自所有源的条目，因此开发人员可以扩展托管列表但不能从中删除，但有 [两个例外](/zh-CN/settings#settings-precedence)，其中托管值替换较低层而不是合并：`fallbackModel` 和 `availableModels`。68无论您选择哪种机制，托管值都优先于用户和项目设置。数组设置（如 `permissions.allow` 和 `permissions.deny`）合并来自所有源的条目，因此开发人员可以扩展托管列表但不能从中删除。对于[两个例外](/zh-CN/settings#settings-precedence)，`fallbackModel` 和 `availableModels`，托管值替换较低层而不是合并。

67 69

68请参阅 [Server-managed settings](/zh-CN/server-managed-settings) 和 [Settings files and precedence](/zh-CN/settings#settings-files)。70请参阅 [Server-managed settings](/zh-CN/server-managed-settings) 和 [Settings files and precedence](/zh-CN/settings#settings-files)。

69 71

82| [MCP server control](/zh-CN/managed-mcp) | 限制用户可以添加或连接的 MCP 服务器，或部署固定集合 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly` 或已部署的 `managed-mcp.json` 文件 |84| [MCP server control](/zh-CN/managed-mcp) | 限制用户可以添加或连接的 MCP 服务器，或部署固定集合 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly` 或已部署的 `managed-mcp.json` 文件 |

83| [Plugin marketplace control](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | 限制用户可以添加和安装的市场来源 | `strictKnownMarketplaces`、`blockedMarketplaces` |85| [Plugin marketplace control](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | 限制用户可以添加和安装的市场来源，并拒绝为单次运行侧加载插件、agents 和 MCP 服务器的 CLI 标志 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags` |

99根据您需要报告的内容选择监控。101根据您需要报告的内容选择监控。

100 102

101| 功能 | 您获得的内容 | 可用性 | 从何处开始 |103| 功能 | 您获得的内容 | 可用性 | 从何处开始 |

102| :------------------ | :------------------------- | :---------- | :------------------------------------------ |104| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |

106 108

107云提供商通过 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公开支出。Claude for Teams 和 Enterprise 计划在 [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) 包含使用情况仪表板。109云提供商通过 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公开支出。Claude for Teams 和 Enterprise 计划在 [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) 包含使用情况仪表板。

108 110

120 122

121如果您需要请求级别的审计日志或按数据敏感性路由流量，请在开发人员和您的提供商之间放置 [LLM gateway](/zh-CN/llm-gateway)。有关监管要求和认证，请参阅 [Legal and compliance](/zh-CN/legal-and-compliance)。123如果您需要请求级别的审计日志或按数据敏感性路由流量，请在开发人员和您的提供商之间放置网关：自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 记录带有 IdP 身份的每个请求审计日志，或使用另一个 [LLM gateway](/zh-CN/llm-gateway)。有关监管要求和认证，请参阅 [Legal and compliance](/zh-CN/legal-and-compliance)。

122 124

123<h2 id="verify-and-onboard">125<h2 id="verify-and-onboard">

124 验证和入职126 验证和入职

advisor.md +2 −1

Details

88| ----------------------------------------------- | -------------------- | ---------------------------- |88| ----------------------------------------------- | -------------------- | ---------------------------- |

90| Sonnet 4.6 | Fable、Opus、Sonnet | |90| Sonnet 4.6 | Fable、Opus、Sonnet | |

91| Sonnet 5 | Fable、Opus、Sonnet 5 | Sonnet 4.6 顾问被拒绝 |

92| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 或 Sonnet 顾问被拒绝 |93| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 或 Sonnet 顾问被拒绝 |

93 94

161 162

162* **Claude Code v2.1.98 或更高版本**：运行 `claude update` 进行升级。163* **Claude Code v2.1.98 或更高版本**：运行 `claude update` 进行升级。

163* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。164* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。

164* **支持的主模型**：Opus 4.6 或更高版本、Sonnet 4.6 或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更高版本上也符合条件。165* **支持的主模型**：Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更高版本上也符合条件。

165 166

166<h2 id="turn-the-advisor-off">167<h2 id="turn-the-advisor-off">

167 关闭顾问168 关闭顾问

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

Details

226 模型226 模型

227</h3>227</h3>

228 228

229如果你不设置 `model`，SDK 使用 Claude Code 的默认值，这取决于你的身份验证方法和订阅。显式设置它（例如，`model="claude-sonnet-4-6"`）以固定特定模型或使用较小的模型以获得更快、更便宜的代理。有关可用 ID，请参阅 [models](https://platform.claude.com/docs/en/about-claude/models)。229如果你不设置 `model`，SDK 使用 Claude Code 的默认值，这取决于你的身份验证方法和订阅。显式设置它（例如，`model="claude-sonnet-5"`）以固定特定模型或使用较小的模型以获得更快、更便宜的代理。有关可用 ID，请参阅 [models](https://platform.claude.com/docs/en/about-claude/models)。

230 230

231<h2 id="the-context-window">231<h2 id="the-context-window">

232 上下文窗口232 上下文窗口

agent-sdk/hooks.md +17 −9

Details

214 214

215使用匹配器来过滤您的回调何时触发。`matcher` 字段根据 hook 事件类型匹配不同的值。例如，基于工具的 hooks 匹配工具名称，而 `Notification` hooks 匹配通知类型。请参阅 [Claude Code hooks 参考](/zh-CN/hooks#matcher-patterns)以获取每个事件类型的匹配器值的完整列表。215使用匹配器来过滤您的回调何时触发。`matcher` 字段根据 hook 事件类型匹配不同的值。例如，基于工具的 hooks 匹配工具名称，而 `Notification` hooks 匹配通知类型。请参阅 [Claude Code hooks 参考](/zh-CN/hooks#matcher-patterns)以获取每个事件类型的匹配器值的完整列表。

216 216

217SDK 匹配器遵循与[设置文件中的匹配器](/zh-CN/hooks#matcher-patterns)相同的规则：仅包含字母、数字、`_`、空格、`,` 和 `|` 的匹配器作为精确字符串进行比较，替代项由 `|` 或 `,` 分隔，可选的周围空格，因此 `Write|Edit` 和 `Write, Edit` 各自精确匹配这两个工具。`*` 的匹配器、空字符串或完全省略匹配器会匹配事件的每次出现；包含任何其他字符的匹配器被评估为正则表达式，因此 `^mcp__` 匹配每个 MCP 工具。像 `mcp__memory` 这样的匹配器仅包含字母和下划线，因此它作为精确字符串进行比较，不匹配任何工具；使用 `mcp__memory__.*` 来匹配来自该服务器的每个工具。217SDK 匹配器遵循与[设置文件中的匹配器](/zh-CN/hooks#matcher-patterns)相同的规则。仅包含字母、数字、`_`、`-`、空格、`,` 和 `|` 的匹配器作为精确字符串进行比较，替代项由 `|` 或 `,` 分隔，可选的周围空格，因此 `Write|Edit` 和 `Write, Edit` 各自精确匹配这两个工具，`code-reviewer` 仅匹配该代理类型。`*` 的匹配器、空字符串或完全省略匹配器会匹配事件的每次出现。

218

219包含任何其他字符的匹配器被评估为非锚定正则表达式，因此 `^mcp__` 匹配每个 MCP 工具，`Edit.*` 匹配 `Edit` 和 `NotebookEdit`。当您需要全字符串匹配时，用 `^` 和 `$` 包装正则表达式。

220

221像 `mcp__memory` 或 `mcp__brave-search` 这样的匹配器仅包含精确匹配字符，因此它作为精确字符串进行比较，不匹配任何工具；使用 `mcp__memory__.*` 来匹配来自该服务器的每个工具。

222

223精确匹配集中的连字符需要 Claude Code 运行时 v2.1.195 或更高版本。在较早的版本中，像 `code-reviewer` 这样的带连字符的名称被评估为非锚定正则表达式，必须锚定为 `^code-reviewer$` 才能精确匹配。

218 224

219| 选项 | 类型 | 默认值 | 描述 |225| 选项 | 类型 | 默认值 | 描述 |

220| --------- | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |226| --------- | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

224 230

225尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。请注意，对于基于工具的 hooks，匹配器仅按**工具名称**过滤，而不是按文件路径或其他参数。要按文件路径过滤，请在回调内检查 `tool_input.file_path`。231尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。

232

233对于基于工具的 hooks，匹配器仅按工具名称过滤，而不是按文件路径或其他参数。要按文件路径过滤，请在回调内检查 `tool_input.file_path`。

226 234

227<Tip>235<Tip>

228 **发现工具名称：** 请参阅[工具输入类型](/zh-CN/agent-sdk/typescript#tool-input-types)以获取内置工具名称的完整列表，或添加没有匹配器的 hook 来记录您的会话进行的所有工具调用。236 **发现工具名称：** 请参阅[工具输入类型](/zh-CN/agent-sdk/typescript#tool-input-types)以获取内置工具名称的完整列表，或添加没有匹配器的 hook 来记录您的会话进行的所有工具调用。

240 248

241每个 hook 回调接收三个参数：249每个 hook 回调接收三个参数：

242 250

243* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状（例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`）。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整类型定义。251* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整类型定义。

244 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。252 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。

245 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们仅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。253 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们仅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。

246* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。254* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。

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

259 267

260<Note>268<Note>

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

262</Note>270</Note>

263 271

264<h4 id="asynchronous-output">272<h4 id="asynchronous-output">

265 异步输出273 异步输出

266</h4>274</h4>

267 275

268默认情况下，代理在您的 hook 返回前等待。如果您的 hook 执行副作用（日志记录、发送 webhook）并且不需要影响代理的行为，您可以改为返回异步输出。这告诉代理立即继续，而不等待 hook 完成：276默认情况下，代理在您的 hook 返回前等待。如果您的 hook 执行副作用，例如日志记录或发送 webhook，并且不需要影响代理的行为，您可以改为返回异步输出。这告诉代理立即继续，而不等待 hook 完成：

269 277

270<CodeGroup>278<CodeGroup>

271 ```python Python theme={null}279 ```python Python theme={null}

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

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

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

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

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

787 795

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

789 匹配器未按预期过滤797 匹配器未按预期过滤

790</h3>798</h3>

791 799

792匹配器仅匹配**工具名称**，而不是文件路径或其他参数。要按文件路径过滤，请在您的 hook 内检查 `tool_input.file_path`：800匹配器仅匹配工具名称，而不是文件路径或其他参数。要按文件路径过滤，请在您的 hook 内检查 `tool_input.file_path`：

793 801

794```typescript theme={null}802```typescript theme={null}

795const myHook: HookCallback = async (input, toolUseID, { signal }) => {803const myHook: HookCallback = async (input, toolUseID, { signal }) => {

815 823

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

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

818* 验证匹配器模式不会太宽泛（空匹配器匹配所有工具）826* 验证匹配器模式不会太宽泛：空匹配器匹配所有工具

819 827

820<h3 id="modified-input-not-applied">828<h3 id="modified-input-not-applied">

821 修改的输入未应用829 修改的输入未应用

841 Python 中不可用会话 hooks849 Python 中不可用会话 hooks

842</h3>850</h3>

843 851

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

845 853

846<CodeGroup>854<CodeGroup>

847 ```python Python theme={null}855 ```python Python theme={null}

agent-sdk/hosting.md +1 −1

Details

209 209

210* **仅记录**：`SessionStore` 镜像记录，不镜像 `CLAUDE.md` 内存文件或其他工作目录工件。挂载共享卷或单独同步这些文件。210* **仅记录**：`SessionStore` 镜像记录，不镜像 `CLAUDE.md` 内存文件或其他工作目录工件。挂载共享卷或单独同步这些文件。

211* **镜像，不替换**：子进程首先写入本地磁盘，存储接收每个批次的副本。本地写入保持权威性。211* **镜像，不替换**：子进程首先写入本地磁盘，存储接收每个批次的副本。本地写入保持权威性。

212* **`mirror_error` 消息**：如果存储拒绝或超时，SDK 发出 `{ type: "system", subtype: "mirror_error" }` 消息并继续查询而不重试。如果存储持久性很重要，请对这些消息进行告警。212* **`mirror_error` 消息**：存储拒绝的批次最多重试三次，每次重试前有短暂的退避；超时的调用不会重试。如果批次仍然失败，SDK 会丢弃它，发出 `{ type: "system", subtype: "mirror_error" }` 消息，并继续查询。如果存储持久性很重要，请对这些消息进行告警。

213 213

214<h3 id="observability">214<h3 id="observability">

215 可观测性215 可观测性

agent-sdk/permissions.md +6 −2

Details

44 </Step>44 </Step>

45</Steps>45</Steps>

46 46

47<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="五步权限评估流程图，与上述步骤相匹配：工具请求通过 hooks、拒绝规则、权限模式、允许规则和 canUseTool。Hooks、拒绝规则和 canUseTool 可以路由到阻止；权限模式绕过、允许规则和 canUseTool 可以路由到执行。" width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />47<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="六步权限评估流程图，与上述步骤相匹配：工具请求通过 hooks、拒绝规则、询问规则、权限模式、允许规则和 canUseTool。Hooks、拒绝规则和 canUseTool 可以路由到阻止；权限模式绕过、允许规则和 canUseTool 可以路由到执行；询问规则路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

48 48

49本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：49本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：

50 50

51* **Hooks：** 运行自定义代码以允许、拒绝或修改工具请求。请参阅 [使用 hooks 控制执行](/zh-CN/agent-sdk/hooks)。51* **Hooks：** 运行自定义代码以允许、拒绝或修改工具请求。请参阅 [使用 hooks 控制执行](/zh-CN/agent-sdk/hooks)。

~~52* **canUseTool 回调：** 在运行时提示用户批准。请参阅 [处理批准和用户输入](/zh-CN/agent-sdk/user-input)。~~52* **canUseTool 回调：** 在运行时提示用户批准，当没有更早的步骤解决调用时。请参阅 [处理批准和用户输入](/zh-CN/agent-sdk/user-input)。

53 53

54<h2 id="allow-and-deny-rules">54<h2 id="allow-and-deny-rules">

55 允许和拒绝规则55 允许和拒绝规则

66 66

67允许规则仅在字面 `mcp__<server>__` 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：`mcp__puppeteer__*` 匹配来自 `puppeteer` 服务器的每个工具，`mcp__github__get_*` 匹配其 `get_` 工具。未锚定的条目如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]` 被忽略并显示启动警告，不会自动批准任何内容。67允许规则仅在字面 `mcp__<server>__` 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：`mcp__puppeteer__*` 匹配来自 `puppeteer` 服务器的每个工具，`mcp__github__get_*` 匹配其 `get_` 工具。未锚定的条目如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]` 被忽略并显示启动警告，不会自动批准任何内容。

68 68

69<Warning>

70 **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过您的 `canUseTool` 回调，因此您在那里放置的权限检查对该工具被静默绕过。覆盖范围取决于条目的形式：像 `Read` 或 `mcp__github__get_issue` 这样的裸名称自动批准对该工具的每个调用，而像 `Bash(ls *)` 这样的范围化规则仅自动批准匹配的调用，其他 `Bash` 调用仍然继续进行回调。对于必须在每个工具调用上运行的检查，请使用 [`PreToolUse` hook](/zh-CN/agent-sdk/hooks)：hooks 在每个其他步骤之前运行，hook 拒绝甚至在 `bypassPermissions` 模式中也适用。

71</Warning>

69对于锁定的代理，将 `allowedTools` 与 `permissionMode: "dontAsk"` 配对。列出的工具被批准；其他任何内容都被直接拒绝，而不是提示：73对于锁定的代理，将 `allowedTools` 与 `permissionMode: "dontAsk"` 配对。列出的工具被批准；其他任何内容都被直接拒绝，而不是提示：

70 74

71```typescript theme={null}75```typescript theme={null}

agent-sdk/python.md +14 −9

Details

750 750

751 751

752async def main():752async def main():

753 options = ClaudeAgentOptions(753 # 不要同时在 allowed_tools 中列出受限工具：allow 规则在 can_use_tool 运行之前批准调用

754 can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"]754 options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

755 )

756 755

757 async with ClaudeSDKClient(options=options) as client:756 async with ClaudeSDKClient(options=options) as client:

758 await client.query("Update the system config file")757 await client.query("Update the system config file")

886 fork_session: bool = False885 fork_session: bool = False

887 agents: dict[str, AgentDefinition] | None = None886 agents: dict[str, AgentDefinition] | None = None

888 setting_sources: list[SettingSource] | None = None887 setting_sources: list[SettingSource] | None = None

888 skills: list[str] | Literal["all"] | None = None

889 sandbox: SandboxSettings | None = None889 sandbox: SandboxSettings | None = None

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

891 max_thinking_tokens: int | None = None # Deprecated: use thinking instead891 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

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

961* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以无限期重试容量错误。961* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以无限期重试容量错误。

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 启动的子代理的停滞监视器。默认 `600000`。在每个流事件时重置；停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父代理。不适用于同步子代理。962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 启动的子代理的停滞监视器。默认 `600000`。在每个流事件时重置；停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父代理。不适用于同步子代理。

963* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应体停止流式传输时中止请求。当 `CLAUDE_ENABLE_STREAM_WATCHDOG` 未设置时，默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。963* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应体停止流式传输时中止请求。监视器对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。

964 964

965<h3 id="outputformat">965<h3 id="outputformat">

966 `OutputFormat`966 `OutputFormat`

1206 "low", # Minimal thinking, fastest responses1206 "low", # Minimal thinking, fastest responses

1207 "medium", # Moderate thinking1207 "medium", # Moderate thinking

1208 "high", # Deep reasoning1208 "high", # Deep reasoning

1209 "xhigh", # Extended reasoning (Opus 4.8 and Opus 4.7; falls back to "high" on other models)1209 "xhigh", # Extended reasoning; falls back to "high" on models that don't support it

1210 "max", # Maximum effort1210 "max", # Maximum effort

1211]1211]

1212```1212```

1231 1231

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

1233 1233

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

1235

1234<h3 id="toolpermissioncontext">1236<h3 id="toolpermissioncontext">

1235 `ToolPermissionContext`1237 `ToolPermissionContext`

1236</h3>1238</h3>

1432与 `ClaudeAgentOptions` 中的 `betas` 字段一起使用以启用测试功能。1434与 `ClaudeAgentOptions` 中的 `betas` 字段一起使用以启用测试功能。

1433 1435

1434<Warning>1436<Warning>

1435 `context-1m-2025-08-07` 测试版自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此标头无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需测试版标头。1437 `context-1m-2025-08-07` 测试版自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此标头无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需测试版标头。

1436</Warning>1438</Warning>

1437 1439

1438<h3 id="mcpsdkserverconfig">1440<h3 id="mcpsdkserverconfig">

2681 2683

2682**工具名称：** `Monitor`2684**工具名称：** `Monitor`

2683 2685

2684运行后台脚本并将每个 stdout 行作为事件传递给 Claude，以便它可以做出反应而无需轮询。Monitor 遵循与 Bash 相同的权限规则。见 [Monitor 工具参考](/zh-CN/tools-reference#monitor-tool) 了解行为和提供商可用性。2686运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 中的一个。

2687

2688当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。{/* min-version: 2.1.195 */}`ws` 源需要 Claude Code v2.1.195 或更高版本。见 [Monitor 工具参考](/zh-CN/tools-reference#monitor-tool) 了解行为和提供商可用性。

2685 2689

2686**输入：**2690**输入：**

2687 2691

2688```python theme={null}2692```python theme={null}

2689{2693{

2690 "command": str, # Shell 脚本；每个 stdout 行是一个事件，退出结束监视2694 "command": str | None, # Shell 脚本；每个 stdout 行是一个事件，退出结束监视

2695 "ws": dict | None, # WebSocket 源：{"url": str, "protocols": list[str] | None}；每个文本帧是一个事件

2691 "description": str, # 在通知中显示的简短描述2696 "description": str, # 在通知中显示的简短描述

2692 "timeout_ms": int | None, # 在此截止时间后杀死（默认 300000，最大 3600000）2697 "timeout_ms": int | None, # 在此截止时间后杀死（默认 300000，最大 3600000）

2693 "persistent": bool | None, # 在会话的生命周期内运行；使用 TaskStop 停止2698 "persistent": bool | None, # 在会话的生命周期内运行；使用 TaskStop 停止

agent-sdk/quickstart.md +39 −26

Details

41 为你的语言安装 Agent SDK 包：41 为你的语言安装 Agent SDK 包：

42 42

43 <Tabs>43 <Tabs>

~~44 <Tab title="TypeScript">~~44 <Tab title="TypeScript（新项目）">

45 ```bash theme={null}45 ```bash theme={null}

46 npm init -y

47 npm pkg set type=module

46 npm install @anthropic-ai/claude-agent-sdk48 npm install @anthropic-ai/claude-agent-sdk

49 npm install --save-dev tsx

47 ```50 ```

52 在 `package.json` 中设置 `"type": "module"` 让你的代理脚本使用顶级 `await`，而 [tsx](https://tsx.is) 直接运行 TypeScript 文件。

48 </Tab>53 </Tab>

49 54

~~50 <Tab title="Python (uv)">~~55 <Tab title="TypeScript（现有项目）">

56 ```bash theme={null}

57 npm install @anthropic-ai/claude-agent-sdk

58 npm install --save-dev tsx

59 ```

61 [tsx](https://tsx.is) 直接运行 TypeScript 文件。如果你的项目使用 CommonJS，将你的代理脚本命名为 `agent.mts` 而不是 `agent.ts`。`.mts` 扩展名使 tsx 将文件视为 ES 模块，所以顶级 `await` 可以工作，而无需将整个项目转换为 ES 模块。在本快速开始中后面的创建和运行步骤中使用 `agent.mts` 代替 `agent.ts`。

62 </Tab>

64 <Tab title="Python（uv）">

51 [uv](https://docs.astral.sh/uv/) 是一个快速的 Python 包管理器，可以自动处理虚拟环境：65 [uv](https://docs.astral.sh/uv/) 是一个快速的 Python 包管理器，可以自动处理虚拟环境：

52 66

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

56 ```70 ```

57 </Tab>71 </Tab>

58 72

~~59 <Tab title="Python (pip)">~~73 <Tab title="Python（pip）">

60 创建并激活虚拟环境，然后安装该包。74 创建并激活虚拟环境，然后安装该包。

61 75

62 在 macOS 或 Linux 上：76 在 macOS 或 Linux 上：

85 </Step>99 </Step>

86 100

87 <Step title="设置你的 API 密钥">101 <Step title="设置你的 API 密钥">

~~88 从 [Claude 控制台](https://platform.claude.com/)获取 API 密钥，然后在你的项目目录中创建一个 `.env` 文件：~~102 从 [Claude 控制台](https://platform.claude.com/)获取 API 密钥，然后在你将运行代理的 shell 中将其设置为环境变量：

89 103

104 <Tabs>

105 <Tab title="macOS / Linux">

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

~~91 ANTHROPIC_API_KEY=your-api-key~~107 export ANTHROPIC_API_KEY=your-api-key

92 ```108 ```

109 </Tab>

110

111 <Tab title="Windows（PowerShell）">

112 ```powershell theme={null}

113 $env:ANTHROPIC_API_KEY = "your-api-key"

114 ```

115 </Tab>

116 </Tabs>

117

118 SDK 从运行你的代理的进程的环境中读取密钥；它不会自动加载 `.env` 文件。如果你将密钥保存在 `.env` 文件中，请自己加载它，例如使用 `dotenv` 包，然后再调用 SDK。

93 119

94 SDK 还支持通过第三方 API 提供商进行身份验证：120 SDK 还支持通过第三方 API 提供商进行身份验证：

95 121

133 构建一个查找和修复错误的代理159 构建一个查找和修复错误的代理

134</h2>160</h2>

135 161

136如果你使用 Python SDK，创建 `agent.py`，或者如果使用 TypeScript，创建 `agent.ts`：162如果你使用 Python SDK，创建 `agent.py`，或者如果使用 TypeScript，创建 `agent.ts`。如果你现有的项目使用 CommonJS，请改用 `agent.mts`：

137 163

138<CodeGroup>164<CodeGroup>

139 ```python Python theme={null}165 ```python Python theme={null}

218 ```bash theme={null}244 ```bash theme={null}

219 npx tsx agent.ts245 npx tsx agent.ts

220 ```246 ```

247

248 如果你将脚本命名为 `agent.mts`，请改为运行 `npx tsx agent.mts`。

221 </Tab>249 </Tab>

222 250

223 <Tab title="Python (uv)">251 <Tab title="Python（uv）">

224 ```bash theme={null}252 ```bash theme={null}

225 uv run agent.py253 uv run agent.py

226 ```254 ```

227 </Tab>255 </Tab>

228 256

229 <Tab title="Python (pip)">257 <Tab title="Python（pip）">

230 使用你仍然激活的虚拟环境：258 使用你仍然激活的虚拟环境：

231 259

232 ```bash theme={null}260 ```bash theme={null}

235 </Tab>263 </Tab>

236</Tabs>264</Tabs>

237 265

238运行后，检查 `utils.py`。你会看到处理空列表和空用户的防御性代码。你的代理自主地：266运行时，代理会打印其推理和它调用的每个工具，最后以 `Done: success` 结束。运行后，检查 `utils.py`。你会看到处理空列表和空用户的防御性代码。你的代理自主地：

239 267

2401. **读取** `utils.py` 以理解代码2681. **读取** `utils.py` 以理解代码

2412. **分析**了逻辑并识别了会导致崩溃的边界情况2692. **分析**了逻辑并识别了会导致崩溃的边界情况

244这就是 Agent SDK 的与众不同之处：Claude 直接执行工具，而不是要求你实现它们。272这就是 Agent SDK 的与众不同之处：Claude 直接执行工具，而不是要求你实现它们。

245 273

246<Note>274<Note>

247 如果你看到"API key not found"，请确保你已在 `.env` 文件或 shell 环境中设置了 `ANTHROPIC_API_KEY` 环境变量。有关更多帮助，请参阅[完整故障排除指南](/zh-CN/troubleshooting)。275 如果你看到"API key not found"，请确保你已在运行代理的 shell 中设置了 `ANTHROPIC_API_KEY` 环境变量。SDK 不会自动加载 `.env` 文件。有关更多帮助，请参阅[完整故障排除指南](/zh-CN/troubleshooting)。

248</Note>276</Note>

249 277

250<h3 id="try-other-prompts">278<h3 id="try-other-prompts">

342| 模式 | 行为 | 用例 |370| 模式 | 行为 | 用例 |

343| -------------------- | ------------------------------------------------------------------------------------------ | -------------- |371| -------------------- | ------------------------------------------------------------------------------------------ | -------------- |

373| `plan` | 运行只读工具；文件编辑永远不会自动批准，并到达你的 `canUseTool` 回调 | 在批准执行前确定任务范围 |

349 378

350上面的示例使用 `acceptEdits` 模式，它自动批准文件操作，以便代理可以在没有交互式提示的情况下运行。如果你想提示用户批准，使用 `default` 模式并提供一个 [`canUseTool` 回调](/zh-CN/agent-sdk/user-input)来收集用户输入。为了获得更多控制，请参阅[权限](/zh-CN/agent-sdk/permissions)。379上面的示例使用 `acceptEdits` 模式，它自动批准文件操作，以便代理可以在没有交互式提示的情况下运行。如果你想提示用户批准，使用 `default` 模式并提供一个 [`canUseTool` 回调](/zh-CN/agent-sdk/user-input)来收集用户输入。为了获得更多控制，请参阅[权限](/zh-CN/agent-sdk/permissions)。

351 380

352<h2 id="troubleshooting">

353 故障排除

354</h2>

~~355~~

356<h3 id="api-error-thinking-type-enabled-is-not-supported-for-this-model">

357 API 错误 `thinking.type.enabled` 不支持此模型

358</h3>

~~359~~

360Claude Opus 4.7 用 `thinking.type.adaptive` 替换了 `thinking.type.enabled`。当你选择 `claude-opus-4-7` 时，较旧的 Agent SDK 版本会失败，出现以下 API 错误：

~~361~~

362```text theme={null}

363API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

364```

~~365~~

366升级到 Agent SDK v0.2.111 或更高版本以使用 Opus 4.7。

~~367~~

368<h2 id="next-steps">381<h2 id="next-steps">

369 后续步骤382 后续步骤

370</h2>383</h2>

agent-sdk/session-storage.md +1 −1

Details

235 镜像写入是尽力而为的235 镜像写入是尽力而为的

236</h3>236</h3>

237 237

238如果 `append()` 拒绝或超时，错误会被记录，一个 `{ type: "system", subtype: "mirror_error" }` 消息被发出到迭代器中，查询继续。本地记录已经在磁盘上持久化，所以存储中断不会中断代理或在本地丢失数据。失败的批次不会重试，因此如果您需要检测存储数据丢失，请监视 `mirror_error`。238如果 `append()` 拒绝，SDK 会以短退避重试该批次最多两次，总共最多三次尝试。超时的调用不会重试，因为原始调用可能仍然会成功。如果批次仍然失败，错误会被记录，一个 `{ type: "system", subtype: "mirror_error" }` 消息被发出到迭代器中，批次被丢弃，查询继续。本地记录已经在磁盘上持久化，所以存储中断不会中断代理或在本地丢失数据。监视 `mirror_error` 如果您需要检测存储数据丢失。因为重试的批次可以重新传递已经成功的条目，请在您的 `append()` 实现中按 `entry.uuid` 进行去重。

239 239

240<h3 id="getsessionmessages-returns-the-post-compaction-chain">240<h3 id="getsessionmessages-returns-the-post-compaction-chain">

241 `getSessionMessages` 返回后压缩链241 `getSessionMessages` 返回后压缩链

agent-sdk/slash-commands.md +141 −25

Details

24 })) {24 })) {

25 if (message.type === "system" && message.subtype === "init") {25 if (message.type === "system" && message.subtype === "init") {

26 console.log("Available slash commands:", message.slash_commands);26 console.log("Available slash commands:", message.slash_commands);

~~27 // Example output: ["clear", "compact", "context", "usage"]~~27 // 包括内置命令加上捆绑的 skills，例如：

28 // ["clear", "compact", "context", "usage", "code-review", "verify", ...]

28 }29 }

29 }30 }

30 ```31 ```

38 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):39 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):

39 if isinstance(message, SystemMessage) and message.subtype == "init":40 if isinstance(message, SystemMessage) and message.subtype == "init":

40 print("Available slash commands:", message.data["slash_commands"])41 print("Available slash commands:", message.data["slash_commands"])

~~41 # Example output: ["clear", "compact", "context", "usage"]~~42 # 包括内置命令加上捆绑的 skills，例如：

43 # ["clear", "compact", "context", "usage", "code-review", "verify", ...]

42 44

43 45

44 asyncio.run(main())46 asyncio.run(main())

49 发送 Slash Commands51 发送 Slash Commands

50</h2>52</h2>

51 53

~~52通过在您的提示字符串中包含 slash commands 来发送它们，就像常规文本一样：~~54通过在您的提示字符串中包含 slash commands 来发送它们，就像常规文本一样。作用于对话历史的命令，例如 `/compact`，需要先前的消息来处理，因此下面的示例首先提出一个问题，然后将命令作为后续发送到同一对话：

53 55

54<CodeGroup>56<CodeGroup>

55 ```typescript TypeScript theme={null}57 ```typescript TypeScript theme={null}

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

57 59

~~58 // Send a slash command~~60 // Build up conversation history first

61 try {

59 for await (const message of query({62 for await (const message of query({

~~60 prompt: "/compact",~~63 prompt: "What does the README in this directory cover?",

~~61 options: { maxTurns: 1 }~~64 options: { maxTurns: 2 }

62 })) {65 })) {

63 if (message.type === "result" && message.subtype === "success") {66 if (message.type === "result" && message.subtype === "success") {

~~64 console.log("Command executed:", message.result);~~67 console.log(message.result);

68 }

69 }

70 } catch (error) {

71 // A single-shot query() throws after yielding an error result,

72 // so the follow-up query below still runs.

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

74 }

76 // Send a slash command as a follow-up to the same conversation

77 for await (const message of query({

78 prompt: "/compact",

79 options: { continue: true, maxTurns: 1 }

80 })) {

81 if (message.type === "result") {

82 console.log("Command executed, result subtype:", message.subtype);

83 // Example output: Command executed, result subtype: success

65 }84 }

66 }85 }

67 ```86 ```

72 91

73 92

74 async def main():93 async def main():

~~75 # Send a slash command~~94 # Build up conversation history first

~~76 async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)):~~95 try:

96 async for message in query(

97 prompt="What does the README in this directory cover?",

98 options=ClaudeAgentOptions(max_turns=2),

99 ):

100 if isinstance(message, ResultMessage) and message.subtype == "success":

101 print(message.result)

102 except Exception as error:

103 # A single-shot query() raises after yielding an error result,

104 # so the follow-up query below still runs.

105 print(f"Session ended with an error: {error}")

106

107 # Send a slash command as a follow-up to the same conversation

108 async for message in query(

109 prompt="/compact",

110 options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),

111 ):

77 if isinstance(message, ResultMessage):112 if isinstance(message, ResultMessage):

~~78 print("Command executed:", message.result)~~113 print("Command executed, result subtype:", message.subtype)

114 # Example output: Command executed, result subtype: success

79 115

80 116

81 asyncio.run(main())117 asyncio.run(main())

82 ```118 ```

83</CodeGroup>119</CodeGroup>

84 120

121<Note>

122 查询可能以错误结果结束，例如当 `maxTurns` / `max_turns` 限制在工作完成前被达到时。最终结果消息随后具有 `is_error: true` 和错误子类型（例如 `error_max_turns`）而不是 `success`。

123

124 在产生该最终结果消息后，SDK 会抛出错误，因为 CLI 进程以非零代码退出。

125

126 如果您的命令可能达到限制，请在 TypeScript 中将循环包装在 `try`/`catch` 中或在 Python 中使用 `try`/`except`，如 [Single Message Input](/zh-CN/agent-sdk/streaming-vs-single-mode#single-message-input) 中所示，或设置 `maxTurns` 足够高以完成工作。在 Python 中，捕获 `Exception`：SDK 将错误结果作为普通 `Exception` 呈现。

127</Note>

128

85<h2 id="common-slash-commands">129<h2 id="common-slash-commands">

86 常见的 Slash Commands130 常见的 Slash Commands

87</h2>131</h2>

90 `/compact` - 压缩对话历史134 `/compact` - 压缩对话历史

91</h3>135</h3>

92 136

~~93`/compact` 命令通过总结较早的消息同时保留重要上下文来减少您的对话历史的大小：~~137`/compact` 命令通过总结较早的消息同时保留重要上下文来减少您的对话历史的大小。压缩需要至少有两次先前交互的现有对话来进行总结。此示例首先进行对话，然后压缩它并读取报告结果的 `compact_boundary` 系统消息：

94 138

95<CodeGroup>139<CodeGroup>

96 ```typescript TypeScript theme={null}140 ```typescript TypeScript theme={null}

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

98 142

143 // Compaction needs existing history, so have a conversation first

144 try {

145 for await (const message of query({

146 prompt: "Explain what this project does",

147 options: { maxTurns: 2 }

148 })) {

149 if (message.type === "result" && message.subtype === "success") {

150 console.log(message.result);

151 }

152 }

153 } catch (error) {

154 // A single-shot query() throws after yielding an error result,

155 // so the follow-up query below still runs.

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

157 }

158

159 // Compact the same conversation

99 for await (const message of query({160 for await (const message of query({

100 prompt: "/compact",161 prompt: "/compact",

101 options: { maxTurns: 1 }162 options: { continue: true, maxTurns: 1 }

102 })) {163 })) {

103 if (message.type === "system" && message.subtype === "compact_boundary") {164 if (message.type === "system" && message.subtype === "compact_boundary") {

104 console.log("Compaction completed");165 console.log("Compaction completed");

105 console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);166 console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);

106 console.log("Trigger:", message.compact_metadata.trigger);167 console.log("Trigger:", message.compact_metadata.trigger);

168 // Example output:

169 // Compaction completed

170 // Pre-compaction tokens: 1842

171 // Trigger: manual

107 }172 }

108 }173 }

109 ```174 ```

110 175

111 ```python Python theme={null}176 ```python Python theme={null}

112 import asyncio177 import asyncio

113 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage178 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage

114 179

115 180

116 async def main():181 async def main():

117 async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)):182 # Compaction needs existing history, so have a conversation first

183 try:

184 async for message in query(

185 prompt="Explain what this project does",

186 options=ClaudeAgentOptions(max_turns=2),

187 ):

188 if isinstance(message, ResultMessage) and message.subtype == "success":

189 print(message.result)

190 except Exception as error:

191 # A single-shot query() raises after yielding an error result,

192 # so the follow-up query below still runs.

193 print(f"Session ended with an error: {error}")

194

195 # Compact the same conversation

196 async for message in query(

197 prompt="/compact",

198 options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),

199 ):

118 if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":200 if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":

119 print("Compaction completed")201 print("Compaction completed")

120 print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])202 print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])

121 print("Trigger:", message.data["compact_metadata"]["trigger"])203 print("Trigger:", message.data["compact_metadata"]["trigger"])

204 # Example output:

205 # Compaction completed

206 # Pre-compaction tokens: 1842

207 # Trigger: manual

122 208

123 209

124 asyncio.run(main())210 asyncio.run(main())

125 ```211 ```

126</CodeGroup>212</CodeGroup>

127 213

214<Note>

215 `compact_boundary` 消息仅在压缩运行时到达。如果没有要总结的内容，`/compact` 会报告原因而不是抛出异常：运行仍然以 `success` 结果结束，不会发出 `compact_boundary` 消息，结果文本会携带消息，例如在单次简短交互后显示 `Not enough messages to compact.`。全新的一次性 `query()` 调用以空上下文开始，因此请在具有先前轮次的会话中使用此模式，例如在[流式输入模式](/zh-CN/agent-sdk/streaming-vs-single-mode)中或恢复会话时。

216</Note>

217

128<h3 id="/clear-reset-conversation-context">218<h3 id="/clear-reset-conversation-context">

129 `/clear` - 重置对话上下文219 `/clear` - 重置对话上下文

130</h3>220</h3>

170 基本示例260 基本示例

171</h4>261</h4>

172 262

173创建 `.claude/commands/refactor.md`：263在您的项目中创建 `.claude/commands` 目录（如果不存在），然后创建 `.claude/commands/refactor.md`：

174 264

175```markdown theme={null}265```markdown theme={null}

176Refactor the selected code to improve readability and maintainability.266Refactor the selected code to improve readability and maintainability.

189---279---

190allowed-tools: Read, Grep, Glob280allowed-tools: Read, Grep, Glob

191description: Run security vulnerability scan281description: Run security vulnerability scan

192model: claude-opus-4-7282model: claude-opus-4-8

193---283---

194 284

195Analyze the codebase for security vulnerabilities including:285Analyze the codebase for security vulnerabilities including:

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

211 301

212 // Use a custom command302 // Use a custom command

303 try {

213 for await (const message of query({304 for await (const message of query({

214 prompt: "/refactor src/auth/login.ts",305 prompt: "/refactor src/auth/login.ts",

215 options: { maxTurns: 3 }306 options: { maxTurns: 3 }

218 console.log("Refactoring suggestions:", message.message);309 console.log("Refactoring suggestions:", message.message);

219 }310 }

220 }311 }

312 } catch (error) {

313 // A single-shot query() throws after yielding an error result,

314 // so the second query below still runs.

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

316 }

221 317

222 // Custom commands appear in the slash_commands list318 // Custom commands appear in the slash_commands list

223 for await (const message of query({319 for await (const message of query({

225 options: { maxTurns: 1 }321 options: { maxTurns: 1 }

226 })) {322 })) {

227 if (message.type === "system" && message.subtype === "init") {323 if (message.type === "system" && message.subtype === "init") {

228 // Will include both built-in and custom commands

229 console.log("Available commands:", message.slash_commands);324 console.log("Available commands:", message.slash_commands);

230 // Example: ["clear", "compact", "context", "usage", "refactor", "security-check"]325 // Includes built-in commands plus bundled skills and your custom commands, for example:

326 // ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]

231 }327 }

232 }328 }

233 ```329 ```

239 335

240 async def main():336 async def main():

241 # Use a custom command337 # Use a custom command

338 try:

242 async for message in query(339 async for message in query(

243 prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3)340 prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3)

244 ):341 ):

246 for block in message.content:343 for block in message.content:

247 if hasattr(block, "text"):344 if hasattr(block, "text"):

248 print("Refactoring suggestions:", block.text)345 print("Refactoring suggestions:", block.text)

346 except Exception as error:

347 # A single-shot query() raises after yielding an error result,

348 # so the second query below still runs.

349 print(f"Session ended with an error: {error}")

249 350

250 # Custom commands appear in the slash_commands list351 # Custom commands appear in the slash_commands list

251 async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)):352 async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)):

252 if isinstance(message, SystemMessage) and message.subtype == "init":353 if isinstance(message, SystemMessage) and message.subtype == "init":

253 # Will include both built-in and custom commands

254 print("Available commands:", message.data["slash_commands"])354 print("Available commands:", message.data["slash_commands"])

255 # Example: ["clear", "compact", "context", "usage", "refactor", "security-check"]355 # Includes built-in commands plus bundled skills and your custom commands, for example:

356 # ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]

256 357

257 358

258 asyncio.run(main())359 asyncio.run(main())

384 实际示例485 实际示例

385</h3>486</h3>

386 487

387<h4 id="code-review-command">488<h4 id="pull-request-review-command">

388 代码审查命令489 Pull Request 审查命令

389</h4>490</h4>

390 491

391创建 `.claude/commands/code-review.md`：492创建 `.claude/commands/review-pr.md`：

392 493

393```markdown theme={null}494```markdown theme={null}

394---495---

414Provide specific, actionable feedback organized by priority.515Provide specific, actionable feedback organized by priority.

415```516```

416 517

518<Note>

519 Claude Code 包含捆绑的 `code-review` 和 `verify` skills。如果您以其中之一的名称命名自定义命令，例如 `.claude/commands/code-review.md`，您的命令会覆盖捆绑的 skill，`slash_commands` 列表中该名称仅出现一次。

520</Note>

521

417<h4 id="test-runner-command">522<h4 id="test-runner-command">

418 测试运行器命令523 测试运行器命令

419</h4>524</h4>

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

443 548

444 // Run code review549 // Run code review

550 try {

445 for await (const message of query({551 for await (const message of query({

446 prompt: "/code-review",552 prompt: "/review-pr",

447 options: { maxTurns: 3 }553 options: { maxTurns: 3 }

448 })) {554 })) {

449 // Process review feedback555 // Process review feedback

450 }556 }

557 } catch (error) {

558 // A single-shot query() throws after yielding an error result,

559 // so the second query below still runs.

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

561 }

451 562

452 // Run specific tests563 // Run specific tests

453 for await (const message of query({564 for await (const message of query({

465 576

466 async def main():577 async def main():

467 # Run code review578 # Run code review

468 async for message in query(prompt="/code-review", options=ClaudeAgentOptions(max_turns=3)):579 try:

580 async for message in query(prompt="/review-pr", options=ClaudeAgentOptions(max_turns=3)):

469 # Process review feedback581 # Process review feedback

470 pass582 pass

583 except Exception as error:

584 # A single-shot query() raises after yielding an error result,

585 # so the second query below still runs.

586 print(f"Session ended with an error: {error}")

471 587

472 # Run specific tests588 # Run specific tests

473 async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)):589 async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)):

agent-sdk/subagents.md +18 −1

Details

71 71

72使用 `agents` 参数直接在代码中定义子代理。此示例创建两个子代理：一个具有只读访问权限的代码审查员和一个可以执行命令的测试运行器。Claude 通过 `Agent` 工具调用子代理，因此在 `allowedTools` 中包含 `Agent` 以自动批准子代理调用，无需权限提示。72使用 `agents` 参数直接在代码中定义子代理。此示例创建两个子代理：一个具有只读访问权限的代码审查员和一个可以执行命令的测试运行器。Claude 通过 `Agent` 工具调用子代理，因此在 `allowedTools` 中包含 `Agent` 以自动批准子代理调用，无需权限提示。

73 73

74本页面上的大多数示例仅打印最终结果。要确认 Claude 委派给了子代理而不是直接回答，请参阅[检测子代理调用](#detecting-subagent-invocation)。

74<CodeGroup>76<CodeGroup>

75 ```python Python theme={null}77 ```python Python theme={null}

76 import asyncio78 import asyncio

195 197

196在 Python SDK 中，这些字段名称使用 camelCase 以匹配线路格式。有关详细信息，请参阅 [`AgentDefinition` 参考](/zh-CN/agent-sdk/python#agentdefinition)。198在 Python SDK 中，多字词字段名称（如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼写以匹配线路格式，而不是遵循 Python 的 snake\_case 约定。有关详细信息，请参阅 [`AgentDefinition` 参考](/zh-CN/agent-sdk/python#agentdefinition)。

197 199

198<Note>200<Note>

199 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位于主代理下方五个级别的子代理无法生成进一步的子代理，无论其是在前台还是后台运行。要防止子代理生成其他子代理，请从其 `tools` 数组中省略 `Agent` 或将其添加到 `disallowedTools`。有关完整的深度规则，请参阅[嵌套子代理](/zh-CN/sub-agents#spawn-nested-subagents)。201 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位于主代理下方五个级别的子代理无法生成进一步的子代理，无论其是在前台还是后台运行。要防止子代理生成其他子代理，请从其 `tools` 数组中省略 `Agent` 或将其添加到 `disallowedTools`。有关完整的深度规则，请参阅[嵌套子代理](/zh-CN/sub-agents#spawn-nested-subagents)。

469 session_id = None471 session_id = None

470 472

471 # First invocation - run the endpoint-finder subagent473 # First invocation - run the endpoint-finder subagent

474 try:

472 async for message in query(475 async for message in query(

473 prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",476 prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",

474 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),477 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),

483 # Print the final result486 # Print the final result

484 if hasattr(message, "result"):487 if hasattr(message, "result"):

485 print(message.result)488 print(message.result)

489 except Exception as error:

490 # A single-shot query() raises after yielding an error result,

491 # so session_id and agent_id have already been captured by the loop above.

492 print(f"Session ended with an error: {error}")

486 493

487 # Second invocation - resume and ask follow-up494 # Second invocation - resume and ask follow-up

488 if agent_id and session_id:495 if agent_id and session_id:

494 ):501 ):

495 if hasattr(message, "result"):502 if hasattr(message, "result"):

496 print(message.result)503 print(message.result)

504 else:

505 print("No agentId found in the first query, so there is no subagent to resume.")

497 506

498 507

499 asyncio.run(main())508 asyncio.run(main())

522 let sessionId: string | undefined;531 let sessionId: string | undefined;

523 532

524 // First invocation - run the endpoint-finder subagent533 // First invocation - run the endpoint-finder subagent

534 try {

525 for await (const message of query({535 for await (const message of query({

526 prompt: "Use the endpoint-finder agent to find all API endpoints in this codebase",536 prompt: "Use the endpoint-finder agent to find all API endpoints in this codebase",

527 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents }537 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents }

534 // Print the final result544 // Print the final result

535 if ("result" in message) console.log(message.result);545 if ("result" in message) console.log(message.result);

536 }546 }

547 } catch (error) {

548 // A single-shot query() throws after yielding an error result,

549 // so sessionId and agentId have already been captured by the loop above.

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

551 }

537 552

538 // Second invocation - resume and ask follow-up553 // Second invocation - resume and ask follow-up

539 if (agentId && sessionId) {554 if (agentId && sessionId) {

543 })) {558 })) {

544 if ("result" in message) console.log(message.result);559 if ("result" in message) console.log(message.result);

545 }560 }

561 } else {

562 console.log("No agentId found in the first query, so there is no subagent to resume.");

546 }563 }

547 ```564 ```

548</CodeGroup>565</CodeGroup>

agent-sdk/typescript.md +22 −9

Details

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

554* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以无限期重试容量错误。554* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以无限期重试容量错误。

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 启动的子代理的停滞监视程序。默认 `600000`。在每个流事件上重置；在停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父级。不适用于同步子代理。555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 启动的子代理的停滞监视程序。默认 `600000`。在每个流事件上重置；在停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父级。不适用于同步子代理。

556* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求。当 `CLAUDE_ENABLE_STREAM_WATCHDOG` 未设置时，默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求。监视程序对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。

557 557

558<h3 id="query-object">558<h3 id="query-object">

559 `Query` 对象559 `Query` 对象

573 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;573 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;

574 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;574 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;

575 initializationResult(): Promise<SDKControlInitializeResponse>;575 initializationResult(): Promise<SDKControlInitializeResponse>;

576 reinitialize(): Promise<SDKControlInitializeResponse>;

576 supportedCommands(): Promise<SlashCommand[]>;577 supportedCommands(): Promise<SlashCommand[]>;

577 supportedModels(): Promise<ModelInfo[]>;578 supportedModels(): Promise<ModelInfo[]>;

578 supportedAgents(): Promise<AgentInfo[]>;579 supportedAgents(): Promise<AgentInfo[]>;

592</h4>593</h4>

593 594

594| 方法 | 描述 |595| 方法 | 描述 |

595| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |596| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

604| `reinitialize()` | {/* min-version: 2.1.195 */}重新发送 `initialize` 控制请求到运行的 CLI，并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |

689 691

690当客户端向已运行的会话发送 `initialize` 时，控制响应包装器也会携带一个可选的 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目都是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流式传输的相同 `{ type: "control_request", request_id, request }` 形状。692当客户端向已运行的会话发送 `initialize` 时，控制响应包装器也会携带一个可选的 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目都是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流式传输的相同 `{ type: "control_request", request_id, request }` 形状。

691 693

692这些是在客户端连接之前发出的请求，仍在等待回复，因此读取此数组以立即在界面中显示进行中的权限提示；它们不会被重新发送。694这些是在客户端连接之前发出的请求，仍在等待回复。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。

693 695

694<h3 id="agentdefinition">696<h3 id="agentdefinition">

695 `AgentDefinition`697 `AgentDefinition`

886 888

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

888 890

891该函数是 SDK 替代交互式权限提示：仅当[权限评估流](/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时才调用它。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要限制每个工具调用，请改用 [`PreToolUse` hook](/zh-CN/agent-sdk/hooks)。

892

889```typescript theme={null}893```typescript theme={null}

890type CanUseTool = (894type CanUseTool = (

891 toolName: string,895 toolName: string,

1531 session_id: string;1535 session_id: string;

1532 transcript_path: string;1536 transcript_path: string;

1533 cwd: string;1537 cwd: string;

1538 prompt_id?: string;

1534 permission_mode?: string;1539 permission_mode?: string;

1535 effort?: { level: string };1540 effort?: { level: string };

1536 agent_id?: string;1541 agent_id?: string;

1538};1543};

1539```1544```

1540 1545

1546`prompt_id` 字段是一个 UUID，用于标识当前正在处理的用户提示。它与 [OpenTelemetry 事件上的 `prompt.id` 属性](/zh-CN/monitoring-usage#event-correlation-attributes)匹配，在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本。

1547

1541<h4 id="pretoolusehookinput">1548<h4 id="pretoolusehookinput">

1542 `PreToolUseHookInput`1549 `PreToolUseHookInput`

1543</h4>1550</h4>

2037 2044

2038```typescript theme={null}2045```typescript theme={null}

2039type MonitorInput = {2046type MonitorInput = {

2040 command: string;2047 command?: string;

2048 ws?: {

2049 url: string;

2050 protocols?: string[];

2051 };

2041 description: string;2052 description: string;

2042 timeout_ms?: number;2053 timeout_ms?: number;

2043 persistent?: boolean;2054 persistent?: boolean;

2044};2055};

2045```2056```

2046 2057

2047运行后台脚本并将每个 stdout 行作为事件传递给 Claude，以便它可以做出反应而无需轮询。为会话长度的监视（如日志尾部）设置 `persistent: true`。Monitor 遵循与 Bash 相同的权限规则。请参阅 [Monitor 工具参考](/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。2058运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并为每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 之一。{/* min-version: 2.1.195 */}`ws` 源需要 Claude Code v2.1.195 或更高版本。

2059

2060为会话长度的监视（如日志尾部）设置 `persistent: true`。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 [Monitor 工具参考](/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。

2048 2061

2049<h3 id="taskoutput">2062<h3 id="taskoutput">

2050 TaskOutput2063 TaskOutput

2236运行[动态工作流](/zh-CN/workflows)：一个脚本，在后台协调许多子代理并返回一个统一的结果。Workflow 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。2249运行[动态工作流](/zh-CN/workflows)：一个脚本，在后台协调许多子代理并返回一个统一的结果。Workflow 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。

2237 2250

2238| 字段 | 类型 | 描述 |2251| 字段 | 类型 | 描述 |

2239| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |2252| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2240| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description, phases }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体 |2253| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体。`meta` 中的可选 `phases` 数组在进度视图中将代理分组到命名阶段下 |

3098```3111```

3099 3112

3100<Warning>3113<Warning>

3101 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需 beta 标头。3114 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需 beta 标头。

3102</Warning>3115</Warning>

3103 3116

3104<h3 id="slashcommand">3117<h3 id="slashcommand">

agent-sdk/user-input.md +6 −4

Details

44 44

45回调在两种情况下触发：45回调在两种情况下触发：

46 46

471. **工具需要批准**：Claude 想要使用不被[权限规则](/zh-CN/agent-sdk/permissions)或模式自动批准的工具。检查 `tool_name` 以获取工具（例如 `"Bash"`、`"Write"`）。471. **工具需要批准**：Claude 想要使用不被[权限规则](/zh-CN/agent-sdk/permissions)或权限模式自动批准的工具。检查 `tool_name` 以获取工具（例如 `"Bash"`、`"Write"`）。

482. **Claude 提出问题**：Claude 调用 `AskUserQuestion` 工具。检查 `tool_name == "AskUserQuestion"` 以不同方式处理它。如果您指定 `tools` 数组，请包含 `AskUserQuestion` 以使其工作。有关详细信息，请参阅[处理澄清问题](#handle-clarifying-questions)。482. **Claude 提出问题**：Claude 调用 `AskUserQuestion` 工具。检查 `tool_name == "AskUserQuestion"` 以不同方式处理它。如果您指定 `tools` 数组，请包含 `AskUserQuestion` 以使其工作。有关详细信息，请参阅[处理澄清问题](#handle-clarifying-questions)。

49 49

~~50<Note>~~50<Warning>

51 要自动允许或拒绝工具而不提示用户，请改用 [hooks](/zh-CN/agent-sdk/hooks)。Hooks 在 `canUseTool` 之前执行，可以根据您自己的逻辑允许、拒绝或修改请求。您还可以使用 [`PermissionRequest` hook](/zh-CN/agent-sdk/hooks#available-hooks) 在 Claude 等待批准时发送外部通知（Slack、电子邮件、推送）。51 **回调永远不会对自动批准的工具触发。** [权限评估流程](/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)中任何较早的批准、允许规则或 `acceptEdits` 或 `bypassPermissions` 等模式会在咨询 `canUseTool` 之前解决调用。如果您在 `allowed_tools` 中列出一个工具，除非询问规则或 `plan` 模式将调用路由回提示，否则该工具的 `canUseTool` 检查永远不会运行。对于必须应用于每个工具调用的逻辑，请使用 [`PreToolUse` hook](/zh-CN/agent-sdk/hooks)，它在流程的其余部分之前执行，可以允许、拒绝或修改请求。

~~52</Note>~~52</Warning>

54您还可以使用 [`PermissionRequest` hook](/zh-CN/agent-sdk/hooks#available-hooks) 在 Claude 等待批准时发送外部通知（Slack、电子邮件、推送）。

53 55

54<h2 id="handle-tool-approval-requests">56<h2 id="handle-tool-approval-requests">

55 处理工具批准请求57 处理工具批准请求

agent-view.md +53 −33

Details

76 76

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

78 78

79默认情况下，列表显示你启动的每个后台会话，跨越所有项目。在一个存储库中工作的会话和在不同 worktree 中工作的另一个会话都会出现在这里，无论你从哪个目录打开 agent view。要将列表限制到一个项目，请传递 `--cwd`（需要 Claude Code v2.1.141 或更高版本）：79默认情况下，列表显示你启动的每个后台会话，跨越所有项目。在一个存储库中工作的会话和在不同 worktree 中工作的另一个会话都会出现在这里，无论你从哪个目录打开 agent view。要将列表限制到一个项目，请传递 `--cwd`：

80 80

81```bash theme={null}81```bash theme={null}

82claude agents --cwd ~/projects/my-app82claude agents --cwd ~/projects/my-app

143 143

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

145 145

146从 v2.1.161 开始，当会话运行两个或更多并行工作项时，例如 subagents、后台 shell 命令或监视器，`done/total` 计数（例如 `2/5`）出现在摘要文本之前。146当会话运行两个或更多并行工作项时，例如 subagents、后台 shell 命令或监视器，`done/total` 计数（例如 `2/5`）出现在摘要文本之前。

147 147

148每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的[数据使用条款](/zh-CN/data-usage)计费和处理。在第三方提供商（如 Bedrock、Vertex AI、Microsoft Foundry 和自定义网关）上，当没有配置 Haiku 模型时，请求会回退到会话的主模型。设置 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config#environment-variables) 以在这些提供商上为这些摘要选择模型。148每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的[数据使用条款](/zh-CN/data-usage)计费和处理。在第三方提供商（如 Bedrock、Vertex AI、Microsoft Foundry 和自定义网关）上，当没有配置 Haiku 模型时，请求会回退到会话的主模型。设置 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config#environment-variables) 以在这些提供商上为这些摘要选择模型。

149 149

172 172

173在选定的行上按 `Space` 打开窥视面板。它显示会话需要什么、其最近的输出和它打开的任何拉取请求。大多数时候这就足够了，你永远不需要打开完整的记录。173在选定的行上按 `Space` 打开窥视面板。它显示会话需要什么、其最近的输出和它打开的任何拉取请求。大多数时候这就足够了，你永远不需要打开完整的记录。

174 174

175从 v2.1.161 开始，当会话运行并行工作项时，面板也会命名运行时间最长的一个以及它已经运行了多长时间，所以你可以看到会话在等待什么而无需附加。175当会话运行并行工作项时，面板也会命名运行时间最长的一个以及它已经运行了多长时间，所以你可以看到会话在等待什么而无需附加。

176 176

177在窥视面板中输入回复并按 `Enter` 将其发送到该会话。当会话提出多选问题时，窥视面板显示选项，你可以按数字键选择一个。对于其他被阻止的会话，按 `Tab` 用建议的回复填充输入，你可以在发送前编辑。用 `!` 前缀回复以发送 Bash 命令。177在窥视面板中输入回复并按 `Enter` 将其发送到该会话。当会话提出多选问题时，窥视面板显示选项，你可以按数字键选择一个。对于其他被阻止的会话，按 `Tab` 用建议的回复填充输入，你可以在发送前编辑。用 `!` 前缀回复以发送 Bash 命令。

178 178

196 196

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

198 198

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

200

201如果在你按 `←` 时工具正在运行，Claude Code 会等待大约十秒钟让它完成，然后后台，响应在后台会话中继续。再按一次 `←` 以立即后台而不是等待。当进行中的工作无法转移到后台会话时，`Background this session?` 对话首先出现，与 [`/background`](#from-inside-a-session) 相同。

202

203该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。当该行是唯一的行时，agent view 在它下方显示一个入门提示。

204

205你可以在 `/config` 中关闭此快捷键（`leftArrowOpensAgents` 设置）。

200 206

201<h3 id="organize-the-list">207<h3 id="organize-the-list">

202 组织列表208 组织列表

215 221

216删除会从 agent view 中删除会话。如果 Claude [为会话创建了 worktree](#how-file-edits-are-isolated)，删除会删除该 worktree，包括其中的任何未提交的更改，所以在删除前推送或提交你想保留的工作。你自己创建的 worktree 并在其中启动会话的会被保留。对话记录保留在你的本地机器上，并且仍然可以通过 `claude --resume` 访问。222删除会从 agent view 中删除会话。如果 Claude [为会话创建了 worktree](#how-file-edits-are-isolated)，删除会删除该 worktree，包括其中的任何未提交的更改，所以在删除前推送或提交你想保留的工作。你自己创建的 worktree 并在其中启动会话的会被保留。对话记录保留在你的本地机器上，并且仍然可以通过 `claude --resume` 访问。

217 223

218较旧的已完成会话折叠成 `… N more` 行以保持列表简短。失败和有打开拉取请求的会话始终保持可见。224不适合屏幕的已完成会话折叠成 `… N more` 行。失败和有打开拉取请求的会话始终保持可见。`Completed` 组填充活跃组之后剩余的垂直空间，在短终端上标题压缩为单个摘要行，以便正在工作或需要输入的会话保持可见。

219 225

220<h3 id="filter-sessions">226<h3 id="filter-sessions">

221 过滤会话227 过滤会话

305 311

306运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。如果 Claude 在你运行 `/bg` 时正在响应，响应会在后台会话中继续。312运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。如果 Claude 在你运行 `/bg` 时正在响应，响应会在后台会话中继续。

307 313

308从交互式会话后台化启动一个新的进程，该进程从保存的对话恢复，所以运行 subagent、[monitors](/zh-CN/tools-reference#monitor-tool) 和后台命令不会转移到它。当任何正在运行时，Claude 会要求你在后台化前确认。一旦在后台，会话可以启动新的 subagent、monitor 和后台命令，这些会在后续的分离和重新附加中保持运行。314从交互式会话后台化启动一个新的进程，该进程从保存的对话恢复，进行中的工作会转移到它：运行后台 shell 命令、后台 subagents、动态工作流和你用 [`/loop`](/zh-CN/scheduled-tasks) 创建的计划任务会转移到后台会话并在那里继续运行。一个 subagent 与它启动的所有内容一起移动，所以它仅在所有工作都能转移时才转移，包括在 Windows 上。要停止进行中的工作而不是转移它，设置 [`CLAUDE_DISABLE_ADOPT=1`](/zh-CN/env-vars#variables) 环境变量；Claude Code 随后会要求你在后台化前确认。

315

316无法转移的工作，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，会被停止。拥有监视器的后台 subagent 会与它一起被停止。当任何此类工作正在运行时，Claude Code 显示 `Background this session?` 对话，以便你可以在它被停止前确认。

317

318一旦在后台，会话可以启动新的 subagents、monitors 和后台命令，这些会在后续的分离和重新附加中保持运行。

309 319

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

311 321

394}404}

395```405```

396 406

397<Note>

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

399</Note>

~~400~~

401在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置一个 [`WorktreeCreate` hook](/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。407在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置一个 [`WorktreeCreate` hook](/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。

402 408

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

412 418

413agent view 标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，这来自你的用户设置中的 [`model` 设置](/zh-CN/settings#available-settings)。通过在 [`/model` 选择器](/zh-CN/model-config) 中选择模型来设置它，或直接编辑设置。要为整个 agent view 会话覆盖它，在打开 agent view 时传递 `--model`。参见 [权限模式、模型和工作量](#permission-mode-model-and-effort)。419agent view 标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，这来自你的用户设置中的 [`model` 设置](/zh-CN/settings#available-settings)。通过在 [`/model` 选择器](/zh-CN/model-config) 中选择模型来设置它，或直接编辑设置。要为整个 agent view 会话覆盖它，在打开 agent view 时传递 `--model`。参见 [权限模式、模型和工作量](#permission-mode-model-and-effort)。

414 420

415要从 agent view 内部更改调度默认值，在调度输入中输入 `/model` 后跟模型名称并按 `Enter`。标题更新以显示该模型，带有 `(session)` 标记，之后调度的会话使用它。输入 `/model default` 以清除覆盖并返回调度默认值。此覆盖持续当前 `claude agents` 运行的其余部分，不写入你的设置文件，并需要 Claude Code v2.1.172 或更高版本。{/* min-version: 2.1.172 */} 以下示例在 Opus 上调度一个会话，在 Sonnet 上调度下一个：421要从 agent view 内部更改调度默认值，在调度输入中输入 `/model` 后跟模型名称并按 `Enter`。标题更新以显示该模型，带有 `(session)` 标记，之后调度的会话使用它。输入 `/model default` 以清除覆盖并返回调度默认值。此覆盖持续当前 `claude agents` 运行的其余部分，不写入你的设置文件。以下示例在 Opus 上调度一个会话，在 Sonnet 上调度下一个：

416 422

417```text theme={null}423```text theme={null}

418/model opus424/model opus

449 455

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

451 457

452这些标志在各个版本中添加。更早的版本会以未知选项错误拒绝它们。

~~453~~

454| 标志或设置 | 最低版本 |

455| :------------------------------------------------------------------------ | :------------------------------------ |

456| `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions` | v2.1.142 {/* min-version: 2.1.142 */} |

457| `--allow-dangerously-skip-permissions` | v2.1.143 {/* min-version: 2.1.143 */} |

458| `--agent` 和尊重调度会话的 `agent` 设置 | v2.1.157 {/* min-version: 2.1.157 */} |

~~459~~

460在 v2.1.157 之前，agent view 忽略 `agent` 设置并调度内置的 `claude` 代理。

~~461~~

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

463 459

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

465 461

466使用 `bypassPermissions` 或 `auto` 被拒绝，直到你通过交互式运行 `claude` 一次接受该模式，因为这些模式让你没有看到的会话无需批准就能行动。无论你是将模式传递给 `claude agents` 还是 `claude --bg --permission-mode`，同样的规则都适用。462使用 `bypassPermissions` 与 `claude --bg --permission-mode` 被拒绝，直到你通过交互式运行 `claude --dangerously-skip-permissions` 一次接受了绕过免责声明，因为该模式让你没有看到的会话无需批准就能行动。传递 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 到 `claude agents` 在你之前没有接受它时显示相同的免责声明，接受会将 `bypassPermissions` 应用到你从视图启动的会话。传递 `--allow-dangerously-skip-permissions` 也显示相同的免责声明，接受会在这些会话的 `Shift+Tab` 循环中使 `bypassPermissions` 可用而不在其中启动它们。

467 463

468<h3 id="settings-plugins-and-mcp-servers">464<h3 id="settings-plugins-and-mcp-servers">

469 Settings、plugins 和 MCP servers465 Settings、plugins 和 MCP servers

470</h3>466</h3>

471 467

472Agent view 接受与 `claude` 相同的配置标志以加载 settings、plugins、MCP servers 和额外目录。这些标志需要 Claude Code v2.1.142 或更高版本。每个标志适用于 agent view 本身，并传递给你从它调度的每个会话，所以以这种方式加载的 plugin 或 MCP server 在这些会话中也可用。468Agent view 接受与 `claude` 相同的配置标志以加载 settings、plugins、MCP servers 和额外目录。每个标志适用于 agent view 本身，并传递给你从它调度的每个会话，所以以这种方式加载的 plugin 或 MCP server 在这些会话中也可用。

473 469

474| 标志 | 效果 |470| 标志 | 效果 |

475| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |471| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |

523 519

524监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。提供商选择变量如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 别名从调度每个会话的 shell 中读取，并应用到其工作进程。520监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。提供商选择变量如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 别名从调度每个会话的 shell 中读取，并应用到其工作进程。

525 521

526{/* min-version: 2.1.174 */}后台会话不继承网关端点变量如 `ANTHROPIC_BASE_URL`、等效的 Bedrock、Vertex 和 Foundry 基础 URL 变量，或从启动监督进程的 shell 或调度 shell 中配对的 `ANTHROPIC_AUTH_TOKEN`。会话使用你的存储凭证和项目目录的[设置](/zh-CN/settings)中 `env` 块中的任何 `env` 值。要在项目中指向[LLM 网关](/zh-CN/llm-gateway)的后台会话，在该项目的 `.claude/settings.json` `env` 块中设置 `ANTHROPIC_BASE_URL`，而不是在你的 shell 中导出它。在 v2.1.174 之前，后台会话从监督进程的启动 shell 继承这些变量，因此它可以使用你在该 shell 中配置的网关，而不是为项目目录配置的网关。522后台会话不继承网关端点变量如 `ANTHROPIC_BASE_URL`、等效的 Bedrock、Vertex 和 Foundry 基础 URL 变量，或从启动监督进程的 shell 或调度 shell 中配对的 `ANTHROPIC_AUTH_TOKEN`。会话使用你的存储凭证和项目目录的[设置](/zh-CN/settings)中 `env` 块中的任何 `env` 值。要在项目中指向[LLM 网关](/zh-CN/llm-gateway)的后台会话，在该项目的 `.claude/settings.json` `env` 块中设置 `ANTHROPIC_BASE_URL`，而不是在你的 shell 中导出它。

527 523

528每个后台会话是其自己的 Claude Code 进程，由监督进程管理而不是与你的终端绑定。积极工作、等待你的输入或有终端连接的会话保持其进程运行。运行中的后台 shell 命令、子代理、动态工作流或监视器计为活跃工作，因此长时间运行的进程（如开发服务器）会保持会话活跃。524每个后台会话是其自己的 Claude Code 进程，由监督进程管理而不是与你的终端绑定。积极工作、等待你的输入或有终端连接的会话保持其进程运行。运行中的后台 shell 命令、子代理、动态工作流或监视器计为活跃工作，因此长时间运行的进程（如开发服务器）会保持会话活跃。

529 525

530一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。你用 `Ctrl+T` [固定](#organize-the-list)的会话是例外，在空闲时保持其进程运行。无论哪种方式，记录和状态都保留在磁盘上，下次你附加、窥视或回复停止的会话时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你需要它时再次启动。526一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。你用 `Ctrl+T` [固定](#organize-the-list)的会话是例外，在空闲时保持其进程运行。无论哪种方式，记录和状态都保留在磁盘上，下次你附加、窥视或回复停止的会话时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你需要它时再次启动。

531 527

532按 `←` 留下的空行从未给出提示符会在大约五分钟后被完全删除，以便列表自动清理。使用 `claude --bg` 启动的会话和等待设置提示符（如信任对话）的会话不会以这种方式被删除。528后台 shell 命令和动态工作流会话启动的在会话的进程被停止、重新启动或更新时继续运行，包括在 Windows 上。下一个为该会话启动的进程会接管它们，在此期间完成的 shell 命令会报告为已完成及其输出，工作流会从中断处恢复。由 subagent 启动的 shell 命令和运行中的 [monitors](/zh-CN/tools-reference#monitor-tool) 仍然与进程一起停止，删除会话会停止它交付的所有内容。要让后台 shell 命令和工作流也与进程一起停止，设置 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-CN/env-vars#variables) 环境变量为 `1`。

529

530如果重新启动的会话回来时仅显示其原始提示，因为 Claude Code 误读了其记录为空，对话记录会被重命名为 `.orphaned-` 后缀而不是删除，所以它保留在你的机器上。

531

532从按 `←` 留下的空行从未给出提示符会在大约五分钟后被完全删除，以便列表自动清理。使用 `claude --bg` 启动的会话和等待设置提示符（如信任对话）的会话不会以这种方式被删除。

533 533

534当主机内存不足时，监督进程首先停止空闲的非固定会话，仅在释放任何内容时才停止空闲的固定会话。534当主机内存不足时，监督进程首先停止空闲的非固定会话，仅在释放任何内容时才停止空闲的固定会话。

535 535

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

571</h3>571</h3>

572 572

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

574 574

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

576 576

580 580

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

582 582

583<h3 id="cannot-open-agents-because-work-is-running-in-the-background">583<h3 id="backgrounding-shows-a-background-this-session-dialog">

584 无法打开代理，因为后台工作正在运行584 后台化显示 `Background this session?` 对话

585</h3>585</h3>

586 586

587如果按 `←` 来后台当前会话显示 `Cannot open agents — N still running in the background`，说明会话有进行中的工作，例如子代理、动态工作流或后台 shell 命令，快捷键不会默默放弃它。运行 `/tasks` 来查看正在运行的内容，然后运行 `/bg` 来确认放弃它们。参见[从会话内部](#from-inside-a-session)了解后台时什么会转移，什么不会转移。587如果按 `←` 来后台当前会话显示 `Background this session?` 对话，会话有进行中的工作无法转移到后台会话，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，Claude Code 不会默默停止它。对话命名将被停止的工作，并分别计算转移的任务。运行 `/tasks` 查看正在运行的内容，然后确认无论如何后台或选择 `Stay` 让工作先完成。参见 [从会话内部](#from-inside-a-session) 了解哪些任务类型转移，哪些被停止。

588 588

589<h3 id="prompt-rejected-as-too-short">589<h3 id="prompt-rejected-as-too-short">

590 提示被拒绝，因为太短590 提示被拒绝，因为太短

618 后台调度失败，出现 `Could not resolve authentication method`618 后台调度失败，出现 `Could not resolve authentication method`

619</h3>619</h3>

620 620

621如果后台调度失败，出现 `Could not resolve authentication method`，而交互式会话正常进行身份验证，则接收调度的工作进程没有获取凭证。在 v2.1.174 及更高版本上，监督进程在将[预热工作进程](#the-supervisor-process)分配给调度时提供新的凭证快照，所以这个错误意味着监督进程本身没有可用的存储凭证。确认你已运行 `/login` 或配置了 API 密钥，然后停止监督进程：621如果后台调度失败，出现 `Could not resolve authentication method`，而交互式会话正常进行身份验证，则接收调度的工作进程没有获取凭证。监督进程在将[预热工作进程](#the-supervisor-process)分配给调度时提供新的凭证快照，所以这个错误意味着监督进程本身没有可用的存储凭证。确认你已运行 `/login` 或配置了 API 密钥，然后停止监督进程：

622 622

623```bash theme={null}623```bash theme={null}

624claude daemon stop --any --keep-workers624claude daemon stop --any --keep-workers

626 626

627下一个 `claude agents` 或 `claude --bg` 启动一个新的监督进程，该进程读取你存储的凭证。如果你使用环境变量（如 `ANTHROPIC_API_KEY`）而不是 `/login` 进行身份验证，请从设置了该变量的 shell 运行下一个命令。627下一个 `claude agents` 或 `claude --bg` 启动一个新的监督进程，该进程读取你存储的凭证。如果你使用环境变量（如 `ANTHROPIC_API_KEY`）而不是 `/login` 进行身份验证，请从设置了该变量的 shell 运行下一个命令。

628 628

629参见[错误参考](/zh-CN/errors#could-not-resolve-authentication-method)了解完整的原因和修复列表。在 v2.1.174 之前，一个闲置的预热工作进程在被分配给调度时可能会出现这个错误，即使你的凭证有效。升级以恢复。629参见[错误参考](/zh-CN/errors#could-not-resolve-authentication-method)了解完整的原因和修复列表。

630 630

631<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">631<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">

632 后台会话无法在 macOS 上读取 Desktop、Documents 或 Downloads632 后台会话无法在 macOS 上读取 Desktop、Documents 或 Downloads

640 附加后会话响应缓慢640 附加后会话响应缓慢

641</h3>641</h3>

642 642

643一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。附加启动一个从中断处的新进程，这需要一点时间。工作或等待你的会话，或[固定](#organize-the-list)的会话永远不会以这种方式停止，所以用 `Ctrl+T` 固定一个会话来保持它的响应性。643一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。附加启动一个从中断处的新进程并立即切换到会话，而进程重新启动。工作或等待你的会话，或[固定](#organize-the-list)的会话永远不会以这种方式停止，所以用 `Ctrl+T` 固定一个会话来保持它的响应性。

644 644

645<h3 id="claude/worktrees/-is-filling-up">645<h3 id="claude/worktrees/-is-filling-up">

646 `.claude/worktrees/` 填满了646 `.claude/worktrees/` 填满了

664 664

665有关以并行方式运行 Claude 的其他方法，请参阅：665有关以并行方式运行 Claude 的其他方法，请参阅：

666 666

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

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

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

670

671<h2 id="version-history">

672 版本历史

673</h2>

674

675Agent view 在研究预览期间发展迅速。如果你使用较旧的 Claude Code 版本，本页上的某些行为可能会有所不同；特别是，`claude agents` 拒绝它尚不支持的标志，出现 `unknown option` 错误。下表列出了何时添加每个标志和行为。

676

677| 版本 | 更改 |

678| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

679| v2.1.196 | {/* min-version: 2.1.196 */}单次 `←` 按压后台前台会话；早期版本需要两次按压，带有页脚提示和确认。`--dangerously-skip-permissions` 传递给 `claude agents` 显示绕过免责声明而不是被默默丢弃。你从未命名的交互式会话在会话列表和 `claude agents --json` 中携带默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话的进程被停止、重新启动或更新时存活，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 关闭交付。在重新启动时误读为空的记录被重命名为 `.orphaned-` 后缀而不是删除。 |

680| v2.1.195 | {/* min-version: 2.1.195 */}进行中的工作在 Windows 上后台会话时也转移；设置 `CLAUDE_DISABLE_ADOPT=1` 改为停止它。`Completed` 组填充剩余的垂直空间，标题在短终端上压缩。较旧的 Claude Code 版本不再丢弃较新会话的 `state.json` 字段或从 `claude agents` 隐藏这些会话。附加到停止的会话立即切换而不是显示空白屏幕长达五秒。无法接受连接的监督进程自行退出并释放其锁。 |

681| v2.1.174 | {/* min-version: 2.1.174 */}后台会话不再从监督进程的启动 shell 继承网关端点变量如 `ANTHROPIC_BASE_URL`；监督进程向预热工作进程提供新的凭证快照，修复虚假的 `Could not resolve authentication method` 错误。 |

682| v2.1.172 | {/* min-version: 2.1.172 */}调度输入中的 `/model` 设置会话范围的调度模型覆盖。 |

683| v2.1.161 | {/* min-version: 2.1.161 */}行摘要显示并行工作项的 `done/total` 计数；窥视面板命名最长运行的并行工作项。 |

684| v2.1.157 | {/* min-version: 2.1.157 */}` claude agents` 接受 `--agent`；调度的会话尊重 `agent` 设置。 |

685| v2.1.145 | {/* min-version: 2.1.145 */}窥视面板回复输入和调度输入中支持语音听写。 |

686| v2.1.143 | {/* min-version: 2.1.143 */}添加 `worktree.bgIsolation` 设置；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |

687| v2.1.142 | {/* min-version: 2.1.142 */}` claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |

688| v2.1.141 | {/* min-version: 2.1.141 */}` claude agents` 接受 `--cwd` 以将列表范围限定到一个项目。 |

689| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作为研究预览版引入。 |

amazon-bedrock.md +10 −2

Details

397 1M 令牌上下文窗口397 1M 令牌上下文窗口

398</h2>398</h2>

399 399

400Claude Opus 4.6 及更高版本，以及 Sonnet 4.6，在 Amazon Bedrock 上支持 [1M 令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)。当您选择 1M 模型变体时，Claude Code 会自动启用扩展上下文窗口。400Claude Sonnet 5、Opus 4.6 及更高版本，以及 Sonnet 4.6 在 Amazon Bedrock 上支持 [1M 令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 通过 [Mantle 端点](#use-the-mantle-endpoint)提供，始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展上下文窗口。

401 401

402[设置向导](#sign-in-with-bedrock)在固定模型时提供 1M 上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)了解详情。402[设置向导](#sign-in-with-bedrock)在固定模型时提供 1M 上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)了解详情。

403 403

458 选择 Mantle 模型458 选择 Mantle 模型

459</h3>459</h3>

460 460

461Mantle 使用以 `anthropic.` 为前缀且没有版本后缀的模型 ID，例如 `anthropic.claude-haiku-4-5`。您的账户可用的模型取决于您的组织被授予的内容；其他模型 ID 列在您来自 AWS 的入职材料中。联系您的 AWS 账户团队以请求访问允许列表中的模型。461Mantle 使用以 `anthropic.` 为前缀且没有版本后缀的模型 ID，例如 `anthropic.claude-sonnet-5` 或 `anthropic.claude-haiku-4-5`。您的账户可用的模型取决于您的组织被授予的内容；其他模型 ID 列在您来自 AWS 的入职材料中。联系您的 AWS 账户团队以请求访问允许列表中的模型。

462 462

463使用 `--model` 标志或在 Claude Code 内使用 `/model` 设置模型：463使用 `--model` 标志或在 Claude Code 内使用 `/model` 设置模型：

464 464

542 542

543Claude Code 使用 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支持 Converse API。543Claude Code 使用 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支持 Converse API。

544 544

545<h3 id="zero-token-counts-in-/context">

546 /context 中的零令牌计数

547</h3>

548

549`/context` 命令通过将工具架构发送到 Bedrock count-tokens API 来计算每个工具组的令牌。{/* min-version: 2.1.196 */}在 Claude Code v2.1.196 之前的版本中，Bedrock 拒绝了该请求，因为架构包含其 count-tokens API 不接受的字段，因此每个工具组显示 0 个令牌。分解中的其他行（如消息和内存文件）不受影响。

550

551更新到 v2.1.196 或更高版本。

552

545<h3 id="mantle-endpoint-errors">553<h3 id="mantle-endpoint-errors">

546 Mantle 端点错误554 Mantle 端点错误

547</h3>555</h3>

authentication.md +5 −1

Details

24* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 Claude.ai 账户登录。24* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 Claude.ai 账户登录。

25* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。25* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。

26* **云提供商**：如果您的组织使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，请在运行 `claude` 之前设置所需的环境变量。不需要浏览器登录。26* **云提供商**：如果您的组织使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，请在运行 `claude` 之前设置所需的环境变量。不需要浏览器登录。

27* **云网关**：如果您的组织运行自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)，请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。

27 28

28要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。29要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。

29 30

37 38

38* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，推荐用于大多数团队39* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，推荐用于大多数团队

39* [Claude Console](#claude-console-authentication)40* [Claude Console](#claude-console-authentication)

41* [Claude apps gateway](/zh-CN/claude-apps-gateway)，一个自托管网关，使用您的 IdP 为开发人员签名，并将推理路由到您配置的云提供商

40* [Amazon Bedrock](/zh-CN/amazon-bedrock)42* [Amazon Bedrock](/zh-CN/amazon-bedrock)

41* [Google Vertex AI](/zh-CN/google-vertex-ai)43* [Google Vertex AI](/zh-CN/google-vertex-ai)

42* [Microsoft Foundry](/zh-CN/microsoft-foundry)44* [Microsoft Foundry](/zh-CN/microsoft-foundry)

131 * 在 Windows 上，凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中，并继承您的用户配置文件目录的访问控制，默认情况下将文件限制为您的用户帐户。133 * 在 Windows 上，凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中，并继承您的用户配置文件目录的访问控制，默认情况下将文件限制为您的用户帐户。

132 * 如果您在 Linux 或 Windows 上设置了 `CLAUDE_CONFIG_DIR` 环境变量，`.credentials.json` 文件将位于该目录下。134 * 如果您在 Linux 或 Windows 上设置了 `CLAUDE_CONFIG_DIR` 环境变量，`.credentials.json` 文件将位于该目录下。

133 * Claude Code 通过 `/login` 和 `/logout` 管理 `.credentials.json`。要通过自定义 API 端点路由请求，请改为设置 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 环境变量。135 * Claude Code 通过 `/login` 和 `/logout` 管理 `.credentials.json`。要通过自定义 API 端点路由请求，请改为设置 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 环境变量。

134* **支持的身份验证类型**：Claude.ai 凭证、Claude API 凭证、Azure Auth、Bedrock Auth 和 Vertex Auth。136* **支持的身份验证类型**：Claude.ai 凭证、Claude API 凭证、Azure Auth、Bedrock Auth、Vertex Auth 和 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话令牌。

135* **自定义凭证脚本**：[`apiKeyHelper`](/zh-CN/settings#available-settings) 设置可以配置为运行返回 API 密钥的 shell 脚本。137* **自定义凭证脚本**：[`apiKeyHelper`](/zh-CN/settings#available-settings) 设置可以配置为运行返回 API 密钥的 shell 脚本。

136* **刷新间隔**：默认情况下，`apiKeyHelper` 在 5 分钟后或在 HTTP 401 响应时调用。设置 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 环境变量以获得自定义刷新间隔。138* **刷新间隔**：默认情况下，`apiKeyHelper` 在 5 分钟后或在 HTTP 401 响应时调用。设置 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 环境变量以获得自定义刷新间隔。

137* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。139* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。

1515. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本，其中浏览器登录不可用。1535. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本，其中浏览器登录不可用。

1526. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。1546. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。

153 155

156一个已签名的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话位于此列表之外：它是一个提供商选择，如 Bedrock 或 Vertex，并且它优先于它们。当网关会话存在时，即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，CLI 也会使用网关令牌进行身份验证，上面的持有者令牌、API 密钥和 `apiKeyHelper` 条目不会被使用。

157

154如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，则 API 密钥在批准后优先。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。158如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，则 API 密钥在批准后优先。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。

155 159

156[Claude Code on the Web](/zh-CN/claude-code-on-the-web) 始终使用您的订阅凭证。沙箱环境中的 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 不会覆盖它们。160[Claude Code on the Web](/zh-CN/claude-code-on-the-web) 始终使用您的订阅凭证。沙箱环境中的 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 不会覆盖它们。

auto-mode-config.md +58 −6

Details

6 6

7> 告诉自动模式分类器您的组织信任哪些代码库、存储桶和域。设置环境上下文，覆盖默认的阻止和允许规则，并使用自动模式 CLI 子命令检查您的有效配置。7> 告诉自动模式分类器您的组织信任哪些代码库、存储桶和域。设置环境上下文，覆盖默认的阻止和允许规则，并使用自动模式 CLI 子命令检查您的有效配置。

8 8

9[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需权限提示即可运行，通过将每个工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和明确询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。9[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需常规权限提示即可运行，通过将工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和明确询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。

10 10

11<Note>11<Note>

12 自动模式可通过 Anthropic API 供所有用户使用。在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上，您必须首先[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 及 Enterprise 计划上的管理员启用。12 自动模式可通过 Anthropic API 供所有用户使用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的[Claude 应用网关](/zh-CN/claude-apps-gateway)会话上，您必须首先[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 及 Enterprise 计划上的所有者启用。

13</Note>13</Note>

14 14

15开箱即用，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。15默认情况下，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。

16 16

17有关如何启用自动模式以及它默认阻止什么的信息，请参阅[权限模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。本页是配置参考。17有关如何启用自动模式以及它默认阻止什么的信息，请参阅[权限模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。本页是配置参考。

18 18

21* [选择在何处设置规则](#where-the-classifier-reads-configuration)跨 CLAUDE.md、用户设置和托管设置21* [选择在何处设置规则](#where-the-classifier-reads-configuration)跨 CLAUDE.md、用户设置和托管设置

22* [定义受信任的基础设施](#define-trusted-infrastructure)使用 `autoMode.environment`22* [定义受信任的基础设施](#define-trusted-infrastructure)使用 `autoMode.environment`

23* [覆盖阻止和允许规则](#override-the-block-and-allow-rules)当默认值不适合您的管道时23* [覆盖阻止和允许规则](#override-the-block-and-allow-rules)当默认值不适合您的管道时

24* [将所有 shell 命令路由通过分类器](#route-all-shell-commands-through-the-classifier)使用 `autoMode.classifyAllShell`

24* [检查您的有效配置](#inspect-the-defaults-and-your-effective-config)使用 `claude auto-mode` 子命令25* [检查您的有效配置](#inspect-the-defaults-and-your-effective-config)使用 `claude auto-mode` 子命令

25* [查看拒绝](#review-denials)以便您知道接下来要添加什么26* [查看拒绝](#review-denials)以便您知道接下来要添加什么

26 27

53 54

54对于大多数组织，`autoMode.environment` 是您唯一需要设置的字段。它告诉分类器哪些代码库、存储桶和域是受信任的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。55对于大多数组织，`autoMode.environment` 是您唯一需要设置的字段。它告诉分类器哪些代码库、存储桶和域是受信任的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。

55 56

56默认环境列表信任工作代码库及其配置的远程。要在该默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目会在该位置被拼接进去，因此您的自定义条目可以在它们之前或之后。57从 Claude Code v2.1.195 开始，`claude auto-mode defaults` 打印两种环境条目。

59* **信任槽**：命名分类器视为在您边界内的内容。槽位是受信任的代码库、源代码控制、受信任的内部域、受信任的云存储桶、关键内部服务和内部包注册表。代码库和源代码控制条目默认为工作代码库及其配置的远程。所有其他信任槽默认为 `None configured`，因此在您添加之前没有其他内容是受信任的。

60* **敏感性槽**：命名保护规则视为高风险的内容。槽位是 PII / 受管制数据位置、敏感远程目标和受保护的 IaC 范围。每个都默认为广泛的启发式方法，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感性槽中命名具体目标会使这些规则应用于命名的目标而不是启发式方法。

62v2.1.195 之前的版本仅打印前五个信任槽。

64要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目会在该位置被拼接进去，因此您的自定义条目可以在它们之前或之后。

66以下示例保持默认条目并添加组织的代码库、存储桶、域和服务。

57 67

58```json theme={null}68```json theme={null}

59{69{

76* **云提供商和受信任的存储桶**：Claude 应该能够读取和写入的存储桶名称或前缀86* **云提供商和受信任的存储桶**：Claude 应该能够读取和写入的存储桶名称或前缀

77* **受信任的内部域**：您网络内的 API、仪表板和服务的主机名，例如 `*.internal.example.com`87* **受信任的内部域**：您网络内的 API、仪表板和服务的主机名，例如 `*.internal.example.com`

78* **关键内部服务**：CI、工件注册表、内部包索引、事件工具88* **关键内部服务**：CI、工件注册表、内部包索引、事件工具

89* **内部包注册表**：私有 npm、PyPI 或其他注册表，安装应该通过它路由，因此绕过它安装到公共注册表的安装会被阻止

90* **PII / 受管制数据位置**：保存个人或受管制数据的存储桶、数据库或路径，以便分类器保护这些位置而不是从内容猜测

91* **敏感远程目标**：计为生产的命名空间、主机或容器，因此远程 shell 和端口转发到它们需要您的明确批准

92* **受保护的 IaC 范围**：其应用或销毁应始终需要您命名更改的基础设施资源

79* **其他上下文**：受管制行业的约束、多租户基础设施或影响分类器应将什么视为风险的合规要求93* **其他上下文**：受管制行业的约束、多租户基础设施或影响分类器应将什么视为风险的合规要求

80 94

95内部包注册表、PII / 受管制数据位置、敏感远程目标和受保护的 IaC 范围条目需要 Claude Code v2.1.195 或更高版本。早期版本仍将它们读作纯上下文，但没有针对它们的内置规则。

81一个有用的起始模板：填入括号中的字段并删除任何不适用的行。97一个有用的起始模板：填入括号中的字段并删除任何不适用的行。

82 98

83```json theme={null}99```json theme={null}

105 覆盖阻止和允许规则121 覆盖阻止和允许规则

106</h2>122</h2>

107 123

108三个额外的字段让您替换分类器的内置规则列表：`autoMode.hard_deny` 用于无条件安全边界，`autoMode.soft_deny` 用于用户意图可以清除的破坏性操作，以及 `autoMode.allow` 用于例外。每个都是散文描述的数组，读作自然语言规则。对于在分类器之前运行的基于工具模式的硬阻止，请使用 [`permissions.deny`](/zh-CN/permissions)。124三个额外的字段让您替换分类器的内置规则列表：

125

126* `autoMode.hard_deny`：无条件安全边界

127* `autoMode.soft_deny`：用户意图可以清除的破坏性操作

128* `autoMode.allow`：软阻止规则的例外

129

130每个都是散文描述的数组，读作自然语言规则。对于在分类器之前运行的基于工具模式的硬阻止，请使用 [`permissions.deny`](/zh-CN/permissions)。

109 131

110在分类器内，优先级分为四个层级：132在分类器内，优先级分为四个层级：

111 133

118 140

119要放松，当分类器重复标记默认例外不涵盖的常规模式时，添加到 `allow`。要收紧，为您的环境特定的破坏性风险添加到 `soft_deny`（默认值会遗漏），或为必须永远不能跨越的安全边界添加到 `hard_deny`。要保持内置规则同时添加您自己的规则，请在数组中包含字面字符串 `"$defaults"`。默认规则会在该位置拼接，因此您的自定义规则可以在它们之前或之后，并且当内置列表在版本发布中更改时，您继续继承更新。141要放松，当分类器重复标记默认例外不涵盖的常规模式时，添加到 `allow`。要收紧，为您的环境特定的破坏性风险添加到 `soft_deny`（默认值会遗漏），或为必须永远不能跨越的安全边界添加到 `hard_deny`。要保持内置规则同时添加您自己的规则，请在数组中包含字面字符串 `"$defaults"`。默认规则会在该位置拼接，因此您的自定义规则可以在它们之前或之后，并且当内置列表在版本发布中更改时，您继续继承更新。

120 142

143以下示例在所有四个列表中保持默认值，并向每个列表添加特定于组织的规则。

144

121```json theme={null}145```json theme={null}

122{146{

123 "autoMode": {147 "autoMode": {

149 173

150每个部分独立评估，因此单独设置 `environment` 会保持默认 `allow`、`soft_deny` 和 `hard_deny` 列表完整。仅在您打算完全拥有该列表时才省略 `"$defaults"`。要安全地执行此操作，请运行 `claude auto-mode defaults` 打印内置规则，将它们复制到您的设置文件中，然后根据您自己的管道和风险容限审查每条规则。174每个部分独立评估，因此单独设置 `environment` 会保持默认 `allow`、`soft_deny` 和 `hard_deny` 列表完整。仅在您打算完全拥有该列表时才省略 `"$defaults"`。要安全地执行此操作，请运行 `claude auto-mode defaults` 打印内置规则，将它们复制到您的设置文件中，然后根据您自己的管道和风险容限审查每条规则。

151 175

176<h2 id="route-all-shell-commands-through-the-classifier">

177 将所有 shell 命令路由通过分类器

178</h2>

179

180默认情况下，窄 Bash 和 PowerShell 允许规则（例如 `Bash(npm test)`）会进入自动模式并在分类器运行之前解决。自动模式仅暂停授予任意代码执行的广泛规则，例如 `Bash(*)` 或通配符解释器。这意味着窄规则仍然可以让破坏性参数通过而不被分类器看到，例如脚本路径或规则前缀未预期的标志。

181

182将 `autoMode.classifyAllShell` 设置为 `true` 以在自动模式处于活动状态时暂停每个 Bash 和 PowerShell 允许规则，以便分类器评估每个 shell 命令，无论您的允许列表如何。

183

184```json theme={null}

185{

186 "autoMode": {

187 "classifyAllShell": true

188 }

189}

190```

191

192这用延迟换取覆盖：允许规则会立即批准的命令现在等待分类器决定，每个 shell 命令计为一个分类器调用。

193

194该设置仅在自动模式处于活动状态时适用，您的允许规则在其他权限模式中表现正常。

195

196<Note>

197 `autoMode.classifyAllShell` 需要 Claude Code v2.1.193 或更高版本。早期版本忽略该键并继续将窄 shell 允许规则进入自动模式。

198</Note>

199

152<h2 id="inspect-the-defaults-and-your-effective-config">200<h2 id="inspect-the-defaults-and-your-effective-config">

153 检查默认值和您的有效配置201 检查默认值和您的有效配置

154</h2>202</h2>

173claude auto-mode critique221claude auto-mode critique

174```222```

175 223

176保存设置后运行 `claude auto-mode config` 以确认有效规则是您期望的，其中 `"$defaults"` 已展开到位。如果您编写了自定义规则，`claude auto-mode critique` 会审查它们并标记模糊、冗余或可能导致误报的条目。如果您需要删除或重写内置规则而不是在其旁边添加，请将 `claude auto-mode defaults` 的输出保存到文件，编辑列表，并将结果粘贴到您的设置文件中以替换 `"$defaults"`。224保存设置后运行 `claude auto-mode config` 以确认有效规则是您期望的，其中 `"$defaults"` 已展开到位。如果您编写了自定义规则，`claude auto-mode critique` 会审查它们并标记模糊、冗余或可能导致误报的条目。

225

226如果您需要删除或重写内置规则而不是在其旁边添加，请将 `claude auto-mode defaults` 的输出保存到文件，编辑列表，并将结果粘贴到您的设置文件中以替换 `"$defaults"`。

177 227

178<h2 id="review-denials">228<h2 id="review-denials">

179 查看拒绝229 查看拒绝

181 231

182当自动模式拒绝工具调用时，拒绝被记录在 `/permissions` 下的"最近拒绝"选项卡中。在被拒绝的操作上按 `r` 将其标记为重试：当您退出对话框时，Claude Code 发送一条消息告诉模型它可能重试该工具调用并恢复对话。232当自动模式拒绝工具调用时，拒绝被记录在 `/permissions` 下的"最近拒绝"选项卡中。在被拒绝的操作上按 `r` 将其标记为重试：当您退出对话框时，Claude Code 发送一条消息告诉模型它可能重试该工具调用并恢复对话。

183 233

234在 Claude Code v2.1.193 及更高版本中，分类器对每个拒绝的原因出现在成绩单中被阻止的工具调用旁边、拒绝通知中以及"最近拒绝"选项卡上的每个条目下。使用原因来决定修复是 `environment` 条目、`allow` 例外还是在您的下一条消息中使用明确意图重试。

235

184对同一目标的重复拒绝通常意味着分类器缺少上下文。将该目标添加到 `autoMode.environment`，然后运行 `claude auto-mode config` 确认它生效。236对同一目标的重复拒绝通常意味着分类器缺少上下文。将该目标添加到 `autoMode.environment`，然后运行 `claude auto-mode config` 确认它生效。

185 237

186要以编程方式对拒绝做出反应，请使用 [`PermissionDenied` hook](/zh-CN/hooks#permissiondenied)。238要以编程方式对拒绝做出反应，请使用 [`PermissionDenied` hook](/zh-CN/hooks#permissiondenied)。

claude-apps-gateway-config.md +746 −0 created

Details

1> ## Documentation Index

2> 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.

5# Claude 应用网关配置

7> 每个 gateway.yaml 选项的参考：监听器和 TLS、OIDC、会话、Postgres 存储、Bedrock/Agent Platform/Foundry 上游、模型路由、托管策略和遥测。

9Claude 应用网关部署由一个 YAML 文件配置，按惯例命名为 `gateway.yaml`。该文件定义网关所做的一切：它在哪里监听、开发者如何登录、推理去往何处，以及应用哪些策略和遥测。本页是该文件中每个选项的参考。要编写你的第一个配置，请从[快速入门](/zh-CN/claude-apps-gateway#quickstart)开始，它构建一个最小的工作配置并运行它；一旦你有了满意的配置，[部署指南](/zh-CN/claude-apps-gateway-deploy)涵盖了在 Kubernetes、Cloud Run 或你自己的平台上容器化和托管它。

11网关在启动时使用 `claude gateway --config /path/to/gateway.yaml` 读取该文件一次。每个选项都在启动时根据模式进行验证，因此格式错误的配置在启动时失败并显示字段级错误，而不是在首次使用时失败。

13本页末尾的[完整示例](#complete-example)演示了每个部分。

15<h2 id="file-structure">

16 文件结构

17</h2>

19五个部分是[必需的](#required-sections)。所有其他部分都是[可选的](#optional-sections)，省略的部分采用其默认值。未知的键会导致启动失败，因此拼写错误会显示为命名错误，而不是被静默忽略的设置。

21**必需部分：**

23* [`listen`](#listen)：绑定地址、公共 URL、TLS 终止

24* [`oidc`](#oidc)：你的身份提供者 (IdP)，包括发行者、客户端、声明映射和谁可以登录

25* [`session`](#session)：网关铸造的持有者令牌，包括密钥和生命周期

26* [`store`](#store)：PostgreSQL，用于设备授权和速率限制计数器

27* [`upstreams`](#upstreams)：推理去往何处，无论是 Anthropic、Bedrock、Agent Platform 还是 Foundry

29**可选部分：**

31* [`admin`](#admin)：Admin API 身份验证和支出限制的保留

32* [`enforcement`](#enforcement)：支出限制故障开放或故障关闭行为

33* [`models`](#models) 和 `auto_include_builtin_models`：管理员策划的模型列表和每个上游的 ID

34* [`managed`](#managed)：按 IdP 组的托管设置策略

35* [`telemetry`](#telemetry)：OTLP 转发到你的可观测性堆栈

36* [`access_control`、`limits`、`timeouts`、`rate_limits`](#http-tuning)：IP 允许/拒绝、请求大小上限、上游首字节时间和每 IP 登录限制

38<h2 id="secret-expansion">

39 密钥扩展

40</h2>

42不要直接在 `gateway.yaml` 中写入密钥，如 `client_secret`、`jwt_secret` 或 `postgres_url`。使用下面的一种形式引用它们，网关在启动时从环境变量或文件解析该值：

44| 形式 | 解析为 | 用于 |

45| --------------- | ---------------------- | -------------------------------------- |

46| `${VAR}` | 环境变量 `VAR`。如果未定义，启动失败。 | 容器环境变量、通过环境注入的 AWS Secrets Manager |

47| `${file:/path}` | 文件内容，已修剪 | Kubernetes Secret 卷挂载、Vault Agent、SOPS |

49<h2 id="required-sections">

50 必需部分

51</h2>

53<h3 id="listen">

54 `listen`

55</h3>

57`listen` 块控制网关服务的位置：绑定地址和端口、外部可见的源和可选的 TLS 终止。

59| 字段 | 必需 | 描述 |

60| ---------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

61| `host` | 否 | 绑定地址。默认 `0.0.0.0`。 |

62| `port` | 否 | 绑定端口。默认 `8080`。 |

63| `public_url` | 在代理后面 | 外部可见的 `https://` 源，用于构建 IdP `redirect_uri` 和发现元数据。在任何 TLS 终止代理（如 ALB、Ingress 或 Cloud Run）后面是必需的，因为网关在构建自己的源时不信任 `X-Forwarded-*` 头；它们是客户端可欺骗的。下面的 `trusted_proxies` 仅控制客户端 IP 解析。启用[遥测](#telemetry)也是必需的，因为网关从此 URL 构建它推送给客户端的 OTLP 端点。 |

64| `tls.cert` / `tls.key` | 否 | 如果网关自己终止 TLS，则为 PEM 路径 |

65| `trusted_proxies` | 否 | 网关前面的负载均衡器的 CIDR 或 IP。设置时，网关仅从这些对等体信任 `X-Forwarded-For`，并记录真实客户端 IP 用于每 IP 速率限制和审计。等同于 nginx `set_real_ip_from`。 |

67<h3 id="oidc">

68 `oidc`

69</h3>

71OpenID Connect (OIDC) 是网关与你的身份提供者一起使用的 SSO 协议；有关在 IdP 端注册的内容，请参阅[身份提供者设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。`oidc` 块将网关连接到你的身份提供者，并决定谁可以登录。它命名发行者和 OAuth 客户端，映射携带电子邮件和组的声明，并按电子邮件域或组限制登录。

73| 字段 | 必需 | 描述 |

74| ------------------------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

75| `issuer` | 是 | OIDC 发现基础。必须在 `/.well-known/openid-configuration` 提供发现。在生产中使用 HTTPS；网关接受 `http://` 发行者。环回发行者（如 `http://localhost:8081`）被[SSRF 防护](/zh-CN/claude-apps-gateway-deploy#threat-model-summary)拒绝，除非在网关的环境中设置了 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`。 |

76| `client_id` / `client_secret` | 是 | 来自你的 OAuth 客户端注册 |

77| `allowed_email_domains` | 否 | 拒绝其 `email` 声明不在这些域之一中的 id\_token，不区分大小写。针对多租户 IdP 配置错误的纵深防御。独立于此设置，其 `email_verified` 声明明确为 `false` 的 id\_token 总是被拒绝。 |

78| `allowed_groups` | 否 | 限制登录到这些 IdP 组的成员，与 `groups_claim` 匹配。允许的电子邮件域中但不在这些组中的用户被拒绝。需要 IdP 发出组声明。 |

79| `groups_claim` | 否 | 哪个 id\_token 声明携带组成员身份。默认 `groups`。Microsoft Entra 在 `roles` 下发出应用角色。接受平面键或 RFC 6901 JSON 指针，如 `/resource_access/gateway/roles` 用于嵌套声明。 |

80| `google_groups` | 否 | 通过 Google Workspace Admin SDK Directory API 查找已登录用户的组，因为 Google 的 id\_token 不携带组声明。将 `service_account_json_path` 设置为具有 `https://www.googleapis.com/auth/admin.directory.group.readonly` 范围的域范围委派的服务帐户密钥文件，并将 `admin_email` 设置为服务帐户模拟的 Workspace 管理员；Directory API 需要真实的管理员主体。每个用户的组电子邮件地址成为他们的组声明，因此 `allowed_groups` 和 `managed.policies.match.groups` 匹配组电子邮件。 |

81| `email_claim` | 否 | 哪个 id\_token 声明携带用户的电子邮件。默认 `email`。某些 IdP（如 ADFS 和 Entra B2C）改为发出 `upn` 或 `preferred_username`。接受平面键、JSON 指针或回退键列表，其中使用第一个存在的键。 |

82| `scopes` | 否 | 网关请求的 OIDC 范围的完全覆盖。默认 `[openid, profile, email, offline_access]`。当你的 IdP 拒绝它不识别的范围或需要自定义范围来发出组或电子邮件时设置。必须包括 `openid`。删除 `offline_access` 会禁用刷新令牌，因此开发者每 `session.ttl_hours` 重新运行浏览器登录。有关每个 IdP 范围配方（如 Google 的刷新令牌流），请参阅[身份提供者设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。 |

83| `extra_auth_params` | 否 | 附加到 IdP 授权请求的额外查询参数，逐字。这是 IdP 特定行为的覆盖机制，如 Google 刷新令牌的 `access_type: offline`、某些 Entra 租户的 `domain_hint` 或分步流的 `acr_values`。不能覆盖网关管理的协议参数：`state`、`nonce`、`redirect_uri`、PKCE、`scope`、`response_type`、`response_mode` 和 `client_id`。 |

84| `userinfo_fallback` | 否 | 当 id\_token 省略电子邮件或组时，从 `/userinfo` 获取它们。Keycloak 轻量级访问令牌、Okta 组织服务器和 ADFS 最小令牌需要。id\_token 保持权威；userinfo 仅填补空白。默认 `false`。 |

85| `use_pkce` | 否 | 在授权请求上发送 PKCE (S256) 质询。默认 `true`。仅当你的 IdP 为此机密客户端拒绝 PKCE 时设置 `false`。 |

86| `clock_skew_seconds` | 否 | 验证 id\_token 时间声明时容忍时钟漂移。默认 `0`，这是严格的。如果由于主机/IdP 时钟偏差在登录后立即看到"令牌过期/尚未有效"错误，请提高。 |

87| `token_endpoint_auth_method` | 否 | 覆盖令牌端点身份验证方法。接受 `client_secret_basic` 或 `client_secret_post`。默认自动协商。 |

88| `id_token_signed_response_alg` | 否 | 预期的 id\_token 签名算法。默认 `RS256`。为使用 ES256、PS256 或 EdDSA 签名的 IdP 设置。 |

89| `additional_authorized_parties` | 否 | 除 `client_id` 外要接受的额外 `azp` 值，用于 Keycloak 代理和令牌交换流 |

90| `discovery_url` | 否 | 从此 URL 而不是从 `issuer` 派生发现文档，用于代理后面重写发行者主机的 IdP。路径必须包含 `/.well-known/`。 |

91| `form_action_origins` | 否 | `/device` 页面的 `Content-Security-Policy: form-action` 指令的其他源。网关已允许 `'self'` 和发现的 `authorization_endpoint` 源，但 Chrome 对整个重定向链强制执行 `form-action`。如果你的 IdP 通过第二个主机重定向，如 Azure AD 联合到 ADFS、中心辐射 Okta 或公司 SSO 拦截器，列出授权请求可能重定向通过的每个源。 |

92| `ca_cert_pem` | 否 | PEM CA 证书，替换 IdP 请求的系统信任存储。用于公司 PKI 后面的 Keycloak 或 Dex。 |

94<h3 id="session">

95 `session`

96</h3>

98`session` 块塑造网关在登录后铸造的持有者令牌：签署它们的密钥和它们的生命周期。

100| 字段 | 必需 | 描述 |

101| ------------ | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

102| `jwt_secret` | 是 | 至少 32 字节的熵，例如来自 `openssl rand -base64 32`。签署网关的 HS256 持有者令牌。接受单个字符串或用于轮换的数组：索引 0 签署，所有条目验证。要轮换，前置新密钥，等待 `ttl_hours`，然后删除旧密钥。 |

103| `ttl_hours` | 否 | 网关持有者令牌生命周期。默认 `1`。当 IdP 发出刷新令牌时，CLI 在过期前静默刷新。较短的生命周期更快地取消配置；较长的生命周期减少 IdP 往返。如果你的 IdP 因为 `offline_access` 不可用而无法发出刷新令牌，则没有静默刷新，因此提高到 `8` 或 `12` 以避免每小时将开发者发送回浏览器登录。 |

104

105<h3 id="store">

106 `store`

107</h3>

108

109`store` 块指向网关的 PostgreSQL 数据库，该数据库保存设备授权和速率限制计数器。

110

111| 字段 | 必需 | 描述 |

112| ----------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

113| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：设备授权会合点，浏览器回调写入，轮询 CLI 读取，需要跨副本状态。网关在启动时运行自己的模式迁移，因此角色需要在目标模式上具有 `CREATE TABLE` 权限。如果你的安全策略禁止应用角色的 DDL，使用管理员角色运行迁移，最初和每当新版本发布迁移时，并授予应用角色对网关表的 `SELECT, INSERT, UPDATE, DELETE` 权限。请参阅[升级](/zh-CN/claude-apps-gateway-deploy#upgrades)和 [Postgres](/zh-CN/claude-apps-gateway-deploy#postgres)。 |

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

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

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

117

118对于本地开发，将 `postgres_url` 指向一个一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。

119

120<h3 id="upstreams">

121 `upstreams`

122</h3>

123

124`upstreams` 是一个有序列表。网关将推理转发到解析请求的模型的第一个上游。在 `5xx`、`429` 或超时时，它故障转移到下一个；其他 `4xx` 不会，因为这些错误归因于请求而不是上游。同一提供者的多个上游必须设置不同的 `name:`。

125

126Bedrock、Agent Platform 和 Foundry 客户端在启动时构建一次，它们的 SDK 在内部刷新凭证，因此轮换云凭证不需要重启。静态 Anthropic API 密钥和持有者在启动时读取；请参阅 [Anthropic API](#anthropic-api)。

127

128<h4 id="anthropic-api">

129 Anthropic API

130</h4>

131

132最小的 Anthropic 上游是来自 [Claude 控制台](https://platform.claude.com) 的 API 密钥：

133

134```yaml theme={null}

135upstreams:

136 - provider: anthropic

137 auth:

138 api_key: ${ANTHROPIC_API_KEY}

139 # 或 OAuth 持有者（例如工作负载身份联合交换的令牌）：

140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}

141 # base_url: https://api.anthropic.com # 默认；为转发代理覆盖

142```

143

144两种凭证形式在它们发送的头中有所不同：

145

146* **`api_key`**：发送 `x-api-key`。在 Claude 控制台中轮换它并更新环境变量。

147* **`oauth_token`**：发送 `Authorization: Bearer`。当你的组织发出短期令牌而不是长期 API 密钥时使用持有者形式。持有者在启动时读取一次，因此通过重新挂载密钥和重启来刷新。

148

149代替静态密钥或持有者，你可以使用工作负载身份联合。按照[工作负载身份联合指南](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)创建联合规则，然后将你的工作负载的 OIDC JWT 挂载为文件，如 Kubernetes 投影服务帐户令牌或 CI 平台的 id-token。网关将 JWT 交换为短期持有者并自动刷新它。令牌文件在每次交换时重新读取，因此轮换的投影令牌被拾取而无需重启。

150

151```yaml theme={null}

152upstreams:

153 - provider: anthropic

154 auth:

155 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}

156 organization_id: ${ANTHROPIC_ORGANIZATION_ID}

157 identity_token_file: /var/run/secrets/anthropic/id-token

158 # workspace_id: wrkspc_... # 如果规则覆盖 >1 个工作区，则必需

159 # service_account_id: svac_... # 可选的预期目标检查

160```

161

162<h4 id="amazon-bedrock">

163 Amazon Bedrock

164</h4>

165

166对于网关替换或前置的客户端 Bedrock 部署，请参阅 [Amazon Bedrock 上的 Claude Code](/zh-CN/amazon-bedrock)。网关端上游：

167

168```yaml theme={null}

169upstreams:

170 - provider: bedrock

171 region: us-east-1

172 auth: {} # 首选：AWS 默认凭证链

173 # 或显式凭证：

174 # auth:

175 # aws_access_key_id: ${AWS_AKID}

176 # aws_secret_access_key: ${AWS_SK}

177 # aws_session_token: ${AWS_ST}

178 # 或 Bedrock API 持有者令牌：

179 # auth:

180 # aws_bearer_token: ${AWS_BEARER_TOKEN}

181 # 为 FIPS 或 VPC 端点部署覆盖 bedrock-runtime 端点：

182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

183```

184

185空的 `auth` 块使用 AWS SDK 的默认凭证链：环境变量、`~/.aws/credentials`、ECS 任务角色、EC2 实例元数据或 EKS 上的 IRSA。在生产中，给网关 pod 一个 IAM 角色，而不是在容器镜像中嵌入静态密钥。

186

187| 设置 | 如何 |

188| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

189| IAM 权限 | 授予网关的主体 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在推理配置文件 ARN 和底层基础模型 ARN 上。对于美国地区的内置目录：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。 |

190| 模型访问 | 在 Bedrock 控制台中，按地区，请求并启用你想要的 Claude 模型的模型访问。跨地区推理配置文件（`us.anthropic.*`）需要在配置文件跨越的每个地区中进行模型访问。 |

191| EKS (IRSA) | 创建一个具有上述策略的 IAM 角色和针对你的集群的 OIDC 提供者的信任策略，范围限定为网关的服务帐户。使用 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway` 注释服务帐户。`auth: {}` 拾取它。 |

192| ECS / EC2 | 将 IAM 角色附加到任务定义或实例配置文件。`auth: {}` 拾取它。 |

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

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

195

196<h4 id="google-cloud-agent-platform">

197 Google Cloud Agent Platform

198</h4>

199

200对于等效的客户端设置，请参阅 [Google Cloud 上的 Claude Code](/zh-CN/google-vertex-ai)。网关端上游：

201

202```yaml theme={null}

203upstreams:

204 - provider: vertex

205 region: us-east5

206 project_id: example-prod

207 auth: {} # 首选：应用默认凭证

208 # 或服务帐户密钥文件：

209 # auth: { service_account_json: /secrets/sa.json }

210 # 为私有服务连接覆盖 aiplatform 端点：

211 # base_url: https://us-east5-aiplatform.p.googleapis.com

212```

213

214空的 `auth` 块使用应用默认凭证：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 元数据或 GKE 工作负载身份。支持服务帐户 JSON 密钥文件但不推荐；使用工作负载身份或将服务帐户附加到 GCE 或 Cloud Run 实例。

215

216设置 `region: global` 以使用 [Agent Platform 的全局端点](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)而不是区域端点。Google 然后将每个请求路由到可用地区，因此你不跟踪每地区模型可用性。设置特定地区会将每个请求固定到它。

217

218| 设置 | 如何 |

219| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |

220| IAM 权限 | 授予网关的服务帐户项目上的 `roles/aiplatform.user`，或具有 `aiplatform.endpoints.predict` 的自定义角色。启用 Agent Platform API (`aiplatform.googleapis.com`)。 |

221| 模型访问 | 在 Model Garden 中，为你的项目启用 Claude 模型。它们发布到特定地区；检查模型卡以了解支持的地区。 |

222| GKE (工作负载身份) | 将 GCP 服务帐户绑定到网关的 Kubernetes 服务帐户，并使用 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com` 注释 KSA。`auth: {}` 拾取它。 |

223| Cloud Run / GCE | 将服务的服务帐户设置为具有 `roles/aiplatform.user` 的服务帐户。`auth: {}` 拾取它。 |

224| 其他任何地方 | `auth: { service_account_json: /secrets/sa.json }`，JSON 密钥文件的路径，挂载为密钥。该字段采用文件路径，而不是密钥内容，因此不涉及 `${file:…}` 扩展。 |

225

226<h4 id="microsoft-foundry">

227 Microsoft Foundry

228</h4>

229

230对于客户端 Foundry 部署，请参阅 [Microsoft Foundry 上的 Claude Code](/zh-CN/microsoft-foundry)。网关端上游：

231

232```yaml theme={null}

233upstreams:

234 - provider: foundry

235 resource: example-foundry # https://example-foundry.services.ai.azure.com

236 auth: { use_azure_ad: true } # 首选：DefaultAzureCredential / 托管身份

237 # 或 API 密钥：

238 # auth:

239 # api_key: ${FOUNDRY_API_KEY}

240```

241

242`use_azure_ad: true` 通过 `DefaultAzureCredential` 解析：AKS、ACI 或 App Service 上的托管身份；Azure CLI；或环境凭证。API 密钥有效但是项目范围的，不会自动轮换。Foundry 的端点从 `resource:` 派生；设置可选的 `base_url` 以为主权云（如 Azure Government）覆盖它。

243

244| 设置 | 如何 |

245| ----------------- | ------------------------------------------------------------------------------------------------- |

246| RBAC | 授予网关的身份 Foundry 资源上的 `Azure AI User` 或 `Cognitive Services User` |

247| 部署 | Foundry 使用管理员选择的部署名称，而不是规范模型 ID。添加一个[`models:`](#models)块，将每个规范 ID 映射到你的部署名称。 |

248| AKS (工作负载身份) | 将用户分配的托管身份与集群的 OIDC 发行者联合，并将其绑定到网关的服务帐户。`use_azure_ad: true` 通过 `WorkloadIdentityCredential` 拾取它。 |

249| ACI / App Service | 在资源上启用系统分配或用户分配的托管身份。`use_azure_ad: true` 拾取它。 |

250| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 内引用 `${…}`。 |

251

252<h4 id="multiple-upstreams">

253 多个上游

254</h4>

255

256同一提供者可以出现多次，具有不同的 `name:`。这涵盖不同的地区、通过不同凭证链的不同帐户、预配吞吐量与按需以及跨提供者故障转移。

257

258网关按顺序尝试上游。`5xx`、`429`、超时和缺失端点（`501`）故障转移；其他 `4xx` 不会。`429` 是每上游容量，因此预配吞吐量 (PT) 耗尽故障转移到按需。无法解析请求的模型的上游被跳过，无需网络往返。

259

260此示例首先路由预配吞吐量 Bedrock 分配，溢出到按需和第二个帐户，最后回退到 Anthropic API：

261

262```yaml theme={null}

263upstreams:

264 # 主要：你的主地区的预配吞吐量。

265 - name: bedrock-pt

266 provider: bedrock

267 region: us-east-1

268 auth: {}

269 # 溢出：按需跨地区。

270 - name: bedrock-od

271 provider: bedrock

272 region: us-west-2

273 auth: {}

274 # 不同帐户：通过假定角色凭证的单独 Bedrock 分配。

275 - name: bedrock-acct2

276 provider: bedrock

277 region: us-east-1

278 auth:

279 aws_access_key_id: ${ACCT2_AKID}

280 aws_secret_access_key: ${ACCT2_SK}

281 # 最后的手段：直接 Anthropic API。

282 - name: anthropic-fallback

283 provider: anthropic

284 auth:

285 api_key: ${ANTHROPIC_API_KEY}

286

287# 每上游模型 ID 由上游的 `name:` 键入；没有 `name:` 的上游默认为其提供者字符串（例如 `bedrock`）。任何未为模型列出的上游都被跳过，这是你如何将模型路由到预配吞吐量，同时其他所有内容保持按需的方式。

288models:

289 - id: claude-opus-4-8

290 label: Claude Opus 4.8

291 upstream_model:

292 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef

293 bedrock-od: us.anthropic.claude-opus-4-8

294 bedrock-acct2: us.anthropic.claude-opus-4-8

295 anthropic-fallback: claude-opus-4-8

296```

297

298| 杠杆 | 如何 |

299| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |

300| 不同地区 | 每个地区一个 Bedrock 上游，每个都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地区推理配置文件自动路由；对于地区固定部署，使用 `models:` 块。 |

301| 不同帐户 | 每个帐户一个 Bedrock 上游，每个在 `auth:` 中都有自己的凭证。默认链 (`auth: {}`) 使用 pod 的身份；对于第二个帐户，设置显式凭证或持有者令牌。 |

302| 预配吞吐量 | 在该上游名称的 `models:` 中将模型映射到预配吞吐量 ARN。其他上游保持按需 ID，因此 PT 容量在故障转移前耗尽。 |

303| VPC / FIPS 端点 | 在上游上设置 `base_url:` 到你的 VPC 端点或 FIPS 端点 URL |

304| 模型范围路由 | 从模型的 `upstream_model:` 映射中省略上游，该上游对该模型被跳过。例如，将 Opus 路由到预配吞吐量，将 Sonnet 和 Haiku 路由到按需。 |

305

306在云提供者之间或直接 Anthropic API 之间故障转移会改变哪个协议、地理位置和其他条款管理请求。

307

308CLI 对网关应用相同的功能门控，无论哪个上游服务给定请求，因此故障转移不会发送上游会拒绝的正文字段。

309

310<h2 id="optional-sections">

311 可选部分

312</h2>

313

314<h3 id="admin">

315 `admin`

316</h3>

317

318可选。启用 `/v1/organizations/spend_limits`，它镜像 Anthropic 的公共 Admin API，以及 `/v1/messages` 上的每开发者支出强制。有关如何设置和强制执行上限的信息，请参阅[支出限制](/zh-CN/claude-apps-gateway-spend-limits)；本部分涵盖打开该功能和调整它的 `gateway.yaml` 键。

319

320```yaml theme={null}

321admin:

322 # 管理员端点的命名静态 API 密钥，作为 x-api-key 发送。

323 # id 在审计日志中显示为 admin-key:<id>，因此每个密钥都是

324 # 可归因的。用于轮换的数组：添加新密钥，滚动客户端，

325 # 删除旧密钥。

326 write_keys:

327 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

328 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

329 read_keys:

330 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

331 # 通过普通网关 JWT（无 API 密钥）授予完全管理员的 IdP 组。

332 admin_groups: [platform-finops]

333 blocked_message: request an increase at https://go.example.com/claude-limits

334```

335

336| 字段 | 必需 | 描述 |

337| ------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

338| `write_keys` | 否 | `{id, key}` 的数组。与这些之一匹配的 `x-api-key` 可以列出、设置和删除支出限制。密钥值必须至少 32 个字符；`id` 必须在 `read_keys` 和 `write_keys` 中唯一。 |

339| `read_keys` | 否 | `{id, key}` 的数组。只读：每个 `GET` 端点，包括列出上限、按 ID 获取一个，以及读取 [`/effective`](/zh-CN/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/zh-CN/claude-apps-gateway-spend-limits#%2Faudit)。 |

340| `admin_groups` | 否 | IdP 组名称。其 `groups` 声明包括其中之一的网关 JWT 具有完全管理员访问权限，读和写，并审计为 `oidc:<sub>`。用于人类管理员；为机器使用 API 密钥。 |

341| `blocked_message` | 否 | 逐字附加到被阻止的开发者看到的 `429 billing_error`。写出整个指令，如 URL 或 Slack 频道。未设置，错误是 `spend limit reached`。 |

342| `audit_retention_days` | 否 | 默认 `365`。较旧的 `admin_audit` 行被清除。 |

343| `spend_retention_months` | 否 | 默认 `13`。`spend` 计数器行早于此被清除。默认值保留完整年份加当前部分月份用于年度比较报告。 |

344| `identity_retention_days` | 否 | 默认 `90`。`principal_emails` 行的最后看到 TTL，其中保存每个开发者的电子邮件、显示名称和组 (PII)。故意比支出保留更短，因此取消配置的身份在其匿名支出计数器保留时老化。 |

345| `group_limit_mode` | 否 | `min`（默认）或 `max`。当开发者在具有上限的多个组中时，`min` 强制执行最严格的，`max` 强制执行最宽松的。由强制执行和 `/effective` 使用。 |

346

347<h3 id="enforcement">

348 `enforcement`

349</h3>

350

351`enforcement` 块控制当存储不可用时支出限制检查的行为。

352

353| 字段 | 必需 | 描述 |

354| ---------------------- | -- | ---------------------------------------------------------------------------------------------------------------- |

355| `fail_closed_on_error` | 否 | 默认 `false`。支出强制在 Postgres 中断时故障开放，因此推理保持运行。设置 `true` 以故障关闭：超额开发者被阻止，但如果存储无法访问，每个人都被阻止。没有 [`admin:`](#admin) 块无效。 |

356

357<h3 id="models">

358 `models`

359</h3>

360

361`models` 块是可选的管理员策划的模型列表，在 `/v1/models` 提供，用于按上游翻译模型 ID。对于非美国 Bedrock 地区、Bedrock 预配吞吐量 ARN 和 Foundry 部署名称是必需的。

362

363```yaml theme={null}

364auto_include_builtin_models: true # false：仅公开下面的列表

365models:

366 - id: claude-opus-4-8

367 label: Claude Opus 4.8

368 # description: 可选文本显示在表面它的客户端中

369 upstream_model:

370 anthropic: claude-opus-4-8

371 bedrock: us.anthropic.claude-opus-4-8 # 或推理配置文件 ARN

372 foundry: your-opus-deployment-name

373```

374

375<h3 id="managed">

376 `managed`

377</h3>

378

379`managed` 块定义基于 IdP 组或电子邮件域键入的基于角色的访问策略。策略按顺序评估；第一个匹配被选择，然后合并到下面描述的 `match: {}` 捕获所有基础。它们按用户在 `GET /managed/settings` 提供，具有 ETag/304 缓存。

380

381```yaml theme={null}

382managed:

383 policies:

384 # 特定组首先。

385 - match: { groups: [eng-contractors] }

386 cli:

387 availableModels: [claude-sonnet-4-6]

388 permissions: { deny: ["WebFetch", "WebSearch"] }

389 # 默认捕获所有最后：匹配每个已认证的用户。

390 - match: {}

391 cli:

392 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

393```

394

395`match: {}` 捕获所有，按惯例列在最后，被视为基础层。每个其他策略从捕获所有继承它不设置的任何键，因此每角色条目只需列出与组织默认不同的内容。合并规则取决于键类型：

396

397* **允许列表**：`availableModels` 和 `permissions.allow`。特定策略的列表完全替换基础的。

398* **拒绝列表和钩子数组**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每个 `hooks` 事件类型数组。这些取基础和策略的并集，因此组织范围的拒绝或审计钩子不能被每角色覆盖意外删除。

399* **记录类型的键**：`env`、`modelOverrides` 和 `skillOverrides`。这些浅合并，因此每角色 `env` 块覆盖它设置的键并从基础继承其余的。

400

401`availableModels` 也在 `/v1/messages` 服务器端强制执行，因此被拒绝的模型返回 `400`，无论客户端发送什么。

402

403| 匹配器 | 行为 |

404| --------------------------------------------------- | --------------------------------------------------------- |

405| `match: {}` | 匹配每个已认证的用户。从其中一个开始，稍后添加组范围的策略。 |

406| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 声明包含任何列出的组，则匹配。区分大小写：组必须与 IdP 的确切大小写匹配。 |

407| `match: { email_domain: example.com }` | 匹配 JWT 的 `email` 声明中最后 `@` 后的部分，不区分大小写。每个策略接受一个域。 |

408| `match: { groups: [a], email_domain: example.com }` | 两个条件都必须匹配 |

409

410与任何策略不匹配的已认证用户获得网关的默认值，这意味着目录中的每个模型和没有托管设置。如果你想要保证的默认策略，最后添加 `match: {}` 捕获所有。

411

412<Note>

413 网关保持自己的用户目录。它从用户的 IdP 令牌授权每个请求，从令牌的 `groups` 声明读取组成员身份，并根据它评估策略。没有要枚举的名册，没有要预创建的帐户，因此没有 SCIM 端点，因为没有东西可供 SCIM 同步到。

414

415 在真实来源处运行用户和组生命周期管理，这是你的 IdP 的本地 SCIM 配置或专用身份治理平台。那里管理的成员身份和取消配置通过令牌自动流入网关。如果你想要 Claude 帐户本身的 SCIM 配置，这是一个 [Claude for Enterprise](/zh-CN/admin-setup) 功能。

416

417 两个传播时钟适用：

418

419 * **策略内容**：编辑策略并重新部署到连接的客户端在其下一个托管设置轮询，在一小时内

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

421</Note>

422

423<h4 id="what-goes-in-cli">

424 `cli` 中的内容

425</h4>

426

427每个 `cli` 值是完整的 Claude Code `managed-settings.json` 文档，与你通过 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同模式，在此表示为 YAML。CLI 在托管层应用交付的文档，在用户和项目设置之上。

428

429网关在启动时根据 CLI 的设置模式验证每个文档，因此无法识别的顶级键或具有格式错误值的识别键在启动时失败，并显示命名每个违规键的错误。模式的故意开放部分仍然接受任意值，因为较新的客户端可能识别网关的模式不识别的条目。这些开放键是 `env`、`pluginConfigs` 和 `permissions` 下嵌套的键。

430

431因为验证使用与网关的已安装版本捆绑的模式，将较新 Claude Code 版本引入的顶级设置键放入托管配置需要首先升级网关。在一个客户端上烟雾测试新策略，然后再推出。

432

433完整的键参考在 [Claude Code 设置](/zh-CN/settings#available-settings) 中。操作员首先到达的最常见的键：

434

435```yaml theme={null}

436managed:

437 policies:

438 - match: {}

439 cli:

440 # 模型访问（也在 /v1/messages 服务器端强制执行）

441 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

442

443 # 权限策略

444 permissions:

445 deny:

446 - "WebFetch"

447 - "Read(./.env)"

448 - "Read(./secrets/**)"

449 disableBypassPermissionsMode: disable # 阻止 --dangerously-skip-permissions

450 allowManagedPermissionRulesOnly: true # 忽略用户/项目权限规则

451

452 # 推送到 CLI 进程的环境。DISABLE_UPDATES 阻止

453 # 后台和手动更新；DISABLE_AUTOUPDATER 仅停止

454 # 后台更新。

455 env:

456 DISABLE_UPDATES: "1" # 通过你自己的分发固定版本

457

458 # 组织范围的钩子。钩子命令在开发者机器上运行，而不是

459 # 网关，因此路径必须存在于策略中每个客户端 OS 上。

460 hooks:

461 PostToolUse:

462 - matcher: "Edit|Write"

463 hooks:

464 - { type: command, command: /usr/local/bin/audit-edit.sh }

465```

466

467| 键 | 由以下强制执行 | 效果 |

468| ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

469| `availableModels` | 网关 + CLI | 模型允许列表。也在 `/v1/messages` 检查，因此修补的客户端无法绕过它。 |

470| `permissions.allow` / `.deny` | CLI | 工具和命令规则。请参阅[权限](/zh-CN/permissions)。 |

471| `permissions.disableBypassPermissionsMode` | CLI | 设置为 `disable` 以阻止 [`bypassPermissions`](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，自动批准每个工具调用的模式，以及 `--dangerously-skip-permissions` 标志 |

472| `allowManagedPermissionRulesOnly` | CLI | 当 `true` 时，用户和项目权限规则被忽略；仅此文档中的规则适用 |

473| `env` | CLI | 合并到 CLI 进程的环境变量。用于遥测、自动更新和模型名称覆盖。 |

474| `hooks` | CLI | 组织范围的[钩子](/zh-CN/hooks) |

475

476因为这些设置通过网络到达，CLI 在应用任何可以运行 shell 命令或改变流量去往何处的内容之前向每个开发者显示一次性安全批准对话。对话涵盖：

477

478* `hooks`

479* `env` 变量不在 CLI 的内置安全列表上

480* shell 执行设置，如 `apiKeyHelper` 和 `statusLine`

481* 托管 CLAUDE.md 内容

482

483安全列表确定哪些 `env` 变量在没有批准的情况下应用：

484

485* **在安全列表上**：自动更新和模型名称变量

486* **不在安全列表上**：代理变量、基础 URL 变量和 `OTEL_EXPORTER_OTLP_ENDPOINT`

487

488网关的[遥测](#telemetry)配置推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此设置 `telemetry.forward_to` 在每个交互式客户端上触发对话。使用 `-p` 标志的非交互式运行跳过对话并在没有批准的情况下应用设置。对话保护开发者的机器免受受损或敌对网关，而不是组织免受开发者，因此 `-p` 跳过是故意的而不是差距。

489

490如果开发者拒绝，Claude Code 退出而不是应用策略。将新钩子或非安全环境变量推送到广泛策略因此意味着每个匹配开发者下一次启动时的批准提示。

491

492`cli` 键在早期版本中被命名为 `settings`。该拼写仍然被接受为别名，但新部署应使用 `cli`。

493

494<h4 id="precedence-with-other-managed-sources">

495 与其他托管来源的优先级

496</h4>

497

498如果设备也有本地 `managed-settings.json` 或 MDM 交付的策略，托管来源不合并。最高优先级来源提供所有策略设置，按此顺序排列，最高优先级优先：

499

5001. [策略助手](/zh-CN/settings#compute-managed-settings-with-a-policy-helper)

5012. 网关交付的设置

5023. MDM，通过 Windows 上的 HKLM 注册表或 macOS 上的 plist

5034. `managed-settings.json` 文件

5045. HKCU 注册表，仅在 Windows 上

505

506嵌入主机可以通过 SDK `managedSettings` 选项提供策略。默认情况下它被忽略，仅当托管来源使用 [`parentSettingsBehavior: "merge"`](/zh-CN/settings#available-settings) 选择加入时应用，过滤以便它可以收紧策略但不能放松它。

507

508例外是一小组跨来源键，当任何管理来源设置它们时被尊重；用户可写的 HKCU 层被排除：

509

510* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：当锁定时，对应的允许列表跨来源联合

511* [`allowAllClaudeAiMcps`](/zh-CN/settings#available-settings)：claude.ai MCP 服务器允许列表的仅允许覆盖

512* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-CN/sandboxing)助手二进制文件的文件系统路径

513

514每个其他键，包括 `allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode`，来自最高优先级来源。请参阅[设置优先级](/zh-CN/settings#settings-precedence)了解设置页面上的相同规则。

515

516网关策略适用于机器上的每个 Claude Code 调用，包括非交互式 `claude -p` 运行和由 Agent SDK 生成的会话。如果网关在启动时无法访问，已登录的会话以错误退出，而不是在没有其策略的情况下运行。

517

518<Warning>

519 策略的 `cli` 块内的 `mcpServers` 在网关启动时被拒绝。不提供每组 MCP 分发；通过文件基础 `managed-mcp.json` 在每个设备上部署 MCP 服务器或让开发者在本地添加它们。

520</Warning>

521

522<h3 id="telemetry">

523 `telemetry`

524</h3>

525

526CLI 通过 HTTP 指标、日志和（启用时）跟踪将 OpenTelemetry Protocol (OTLP) 发送到网关，网关逐字中继到每个配置的目标。有关 CLI 发出的指标和事件，请参阅[监控使用](/zh-CN/monitoring-usage)。

527

528CLI 使用从网关发出的 JWT 读取的已认证用户的身份戳记每个导出：`user.id`、`user.email` 和 `user.groups` 属性。每开发者成本和使用归因因此在没有开发者端配置的情况下工作。

529

530```yaml theme={null}

531telemetry:

532 forward_to:

533 - url: https://otel-collector.internal.example.com

534 headers:

535 Authorization: ${OTLP_TOKEN}

536 # 每信号选择加入。默认：仅指标。

537 metrics: true

538 logs: false

539 traces: false

540 - url: https://api.datadoghq.com/api/v2/otlp

541 headers:

542 DD-API-KEY: ${DD_API_KEY}

543```

544

545<Warning>

546 每个目标独立选择加入 `metrics`、`logs` 和 `traces`，默认值仅为指标。信号在敏感性上有所不同：

547

548 * **指标**：聚合计数器，如令牌计数、请求计数和延迟

549 * **日志和跟踪**：可以携带完整的 bash 命令、工具输入和文件路径，涵盖 Claude Code 在开发者机器上所做的任何事情

550

551 仅在具有该数据保证的访问控制和保留策略的目标上启用日志和跟踪。

552</Warning>

553

554遥测在 CLI 中默认关闭。将 `telemetry.forward_to` 与 `listen.public_url` 一起配置会打开它。网关通过 `/managed/settings` 推送五个环境变量到每个连接的客户端：

555

556* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

557* `OTEL_METRICS_EXPORTER=otlp`

558* `OTEL_LOGS_EXPORTER=otlp`

559* `OTEL_TRACES_EXPORTER=otlp`

560* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

561

562推送的端点从公共 URL 构建，因此指标和日志不需要来自开发者或策略的 OTEL 配置。推送的配置在托管层应用，覆盖开发者在本地设置的 `OTEL_*` 变量。

563

564[跟踪](/zh-CN/monitoring-usage#traces-beta)另外需要每个客户端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。网关不推送该变量，因此通过托管策略的 `env` 块设置它。它不在 CLI 的安全列表上，因此通过策略交付它由推送的 OTLP 端点已经触发的相同[安全批准对话](#managed)覆盖。

565

566protobuf 和 JSON OTLP 编码都被中继，任何 OpenTelemetry 兼容的后端都可以作为目标。

567

568<h3 id="http-tuning">

569 HTTP 调整

570</h3>

571

572四个可选的顶级块，`access_control`、`limits`、`timeouts` 和 `rate_limits`，调整 HTTP 表面。默认值适合大多数部署。

573

574| 块 | 键 | 默认 | 描述 |

575| ---------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

576| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 按客户端地址的入站 IP 允许/拒绝，在 `trusted_proxies` 解析后。`deny_cidrs` 首先检查；与它匹配的客户端被拒绝，即使 `allow_cidrs` 也匹配。如果 `allow_cidrs` 非空，网关是默认拒绝。`/healthz` 和 `/readyz` 免除 `allow_cidrs`。 |

581| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未认证设备授权端点上的每 IP 速率限制。为共享出口 IP 或 NAT 后面的大型组织提高。这些限制仅适用于设备授权登录流，不适用于 `/v1/messages` 推理。请参阅[用户代码暴力破解抵抗](/zh-CN/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |

583

584<h2 id="complete-example">

585 完整示例

586</h2>

587

588此完整参考配置演示了每个核心部分；[HTTP 调整块](#http-tuning)保持其默认值。复制它，删除你不需要的，并填入你的值。[快速入门](/zh-CN/claude-apps-gateway#quickstart)中的配置是此的最小版本。

589

590```yaml gateway.yaml theme={null}

591# 运行方式：

592# claude gateway --config gateway.yaml

593#

594# 操作日志详细程度由 CLAUDE_GATEWAY_LOG_LEVEL

595# 环境变量控制（info | warn | error；默认 info）。它不

596# 影响审计事件，总是发出。

597

598listen:

599 host: 0.0.0.0

600 port: 8080

601 public_url: https://claude-gateway.internal.example.com

602 # 在 TLS 终止入口后面运行时省略 tls 块。

603 # tls:

604 # cert: /certs/gateway.crt

605 # key: /certs/gateway.key

606 # trusted_proxies:

607 # - 10.0.0.0/8

608

609oidc:

610 issuer: https://example.okta.com

611 client_id: 0oa1example2

612 client_secret: ${OIDC_CLIENT_SECRET}

613 allowed_email_domains:

614 - example.com

615 # 当发行者是 Okta 组织服务器时需要，其 id_token

616 # 可以省略电子邮件和组；网关从 /userinfo 填充它们。

617 userinfo_fallback: true

618 # allowed_groups: [claude-code-users]

619 # Okta 仅在请求 `groups` 范围且

620 # 应用的组声明过滤允许它们时发出组。下面的承包商策略

621 # 匹配组，因此范围在此处请求。

622 scopes: [openid, profile, email, offline_access, groups]

623 # extra_auth_params: { access_type: offline, prompt: consent } # Google

624 # groups_claim: groups # Entra 应用角色：使用 `roles`

625 # email_claim: email

626

627session:

628 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32

629 # ttl_hours: 1

630

631store:

632 postgres_url: ${GATEWAY_POSTGRES_URL}

633 # max_connections: 5

634

635# 启用 /v1/organizations/spend_limits（镜像 Anthropic Admin API）

636# 和 /v1/messages 上的每开发者支出强制。省略以禁用。

637# 上限本身通过 admin API 设置，而不是此处。

638# admin:

639# write_keys:

640# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

641# read_keys:

642# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

643# admin_groups: [platform-finops]

644# blocked_message: request an increase at https://go.example.com/claude-limits

645# # audit_retention_days: 365

646# # spend_retention_months: 13

647# # identity_retention_days: 90

648# # group_limit_mode: min

649

650# enforcement:

651# fail_closed_on_error: false

652

653upstreams:

654 - provider: anthropic

655 auth:

656 api_key: ${ANTHROPIC_API_KEY}

657

658 # - provider: bedrock

659 # region: us-east-1

660 # auth: {}

661

662 # - provider: vertex

663 # region: us-east5

664 # project_id: example-prod

665 # auth: {}

666

667 # - provider: foundry

668 # resource: example-foundry

669 # auth: { use_azure_ad: true }

670

671auto_include_builtin_models: true

672models:

673 - id: claude-opus-4-8

674 label: Claude Opus 4.8

675 upstream_model:

676 anthropic: claude-opus-4-8

677 # bedrock: us.anthropic.claude-opus-4-8

678 # vertex: claude-opus-4-8

679 # foundry: <your-opus-deployment-name>

680 - id: claude-sonnet-4-6

681 label: Claude Sonnet 4.6

682 upstream_model:

683 anthropic: claude-sonnet-4-6

684 - id: claude-haiku-4-5

685 label: Claude Haiku 4.5

686 upstream_model:

687 anthropic: claude-haiku-4-5

688

689managed:

690 policies:

691 - match: { groups: [contractors] }

692 cli:

693 availableModels: [claude-haiku-4-5]

694 # 将默认选择器选项限制为 availableModels 而不是

695 # 层默认，因此承包商不会在默认上获得 400。

696 enforceAvailableModels: true

697 # allow 自动批准这些工具；它不阻止其余的。

698 # 添加拒绝规则以限制工具。

699 permissions: { allow: [Read, Grep] }

700 - match: {}

701 cli:

702 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

703 permissions:

704 allow: [Read, Grep, Bash, Edit]

705 deny: ["WebFetch"]

706 env: { HTTP_PROXY: http://proxy.example.com:8080 }

707

708telemetry:

709 forward_to:

710 - url: https://otel.internal.example.com:4318

711 headers:

712 Authorization: Bearer ${OTEL_TOKEN}

713```

714

715<h2 id="client-side-managed-settings">

716 客户端托管设置

717</h2>

718

719上面的所有内容配置网关服务器。将开发者机器指向它是在每个设备上单独配置的，通过 Claude Code 的[托管设置](/zh-CN/settings#settings-files)。网关无法自己推送这些键，因为它们是告诉客户端网关在哪里的内容。

720

721对于 CLI，在每个 OS `managed-settings.json` 中设置两个键：

722

723```json theme={null}

724{

725 "forceLoginMethod": "gateway",

726 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"

727}

728```

729

730将该文件部署到每个设备，通常通过你的 MDM 平台。文件路径因平台而异：

731

732| 平台 | 路径 |

733| ----------- | --------------------------------------------------------------------------------------------------- |

734| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`，或 `com.anthropic.claudecode` 托管首选项域 |

735| Linux 和 WSL | `/etc/claude-code/managed-settings.json` |

736| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`，或通过 HKLM 注册表的组策略 |

737

738`forceLoginGatewayUrl` 和 `forceLoginMethod` 的 `"gateway"` 值仅从管理员控制的托管层被尊重。开发者在自己的 `~/.claude/settings.json` 中设置它们无效。

739

740<h2 id="related">

741 相关

742</h2>

743

744* [Claude 应用网关概述](/zh-CN/claude-apps-gateway)：快速入门和开发者连接

745* [部署指南](/zh-CN/claude-apps-gateway-deploy)：IdP 设置、容器镜像、Kubernetes 和 Cloud Run，以及操作

746* [支出限制](/zh-CN/claude-apps-gateway-spend-limits)：每开发者上限和 Admin API

claude-apps-gateway-deploy.md +301 −0 created

Details

1> ## Documentation Index

2> 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.

5# Claude 应用网关部署和运维

7> 向身份提供商注册网关，构建容器，在 Kubernetes 或 Cloud Run 上部署，并运维它：健康检查、密钥轮换、升级和安全。

9本页面涵盖运行 [Claude 应用网关](/zh-CN/claude-apps-gateway) 的运维方面：在身份提供商 (IdP) 中注册 OAuth 客户端、将网关部署为容器，以及日常运行。关于网关在启动时读取的 `gateway.yaml` 文件中的每个选项，请参阅 [配置参考](/zh-CN/claude-apps-gateway-config)。

11生产部署按顺序遵循四个步骤，下面的部分与之相对应。前两个是您做出选择的地方；后两个是在运行后参考的材料。

131. [设置身份提供商](#identity-provider-setup)：注册 OAuth 客户端并查看 Okta、Entra 和 Google 的特定 IdP 说明

142. [部署网关](#deployment)：构建固定版本的容器镜像并在 Kubernetes、Cloud Run 或您自己的平台上运行它。本部分还涵盖成本、绕过、多网关和无服务器决策

153. [设置运维](#operations)：日志、健康探针、中断行为、密钥轮换和升级。当您连接监控和运行手册时参考的材料

164. [审查安全态势](#security)：数据流向何处、威胁模型和合规性答案。用于安全审查的参考

18如果在此过程中登录或启动失败，请直接转到 [故障排除](#troubleshooting)，该部分按您看到的错误进行索引。

20<Note>

21 **在您的私有网络上部署。** Claude Code 仅连接到地址为私有的网关。这是一个安全防护，因为受信任的网关可以推送在开发者机器上运行命令的设置。将网关放在内部负载均衡器或 VPN 后面，并为其分配一个仅解析为私有 IP 的主机名。

22</Note>

24<h2 id="identity-provider-setup">

25 身份提供商设置

26</h2>

28向身份提供商注册一个机密 OAuth/OpenID Connect (OIDC) Web 应用程序，使用单个重定向 URI `https://<gateway>/oauth/callback`，并将其分配给应该有网关访问权限的用户或组。

30任何符合 OIDC 的 IdP 都可以工作：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必须满足三个要求：

32* 在生产环境中通过 HTTPS 提供 `/.well-known/openid-configuration`；网关接受 [`http://` 发行者](/zh-CN/claude-apps-gateway-config#oidc)，本地环回发行者另外需要 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`

33* 支持授权代码流。PKCE（代码交换证明密钥）默认启用；对于不支持它的 IdP，使用 `oidc.use_pkce: false` 禁用它

34* 在 id\_token 中返回 `email` 和可选的 `groups`，或使用 `oidc.userinfo_fallback: true` 从 userinfo 端点提供它们

36对于私有 PKI，设置 `oidc.ca_cert_pem`。

38一些提供商处理电子邮件和组声明的方式不同：

40* **Okta**：位于 `https://example.okta.com` 的组织授权服务器返回一个省略 `email` 和 `groups` 的简化 id\_token，因此当您将其用作 `issuer` 时设置 `oidc.userinfo_fallback: true`。包含 id\_token 中 `email` 和可选 `groups` 的自定义授权服务器（如 `https://example.okta.com/oauth2/default`）直接发出它们，不需要回退。Okta 仅在 `oidc.scopes` 中请求 `groups` 作用域且应用的组声明过滤器允许时才发出 `groups`；`userinfo_fallback` 无法填充 IdP 未被要求的声明。

41* **Microsoft Entra ID**：`issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`。Entra 发出组对象 ID 而不是名称，因此在 `managed.policies.match.groups` 中使用 GUID，或使用应用角色获得人类可读的名称。如果您的租户在 `roles` 而不是 `groups` 下发出角色，设置 `oidc.groups_claim: roles`。

42* **Google Workspace**：`issuer` = `https://accounts.google.com`。Google 的 id\_token 不包含组。要在 Google 作为 IdP 时使用基于组的 `allowed_groups` 或 `managed.policies`，配置 [`oidc.google_groups`](/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，使用 `oidc.allowed_email_domains` 进行成员资格门控，使用 `managed.policies.match.email_domain` 进行策略分配。Google 也忽略标准 `offline_access` 作用域。对于刷新令牌，设置 `oidc.scopes: [openid, profile, email]` 和 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`。

44有关不在上述范围内的身份提供商的支持，请参阅[故障排除](#troubleshooting)。

46<Warning>

47 刷新令牌让网关可以在不将开发者发送回浏览器的情况下无声地续订开发者的会话。它们也驱动取消配置，因为当 IdP 禁用用户时，下一次刷新失败，会话在 `ttl_hours` 内结束。网关默认请求 `offline_access` 以获取刷新令牌。如果您的 IdP 需要明确同意离线访问，配置 OAuth 客户端以允许它。

49 如果您的 IdP 根本无法发出刷新令牌，网关仍然可以工作，但没有无声续订，因此开发者在会话过期时重新运行浏览器登录。为了防止每小时都发生这种情况，将 [`session.ttl_hours`](/zh-CN/claude-apps-gateway-config#session) 提高到 `8` 或 `12`。权衡是取消配置延迟，因为没有刷新令牌，禁用的用户在更长的 TTL 过期之前保持访问权限。

50</Warning>

52<h2 id="deployment">

53 部署

54</h2>

56网关是一个单一的 Linux 二进制文件。它水平扩展，因为副本是无状态的，Postgres 是共享协调层。按照您在环境中运行无状态服务的方式运行它。本部分的其余部分说明镜像需要什么，并为 Kubernetes 和 Cloud Run 提供简短说明。

58网关设计为在您的网络内运行，因为它持有您的上游凭证并充当推理的单一出口点。它可以在您的开发者和您的 IdP 可以通过 HTTPS 到达的任何地方运行；将其视为任何其他持有生产凭证的服务。

60除了运行位置外，还有一些决策塑造部署：

62* **成本**：网关没有单独的许可证或按座位费用；它是 `claude` 二进制文件的一部分。您通过现有的云或 Anthropic 承诺为推理付费，加上容器的计算和您的遥测收集器。

63* **绕过**：网关不强制执行通过它的唯一模型路由。具有自己凭证的开发者仍然可以直接调用提供商，因此关闭该路径是网络策略决策，例如阻止到 `api.anthropic.com` 的出口，除了来自网关的。阻止该出口也会破坏 [WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，它从每个开发者的机器调用 `api.anthropic.com`；在托管策略中设置 `skipWebFetchPreflight: true` 以禁用它。

64* **多个网关**：每个网关是一个单独的部署，有自己的配置。CLI 按网关主机名存储其信任指纹和凭证，因此不同的团队可以连接到不同的网关而不会冲突。要提供多个 OIDC 发行者，运行单独的实例。

65* **无服务器**：Cloud Run 可以工作；设置 `min-instances: 1` 以避免冷 OIDC 发现。Lambda 和 Cloud Functions 不行，因为网关是一个长时间运行的 HTTP 服务器。

67这里的每个生产拓扑都在普通 HTTP 副本前面放置一个 L7 代理，如 Ingress、Cloud Run 的前端或 ALB。设置 [`listen.trusted_proxies`](/zh-CN/claude-apps-gateway-config#listen) 为代理的源范围，以便网关从 `X-Forwarded-For` 读取客户端 IP。网关仅在 TCP 对等体受信任时才遵守该标头；[Google Cloud 工作示例](/zh-CN/claude-apps-gateway-on-gcp) 为每个拓扑提供具体值。没有受信任的代理，每个请求似乎都来自代理的 IP，这会将按 IP 速率限制折叠为一个共享桶，并在审计事件中记录代理的 IP。

69<h3 id="container-image">

70 容器镜像

71</h3>

73围绕标准 Claude Code 版本中的本机 `claude` 二进制文件构建您自己的镜像：

751. 从固定版本下载您的镜像架构的 Linux 构建；请参阅 [安装特定版本](/zh-CN/setup#install-a-specific-version) 了解下载 URL。

762. 根据版本的 GPG 签名 `manifest.json` 验证它，如 [二进制完整性和代码签名](/zh-CN/setup#binary-integrity-and-code-signing) 中所述。

773. 将其复制到构建上下文中。

79如果您的构建无法到达版本主机，请将版本镜像到您的内部注册表中，并固定您的舰队运行的版本。

81除了二进制文件外，镜像还需要：

83* **基于 glibc 的镜像**：glibc 构建的唯一动态依赖项是 glibc 库。基于 Musl 的镜像需要 `linux-x64-musl` 或 `linux-arm64-musl` 构建加上额外的包；请参阅 [Alpine Linux 设置](/zh-CN/setup#alpine-linux-and-musl-based-distributions)。

84* **可写状态目录**：网关以任何用户身份运行，但最小镜像没有可写的主目录。将 `CLAUDE_CONFIG_DIR` 设置为可写路径，如 `/tmp/.claude`。

85* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置文件以只读方式挂载，密钥作为环境变量提供；网关在 `listen.port` 上监听，默认为 `8080`。

87<h3 id="kubernetes">

88 Kubernetes

89</h3>

91将网关作为 Deployment 运行，就像任何无状态服务一样：

93* 从 ConfigMap 挂载配置，从 Secret 挂载密钥；通过 `${file:/path/to/secret}` 或作为环境变量在 YAML 中引用密钥

94* 在 Ingress 处终止 TLS 并将 `listen.public_url` 设置为 Ingress 主机名

95* 将就绪探针指向 `GET /readyz`，将活跃探针指向 `GET /healthz`

97<Note>

98 **工作负载身份**

100 优先使用平台的工作负载身份而不是静态密钥：EKS 上的 IRSA 用于 Bedrock，GKE 上的工作负载身份用于 Agent Platform，AKS 上的工作负载身份用于 Foundry。在上游块中设置 `auth: {}`，或对 Foundry 设置 `use_azure_ad: true`，网关通过该提供商的默认凭证链获取 pod 的身份。对于跨云配对，如 GKE 上的 Bedrock 上游，在上游的 `auth` 块中设置显式凭证。[`upstreams` 参考](/zh-CN/claude-apps-gateway-config#upstreams) 有每个平台的设置详情。

101</Note>

102

103<h3 id="cloud-run">

104 Cloud Run

105</h3>

106

107按如下方式配置服务：

108

109* 将 `listen.port` 保留在其默认值 `8080`，这与 Cloud Run 的默认 `PORT` 匹配，或设置 `port: ${PORT}`

110* 将 `public_url` 设置为外部可达的源。对于生产，这通常是内部负载均衡器的主机名，因为 `/login` [拒绝公共地址](/zh-CN/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析为一个，所以单独的 Cloud Run URL 仅适用于 `curl` 或浏览器烟雾测试。例外是一个网络，其中 `*.run.app` 通过 Private Service Connect 和 Cloud DNS 私有区域私下解析；在该拓扑中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 工作示例](/zh-CN/claude-apps-gateway-on-gcp#deploy-the-gateway) 涵盖两者。

111* 将配置作为密钥卷挂载

112* 设置 `min-instances: 1` 以避免首次请求时的冷 OIDC 发现

113

114<Note>

115 有关 Google Cloud 上的完整工作示例，涵盖 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，请参阅 [在 Google Cloud 上部署](/zh-CN/claude-apps-gateway-on-gcp)。

116</Note>

117

118<h3 id="push-the-gateway-url-to-developer-machines">

119 将网关 URL 推送到开发者机器

120</h3>

121

122一旦网关开始提供服务，通过托管设置、MDM 或直接写入每个操作系统的 `managed-settings.json` 将 `forceLoginMethod` 和 `forceLoginGatewayUrl` 推送到每个开发者的机器。没有这个，`/login` 显示标准账户选择器，没有网关选项。请参阅 [客户端托管设置](/zh-CN/claude-apps-gateway-config#client-side-managed-settings) 了解文件路径。

123

124<h2 id="operations">

125 运维

126</h2>

127

128一旦网关开始提供流量，日常运维就是读取其日志、探测其健康状况，以及按您的计划轮换其密钥。下面的小节涵盖每一个，加上 Postgres 持有的内容以及升级和回滚的行为。

129

130<h3 id="logs">

131 日志

132</h3>

133

134网关向 stderr 写入两个流，都是 JSON 友好的：

135

136* **审计事件**：每个安全相关事件一行 JSON。将 stderr 管道传输到您的日志聚合器。发出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`spend.blocked` 和 `admin.denied`。字段因事件而异：

137 * 成功的 mint 和 refresh 事件携带 `sub`、`email`、`client_ip` 和结果

138 * 拒绝事件携带原因、路径和客户端 IP，因为拒绝时不存在身份

139 * `inference` 记录哪个上游提供了请求以及响应状态

140 * `admin.denied` 记录被拒绝的管理员 API 身份验证尝试，包括原因（`invalid_key` 或 `no_credentials`）、客户端 IP、方法和路径，不包括呈现的密钥材料

141* **运维日志**：人类可读的 `[gateway]` 前缀行，用于启动、警告和上游错误。`CLAUDE_GATEWAY_LOG_LEVEL` 环境变量控制详细程度，接受 `info`、`warn` 或 `error`，默认为 `info`。它不影响审计事件，这些事件总是被发出。

142

143<h3 id="health">

144 健康

145</h3>

146

147网关提供 `GET /healthz` 作为活跃探针，`GET /readyz` 作为就绪探针；`/readyz` 验证存储是否可达。两者都免除 `access_control.allow_cidrs`，因此探针在锁定的监听器上继续工作。

148

149`/.well-known/oauth-authorization-server` 处的 OAuth 发现文档也仅在配置加载、OIDC 发现、上游客户端构造和 Postgres 迁移全部成功后才返回 `200`，因此它也充当端到端启动检查。

150

151运行中的网关还在 `<public_url>/protocol` 提供它接受的路径和请求形状的描述，与您运行的版本相匹配。内容在版本之间不稳定。

152

153<h3 id="outage-behavior">

154 中断行为

155</h3>

156

157如果 Postgres 宕机，网关本身继续为已登录的开发者提供服务，新登录失败。开发者是否真的继续工作取决于您的编排器如何处理就绪：

158

159* **现有会话**：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理

160* **新登录**：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中

161* **[支出限制执行](/zh-CN/claude-apps-gateway-spend-limits#postgres-availability)**：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭

162* **就绪**：`/readyz` 在中断期间报告未就绪，因此在就绪上门控流量的编排器一次从轮换中移除每个副本。在该拓扑中，所有流量，包括网关仍然可以提供的推理，在负载均衡器处失败，直到 Postgres 恢复。`/healthz` 上的活跃探针继续通过，因此副本不会重新启动。如果您宁愿已登录的开发者在存储中断期间继续工作，将就绪探针指向 `/healthz`；成本是新登录失败，反对仍然报告就绪的副本。

163

164如果您的 IdP 宕机，现有会话工作直到 `ttl_hours`，新登录和刷新失败。如果您的 IdP 有频繁的维护窗口，设置更长的 `ttl_hours`。

165

166<h3 id="jwt-secret-rotation">

167 JWT 密钥轮换

168</h3>

169

170通过三个步骤轮换签名密钥，以便现有会话保持有效：

171

1721. 生成一个新密钥。将其前置到 `session.jwt_secret` 数组。

1732. 滚动部署。新令牌使用新密钥签名；旧令牌仍然验证。

1743. 在 `ttl_hours` 加上一个边距之后，移除旧密钥并再次滚动。

175

176轮换也是在过期前强制会话退出的唯一方式：持有者令牌针对 JWT 密钥在本地验证，因此没有按会话撤销。直接替换密钥，不在数组中保留旧密钥，一次使每个未完成的会话失效。对于个人离职，在您的 IdP 中取消配置用户；他们的会话在 `ttl_hours` 内结束。

177

178<h3 id="postgres">

179 Postgres

180</h3>

181

182网关持有五个表，全部由其启动时迁移创建：

183

184| 表 | 内容 | 保留 |

185| ------------------ | ---------------------------------- | --------------------------------------------- |

186| `kv` | 设备授权（10 分钟 TTL）和速率限制计数器 | 每行 TTL |

187| `spend` | 每个主体期间至今支出计数器，以美分计 | `admin.spend_retention_months`，默认 13 |

188| `spend_limits` | 配置的支出上限 | 直到通过 API 删除 |

189| `admin_audit` | 管理员 API 变更跟踪 | `admin.audit_retention_days`，默认 365 |

190| `principal_emails` | 每个主体的最后看到的电子邮件、显示名称和 IdP 组。包含 PII。 | `admin.identity_retention_days` 自上次活动以来，默认 90 |

191

192一个 30 秒的循环过期 `kv` 行超过其 TTL，一个每小时的扫描在支出表上强制保留窗口，因此没有什么无限增长。没有 [支出限制](/zh-CN/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被写入。如果您的安全策略禁止应用角色的 DDL，预先创建这些表和 `_migrations`，使用管理员角色，并授予应用角色 `SELECT, INSERT, UPDATE, DELETE` 在每个上。

193

194使用支出限制，丢失的数据库意味着丢失支出跟踪和上限，不仅仅是开发者重新登录，因此运行定期备份。要立即删除一个离职的开发者而不是等待保留，直接运行 `DELETE FROM principal_emails WHERE principal = '<sub>'`；这移除了唯一持有其电子邮件、名称和组的表。`spend` 和 `admin_audit` 行仅引用伪匿名 OIDC `sub`。

195

196<h3 id="upgrades">

197 升级

198</h3>

199

200副本是无状态的，因此滚动重启在任何时间都是安全的。网关在启动时运行架构迁移，这意味着部署新二进制文件会自动迁移数据库。如果数据库角色无法运行 DDL，预先创建架构，包括 `_migrations` 表，种子为当前版本；否则启动失败，尝试 `CREATE TABLE`。

201

202迁移是仅追加的，因此回滚到知道较少迁移的先前二进制文件是安全的；它忽略额外的行。回滚也重新验证 YAML 针对较旧二进制文件的架构，因此采用由较新版本引入的密钥的配置在较旧版本上启动失败。在回滚前移除新密钥。

203

204因为您在自己的镜像中固定网关的版本，新 Claude Code 版本中的修复，包括安全修复，仅在您更新固定并重新部署时才到达您的部署。在您用于持有生产凭证的其他服务的相同修补周期中包括网关。

205

206<h2 id="security">

207 安全

208</h2>

209

210本部分回答安全审查提出的问题：什么数据流经网关以及它去哪里，设计防御哪些攻击，以及哪些答案属于合规性问卷。

211

212<h3 id="data-flow">

213 数据流

214</h3>

215

216| 数据 | 路径 | 由网关发送给 Anthropic |

217| ----------------------------------------------------------------------- | -------------------------------------- | ------------------------ |

218| 推理（提示、完成） | CLI → 网关 → 您的上游 | 仅当 Anthropic API 是配置的上游时 |

219| 遥测（OTLP 指标，加上 [选择加入日志和跟踪](/zh-CN/claude-apps-gateway-config#telemetry)） | CLI → 网关 → 您的收集器 | 从不 |

220| 身份（电子邮件、组、sub） | IdP → 网关 → JWT → CLI；CLI 在 OTLP 导出上标记它 | 从不 |

221| 托管设置 | 您的网关 YAML → CLI | 从不 |

222| 审计日志 | 网关 stderr → 您的聚合器 | 从不 |

223

224<h3 id="threat-model-summary">

225 威胁模型摘要

226</h3>

227

228网关位于您的网络周边内，但个别开发者笔记本电脑不被视为受信任。设计通过三种方式考虑这一点：

229

230* 开发者持有短期 JWT 而不是原始上游密钥。CLI 到网关的腿使用 RFC 8628 设备授权，网关与 IdP 的授权代码交换在默认配置中运行 PKCE，因此拦截的 IdP 授权代码是无用的。

231* 设备验证页面强制执行同源 POST 和每个 RFC 8628 §5.1 的每 IP 速率限制。请参阅 [用户代码暴力破解抵抗](#user-code-brute-force-resistance)。

232* 出站请求通过服务器端请求伪造 (SSRF) 防护，解析 DNS，阻止链接本地和云元数据地址加上默认的本地环回，并将连接固定到解析的 IP，因此操作员影响的 URL（如 IdP 和 OTLP 目的地）无法重定向到云元数据端点。RFC 1918 私有范围被故意允许，因为 IdP 和 OTLP 收集器通常存在于私有 IP 上。对于针对本地环回 IdP 或收集器的本地开发，在网关的环境中设置 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`；在生产中保持未设置。

233

234如果您添加自己的出口控制，网关必须在使用实例元数据凭证（如工作负载身份）时到达元数据服务器。

235

236两个威胁超出范围，因为它们是您的基础设施来保护：

237

238* **受损的网关主机**：主机既持有上游凭证，又向每个连接的开发者分发 [托管设置](/zh-CN/claude-apps-gateway-config#managed)，因此对网关配置的控制与对您的 MDM 的控制相当。CLI 的一次性批准对话框用于 shell 能力设置限制无声更改，但不替代主机安全。

239* **恶意 OIDC 提供商**：提供商签署网关信任的 id\_tokens，因此它可以声称任何身份。审查和保护您的 IdP 是您的责任。

240

241<h3 id="user-code-brute-force-resistance">

242 用户代码暴力破解抵抗

243</h3>

244

245开发者在 `/device` 验证页面中输入的 `user_code` 是从 20 字符字母表中抽取的 8 个字符，产生 20⁸ 或约 2.56×10¹⁰ 个组合，在 10 分钟后过期。

246

247网关在设备授权端点上应用按 IP 速率限制，可通过 [`rate_limits`](/zh-CN/claude-apps-gateway-config#http-tuning) 配置。如果许多开发者从单个共享公司 NAT 地址登录，提高限制。限制仅适用于登录流，不适用于推理。

248

249<h3 id="compliance-posture">

250 合规性态势

251</h3>

252

253* **数据驻留**：网关自己的数据平面除非 Anthropic API 是配置的上游，否则不向 Anthropic 发送任何内容；当它是时，您现有的数据处理协议适用于推理路径。遥测、审计、身份和设置仅去往您配置的目的地。

254* **主机进程流量**：主机进程是 Claude Code CLI，它可以向 Anthropic 发送启动分析和更新检查。对于严格出口部署，在网关的容器环境中设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`。

255* **客户端分析**：CLI 在登录到网关时禁用自己的使用分析，错误报告在第三方 API 表面上默认关闭。

256* **客户端机器**：开发者的 CLI 仍然向 Anthropic 发送 WebFetch 主机名检查和版本检查，除非设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 和 `skipWebFetchPreflight: true`。请参阅 [数据使用](/zh-CN/data-usage)。

257* **调查评分**：网关凭证禁用 Anthropic 绑定的评分接收器，因此评分不发送给 Anthropic。

258* **成绩单共享**：在调查的成绩单共享提示上选择"是"会在 `~/.claude/feedback-bundles/` 下写入本地文件，而不是上传到 Anthropic。

259* **客户端更新**：更新检查与网关流量分开。通过您自己的分发固定版本，如果笔记本电脑不得获取版本，设置 `DISABLE_UPDATES`。`DISABLE_AUTOUPDATER` 仅停止后台更新，而 `claude update` 仍然有效。

260* **TLS**：在生产中通过 HTTPS 提供 `public_url`，要么从网关自己的监听器通过 `listen.tls`，要么从 TLS 终止入口在普通 HTTP 副本前面，设置 `listen.public_url`。网关不拒绝普通 HTTP。IdP 必须在生产中提供 HTTPS，Postgres 支持 `?sslmode=require`。在您的入口处设置 `Strict-Transport-Security`。

261* **漏洞披露**：遵循 [报告安全问题](/zh-CN/security#reporting-security-issues)

262

263<h2 id="troubleshooting">

264 故障排除

265</h2>

266

267有关问题和反馈，使用 [Claude Code 支持](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 存储库](https://github.com/anthropics/claude-code/issues) 上打开问题。报告问题时，包括：

268

269* **网关问题**：相关窗口的网关 stderr、您的 `gateway.yaml`（密钥已编辑），网关版本，显示在 `/` 处的登陆页面和 `/managed/settings` 上的 `x-cc-gateway-version` 响应标头中，以及最近更改的内容

270* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`，重现，并发送该文件加上相同窗口的网关审计日志

271* **推理问题**：请求的模型、配置的上游和请求的网关审计日志，记录哪个上游提供了它和响应状态

272

273| 症状 | 原因 | 修复 |

274| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

275| 开发者的 `/login` 显示标准账户选择器而不是 **Cloud gateway** 屏幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在该机器的托管设置中设置 | 将 [托管设置文件](/zh-CN/claude-apps-gateway#set-the-gateway-url) 部署到设备；`/login` 从那里读取网关 URL |

276| 启动显示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 安装的 Claude Code 构建早于网关支持 | 让开发者更新 Claude Code 到包括 Cloud gateway 支持的版本 |

277| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公共 IP 地址。Claude Code 检查每个解析的地址，需要每一个都是私有的。常见原因是一个双栈名称，其中一个族解析为公共地址，包括 AWS 内部双栈负载均衡器，它们返回公共范围 AAAA 地址 | 让网关名称在开发者机器上仅解析为私有地址。对于双栈名称，删除公共范围记录或提供单独的仅内部 DNS 名称。请参阅 [私有网络先决条件](/zh-CN/claude-apps-gateway#prerequisites)。 |

278| CLI `/login`：`Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，代理的主机名解析为公共地址。代理的主机解析为仅私有地址是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私有地址的代理 |

279| CLI `/login`：`Could not resolve gateway host <host>` | 机器无法解析网关的内部 DNS 名称，通常是因为它不在公司网络上 | 让开发者连接到您的网络或 VPN，然后重试 `/login` |

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

281| 启动退出：`requires the native binary` | 在 Node 下运行而不是本机二进制文件 | 使用 [独立安装方法](/zh-CN/setup) 之一安装 Claude Code |

282| 启动退出，OIDC 发现错误在 `config.load` 之后 | `oidc.issuer` 无法到达，或 TLS 链不受信任 | 检查发行者是否可从 pod 到达并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。 |

283| 启动退出，Postgres 权限错误 | 应用角色缺少 `CREATE TABLE` | 使用管理员角色预先创建架构，并授予应用角色 DML，或临时授予 DDL 用于应用新迁移的启动 |

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

285| 日志：`token exchange failed: 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`。 |

286| 每个 Bedrock 请求返回 502；日志显示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的默认跳数限制为 1 阻止来自容器内的实例元数据请求。启动和 `/readyz` 通过，因为 AWS SDK 在第一个请求时解析实例凭证，而不是在客户端构造时 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高跳数限制，或在启动模板中设置它。更改适用于实例上的每个容器。在可用的地方优先使用 ECS 任务角色，它从 ECS 容器凭证端点读取凭证，完全避免更改，或在专用网关实例上应用更改以限制暴露。 |

287| IdP 错误：unknown or unsupported scope | IdP 拒绝它不识别的作用域 | 将 `oidc.scopes` 设置为您的 IdP 接受的确切列表；它必须包括 `openid`。默认值为 `openid profile email offline_access`。 |

288| 设置 `oidc.scopes` 后会话不无声续订 | `offline_access` 从覆盖中删除 | 如果您的 IdP 支持，添加 `offline_access` 回来。没有刷新令牌，开发者每 `session.ttl_hours` 重新运行浏览器登录。 |

289| 浏览器显示"This request came from another site and was blocked" | 跨站点表单 POST，作为 CSRF 保护被阻止。对于嵌入或代理页面是预期的 | 直接打开验证链接 |

290| Chrome 用"Refused to send form data … violates … Content Security Policy directive: form-action"阻止"批准"按钮，但相同页面在 Safari 或 Firefox 中工作 | Chrome 对整个重定向链强制执行 `form-action`。您的 IdP 重定向到第二个主机，该主机未被列入白名单。 | 在 `oidc.form_action_origins` 中添加重定向链中的每个额外源。在"批准"页面上打开 Chrome DevTools → 控制台以查看哪个源被阻止。 |

291| 登录在 IdP 处完成，但回调失败，Chrome 中出现 CSP 错误或 Safari 中出现"this sign-in link has expired" | IdP 通过 `response_mode=form_post` 返回代码，它通过 POST 自动提交到 `/oauth/callback`。Chrome 在严格 CSP 下阻止它；Safari 允许提交，但回调仅读取查询字符串。 | 确保您的 IdP 遵守 `response_mode=query`，网关明确请求它，以便回调是普通重定向 |

292| 登录在本地工作，但在 ALB 后面失败 | `public_url` 未设置，因此 IdP 获取内部 `http://` 源作为 `redirect_uri` | 将 `listen.public_url` 设置为外部 `https://` 源 |

293| 开发者重复看到信任提示 | TLS 证书每个副本或每个请求轮换 | 在入口处使用稳定的证书，或终止 TLS 一次并在内部通过普通 HTTP 运行副本 |

294| CLI `/login`：`"Could not verify the gateway's TLS certificate"` 或 `SELF_SIGNED_CERT_IN_CHAIN` | 网关的 TLS 链由 CLI 主机的信任存储中不存在的私有 CA 签署 | Claude Code 默认在本机二进制文件上读取 OS 信任存储，在 Node 22.15 或更高版本上；[`CLAUDE_CODE_CERT_STORE`](/zh-CN/network-config#ca-certificate-store) 控制此行为。如果 CA 安装在 OS 信任存储中，确保开发者在当前运行时上。否则在启动前将 `NODE_EXTRA_CA_CERTS` 设置为 CA 证书 PEM。首次连接指纹提示仍然适用。 |

295

296<h2 id="related">

297 相关

298</h2>

299

300* [Claude 应用网关概述](/zh-CN/claude-apps-gateway)：快速入门和开发者连接

301* [配置参考](/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项

claude-apps-gateway-on-gcp.md +330 −0 created

Details

1> ## Documentation Index

2> 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.

5# 在 Google Cloud 上部署 Claude apps gateway

7> 在 Google Cloud 上运行 Claude apps gateway 的实际示例：Cloud Run 或 GKE、Cloud SQL for PostgreSQL、Secret Manager 和 Agent Platform 的服务账户身份验证。

9<Note>

10 本页介绍在 Google Cloud 上运行 Claude apps gateway 的一种方式。该配置是客户管理基础设施的工作示例，而不是受支持的生产部署；使用它来了解各个部分如何组合在一起，然后再根据您自己的环境进行调整。有关平台无关的要求，请参阅[部署指南](/zh-CN/claude-apps-gateway-deploy)。

11</Note>

13此示例在 Google Cloud 上配置 Claude apps gateway，使用 Google Cloud 的 Agent Platform 作为模型上游，使用 Cloud Run 或 GKE 进行计算。Google Workspace 是示例身份提供商 (IdP)，但任何符合 OpenID Connect (OIDC) 的 IdP 都可以工作；只有 `oidc` 块会改变。有关每个 IdP 的详细信息，请参阅[身份提供商设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。

15<h2 id="what-you’ll-build">

16 您将构建的内容

17</h2>

19<Frame>

20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude apps gateway 的图表：Claude Code 客户端通过 HTTPS 连接到网关（Cloud Run 或 GKE），网关在 VPC 内运行，旁边是用于会话状态的私有 IP Cloud SQL 数据库。网关通过 OIDC 针对 Google Workspace 对用户进行签名，从 Secret Manager 读取配置和机密，将模型请求转发到 Agent Platform，并在部署时从 Artifact Registry 拉取其镜像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />

21</Frame>

23参考配置配置以下内容：

25* **Cloud Run** 服务或 **GKE** Deployment 运行网关容器

26* **Artifact Registry** 存储库用于网关镜像

27* **Cloud SQL for PostgreSQL** 实例，仅限私有 IP，用于网关的[存储](/zh-CN/claude-apps-gateway-config#store)

28* **Secret Manager** 机密用于 `gateway.yaml`、JWT 签名密钥、OIDC 客户端机密和 Postgres URL

29* **服务账户**，具有 `roles/aiplatform.user`，直接附加到 Cloud Run 或通过 Workload Identity 绑定到 GKE

30* **内部应用负载均衡器**在 Cloud Run 上，或在 GKE 上的内部 **GKE Ingress**，类别为 `gce-internal`，用于 HTTPS

32<h2 id="prerequisites">

33 前置条件

34</h2>

36* 启用了计费的 GCP 项目，以及创建上述资源的权限

37* `gcloud` CLI，使用 `gcloud auth login` 进行身份验证，并在本地安装了 Docker

38* 对于 GKE 路径：`kubectl` 和在下面演练中创建的 VPC 上的 GKE 集群

39* 在 Model Garden 中访问您需要的 Claude 模型，在发布这些模型的区域中

40* Google Workspace OAuth 2.0 网络应用程序客户端，重定向 URI 为 `https://<gateway-host>/oauth/callback`；请参阅[身份提供商设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)

41* 网关的 TLS 主机名，通常是指向负载均衡器的内部 DNS 名称

43设置项目和区域一次：

45```bash theme={null}

46export PROJECT_ID=<your-project>

47export REGION=us-east5 # a region where the Claude models you need are published in Model Garden

48gcloud config set project "$PROJECT_ID"

49```

51<h2 id="deploy-the-gateway">

52 部署网关

53</h2>

55下面的步骤使用 `gcloud` 命令配置完整的部署。

57<Steps>

58 <Step title="启用 API">

59 启用演练使用的服务 API：

61 ```bash theme={null}

62 gcloud services enable \

63 aiplatform.googleapis.com \

64 artifactregistry.googleapis.com \

65 sqladmin.googleapis.com \

66 secretmanager.googleapis.com \

67 iamcredentials.googleapis.com \

68 iam.googleapis.com \

69 compute.googleapis.com \

70 servicenetworking.googleapis.com \

71 run.googleapis.com \

72 container.googleapis.com

73 ```

75 您需要的 API 取决于部署路径：

77 * `compute` 和 `servicenetworking`：私有 IP Cloud SQL 路径所需

78 * `run`：仅限 Cloud Run

79 * `container`：仅限 GKE

80 </Step>

82 <Step title="创建服务账户并授予 IAM">

83 网关作为专用服务账户运行，具有调用 Agent Platform 的权限。它通过 VPC 使用密码用户到达 Cloud SQL，因此不需要 Cloud SQL IAM 角色：

85 ```bash theme={null}

86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"

87 SA="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

89 gcloud projects add-iam-policy-binding "$PROJECT_ID" \

90 --member="serviceAccount:${SA}" --role="roles/aiplatform.user" --condition=None

91 ```

93 然后在 Model Garden 中为项目启用 Claude 模型；模型发布到特定区域，因此请检查每个模型卡。

94 </Step>

96 <Step title="构建镜像并将其推送到 Artifact Registry">

97 根据[容器镜像要求](/zh-CN/claude-apps-gateway-deploy#container-image)构建镜像，使用 `linux-x64` glibc 二进制文件，并推送它：

99 ```bash theme={null}

100 gcloud artifacts repositories create claude-gateway \

101 --repository-format=docker --location="$REGION"

102 gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet

103

104 # Cloud Run requires linux/amd64. --provenance=false avoids a buildx OCI

105 # image index that Cloud Run rejects.

106 docker build --platform=linux/amd64 --provenance=false \

107 -t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .

108 docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"

109 ```

110 </Step>

111

112 <Step title="配置 Cloud SQL for PostgreSQL">

113 通过 Private Services Access 在 VPC 上创建实例，使其没有公共 IP；这也满足强制执行 `constraints/sql.restrictPublicIp` 的项目：

114

115 ```bash theme={null}

116 VPC=cc-gateway-vpc

117 gcloud compute networks create "$VPC" --subnet-mode=custom

118 gcloud compute networks subnets create cc-gateway-subnet \

119 --network="$VPC" --region="$REGION" --range=10.0.0.0/24

120

121 # Private Services Access: one-time per VPC

122 gcloud compute addresses create "google-managed-services-${VPC}" \

123 --global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"

124 gcloud services vpc-peerings connect \

125 --service=servicenetworking.googleapis.com \

126 --ranges="google-managed-services-${VPC}" --network="$VPC"

127

128 gcloud sql instances create claude-gateway-db \

129 --database-version=POSTGRES_16 --tier=db-g1-small --region="$REGION" \

130 --network="projects/${PROJECT_ID}/global/networks/${VPC}" --no-assign-ip

131 gcloud sql databases create claude_gateway --instance=claude-gateway-db

132 PGPASS="$(openssl rand -hex 24)"

133 gcloud sql users create gateway --instance=claude-gateway-db --password="$PGPASS"

134

135 PRIVATE_IP="$(gcloud sql instances describe claude-gateway-db \

136 --format='value(ipAddresses[0].ipAddress)')"

137 GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${PRIVATE_IP}:5432/claude_gateway?sslmode=require"

138 ```

139

140 Cloud Run 或 GKE 运行时必须在此 VPC 上或路由到此 VPC。

141 </Step>

142

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

144 `upstreams` 块使用 `auth: {}` 指向 Agent Platform，因此网关通过运行时服务账户的应用默认凭据进行身份验证。有关每个字段，请参阅[配置参考](/zh-CN/claude-apps-gateway-config)。

145

146 两个 `listen` 字段取决于什么在网关前面：

147

148 * `public_url`：在 Cloud Run 或 GKE Ingress 后面时需要。网关仅从此值构建 IdP `redirect_uri` 和其发现文档，从不从 `X-Forwarded-*` 标头构建。

149 * `trusted_proxies`：前端的源范围。网关仅当 TCP 对等体在此列表中时才遵守 `X-Forwarded-For`，然后遍历链越过受信任的跳跃，因此按 IP 的登录速率限制和审计事件记录开发人员 IP 而不是负载均衡器的。

150

151 设置 `trusted_proxies` 以匹配您的前端。类别为 `gce` 的外部 GKE Ingress 未列出：它配置一个公共转发规则地址，`/login` [私有网络检查](/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。

152

153 | 前端 | `trusted_proxies` |

154 | -------------------------------- | -------------------------------- |

155 | 直接到达的 Cloud Run，无负载均衡器 | `[169.254.0.0/16]` |

156 | Cloud Run 前面的内部应用负载均衡器 | `169.254.0.0/16` 加上您的仅代理子网的 CIDR |

157 | GKE 内部 Ingress，类别 `gce-internal` | 您的仅代理子网的 CIDR |

158

159 下面的示例使用内部负载均衡器前面的 Cloud Run 值。

160

161 ```yaml gateway.yaml theme={null}

162 listen:

163 host: 0.0.0.0

164 port: 8080

165 public_url: https://claude-gateway.internal.example.com

166 trusted_proxies: [169.254.0.0/16, <your-proxy-only-subnet-cidr>]

167

168 oidc:

169 issuer: https://accounts.google.com

170 client_id: <your-oauth-client-id>

171 client_secret: ${OIDC_CLIENT_SECRET} # GKE: ${file:/secrets/oidc-client-secret}

172 allowed_email_domains: [example.com]

173 # Google ignores offline_access; these yield refresh tokens:

174 scopes: [openid, profile, email]

175 extra_auth_params: { access_type: offline, prompt: consent }

176

177 session:

178 jwt_secret: ${GATEWAY_JWT_SECRET} # GKE: ${file:/secrets/jwt-secret}

179

180 store:

181 postgres_url: ${GATEWAY_POSTGRES_URL} # GKE: ${file:/secrets/postgres-url}

182

183 upstreams:

184 - provider: vertex

185 region: <your-region> # must match $REGION

186 project_id: <your-project>

187 auth: {} # ADC via the runtime service account

188 ```

189

190 <Note>

191 Google id\_tokens 不携带 `groups` 声明。要在 [`managed.policies`](/zh-CN/claude-apps-gateway-config#managed) 中使用基于组的策略，并将 Google Workspace 作为 IdP，请配置 [`oidc.google_groups`](/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，改为匹配 `email_domain`。

192 </Note>

193 </Step>

194

195 <Step title="在 Secret Manager 中存储机密">

196 创建四个机密并授予 `roles/secretmanager.secretAccessor` 给 `claude-gateway` 服务账户：

197

198 | 机密 | 来源 |

199 | ---------------------------- | -------------------------------------- |

200 | `gateway-jwt-secret` | `openssl rand -base64 32` |

201 | `gateway-oidc-client-secret` | Google Cloud Console → OAuth 客户端 |

202 | `gateway-postgres-url` | Cloud SQL 步骤中的 `$GATEWAY_POSTGRES_URL` |

203 | `gateway-config` | 前一步中的完整 `gateway.yaml` |

204

205 机密到达容器的方式因路径而异：

206

207 * 在 GKE 上，它们通过 Secret Manager CSI 驱动程序作为文件挂载，`gateway.yaml` 引用 `${file:/secrets/...}`。

208 * 在 Cloud Run 上，它无法将多个机密挂载到一个目录中，`gateway.yaml` 作为文件挂载，其他三个作为环境变量注入，因此 `gateway.yaml` 改为引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

209 </Step>

210

211 <Step title="部署">

212 <Tabs>

213 <Tab title="Cloud Run">

214 下面的命令在内部负载均衡器后面为生产部署。

215

216 ```bash theme={null}

217 gcloud run deploy claude-gateway \

218 --image="${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" \

219 --region="$REGION" \

220 --service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \

221 --min-instances=1 \

222 --timeout=3600 \

223 --ingress=internal-and-cloud-load-balancing \

224 --network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \

225 --set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \

226 --no-invoker-iam-check

227 ```

228

229 直接 VPC 出口，通过 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`，让服务直接到达 Cloud SQL 私有 IP。到 Agent Platform 端点和 `accounts.google.com` 的公共出口直接进入互联网，而不是通过 VPC，因此不需要 Cloud NAT。

230

231 调用者 IAM 检查必须打开或禁用。网关运行自己的 OIDC，其客户端不携带 GCP 令牌，因此 Cloud Run 的调用者检查必须允许未经身份验证的请求。网关的 OIDC 登录在请求到达容器后对其进行身份验证，使用 `allowed_email_domains` 限制哪些域可以登录。

232

233 两个标志允许未经身份验证的请求：

234

235 * `--no-invoker-iam-check`：禁用检查，无需管理 `allUsers` 绑定，并在域受限共享下工作

236 * `--allow-unauthenticated`：授予 `allUsers` `run.invoker` 角色；如果您的组织不允许 `--no-invoker-iam-check`，请使用它

237

238 通过 `--ingress` 的入口限制是与调用者检查独立的单独层；保持设置以将服务限制在您的公司网络。

239

240 默认情况下，Cloud Run `*.run.app` URL 解析为公共地址，`/login` [私有网络检查](/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。两种拓扑为开发人员提供私有可解析的主机名，Cloud Run 都不为您配置：

241

242 * **内部应用负载均衡器**，上面部署命令假设的拓扑：使用 `--ingress=internal-and-cloud-load-balancing` 部署，在服务前面配置内部应用负载均衡器，具有内部 DNS 名称和证书，并将 `listen.public_url` 设置为该主机名。

243 * **仅限内部入口，无负载均衡器**：使用 `--ingress=internal` 部署，并将 `listen.public_url` 保留为 `*.run.app` URL，下面[参考资产](#terraform-reference)中的默认值。为了让 `*.run.app` 私有解析，您的网络团队必须已经运营 Google API 的 Private Service Connect 端点、解析 `*.run.app` 到它的 Cloud DNS 私有区域，以及到该端点的本地路由。

244

245 Google 的 [Cloud Run 私有网络指南](https://cloud.google.com/run/docs/securing/private-networking)涵盖了两个选项都需要的基础设施。在网关在私有主机名上提供服务后验证登录；在那之前，从 Cloud Run 中的日志确认容器启动。

246

247 在第一次登录前更新 OAuth 客户端的授权重定向 URI 为 `<public_url>/oauth/callback`。更改 `public_url` 后重新部署，因为网关仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。

248 </Tab>

249

250 <Tab title="GKE">

251 集群必须在 Cloud SQL 步骤中创建的 `$VPC` 上，以便 pod 可以到达数据库的私有 IP；仅 VPC 对等不起作用，因为 Cloud SQL 私有 IP 本身是对等网络，对等是非传递的。要在该 VPC 上创建新集群，请将 `--network="$VPC" --subnetwork=cc-gateway-subnet` 传递给 `gcloud container clusters create`。

252

253 在集群及其节点池上启用 Workload Identity，然后将 Google 服务账户绑定到 Kubernetes 服务账户，以便 pod 继承其凭据：

254

255 ```bash theme={null}

256 gcloud container clusters update <cluster> --region="$REGION" \

257 --workload-pool="${PROJECT_ID}.svc.id.goog"

258 # On a Standard cluster, existing node pools also need GKE_METADATA;

259 # Autopilot enables this by default.

260 gcloud container node-pools update <pool> --cluster=<cluster> \

261 --region="$REGION" --workload-metadata=GKE_METADATA

262

263 kubectl create namespace claude-gateway

264 kubectl create serviceaccount gateway -n claude-gateway

265

266 gcloud iam service-accounts add-iam-policy-binding \

267 "claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \

268 --role roles/iam.workloadIdentityUser \

269 --member "serviceAccount:${PROJECT_ID}.svc.id.goog[claude-gateway/gateway]"

270

271 kubectl annotate serviceaccount gateway -n claude-gateway \

272 iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

273 ```

274

275 将网关部署为标准 Deployment 加上 Service 和内部 Ingress，类别 `gce-internal`，如[Kubernetes 部署](/zh-CN/claude-apps-gateway-deploy#kubernetes)中所述，具有：

276

277 * `serviceAccountName: gateway`

278 * Secret Manager CSI 驱动程序在 `/secrets` 处挂载机密

279 * 就绪探针指向 `GET /readyz`

280

281 将具有提高的 `timeoutSec` 的 BackendConfig 附加到网关 Service：GKE Ingress 后面的负载均衡器后端服务默认为 30 秒超时，这会切断长流式响应。

282

283 不要在 Workload Identity 集群上应用阻止 `169.254.169.254` 的出口 NetworkPolicy；pod 必须到达元数据服务器以获取凭据。网关的内置 [SSRF 防护](/zh-CN/claude-apps-gateway-deploy#threat-model-summary)是那里的防御。

284

285 网关记录启动警告，指出元数据端点可达，并建议应用出口 NetworkPolicy。在 Workload Identity 下，该警告是预期的，因为 pod 需要端点。

286 </Tab>

287 </Tabs>

288 </Step>

289

290 <Step title="将网关 URL 推送到开发人员机器">

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

292 </Step>

293</Steps>

294

295<h2 id="terraform-reference">

296 Terraform 参考

297</h2>

298

299[参考部署资产](https://github.com/anthropics/claude-code/tree/main/examples/gateway/gcp)自动化本页的 Cloud Run 路径；配置和镜像资产适用于两条路径：

300

301* `setup.sh`：一个幂等的 `gcloud` 配置程序，遍历完整的 Cloud Run 路径，从启用 API 到第一次部署

302* `terraform/`：相同的部署作为基础设施即代码，用于绿地部署：创建 Artifact Registry 存储库的目标应用，然后构建和推送镜像，然后完整应用

303* `gateway.yaml.example` 和用于 distroless 运行时镜像的 `Dockerfile`

304

305工件默认 Cloud Run 入口为 `internal`，因此不需要负载均衡器。要匹配本页的生产后面 ALB 部署，使用 `INGRESS=internal-and-cloud-load-balancing` 运行 `setup.sh`，或将 Terraform 变量 `ingress` 设置为 `INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`。工件还默认调用者层为 `allUsers` `run.invoker` 授予而不是 `--no-invoker-iam-check`，与本页演练相反；两者都有效，选择取决于您的组织的策略约束。

306

307资产作为工作示例提供，而不是受支持的生产工件；查看并根据您的环境调整它们。

308

309<h2 id="troubleshooting">

310 故障排除

311</h2>

312

313有关网关启动和登录错误，请参阅平台无关的[故障排除表](/zh-CN/claude-apps-gateway-deploy#troubleshooting)。下面的条目特定于 Google Cloud。

314

315| 症状 | 原因 | 修复 |

316| --------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |

317| Cloud Run 在到达容器前返回 `403 Forbidden` | 调用者 IAM 检查仍然启用 | 使用 `--no-invoker-iam-check` 部署，或使用 `--allow-unauthenticated` 授予 `allUsers` `run.invoker` 角色 |

318| `--no-invoker-iam-check` 被拒绝，显示 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果通过 `constraints/iam.allowedPolicyMemberDomains` 的域受限共享也阻止了它，请使用 GKE 路径，它在网络层公开网关，无需 `allUsers` 绑定。 |

319| 部署时 `Container manifest type … must support amd64/linux` | 镜像在非 amd64 主机上构建，或 buildx 发出了 OCI 镜像索引 | 使用 `--platform=linux/amd64 --provenance=false` 构建 |

320| 网关启动在 Cloud Run 上以 Postgres 连接超时错误退出 | 服务未附加到 VPC，或 Cloud SQL 在该 VPC 上没有私有 IP；存储在 5 秒后停止等待 | 使用 `--network` 和 `--subnet` 部署以进行直接 VPC 出口，并使用 `--no-assign-ip` 和 `--network` 指向同一 VPC 创建 Cloud SQL 实例 |

321| Agent Platform 请求返回 `403 PERMISSION_DENIED` | 运行时未使用 `claude-gateway` 服务账户，或模型未在 Model Garden 中为项目启用 | 在 Cloud Run 上设置 `--service-account` 或在 GKE 上绑定 Workload Identity，并在 Model Garden 中为目标区域启用每个 Claude 模型 |

322| 流式响应在固定持续时间后切断 | 前端请求超时：GKE Ingress 后面的负载均衡器后端服务默认为 30 秒，Cloud Run 默认为 300 秒 | 在 GKE 上附加具有提高的 `timeoutSec` 的 BackendConfig，或在 Cloud Run 上使用 `--timeout=3600` 部署 |

323

324<h2 id="next-steps">

325 后续步骤

326</h2>

327

328* [配置参考](/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项，包括 `managed.policies` 和 `telemetry`

329* [部署和操作](/zh-CN/claude-apps-gateway-deploy)：IdP 设置、健康检查、JWT 密钥轮换、升级和安全模型

330* [Claude apps gateway 概述](/zh-CN/claude-apps-gateway)：快速入门和连接开发人员

claude-apps-gateway-spend-limits.md +162 −0 created

Details

1> ## Documentation Index

2> 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.

5# Claude 应用网关支出限制

7> 通过 Claude 应用网关为每个开发者按天、周或月设置支出上限。使用 Admin API 设置限制，网关在每个请求上实时执行这些限制。

9支出限制限制了每个开发者在给定的一天、一周或一个月内通过你的 [Claude 应用网关](/zh-CN/claude-apps-gateway) 可以花费的金额。当开发者超过他们的上限时，网关在他们的下一个请求上返回 `429`，并阻止他们直到该周期重置或管理员提高上限。使用支出限制为每个开发者、团队或整个组织设置一个共享凭证的上限。

11Claude 应用网关通过一个共享的上游凭证转发所有推理，因此你的提供商的账单将所有内容归属于该凭证，而不是单个开发者。没有按开发者的限制，一个失控的代理群可能会花费组织的整个承诺。支出限制是网关在该共享账单之上的按开发者视图和断路器。

13<h2 id="set-a-cap">

14 设置上限

15</h2>

17配置了 [`admin:`](/zh-CN/claude-apps-gateway-config#admin) 块在 `gateway.yaml` 中后，网关在 `/v1/organizations/spend_limits` 处提供一个 admin API，并在每个推理请求上实时执行上限。上限本身通过该 API 设置，而不是在 `gateway.yaml` 中；每个 `POST /v1/organizations/spend_limits` 请求从 `{scope, amount, period}` 创建或替换一个上限。该 API 镜像了 Anthropic 的公共 [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) 支出限制端点的线路形状，因此针对该契约编写的 HTTP 客户端可以通过更改其基础 URL 来针对网关。

19此请求为每个开发者设置了一个组织范围的默认值，每月 \$500：

21```bash theme={null}

22curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \

23 -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \

24 -H "Content-Type: application/json" \

25 -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

26```

28此请求在 `contractors` 组的每个成员上分层了一个更严格的每天 \$100 的上限：

30```bash theme={null}

31curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \

32 -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \

33 -H "Content-Type: application/json" \

34 -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'

35```

37| 字段 | 值 | 描述 |

38| ------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

39| `scope.type` | `user`, `rbac_group`, `organization` | `user` 通过其 OpenID Connect (OIDC) `sub`（你的身份提供商分配的稳定用户 ID）针对一个开发者；将其作为 `scope.user_id` 传递。`rbac_group` 通过名称针对一个 [IdP 组](/zh-CN/claude-apps-gateway-config#managed)；将其作为 `scope.rbac_group_id` 传递。`organization` 是组织范围的默认值。网关接受所有三个；Anthropic 的公共 `POST` 目前仅限用户。 |

40| `amount` | USD 美分的整数字符串，或 `null` | `null` 是无限制的。`"0"` 是零上限，它阻止每个请求。 |

41| `period` | `daily`, `weekly`, `monthly` | 一个作用域可以为每个时期保持一个上限，每个都独立执行：如果开发者超过其中任何一个，他们就会被阻止。 |

43组或组织上限是每个成员继承的按座位默认值，而不是共享池。每个时期，开发者的有效上限按以下顺序解决：按用户覆盖，然后是其组上限中最严格的，然后是组织默认值，然后是无限制。[`admin.group_limit_mode: max`](/zh-CN/claude-apps-gateway-config#admin) 将多组平局打破翻转为最不严格的。

45<h3 id="authenticate-to-the-admin-api">

46 向 admin API 进行身份验证

47</h3>

49发送以下之一：

51* 一个 `x-api-key` 标头，匹配 [`admin.write_keys`](/zh-CN/claude-apps-gateway-config#admin) 中的一个密钥以获得完全访问权限，或 `admin.read_keys` 以获得仅 `GET` 访问权限。每个密钥都有一个 `id`，在审计日志中显示为 `admin-key:<id>`，因此为 Terraform、CI 和每个自动化提供自己的密钥。

52* 一个网关承载令牌，其 `groups` 声明包括 [`admin.admin_groups`](/zh-CN/claude-apps-gateway-config#admin) 中的一个。这是完全访问权限，审计为 `oidc:<sub>`，因此对人类管理员更好。

54<h2 id="how-enforcement-works">

55 执行如何工作

56</h2>

58在每个 `/v1/messages` 请求上，网关在一个 Postgres 查询中解决开发者的上限和期间至今的支出。如果他们超过任何上限，请求返回 `429`，`error.type: billing_error` 和标头 `x-should-retry: false`。消息是 `spend limit reached`，后跟你的 [`admin.blocked_message`](/zh-CN/claude-apps-gateway-config#admin)（如果设置）。

60`/v1/messages/count_tokens` 是豁免的。令牌计数是免费的，因此无论上限状态如何都会运行。

62在每个响应之后，使用计量器从响应中读取令牌计数，当它流向客户端时，以 USD 列表价格对其进行定价，并为所有三个时期桶增加 Postgres 计数器。计量器是流上的单个读取器，因此客户端的字节不受影响，计量失败不会破坏响应。

64支出限制从 USD 列表价格的令牌计数估计支出；它们是断路器，而不是发票。对于权威计费，请根据你的提供商自己的使用报告进行协调，例如 Anthropic 使用和成本 Admin API、Bedrock 上的调用日志或 Google Cloud 上的 Cloud Monitoring。

66定价使用与 Claude Code CLI 用于自己的成本显示相同的表，具有跨 Anthropic、Bedrock (`us.anthropic.…-v1:0`)、Agent Platform (`claude-…@date`) 和 Foundry ID 形式的相同模型 ID 规范化。表无法放置的模型 ID（例如 Foundry 部署名称或推理配置文件 ARN）以未知模型默认层 \$5/\$25 每百万输入/输出令牌的价格定价，而不是零，因此无法识别的 ID 无法通过不计量来绕过上限。网关在启动时和运行时每个 ID 一次警告模型何时通过回退定价。

68客户端中止也被计费。上游仅在流的终端帧中报告输出令牌，因此中止的流不会携带它们。计量器从流式内容大小保持保守的下限估计，大约每令牌四个字符，并在终端使用帧缺失时计费。完整流始终计费上游报告的计数。没有这个，一个受限的开发者可以流式输出并在结束前立即中止每个请求，花费而不被计数。

70<h3 id="postgres-availability">

71 Postgres 可用性

72</h3>

74预检查使用两秒超时查询 Postgres。如果存储无法访问或超时，执行默认情况下失败打开：请求继续，网关记录警告。设置 [`enforcement.fail_closed_on_error: true`](/zh-CN/claude-apps-gateway-config#enforcement) 改为失败关闭，它返回相同的 `429 billing_error`，消息为 `spend limit unavailable`。失败打开防止存储中断成为推理中断；失败关闭保证没有无计量支出。

76<h2 id="admin-api-reference">

77 Admin API 参考

78</h2>

80下面的端点在 `/v1/organizations/spend_limits` 下提供。

82| 方法和路径 | 描述 |

83| ---------------------------------------------- | ---------------------------------------------- |

84| `GET /v1/organizations/spend_limits` | 列出配置的上限。查询：`?limit=&after_id=&before_id=`。 |

85| `POST /v1/organizations/spend_limits` | 为 `{scope, period}` 创建或替换上限。 |

86| `GET /v1/organizations/spend_limits/{id}` | 通过其 `spl_` 前缀 ID 获取一个上限。 |

87| `DELETE /v1/organizations/spend_limits/{id}` | 删除一个上限。返回 `{type: "spend_limit_deleted", id}`。 |

88| `GET /v1/organizations/spend_limits/effective` | 每个主体每个时期的已解决上限和至今支出。 |

89| `GET /v1/organizations/spend_limits/audit` | 管理员变更跟踪，最新优先。查询：`?limit=`。 |

91约定镜像 Anthropic 的 Admin API：

93* 每个对象上的 `type`

94* `spl_` 前缀 ID

95* 金额为 USD 美分的整数字符串；`POST` 拒绝任何其他 `currency`，返回 `400`

96* `{type: "error", error: {type, message}, request_id}` 错误信封

97* 每个管理员响应上的 `request-id` 响应标头，成功或错误，匹配正文的 `request_id`

99每个变更在同一事务中向 `admin_audit` 写入前/后行，归属于 `admin-key:<id>` 或 `oidc:<sub>`。

100

101网关仅提供支出限制端点。其他 Admin API 表面，例如 `spend_limit_increase_requests` 队列，不是网关 Admin API 的一部分。

102

103<h3 id="/effective">

104 `/effective`

105</h3>

106

107`GET /v1/organizations/spend_limits/effective` 返回 Anthropic 的 `SpendSummary` 模式：每行是一个主体的一个时期，具有已解决的上限、期间至今的支出和一个 `actor` 对象。网关特定的差异：

108

109* `user_id` 是 OIDC `sub`。

110* `actor.name` 和 `actor.email_address` 是 `null`，直到主体通过网关的第一个推理请求。网关没有用户目录；它从每个用户自己的会话 JWT 记录最后看到的值。

111* 每行还携带一个 `groups` 数组，主体的最后看到的 IdP 组。这是一个网关扩展，因此管理员 UI 可以显示应用的每个上限层；Anthropic 形状的客户端忽略它。

112* 没有 `user_ids[]` 过滤器，它列出有记录支出的主体，因为网关无法枚举所有组织成员。

113

114组源上限根据那些最后看到的组解决，具有与执行使用的相同 `group_limit_mode` 平局打破，因此查看器显示实际应用的上限。

115

116| 查询参数 | 描述 |

117| ---------------- | ----------------------------------------------- |

118| `user_ids[]` | 可重复。按 OIDC `sub` 过滤到特定主体。 |

119| `period[]` | 可重复。过滤到 `daily`、`weekly` 或 `monthly` 行。 |

120| `sort` | `spend_desc` 首先列出最高支出者。需要恰好一个 `period[]`。 |

121| `q` | 对 OIDC `sub`、最后看到的电子邮件和最后看到的显示名称的不区分大小写的子字符串过滤。 |

122| `limit` / `page` | 页面大小（1–1000，默认 20）和前一个响应的 `next_page` 中的不透明游标。 |

123

124<Warning>

125 `q=` 和 `user_ids[]=` 乘坐 GET 查询字符串，因此任何前置代理或负载均衡器在其访问日志中捕获它们。如果你的 PII 日志策略很严格，请在那里清理这些参数。

126</Warning>

127

128<h3 id="/audit">

129 `/audit`

130</h3>

131

132返回支出限制变更跟踪：谁更改了哪个上限、前/后快照和可选原因，最新优先。`has_more` 是精确的。此端点遵循本地 Admin API 约定，而不是第一方线路形状。

133

134<h3 id="pagination">

135 分页

136</h3>

137

138原始列表按 `after_id` 和 `before_id` 分页，它们是互斥的 `spl_…` ID；结果按创建排序，`has_more` 反映遍历方向。`/effective` 按传回的不透明 `next_page` 令牌分页为 `?page=`，主体按升序排序，因此在记录支出时页面保持稳定。`limit` 在两者上都是 1–1000，默认 20。

139

140<h2 id="data-lifecycle">

141 数据生命周期

142</h2>

143

144网关保持四个支出相关的表；每小时扫描执行保留窗口：

145

146| 表 | 内容 | 保留 |

147| ------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------- |

148| `spend` | 按主体期间至今的计数器（美分） | [`admin.spend_retention_months`](/zh-CN/claude-apps-gateway-config#admin)，默认 13 |

149| `spend_limits` | 配置的上限 | 直到通过 API 删除 |

150| `admin_audit` | 变更跟踪 | [`admin.audit_retention_days`](/zh-CN/claude-apps-gateway-config#admin)，默认 365 |

151| `principal_emails` | 每个主体的最后看到的电子邮件、显示名称和 IdP 组。包含 PII。 | [`admin.identity_retention_days`](/zh-CN/claude-apps-gateway-config#admin) 自上次活动以来，默认 90 |

152

153`identity_retention_days` 故意比 `spend_retention_months` 短：一个已取消配置的身份停止刷新并老化，而其匿名支出计数器保持用于年度报告。

154

155当开发者离开时，通过 `DELETE /v1/organizations/spend_limits/{id}` 删除任何按用户上限；他们的支出和身份行按上面的保留窗口老化。要立即擦除一个人，用于离职或数据主体访问请求 (DSAR)，直接针对网关数据库运行 `DELETE FROM principal_emails WHERE principal = '<sub>'`。这删除了唯一保存其电子邮件、名称和组的表。`spend` 和 `admin_audit` 行仅引用伪匿名 OIDC `sub`，并按其自己的窗口老化。

156

157<h2 id="related">

158 相关

159</h2>

160

161* [`admin` 和 `enforcement` 配置](/zh-CN/claude-apps-gateway-config#admin)：启用 admin API 和调整保留

162* [部署指南](/zh-CN/claude-apps-gateway-deploy#postgres)：Postgres 模式和备份指导

claude-code-on-the-web.md +15 −8

Details

186| 归档环境 | 打开环境进行编辑并选择**归档**。归档的环境从选择器中隐藏，但现有会话继续运行。 |186| 归档环境 | 打开环境进行编辑并选择**归档**。归档的环境从选择器中隐藏，但现有会话继续运行。 |

188 188

189环境变量使用 `.env` 格式，每行一个 `KEY=value` 对。不要用引号包装值，因为引号会存储为值的一部分。189环境变量使用 `.env` 格式，每行一个 `KEY=value` 对。不要用引号包装值，因为引号会存储为值的一部分。此示例定义了三个变量：

190 190

191```text theme={null}191```text theme={null}

192NODE_ENV=development192NODE_ENV=development

593 * \*.sentry.io593 * \*.sentry.io

594 * downloads.sentry-cdn.com594 * downloads.sentry-cdn.com

595 * http-intake.logs.datadoghq.com595 * http-intake.logs.datadoghq.com

596 * browser-intake-us5-datadoghq.com

596 * \*.datadoghq.com597 * \*.datadoghq.com

597 * \*.datadoghq.eu598 * \*.datadoghq.eu

598 * api.honeycomb.io599 * api.honeycomb.io

641 642

642这在 claude.ai 上创建一个新的云会话。会话克隆你当前目录的 GitHub 远程，位于你的当前分支，所以如果你有本地提交，请先推送，因为 VM 从 GitHub 而不是你的机器克隆。`--remote` 一次只能处理单个存储库。任务在云中运行，而你继续在本地工作。643这在 claude.ai 上创建一个新的云会话。会话克隆你当前目录的 GitHub 远程，位于你的当前分支，所以如果你有本地提交，请先推送，因为 VM 从 GitHub 而不是你的机器克隆。`--remote` 一次只能处理单个存储库。任务在云中运行，而你继续在本地工作。

643 644

645{/* min-version: 2.1.195 */}从 v2.1.195 开始，CLI 显示设置步骤的实时清单，例如克隆存储库和运行你的[设置脚本](#setup-scripts)，同时云容器启动。你在容器配置期间输入的消息会被排队，并在会话准备好后发送。

646

644<Note>647<Note>

645 `--remote` 创建云会话。`--remote-control` 无关：它公开本地 CLI 会话以从网络进行监控。请参阅[远程控制](/zh-CN/remote-control)。648 `--remote` 创建云会话。`--remote-control` 无关：它公开本地 CLI 会话以从网络进行监控。请参阅[远程控制](/zh-CN/remote-control)。

646</Note>649</Note>

703使用以下任何方式将云会话拉入终端：706使用以下任何方式将云会话拉入终端：

704 707

705* **使用 `--teleport`**：从命令行，运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果你有未提交的更改，系统会提示你先隐藏它们。708* **使用 `--teleport`**：从命令行，运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果你有未提交的更改，系统会提示你先隐藏它们。

706* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport`（或 `/tp`）以打开相同的会话选择器，无需重启 Claude Code。709* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport` 或 `/tp` 以打开相同的会话选择器，无需重启 Claude Code。

707* **从 `/tasks`**：运行 `/tasks` 以查看你的后台会话，然后按 `t` 传送到其中一个710* **从 `/tasks`**：运行 `/tasks` 以查看你的后台会话，然后按 `t` 传送到其中一个。

708* **从网络界面**：选择**在 CLI 中打开**以复制可以粘贴到终端中的命令711* **从网络界面**：选择**在 CLI 中打开**以复制可以粘贴到终端中的命令。

709 712

710当你传送一个会话时，Claude 验证你在正确的存储库中，从云会话获取并检出分支，并将完整的对话历史加载到终端中。713当你传送一个会话时，Claude 验证你在正确的存储库中，从云会话获取并检出分支，并将完整的对话历史加载到终端中。

711 714

752 755

753自动压缩在上下文窗口接近容量时自动运行。要更早触发它，在你的[环境变量](#configure-your-environment)中设置 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/zh-CN/env-vars)。例如，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` 在 70% 容量而不是等待窗口几乎满时压缩。要更改压缩计算的有效窗口大小，请使用 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-CN/env-vars)。756自动压缩在上下文窗口接近容量时自动运行。要更早触发它，在你的[环境变量](#configure-your-environment)中设置 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/zh-CN/env-vars)。例如，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` 在 70% 容量而不是等待窗口几乎满时压缩。要更改压缩计算的有效窗口大小，请使用 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-CN/env-vars)。

754 757

755[Subagents](/zh-CN/sub-agents)的工作方式与本地相同。Claude 可以使用 Task 工具生成它们，以将研究或并行工作卸载到单独的上下文窗口中，保持主对话更轻。在你的存储库的 `.claude/agents/` 中定义的 Subagents 会自动被拾取。[Agent teams](/zh-CN/agent-teams)默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](#configure-your-environment)来启用。758[Subagents](/zh-CN/sub-agents)的工作方式与本地相同。Claude 可以使用 Task 工具生成它们，以将研究或并行工作卸载到单独的上下文窗口中，保持主对话更轻。在你的存储库的 `.claude/agents/` 中定义的 Subagents 会自动被拾取。

759

760[Agent teams](/zh-CN/agent-teams)默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](#configure-your-environment)来启用。

756 761

757<h3 id="review-changes">762<h3 id="review-changes">

758 审查更改763 审查更改

770 从 Enterprise 或 Team 账户共享775 从 Enterprise 或 Team 账户共享

771</h4>776</h4>

772 777

773对于 Enterprise 和 Team 账户，两个可见性选项是**私有**和**团队**。团队可见性使会话对你的 claude.ai 组织的其他成员可见。默认情况下启用存储库访问验证，基于连接到收件人账户的 GitHub 账户。你的账户显示名称对所有有访问权限的收件人可见。[Claude in Slack](/zh-CN/slack) 会话会自动以团队可见性共享。778对于 Enterprise 和 Team 账户，两个可见性选项是**私有**和**团队**。团队可见性使会话对你的 claude.ai 组织的其他成员可见。[Claude in Slack](/zh-CN/slack) 会话会自动以团队可见性共享。

779

780默认情况下启用存储库访问验证，基于连接到收件人账户的 GitHub 账户。你的账户显示名称对所有有访问权限的收件人可见。

774 781

775<h4 id="share-from-a-max-or-pro-account">782<h4 id="share-from-a-max-or-pro-account">

776 从 Max 或 Pro 账户共享783 从 Max 或 Pro 账户共享

863 870

864* 检查 [status.claude.com](https://status.claude.com) 以了解云会话事件871* 检查 [status.claude.com](https://status.claude.com) 以了解云会话事件

865* 一分钟后重试，因为容量是按需配置的872* 一分钟后重试，因为容量是按需配置的

866* 确认你的存储库可访问。连接的 GitHub 账户必须通过 Claude GitHub App 授权或通过 `/web-setup` 同步的 `gh` 令牌在 GitHub 上拥有对存储库的访问权限 — 不需要在存储库上安装该应用。请参阅 [GitHub 身份验证选项](#github-authentication-options)。873* 确认你的存储库可访问。连接的 GitHub 账户必须通过 Claude GitHub App 授权或通过 `/web-setup` 同步的 `gh` 令牌在 GitHub 上拥有对存储库的访问权限。不需要在存储库上安装该应用。请参阅 [GitHub 身份验证选项](#github-authentication-options)。

867 874

868<h3 id="remote-control-session-expired-or-access-denied">875<h3 id="remote-control-session-expired-or-access-denied">

869 远程控制会话已过期或访问被拒绝876 远程控制会话已过期或访问被拒绝

873 880

874* 在本地运行 `/login` 以刷新你的凭证，然后重新连接881* 在本地运行 `/login` 以刷新你的凭证，然后重新连接

875* 确认你已登录到拥有会话的相同账户882* 确认你已登录到拥有会话的相同账户

876* 如果你看到 `Remote Control may not be available for this organization`，你的管理员尚未为你的计划启用云会话883* 如果你看到 `Remote Control may not be available for this organization`，管理员尚未为你的组织启用云会话

877 884

878<h3 id="environment-expired">885<h3 id="environment-expired">

879 环境已过期886 环境已过期

claude-platform-on-aws.md +1 −1

Details

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

284export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5284export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5

285export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7285export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7

286export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6286export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

287export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5287export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

288```288```

289 289

cli-reference.md +2 −1

Details

25| `claude gateway` | 启动自托管 [Claude apps gateway](/zh-CN/claude-apps-gateway) 服务器，供在 Bedrock、Vertex AI 或 Foundry 上部署 SSO 和策略在 Claude Code 前面的管理员使用。需要 `--config` 指向 [`gateway.yaml`](/zh-CN/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更高版本中可用。 | `claude gateway --config gateway.yaml` |

26| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |27| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |

96| `--model` | 为当前会话设置模型，使用最新模型的别名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称。覆盖 [`model`](/zh-CN/settings#available-settings) 设置和 [`ANTHROPIC_MODEL`](/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-4-6` |97| `--model` | 为当前会话设置模型，使用最新模型的别名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称。覆盖 [`model`](/zh-CN/settings#available-settings) 设置和 [`ANTHROPIC_MODEL`](/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |

97| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。<br /><br />[`/rename`](/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |98| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。<br /><br />[`/rename`](/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |

99| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |100| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |

commands.md +2 −0

Details

71| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |71| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |

73| `/design-login` | 使用您的 claude.ai 账户授权设计系统访问权限以供 `/design-sync` 使用 |

74| `/design-sync [hint]` | **[Skill](/zh-CN/skills#bundled-skills).** 转换您的存储库的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，以便它生成的设计使用您的真实组件。可选择性地命名设计系统，例如 `/design-sync Acme DS`。首次同步验证每个组件，在大型存储库上可能需要几个小时。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，底层工具无法访问 claude.ai，因此该命令不可用 |

computer-use.md +3 −3

Details

112 一次一个会话112 一次一个会话

113</h3>113</h3>

114 114

115Computer use 在活动时持有机器范围的锁。如果另一个 Claude Code 会话已在使用您的计算机，新的尝试会失败并显示一条消息，告诉您哪个会话持有锁。首先完成或退出该会话。115Computer use 从第一个 computer use 操作开始持有机器范围的锁，直到执行该操作的会话退出。{/* min-version: 2.1.195 */}从 v2.1.195 开始，完成任务不会释放锁；只有退出会话才会释放锁。如果另一个 Claude Code 会话已在使用您的计算机，新的尝试会失败并显示一条消息，告诉您哪个会话持有锁。首先退出该会话。

116 116

117<h3 id="apps-are-hidden-while-claude-works">117<h3 id="apps-are-hidden-while-claude-works">

118 Claude 工作时应用被隐藏118 Claude 工作时应用被隐藏

134 随时停止134 随时停止

135</h3>135</h3>

136 136

137当 Claude 获取锁时，会出现 macOS 通知："Claude is using your computer · press Esc to stop"。在任何地方按 `Esc` 立即中止当前操作，或在终端中按 `Ctrl+C`。无论哪种方式，Claude 都会释放锁、取消隐藏您的应用，并将控制权返回给您。137当 Claude 获取锁时，会出现 macOS 通知："Claude is using your computer · press Esc to stop"。在任何地方按 `Esc` 立即中止当前操作，或在终端中按 `Ctrl+C`。无论哪种方式，Claude 都会停止、取消隐藏您的应用，并将控制权返回给您。会话保持 [computer use 锁](#one-session-at-a-time)，直到它退出。

138 138

139当 Claude 完成时，会出现第二个通知。139当 Claude 完成时，会出现第二个通知。

140 140

221 "Computer use is in use by another Claude session"221 "Computer use is in use by another Claude session"

222</h3>222</h3>

223 223

224另一个 Claude Code 会话持有锁。完成该会话中的任务或退出它。如果另一个会话崩溃，当 Claude 检测到该进程不再运行时，锁会自动释放。224另一个 Claude Code 会话持有锁，它会一直保持到该会话退出。退出该会话。如果另一个会话崩溃，当 Claude 检测到该进程不再运行时，锁会自动释放。

225 225

226<h3 id="macos-permissions-prompt-keeps-reappearing">226<h3 id="macos-permissions-prompt-keeps-reappearing">

227 macOS 权限提示不断重新出现227 macOS 权限提示不断重新出现

context-window.md +1 −1

Details

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

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

1617 1617

1618如果您需要更大的窗口而不是更小的对话，Fable 5、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。1618如果您需要更大的窗口而不是更小的对话，Fable 5、Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/zh-CN/model-config#extended-context)。Sonnet 5 以 1M 运行，无需选择 `[1m]` 变体；有关其自动压缩阈值和 LLM 网关异常，请参阅[Sonnet 5 上下文窗口](/zh-CN/model-config#sonnet-5-context-window)。压缩在更大的限制下以相同的方式工作。

1619 1619

1620<h2 id="check-your-own-session">1620<h2 id="check-your-own-session">

1621 检查您自己的会话1621 检查您自己的会话

costs.md +1 −1

Details

51 对于具有自定义速率限制的组织，此工作区中的 Claude Code 流量计入您的组织整体 API 速率限制。您可以在 Claude Console 的此工作区的 Limits 页面上设置[工作区速率限制](https://platform.claude.com/docs/zh-CN/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份额并保护其他生产工作负载。51 对于具有自定义速率限制的组织，此工作区中的 Claude Code 流量计入您的组织整体 API 速率限制。您可以在 Claude Console 的此工作区的 Limits 页面上设置[工作区速率限制](https://platform.claude.com/docs/zh-CN/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份额并保护其他生产工作负载。

52</Note>52</Note>

53 53

54在 Bedrock、Vertex 和 Foundry 上，Claude Code 不会从您的云中发送指标。已经通过 [LLM gateway](/zh-CN/llm-gateway) 路由 Claude Code 的组织可以在那里跟踪支出，因为网关会看到每个请求。54在 Bedrock、Vertex 和 Foundry 上，Claude Code 不会从您的云中发送指标。自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供按用户使用情况归因、带有令牌计数的 OTLP 指标，以及这些提供商上的[按用户支出限制](/zh-CN/claude-apps-gateway-spend-limits)。通过不同 [LLM gateway](/zh-CN/llm-gateway) 路由 Claude Code 的组织可以在网关处跟踪支出，因为网关会看到每个请求。

55 55

56<h3 id="rate-limit-recommendations">56<h3 id="rate-limit-recommendations">

57 速率限制建议57 速率限制建议

data-usage.md +2 −2

Details

39 39

40在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话记录以帮助我们改进 Claude Code 吗？"。这是一个与评分不同的可选第二步：40在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话记录以帮助我们改进 Claude Code 吗？"。这是一个与评分不同的可选第二步：

41 41

42* **是**：将您的对话记录、任何子代理记录和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的记录保留最多 6 个月。42* **是**：将您的对话记录、任何子代理记录和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的记录保留最多 6 个月。在 Bedrock、Vertex AI、Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，"是"会将相同的有效负载写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是上传；在您转发该文件之前，没有任何内容离开您的计算机。

43* **否**：拒绝而不发送任何内容43* **否**：拒绝而不发送任何内容

44* **不再询问**：拒绝并停止此后续在未来会话中出现44* **不再询问**：拒绝并停止此后续在未来会话中出现

45 45

127 按 API 提供商的默认行为127 按 API 提供商的默认行为

128</h2>128</h2>

129 129

130默认情况下，当使用 Bedrock、Vertex、Foundry 或 Claude Platform on AWS 时，错误报告、遥测和错误报告被禁用。会话质量调查和 WebFetch 域安全检查是例外，无论提供商如何都会运行。您可以通过设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次选择退出所有非必需的流量，包括调查。此变量不影响 WebFetch 检查，它有自己的选择退出选项。以下是完整的默认行为：130默认情况下，当使用 Bedrock、Vertex、Foundry 或 Claude Platform on AWS 时，错误报告、遥测和错误报告被禁用。会话质量调查和 WebFetch 域安全检查是例外，无论提供商如何都会运行。在已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，使用分析、错误报告和向 Anthropic 的调查评分由网关凭证本身禁用，没有重新启用的设置。您可以通过设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次选择退出所有非必需的流量，包括调查。此变量不影响 WebFetch 检查，它有自己的选择退出选项。以下是完整的默认行为：

131 131

133| ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |133| ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |

debug-your-config.md +2 −2

Details

19对于特定类别的详细信息，请使用专用命令：19对于特定类别的详细信息，请使用专用命令：

20 20

21| 命令 | 显示内容 |21| 命令 | 显示内容 |

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

23| `/memory` | 加载了哪些 `CLAUDE.md` 和规则文件，加上自动内存条目 |23| `/memory` | 加载了哪些 `CLAUDE.md` 和规则文件，加上自动内存条目 |

24| `/skills` | 来自项目、用户和插件源的可用 skills |24| `/skills` | 来自项目、用户和插件源的可用 skills |

25| `/agents` | 配置的子代理及其设置 |25| `/agents` | 配置的子代理及其设置 |

26| `/hooks` | 活跃的 hook 配置 |26| `/hooks` | 活跃的 hook 配置 |

27| `/mcp` | 连接的 MCP 服务器及其状态 |27| `/mcp` | 连接的 MCP 服务器及其状态 |

28| `/permissions` | 当前生效的已解析允许和拒绝规则 |28| `/permissions` | 当前生效的已解析允许和拒绝规则 |

~~29| `/doctor` | 配置诊断：无效的键、schema 错误、安装健康状况 |~~29| `/doctor` | 配置诊断：无效的键、schema 错误、安装健康状况。{/* min-version: 2.1.196 */}从 v2.1.196 开始，还会报告在同一作用域中定义的重复[子代理](/zh-CN/sub-agents)名称，并标记哪一个是活跃的 |

31| `/status` | 活跃的设置源，包括是否启用了托管设置 |31| `/status` | 活跃的设置源，包括是否启用了托管设置 |

32 32

deep-links.md +1 −1

Details

63| 参数 | 描述 |63| 参数 | 描述 |

64| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |64| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

65| `q` | 在提示框中预填充的文本。[URL 编码](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)该值。在多行提示中使用 `%0A` 表示换行符。最多 5,000 个字符。 |65| `q` | 在提示框中预填充的文本。[URL 编码](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)该值。在多行提示中使用 `%0A` 表示换行符。最多 5,000 个字符。 |

66| `cwd` | 用作工作目录的绝对路径。网络和 UNC 路径被拒绝。 |66| `cwd` | 用作工作目录的绝对路径。网络和 UNC 路径被拒绝，包含不可见或双向控制字符的路径也被拒绝。 |

68 68

69`cwd` 和 `repo` 是[设置工作目录的两种方式](#choose-between-cwd-and-repo)。如果你同时传递两者，`cwd` 优先，`repo` 被忽略，即使 `cwd` 路径不存在。69`cwd` 和 `repo` 是[设置工作目录的两种方式](#choose-between-cwd-and-repo)。如果你同时传递两者，`cwd` 优先，`repo` 被忽略，即使 `cwd` 路径不存在。

desktop.md +10 −6

Details

8 8

9Claude Desktop 应用有三个选项卡：**Chat** 用于对话，**Cowork** 用于 [Dispatch 和更长的代理工作](https://claude.com/product/cowork)，**Code** 用于软件开发。本页是 Code 选项卡的参考。9Claude Desktop 应用有三个选项卡：**Chat** 用于对话，**Cowork** 用于 [Dispatch 和更长的代理工作](https://claude.com/product/cowork)，**Code** 用于软件开发。本页是 Code 选项卡的参考。

10 10

~~11<CardGroup cols={2}>~~11<CardGroup cols={3}>

12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

13 Universal build for Intel and Apple Silicon13 Universal build for Intel and Apple Silicon

14 </Card>14 </Card>

16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

17 For x64 processors17 For x64 processors

18 </Card>18 </Card>

20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/en/desktop-linux">

21 apt or .deb for Ubuntu and Debian

22 </Card>

19</CardGroup>23</CardGroup>

20 24

21For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). The desktop app is not available on Linux; use the [CLI](/en/quickstart) instead.25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/en/desktop-linux).

22 26

23安装后，启动 Claude，登录，然后点击 **Code** 选项卡。第一次在 Windows 上打开它时，你需要安装 [Git for Windows](https://git-scm.com/downloads/win)；安装后重启应用。有关首次会话的演练，请参阅[快速开始指南](/zh-CN/desktop-quickstart)。27安装后，启动 Claude，登录，然后点击 **Code** 选项卡。第一次在 Windows 上打开它时，你需要安装 [Git for Windows](https://git-scm.com/downloads/win)；安装后重启应用。有关首次会话的演练，请参阅[快速开始指南](/zh-CN/desktop-quickstart)。

24 28

88 92

89<span id="auto-mode-availability" />93<span id="auto-mode-availability" />

90 94

91Auto mode 是一个研究预览版，在 Anthropic API 上对所有用户可用，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6。在路由到 Google Cloud Vertex AI 的企业部署中，Auto mode 处于关闭状态，直到你[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)，并且只有 Claude Opus 4.7 和 Opus 4.8 在那里受支持。95Auto mode 是一个研究预览版，在 Anthropic API 上对所有用户可用，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在路由到 Google Cloud Vertex AI 的企业部署中，Auto mode 处于关闭状态，直到你[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)，并且只有 Claude Sonnet 5、Opus 4.7 和 Opus 4.8 在那里受支持。

92 96

93<Tip title="最佳实践">97<Tip title="最佳实践">

94 在 Plan Mode 中启动复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到"自动接受编辑"或"询问权限"来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/zh-CN/best-practices#explore-first-then-plan-then-code)。98 在 Plan Mode 中启动复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到"自动接受编辑"或"询问权限"来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/zh-CN/best-practices#explore-first-then-plan-then-code)。

600 604

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

602 606

603[Extended thinking](/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。要禁用思考，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0`；这对 Fable 5 没有影响，Fable 5 始终使用 extended thinking。在[第三方提供商](/zh-CN/third-party-integrations)上，`0` 会省略 `thinking` 参数，自适应推理模型可能仍然会思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，任何其他 `MAX_THINKING_TOKENS` 值都被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 为 `1` 来使用固定思考预算；Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。607[Extended thinking](/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。要禁用思考，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0`；这对 Fable 5 没有影响，Fable 5 始终使用 extended thinking。在[第三方提供商](/zh-CN/third-party-integrations)上，`0` 会省略 `thinking` 参数，自适应推理模型可能仍然会思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，任何其他 `MAX_THINKING_TOKENS` 值都被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 为 `1` 来使用固定思考预算；Fable 5、Sonnet 5 和 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。

604 608

605<h3 id="cloud-sessions">609<h3 id="cloud-sessions">

606 云会话610 云会话

822以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：826以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：

823 827

824* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。企业部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Vertex AI 和网关提供商。对于 CLI 中的 Bedrock 或 Foundry，请参阅[快速入门](/zh-CN/quickstart)。作为上述部分的例外，[Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)在 Bedrock、Vertex AI、Foundry 或自托管 LLM 网关上运行 Code 选项卡。828* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。企业部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Vertex AI 和网关提供商。对于 CLI 中的 Bedrock 或 Foundry，请参阅[快速入门](/zh-CN/quickstart)。作为上述部分的例外，[Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)在 Bedrock、Vertex AI、Foundry 或自托管 LLM 网关上运行 Code 选项卡。

825* **Linux**：桌面应用仅在 macOS 和 Windows 上可用。在 Linux 上，使用 [CLI](/zh-CN/quickstart)。829* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/zh-CN/desktop-linux)。

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

827* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。831* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。

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

862如果应用打开但显示空白或无响应的屏幕：866如果应用打开但显示空白或无响应的屏幕：

863 867

8641. 重启应用。8681. 重启应用。

8652. 检查待处理的更新。应用在启动时自动更新。8692. 检查待处理的更新。在 macOS 和 Windows 上，应用在启动时自动更新；在 Linux 上，通过 apt 更新，如 [Claude Desktop on Linux](/zh-CN/desktop-linux) 中所述。

8663. 在 Windows 上，在 **Windows 日志 → 应用程序** 下的事件查看器中检查崩溃日志。8703. 在 Windows 上，在 **Windows 日志 → 应用程序** 下的事件查看器中检查崩溃日志。

867 871

868<h3 id="failed-to-load-session">872<h3 id="failed-to-load-session">

desktop-linux.md +113 −0 created

Details

1> ## Documentation Index

2> 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.

5# Linux 上的 Claude Desktop（测试版）

7> 在 Ubuntu 和 Debian 上安装和更新 Claude 桌面应用

9<Note>

10 Claude 桌面应用的 Linux 支持处于测试版阶段。Chat、Cowork 和 Code 选项卡都可用。

11</Note>

13Linux 上的桌面应用提供与 macOS 和 Windows 相同的 Chat、Cowork 和 Claude Code 体验：并行会话、可视化差异审查、集成终端和编辑器以及实时应用预览。有关完整的功能参考，请参阅[使用 Claude Code Desktop](/zh-CN/desktop)。

15<h2 id="requirements">

16 要求

17</h2>

19* Ubuntu 22.04 或更高版本，或 Debian 12 或更高版本

20* x86\_64 或 arm64

22其他满足这些要求的基于 Debian 的发行版可能可以工作，但未经过官方测试。

24<h2 id="install">

25 安装

26</h2>

28从 Anthropic 的 apt 存储库安装，以便更新通过系统的常规包更新到达。

30<Steps>

31 <Step title="添加 Anthropic 的 apt 存储库">

32 下载 Anthropic 的签名密钥：

34 ```bash theme={null}

35 sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc

36 ```

38 注册存储库：

40 ```bash theme={null}

41 echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list

42 ```

43 </Step>

45 <Step title="安装软件包">

46 ```bash theme={null}

47 sudo apt update && sudo apt install claude-desktop

48 ```

49 </Step>

51 <Step title="启动并登录">

52 从应用启动器启动 **Claude**，或从终端运行 `claude-desktop`，然后使用您的 Anthropic 账户登录。

53 </Step>

54</Steps>

56<Accordion title="验证签名密钥">

57 您可以确认下载的签名密钥属于 Anthropic：

59 ```bash theme={null}

60 gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc

61 ```

63 指纹应该是 `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`。

64</Accordion>

66<h3 id="install-from-a-downloaded-file">

67 从下载的文件安装

68</h3>

70如果您无法使用 apt 存储库，请从 [claude.com/download](https://claude.com/download) 下载适用于您的架构（x64 或 arm64）的 `.deb` 软件包，然后使用软件安装程序打开它或从下载目录运行：

72```bash theme={null}

73sudo apt install ./claude-desktop_*.deb

74```

76以这种方式安装的 `.deb` 不会接收更新。要通过 apt 获取更新，请添加上面显示的存储库，或取消注释软件包写入 `/etc/apt/sources.list.d/claude-desktop.list` 的占位符条目中的 `deb` 行。

78<h2 id="update">

79 更新

80</h2>

82桌面应用在 Linux 上不会自动更新。更新通过系统的常规包更新到达：

84```bash theme={null}

85sudo apt update && sudo apt upgrade

86```

88您的发行版的图形软件更新程序也会获取新版本。

90<h2 id="uninstall">

91 卸载

92</h2>

94```bash theme={null}

95sudo apt remove claude-desktop

96```

98这会删除签名密钥以及应用，因此如果您在安装期间添加了存储库条目，也要删除它：

100```bash theme={null}

101sudo rm /etc/apt/sources.list.d/claude-desktop.list

102```

103

104<h2 id="what’s-not-in-the-linux-beta-yet">

105 Linux 测试版中尚未包含的内容

106</h2>

107

108* **Computer Use**：[应用和屏幕控制](/zh-CN/desktop#let-claude-use-your-computer)在 Linux 上不可用。

109* **Dictation**：语音输入在 Linux 桌面应用中不可用。请改用 CLI 中的[语音听写](/zh-CN/voice-dictation)。

110* **Quick Entry 全局热键**：在 X11 上有效。在原生 Wayland 上，它需要您的桌面环境的 GlobalShortcuts 门户。

111* **Fedora 和 RHEL**：目前仅支持基于 Debian 的发行版。对其他发行版的支持将在未来推出。

112

113对于桌面应用中尚未提供的任何功能，[CLI](/zh-CN/quickstart) 运行相同的 Claude Code 引擎并支持更广泛的 Linux 发行版范围；请参阅[系统要求](/zh-CN/setup#system-requirements)。

desktop-quickstart.md +7 −3

Details

8 8

9桌面应用为您提供具有图形界面的 Claude Code，专为并行运行多个会话而构建：用于管理并行工作的侧边栏、带有集成终端和文件编辑器的拖放布局、可视化差异审查、实时应用预览、GitHub PR 监控和自动合并以及计划任务。无需终端。9桌面应用为您提供具有图形界面的 Claude Code，专为并行运行多个会话而构建：用于管理并行工作的侧边栏、带有集成终端和文件编辑器的拖放布局、可视化差异审查、实时应用预览、GitHub PR 监控和自动合并以及计划任务。无需终端。

10 10

~~11<CardGroup cols={2}>~~11<CardGroup cols={3}>

13 Universal build for Intel and Apple Silicon13 Universal build for Intel and Apple Silicon

14 </Card>14 </Card>

17 For x64 processors17 For x64 processors

18 </Card>18 </Card>

20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/en/desktop-linux">

21 apt or .deb for Ubuntu and Debian

22 </Card>

19</CardGroup>23</CardGroup>

20 24

22 26

23<Note>27<Note>

24 Claude Code 需要 [Pro、Max、Team 或 Enterprise 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。28 Claude Code 需要 [Pro、Max、Team 或 Enterprise 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。

40 44

41<Steps>45<Steps>

42 <Step title="安装并登录">46 <Step title="安装并登录">

43 从上面的链接下载您的平台的安装程序并运行它。在 macOS 上从应用程序文件夹启动 Claude，或在 Windows 上从开始菜单启动，然后使用您的 Anthropic 账户登录。47 在 macOS 和 Windows 上，从上面的链接下载安装程序并运行它。在 Linux 上，请按照 [Claude Desktop on Linux](/zh-CN/desktop-linux) 中的安装步骤进行操作。在 macOS 上从应用程序文件夹启动 Claude，在 Windows 上从开始菜单启动，或在 Linux 上从应用程序启动器启动，然后使用您的 Anthropic 账户登录。

44 </Step>48 </Step>

45 49

46 <Step title="打开 Code 选项卡">50 <Step title="打开 Code 选项卡">

discover-plugins.md +19 −9

Details

223 **快捷方式**：您可以使用 `/plugin market` 代替 `/plugin marketplace`，以及使用 `rm` 代替 `remove`。223 **快捷方式**：您可以使用 `/plugin market` 代替 `/plugin marketplace`，以及使用 `rm` 代替 `remove`。

224</Tip>224</Tip>

225 225

226* **GitHub 存储库**：`owner/repo` 格式（例如，`anthropics/claude-code`）226* **GitHub 存储库**：`owner/repo` 格式，例如 `anthropics/claude-code`

227* **Git URL**：任何 git 存储库 URL（GitLab、Bitbucket、自托管）227* **Git URL**：任何 git 存储库 URL，包括 GitLab、Bitbucket 和自托管服务器

228* **本地路径**：目录或 `marketplace.json` 文件的直接路径228* **本地路径**：目录或 `marketplace.json` 文件的直接路径

229* **远程 URL**：托管 `marketplace.json` 文件的直接 URL229* **远程 URL**：托管 `marketplace.json` 文件的直接 URL

230 230

246 246

247通过提供完整 URL 添加任何 git 存储库。这适用于任何 Git 主机，包括 GitLab、Bitbucket 和自托管服务器。包括 `.git` 后缀，以便 Claude Code 克隆存储库，而不是将 URL 视为托管 `marketplace.json` 文件的直接链接。247通过提供完整 URL 添加任何 git 存储库。这适用于任何 Git 主机，包括 GitLab、Bitbucket 和自托管服务器。包括 `.git` 后缀，以便 Claude Code 克隆存储库，而不是将 URL 视为托管 `marketplace.json` 文件的直接链接。

248 248

249同时包括 `https://` 前缀。Claude Code v2.1.196 及更高版本会拒绝没有前缀的主机，例如 `gitlab.com/company/plugins.git`，将其视为无效的 GitHub `owner/repo` 简写，错误消息会告诉您添加前缀。早期版本会将其误读为 GitHub 存储库路径，并在克隆时失败。

250

249使用 HTTPS：251使用 HTTPS：

250 252

251```shell theme={null}253```shell theme={null}

298 安装插件300 安装插件

299</h2>301</h2>

300 302

301添加市场后，您可以直接安装插件（默认安装到用户范围）：303添加市场后，您可以直接安装插件：

302 304

303```shell theme={null}305```shell theme={null}

304/plugin install plugin-name@marketplace-name306/plugin install plugin-name@marketplace-name

305```307```

306 308

307要选择不同的[安装范围](/zh-CN/settings#configuration-scopes)，请使用交互式 UI：运行 `/plugin`，转到**发现**选项卡，然后在插件上按 **Enter**。您将看到以下选项：309该命令打开该插件的详情，您可以在其中选择[安装范围](/zh-CN/settings#configuration-scopes)。当您运行 `/plugin`，转到**发现**选项卡，然后在插件上按 **Enter** 时，您会看到相同的选择：

308 310

309* **用户范围**（默认）：在所有项目中为自己安装311* **用户范围**（默认）：在所有项目中为自己安装

310* **项目范围**：为此存储库上的所有协作者安装（添加到 `.claude/settings.json`）312* **项目范围**：为此存储库上的所有协作者安装，这会将插件添加到 `.claude/settings.json`

311* **本地范围**：仅在此存储库中为自己安装（不与协作者共享）313* **本地范围**：仅在此存储库中为自己安装，不与协作者共享

314

315要在没有交互式步骤的情况下安装，请使用 [`claude plugin install`](/zh-CN/plugins-reference#plugin-install) shell 命令，该命令默认安装到用户范围，除非您传递 `--scope`。

312 316

313您也可能看到具有**托管**范围的插件——这些由管理员通过[托管设置](/zh-CN/settings#settings-files)安装，无法修改。317您也可能看到具有**托管**范围的插件。这些由管理员通过[托管设置](/zh-CN/settings#settings-files)安装，无法修改。

314 318

315<Warning>319<Warning>

316 在安装插件之前，请确保您信任该插件。Anthropic 不控制插件中包含的 MCP servers、文件或其他软件，也无法验证它们是否按预期工作。检查每个插件的主页以获取更多信息。320 在安装插件之前，请确保您信任该插件。Anthropic 不控制插件中包含的 MCP servers、文件或其他软件，也无法验证它们是否按预期工作。检查每个插件的主页以获取更多信息。

358/plugin enable plugin-name@marketplace-name362/plugin enable plugin-name@marketplace-name

359```363```

360 364

365在这些标识符中，`plugin-name` 是 [marketplace entry](/zh-CN/plugin-marketplaces#plugin-entries) 中插件的 `name`，它可能与插件自己的 `plugin.json` 中的 `name` 不同。

366

367从 Claude Code v2.1.195 开始，`/plugin` 界面中的**启用**和**禁用**适用于两个名称不同的插件，`/plugin enable` 和 `/plugin disable` 接受任一名称。当您在早期版本中禁用此类插件时，Claude Code 报告 `already disabled` 并将其保持启用状态。

368

361完全删除插件：369完全删除插件：

362 370

363```shell theme={null}371```shell theme={null}

464 472

465团队管理员可以通过将市场配置添加到 `.claude/settings.json` 来为项目设置自动市场安装。当团队成员信任存储库文件夹时，Claude Code 会提示他们安装这些市场和插件。473团队管理员可以通过将市场配置添加到 `.claude/settings.json` 来为项目设置自动市场安装。当团队成员信任存储库文件夹时，Claude Code 会提示他们安装这些市场和插件。

466 474

475从 Claude Code v2.1.195 开始，此安装步骤适用于加载插件的每个路径。仅由项目的 `.claude/settings.json` 启用且来自外部源（如 GitHub 存储库或 npm 包）的插件在团队成员安装之前不会加载。在此之前，Claude Code 会将该插件报告为未安装，并显示要运行的 `claude plugin install` 命令。

476

467将 `extraKnownMarketplaces` 添加到您项目的 `.claude/settings.json`：477将 `extraKnownMarketplaces` 添加到您项目的 `.claude/settings.json`：

468 478

469```json theme={null}479```json theme={null}

499 509

5001. **检查您的版本**：运行 `claude --version` 以查看安装的内容。5101. **检查您的版本**：运行 `claude --version` 以查看安装的内容。

5012. **更新 Claude Code**：5112. **更新 Claude Code**：

502 * **Homebrew**：`brew upgrade claude-code`（或如果您安装了该 cask，则为 `brew upgrade claude-code@latest`）512 * **Homebrew**：`brew upgrade claude-code`，或如果您安装了该 cask，则为 `brew upgrade claude-code@latest`

503 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`513 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`

504 * **本地安装程序**：从[设置](/zh-CN/setup)重新运行安装命令514 * **本地安装程序**：从[设置](/zh-CN/setup)重新运行安装命令

5053. **重启 Claude Code**：更新后，重启您的终端并再次运行 `claude`。5153. **重启 Claude Code**：更新后，重启您的终端并再次运行 `claude`。

509</h3>519</h3>

510 520

511* **市场未加载**：验证 URL 是否可访问以及 `.claude-plugin/marketplace.json` 是否存在于该路径521* **市场未加载**：验证 URL 是否可访问以及 `.claude-plugin/marketplace.json` 是否存在于该路径

512* **插件安装失败**：检查插件源 URL 是否可访问以及存储库是否公开（或您有访问权限）522* **插件安装失败**：检查插件源 URL 是否可访问以及存储库是否公开，或您是否有访问权限

513* **安装后找不到文件**：插件被复制到缓存，因此引用插件目录外文件的路径将不起作用523* **安装后找不到文件**：插件被复制到缓存，因此引用插件目录外文件的路径将不起作用

514* **插件 skills 未出现**：使用 `rm -rf ~/.claude/plugins/cache` 清除缓存，重启 Claude Code，然后重新安装插件。524* **插件 skills 未出现**：使用 `rm -rf ~/.claude/plugins/cache` 清除缓存，重启 Claude Code，然后重新安装插件。

515 525

env-vars.md +24 −18

Details

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

103| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |103| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |

104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 所需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 所需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |

105| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)默认禁用。如果您的代理转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true` |105| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)默认禁用。如果您的代理转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/zh-CN/remote-control#requirements) 被禁用，与其在 Bedrock、Vertex AI 和 Foundry 上的行为相匹配 |

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

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

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

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |

150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 后台 subagents 的停滞超时（以毫秒为单位）。默认 `600000`（10 分钟）。计时器在每个流式进度事件时重置；如果在窗口内没有进度到达，subagent 会被中止，任务被标记为失败，将任何部分结果呈现给父级 |150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 后台 subagents 的停滞超时（以毫秒为单位）。默认 `600000`（10 分钟）。计时器在每个流式进度事件时重置；如果在窗口内没有进度到达，subagent 会被中止，任务被标记为失败，将任何部分结果呈现给父级 |

151| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩的上下文容量百分比（1-100）。使用较低的值（如 `50`）可更早进行压缩。此变量仅在 Claude Code 主动压缩时导致更早压缩：当设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 时、在[云会话](/zh-CN/claude-code-on-the-web)中、在没有[扩展上下文](/zh-CN/model-config#extended-context)的 Sonnet 4.6 和 Opus 4.6 上，默认在 200K 边界处压缩。在其他情况下，例如本地会话，当对话达到模型的上下文限制时自动压缩触发。覆盖只能降低阈值，因此高于默认值的值无效。适用于主对话和 subagents |151| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩的上下文容量百分比（1-100）。使用较低的值（如 `50`）可更早进行压缩。此变量仅在 Claude Code 主动压缩时导致更早压缩：当设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 时、在[云会话](/zh-CN/claude-code-on-the-web)中、在没有[扩展上下文](/zh-CN/model-config#extended-context)的 Sonnet 4.6 和 Opus 4.6 上，默认在 200K 边界处压缩。在 Sonnet 5 上，主动压缩在模型的[默认阈值](/zh-CN/model-config#sonnet-5-context-window)处应用。在其他情况下，例如本地会话上的 Opus 4.8，当对话达到模型的上下文限制时自动压缩触发。覆盖只能降低阈值，因此高于默认值的值无效。适用于主对话和 subagents |

153| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 以呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。设置为 `0` 以强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/zh-CN/settings#available-settings) 为 `true`。[`--ax-screen-reader`](/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |153| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 以呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。设置为 `0` 以强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/zh-CN/settings#available-settings) 为 `true`。[`--ax-screen-reader`](/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口：标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口，标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M，除了 Sonnet 5，它有自己的[默认阈值](/zh-CN/model-config#sonnet-5-context-window)。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时。优先于 [`autoConnectIde`](/zh-CN/settings#global-config-settings) 全局配置设置 |164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时。优先于 [`autoConnectIde`](/zh-CN/settings#global-config-settings) 全局配置设置 |

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

166| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/zh-CN/hooks) 命令和[状态行](/zh-CN/statusline)命令生成的子进程中设置为 `1`。不为 stdio [MCP server](/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 或更高版本 |166| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/zh-CN/hooks) 命令和[状态行](/zh-CN/statusline)命令生成的子进程中设置为 `1`。不为 stdio [MCP server](/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 或更高版本 |

170| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时 |170| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时 |

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

172| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |172| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |

173| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用[1M 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用。对于具有合规要求的企业环境很有用 |173| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用[1M 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用，[Sonnet 5](/zh-CN/model-config#sonnet-5-context-window) 会话被视为具有 200K 窗口。对于具有合规要求的企业环境很有用 |

174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。从 v2.1.111 开始，对 Fable 5 无效，或对 Opus 4.7 及更高版本无效，它们始终使用自适应推理 |174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。从 v2.1.111 开始，对 Fable 5、Sonnet 5 或 Opus 4.7 及更高版本无效，它们始终使用自适应推理 |

175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用[顾问工具](/zh-CN/advisor)。`/advisor` 命令和 `--advisor` 标志变为不可用，任何配置的 `advisorModel` 被忽略。需要 Claude Code v2.1.98 或更高版本 |175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用[顾问工具](/zh-CN/advisor)。`/advisor` 命令和 `--advisor` 标志变为不可用，任何配置的 `advisorModel` 被忽略。需要 Claude Code v2.1.98 或更高版本 |

176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭[后台代理和代理视图](/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需监督员。等同于 [`disableAgentView`](/zh-CN/settings#available-settings) 设置 |176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭[后台代理和代理视图](/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需监督员。等同于 [`disableAgentView`](/zh-CN/settings#available-settings) 设置 |

177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)并使用经典主屏幕渲染器。对话保持在您的终端的原生滚动条中，因此 `Cmd+f` 和 tmux 复制模式可以正常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-CN/settings#available-settings) 设置。您也可以使用 `/tui default` 切换。不适用于从[代理视图](/zh-CN/agent-view)打开的后台会话，它们始终使用全屏渲染 |177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)并使用经典主屏幕渲染器。对话保持在您的终端的原生滚动条中，因此 `Cmd+f` 和 tmux 复制模式可以正常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-CN/settings#available-settings) 设置。您也可以使用 `/tui default` 切换。不适用于从[代理视图](/zh-CN/agent-view)打开的后台会话，它们始终使用全屏渲染 |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-CN/settings#available-settings) 会禁用它时强制启用自动内存。禁用后，Claude 不会创建或加载自动内存文件 |180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-CN/settings#available-settings) 会禁用它时强制启用自动内存。禁用后，Claude 不会创建或加载自动内存文件 |

181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和 subagent 工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和 subagent 工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |

182| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 以在[监督员](/zh-CN/agent-view#the-supervisor-process)停止、重启或更新该会话的进程时停止[后台会话](/zh-CN/agent-view)的运行后台 shell 命令和动态工作流，而不是将它们交给会话的下一个进程。仅影响该交接：使用 `←` 或 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话仍会进行中的工作，`CLAUDE_DISABLE_ADOPT` 关闭两者。需要 Claude Code v2.1.196 或更高版本 |

183| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 以停止 Claude Code 在操作系统报告内存压力时终止[后台 shell 命令](/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，Claude Code 在会话空闲 30 分钟且没有转换或 subagent 运行后，在内存压力信号上终止在主会话中启动的后台 shell。Windows 没有内存压力信号，因此此变量对其无效。需要 Claude Code v2.1.193 或更高版本 |

182| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |184| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |

184| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |186| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |

185| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留。 |187| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留 |

187| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新启用。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |189| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新启用。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |

189| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |191| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |

190| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Bedrock、Vertex 或 Foundry 上运行 |192| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Bedrock、Vertex 或 Foundry 上运行 |

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

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

192| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 等同于设置 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |195| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 等同于设置 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |

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

196| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 以禁用基于对话上下文的自动终端标题更新。在 Agent SDK 和 `claude -p` 会话中，这也会跳过生成会话标题的后台 Haiku 请求 |200| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 以禁用基于对话上下文的自动终端标题更新。在 Agent SDK 和 `claude -p` 会话中，这也会跳过生成会话标题的后台 Haiku 请求 |

198| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的虚拟滚动并渲染转录中的每条消息。如果全屏模式中的滚动显示应该出现消息的空白区域，请使用此选项 |202| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的虚拟滚动并渲染转录中的每条消息。如果全屏模式中的滚动显示应该出现消息的空白区域，请使用此选项 |

199| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用[工作流](/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/zh-CN/settings#available-settings) 设置 |203| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用[工作流](/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/zh-CN/settings#available-settings) 设置 |

200| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |204| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |

201| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 设置为 `1` 以在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上提供[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更高版本。对 Anthropic API 无效，自动模式在那里默认可用。请参阅[在 Bedrock、Vertex AI 或 Foundry 上启用自动模式](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) |205| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 设置为 `1` 以在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 [Claude apps 网关](/zh-CN/claude-apps-gateway)会话上提供[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更高版本。对 Anthropic API 无效，自动模式在那里默认可用。请参阅[在 Bedrock、Vertex AI 或 Foundry 上启用自动模式](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) |

202| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |206| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |

203| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](/zh-CN/prompt-caching) 失效 |207| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](/zh-CN/prompt-caching) 失效 |

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

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

206| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |210| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤，会话接收；通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files)传递列表，因为[服务器管理的交付在网关配置上不可用](/zh-CN/server-managed-settings#platform-availability) |

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

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

215| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 以强制转录持久化、提示历史和 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 Claude Code 的 Bash 工具首次启动的 tmux 服务器）导致真正的顶级会话被误分类为嵌套时使用。从 v2.1.178 开始，Claude Code 自动检测 tmux 情况并忽略继承的标记，因此 tmux 不再需要此变量。也在 v2.1.169 及更早版本上受尊重；对 v2.1.170 和 v2.1.171 无效，其中它覆盖的嵌套会话检测被移除 |219| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 以强制转录持久化、提示历史和 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 Claude Code 的 Bash 工具首次启动的 `screen` 会话）导致真正的顶级会话被误分类为嵌套时使用。从 v2.1.178 开始，Claude Code 自动检测 tmux 情况并忽略继承的标记，因此 tmux 不再需要此变量。也在 v2.1.169 及更早版本上受尊重；对 v2.1.170 和 v2.1.171 无效，其中它覆盖的嵌套会话检测被移除 |

216| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 以在您的终端支持但未自动检测到时强制对 `~~text~~` 进行删除线渲染，例如通过 SSH 而不转发 `TERM_PROGRAM`。没有这个，未检测到的终端显示文字 `~~` 标记而不是将文本呈现为删除线。需要 Claude Code v2.1.186 或更高版本 |220| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 以在您的终端支持但未自动检测到时强制对 `~~text~~` 进行删除线渲染，例如通过 SSH 而不转发 `TERM_PROGRAM`。没有这个，未检测到的终端显示文字 `~~` 标记而不是将文本呈现为删除线。需要 Claude Code v2.1.186 或更高版本 |

217| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 以在您的终端支持但未自动检测到时强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。对于实现 BSU/ESU 但不回复能力探针的模拟器（如 Emacs `eat`）很有用。在 tmux 下无效 |221| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 以在您的终端支持但未自动检测到时强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。对于实现 BSU/ESU 但不回复能力探针的模拟器（如 Emacs `eat`）很有用。在 tmux 下无效 |

218| `CLAUDE_CODE_FORK_SUBAGENT` | 设置为 `1` 以让 Claude 生成[分叉 subagents](/zh-CN/sub-agents#fork-the-current-conversation)，或 `0` 以禁用它们，覆盖任何服务器端推出。启用后，Claude 可以请求 `fork` subagent 类型以生成分叉，一个继承完整对话上下文而不是从头开始的 subagent。没有 subagent 类型的生成仍使用通用 subagent，所有 subagent 生成在后台运行。显式 [`/fork`](/zh-CN/commands) 命令无需此变量即可工作。在交互模式和通过 SDK 或 `claude -p` 中工作 |222| `CLAUDE_CODE_FORK_SUBAGENT` | 设置为 `1` 以让 Claude 生成[分叉 subagents](/zh-CN/sub-agents#fork-the-current-conversation)，或 `0` 以禁用它们，覆盖任何服务器端推出。启用后，Claude 可以请求 `fork` subagent 类型以生成分叉，一个继承完整对话上下文而不是从头开始的 subagent。没有 subagent 类型的生成仍使用通用 subagent，所有 subagent 生成在后台运行。显式 [`/fork`](/zh-CN/commands) 命令无需此变量即可工作。在交互模式和通过 SDK 或 `claude -p` 中工作 |

225| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/zh-CN/settings#global-config-settings) 设置为 `false` |229| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/zh-CN/settings#global-config-settings) 设置为 `false` |

227| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活动模型假设的上下文窗口大小。仅在同时设置 `DISABLE_COMPACT` 时生效。当通过 `ANTHROPIC_BASE_URL` 路由到上下文窗口与其名称的内置大小不匹配的模型时使用 |231| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活动模型假设的上下文窗口大小。从 v2.1.193 开始，对于 Claude Code 不识别为 Claude 模型的模型名称直接应用；对于识别的 Claude 模型，仅当同时设置 `DISABLE_COMPACT` 时才生效。当通过 `ANTHROPIC_BASE_URL` 路由到上下文窗口与其名称的内置大小不匹配的模型时使用 |

228| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口。 |232| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口 |

229| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10）。从 v2.1.186 开始，上限为 15。对于需要等待更长中断的无人值守会话，请改用 `CLAUDE_CODE_RETRY_WATCHDOG` |233| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10）。从 v2.1.186 开始，上限为 15。对于需要等待更长中断的无人值守会话，请改用 `CLAUDE_CODE_RETRY_WATCHDOG` |

231| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |235| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |

233| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | 远程 MCP 工具调用的空闲超时（以毫秒为单位）（默认值：300000，或 5 分钟）。当 HTTP、SSE、WebSocket 或 [claude.ai 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内没有发送响应和没有进度通知时，工具调用会中止并显示错误，而不是等待墙钟 `MCP_TOOL_TIMEOUT`。设置为 `0` 以禁用空闲检查。低于 1000 的值被提高到一秒，该值上限为有效的 `MCP_TOOL_TIMEOUT`。不适用于 stdio 或 IDE 服务器。需要 Claude Code v2.1.187 或更高版本 |237| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | 远程 MCP 工具调用的空闲超时（以毫秒为单位）（默认值：300000，或 5 分钟）。当 HTTP、SSE、WebSocket 或 [claude.ai 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内没有发送响应和没有进度通知时，工具调用会中止并显示错误，而不是等待墙钟 `MCP_TOOL_TIMEOUT`。设置为 `0` 以禁用空闲检查。低于 1000 的值被提高到一秒，该值上限为有效的 `MCP_TOOL_TIMEOUT`。不适用于 stdio 或 IDE 服务器。需要 Claude Code v2.1.187 或更高版本 |

235| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |239| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示 |

236| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |240| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |

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

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

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

240| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，现在是无操作。以前将[快速模式](/zh-CN/fast-mode)固定到 Claude Opus 4.6 而不是当前默认值 |244| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，现在是无操作。以前将[快速模式](/zh-CN/fast-mode)固定到 Claude Opus 4.6 而不是当前默认值。Opus 4.6 不再支持快速模式 |

241| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 以将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下，这些错误仅在 `--debug` 时出现，因此配置错误的导出器（如 Prometheus 端口冲突）会以其他方式无声失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](/zh-CN/monitoring-usage) |245| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 以将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下，这些错误仅在 `--debug` 时出现，因此配置错误的导出器（如 Prometheus 端口冲突）会以其他方式无声失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](/zh-CN/monitoring-usage) |

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

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

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

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

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

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

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

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

281| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（以毫秒为单位）。超过时，Claude Code 继续而不使用插件并记录错误。无默认值：没有此变量，同步安装会等待直到完成 |285| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（以毫秒为单位）。超过时，Claude Code 继续而不使用插件并记录错误。无默认值：没有此变量，同步安装会等待直到完成 |

295| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，该工具正在逐步推出：设置为 `1` 以选择加入或 `0` 以选择退出。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上有 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。请参阅 [PowerShell 工具](/zh-CN/tools-reference#powershell-tool) |299| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，该工具正在逐步推出：设置为 `1` 以选择加入或 `0` 以选择退出。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上有 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。请参阅 [PowerShell 工具](/zh-CN/tools-reference#powershell-tool) |

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

302| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在您通过按 `←` 或使用 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止会以其他方式进行的任务。需要 Claude Code v2.1.195 或更高版本 |

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

299| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接默认启用。字节监视程序在 180 秒（直接 Anthropic API 连接）、300 秒（Claude Platform on AWS 和其他提供商）或 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的值（限制为最少 5 分钟）内没有字节到达线路时中止连接，独立于事件级监视程序 |304| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接默认启用。字节监视程序在 180 秒（直接 Anthropic API 连接）、300 秒（Claude Platform on AWS 和其他提供商）或 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的值（限制为最少 5 分钟）内没有字节到达线路时中止连接，独立于事件级监视程序 |

300| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |305| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

301| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `1` 以强制启用事件级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。从 v2.1.169 开始，直接 Anthropic API 和 Claude Platform on AWS 以外的提供商也有默认启用的 5 分钟体空闲超时，独立于此变量；请参阅 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 启用独立的字节级监视程序；当两者都设置时，它们一起运行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |306| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视程序，或设置为 `1` 以强制启用它。未设置时，监视程序对所有提供商默认启用。在 v2.1.196 之前，未设置的默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。从 v2.1.169 开始，直接 Anthropic API 和 Claude Platform on AWS 以外的提供商也有默认启用的 5 分钟体空闲超时，独立于此变量；请参阅 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 启用独立的字节级监视程序；当两者都设置时，它们一起运行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

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

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

304| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。当您明确设置此变量时，最小值为 `300000`（5 分钟）；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。未设置时，事件级监视程序默认为 300 秒，字节级监视程序在直接 Anthropic API 连接上默认为 180 秒（Claude Platform on AWS 和其他提供商上为 300 秒）。未设置的 180 秒字节监视程序默认值是一个单独的值，不受 5 分钟限制。对于第三方提供商上的事件级监视程序，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`；`API_FORCE_IDLE_TIMEOUT` 下描述的体空闲超时独立应用。在 Bedrock 上，也在 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 时应用 |309| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。当您明确设置此变量时，最小值为 `300000`（5 分钟）；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。未设置时，事件级监视程序默认为 300 秒，字节级监视程序在直接 Anthropic API 连接上默认为 180 秒（Claude Platform on AWS 和其他提供商上为 300 秒）。未设置的 180 秒字节监视程序默认值是一个单独的值，不受 5 分钟限制。体空闲超时在 `API_FORCE_IDLE_TIMEOUT` 下描述，独立应用。在 Bedrock 上，也在 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 时应用 |

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

349| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时（以毫秒为单位）（默认值：100000000，约 28 小时）。`.mcp.json` 中的每个服务器 `timeout` 字段会覆盖该服务器的此值。对于 env 变量，低于 1000 的值被限制为一秒；对于每个服务器字段，低于 1000 的值被忽略 |354| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时（以毫秒为单位）（默认值：100000000，约 28 小时）。`.mcp.json` 中的每个服务器 `timeout` 字段会覆盖该服务器的此值。对于 env 变量，低于 1000 的值被限制为一秒；对于每个服务器字段，低于 1000 的值被忽略 |

356| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件中包含模型的响应文本。未设置时，使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 以在设置 `OTEL_LOG_USER_PROMPTS` 时保持响应编辑。需要 Claude Code v2.1.193 或更高版本。请参阅[监控](/zh-CN/monitoring-usage#assistant-response-event) |

351| `OTEL_LOG_RAW_API_BODIES` | 设置为 `1` 以将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出，截断为 60 KB，或 `file:<dir>` 以将未截断的主体写入磁盘并发出 `body_ref` 路径。默认禁用；主体包括整个对话历史。请参阅[监控](/zh-CN/monitoring-usage#api-request-body-event) |357| `OTEL_LOG_RAW_API_BODIES` | 设置为 `1` 以将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出，截断为 60 KB，或 `file:<dir>` 以将未截断的主体写入磁盘并发出 `body_ref` 路径。默认禁用；主体包括整个对话历史。请参阅[监控](/zh-CN/monitoring-usage#api-request-body-event) |

353| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、工具失败时的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。请参阅[监控](/zh-CN/monitoring-usage) |359| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、工具失败时的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。请参阅[监控](/zh-CN/monitoring-usage) |

errors.md +22 −4

Details

40| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |40| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |

41| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |41| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |

42| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organization%E2%80%99s-policy) |42| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organization%E2%80%99s-policy) |

43| `Remote Control is only available when using Claude via api.anthropic.com` | [身份验证](#remote-control-requires-the-anthropic-api) |

43| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |44| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |

44| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |45| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |

45| `Unable to connect to API` | [网络](#unable-to-connect-to-api) |46| `Unable to connect to API` | [网络](#unable-to-connect-to-api) |

426* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用**例程**切换427* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用**例程**切换

427* 对于不需要组织级别例程的一次性计划工作，请参阅[计划任务](/zh-CN/scheduled-tasks)428* 对于不需要组织级别例程的一次性计划工作，请参阅[计划任务](/zh-CN/scheduled-tasks)

428 429

430<h3 id="remote-control-requires-the-anthropic-api">

431 Remote Control requires the Anthropic API

432</h3>

433

434该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/zh-CN/remote-control) 配对。

435

436```text theme={null}

437Remote Control is only available when using Claude via api.anthropic.com.

438```

439

440这出现在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，它也会出现，例如 [LLM gateway](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录。

441

442**要做什么：**

443

444* 取消设置 `ANTHROPIC_BASE_URL` 并重新启动会话，或从直接与 Anthropic API 通信的会话启动 Remote Control

445* 对于此错误和其他 Remote Control 启动消息，请参阅[故障排除 Remote Control](/zh-CN/remote-control#troubleshooting)

446

429<h3 id="oauth-token-revoked-or-expired">447<h3 id="oauth-token-revoked-or-expired">

430 OAuth token revoked or expired448 OAuth token revoked or expired

431</h3>449</h3>

727 thinking.type.enabled is not supported for this model745 thinking.type.enabled is not supported for this model

728</h3>746</h3>

729 747

730您的 Claude Code 版本早于 Opus 4.7 或 Opus 4.8 的最低版本。CLI 发送了模型不再接受的思考配置。748您的 Claude Code 版本早于 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本。CLI 发送了模型不再接受的思考配置。

731 749

732```text theme={null}750```text theme={null}

733API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.751API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

735 753

736**要做什么：**754**要做什么：**

737 755

738* 运行 `claude update` 并重新启动 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本756* 运行 `claude update` 并重新启动 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本

739* 如果您无法升级，请运行 `/model` 并选择 Opus 4.6 或 Sonnet757* 如果您无法升级，请运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.6 代替

740* 如果您在 Agent SDK 中遇到这个，请参阅 [SDK 故障排除](/zh-CN/agent-sdk/quickstart#troubleshooting)758* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-CN/agent-sdk/overview) 中遇到这个，请升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本

741 759

742<h3 id="thinking-budget-exceeds-output-limit">760<h3 id="thinking-budget-exceeds-output-limit">

743 Thinking budget exceeds output limit761 Thinking budget exceeds output limit

fullscreen.md +7 −1

Details

123 搜索和查看对话123 搜索和查看对话

124</h2>124</h2>

125 125

126`Ctrl+o` 在正常提示和记录模式之间切换。对于一个更安静的视图，只显示您的最后一个提示、工具调用的单行摘要和编辑 diffstats，以及最终响应，请运行 `/focus`。该设置在会话之间保持。再次运行 `/focus` 来关闭它。126`Ctrl+o` 在正常提示和记录模式之间切换。

127

128对于一个更安静的视图，只显示您的最后一个提示、工具调用的单行摘要和编辑 diffstats，以及最终响应，请运行 `/focus`。该设置在会话之间保持。再次运行 `/focus` 来关闭它。

127 129

128记录模式获得 `less` 风格的导航和搜索：130记录模式获得 `less` 风格的导航和搜索：

129 131

203 205

204禁用鼠标捕获后，使用 `PgUp`、`PgDn`、`Ctrl+Home` 和 `Ctrl+End` 的键盘滚动仍然有效，您的终端原生处理选择。您会失去点击定位光标、点击展开工具输出、URL 点击和 Claude Code 内的滚轮滚动。206禁用鼠标捕获后，使用 `PgUp`、`PgDn`、`Ctrl+Home` 和 `Ctrl+End` 的键盘滚动仍然有效，您的终端原生处理选择。您会失去点击定位光标、点击展开工具输出、URL 点击和 Claude Code 内的滚轮滚动。

205 207

208要保持滚轮滚动但关闭点击、拖动和悬停处理，请改为设置 `CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1`。需要 Claude Code v2.1.195 或更高版本。当两个变量都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。

209

210禁用点击后，Claude Code 仍然捕获鼠标，因此滚轮和触控板滚动对话，但左键点击在 Claude Code 内不起作用。您仍然需要按住终端的键进行原生点击拖动选择。右键点击和中键粘贴在支持它们的终端上继续工作。

211

206<h2 id="research-preview">212<h2 id="research-preview">

207 研究预览213 研究预览

208</h2>214</h2>

gateways.md +87 −0 created

Details

1> ## Documentation Index

2> 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.

5# 通过网关运行 Claude Code

7> 通过自托管网关路由 Claude Code，实现集中式凭证管理、使用情况跟踪和成本控制。涵盖架构、Anthropic 的 Claude 应用网关以及使用其他网关产品。

9网关是您的组织在 Claude Code 和模型提供商之间运行的代理。Claude Code 将 API 流量发送到网关，而不是直接发送到提供商，网关使用您的组织持有的凭证转发流量。开发人员向网关进行身份验证，而不是持有提供商凭证，因此身份验证、使用情况跟踪、预算和审计日志都在您控制的一个地方进行。

11Claude Code 包含一个自托管网关，[Claude 应用网关](/zh-CN/claude-apps-gateway)，在 `claude` 二进制文件中，因此您不必采用单独的网关产品来运行一个。如果您的组织已经运行了 [LLM 网关](/zh-CN/llm-gateway)，Claude Code 也可以与之配合使用。

13本页涵盖：

15* [网关如何位于 Claude Code 和您的提供商之间](#how-a-gateway-works)

16* [在 Claude 应用网关和您已运行的网关之间进行选择](#choose-a-gateway)

17* [网关如何与 claude.ai 订阅交互](#subscriptions-and-gateways)

18* [与网关分开配置的内容](#configure-separately-from-the-gateway)

20<h2 id="how-a-gateway-works">

21 How a gateway works

22</h2>

24每个开发人员的 Claude Code 都指向网关的地址，并使用网关颁发的凭证进行身份验证。

26网关对开发人员进行身份验证，应用您配置的任何访问和预算规则，并使用组织的凭证将请求转发给您的提供商。提供商可以是 Anthropic 的 API 或 [云提供商](/zh-CN/third-party-integrations)，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry；网关的配置决定了这一点。使用 Claude 应用网关或另一个公开单个 Anthropic 格式端点的网关，更改提供商不需要触及开发人员的机器。

28<Frame>

29 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/llm-gateway-flow.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=1c1a8dcc0cfcc3a58652cc8e28cd3e20" alt="显示 Claude Code 通过网关路由的图表。在开发人员机器区域中，Claude Code CLI 和 VS Code 扩展使用每个开发人员的凭证向网关地址发送请求。在标记为您的基础设施的区域中，网关处理身份验证、使用情况跟踪、预算和路由，并使用您的组织凭证转发请求。在模型提供商区域中，实线箭头指向您配置的提供商（显示为 Anthropic API），虚线箭头指向其他提供商选项，以 Amazon Bedrock、Google Cloud 和 Microsoft Foundry 为例。" width="780" height="322" data-path="images/llm-gateway-flow.svg" />

30</Frame>

32涉及两种凭证：

34* **开发人员凭证**：每个开发人员持有自己的凭证，由网关颁发。它向网关验证他们的身份，并在使用情况跟踪中识别他们

35* **提供商凭证**：网关为您的提供商账户持有一个凭证，由所有转发的流量共享

37<h2 id="choose-a-gateway">

38 Choose a gateway

39</h2>

41Claude Code 可与 Anthropic 自己的网关或您的组织已运行的网关配合使用。

43<h3 id="claude-apps-gateway">

44 Claude apps gateway

45</h3>

47Claude 应用网关是 Anthropic 的自托管网关，包含在 `claude` 二进制文件中。它路由到 Amazon Bedrock、Google Cloud、Microsoft Foundry 或 Anthropic API 作为上游。开发人员通过 `/login` 使用您的企业身份提供商登录，网关按 IdP 组强制执行模型访问和 [托管设置](/zh-CN/permissions#managed-settings)，并向您自己的可观测性堆栈发出 [OpenTelemetry Protocol (OTLP)](/zh-CN/monitoring-usage) 使用指标。

49因为它与每个 Claude Code 版本一起构建和测试，所以它转发 Claude Code 发送的标头和请求字段。单独维护的网关需要在每个版本中更改这些标头和字段时 [更新其转发规则](/zh-CN/llm-gateway-protocol#forward-as-open-lists)；Claude 应用网关与 CLI 一起发布，因此没有列表需要保持最新。有关在网关会话上行为不同的小功能集，请参阅 [可用性和限制](/zh-CN/claude-apps-gateway#availability-and-limitations)。

51网关登录是浏览器 SSO 步骤，没有服务令牌流，因此没有开发人员批准登录的 CI 管道无法通过它进行身份验证；直接针对您的提供商配置这些。Agent SDK 会话和在开发人员已登录的机器上运行的 `claude -p` 使用该机器的网关会话，并受其策略管制。请参阅 [CI 管道和远程机器](/zh-CN/claude-apps-gateway#ci-pipelines-and-remote-machines)。

53请参阅 [Claude 应用网关](/zh-CN/claude-apps-gateway) 来部署它。

55<h3 id="other-gateways">

56 Other gateways

57</h3>

59如果您的组织已经运行了 LLM 网关或 API 网关，您可以改用它。Anthropic 不认可、维护或审计其他网关产品，也不支持通过任何网关将 Claude Code 路由到非 Claude 模型。有关管理员推出清单、网关必须实现的内容以及如何将 Claude Code 指向它，请参阅 [其他 LLM 网关](/zh-CN/llm-gateway)。

61<h2 id="subscriptions-and-gateways">

62 Subscriptions and gateways

63</h2>

65当开发人员通过具有网关凭证的网关连接时，使用情况按 API 费率计费到您的组织的提供商账户，他们的 claude.ai 订阅不被使用或收费。为您运行的网关设置 [`ANTHROPIC_AUTH_TOKEN`](/zh-CN/env-vars)，或使用 `/login` 登录到 Claude 应用网关，会关闭该会话的订阅登录。在该凭证下转发的每个请求都计费到网关提供商凭证后面的账户。

67例外是仅设置 `ANTHROPIC_BASE_URL`，没有网关凭证。请求仍然通过网关路由，但保存的 claude.ai 登录保持活跃凭证，因此订阅的使用限制和计费适用。[其他 LLM 网关](/zh-CN/llm-gateway#subscriptions-and-gateways) 涵盖该配置以及网关必须转发的内容才能使其工作。

69<h2 id="configure-separately-from-the-gateway">

70 Configure separately from the gateway

71</h2>

73网关路由模型 API 请求。您可能期望它处理的一些事情在其他地方配置：

75* **哪个模型回答**：使用 `/model` 命令或 [模型环境变量](/zh-CN/model-config#setting-your-model) 选择模型。网关决定请求去向，而不是开发人员选择的模型。Claude 应用网关可以使用每个组的 `availableModels` 允许列表限制选择，但开发人员仍在其中选择。

76* **其他网络流量**：Claude Code 本身将版本检查和下载直接发送到 Anthropic，与网关路径分开。可选的客户端遥测流是否也在取决于您的提供商；[遥测默认值表](/zh-CN/data-usage#telemetry-services) 涵盖每种情况。在已登录的 Claude 应用网关会话上，网关凭证禁用 Anthropic 绑定的分析，当 [配置遥测转发](/zh-CN/claude-apps-gateway-config#telemetry) 时，将 OTLP 导出固定到网关。您的网络仍需要出口到 [必需的域](/zh-CN/network-config)，或设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-CN/env-vars) 以关闭可选流。

77* **企业 HTTP 代理**：`HTTPS_PROXY` 位于 Claude Code 和它与之通信的每个服务器之间，包括网关。如果您的网络需要一个，[配置代理](/zh-CN/network-config) 以及网关。对于 Claude 应用网关，[登录检查代理主机也在私有网络上](/zh-CN/claude-apps-gateway#prerequisites)；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接到它。

79<h2 id="next-steps">

80 Next steps

81</h2>

83下一页取决于谁运行网关。Anthropic 的网关从 `claude` 二进制文件运行，有自己的设置指南；您的组织已运行的网关有一个要实现的协议和一个管理员推出清单。

85* [Claude 应用网关](/zh-CN/claude-apps-gateway) 部署 Anthropic 的自托管网关，具有 SSO 登录和 OTLP 遥测

86* [其他 LLM 网关](/zh-CN/llm-gateway) 了解您的组织已运行的网关必须实现的内容，以及如何将 Claude Code 指向它

87* [为您的组织设置 Claude Code](/zh-CN/admin-setup) 了解网关是其中一部分的更广泛的推出决策

github-actions.md +5 −5

Details

127 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}127 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

128 custom_instructions: "Follow our coding standards"128 custom_instructions: "Follow our coding standards"

129 max_turns: "10"129 max_turns: "10"

130 model: "claude-sonnet-4-6"130 model: "claude-sonnet-5"

131```131```

132 132

133**GA 版本 (v1.0)：**133**GA 版本 (v1.0)：**

140 claude_args: |140 claude_args: |

141 --append-system-prompt "Follow our coding standards"141 --append-system-prompt "Follow our coding standards"

142 --max-turns 10142 --max-turns 10

143 --model claude-sonnet-4-6143 --model claude-sonnet-5

144```144```

145 145

146<Tip>146<Tip>

228 228

229在 issue 或 PR 评论中：229在 issue 或 PR 评论中：

230 230

231```text theme={null}231```text wrap theme={null}

232@claude implement this feature based on the issue description232@claude implement this feature based on the issue description

233@claude how should I implement user authentication for this endpoint?233@claude how should I implement user authentication for this endpoint?

234@claude fix the TypeError in the user dashboard component234@claude fix the TypeError in the user dashboard component

709`claude_args` 参数接受任何 Claude Code CLI 参数：709`claude_args` 参数接受任何 Claude Code CLI 参数：

710 710

711```yaml theme={null}711```yaml theme={null}

712claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"712claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"

713```713```

714 714

715常见参数：715常见参数：

716 716

717* `--max-turns`：最大对话轮数（默认：10）717* `--max-turns`：最大对话轮数（默认：10）

718* `--model`：要使用的模型（例如，`claude-sonnet-4-6`）718* `--model`：要使用的模型（例如，`claude-sonnet-5`）

719* `--mcp-config`：MCP 配置的路径719* `--mcp-config`：MCP 配置的路径

720* `--allowedTools`：允许的工具的逗号分隔列表。`--allowed-tools` 别名也可以使用。720* `--allowedTools`：允许的工具的逗号分隔列表。`--allowed-tools` 别名也可以使用。

721* `--debug`：启用调试输出721* `--debug`：启用调试输出

glossary.md +1 −1

Details

170 Effort level170 Effort level

171</h3>171</h3>

172 172

173一个设置，控制 Claude 在每个回合上使用多少自适应推理思考预算。更高的努力意味着更多的思考 tokens 和更深入的推理；更低的努力更快且更便宜。Effort 在 Fable 5、Opus 4.6 及更高版本以及 Sonnet 4.6 上受支持。173一个设置，控制 Claude 在每个回合上使用多少自适应推理思考预算。更高的努力意味着更多的思考 tokens 和更深入的推理；更低的努力更快且更便宜。Effort 在 Fable 5、Opus 4.6 及更高版本以及 Sonnet 4.6 及更高版本上受支持。

174 174

175了解更多：[调整 effort level](/zh-CN/model-config#adjust-effort-level)175了解更多：[调整 effort level](/zh-CN/model-config#adjust-effort-level)

176 176

google-vertex-ai.md +2 −2

Details

236 236

237```bash theme={null}237```bash theme={null}

238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

239export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'239export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'

240export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'240export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

241```241```

242 242

290 1M token context window290 1M token context window

291</h2>291</h2>

292 292

293Claude Opus 4.6 及更高版本以及 Sonnet 4.6 在 Vertex AI 上支持 [1M token context window](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)。当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。293Claude Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 在 Vertex AI 上支持 [1M token context window](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。

294 294

295[设置向导](#sign-in-with-vertex-ai)在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)。295[设置向导](#sign-in-with-vertex-ai)在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)。

296 296

hooks.md +55 −20

Details

191`matcher` 字段过滤 hooks 何时触发。匹配器的评估方式取决于它包含的字符：191`matcher` 字段过滤 hooks 何时触发。匹配器的评估方式取决于它包含的字符：

192 192

193| 匹配器值 | 评估为 | 示例 |193| 匹配器值 | 评估为 | 示例 |

194| :----------------------- | :----------------------------------- | :------------------------------------------------------------------------ |194| :--------------------------- | :----------------------------------- | :----------------------------------------------------------------------------------- |

195| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |195| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |

198 198

199逗号分隔符和周围空格容差需要 Claude Code v2.1.191 或更高版本。`FileChanged` 和 `StopFailure` 事件仅接受 `|` 作为列表分隔符，并将 `,` 视为文字字符；下表中列出的所有其他事件接受 `|` 或 `,`。199在正则表达式路径上的匹配器使用 JavaScript 的 `RegExp.prototype.test` 进行测试，该测试在值中任何位置的匹配时成功。`Edit.*` 匹配 `Edit` 和 `NotebookEdit`；当您需要整个字符串匹配时，用 `^` 和 `$` 包装模式，如 `^Edit$`。

200

201逗号分隔符和周围空格容差需要 Claude Code v2.1.191 或更高版本。

202

203精确匹配集中的连字符需要 Claude Code v2.1.195 或更高版本。在早期版本中，像 `code-reviewer` 这样的连字符名称被评估为未锚定的正则表达式，因此它也会对 `senior-code-reviewer` 触发；在这些版本上将其锚定为 `^code-reviewer$` 以仅匹配该名称。

204

205`FileChanged` 和 `StopFailure` 使用更窄的精确匹配集，仅包含字母、数字、`_` 和 `|`。这两个事件的匹配器中的连字符、空格或逗号将其保留在正则表达式路径上，仅 `|` 分隔替代项。下表中列出的支持匹配器的所有其他事件接受 `|` 或 `,`。

200 206

201`FileChanged` 事件在构建其监视列表时不遵循这些规则。请参阅 [FileChanged](#filechanged)。207`FileChanged` 事件在构建其监视列表时不遵循这些规则。请参阅 [FileChanged](#filechanged)。

202 208

215| `ConfigChange` | 配置源 | `user_settings`、`project_settings`、`local_settings`、`policy_settings`、`skills` |221| `ConfigChange` | 配置源 | `user_settings`、`project_settings`、`local_settings`、`policy_settings`、`skills` |

244}250}

245```251```

246 252

247`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove` 和 `CwdChanged` 不支持匹配器，总是在每次出现时触发。如果您向这些事件添加 `matcher` 字段，它会被静默忽略。253`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` 和 `CwdChanged` 不支持匹配器，总是在每次出现时触发。如果您向这些事件添加 `matcher` 字段，它会被静默忽略。

248 254

249对于工具事件，您可以通过在单个 hook 处理程序上设置[`if` 字段](#common-fields)来更狭隘地过滤。`if` 使用[权限规则语法](/zh-CN/permissions)来匹配工具名称和参数，因此 `"Bash(git *)"` 仅在任何 Bash 输入的子命令与 `git *` 匹配时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。255对于工具事件，您可以通过在单个 hook 处理程序上设置[`if` 字段](#common-fields)来更狭隘地过滤。`if` 使用[权限规则语法](/zh-CN/permissions)来匹配工具名称和参数，因此 `"Bash(git *)"` 仅在任何 Bash 输入的子命令与 `git *` 匹配时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。

250 256

260* `mcp__filesystem__read_file`：Filesystem 服务器的读取文件工具266* `mcp__filesystem__read_file`：Filesystem 服务器的读取文件工具

261* `mcp__github__search_repositories`：GitHub 服务器的搜索工具267* `mcp__github__search_repositories`：GitHub 服务器的搜索工具

262 268

263要匹配来自服务器的每个工具，请在服务器前缀后追加 `.*`。`.*` 是必需的：像 `mcp__memory` 这样的匹配器仅包含字母和下划线，因此它作为精确字符串进行比较，不匹配任何工具。269要匹配来自服务器的每个工具，请在服务器前缀后追加 `.*`。`.*` 是必需的：像 `mcp__memory` 或 `mcp__brave-search` 这样的匹配器仅包含精确匹配字符，因此它作为精确字符串进行比较，不匹配任何工具。

264 270

265* `mcp__memory__.*` 匹配来自 `memory` 服务器的所有工具271* `mcp__memory__.*` 匹配来自 `memory` 服务器的所有工具

272* `mcp__brave-search__.*` 匹配来自名称包含连字符的服务器的所有工具

266* `mcp__.*__write.*` 匹配来自任何服务器的任何名称以 `write` 开头的工具273* `mcp__.*__write.*` 匹配来自任何服务器的任何名称以 `write` 开头的工具

267 274

275精确匹配集中的连字符需要 Claude Code v2.1.195 或更高版本。在早期版本中，像 `mcp__brave-search` 这样的裸连字符前缀被评估为未锚定的正则表达式，并匹配来自该服务器的每个工具。`mcp__brave-search__.*` 形式在每个版本上都有效。

276

268此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：277此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：

269 278

270```json theme={null}279```json theme={null}

306* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型返回 yes/no 决定作为 JSON。请参阅[基于提示的 hooks](#prompt-based-hooks)。315* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型返回 yes/no 决定作为 JSON。请参阅[基于提示的 hooks](#prompt-based-hooks)。

307* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个可以使用 Read、Grep 和 Glob 等工具来验证条件的 subagent，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅[基于代理的 hooks](#agent-based-hooks)。316* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个可以使用 Read、Grep 和 Glob 等工具来验证条件的 subagent，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅[基于代理的 hooks](#agent-based-hooks)。

308 317

318所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串和 `args` 去重，HTTP hooks 按 URL 去重。

319

320处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。

321

309<h4 id="common-fields">322<h4 id="common-fields">

310 通用字段323 通用字段

311</h4>324</h4>

341除了[通用字段](#common-fields)外，命令 hooks 还接受这些字段：354除了[通用字段](#common-fields)外，命令 hooks 还接受这些字段：

342 355

343| 字段 | 必需 | 描述 |356| 字段 | 必需 | 描述 |

344| :------------ | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |357| :------------ | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

345| `command` | 是 | 要执行的 shell 命令。与 `args` 一起，要直接生成的可执行文件。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |358| `command` | 是 | 要执行的 shell 命令。与 `args` 一起，要直接生成的可执行文件。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |

346| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |359| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅[Exec 形式和 shell 形式](#exec-form-and-shell-form) |

347| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅[在后台运行 hooks](#run-hooks-in-the-background) |360| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅[在后台运行 hooks](#run-hooks-in-the-background) |

348| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。暗示 `async`。Hook 的 stderr，或 stdout（如果 stderr 为空），作为系统提醒显示给 Claude，以便它可以对长时间运行的后台失败做出反应 |361| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。暗示 `async`。Hook 的 stderr，或 stdout（如果 stderr 为空），作为系统提醒显示给 Claude，以便它可以对长时间运行的后台失败做出反应 |

349| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"`（默认）或 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell。设置 `args` 时被忽略 |362| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"` 或 `"powershell"`。默认为 `"bash"`，或在未安装 Git Bash 时在 Windows 上默认为 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell。设置 `args` 时被忽略 |

350 363

351<a id="exec-form-and-shell-form" />364<a id="exec-form-and-shell-form" />

352 365

479| `prompt` | 是 | 要发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。使用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |492| `prompt` | 是 | 要发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。使用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |

480| `model` | 否 | 用于评估的模型。默认为快速模型 |493| `model` | 否 | 用于评估的模型。默认为快速模型 |

481 494

482所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串和 `args` 去重，HTTP hooks 按 URL 去重。处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。

~~483~~

484<h3 id="reference-scripts-by-path">495<h3 id="reference-scripts-by-path">

485 按路径引用脚本496 按路径引用脚本

486</h3>497</h3>

620| 字段 | 描述 |631| 字段 | 描述 |

621| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |632| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

634| `prompt_id` | UUID 标识当前正在处理的用户提示。与 OpenTelemetry 事件上的[`prompt.id` 属性](/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本 |

624| `cwd` | 调用 hook 时的当前工作目录 |636| `cwd` | 调用 hook 时的当前工作目录 |

625| `permission_mode` | 当前[权限模式](/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。并非所有事件都接收此字段：请参阅下面每个事件的 JSON 示例以检查 |637| `permission_mode` | 当前[权限模式](/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。并非所有事件都接收此字段：请参阅下面每个事件的 JSON 示例以检查 |

629使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：641使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：

630 642

631| 字段 | 描述 |643| 字段 | 描述 |

632| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |644| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

634| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。 |646| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。对于由[插件](/zh-CN/plugins)提供的 subagents，这是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。请参阅[SubagentStart](#subagentstart)了解如何针对插件范围的名称编写匹配器。 |

635 647

636仅[`SessionStart`](#sessionstart) hooks 可以接收 `model` 字段，且不保证存在。没有 `$CLAUDE_MODEL` 环境变量。Hook 进程继承父环境，因此如果您在 shell 中设置了 `$ANTHROPIC_MODEL`，它可以读取该值，但当您在会话期间使用 `/model` 切换模型时，该值不会改变。648仅[`SessionStart`](#sessionstart) hooks 可以接收 `model` 字段，且不保证存在。没有 `$CLAUDE_MODEL` 环境变量。Hook 进程继承父环境，因此如果您在 shell 中设置了 `$ANTHROPIC_MODEL`，它可以读取该值，但当您在会话期间使用 `/model` 切换模型时，该值不会改变。

637 649

640```json theme={null}652```json theme={null}

641{653{

642 "session_id": "abc123",654 "session_id": "abc123",

655 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",

643 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",656 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",

644 "cwd": "/home/user/my-project",657 "cwd": "/home/user/my-project",

645 "permission_mode": "default",658 "permission_mode": "default",

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

797input=$(cat)810input=$(cat)

798title="Claude Code'811title="Claude Code'

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

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

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

802```815```

867 880

868一些事件也可以重写内容而不仅仅允许或阻止它：881一些事件也可以重写内容而不仅仅允许或阻止它：

869 882

870* `PreToolUse` — `updatedInput` 直接在 `hookSpecificOutput` 下替换工具的参数，然后它运行（[详情](#pretooluse-decision-control)）883* `PreToolUse`：`updatedInput` 直接在 `hookSpecificOutput` 下替换工具的参数，然后它运行。请参阅[PreToolUse 决定控制](#pretooluse-decision-control)

871* `PermissionRequest` — `updatedInput` 在 `decision` 对象内（[详情](#permissionrequest-decision-control)）884* `PermissionRequest`：`updatedInput` 在 `decision` 对象内。请参阅[PermissionRequest 决定控制](#permissionrequest-decision-control)

872* `PostToolUse` — `updatedToolOutput` 替换工具的结果（[详情](#posttooluse-decision-control)）885* `PostToolUse`：`updatedToolOutput` 替换工具的结果。请参阅[PostToolUse 决定控制](#posttooluse-decision-control)

873* `UserPromptSubmit` — 无法替换提示；仅在其旁边注入 `additionalContext`886* `UserPromptSubmit`：无法替换提示；仅在其旁边注入 `additionalContext`

874 887

875对于编辑或转换用例，在 `PreToolUse` 处拦截出站工具输入，在 `PostToolUse` 处拦截入站工具结果。888对于编辑或转换用例，在 `PreToolUse` 处拦截出站工具输入，在 `PostToolUse` 处拦截入站工具结果。

876 889

959 "cwd": "/Users/...",972 "cwd": "/Users/...",

960 "hook_event_name": "SessionStart",973 "hook_event_name": "SessionStart",

961 "source": "startup",974 "source": "startup",

962 "model": "claude-sonnet-4-6"975 "model": "claude-sonnet-5"

963}976}

964```977```

965 978

1148 1161

1149`UserPromptSubmit` hooks 对 `command`、`http` 和 `mcp_tool` 类型的默认超时为 30 秒，比这些类型在其他事件上的 600 秒默认值更短。因为此 hook 在每个提示之前运行并阻止模型处理直到完成，卡住的 hook 会停滞会话。如果您的 hook 需要更多时间，在 hook 条目中设置 `timeout` 字段。1162`UserPromptSubmit` hooks 对 `command`、`http` 和 `mcp_tool` 类型的默认超时为 30 秒，比这些类型在其他事件上的 600 秒默认值更短。因为此 hook 在每个提示之前运行并阻止模型处理直到完成，卡住的 hook 会停滞会话。如果您的 hook 需要更多时间，在 hook 条目中设置 `timeout` 字段。

1150 1163

1164达到超时的 `UserPromptSubmit` hook 被取消，其输出（包括任何 `additionalContext`）被丢弃。提示仍然到达 Claude，但没有该上下文。从 v2.1.196 开始，成绩单显示一个通知，命名 hook、触发的超时以及输出被丢弃。早期版本取消 hook 而不显示通知。

1165

1151<h4 id="userpromptsubmit-input">1166<h4 id="userpromptsubmit-input">

1152 UserPromptSubmit 输入1167 UserPromptSubmit 输入

1153</h4>1168</h4>

1404 1419

1405在 Claude 创建工具参数后和处理工具调用之前运行。在工具名称上匹配：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何[MCP 工具名称](#match-mcp-tools)。1420在 Claude 创建工具参数后和处理工具调用之前运行。在工具名称上匹配：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何[MCP 工具名称](#match-mcp-tools)。

1406 1421

1422<Warning>

1423 PreToolUse 仅在 Claude 调用工具时运行。您[在提示中使用 `@` 引用的文件](/zh-CN/common-workflows#reference-files-and-directories)被添加而不进行任何工具调用：Claude Code 在构建提示时插入其内容，因此没有 PreToolUse hook 对它们触发，包括匹配 `Read` 的 hooks。要阻止特定路径的 `@` 引用，请改用[`Read` 拒绝规则](/zh-CN/permissions#read-and-edit)。

1424</Warning>

1425

1407使用[PreToolUse 决定控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。1426使用[PreToolUse 决定控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。

1408 1427

1409<h4 id="pretooluse-input">1428<h4 id="pretooluse-input">

2053 2072

2054当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤。对于内置代理，这是代理名称，如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。2073当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤。对于内置代理，这是代理名称，如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。

2055 2074

2075对于由[插件](/zh-CN/plugins)提供的 subagents，代理类型是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。冒号将插件范围的名称放在正则表达式路径上，因此使用 `^` 和 `$` 锚定匹配器以进行精确匹配：`^my-plugin:reviewer$`。

2076

2056<h4 id="subagentstart-input">2077<h4 id="subagentstart-input">

2057 SubagentStart 输入2078 SubagentStart 输入

2058</h4>2079</h4>

2255 Stop 输入2276 Stop 输入

2256</h4>2277</h4>

2257 2278

2258除了[通用输入字段](#common-input-fields)外，Stop hooks 还接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 字段在 Claude Code 已经作为 stop hook 的结果继续时为 `true`。检查此值或处理成绩单以防止 Claude Code 无限运行。Claude Code 在 8 次连续阻止后覆盖 hook 并结束轮次。`last_assistant_message` 字段包含 Claude 最终响应的文本内容，因此 hooks 可以访问它而无需解析成绩单文件。2279除了[通用输入字段](#common-input-fields)外，Stop hooks 还接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 字段在 Claude Code 已经作为 stop hook 的结果继续时为 `true`。检查此值或处理成绩单以防止 Claude Code 无限运行。Claude Code 在 8 次连续阻止后覆盖 hook 并结束轮次。

2280

2281`last_assistant_message` 字段包含 Claude 最终响应的文本内容，因此 hooks 可以访问它而无需解析成绩单文件。

2259 2282

2260`background_tasks` 和 `session_crons` 数组在 Claude Code v2.1.145 或更高版本中可用，让 hooks 区分"会话完成"和"会话暂停等待后台工作唤醒它"。当任务注册表可达时两个数组都存在，当没有任何内容在进行中或计划时为空。2283`background_tasks` 和 `session_crons` 数组在 Claude Code v2.1.145 或更高版本中可用，让 hooks 区分"会话完成"和"会话暂停等待后台工作唤醒它"。当任务注册表可达时两个数组都存在，当没有任何内容在进行中或计划时为空。

2261 2284

3284}3307}

3285```3308```

3286 3309

3310要从 PowerShell shell 形式命令引用项目根目录，请使用 `$env:CLAUDE_PROJECT_DIR` 将其作为环境变量读取。PowerShell 将裸 `${CLAUDE_PROJECT_DIR}` 形式视为本地变量而不是环境查找，Claude Code 仅对 [plugin hooks](#reference-scripts-by-path) 的 shell 形式替换该占位符。对于在 `settings.json` 中定义的 hook，要么使用 `$env:` 形式，要么切换到 [exec 形式](#exec-form-and-shell-form)，其中 `${CLAUDE_PROJECT_DIR}` 在每个 `args` 元素中被替换，无论 hook 在何处定义。

3311

3312下面的示例显示了一个 `settings.json` hook，它使用 `$env:` 形式运行项目脚本：

3313

3314```json theme={null}

3315{

3316 "type": "command",

3317 "shell": "powershell",

3318 "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""

3319}

3320```

3321

3287<h2 id="debug-hooks">3322<h2 id="debug-hooks">

3288 调试 hooks3323 调试 hooks

3289</h2>3324</h2>

interactive-mode.md +17 −13

Details

42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示内移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。{/* min-version: 2.1.169 */}从 v2.1.169 开始，换行的单行输入的行为与多行输入相同 |42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示内移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。{/* min-version: 2.1.169 */}从 v2.1.169 开始，换行的单行输入的行为与多行输入相同 |

249* 当您运行 `/clear` 以启动新会话时，输入历史会重置。上一个会话的对话被保留并可以恢复。249* 当您运行 `/clear` 以启动新会话时，输入历史会重置。上一个会话的对话被保留并可以恢复。

250* 连续两次提交相同的提示会记录一个历史条目，因此按向上箭头会跳转到上一个不同的提示250* 连续两次提交相同的提示会记录一个历史条目，因此按向上箭头会跳转到上一个不同的提示

251* 使用向上/向下箭头导航（请参阅上面的快捷键）251* 使用向上/向下箭头导航（请参阅上面的快捷键）

252* **注意**：历史扩展（`!`）默认禁用252* 历史扩展（`!`）默认禁用

253 253

254<h3 id="reverse-search-with-ctrl-r">254<h3 id="reverse-search-with-ctrl-r">

255 使用 Ctrl+R 反向搜索255 使用 Ctrl+R 反向搜索

271搜索加载所选范围内最近的 100 个唯一提示，重复项折叠到最新出现。匹配的提示显示时搜索词突出显示，因此您可以找到并重用以前的输入。271搜索加载所选范围内最近的 100 个唯一提示，重复项折叠到最新出现。匹配的提示显示时搜索词突出显示，因此您可以找到并重用以前的输入。

272 272

273<h2 id="background-bash-commands">273<h2 id="background-bash-commands">

274 后台 bash 命令274 后台 Bash 命令

275</h2>275</h2>

276 276

277Claude Code 支持在后台运行 bash 命令，允许您在长时间运行的进程执行时继续工作。277Claude Code 支持在后台运行 Bash 命令，允许您在长时间运行的进程执行时继续工作。

278 278

279<h3 id="how-backgrounding-works">279<h3 id="how-backgrounding-works">

280 后台运行的工作原理280 后台运行的工作原理

285要在后台运行命令，您可以：285要在后台运行命令，您可以：

286 286

287* 提示 Claude Code 在后台运行命令287* 提示 Claude Code 在后台运行命令

288* 按 Ctrl+B 将常规 Bash 工具调用移到后台。（Tmux 用户必须按 Ctrl+B 两次，因为 tmux 的前缀键。）288* 按 `Ctrl+B` 将常规 Bash 工具调用移到后台。Tmux 用户必须按 `Ctrl+B` 两次，因为 tmux 的前缀键。

289 289

290**主要功能：**290**主要功能：**

291 291

292* 输出被写入文件，Claude 可以使用 Read 工具检索它292* 输出被写入文件，Claude 可以使用 Read 工具检索它

293* 后台任务具有唯一的 ID 用于跟踪和输出检索293* 后台任务具有唯一的 ID 用于跟踪和输出检索

294* 当 Claude Code 退出时，后台任务会自动清理294* 当 Claude Code 退出时，后台任务会自动清理。将会话放在后台而不是退出会将它们交给后台会话，它们会继续运行。请参阅[在会话内部将其放在后台](/zh-CN/agent-view#from-inside-a-session)

295* 如果输出超过 5GB，后台任务会自动终止，stderr 中会有说明原因的注释295* 如果输出超过 5GB，后台任务会自动终止，stderr 中会有说明原因的注释

296* {/* min-version: 2.1.193 */}从 v2.1.193 开始，在 macOS 和 Linux 上，当操作系统发出内存压力信号时，运行中的后台任务会被终止，前提是会话已经空闲至少 30 分钟，没有任何轮次或子代理运行。将 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/zh-CN/env-vars) 设置为 `1` 以关闭此功能

296 297

297要禁用所有后台任务功能，请将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量设置为 `1`。有关详细信息，请参阅[环境变量](/zh-CN/env-vars)。298要禁用所有后台任务功能，请将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量设置为 `1`。有关详细信息，请参阅[环境变量](/zh-CN/env-vars)。

298 299

308 使用 `!` 前缀的 Shell 模式309 使用 `!` 前缀的 Shell 模式

309</h3>310</h3>

310 311

311通过在输入前加上 `!` 来直接运行 bash 命令，无需通过 Claude：312通过在输入前加上 `!` 来直接运行 shell 命令，无需通过 Claude：

312 313

313```bash theme={null}314```bash theme={null}

314! npm test315! npm test

322* 显示实时进度和输出323* 显示实时进度和输出

323* 支持相同的 `Ctrl+B` 后台运行长时间运行的命令324* 支持相同的 `Ctrl+B` 后台运行长时间运行的命令

324* 不需要 Claude 解释或批准命令325* 不需要 Claude 解释或批准命令

325* 支持基于历史的自动完成：键入部分命令并按 **Tab** 以从当前项目中的上一个 `!` 命令完成326* 支持基于历史的自动完成：键入部分命令并按 `Tab` 以从当前项目中的上一个 `!` 命令完成

326* 使用 `Escape`、`Backspace` 或在空提示上使用 `Ctrl+U` 退出327* {/* min-version: 2.1.193 */}从 v2.1.193 开始在所有平台上支持实时文件路径自动完成：键入包含正斜杠的令牌，例如 `./src/` 或 `~/`，以查看匹配文件和目录的下拉列表，然后按 `Tab` 接受。在 Windows 上也使用正斜杠；下拉列表由 `/` 触发，而不是 `\`

328* 在空提示上使用 `Escape`、`Backspace` 或 `Ctrl+U` 退出

327* 将以 `!` 开头的文本粘贴到空提示中会自动进入 shell 模式，与键入的 `!` 行为相匹配329* 将以 `!` 开头的文本粘贴到空提示中会自动进入 shell 模式，与键入的 `!` 行为相匹配

328 330

329从 v2.1.186 开始，Claude 在命令输出进入记录后会自动响应，因此您可以运行 `! npm test` 并获得失败的解释，无需第二个提示。响应成本与发送普通提示相同。要恢复早期行为（其中输出被添加到上下文而不响应），请在 `settings.json` 中将 [`respondToBashCommands`](/zh-CN/settings#available-settings) 设置为 `false`。在 v2.1.186 之前，shell 模式始终将输出添加到上下文而不响应。331从 v2.1.186 开始，Claude 在命令输出进入记录后会自动响应，因此您可以运行 `! npm test` 并获得失败的解释，无需第二个提示。响应成本与发送普通提示相同。要恢复早期行为（其中输出被添加到上下文而不响应），请在 `settings.json` 中将 [`respondToBashCommands`](/zh-CN/settings#available-settings) 设置为 `false`。在 v2.1.186 之前，shell 模式始终将输出添加到上下文而不响应。

338 340

339Claude 响应后，建议会根据您的对话历史继续出现，例如多部分请求的后续步骤或工作流的自然延续。341Claude 响应后，建议会根据您的对话历史继续出现，例如多部分请求的后续步骤或工作流的自然延续。

340 342

341* 按 **Tab** 或 **Right arrow** 将建议放入提示输入中，然后按 **Enter** 提交343* 按 `Tab` 或 `Right arrow` 将建议放入提示输入中，然后按 `Enter` 提交

342* 开始输入以关闭它344* 开始输入以关闭它

343 345

344建议作为后台请求运行，该请求重用父对话的 prompt cache，因此额外成本最小。当缓存冷时，Claude Code 会跳过建议生成以避免不必要的成本。346建议作为后台请求运行，该请求重用父对话的 prompt cache，因此额外成本最小。当缓存冷时，Claude Code 会跳过建议生成以避免不必要的成本。

368* **单一响应**：覆盖层中没有后续轮次。要继续该线程，请使用 `f` 将其分叉到自己的会话中。370* **单一响应**：覆盖层中没有后续轮次。要继续该线程，请使用 `f` 将其分叉到自己的会话中。

369* **低成本**：侧面问题重用父对话的提示缓存，因此额外成本最小。371* **低成本**：侧面问题重用父对话的提示缓存，因此额外成本最小。

370 372

371答案出现后，覆盖层接受这些按键。来自同一会话的较早侧面问题显示为当前答案上方的暗淡列表；它们保持在对话历史之外，但在覆盖层中保持可见，直到您清除它们。373来自同一会话的较早侧面问题显示为当前答案上方的暗淡列表。它们保持在对话历史之外，但在覆盖层中保持可见，直到您清除它们。

374

375答案出现后，覆盖层接受这些按键。

372 376

373| 按键 | 操作 |377| 按键 | 操作 |

374| :----------------------- | :-------------------------------------------------------------------------------------------------------------------- |378| :----------------------- | :-------------------------------------------------------------------------------------------------------------------- |

406 PR 审查状态410 PR 审查状态

407</h2>411</h2>

408 412

409在处理具有开放拉取请求的分支时，Claude Code 在页脚中显示可点击的 PR 链接（例如"PR #446"）。该链接具有彩色下划线，指示审查状态：413在处理具有开放拉取请求的分支时，Claude Code 在页脚中显示可点击的 PR 链接，例如"PR #446"。该链接具有彩色下划线，指示审查状态：

410 414

411* 绿色：已批准415* 绿色：已批准

412* 黄色：待审查416* 黄色：待审查

413* 红色：请求更改417* 红色：请求更改

414* 灰色：草稿418* 灰色：草稿

415 419

416拉取请求合并或关闭后，徽章消失。`Cmd+click`（Mac）或 `Ctrl+click`（Windows/Linux）点击链接以在浏览器中打开拉取请求。状态每 60 秒刷新一次，并在会话中运行 `gh pr` 或 `git push` 命令后立即刷新。420拉取请求合并或关闭后，徽章消失。`Cmd+click`（macOS）或 `Ctrl+click`（Windows/Linux）点击链接以在浏览器中打开拉取请求。状态每 60 秒刷新一次，并在会话中运行 `gh pr` 或 `git push` 命令后立即刷新。

417 421

418<Note>422<Note>

419 PR 状态需要安装并验证 `gh` CLI（`gh auth login`）。423 PR 状态需要安装并验证 `gh` CLI（`gh auth login`）。

jetbrains.md +1 −1

Details

233 安全考虑233 安全考虑

234</h2>234</h2>

235 235

236当 Claude Code 在启用自动编辑权限的 JetBrains IDE 中运行时，它可能能够修改可由您的 IDE 自动执行的 IDE 配置文件。这可能会增加在自动编辑模式下运行 Claude Code 的风险，并允许绕过 Claude Code 对 bash 执行的权限提示。236当 Claude Code 在启用 [`acceptEdits` 权限模式](/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)的 JetBrains IDE 中运行时，它可能能够修改可由您的 IDE 自动执行的 IDE 配置文件。这可能会增加在 `acceptEdits` 模式下运行 Claude Code 的风险，并允许绕过 Claude Code 对 bash 执行的权限提示。

237 237

238在 JetBrains IDE 中运行时，请考虑：238在 JetBrains IDE 中运行时，请考虑：

239 239

llm-gateway.md +0 −96 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> 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.~~

~~5# LLM gateway~~

7> 通过 LLM gateway 路由 Claude Code 以实现集中身份验证、使用情况跟踪和成本控制。涵盖将 Claude Code 连接到网关、为您的组织部署网关、Claude Code 发送到网关的内容，以及网关如何与 claude.ai 订阅交互。

~~9LLM gateway 是您的组织在 Claude Code 和模型提供商之间运行的代理。Claude Code 将 API 流量发送到网关，网关使用您的组织控制的凭证将其转发给提供商。~~

~~11<Note>~~

~~12 * 如果您是连接到现有网关的开发人员：[将 Claude Code 连接到您的网关](/zh-CN/llm-gateway-connect)~~

~~13 * 如果您是为组织部署网关的管理员：[部署和分发网关](/zh-CN/llm-gateway-rollout)~~

~~14 * 如果您正在配置网关产品：[网关协议参考](/zh-CN/llm-gateway-protocol)~~

~~15</Note>~~

~~17<h2 id="what-a-gateway-provides">~~

~~18 网关提供的功能~~

~~19</h2>~~

~~21网关为您的组织提供一个地方来管理：~~

~~23* **凭证**：提供商密钥保留在服务器端；开发人员改为持有网关凭证~~

~~24* **使用情况跟踪**：按开发人员或团队归属使用情况，无论哪个提供商处理请求~~

~~25* **成本控制**：在一个地方强制执行预算和速率限制~~

~~26* **审计日志**：记录每个模型请求以实现合规性~~

~~27* **提供商切换**：在网关配置中更改提供商，无需接触开发人员机器~~

~~29除了提供商切换外，所有这些都适用于上游是 Anthropic 的 API 还是[云提供商](/zh-CN/third-party-integrations)。~~

31权衡是网关成为您的组织运营的基础设施。Claude Code 在每个版本中添加功能，不转发这些功能的网关会破坏相应的功能，因此网关产品需要随着 Claude Code 的发展而保持更新。[网关协议参考](/zh-CN/llm-gateway-protocol)涵盖要转发的内容。

~~33<h2 id="how-a-gateway-works">~~

~~34 网关如何工作~~

~~35</h2>~~

37默认情况下，Claude Code 直接向 Anthropic 的 API `api.anthropic.com` 发送请求。要通过网关路由，请将 `ANTHROPIC_BASE_URL` 设置为网关的地址；Claude Code 改为向那里发送相同的请求。网关对开发人员进行身份验证，附加您的组织的提供商凭证，并将每个请求转发给它配置的任何提供商。

39`ANTHROPIC_BASE_URL` 是大多数网关的地址变量。面向特定云提供商（如 Bedrock、Vertex、Foundry 或 AWS 上的 Claude Platform）的网关改为使用该提供商的基础 URL 变量；[API 格式](/zh-CN/llm-gateway-protocol#api-formats)列出了哪个变量与每个配置相关联。

~~41<Frame>~~

42 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/llm-gateway-flow.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=1c1a8dcc0cfcc3a58652cc8e28cd3e20" alt="显示 Claude Code 通过 LLM gateway 路由的图表。在开发人员机器区域中，Claude Code CLI、VS Code 扩展和 CI 或 Agent SDK 客户端向网关发送请求，网关 API 格式的基础 URL 变量指向它，每个开发人员持有每个开发人员的凭证，桌面应用通过组织分发的配置到达相同的网关。在标记为您的基础设施的区域中，LLM gateway 处理身份验证、使用情况跟踪、预算和路由，并使用您的组织的凭证转发请求。在模型提供商区域中，实线箭头指向您配置的提供商，显示为 Anthropic API，虚线箭头指向其他提供商选项，以 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 为例。" width="780" height="322" data-path="images/llm-gateway-flow.svg" />

~~43</Frame>~~

~~45涉及两种凭证：~~

~~47* **开发人员凭证**：每个开发人员持有自己的凭证，由网关颁发。它向网关验证他们的身份并在使用情况跟踪中识别他们~~

~~48* **提供商凭证**：网关持有一个提供商账户的凭证，由所有转发的流量共享。您不需要为每个开发人员配置提供商密钥~~

50网关将每个请求转发给您配置的提供商，例如 Anthropic API、[Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或 [AWS 上的 Claude Platform](/zh-CN/claude-platform-on-aws)。因为 Claude Code 仅与网关通信，提供商选择是网关的配置，而不是客户端的。

~~52<h2 id="roll-out-a-gateway">~~

~~53 部署网关~~

~~54</h2>~~

~~56当您准备好为组织部署 LLM gateway 时，无论您选择哪个网关产品，顺序都是相同的：~~

~~581. 部署网关并给予它您的提供商凭证，以便它可以验证它转发的请求。~~

~~592. 为每个开发人员颁发网关凭证，以便使用情况归属于开发人员，离职时撤销一个凭证。~~

603. 通过[托管设置文件](/zh-CN/settings#settings-files)和您的机密工具分发配置，以便每台机器都接收基础 URL 和凭证。当两者都分发时，开发人员无需配置任何内容。如果您没有设置分发，开发人员按照[连接页面](/zh-CN/llm-gateway-connect)自己设置变量。

~~614. 让每个开发人员[检查 Claude Code 中的配置](/zh-CN/llm-gateway-connect#check-for-an-existing-configuration)，以便分发问题在他们依赖网关之前浮出水面。~~

63[为您的组织部署 LLM gateway](/zh-CN/llm-gateway-rollout) 逐步讲解每个步骤，并显示在每个步骤中分发的配置文件。网关是组织设置的一部分；对于策略强制执行、使用情况可见性和数据处理决策，请参阅[为您的组织设置 Claude Code](/zh-CN/admin-setup)。

~~65<h2 id="third-party-gateways">~~

~~66 第三方网关~~

~~67</h2>~~

69任何公开[支持的 API 格式](/zh-CN/llm-gateway-protocol#api-formats)的网关都可以工作。Anthropic 不认可、维护或审计第三方网关产品。按照它们自己的文档部署它们，然后使用[部署步骤](/zh-CN/llm-gateway-rollout)完成 Claude Code 端的部署。

~~71<h2 id="subscriptions-and-gateways">~~

~~72 订阅和网关~~

~~73</h2>~~

75当[网关凭证变量](/zh-CN/llm-gateway-connect#set-the-credential-variable)或 `apiKeyHelper` 处于活动状态时，开发人员的 claude.ai 订阅不被使用：凭证替换该会话的订阅登录，订阅的使用限制不适用。该流量按令牌计费给拥有网关转发的凭证的人，例如您的组织的 Anthropic Console 账户，或当网关路由到那里时您的 Bedrock、Vertex 或 Foundry 账户。

77仅设置 `ANTHROPIC_BASE_URL`，不设置网关凭证，不会替换订阅。请求仍然通过网关路由，但保存的 claude.ai 登录保持活动凭证，因此其使用限制和计费适用。将此流量转发给 Anthropic 的网关必须转发 `anthropic-beta` 中的 OAuth 功能；请参阅[请求头参考](/zh-CN/llm-gateway-protocol#request-headers)。

~~79<h2 id="configure-separately-from-the-gateway">~~

~~80 与网关分开配置~~

~~81</h2>~~

~~83网关确定模型 API 请求的发送位置。模型选择、Claude Code 的其余网络流量和企业代理分开配置：~~

85* **模型选择**：基础 URL 决定请求的发送位置，而不是哪个模型回答它们。使用 `/model` 命令或模型环境变量选择模型；请参阅[如何设置您的模型](/zh-CN/model-config#setting-your-model)

86* **客户端流量**：版本检查和可选的客户端遥测（都可以用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-CN/env-vars) 禁用），以及当使用 claude.ai 或 Console 登录时的登录流量，转到 Anthropic 的更新和身份验证端点而不是网关。请参阅[网络访问要求](/zh-CN/network-config#network-access-requirements)了解域名

87* **企业代理**：使用 `HTTPS_PROXY` 设置的代理位于 Claude Code 和它与之通信的每个服务器之间，包括网关。如果您的网络需要代理，请配置两者；请参阅[代理配置](/zh-CN/network-config#proxy-configuration)

~~89<h2 id="related-pages">~~

~~90 相关页面~~

~~91</h2>~~

~~93* [将 Claude Code 连接到 LLM gateway](/zh-CN/llm-gateway-connect)：在您自己的机器上设置基础 URL 和凭证，具有每个表面的配置和故障排除表~~

~~94* [为您的组织部署 LLM gateway](/zh-CN/llm-gateway-rollout)：部署网关、颁发开发人员凭证和分发托管设置的管理员检查清单~~

~~95* [Gateway 协议参考](/zh-CN/llm-gateway-protocol)：Claude Code 发送到网关的内容，供配置网关的运营商使用，涵盖端点、要转发的头和功能传递~~

~~96* [为您的组织设置 Claude Code](/zh-CN/admin-setup)：网关是其中一部分的更广泛的部署决策，包括策略强制执行和使用情况可见性~~

llm-gateway-connect.md +12 −7

Details

231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

232```232```

233 233

234对于 bearer 令牌网关，将相同的密钥作为 `anthropic_api_key` 输入和工作流 `env` 块中的 `ANTHROPIC_AUTH_TOKEN` 传递。操作在启动 Claude Code 之前需要 `anthropic_api_key`、`CLAUDE_CODE_OAUTH_TOKEN` 或工作负载身份联合，并且它不读取 `ANTHROPIC_AUTH_TOKEN`，因此输入满足该启动检查，而 env 变量将密钥放在网关读取的 `Authorization` 标头中。`x-api-key` 中的副本被忽略：234对于 bearer 令牌网关，将相同的密钥作为 `anthropic_api_key` 输入和工作流 `env` 块中的 `ANTHROPIC_AUTH_TOKEN` 传递。操作在启动 Claude Code 之前需要 `anthropic_api_key`、`CLAUDE_CODE_OAUTH_TOKEN` 或工作负载身份联合，并且它不读取 `ANTHROPIC_AUTH_TOKEN`，因此输入满足该启动检查。env 变量是将密钥放在网关读取的 `Authorization` 标头中的内容；`x-api-key` 中的副本被忽略：

235 235

236```yaml theme={null}236```yaml theme={null}

237env:237env:

285 285

286[Slack 中的 Claude Code](/zh-CN/slack) 和[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 是 Anthropic 托管的产品，始终使用 Anthropic 的 API；它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上，请不要为这些用户启用这些界面。286[Slack 中的 Claude Code](/zh-CN/slack) 和[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 是 Anthropic 托管的产品，始终使用 Anthropic 的 API；它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上，请不要为这些用户启用这些界面。

287 287

288[远程控制](/zh-CN/remote-control)和[语音听写](/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。要使用任一个，取消设置网关凭证并改用 claude.ai 登录；`/doctor` 命名要取消设置的变量。288[远程控制](/zh-CN/remote-control)和[语音听写](/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主机时，远程控制也被禁用，因此仅使用 claude.ai 登录是不够的。

289

290要恢复任一功能，请使用 claude.ai 登录并取消设置它检查的网关变量。`/doctor` 命名要取消设置的凭证变量。

291

292* 语音听写：取消设置网关凭证

293* 远程控制：取消设置网关凭证和 `ANTHROPIC_BASE_URL`

289 294

290<h2 id="additional-configuration">295<h2 id="additional-configuration">

291 其他配置296 其他配置

318```json theme={null}323```json theme={null}

319{324{

320 "env": {325 "env": {

321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"326 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"

322 }327 }

323}328}

324```329```

388 通过网关路由到云提供商393 通过网关路由到云提供商

389</h3>394</h3>

390 395

391这些配置使用提供商特定的基础 URL 变量代替 `ANTHROPIC_BASE_URL` 将 Claude Code 指向通过网关的云提供商。Bedrock 和 Vertex 网关接受这些提供商的本机请求格式；Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式，仅在哪个基础 URL 变量到达它们方面有所不同。396这些配置使用提供商特定的基础 URL 变量代替 `ANTHROPIC_BASE_URL` 将 Claude Code 指向通过网关的云提供商。Bedrock 和 Agent Platform 网关接受这些提供商的本机请求格式；Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式，仅在哪个基础 URL 变量到达它们方面有所不同。

392 397

393仅在您的网关团队特别命名 Bedrock、Vertex、Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的[验证请求](#verify-the-connection)返回 JSON，您可以跳过本部分。398仅在您的网关团队特别命名 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的[验证请求](#verify-the-connection)返回 JSON，您可以跳过本部分。

394 399

395为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求，因为网关持有这些。如果网关需要自己的令牌，请在块后添加 `ANTHROPIC_AUTH_TOKEN`，除了 Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。400为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求，因为网关持有这些。如果网关需要自己的令牌，请在块后添加 `ANTHROPIC_AUTH_TOKEN`，除了 Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。

396 401

416 </Tab>421 </Tab>

417</Tabs>422</Tabs>

418 423

419<h4 id="google-vertex-ai">424<h4 id="google-cloud’s-agent-platform">

420 Google Vertex AI425 Google Cloud 的 Agent Platform

421</h4>426</h4>

422 427

423<Tabs>428<Tabs>

llm-gateway-protocol.md +19 −14

Details

8 8

9本页面记录了 Claude Code 发送到 gateway 的请求，包括它调用的端点、gateway 必须转发的请求头和请求体字段，以及当 gateway 不转发这些内容时哪些功能会停止工作。本页面是为配置 gateway 产品以与 Claude Code 配合工作的运营人员编写的。9本页面记录了 Claude Code 发送到 gateway 的请求，包括它调用的端点、gateway 必须转发的请求头和请求体字段，以及当 gateway 不转发这些内容时哪些功能会停止工作。本页面是为配置 gateway 产品以与 Claude Code 配合工作的运营人员编写的。

10 10

11一个运行中的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 在 `GET /protocol` 处提供此契约的机器可读版本，涵盖相同的转发要求以及 Claude apps gateway 特定的 SSO 登录、托管设置交付和遥测端点。Claude apps gateway 从与 CLI 相同的 `claude` 二进制文件运行，因此 [Claude apps gateway 快速入门](/zh-CN/claude-apps-gateway#quickstart) 是获取可以从中获取规范的运行实例的最短路径。

11<Note>13<Note>

12 * 要为您的组织推出现有或第三方 gateway，请参阅[推出 LLM gateway](/zh-CN/llm-gateway-rollout)14 * 要为您的组织推出现有或第三方 gateway，请参阅[推出 LLM gateway](/zh-CN/llm-gateway-rollout)

13 * 如果您是使用给定凭证向 gateway 验证 Claude Code 的个人开发者，请参阅[将 Claude Code 连接到 LLM gateway](/zh-CN/llm-gateway-connect)15 * 如果您是使用给定凭证向 gateway 验证 Claude Code 的个人开发者，请参阅[将 Claude Code 连接到 LLM gateway](/zh-CN/llm-gateway-connect)

32 API 格式34 API 格式

33</h2>35</h2>

34 36

35gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式由客户端的配置决定：下表"选择者"列中的变量指向您的 gateway 使用该格式。37gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式由客户端的配置决定：下表"选择者"列中的变量指向您的 gateway 使用该格式。Agent Platform 是 Google Cloud 的 Claude 端点，原名 Vertex AI；其变量名保留 `VERTEX` 拼写。

36 38

37| 格式 | 选择者 | 端点 | 转发不变 |39| 格式 | 选择者 | 端点 | 转发不变 |

38| :------------------ | :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------- |40| :------------------------ | :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------- |

40| Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 请求体字段 |42| Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 请求体字段 |

41| Vertex rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |43| Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |

42 44

43<h3 id="foundry-and-claude-platform-on-aws">45<h3 id="foundry-and-claude-platform-on-aws">

44 Foundry 和 AWS 上的 Claude Platform46 Foundry 和 AWS 上的 Claude Platform

50 可选端点和启动流量52 可选端点和启动流量

51</h3>53</h3>

52 54

53令牌计数端点是唯一可选的：当它们不存在时，Claude Code 在本地估计上下文使用情况。推理请求发送到 `/v1/messages?beta=true`，因此请匹配路径，而不是完整 URL。Vertex 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。55令牌计数端点是唯一可选的：当它们不存在时，Claude Code 在本地估计上下文使用情况。推理请求发送到 `/v1/messages?beta=true`，因此请匹配路径，而不是完整 URL。Agent Platform 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。

54 56

55gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西：一个 `HEAD /` 连接探针，以及在 Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求。57gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西：一个 `HEAD /` 连接探针，以及在 Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求。

56 58

66 68

67客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。69客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。

68 70

~~69* 当客户端使用 Bedrock 或 Vertex 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集~~71* 当客户端使用 Bedrock 或 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集

~~70* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Bedrock 或 Vertex 上游~~72* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Bedrock 或 Agent Platform 上游

71 73

72弥合这种差异是您的 gateway 的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。74弥合这种差异是您的 gateway 的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。

73 75

80| 请求头 | 描述 |82| 请求头 | 描述 |

81| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |83| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

82| `Authorization`、`x-api-key` | 开发者的 gateway 凭证，根据他们设置的[凭证变量](/zh-CN/llm-gateway-connect#set-the-credential-variable)在一个或两个请求头中 |84| `Authorization`、`x-api-key` | 开发者的 gateway 凭证，根据他们设置的[凭证变量](/zh-CN/llm-gateway-connect#set-the-credential-variable)在一个或两个请求头中 |

84| `anthropic-beta` | 请求的逗号分隔功能值。逐字转发请求头；不要将单个值列入白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而不设置 gateway 凭证变量时可能），此请求头还携带上游需要的 OAuth 功能，删除它会导致这些请求失败，返回 `401` |86| `anthropic-beta` | 请求的逗号分隔功能值。逐字转发请求头；不要将单个值列入白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而不设置 gateway 凭证变量时可能），此请求头还携带上游需要的 OAuth 功能，删除它会导致这些请求失败，返回 `401` |

98 100

99转发到 Anthropic 格式上游时，将 `anthropic-*` 请求头和请求体字段原封不动地传递，而不是将您今天看到的列入白名单。固定到观察列表的 gateway 会删除下一个功能的请求头或字段，并在引入它的版本上破坏它。101转发到 Anthropic 格式上游时，将 `anthropic-*` 请求头和请求体字段原封不动地传递，而不是将您今天看到的列入白名单。固定到观察列表的 gateway 会删除下一个功能的请求头或字段，并在引入它的版本上破坏它。

100 102

101例外是非 Anthropic 上游，如 Bedrock 或 Vertex，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。103例外是非 Anthropic 上游，如 Bedrock 或 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。

102 104

103<h2 id="system-prompt-attribution-block">105<h2 id="system-prompt-attribution-block">

104 系统提示归属块106 系统提示归属块

112 功能传递114 功能传递

113</h2>115</h2>

114 116

115Claude Code 将 `ANTHROPIC_BASE_URL` gateway 视为 Anthropic 格式端点，并向其发送它发送到 `api.anthropic.com` 的 beta 请求头和请求体字段，除了为直接连接保留的一小组诊断和默认值。117Claude Code 将 `ANTHROPIC_BASE_URL` gateway 视为 Anthropic 格式端点，并向其发送它发送到 `api.anthropic.com` 的 beta 请求头和请求体字段，除了为直接连接保留的一小组诊断和默认值，例如下面涵盖的细粒度工具流式传输默认值。该集合因版本而异，因此不要依赖其内容。

116 118

117添加请求体字段的功能将它们与 beta 请求头配对，该对一起传递。删除请求头同时传递请求体的 gateway，或将 Anthropic 格式请求体转发到具有不同架构的上游，会产生硬 `400` 错误；只有当两个部分一起缺失时，功能才会安静地关闭。重写或编辑请求体以进行内容检查的 gateway 会以与删除相同的方式破坏配对，因此在不修改的情况下检查。该表注明了功能偏离配对的位置。119添加请求体字段的功能将它们与 beta 请求头配对，该对一起传递。删除请求头同时传递请求体的 gateway，或将 Anthropic 格式请求体转发到具有不同架构的上游，会产生硬 `400` 错误；只有当两个部分一起缺失时，功能才会安静地关闭。重写或编辑请求体以进行内容检查的 gateway 会以与删除相同的方式破坏配对，因此在不修改的情况下检查。该表注明了功能偏离配对的位置。

118 120

119细粒度工具流式传输是直接连接默认值之一：每当请求通过自定义基础 URL 路由时，它默认关闭，当开发者设置 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-CN/env-vars) 时，gateway 会接收它。121细粒度工具流式传输是直接连接默认值之一：每当请求通过自定义基础 URL 路由时，它默认关闭，当开发者设置 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-CN/env-vars) 时，gateway 会接收它。

120 122

121| 功能 | 请求头和请求体对 | 破坏时的症状 | 补救 |123| 功能 | 请求头和请求体对 | 破坏时的症状 | 补救 |

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

123| [自适应推理](/zh-CN/model-config#adjust-effort-level) | 无 beta 请求头。Claude Code 为 Claude 4.6 及更高版本发送 `thinking: {"type": "adaptive"}`，并将它不识别的模型名称（如 gateway 别名）视为接收该字段的当前模型 | 当上游模型构建不接受它时，命名 `thinking` 字段或 `adaptive` 标签的 `400` | 升级上游。在 Opus 4.6 和 Sonnet 4.6 上，开发者可以改为设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |125| [自适应推理](/zh-CN/model-config#adjust-effort-level) | 无 beta 请求头。Claude Code 为 Claude 4.6 及更高版本发送 `thinking: {"type": "adaptive"}`，并将它不识别的模型名称（如 gateway 别名）视为接收该字段的当前模型 | 当上游模型构建不接受它时，命名 `thinking` 字段或 `adaptive` 标签的 `400` | 升级上游。在 Opus 4.6 和 Sonnet 4.6 上，开发者可以改为设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |

124| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理 beta 请求头与 `context_management` 请求体字段配对 | `400` 带有 `Extra inputs are not permitted`。常见于 gateway 接受 Anthropic 格式请求但将其转发到 Bedrock 时 | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars) |126| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理 beta 请求头与 `context_management` 请求体字段配对 | `400` 带有 `Extra inputs are not permitted`。常见于 gateway 接受 Anthropic 格式请求但将其转发到 Bedrock 时 | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars) |

125| [扩展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 仅 Beta 请求头，无请求体字段 | 当请求头被删除时无声地不可用；上游永远不会看到功能请求 | 逐字转发 `anthropic-beta` |127| [扩展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 仅 Beta 请求头，无请求体字段 | 当请求头被删除时无声地不可用；上游永远不会看到功能请求 | 逐字转发 `anthropic-beta` |

126| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具架构字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具架构字段的 `400` | 转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |128| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具架构字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具架构字段的 `400` | 转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |

127| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Bedrock 和 Vertex 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发字段及其请求头 |129| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Bedrock 和 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发字段及其请求头 |

129 131

130`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [变量](/zh-CN/model-config)仅在提供商配置中声明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。它们在 `ANTHROPIC_BASE_URL` gateway 后面没有效果。132`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [变量](/zh-CN/model-config)仅在提供商配置中声明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。它们在 `ANTHROPIC_BASE_URL` gateway 后面没有效果。

182{184{

183 "data": [185 "data": [

184 { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },186 { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },

185 { "id": "claude-opus-4-7" }187 { "id": "claude-opus-4-8" }

186 ]188 ]

187}189}

188```190```

191 选择器条目和缓存193 选择器条目和缓存

192</h3>194</h3>

193 195

194选择器是当开发者在 Claude Code 中运行 `/model` 时打开的交互式模型列表。每个发现的条目都标记为"来自 gateway"，并在提供时使用 `display_name`。仅当发现的 ID 与选择器中已有的行完全匹配时，或当发现的和现有的 ID 都解析为 [Fable](/zh-CN/model-config#work-with-fable-5) 时，才会跳过发现的 ID。内置行按别名（如 `sonnet`）键入，因此发现的 ID（如 `claude-sonnet-4-6`）在内置条目旁边添加自己的"来自 gateway"行。[`availableModels` 托管设置](/zh-CN/settings#available-settings)限制了发现可以添加的内容。196选择器是当开发者在 Claude Code 中运行 `/model` 时打开的交互式模型列表。每个发现的条目都标记为"来自 gateway"，并在提供时使用 `display_name`。[`availableModels` 托管设置](/zh-CN/settings#available-settings)限制了发现可以添加的内容。

197

198仅当发现的 ID 与选择器中已有的行完全匹配时，或当发现的和现有的 ID 都解析为 [Fable](/zh-CN/model-config#work-with-fable-5) 时，才会跳过发现的 ID。内置行按别名（如 `sonnet`）键入，因此发现的 ID（如 `claude-sonnet-4-6`）在内置条目旁边添加自己的"来自 gateway"行。

195 199

196结果被缓存到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，并在每次启动时刷新。如果请求失败或 gateway 未实现 `/v1/models`，选择器会回退到上次启动的缓存列表或内置模型列表。如果您的 gateway 在不匹配发现过滤器的别名下提供 Claude 模型，开发者可以使用[模型配置](/zh-CN/model-config)变量手动添加这些别名。200结果被缓存到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，并在每次启动时刷新。如果请求失败或 gateway 未实现 `/v1/models`，选择器会回退到上次启动的缓存列表或内置模型列表。如果您的 gateway 在不匹配发现过滤器的别名下提供 Claude 模型，开发者可以使用[模型配置](/zh-CN/model-config)变量手动添加这些别名。

197 201

201 205

202有关 gateway 文档集的其余部分和基础 API 参考：206有关 gateway 文档集的其余部分和基础 API 参考：

203 207

204* [LLM gateway 概述](/zh-CN/llm-gateway)：gateway 是什么以及它如何与 claude.ai 订阅交互208* [Gateway 概述](/zh-CN/gateways)：什么是 gateway 以及如何在 Claude 应用 gateway 和其他产品之间进行选择

209* [其他 LLM gateway](/zh-CN/llm-gateway)：如何推出您的组织运行的 gateway 以及它如何与 claude.ai 订阅交互

205* [为您的组织推出 LLM gateway](/zh-CN/llm-gateway-rollout)：使用此契约的管理员检查清单210* [为您的组织推出 LLM gateway](/zh-CN/llm-gateway-rollout)：使用此契约的管理员检查清单

206* [将 Claude Code 连接到 LLM gateway](/zh-CN/llm-gateway-connect)：每个开发者的配置和故障排除表211* [将 Claude Code 连接到 LLM gateway](/zh-CN/llm-gateway-connect)：每个开发者的配置和故障排除表

207* [Beta 请求头参考](https://platform.claude.com/docs/en/api/beta-headers)：当前的 `anthropic-beta` 值集212* [Beta 请求头参考](https://platform.claude.com/docs/en/api/beta-headers)：当前的 `anthropic-beta` 值集

llm-gateway-rollout.md +5 −5

Details

22* 在您的基础设施上部署的网关，在您将分发给开发者的确切地址上提供 HTTPS，而不是重定向到它的地址，并配置为将 Claude 模型名称路由到您的提供商22* 在您的基础设施上部署的网关，在您将分发给开发者的确切地址上提供 HTTPS，而不是重定向到它的地址，并配置为将 Claude 模型名称路由到您的提供商

23* 网关转发的提供商凭证：23* 网关转发的提供商凭证：

24 * 对于 Anthropic API：来自 [Claude 控制台](https://platform.claude.com/settings/keys)的 API 密钥24 * 对于 Anthropic API：来自 [Claude 控制台](https://platform.claude.com/settings/keys)的 API 密钥

25 * 对于云提供商：具有模型访问权限的云凭证。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock#prerequisites)、[Google Vertex AI](/zh-CN/google-vertex-ai#prerequisites) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry#prerequisites) 页面上的前置条件25 * 对于云提供商：具有模型访问权限的云凭证。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock#prerequisites)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai#prerequisites) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry#prerequisites) 页面上的前置条件

26* 一种向开发者机器交付设置文件的方式，例如 MDM 或配置管理26* 一种向开发者机器交付设置文件的方式，例如 MDM 或配置管理

27 * 如果您还没有，[设置如何到达设备](/zh-CN/admin-setup#decide-how-settings-reach-devices)比较了各种选项27 * 如果您还没有，[设置如何到达设备](/zh-CN/admin-setup#decide-how-settings-reach-devices)比较了各种选项

28 28

180无论您选择哪条路径，都适用相同的变量集。大多数推出只需要 `ANTHROPIC_BASE_URL` 和凭证；当您的网关设置需要时包括条件行。180无论您选择哪条路径，都适用相同的变量集。大多数推出只需要 `ANTHROPIC_BASE_URL` 和凭证；当您的网关设置需要时包括条件行。

181 181

183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

184| `ANTHROPIC_BASE_URL` | 将 Claude Code 的 API 请求发送到网关而不是 `api.anthropic.com` | 总是 |184| `ANTHROPIC_BASE_URL` | 将 Claude Code 的 API 请求发送到网关而不是 `api.anthropic.com` | 总是 |

189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config) | 设置 Claude Code 为主会话和后台流量请求的模型名称 | 您的网关路由与 Claude Code 默认值不匹配的模型名称，或您将[后台功能](/zh-CN/costs#background-token-usage)路由到不同的模型。在网关处路由覆盖名称和 Claude Code 的默认名称，因为某些子调用可以请求默认名称，无论覆盖如何 |189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config) | 设置 Claude Code 为主会话和后台流量请求的模型名称 | 您的网关路由与 Claude Code 默认值不匹配的模型名称，或您将[后台功能](/zh-CN/costs#background-token-usage)路由到不同的模型。在网关处路由覆盖名称和 Claude Code 的默认名称，因为某些子调用可以请求默认名称，无论覆盖如何；[模型配置](/zh-CN/model-config)涵盖了会话的每个部分使用哪个模型 |

190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[该提供商的变量](/zh-CN/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 通过网关将 Claude Code 指向网关。Bedrock 和 Vertex 也切换到这些提供商的本机请求格式 | 您的网关前置 Bedrock、Vertex、Foundry 或 AWS 上的 Claude 平台；请参阅 [API 格式](/zh-CN/llm-gateway-protocol#api-formats) |190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[该提供商的变量](/zh-CN/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 通过网关将 Claude Code 指向网关。Bedrock 和 Agent Platform 也切换到这些提供商的本机请求格式 | 您的网关前置 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude 平台；请参阅 [API 格式](/zh-CN/llm-gateway-protocol#api-formats) |

191 191

192<h4 id="distribute-through-managed-settings">192<h4 id="distribute-through-managed-settings">

193 通过托管设置分发193 通过托管设置分发

mcp.md +40 −14

Details

176 176

177来自 `.mcp.json` 的项目范围服务器如果等待您的批准，会在 `claude mcp list` 中显示为 `⏸ 待批准`。运行 `claude` 交互式命令来审查和批准它们。`claude mcp get <name>` 将待批准的服务器显示为 `⏸ 待批准`，将被拒绝的服务器显示为 `✗ 已拒绝`。177来自 `.mcp.json` 的项目范围服务器如果等待您的批准，会在 `claude mcp list` 中显示为 `⏸ 待批准`。运行 `claude` 交互式命令来审查和批准它们。`claude mcp get <name>` 将待批准的服务器显示为 `⏸ 待批准`，将被拒绝的服务器显示为 `✗ 已拒绝`。

178 178

179从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅从未检入存储库的设置文件中读取 `.mcp.json` 批准，直到您通过在其中运行 `claude` 并接受工作区信任对话框来信任工作区。克隆的存储库无法批准其自己的服务器：提交到项目的 `.claude/settings.json` 的 [`enableAllProjectMcpServers` 或 `enabledMcpjsonServers`](/zh-CN/settings#available-settings) 在不受信任的文件夹中被忽略，服务器保持在 `⏸ 待批准` 状态，而不是被连接和健康检查。

180

181这些来源的批准仍然适用于不受信任的文件夹：

182

183* 您的用户 `~/.claude/settings.json`

184* 托管设置

185* 使用 `--settings` 传递的设置

186* `.claude/settings.local.json`，只要 git 不跟踪它

187

188任何设置文件中的 `disabledMcpjsonServers` 条目仍然会拒绝该服务器。

189

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

180 191

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

208 提示：219 提示：

209 220

210 * 使用 `--scope` 标志指定配置的存储位置：221 * 使用 `--scope` 标志指定配置的存储位置：

211 * `local`（默认）：仅在当前项目中对您可用（在较旧版本中称为 `project`）222 * `local`（默认）：仅在当前项目中对您可用。较旧版本称此范围为 `project`

212 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享223 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享

213 * `user`：在所有项目中对您可用（在较旧版本中称为 `global`）224 * `user`：在所有项目中对您可用。较旧版本称此范围为 `global`

214 * 使用 `--env` 标志设置环境变量（例如，`--env KEY=value`）225 * 使用 `--env` 标志设置环境变量（例如，`--env KEY=value`）

215 * 使用 MCP\_TIMEOUT 环境变量配置 MCP 服务器启动超时（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒超时）226 * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒超时）

216 * 通过向该服务器的 `.mcp.json` 条目添加 `timeout` 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量227 * 通过向该服务器的 `.mcp.json` 条目添加 `timeout` 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量

217 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如，`MAX_MCP_OUTPUT_TOKENS=50000`）228 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如，`MAX_MCP_OUTPUT_TOKENS=50000`）

218 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证229 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

233* 插件在插件根目录的 `.mcp.json` 中或在 `plugin.json` 中内联定义 MCP 服务器244* 插件在插件根目录的 `.mcp.json` 中或在 `plugin.json` 中内联定义 MCP 服务器

234* 启用插件时，其 MCP 服务器会自动启动245* 启用插件时，其 MCP 服务器会自动启动

235* 插件 MCP 工具与手动配置的 MCP 工具一起出现246* 插件 MCP 工具与手动配置的 MCP 工具一起出现

236* 插件服务器通过插件安装进行管理（不是 `/mcp` 命令）247* 插件服务器通过插件安装进行管理，不是 `/mcp` 命令

237 248

238**示例插件 MCP 配置**：249**示例插件 MCP 配置**：

239 250

272* **自动生命周期**：在会话启动时，启用的插件的服务器会自动连接。如果您在会话期间启用或禁用插件，请运行 `/reload-plugins` 以连接或断开其 MCP 服务器283* **自动生命周期**：在会话启动时，启用的插件的服务器会自动连接。如果您在会话期间启用或禁用插件，请运行 `/reload-plugins` 以连接或断开其 MCP 服务器

273* **环境变量**：对捆绑的插件文件使用 `${CLAUDE_PLUGIN_ROOT}`，对[持久状态](/zh-CN/plugins-reference#persistent-data-directory)使用 `${CLAUDE_PLUGIN_DATA}`（在插件更新后仍然存在），以及对稳定项目根目录使用 `${CLAUDE_PROJECT_DIR}`284* **环境变量**：对捆绑的插件文件使用 `${CLAUDE_PLUGIN_ROOT}`，对[持久状态](/zh-CN/plugins-reference#persistent-data-directory)使用 `${CLAUDE_PLUGIN_DATA}`（在插件更新后仍然存在），以及对稳定项目根目录使用 `${CLAUDE_PROJECT_DIR}`

274* **用户环境访问**：访问与手动配置的服务器相同的环境变量285* **用户环境访问**：访问与手动配置的服务器相同的环境变量

275* **多种传输类型**：支持 stdio、SSE、HTTP 和 WebSocket 传输（传输支持可能因服务器而异）286* **多种传输类型**：支持 stdio、SSE、HTTP 和 WebSocket 传输，尽管传输支持可能因服务器而异

276 287

277**查看插件 MCP 服务器**：288**查看插件 MCP 服务器**：

278 289

524 535

525许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。536许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。

526 537

527当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时，Claude Code 将远程服务器标记为需要身份验证。任一状态代码都会在 `/mcp` 中标记该服务器，以便您可以完成 OAuth 流程。返回指向其授权服务器的 `WWW-Authenticate` 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。538当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时，Claude Code 将远程服务器标记为需要身份验证。任一状态代码都会在 `/mcp` 中标记该服务器，以便您可以完成 OAuth 流程。

539

540从 v2.1.195 开始，当令牌刷新失败，因为服务器拒绝了存储的刷新令牌时，Claude Code 会立即显示一个指向 `/mcp` 的通知。连接的服务器的菜单中提供了"重新身份验证"选项，因此您可以在下一个工具调用失败之前重新登录。

541

542返回指向其授权服务器的 `WWW-Authenticate` 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。

543

544从 v2.1.193 开始，当一个或多个配置的服务器需要身份验证时，Claude Code 也会在启动时显示通知，因此您无需打开 `/mcp` 来发现哪些服务器需要登录。

545

546在非交互模式下，没有 `/mcp` 面板，因此 Claude Code 无法为您运行 OAuth 流程。从 v2.1.196 开始，当配置的服务器在 `claude -p` 或启用了[工具搜索](#scale-with-mcp-tool-search)的 Agent SDK 运行期间需要身份验证时（这是默认设置），Claude Code 会告诉 Claude 该服务器的工具不可用，直到您授权它。Claude 可以命名需要登录的服务器，而不是响应就像服务器未配置一样。从与 `/mcp` 的交互式会话或 `claude mcp login <name>` 完成登录。

528 547

529如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。548如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。

530 549

710 729

711`oauth.scopes` 优先于 `authServerMetadataUrl` 和服务器在 `/.well-known` 发现的范围。将其保留未设置以让 MCP 服务器确定请求的范围集。730`oauth.scopes` 优先于 `authServerMetadataUrl` 和服务器在 `/.well-known` 发现的范围。将其保留未设置以让 MCP 服务器确定请求的范围集。

712 731

732从 v2.1.196 开始，当未设置 `oauth.scopes` 时，Claude Code 请求服务器的 `WWW-Authenticate` 标头或其受保护资源元数据提供的范围，当两者都未提供时不发送 `scope` 参数。它不再从自动发现的授权服务器元数据请求完整的 `scopes_supported` 目录。请求该目录导致公开仅限管理员或模板范围的身份提供者拒绝授权请求，出现 `invalid_scope` 错误。从配置的 `authServerMetadataUrl` 获取的元数据仍然将其 `scopes_supported` 作为请求的范围提供。

733

713如果授权服务器在 `scopes_supported` 中公开 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。734如果授权服务器在 `scopes_supported` 中公开 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。

714 735

715如果服务器稍后为工具调用返回 403 `insufficient_scope`，Claude Code 会使用相同的固定范围重新进行身份验证。当您需要的工具需要固定范围之外的范围时，扩展 `oauth.scopes`。736如果服务器稍后为工具调用返回 403 `insufficient_scope`，Claude Code 会使用相同的固定范围重新进行身份验证。当您需要的工具需要固定范围之外的范围时，扩展 `oauth.scopes`。

754 775

755助手在每次连接时运行（在会话启动和重新连接时）。没有缓存，因此您的脚本负责任何令牌重用。776助手在每次连接时运行（在会话启动和重新连接时）。没有缓存，因此您的脚本负责任何令牌重用。

756 777

778从 v2.1.193 开始，如果工具调用返回 `401 Unauthorized` 或 `403 Forbidden`，Claude Code 会自动重新运行助手，使用新标头重新连接，并重试调用一次。只有在该重试也失败时，Claude Code 才会在 `/mcp` 中将服务器标记为需要身份验证。

779

757Claude Code 在执行助手时设置这些环境变量：780Claude Code 在执行助手时设置这些环境变量：

758 781

759| 变量 | 值 |782| 变量 | 值 |

760| :---------------------------- | :----------- |783| :---------------------------- | :---------------------------------------------------------- |

786| `CLAUDE_PLUGIN_ROOT` | 插件的根目录。仅当[插件](/zh-CN/plugins-reference#mcp-servers)提供服务器时设置 |

763 787

764使用这些来编写一个为多个 MCP 服务器服务的单个助手脚本。788使用这些来编写一个为多个 MCP 服务器服务的单个助手脚本。

765 789

790对于插件提供的服务器，助手也会在其工作目录设置为插件根目录的情况下运行，因此相对 `headersHelper` 路径在插件目录内解析，而不是针对会话的工作目录。需要 Claude Code v2.1.195 或更高版本。

791

766<Note>792<Note>

767 `headersHelper` 执行任意 shell 命令。在项目或本地范围定义时，它仅在您接受工作区信任对话框后运行。793 `headersHelper` 执行任意 shell 命令。在项目或本地范围定义时，它仅在您接受工作区信任对话框后运行。

768</Note>794</Note>

841</Tip>867</Tip>

842 868

843<h2 id="use-mcp-servers-from-claude-ai">869<h2 id="use-mcp-servers-from-claude-ai">

844 使用来自 Claude.ai 的 MCP 服务器870 使用来自 claude.ai 的 MCP 服务器

845</h2>871</h2>

846 872

847如果您已使用 [Claude.ai](https://claude.ai) 帐户登录 Claude Code，您在 Claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：873如果您已使用 [claude.ai](https://claude.ai) 帐户登录 Claude Code，您在 claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：

848 874

849<Steps>875<Steps>

850 <Step title="在 Claude.ai 中配置 MCP 服务器">876 <Step title="在 claude.ai 中配置 MCP 服务器">

851 在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加服务器。在 Team 和 Enterprise 计划上，仅管理员可以添加服务器。877 在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加服务器。在 Team 和 Enterprise 计划上，仅管理员可以添加服务器。

852 </Step>878 </Step>

853 879

854 <Step title="对 MCP 服务器进行身份验证">880 <Step title="对 MCP 服务器进行身份验证">

855 在 Claude.ai 中完成任何必需的身份验证步骤。881 在 claude.ai 中完成任何必需的身份验证步骤。

856 </Step>882 </Step>

857 883

858 <Step title="在 Claude Code 中查看和管理服务器">884 <Step title="在 Claude Code 中查看和管理服务器">

862 /mcp888 /mcp

863 ```889 ```

864 890

865 Claude.ai 服务器在列表中出现，并带有指示它们来自 Claude.ai 的指示符。891 claude.ai 服务器在列表中出现，并带有指示它们来自 claude.ai 的指示符。

866 </Step>892 </Step>

867</Steps>893</Steps>

868 894

958 984

959 * 服务器提供对 Claude 的工具（如 View、Edit、LS 等）的访问权限。985 * 服务器提供对 Claude 的工具（如 View、Edit、LS 等）的访问权限。

960 * 在 Claude Desktop 中，尝试要求 Claude 读取目录中的文件、进行编辑等。986 * 在 Claude Desktop 中，尝试要求 Claude 读取目录中的文件、进行编辑等。

961 * 请注意，此 MCP 服务器仅向您的 MCP 客户端公开 Claude Code 的工具，因此您自己的客户端负责为单个工具调用实现用户确认。987 * 此 MCP 服务器仅向您的 MCP 客户端公开 Claude Code 的工具，因此您自己的客户端负责为单个工具调用实现用户确认。

962</Tip>988</Tip>

963 989

964<h2 id="mcp-output-limits-and-warnings">990<h2 id="mcp-output-limits-and-warnings">

1199 * MCP 提示从连接的服务器动态发现1225 * MCP 提示从连接的服务器动态发现

1200 * 参数根据提示的定义参数进行解析1226 * 参数根据提示的定义参数进行解析

1201 * 提示结果直接注入到对话中1227 * 提示结果直接注入到对话中

1202 * 服务器和提示名称被规范化（空格变为下划线）1228 * 服务器和提示名称被规范化，空格转换为下划线

1203</Tip>1229</Tip>

1204 1230

1205<h2 id="managed-mcp-configuration">1231<h2 id="managed-mcp-configuration">

microsoft-foundry.md +1 −1

Details

171 171

172```bash theme={null}172```bash theme={null}

173export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'173export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

174export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'174export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'

175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

176```176```

177 177

model-config.md +42 −31

Details

30模型别名提供了一种便捷的方式来选择模型设置，无需记住确切的版本号：30模型别名提供了一种便捷的方式来选择模型设置，无需记住确切的版本号：

31 31

32| 模型别名 | 行为 |32| 模型别名 | 行为 |

~~33| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |~~33| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

~~40| **`sonnet[1m]`** | 使用 Sonnet 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话 |~~40| **`sonnet[1m]`** | 使用 Sonnet 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话。当 `sonnet` 已解析为具有原生 1M 窗口的 Sonnet 5 时无效；在 [LLM 网关](/zh-CN/llm-gateway)后面，为 Sonnet 5 选择 1M 窗口 |

41| **`opus[1m]`** | 使用 Opus 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话 |41| **`opus[1m]`** | 使用 Opus 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话 |

43 43

44在 Anthropic API 上，`opus` 解析为 Opus 4.8，`sonnet` 解析为 Sonnet 4.6。在 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 上，`opus` 解析为 Opus 4.7，`sonnet` 解析为 Sonnet 4.6。在 Bedrock、Vertex 和 Foundry 上，`opus` 解析为 Opus 4.6，`sonnet` 解析为 Sonnet 4.5；通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 可以在这些提供商上获得更新的模型。44在 Anthropic API 上，`opus` 解析为 Opus 4.8，`sonnet` 解析为 Sonnet 5。在 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 上，`opus` 解析为 Opus 4.7，`sonnet` 解析为 Sonnet 4.6。在 Bedrock、Vertex 和 Foundry 上，`opus` 解析为 Opus 4.6，`sonnet` 解析为 Sonnet 4.5；通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 可以在这些提供商上获得更新的模型。

45 45

46别名指向您的提供商推荐的版本，并随时间更新。要固定到特定版本，请使用完整模型名称（例如 `claude-opus-4-8`）或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。46别名指向您的提供商推荐的版本，并随时间更新。要固定到特定版本，请使用完整模型名称（例如 `claude-opus-4-8`）或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

47 47

48<Note>48<Note>

~~49 Opus 4.8 需要 Claude Code v2.1.154 或更高版本。运行 `claude update` 进行升级。~~49 Sonnet 5 需要 Claude Code v2.1.197 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。运行 `claude update` 进行升级。

50</Note>50</Note>

51 51

52<h3 id="work-with-fable-5">52<h3 id="work-with-fable-5">

74 74

75您可以通过多种方式配置模型，按优先级顺序列出：75您可以通过多种方式配置模型，按优先级顺序列出：

76 76

771. **在会话期间** - 使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。当对话有先前的输出时，选择器会要求确认，因为下一个响应会重新读取完整历史记录而不使用缓存的上下文771. **在会话期间**：使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。当对话有先前的输出时，选择器会要求确认，因为下一个响应会重新读取完整历史记录而不使用缓存的上下文

~~782. **启动时** - 使用 `claude --model <alias|name>` 启动~~782. **启动时**：使用 `claude --model <alias|name>` 启动

~~793. **环境变量** - 设置 `ANTHROPIC_MODEL=<alias|name>`~~793. **环境变量**：设置 `ANTHROPIC_MODEL=<alias|name>`

~~804. **设置** - 在设置文件中使用 `model` 字段永久配置。~~804. **设置**：在设置文件中使用 `model` 字段永久配置

81 81

82从 v2.1.153 开始，`/model` 通过在用户设置中写入 `model` 字段来将您的选择保存为新会话的默认值。在选择器中：82从 v2.1.153 开始，`/model` 通过在用户设置中写入 `model` 字段来将您的选择保存为新会话的默认值。在选择器中：

83 83

165 默认模型行为165 默认模型行为

166</h3>166</h3>

167 167

168模型选择器中的"默认"选项不受 `availableModels` 影响，除非也设置了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。单独使用 `availableModels` 会保持"默认"可用，解析为系统的运行时默认值[基于用户的订阅层级](#default-model-setting)。如果层级默认值是您打算限制的模型，也设置 `enforceAvailableModels`。168模型选择器中的"默认"选项不受 `availableModels` 影响，除非也设置了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。单独使用 `availableModels` 会保持"默认"可用，解析为系统的[运行时默认](#default-model-setting)。如果该默认值是您打算限制的模型，也设置 `enforceAvailableModels`。

169 169

170空的 `availableModels` 数组永远不会启用"默认"模型强制执行：使用 `availableModels: []`，命名的模型选择被阻止，但帐户类型的默认模型无论 `enforceAvailableModels` 如何设置都保持可用。170空的 `availableModels` 数组永远不会启用"默认"模型强制执行：使用 `availableModels: []`，命名的模型选择被阻止，但帐户类型的默认模型无论 `enforceAvailableModels` 如何设置都保持可用。

171 171

192 控制用户运行的模型192 控制用户运行的模型

193</h3>193</h3>

194 194

195`model` 设置是初始选择，而不是强制执行。它设置会话启动时哪个模型处于活跃状态，但用户仍然可以打开 `/model` 并选择"默认"，这会解析为其层级的系统默认值，无论 `model` 设置为什么，除非 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 重定向它。195`model` 设置是初始选择，而不是强制执行。它设置会话启动时哪个模型处于活跃状态，但用户仍然可以打开 `/model` 并选择"默认"，这会解析为系统的[运行时默认](#default-model-setting)，无论 `model` 设置为什么，除非 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 重定向它。

196 196

197要完全控制模型体验，请结合这些设置：197要完全控制模型体验，请结合这些设置：

198 198

201* **`model`**：设置会话启动时的初始模型选择201* **`model`**：设置会话启动时的初始模型选择

202* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**：控制"默认"选项和 `sonnet`、`opus`、`haiku` 和 `fable` 别名解析为什么202* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**：控制"默认"选项和 `sonnet`、`opus`、`haiku` 和 `fable` 别名解析为什么

203 203

204此示例在 Sonnet 4.5 上启动用户，将选择器限制为 Sonnet 和 Haiku，并确保"默认"解析为允许列表上的模型，而不是层级默认值：204此示例在 Sonnet 4.5 上启动用户，将选择器限制为 Sonnet 和 Haiku，并确保"默认"解析为允许列表上的模型，而不是系统默认值：

205 205

206```json theme={null}206```json theme={null}

207{207{

234 组织模型限制234 组织模型限制

235</h3>235</h3>

236 236

237当您的成员通过 Anthropic API 进行身份验证，并且您想要一个组织范围的开关而不部署设置文件时，使用控制台切换而不是 `availableModels`。组织管理员通过在 Claude 控制台中禁用单个模型来限制成员可以运行的模型。当 Claude Code 进行身份验证时，此限制与帐户的权利一起交付，与设置中的任何 `availableModels` 列表分开，服务器在创建会话时独立强制执行相同的限制。需要 Claude Code v2.1.187 或更高版本。237组织管理员通过在 Claude 控制台中禁用单个模型来限制成员可以运行的模型。当您的成员通过 Anthropic API 进行身份验证，并且您想要一个组织范围的开关而不部署设置文件时，使用此控制台切换而不是 `availableModels`。此限制与帐户的权利一起交付，当 Claude Code 进行身份验证时，与设置中的任何 `availableModels` 列表分开，服务器在创建会话时独立强制执行相同的限制。需要 Claude Code v2.1.187 或更高版本。

238 238

239受限制的模型在 `/model` 选择器中被隐藏。使用 `--model`、`ANTHROPIC_MODEL` 环境变量或 `model` 设置按名称选择它会显示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，会话在允许的模型上启动。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，会话保持其当前模型。239受限制的模型在 `/model` 选择器中被隐藏。使用 `--model`、`ANTHROPIC_MODEL` 环境变量或 `model` 设置按名称选择它会显示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，会话在允许的模型上启动。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，会话保持其当前模型。

240 240

252 252

253* **Max、Team Premium、Enterprise 按使用量付费和 Anthropic API**：默认为 Opus 4.8253* **Max、Team Premium、Enterprise 按使用量付费和 Anthropic API**：默认为 Opus 4.8

254* **AWS 上的 Claude Platform**：默认为 Opus 4.7254* **AWS 上的 Claude Platform**：默认为 Opus 4.7

255* **Pro、Team Standard 和 Enterprise 订阅席位**：默认为 Sonnet 4.6255* **Pro、Team Standard 和 Enterprise 订阅席位**：默认为 Sonnet 5

256* **Bedrock、Vertex 和 Foundry**：默认为 Sonnet 4.5256* **Bedrock、Vertex 和 Foundry**：默认为 Sonnet 4.5

257 257

258Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。258Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。

267 267

268`opusplan` 模型别名提供了一种自动化的混合方法：268`opusplan` 模型别名提供了一种自动化的混合方法：

269 269

270* **在 Plan Mode 中** - 使用 `opus` 进行复杂推理和架构决策270* **在 Plan Mode 中**：使用 `opus` 进行复杂推理和架构决策

271* **在执行模式中** - 自动切换到 `sonnet` 进行代码生成和实现271* **在执行模式中**：自动切换到 `sonnet` 进行代码生成和实现

272 272

273这为您提供了两全其美的方案：Opus 的卓越推理能力用于规划，Sonnet 的效率用于执行。273这为您提供了两全其美的方案：Opus 的卓越推理能力用于规划，Sonnet 的效率用于执行。

274 274

296 296

297```json theme={null}297```json theme={null}

298{298{

299 "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]299 "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]

300}300}

301```301```

302 302

368可用的工作量级别取决于模型。此处未列出的模型不支持工作量：368可用的工作量级别取决于模型。此处未列出的模型不支持工作量：

369 369

370| 模型 | 级别 |370| 模型 | 级别 |

371| :-------------------- | :---------------------------------- |371| :--------------------------- | :---------------------------------- |

375 375

376如果您设置活跃模型不支持的级别，Claude Code 会回退到您设置的级别或以下的最高支持级别。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。376如果您设置活跃模型不支持的级别，Claude Code 会回退到您设置的级别或以下的最高支持级别。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。

377 377

378Fable 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的默认工作量是 `high`，Opus 4.7 上的默认工作量是 `xhigh`。378Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的默认工作量是 `high`，Opus 4.7 上的默认工作量是 `xhigh`。

379 379

380当您首次运行 Fable 5、Opus 4.8 或 Opus 4.7 时，Claude Code 会应用该模型的默认工作量，即使您之前为另一个模型设置了不同的级别：Fable 5 和 Opus 4.8 上的 `high`，Opus 4.7 上的 `xhigh`。切换后再次运行 `/effort` 以选择不同的级别。380当您首次运行 Fable 5、Opus 4.8 或 Opus 4.7 时，Claude Code 会应用该模型的默认工作量，即使您之前为另一个模型设置了不同的级别：Fable 5 和 Opus 4.8 上的 `high`，Opus 4.7 上的 `xhigh`。切换后再次运行 `/effort` 以选择不同的级别。

381 381

393| :---------- | :----------------------------------------------------------------------------- |393| :---------- | :----------------------------------------------------------------------------- |

394| `low` | 保留用于短期、范围有限、延迟敏感且不需要高智能的任务 |394| `low` | 保留用于短期、范围有限、延迟敏感且不需要高智能的任务 |

398| `max` | 可以改进困难任务的性能，但可能显示收益递减，容易过度思考。在广泛采用前进行测试 |398| `max` | 可以改进困难任务的性能，但可能显示收益递减，容易过度思考。在广泛采用前进行测试 |

429 429

430自适应推理使思考在每一步都是可选的，因此 Claude 可以更快地响应常规提示，并为受益于思考的步骤保留更深入的思考。如果您希望 Claude 比当前级别产生的思考更多或更少，您可以直接在您的提示或 `CLAUDE.md` 中说明；模型会在其工作量设置范围内响应该指导。430自适应推理使思考在每一步都是可选的，因此 Claude 可以更快地响应常规提示，并为受益于思考的步骤保留更深入的思考。如果您希望 Claude 比当前级别产生的思考更多或更少，您可以直接在您的提示或 `CLAUDE.md` 中说明；模型会在其工作量设置范围内响应该指导。

431 431

432Opus 4.7 及更高版本始终使用自适应推理，Fable 5 也是如此。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。432Fable 5、Sonnet 5 和 Opus 4.7 及更高版本始终使用自适应推理。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。

433 433

434在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/zh-CN/env-vars)。434在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/zh-CN/env-vars)。

435 435

453 扩展上下文453 扩展上下文

454</h3>454</h3>

455 455

456Fable 5、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于包含大型代码库的长会话。456Fable 5、Sonnet 5、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于包含大型代码库的长会话。

457 457

458可用性因模型和计划而异。在 Max、Team 和 Enterprise 计划上，Opus 会自动升级到 1M 上下文，无需额外配置。这适用于 Team Standard 和 Team Premium 席位。在 Anthropic API 上，Fable 5、Opus 4.8 和 Opus 4.7 始终使用 1M 窗口运行。Sonnet with 1M context 不是自动升级的一部分，需要在每个订阅计划上[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。458可用性因模型和计划而异。在 Anthropic API 上，Fable 5、Sonnet 5、Opus 4.8 和 Opus 4.7 始终使用 1M 窗口运行。在 Max、Team 和 Enterprise 计划上，Opus 会自动升级到 1M 上下文，无需额外配置。这适用于 Team Standard 和 Team Premium 席位。Sonnet 4.6 with 1M context 不是自动升级的一部分，需要在每个订阅计划上[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。

459 459

460| 计划 | Opus with 1M context | Sonnet with 1M context |460| 计划 | Opus with 1M context | Sonnet 4.6 with 1M context |

461| --------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |461| --------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |

463| Pro | 需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | 需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |463| Pro | 需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | 需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

480/model claude-opus-4-8[1m]480/model claude-opus-4-8[1m]

481```481```

482 482

483<h4 id="sonnet-5-context-window">

484 Sonnet 5 上下文窗口

485</h4>

486

487在 Anthropic API 上，Sonnet 5 始终使用 1M 上下文窗口运行。没有 200K 变体，没有可供选择的 `[1m]` 后缀，任何计划都不需要使用额度。会话在窗口填满前自动压缩，默认约为 967K 令牌；设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-CN/env-vars) 以选择不同的阈值。

488

489两种配置会改为将窗口预算设为 200K，并在该边界自动压缩：

490

491* **LLM 网关**：当 `ANTHROPIC_BASE_URL` 指向[网关](/zh-CN/llm-gateway)时，Claude Code 无法验证 1M 支持。要使用完整窗口，请在模型选择器中选择 Sonnet 5 (1M context)，它映射到 `sonnet[1m]`。

492* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将 Sonnet 5 会话视为具有 200K 窗口，适用于需要限制上下文的部署。

493

483<h2 id="checking-your-current-model">494<h2 id="checking-your-current-model">

484 检查您当前的模型495 检查您当前的模型

485</h2>496</h2>

486 497

487您可以通过多种方式查看您当前使用的模型：498您可以在两个位置查看您当前使用的模型：

488 499

4891. 在[状态行](/zh-CN/statusline)中（如果已配置）500* 在[状态行](/zh-CN/statusline)中（如果已配置）

4902. 在 `/status` 中，它也显示您的账户信息。501* 在 `/status` 中，它也显示您的账户信息

491 502

492<h2 id="add-a-custom-model-option">503<h2 id="add-a-custom-model-option">

493 添加自定义模型选项504 添加自定义模型选项

498此示例设置所有三个变量以使网关路由的 Opus 部署可选择：509此示例设置所有三个变量以使网关路由的 Opus 部署可选择：

499 510

500```bash theme={null}511```bash theme={null}

501export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-7"512export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-8"

502export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"513export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"

503export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"514export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

504```515```

505 516

506自定义条目出现在 `/model` 选择器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可选的。如果省略，模型 ID 用作名称，描述默认为 `Custom model (<model-id>)`。517自定义条目出现在 `/model` 选择器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可选的。如果省略，模型 ID 用作名称，描述默认为 `Custom model (<model-id>)`。

507 518

508Claude Code 跳过对 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中设置的模型 ID 的验证，因此您可以使用您的 API 端点接受的任何字符串。当设置 [`availableModels`](#restrict-model-selection) 时，也要在允许列表中包含自定义模型 ID：自定义条目会从选择器中被过滤，对其进行 `--model` 选择会被拒绝，就像任何其他被排除的模型一样。嵌入了系列名称的自定义 ID（例如 `my-gateway/claude-opus-4-7`）计为该系列的特定条目并禁用其通配符，因此还要列出您打算保持可选择的版本。请参阅 [合并行为](#merge-behavior)。519Claude Code 跳过对 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中设置的模型 ID 的验证，因此您可以使用您的 API 端点接受的任何字符串。当设置 [`availableModels`](#restrict-model-selection) 时，也要在允许列表中包含自定义模型 ID：自定义条目会从选择器中被过滤，对其进行 `--model` 选择会被拒绝，就像任何其他被排除的模型一样。嵌入了系列名称的自定义 ID（例如 `my-gateway/claude-opus-4-8`）计为该系列的特定条目并禁用其通配符，因此还要列出您打算保持可选择的版本。请参阅 [合并行为](#merge-behavior)。

509 520

510<h2 id="environment-variables">521<h2 id="environment-variables">

511 环境变量522 环境变量

512</h2>523</h2>

513 524

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

515 526

516| 环境变量 | 描述 |527| 环境变量 | 描述 |

517| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |528| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

555 566

556* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。567* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。

557* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)时才附加 `[1m]`。568* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)时才附加 `[1m]`。

558* 该后缀按变量读取，而不是按模型读取。在 Bedrock、Vertex 和 Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。569* 该后缀按变量读取，而不是按模型读取。在 Bedrock、Vertex 和 Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。Sonnet 5 在这些提供商上始终以 1M 窗口运行，从不需要该后缀。

559 570

560<Note>571<Note>

561 使用第三方提供商时，通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files) 提供的 `availableModels` 允许列表仍然适用；[服务器托管设置不会在那里提供](/zh-CN/server-managed-settings#platform-availability)。过滤与模型别名（如 `opus`）、版本前缀（如 `claude-opus-4-8`）或完整提供商形式的模型 ID 匹配。提供商特定的前缀（如 `us.anthropic.`）不会被删除，因此要允许特定模型，请列出选择器显示的相同提供商形式 ID，或通过 [`modelOverrides`](#override-model-ids-per-version) 映射它。任何 `[1m]` 后缀在匹配前都会从允许列表条目和请求的模型中删除。572 使用第三方提供商时，通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files) 提供的 `availableModels` 允许列表仍然适用；[服务器托管设置不会在那里提供](/zh-CN/server-managed-settings#platform-availability)。过滤与模型别名（如 `opus`）、版本前缀（如 `claude-opus-4-8`）或完整提供商形式的模型 ID 匹配。提供商特定的前缀（如 `us.anthropic.`）不会被删除，因此要允许特定模型，请列出选择器显示的相同提供商形式 ID，或通过 [`modelOverrides`](#override-model-ids-per-version) 映射它。任何 `[1m]` 后缀在匹配前都会从允许列表条目和请求的模型中删除。

monitoring-usage.md +41 −20

Details

93| `OTEL_METRIC_EXPORT_INTERVAL` | 导出间隔（毫秒）（默认：60000） | `5000`、`60000` |93| `OTEL_METRIC_EXPORT_INTERVAL` | 导出间隔（毫秒）（默认：60000） | `5000`、`60000` |

94| `OTEL_LOGS_EXPORT_INTERVAL` | 日志导出间隔（毫秒）（默认：5000） | `1000`、`10000` |94| `OTEL_LOGS_EXPORT_INTERVAL` | 日志导出间隔（毫秒）（默认：5000） | `1000`、`10000` |

95| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认：禁用） | `1` 启用 |95| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认：禁用） | `1` 启用 |

96| `OTEL_LOG_ASSISTANT_RESPONSES` | 启用在 `assistant_response` 事件上记录助手响应文本（默认：禁用）。未设置时，回退到 `OTEL_LOG_USER_PROMPTS` 的值。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更高版本 | `1` 启用，`0` 保持编辑 |

96| `OTEL_LOG_TOOL_DETAILS` | 启用在工具事件和 trace span 属性中记录工具参数和输入参数：Bash 命令、MCP 服务器和工具名称、技能名称和工具输入。还在 `user_prompt` 事件上启用自定义、插件和 MCP 命令名称（默认：禁用） | `1` 启用 |97| `OTEL_LOG_TOOL_DETAILS` | 启用在工具事件和 trace span 属性中记录工具参数和输入参数：Bash 命令、MCP 服务器和工具名称、技能名称和工具输入。还在 `user_prompt` 事件上启用自定义、插件和 MCP 命令名称（默认：禁用） | `1` 启用 |

97| `OTEL_LOG_TOOL_CONTENT` | 启用在 span 事件中记录工具输入和输出内容（默认：禁用）。需要 [tracing](#traces-beta)。内容在 60 KB 处截断 | `1` 启用 |98| `OTEL_LOG_TOOL_CONTENT` | 启用在 span 事件中记录工具输入和输出内容（默认：禁用）。需要 [tracing](#traces-beta)。内容在 60 KB 处截断 | `1` 启用 |

98| `OTEL_LOG_RAW_API_BODIES` | 将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出（默认：禁用）。主体包括整个对话历史。启用此选项意味着同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 会揭示的所有内容 | `1` 用于在 60 KB 处截断的内联主体，或 `file:<dir>` 用于磁盘上的未截断主体，事件中带有 `body_ref` 指针 |99| `OTEL_LOG_RAW_API_BODIES` | 将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出（默认：禁用）。主体包括整个对话历史。启用此选项意味着同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 会揭示的所有内容 | `1` 用于在 60 KB 处截断的内联主体，或 `file:<dir>` 用于磁盘上的未截断主体，事件中带有 `body_ref` 指针 |

341每个自定义键都成为每个指标系列上的标签，因此高基数值会增加指标后端中的存储成本。要仅在资源块中发送自定义属性并从数据点标签中省略它们，请设置 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。请参阅 [指标基数控制](#metrics-cardinality-control)。342每个自定义键都成为每个指标系列上的标签，因此高基数值会增加指标后端中的存储成本。要仅在资源块中发送自定义属性并从数据点标签中省略它们，请设置 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。请参阅 [指标基数控制](#metrics-cardinality-control)。

342 343

343<Warning>344<Warning>

344 **OTEL\_RESOURCE\_ATTRIBUTES 的重要格式要求：**

~~345~~

346 `OTEL_RESOURCE_ATTRIBUTES` 环境变量使用逗号分隔的键=值对，具有严格的格式要求：345 `OTEL_RESOURCE_ATTRIBUTES` 环境变量使用逗号分隔的键=值对，具有严格的格式要求：

347 346

348 * **不允许空格**：值不能包含空格。例如，`user.organizationName=My Company` 无效347 * **不允许空格**：值不能包含空格。例如，`user.organizationName=My Company` 无效

350 * **允许的字符**：仅 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠349 * **允许的字符**：仅 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠

351 * **特殊字符**：超出允许范围的字符必须进行百分比编码350 * **特殊字符**：超出允许范围的字符必须进行百分比编码

352 351

353 **示例：**352 对于需要空格的值，请改用下划线或驼峰式大小写。以下示例以每种形式设置 `org.name`：

354 353

355 ```bash theme={null}354 ```bash theme={null}

356 # ❌ 无效 - 包含空格

357 export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

~~358~~

359 # ✅ 有效 - 改用下划线或驼峰式大小写

360 export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"355 export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"

361 export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"356 export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

357 ```

362 358

363 # ✅ 有效 - 如果需要，对特殊字符进行百分比编码359 您可以对任何字符进行百分比编码，不仅仅是被排除的字符。此示例对空格和撇号进行编码：

360

361 ```bash theme={null}

364 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"362 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

365 ```363 ```

366 364

367 注意：用引号包装值不会转义空格。例如，`org.name="My Company"` 会导致字面值 `"My Company"`（包括引号），而不是 `My Company`。365 用引号包装值不会转义空格。例如，`org.name="My Company"` 会导致字面值 `"My Company"`（包括引号），而不是 `My Company`。

368</Warning>366</Warning>

369 367

370<h3 id="example-configurations">368<h3 id="example-configurations">

440| `OTEL_RESOURCE_ATTRIBUTES` 中的键 | 您设置的自定义属性，例如 `department` 或 `team.id`。请参阅 [多团队组织支持](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（默认：true） |438| `OTEL_RESOURCE_ATTRIBUTES` 中的键 | 您设置的自定义属性，例如 `department` 或 `team.id`。请参阅 [多团队组织支持](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（默认：true） |

441 439

440当 Claude Code 登录到 [Claude apps gateway](/zh-CN/claude-apps-gateway) 时，CLI 会使用来自网关会话的已认证身份标记导出：`user.id` 是 IdP 主体而不是匿名安装标识符，`user.email` 是已登录的电子邮件，`user.groups` 作为逗号分隔的字符串携带 IdP 组成员身份。每个导出还携带 `identity.source: gateway-oidc`。网关身份最后应用，因此通过 `OTEL_RESOURCE_ATTRIBUTES` 设置的 `user.*` 和 `identity.*` 键在网关会话上被忽略。

441

442事件另外包含以下属性。这些永远不会附加到指标，因为它们会导致无限基数：442事件另外包含以下属性。这些永远不会附加到指标，因为它们会导致无限基数：

443 443

444* `prompt.id`：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 [事件关联属性](#event-correlation-attributes)。444* `prompt.id`：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 [事件关联属性](#event-correlation-attributes)。

488 488

489* 所有 [标准属性](#standard-attributes)489* 所有 [标准属性](#standard-attributes)

490* `type`：（`"added"`、`"removed"`）490* `type`：（`"added"`、`"removed"`）

491* `model`：进行更改的模型的模型标识符（例如，"claude-sonnet-4-6"）。{/* min-version: 2.1.172 */}需要 Claude Code v2.1.172 或更高版本491* `model`：进行更改的模型的模型标识符（例如，"claude-sonnet-5"）

492 492

493<h4 id="pull-request-counter">493<h4 id="pull-request-counter">

494 拉取请求计数器494 拉取请求计数器

519**属性**：519**属性**：

520 520

521* 所有 [标准属性](#standard-attributes)521* 所有 [标准属性](#standard-attributes)

522* `model`：模型标识符（例如，"claude-sonnet-4-6"）522* `model`：模型标识符（例如，"claude-sonnet-5"）

523* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一523* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

524* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在524* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

525* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。525* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。

540 540

541* 所有 [标准属性](#standard-attributes)541* 所有 [标准属性](#standard-attributes)

542* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）542* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）

543* `model`：模型标识符（例如，"claude-sonnet-4-6"）543* `model`：模型标识符（例如，"claude-sonnet-5"）

544* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一544* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

545* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在545* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

546* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅 [成本计数器](#cost-counter)。546* `effort`：应用于请求的 [努力级别](/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅 [成本计数器](#cost-counter)。

608* `event.timestamp`：ISO 8601 时间戳608* `event.timestamp`：ISO 8601 时间戳

609* `event.sequence`：单调递增的计数器，用于在会话内排序事件609* `event.sequence`：单调递增的计数器，用于在会话内排序事件

610* `prompt_length`：提示的长度610* `prompt_length`：提示的长度

611* `prompt`：提示内容（默认为已编辑，使用 `OTEL_LOG_USER_PROMPTS=1` 启用）611* `prompt`：提示内容。默认为已编辑。设置 `OTEL_LOG_USER_PROMPTS=1` 以包含它

612* `command_name`：当提示调用命令时的命令名称。内置和捆绑的命令名称（例如 `compact` 或 `debug`）按原样发出；别名（例如 `reset`）按输入方式发出而不是规范名称。自定义、插件和 MCP 命令名称折叠为 `custom` 或 `mcp`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`612* `command_name`：当提示调用命令时的命令名称。内置和捆绑的命令名称（例如 `compact` 或 `debug`）按原样发出；别名（例如 `reset`）按输入方式发出而不是规范名称。自定义、插件和 MCP 命令名称折叠为 `custom` 或 `mcp`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`

613* `command_source`：命令存在时的来源：`builtin`、`custom` 或 `mcp`。插件提供的命令报告为 `custom`613* `command_source`：命令存在时的来源：`builtin`、`custom` 或 `mcp`。插件提供的命令报告为 `custom`

614 614

615<h4 id="assistant-response-event">

616 助手响应事件

617</h4>

618

619在每个返回来自模型的文本内容的 API 请求后记录。仅包含响应的文本块；思考块和工具使用块被排除。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更高版本。

620

621**事件名称**：`claude_code.assistant_response`

622

623**属性**：

624

625* 所有 [标准属性](#standard-attributes)

626* `event.name`：`"assistant_response"`

627* `event.timestamp`：ISO 8601 时间戳

628* `event.sequence`：单调递增的计数器，用于在会话内排序事件

629* `response_length`：响应文本的长度（字符数）

630* `response`：响应文本，在 60 KB 处截断。默认为 `<REDACTED>` 编辑。设置 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。当 `OTEL_LOG_ASSISTANT_RESPONSES` 未设置时，`OTEL_LOG_USER_PROMPTS` 控制它，因此设置 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在启用提示日志记录时保持响应编辑

631* `model`：模型标识符（例如，"claude-sonnet-4-6"）

632* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID。仅当 API 返回时存在

633* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称

634

615<h4 id="tool-result-event">635<h4 id="tool-result-event">

616 工具结果事件636 工具结果事件

617</h4>637</h4>

632* `duration_ms`：执行时间（毫秒）652* `duration_ms`：执行时间（毫秒）

633* `error_type`：工具失败时的错误类别字符串，例如 `"Error:ENOENT"` 或 `"ShellError"`653* `error_type`：工具失败时的错误类别字符串，例如 `"Error:ENOENT"` 或 `"ShellError"`

634* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：工具失败时的完整错误消息654* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：工具失败时的完整错误消息

635* `decision_type`：始终为 `"accept"`，因为此事件仅在工具运行后发出（拒绝的调用不会产生工具结果）655* `decision_type`：始终为 `"accept"`，因为此事件仅在工具运行后发出。拒绝的调用不会产生工具结果

636* `decision_source`：权限决策来源。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。请参阅 [工具决策事件](#tool-decision-event) 了解每个值的含义。仅拒绝的来源 `"user_abort"` 和 `"user_reject"` 永远不会出现在此事件上。656* `decision_source`：权限决策来源。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。请参阅 [工具决策事件](#tool-decision-event) 了解每个值的含义。仅拒绝的来源 `"user_abort"` 和 `"user_reject"` 永远不会出现在此事件上。

637* `tool_input_size_bytes`：JSON 序列化工具输入的大小（字节）657* `tool_input_size_bytes`：JSON 序列化工具输入的大小（字节）

638* `tool_result_size_bytes`：工具结果的大小（字节）658* `tool_result_size_bytes`：工具结果的大小（字节）

659* `event.name`：`"api_request"`679* `event.name`：`"api_request"`

660* `event.timestamp`：ISO 8601 时间戳680* `event.timestamp`：ISO 8601 时间戳

661* `event.sequence`：单调递增的计数器，用于在会话内排序事件681* `event.sequence`：单调递增的计数器，用于在会话内排序事件

662* `model`：使用的模型（例如，"claude-sonnet-4-6"）682* `model`：使用的模型（例如，"claude-sonnet-5"）

663* `cost_usd`：USD 估计成本683* `cost_usd`：USD 估计成本

664* `duration_ms`：请求持续时间（毫秒）684* `duration_ms`：请求持续时间（毫秒）

665* `input_tokens`：输入令牌数685* `input_tokens`：输入令牌数

686* `event.name`：`"api_error"`706* `event.name`：`"api_error"`

687* `event.timestamp`：ISO 8601 时间戳707* `event.timestamp`：ISO 8601 时间戳

688* `event.sequence`：单调递增的计数器，用于在会话内排序事件708* `event.sequence`：单调递增的计数器，用于在会话内排序事件

689* `model`：使用的模型（例如，"claude-sonnet-4-6"）709* `model`：使用的模型（例如，"claude-sonnet-5"）

690* `error`：错误消息710* `error`：错误消息

691* `status_code`：HTTP 状态代码（数字形式）。对于非 HTTP 错误（例如连接失败）不存在。711* `status_code`：HTTP 状态代码（数字形式）。对于非 HTTP 错误（例如连接失败）不存在。

692* `duration_ms`：请求持续时间（毫秒）712* `duration_ms`：请求持续时间（毫秒）

1187 审计安全事件1207 审计安全事件

1188</h2>1208</h2>

1189 1209

1190OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件都携带身份属性，将工具调用、MCP 活动和权限决策与触发它们的用户联系起来，OTLP 日志导出器可以将这些事件传递到任何具有 OTLP 接收器的安全信息和事件管理 (SIEM) 平台或转发到您的 SIEM 的 OpenTelemetry Collector。1210OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件都携带身份属性，将工具调用、MCP 活动和权限决策与触发它们的用户联系起来。OTLP 日志导出器可以将这些事件传递到任何具有 OTLP 接收器的安全信息和事件管理 (SIEM) 平台，或转发到您的 SIEM 的 OpenTelemetry Collector。

1191 1211

1192<h3 id="attribute-actions-to-users">1212<h3 id="attribute-actions-to-users">

1193 将属性操作归属于用户1213 将属性操作归属于用户

1194</h3>1214</h3>

1195 1215

1196每个事件上的 [标准属性](#standard-attributes) 包括已认证用户的身份：`user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`（使用 Claude 账户登录时），加上安装范围的 `user.id` 和每会话的 `session.id`。1216每个事件上的 [标准属性](#standard-attributes) 包括已认证用户的身份：`user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`（使用 Claude 账户登录时），加上 `user.id` 和每会话的 `session.id`。`user.id` 是安装范围的标识符，除了在 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，其中它是来自网关颁发的令牌的 IdP 主体。

1197 1217

1198MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户。1218MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上的 IdP 身份。

1199 1219

1200当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置：1220当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：CLI 自动标记 IdP 身份，如 [标准属性](#standard-attributes) 中所述。

1201 1221

1202```bash theme={null}1222```bash theme={null}

1203export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1223export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1319* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号1339* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号

1320* 通过 OAuth 认证时，`user.email` 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段1340* 通过 OAuth 认证时，`user.email` 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段

1321* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`1341* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`

1342* 默认情况下不收集助手响应文本。仅记录响应长度。要包含响应文本，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=1`。与来自 Claude Code 的所有 OpenTelemetry 数据一样，响应文本仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。当此变量未设置时，`OTEL_LOG_USER_PROMPTS` 用作后备，因此如果您想要提示内容而不要响应内容，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=0`

1322* 默认情况下不记录工具输入参数和参数。要包含它们，请设置 `OTEL_LOG_TOOL_DETAILS=1`。此数据仅发送到您配置的 OTEL 端点，永远不会发送到 Anthropic。参数仍可能包含敏感值，因此请根据需要配置您的遥测后端以过滤或编辑这些属性。启用后：1343* 默认情况下不记录工具输入参数和参数。要包含它们，请设置 `OTEL_LOG_TOOL_DETAILS=1`。此数据仅发送到您配置的 OTEL 端点，永远不会发送到 Anthropic。参数仍可能包含敏感值，因此请根据需要配置您的遥测后端以过滤或编辑这些属性。启用后：

1323 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出1344 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出

1324 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符1345 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符

network-config.md +2 −2

Details

63 CA 证书存储63 CA 证书存储

64</h2>64</h2>

65 65

66默认情况下，Claude Code 信任其捆绑的 Mozilla CA 证书和您的操作系统的证书存储。企业 TLS 检查代理（如 CrowdStrike Falcon 和 Zscaler）在其根证书安装在操作系统信任存储中时无需额外配置即可工作。66默认情况下，Claude Code 信任其捆绑的 Mozilla CA 证书和您的操作系统的证书存储。读取操作系统存储需要具有 `tls.getCACertificates` 的运行时：本机安装程序始终具有它，npm 安装需要 Node 22.15 或更高版本。在较旧的 Node 版本上，仅捆绑的集合和 `NODE_EXTRA_CA_CERTS` 适用。企业 TLS 检查代理（如 CrowdStrike Falcon 和 Zscaler）在其根证书安装在操作系统信任存储中且运行时可以读取它时无需额外配置即可工作。

67 67

68`CLAUDE_CODE_CERT_STORE` 接受逗号分隔的源列表。识别的值为 `bundled`（Claude Code 附带的 Mozilla CA 集）和 `system`（操作系统信任存储）。默认值为 `bundled,system`。68`CLAUDE_CODE_CERT_STORE` 接受逗号分隔的源列表。识别的值为 `bundled`（Claude Code 附带的 Mozilla CA 集）和 `system`（操作系统信任存储）。默认值为 `bundled,system`。

69 69

131 131

132Claude Code 默认还会发送可选的操作遥测数据，您可以使用环境变量禁用它。请参阅 [遥测服务](/zh-CN/data-usage#telemetry-services) 了解如何在最终确定您的白名单之前禁用它。132Claude Code 默认还会发送可选的操作遥测数据，您可以使用环境变量禁用它。请参阅 [遥测服务](/zh-CN/data-usage#telemetry-services) 了解如何在最终确定您的白名单之前禁用它。

133 133

134使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry) 时，模型流量和身份验证会转到您的提供商，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍会调用 `api.anthropic.com` 进行其 [域名安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，除非您在 [settings](/zh-CN/settings) 中设置 `skipWebFetchPreflight: true`。134使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话时，模型流量和身份验证会转到您的提供商或网关，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍会调用 `api.anthropic.com` 进行其 [域名安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，除非您在 [settings](/zh-CN/settings) 中设置 `skipWebFetchPreflight: true`。

135 135

136[Claude Code on the web](/zh-CN/claude-code-on-the-web) 和 [Code Review](/zh-CN/code-review) 从 Anthropic 管理的基础设施连接到您的存储库。如果您的 GitHub Enterprise Cloud 组织按 IP 地址限制访问，请启用 [已安装 GitHub Apps 的 IP 允许列表继承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 注册了其 IP 范围，因此启用此设置允许访问而无需手动配置。要 [手动将范围添加到您的允许列表](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或配置其他防火墙，请参阅 [Anthropic API IP 地址](https://platform.claude.com/docs/en/api/ip-addresses)。136[Claude Code on the web](/zh-CN/claude-code-on-the-web) 和 [Code Review](/zh-CN/code-review) 从 Anthropic 管理的基础设施连接到您的存储库。如果您的 GitHub Enterprise Cloud 组织按 IP 地址限制访问，请启用 [已安装 GitHub Apps 的 IP 允许列表继承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 注册了其 IP 范围，因此启用此设置允许访问而无需手动配置。要 [手动将范围添加到您的允许列表](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或配置其他防火墙，请参阅 [Anthropic API IP 地址](https://platform.claude.com/docs/en/api/ip-addresses)。

137 137

permission-modes.md +31 −6

Details

37 <Tab title="CLI">37 <Tab title="CLI">

38 **在会话期间**：按 `Shift+Tab` 循环切换 `default` → `acceptEdits` → `plan`。当前模式显示在状态栏中。并非每种模式都在默认循环中：38 **在会话期间**：按 `Shift+Tab` 循环切换 `default` → `acceptEdits` → `plan`。当前模式显示在状态栏中。并非每种模式都在默认循环中：

39 39

40 * `auto`：当您的账户满足 [auto mode 要求](#eliminate-prompts-with-auto-mode)时出现；循环到 auto 会显示一个选择加入提示，直到您接受它，或选择**不，不再询问**以从循环中移除 auto40 * `auto`：当您的账户满足 [auto mode 要求](#eliminate-prompts-with-auto-mode)时出现；循环到它会在不确认提示的情况下切换模式

41 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 启动后出现；`--allow-` 变体将模式添加到循环中而不激活它41 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 启动后出现；`--allow-` 变体将模式添加到循环中而不激活它

42 * `dontAsk`：永远不会出现在循环中；使用 `--permission-mode dontAsk` 设置它42 * `dontAsk`：永远不会出现在循环中；使用 `--permission-mode dontAsk` 设置它

43 43

187Auto mode 仅在您的账户满足所有这些要求时可用：187Auto mode 仅在您的账户满足所有这些要求时可用：

188 188

189* **计划**：所有计划。189* **计划**：所有计划。

190* **管理员**：在 Team 和 Enterprise 上，管理员必须在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用它，然后用户才能打开它。管理员也可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来锁定它。190* **所有者**：在 Team 和 Enterprise 上，所有者必须在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用它，然后用户才能打开它。管理员也可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来锁定它。

191* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更高版本，或 Sonnet 4.6。在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上，仅支持 Claude Opus 4.7 和 Opus 4.8。不支持其他模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支持。191* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，仅支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。不支持其他模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支持。

192* **提供商**：在 Anthropic API 上默认可用。在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上，auto mode 处于关闭状态，直到您[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。192* **提供商**：在 Anthropic API 上默认可用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 Claude apps gateway 会话上，auto mode 处于关闭状态，直到您[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。

193 193

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

195 195

199 在 Bedrock、Vertex AI 或 Foundry 上启用 auto mode199 在 Bedrock、Vertex AI 或 Foundry 上启用 auto mode

200</h3>200</h3>

201 201

202在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud Vertex AI](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，auto mode 不会出现在 `Shift+Tab` 循环中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 被设置为 `1`。该变量在 Claude Code v2.1.158 及更高版本中有效。仅在这些提供商上支持 Claude Opus 4.7 和 Opus 4.8。202在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，auto mode 不会出现在 `Shift+Tab` 循环中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 被设置为 `1`。该变量在 Claude Code v2.1.158 及更高版本中有效。仅在这些提供商上支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

203 203

204要为一个开发者启用它，请将变量添加到 `~/.claude/settings.json` 中的 `env` 块：204要为一个开发者启用它，请将变量添加到 `~/.claude/settings.json` 中的 `env` 块：

205 205

217 217

218要防止开发者启用 auto mode，请在托管设置中将 `disableAutoMode` 设置为 `"disable"`。这会覆盖启用变量。218要防止开发者启用 auto mode，请在托管设置中将 `disableAutoMode` 设置为 `"disable"`。这会覆盖启用变量。

219 219

220如果您通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM gateway](/zh-CN/llm-gateway) 连接，auto mode 可能已经可以访问而无需启用变量，因为网关通过 Anthropic API 路由请求。`disableAutoMode` 设置在该配置中以相同方式应用。220如果您通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM gateway](/zh-CN/llm-gateway) 连接，auto mode 可能已经可以访问而无需启用变量，因为网关通过 Anthropic API 路由请求。这不适用于已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话，它是自己的提供商类别，需要启用变量。`disableAutoMode` 设置在任一配置中以相同方式应用。

221 221

222<h3 id="what-the-classifier-blocks-by-default">222<h3 id="what-the-classifier-blocks-by-default">

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

239* `git commit --amend`，当 HEAD 处的提交不是在此会话中创建的239* `git commit --amend`，当 HEAD 处的提交不是在此会话中创建的

240* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用会销毁资源的计划240* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用会销毁资源的计划

241 241

242Claude Code v2.1.195 及更高版本默认阻止更多类别。其中几个取决于[环境](/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。

243

244* 写入密钥管理器，或更改 DNS 记录或 TLS 证书

245* 合并人类未批准的拉取请求、批准 Claude 自己的拉取请求或禁用 CI 检查

246* 发布本身是自动化命令的评论，例如 `atlantis apply` 或机器人的 `/deploy` 或 `/merge`

247* 切换、调整或删除生产功能标志

248* 将基础设施更改应用于受保护的 IaC 范围，或排空和删除集群节点

249* 写入超出您命名的资源的共享计算集群，例如标签选择器或 `--all` 捕获其他用户的作业

250* 创建在每个节点上运行或拦截集群流量的 Kubernetes 资源，例如 DaemonSets 和准入 webhooks

251* 交互式 shell 或端口转发到敏感的远程目标

252* 打开隧道或反向 shell，使本地服务可从公共互联网访问

253* 将实时凭证或令牌打印到记录或文件中

254* 访问 PII 或受管制数据位置，或从其中复制数据

255* 绕过您的内部包注册表将包安装路由到公共注册表

256* 使用禁用安全防护的标志运行命令，如 `--insecure`

257* [Chrome 中的 Claude](/zh-CN/chrome) 浏览器操作可能会发送页面内容、cookie 或凭证跨源

258

242**默认允许**：259**默认允许**：

243 260

244* 工作目录中的本地文件操作261* 工作目录中的本地文件操作

247* 只读 HTTP 请求264* 只读 HTTP 请求

248* 推送到您启动的分支或 Claude 创建的分支265* 推送到您启动的分支或 Claude 创建的分支

249 266

267Claude Code v2.1.195 及更高版本也默认允许这些：

268

269* 删除 Claude 在同一会话中早前创建的确切作业

270* 作为您的任务的一部分读取、审查或编写与安全相关的代码、配置和威胁模型

271* 在同一多代理会话中协同工作的代理之间的消息

272* 向您在 [`environment`](/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、桶和服务发送数据。这仅涵盖数据流，不涵盖相同基础设施上的破坏性或凭证操作

273* [Chrome 中的 Claude](/zh-CN/chrome) 导航到受信任的内部域、localhost 或您命名的 URL

274

250Sandbox 网络访问请求通过分类器路由而不是默认允许。运行 `claude auto-mode defaults` 以查看完整的规则列表。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、桶和服务：请参阅[配置 auto mode](/zh-CN/auto-mode-config)。275Sandbox 网络访问请求通过分类器路由而不是默认允许。运行 `claude auto-mode defaults` 以查看完整的规则列表。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、桶和服务：请参阅[配置 auto mode](/zh-CN/auto-mode-config)。

251 276

252<h3 id="boundaries-you-state-in-conversation">277<h3 id="boundaries-you-state-in-conversation">

permissions.md +31 −20

Details

24 管理权限24 管理权限

25</h2>25</h2>

26 26

~~27您可以使用 `/permissions` 查看和管理 Claude Code 的工具权限。此 UI 列出所有权限规则和它们来自的 settings.json 文件。~~27您可以使用 `/permissions` 查看和管理 Claude Code 的工具权限。此 UI 列出所有权限规则和它们来自的 `settings.json` 文件。

28 28

29* **Allow** 规则让 Claude Code 使用指定的工具而无需手动批准。29* **Allow** 规则让 Claude Code 使用指定的工具而无需手动批准。

30* **Ask** 规则在 Claude Code 尝试使用指定工具时提示确认。30* **Ask** 规则在 Claude Code 尝试使用指定工具时提示确认。

31* **Deny** 规则防止 Claude Code 使用指定的工具。31* **Deny** 规则防止 Claude Code 使用指定的工具。

32 32

33规则按顺序评估：deny、ask，然后 allow。该顺序中的第一个匹配项决定结果，规则特异性不会改变顺序。匹配的 deny 规则（如 `Bash(aws *)`）会阻止每个匹配的调用，包括也匹配更具体的 allow 规则（如 `Bash(aws s3 ls)`）的调用，因此 deny 规则不能包含允许列表例外。ask 和 allow 之间也适用相同的优先级：匹配的 ask 规则即使更具体的 allow 规则也匹配同一调用，也会提示。33规则按顺序评估：deny、ask，然后 allow。该顺序中的第一个匹配项决定结果，规则特异性不会改变顺序。

35一个宽泛的 deny 规则（如 `Bash(aws *)`）会阻止每个匹配的调用，包括也匹配更具体的 allow 规则（如 `Bash(aws s3 ls)`）的调用，因此 deny 规则不能包含允许列表例外。ask 和 allow 之间也适用相同的优先级：匹配的 ask 规则即使更具体的 allow 规则也匹配同一调用，也会提示。

34 36

35Deny 规则的行为取决于它们是命名工具还是在工具内范围化模式。像 `Bash` 这样的裸工具名称会将工具从 Claude 的上下文中完全移除，因此 Claude 永远看不到它。像 `Bash(rm *)` 这样的范围化规则会保留工具的可用性，并在 Claude 尝试时阻止匹配的调用。37Deny 规则的行为取决于它们是命名工具还是在工具内范围化模式。像 `Bash` 这样的裸工具名称会将工具从 Claude 的上下文中完全移除，因此 Claude 永远看不到它。像 `Bash(rm *)` 这样的范围化规则会保留工具的可用性，并在 Claude 尝试时阻止匹配的调用。

36 38

54| `bypassPermissions` | 跳过权限提示，除了由显式 `ask` 规则强制的提示。根目录和主目录删除操作（如 `rm -rf /`）仍会作为断路器提示 |56| `bypassPermissions` | 跳过权限提示，除了由显式 `ask` 规则强制的提示。根目录和主目录删除操作（如 `rm -rf /`）仍会作为断路器提示 |

55 57

56<Warning>58<Warning>

57 `bypassPermissions` 模式跳过权限提示，包括对 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn` 的写入。显式 `ask` 规则仍会强制提示，针对文件系统根目录或主目录的删除操作（如 `rm -rf /` 和 `rm -rf ~`）仍会作为断路器提示以防止模型错误。仅在隔离环境（如容器或虚拟机）中使用此模式，其中 Claude Code 无法造成损害。管理员可以通过在[托管设置](#managed-settings)中将 `permissions.disableBypassPermissionsMode` 设置为 `"disable"` 来防止此模式。59 `bypassPermissions` 模式跳过权限提示，包括对 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn` 的写入。显式 `ask` 规则仍会强制提示，针对文件系统根目录或主目录的删除操作（如 `rm -rf /` 和 `rm -rf ~`）仍会作为断路器提示以防止模型错误。仅在隔离环境（如容器或虚拟机）中使用此模式，其中 Claude Code 无法造成损害。

58</Warning>60</Warning>

59 61

60为了防止使用 `bypassPermissions` 或 `auto` 模式，在任何[设置文件](/zh-CN/settings#settings-files)中将 `permissions.disableBypassPermissionsMode` 或 `permissions.disableAutoMode` 设置为 `"disable"`。这些在[托管设置](#managed-settings)中最有用，因为它们无法被覆盖。62为了防止 `bypassPermissions` 或 `auto` 模式被使用，在任何[设置文件](/zh-CN/settings#settings-files)中将 `permissions.disableBypassPermissionsMode` 或 `permissions.disableAutoMode` 设置为 `"disable"`。这些在[托管设置](#managed-settings)中最有用，因为它们无法被覆盖。

61 63

62<h2 id="permission-rule-syntax">64<h2 id="permission-rule-syntax">

63 权限规则语法65 权限规则语法

95 按输入参数匹配97 按输入参数匹配

96</h3>98</h3>

97 99

98拒绝和询问规则可以使用 `Tool(param:value)` 匹配任何工具上的顶级输入参数。当 Claude 调用该工具且该参数设置为该确切值时，规则匹配。此语法适用于拒绝和询问规则；一个参数值的允许规则不会确立该调用总体上是安全的，因此允许规则继续使用每个工具自己的说明符语法。这适用于工具接受的任何标量参数：100拒绝和询问规则可以使用 `Tool(param:value)` 匹配任何工具上的顶级输入参数。当 Claude 调用该工具且该参数设置为该确切值时，规则匹配。一个参数值的允许规则不会确立该调用总体上是安全的，因此允许规则继续使用每个工具自己的说明符语法。这适用于工具接受的任何标量参数：

99 101

100| 规则 | 匹配 |102| 规则 | 匹配 |

101| :----------------------------- | :------------------------- |103| :----------------------------- | :------------------------- |

220 222

221 * URL 前的选项：`curl -X GET http://github.com/...`223 * URL 前的选项：`curl -X GET http://github.com/...`

222 * 不同的协议：`curl https://github.com/...`224 * 不同的协议：`curl https://github.com/...`

223 * 重定向：`curl -L http://bit.ly/xyz`（重定向到 github）225 * 重定向：`curl -L http://bit.ly/xyz`（重定向到 GitHub）

224 * 变量：`URL=http://github.com && curl $URL`226 * 变量：`URL=http://github.com && curl $URL`

225 * 额外空格：`curl http://github.com`227 * 额外空格：`curl http://github.com`

226 228

270Read 和 Edit 规则都遵循 [gitignore](https://git-scm.com/docs/gitignore) 规范，具有四种不同的模式类型：272Read 和 Edit 规则都遵循 [gitignore](https://git-scm.com/docs/gitignore) 规范，具有四种不同的模式类型：

271 273

272| 模式 | 含义 | 示例 | 匹配 |274| 模式 | 含义 | 示例 | 匹配 |

273| ----------------- | ------------------ | -------------------------------- | ------------------------------ |275| ----------------- | -------------- | -------------------------------- | ------------------------------ |

274| `//path` | 来自文件系统根目录的**绝对**路径 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |276| `//path` | 来自文件系统根目录的绝对路径 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

275| `~/path` | 来自**主**目录的路径 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |277| `~/path` | 来自主目录的路径 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

276| `/path` | **相对于项目根目录**的路径 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` |278| `/path` | 相对于项目根目录的路径 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` |

277| `path` 或 `./path` | **相对于当前目录**的路径 | `Read(*.env)` | `<cwd>/*.env` |279| `path` 或 `./path` | 相对于当前目录的路径 | `Read(*.env)` | `<cwd>/*.env` |

278 280

279<Warning>281<Warning>

280 像 `/Users/alice/file` 这样的模式不是绝对路径。它相对于项目根目录。对于绝对路径，使用 `//Users/alice/file`。282 像 `/Users/alice/file` 这样的模式不是绝对路径。它相对于项目根目录。对于绝对路径，使用 `//Users/alice/file`。

323 MCP325 MCP

324</h3>326</h3>

325 327

326* `mcp__puppeteer` 匹配由 `puppeteer` 服务器提供的任何工具（在 Claude Code 中配置的名称）328MCP 规则使用在 Claude Code 中配置的服务器名称，可选地后跟该服务器提供的工具的名称。

327* `mcp__puppeteer__*` 通配符语法，也匹配来自 `puppeteer` 服务器的所有工具329

330* `mcp__puppeteer` 匹配由 `puppeteer` 服务器提供的任何工具

331* `mcp__puppeteer__*` 使用通配符语法，也匹配来自 `puppeteer` 服务器的所有工具

328* `mcp__puppeteer__puppeteer_navigate` 匹配由 `puppeteer` 服务器提供的 `puppeteer_navigate` 工具332* `mcp__puppeteer__puppeteer_navigate` 匹配由 `puppeteer` 服务器提供的 `puppeteer_navigate` 工具

329 333

330<h3 id="agent-subagents">334<h3 id="agent-subagents">

418 422

419权限和[沙箱](/zh-CN/sandboxing)是互补的安全层：423权限和[沙箱](/zh-CN/sandboxing)是互补的安全层：

420 424

421* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于所有工具（Bash、Read、Edit、WebFetch、MCP 和其他）。425* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于所有工具，包括 Bash、Read、Edit、WebFetch 和 MCP。

422* **沙箱**提供 OS 级别的强制执行，限制 Bash 工具的文件系统和网络访问。它仅适用于 Bash 命令及其子进程。426* **沙箱**提供 OS 级别的强制执行，限制 Bash 工具的文件系统和网络访问。它仅适用于 Bash 命令及其子进程。

423 427

424使用两者进行深度防御：428使用两者进行深度防御：

428* 沙箱中的文件系统限制结合 [`sandbox.filesystem`](/zh-CN/sandboxing) 设置与 Read 和 Edit deny 规则；两者都合并到最终的沙箱边界中432* 沙箱中的文件系统限制结合 [`sandbox.filesystem`](/zh-CN/sandboxing) 设置与 Read 和 Edit deny 规则；两者都合并到最终的沙箱边界中

429* 网络限制结合 WebFetch 权限规则与沙箱的 `allowedDomains` 和 `deniedDomains` 列表433* 网络限制结合 WebFetch 权限规则与沙箱的 `allowedDomains` 和 `deniedDomains` 列表

430 434

431当沙箱启用 `autoAllowBashIfSandboxed: true`（这是默认值）时，沙箱化的 Bash 命令无需提示即可运行，即使您的权限包括裸 `Bash` ask 规则，或[等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱边界替代了该整体工具提示。内容范围的 ask 规则（如 `Bash(git push *)`）仍然强制提示，显式 deny 规则仍然适用，针对 `/`、您的主目录或其他关键系统路径的 `rm` 或 `rmdir` 命令仍然会触发提示。不会在沙箱中运行的命令（如排除的命令）按照通常的方式遵守裸 `Bash` ask 规则。请参见[沙箱模式](/zh-CN/sandboxing#sandbox-modes)以更改此行为。435当沙箱启用 `autoAllowBashIfSandboxed: true`（这是默认值）时，沙箱化的 Bash 命令无需提示即可运行，即使您的权限包括裸 `Bash` ask 规则，或[等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱边界替代了该整体工具提示。这些检查仍然适用：

436

437* 内容范围的 ask 规则（如 `Bash(git push *)`）仍然强制提示

438* 显式 deny 规则仍然适用

439* 针对 `/`、您的主目录或其他关键系统路径的 `rm` 或 `rmdir` 命令仍然会触发提示

440

441不会在沙箱中运行的命令（如排除的命令）按照通常的方式遵守裸 `Bash` ask 规则。请参见[沙箱模式](/zh-CN/sandboxing#sandbox-modes)以更改此行为。

432 442

433<h2 id="managed-settings">443<h2 id="managed-settings">

434 托管设置444 托管设置

435</h2>445</h2>

436 446

437对于需要对 Claude Code 配置进行集中控制的组织，管理员可以部署无法被用户或项目设置覆盖的托管设置。这些策略设置遵循与常规设置文件相同的格式，可以通过 MDM/OS 级别策略、托管设置文件或[服务器托管设置](/zh-CN/server-managed-settings)传递。有关传递机制和文件位置，请参见[设置文件](/zh-CN/settings#settings-files)。447对于需要对 Claude Code 配置进行集中控制的组织，管理员可以部署无法被用户或项目设置覆盖的托管设置。这些策略设置遵循与常规设置文件相同的格式，可以通过 MDM/OS 级别策略、托管设置文件、[服务器托管设置](/zh-CN/server-managed-settings)或自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 传递。有关传递机制和文件位置，请参见[设置文件](/zh-CN/settings#settings-files)。

438 448

439<h3 id="managed-only-settings">449<h3 id="managed-only-settings">

440 仅托管设置450 仅托管设置

443以下设置仅在托管设置中有效。将它们放在用户或项目设置文件中无效。453以下设置仅在托管设置中有效。将它们放在用户或项目设置文件中无效。

444 454

445| 设置 | 描述 |455| 设置 | 描述 |

446| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |456| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

447| `allowAllClaudeAiMcps` | 当为 `true` 时，claude.ai 连接器与已部署的 `managed-mcp.json` 一起加载，而不是被其独占控制所抑制。请参见[托管 MCP 配置](/zh-CN/managed-mcp) |457| `allowAllClaudeAiMcps` | 当为 `true` 时，claude.ai 连接器与已部署的 `managed-mcp.json` 一起加载，而不是被其独占控制所抑制。请参见[托管 MCP 配置](/zh-CN/managed-mcp) |

448| `allowedChannelPlugins` | 可能推送消息的频道插件的允许列表。设置时替换默认 Anthropic 允许列表。需要 `channelsEnabled: true`。请参见[限制哪些频道插件可以运行](/zh-CN/channels#restrict-which-channel-plugins-can-run) |458| `allowedChannelPlugins` | 可能推送消息的频道插件的允许列表。设置时替换默认 Anthropic 允许列表。需要 `channelsEnabled: true`。请参见[限制哪些频道插件可以运行](/zh-CN/channels#restrict-which-channel-plugins-can-run) |

449| `allowManagedHooksOnly` | 当为 `true` 时，仅加载托管 hooks、SDK hooks 和托管设置 `enabledPlugins` 中强制启用的插件中的 hooks。用户、项目和所有其他插件 hooks 被阻止 |459| `allowManagedHooksOnly` | 当为 `true` 时，仅加载托管 hooks、SDK hooks 和托管设置 `enabledPlugins` 中强制启用的插件中的 hooks。用户、项目和所有其他插件 hooks 被阻止 |

451| `allowManagedPermissionRulesOnly` | 当为 `true` 时，防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用托管设置中的规则。不影响 MCP 服务器允许列表；对于此，请设置 `allowManagedMcpServersOnly` |461| `allowManagedPermissionRulesOnly` | 当为 `true` 时，防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用托管设置中的规则。不影响 MCP 服务器允许列表；对于此，请设置 `allowManagedMcpServersOnly` |

452| `blockedMarketplaces` | 市场来源的黑名单。在下载前检查被阻止的来源，因此它们永远不会接触文件系统。请参见[托管市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |462| `blockedMarketplaces` | 市场来源的黑名单。在下载前检查被阻止的来源，因此它们永远不会接触文件系统。请参见[托管市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |

464| `disableSideloadFlags` | {/* min-version: 2.1.193 */}在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志。没有这个，用户可以通过传递这些标志来绕过 `strictKnownMarketplaces` 进行单次运行。请参见[`disableSideloadFlags`](/zh-CN/settings#available-settings)。需要 Claude Code v2.1.193 或更高版本 |

454| `forceRemoteSettingsRefresh` | 当为 `true` 时，阻止 CLI 启动直到远程托管设置被新鲜获取，如果获取失败则退出。请参见[故障关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) |465| `forceRemoteSettingsRefresh` | 当为 `true` 时，阻止 CLI 启动直到远程托管设置被新鲜获取，如果获取失败则退出。请参见[故障关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) |

462`disableBypassPermissionsMode` 通常放在托管设置中以强制执行组织策略，但它可以从任何范围工作。用户可以在自己的设置中设置它以将自己锁定在绕过模式之外。473`disableBypassPermissionsMode` 通常放在托管设置中以强制执行组织策略，但它可以从任何范围工作。用户可以在自己的设置中设置它以将自己锁定在绕过模式之外。

463 474

464<Note>475<Note>

465 在 Team 和 Enterprise 计划上，管理员在[Claude Code 管理设置](https://claude.ai/admin-settings/claude-code)中启用或禁用[远程控制](/zh-CN/remote-control)和[网络会话](/zh-CN/claude-code-on-the-web)。远程控制还可以通过 [`disableRemoteControl`](/zh-CN/settings#available-settings) 托管设置按设备禁用。网络会话没有按设备托管设置密钥。476 在 Team 和 Enterprise 计划上，Owner 在[Claude Code 管理设置](https://claude.ai/admin-settings/claude-code)中启用或禁用[远程控制](/zh-CN/remote-control)和[网络会话](/zh-CN/claude-code-on-the-web)组织范围内的设置。远程控制还可以通过 [`disableRemoteControl`](/zh-CN/settings#available-settings) 设置按设备禁用。网络会话没有按设备托管设置密钥。

466</Note>477</Note>

467 478

468<h2 id="settings-precedence">479<h2 id="settings-precedence">

479 490

480如果工具在任何级别被拒绝，没有其他级别可以允许它。例如，托管设置 deny 无法被 `--allowedTools` 覆盖，`--disallowedTools` 可以添加超出托管设置定义的限制。491如果工具在任何级别被拒绝，没有其他级别可以允许它。例如，托管设置 deny 无法被 `--allowedTools` 覆盖，`--disallowedTools` 可以添加超出托管设置定义的限制。

481 492

482嵌入主机可以在 [`parentSettingsBehavior`](/zh-CN/settings#settings-precedence) 设置为 `"merge"` 时，通过 SDK `managedSettings` 选项提供额外的托管策略；嵌入器值可以收紧策略但不能放松它。493同样的规则也适用于设置范围：如果用户设置允许某个权限而项目设置拒绝它，deny 规则会阻止它。反之亦然：用户级别的 deny 会阻止项目级别的 allow，因为来自任何范围的 deny 规则在 allow 规则之前被评估。

483 494

484例如，如果用户设置允许某个权限而项目设置拒绝它，deny 规则会阻止它。反之亦然：用户级别的 deny 会阻止项目级别的 allow，因为来自任何范围的 deny 规则在 allow 规则之前被评估。495嵌入主机可以在 [`parentSettingsBehavior`](/zh-CN/settings#settings-precedence) 设置为 `"merge"` 时，通过 SDK `managedSettings` 选项提供额外的托管策略；嵌入器值可以收紧策略但不能放松它。

485 496

486<h2 id="example-configurations">497<h2 id="example-configurations">

487 示例配置498 示例配置

plugin-dependencies.md +5 −0

Details

102 102

103当你安装声明了 `{ "name": "secrets-vault", "version": "~2.1.0" }` 的插件时，Claude Code 会列出 marketplace 的标签，过滤到以 `secrets-vault--v` 开头的标签，并获取满足 `~2.1.0` 的最高版本。如果不存在匹配的标签，依赖插件会被禁用并显示错误，列出可用的版本。103当你安装声明了 `{ "name": "secrets-vault", "version": "~2.1.0" }` 的插件时，Claude Code 会列出 marketplace 的标签，过滤到以 `secrets-vault--v` 开头的标签，并获取满足 `~2.1.0` 的最高版本。如果不存在匹配的标签，依赖插件会被禁用并显示错误，列出可用的版本。

104 104

105作为本地文件夹路径添加的 marketplace 在该文件夹是 git 存储库时以相同的方式解析标签。这需要 Claude Code v2.1.196 或更高版本。在两种情况下，Claude Code 从文件夹的当前内容安装依赖：

106

107* 早期版本不从本地文件夹 marketplace 读取标签，因此受约束的依赖仅在该副本满足范围时才加载。

108* 不是 git 存储库的本地文件夹没有标签，无论版本如何。

109

105已解析标签的 semver 与 `plugin.json` 的 `version` 分开记录，因此约束检查使用实际获取的标签，即使该提交处的 `plugin.json` 有过时的值。标签解析安装的缓存目录名称包含 12 字符的 commit-SHA 后缀，因此如果维护者强制将标签移动到不同的提交，下次安装会获得一个新的缓存目录，而不是重用过时的内容。110已解析标签的 semver 与 `plugin.json` 的 `version` 分开记录，因此约束检查使用实际获取的标签，即使该提交处的 `plugin.json` 有过时的值。标签解析安装的缓存目录名称包含 12 字符的 commit-SHA 后缀，因此如果维护者强制将标签移动到不同的提交，下次安装会获得一个新的缓存目录，而不是重用过时的内容。

106 111

107<Note>112<Note>

plugin-marketplaces.md +68 −20

Details

6 6

7> 构建和托管 plugin marketplace，以在团队和社区中分发 Claude Code 扩展。7> 构建和托管 plugin marketplace，以在团队和社区中分发 Claude Code 扩展。

8 8

9**plugin marketplace** 是一个目录，让你能够将 plugins 分发给他人。Marketplace 提供集中式发现、版本跟踪、自动更新以及对多种源类型（git 存储库、本地路径等）的支持。本指南展示了如何创建自己的 marketplace，与你的团队或社区共享 plugins。9**plugin marketplace** 是一个目录，让你能够将 plugins 分发给他人。Marketplace 提供集中式发现、版本跟踪、自动更新以及对多种源类型（包括 git 存储库和本地路径）的支持。本指南展示了如何创建自己的 marketplace，与你的团队或社区共享 plugins。

10 10

11想要从现有 marketplace 安装 plugins？请参阅[发现和安装预构建的 plugins](/zh-CN/discover-plugins)。11想要从现有 marketplace 安装 plugins？请参阅[发现和安装预构建的 plugins](/zh-CN/discover-plugins)。

12 12

17创建和分发 marketplace 涉及：17创建和分发 marketplace 涉及：

18 18

191. **创建 plugins**：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins。本指南假设你已经有要分发的 plugins；有关如何创建 plugins 的详细信息，请参阅[创建 plugins](/zh-CN/plugins)。191. **创建 plugins**：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins。本指南假设你已经有要分发的 plugins；有关如何创建 plugins 的详细信息，请参阅[创建 plugins](/zh-CN/plugins)。

~~202. **创建 marketplace 文件**：定义一个 `marketplace.json`，列出你的 plugins 及其位置（请参阅[创建 marketplace 文件](#create-the-marketplace-file)）。~~202. **创建 marketplace 文件**：定义一个 `marketplace.json`，列出你的 plugins 及其位置。请参阅[创建 marketplace 文件](#create-the-marketplace-file)。

~~213. **托管 marketplace**：推送到 GitHub、GitLab 或其他 git 主机（请参阅[托管和分发 marketplaces](#host-and-distribute-marketplaces)）。~~213. **托管 marketplace**：推送到 GitHub、GitLab 或其他 git 主机。请参阅[托管和分发 marketplaces](#host-and-distribute-marketplaces)。

~~224. **与用户共享**：用户使用 `/plugin marketplace add` 添加你的 marketplace 并安装单个 plugins（请参阅[发现和安装 plugins](/zh-CN/discover-plugins)）。~~224. **与用户共享**：用户使用 `/plugin marketplace add` 添加你的 marketplace 并安装单个 plugins。请参阅[发现和安装 plugins](/zh-CN/discover-plugins)。

23 23

24一旦你的 marketplace 上线，你可以通过推送更改到你的存储库来更新它。用户使用 `/plugin marketplace update` 刷新他们的本地副本。24一旦你的 marketplace 上线，你可以通过推送更改到你的存储库来更新它。用户使用 `/plugin marketplace update` 刷新他们的本地副本。

25 25

44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

45 ---45 ---

46 description: Review code for bugs, security, and performance46 description: Review code for bugs, security, and performance

~~47 disable-model-invocation: true~~

48 ---47 ---

49 48

50 Review the code I've selected or the recent changes for:49 Review the code I've selected or the recent changes for:

125 124

126在你的存储库根目录中创建 `.claude-plugin/marketplace.json`。此文件定义你的 marketplace 的名称、所有者信息以及包含其源的 plugins 列表。125在你的存储库根目录中创建 `.claude-plugin/marketplace.json`。此文件定义你的 marketplace 的名称、所有者信息以及包含其源的 plugins 列表。

127 126

128每个 plugin 条目至少需要一个 `name` 和 `source`（从哪里获取它）。有关所有可用字段，请参阅下面的[完整架构](#marketplace-schema)。127每个 plugin 条目至少需要一个 `name` 和 `source`（告诉 Claude Code 从哪里获取它）。有关所有可用字段，请参阅下面的[完整架构](#marketplace-schema)。

129 128

130```json theme={null}129```json theme={null}

131{130{

188</h3>187</h3>

189 188

190| 字段 | 类型 | 描述 |189| 字段 | 类型 | 描述 |

191| :------------------------------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |190| :------------------------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

196| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugins 可能依赖的其他 marketplaces。来自此处未列出的 marketplace 的依赖项在安装时被阻止。见[依赖来自另一个 marketplace 的 plugin](/zh-CN/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |195| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugins 可能依赖的其他 marketplaces。来自此处未列出的 marketplace 的依赖项在安装时被阻止。见[依赖来自另一个 marketplace 的 plugin](/zh-CN/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |

196| `renames` | object | {/* min-version: 2.1.193 */}从前一个 plugin `name` 到其当前名称的映射，或如果 plugin 被移除则映射到 `null`。当你重命名或移除 `plugins` 中的条目时，让现有用户自动迁移。见[重命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更高版本。 |

197 197

198`description` 和 `version` 也可以在 `metadata` 下接受，以实现向后兼容性。198`description` 和 `version` 也可以在 `metadata` 下接受，以实现向后兼容性。

199 199

201 Plugin 条目201 Plugin 条目

202</h2>202</h2>

203 203

204`plugins` 数组中的每个 plugin 条目描述一个 plugin 及其位置。你可以包含 [plugin manifest 架构](/zh-CN/plugins-reference#plugin-manifest-schema)中的任何字段（如 `description`、`version`、`author`、`commands`、`hooks` 等），加上这些 marketplace 特定的字段：`source`、`category`、`tags`、`strict` 和 `relevance`。204`plugins` 数组中的每个 plugin 条目描述一个 plugin 及其位置。你可以包含 [plugin manifest 架构](/zh-CN/plugins-reference#plugin-manifest-schema)中的任何字段，如 `description`、`version`、`author`、`commands` 和 `hooks`，加上这些 marketplace 特定的字段：`source`、`category`、`tags`、`strict` 和 `relevance`。

205 205

206<h3 id="required-fields-1">206<h3 id="required-fields-1">

207 必需字段207 必需字段

251 251

252Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。252Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。

253 253

254一旦 plugin 被克隆或复制到本地机器，它就会被复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`。254一旦 Claude Code 克隆或下载 plugin 到本地机器，它就会将 plugin 复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`。

255 255

256| 源 | 类型 | 字段 | 注释 |256| 源 | 类型 | 字段 | 注释 |

257| ------------ | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- |257| ------------ | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- |

264<Note>264<Note>

265 **Marketplace 源与 plugin 源**：这些是控制不同事物的不同概念。265 **Marketplace 源与 plugin 源**：这些是控制不同事物的不同概念。

266 266

267 * **Marketplace 源** — 从哪里获取 `marketplace.json` 目录本身。在用户运行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 设置中设置。支持 `ref`（分支/标签）但不支持 `sha`。267 * **Marketplace 源**：从哪里获取 `marketplace.json` 目录本身。在用户运行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 设置中设置。支持 `ref`（分支/标签）但不支持 `sha`。

268 * **Plugin 源** — 从哪里获取 marketplace 中列出的单个 plugin。在 `marketplace.json` 内每个 plugin 条目的 `source` 字段中设置。支持 `ref`（分支/标签）和 `sha`（精确提交）。268 * **Plugin 源**：从哪里获取 marketplace 中列出的单个 plugin。在 `marketplace.json` 内每个 plugin 条目的 `source` 字段中设置。支持 `ref`（分支/标签）和 `sha`（精确提交）。

269 269

270 例如，托管在 `acme-corp/plugin-catalog` 的 marketplace（marketplace 源）可以列出从 `acme-corp/code-formatter` 获取的 plugin（plugin 源）。marketplace 源和 plugin 源指向不同的存储库，并独立固定。270 例如，托管在 `acme-corp/plugin-catalog` 的 marketplace（marketplace 源）可以列出从 `acme-corp/code-formatter` 获取的 plugin（plugin 源）。marketplace 源和 plugin 源指向不同的存储库，并独立固定。

271</Note>271</Note>

288路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。在上面的示例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。288路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。在上面的示例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。

289 289

290<Note>290<Note>

291 相对路径仅在用户通过 Git（GitHub、GitLab 或 git URL）添加你的 marketplace 时有效。如果用户通过直接 URL 添加你的 marketplace 到 `marketplace.json` 文件，相对路径将无法正确解析。对于基于 URL 的分发，请改用 GitHub、npm 或 git URL 源。有关详细信息，请参阅[故障排除](#plugins-with-relative-paths-fail-in-url-based-marketplaces)。291 相对路径仅在用户通过 git 源或本地目录添加你的 marketplace 时有效。如果用户通过直接 URL 添加你的 marketplace 到 `marketplace.json` 文件，相对路径将无法解析，因为只有该文件被下载。对于基于 URL 的分发，请改用 GitHub、npm 或 git URL 源。有关详细信息，请参阅[故障排除](#plugins-with-relative-paths-fail-in-url-based-marketplaces)。

292</Note>292</Note>

293 293

294<h3 id="github-repositories">294<h3 id="github-repositories">

547 在 GitHub 上托管（推荐）547 在 GitHub 上托管（推荐）

548</h3>548</h3>

549 549

550GitHub 提供最简单的分发方法：550GitHub 是托管和分发 marketplace 的推荐方式：

551 551

5521. **创建存储库**：为你的 marketplace 设置一个新存储库5521. **创建存储库**：为你的 marketplace 设置一个新存储库

5532. **添加 marketplace 文件**：使用你的 plugin 定义创建 `.claude-plugin/marketplace.json`5532. **添加 marketplace 文件**：使用你的 plugin 定义创建 `.claude-plugin/marketplace.json`

596在共享前本地测试你的 marketplace：596在共享前本地测试你的 marketplace：

597 597

598```shell theme={null}598```shell theme={null}

599/plugin marketplace add ./my-local-marketplace599/plugin marketplace add ./my-marketplace

600/plugin install test-plugin@my-local-marketplace600/plugin install quality-review-plugin@my-plugins

601```601```

602 602

603有关完整的添加命令范围（GitHub、Git URL、本地路径、远程 URL），请参阅[添加 marketplaces](/zh-CN/discover-plugins#add-marketplaces)。603有关完整的添加命令范围（GitHub、Git URL、本地路径、远程 URL），请参阅[添加 marketplaces](/zh-CN/discover-plugins#add-marketplaces)。

680 托管 marketplace 限制680 托管 marketplace 限制

681</h3>681</h3>

682 682

683对于需要严格控制 plugin 源的组织，管理员可以使用托管设置中的 [`strictKnownMarketplaces`](/zh-CN/settings#strictknownmarketplaces) 设置限制用户允许添加哪些 plugin marketplaces。683对于需要严格控制 plugin 源的组织，管理员可以使用托管设置中的 [`strictKnownMarketplaces`](/zh-CN/settings#strictknownmarketplaces) 设置限制用户允许添加哪些 plugin marketplaces。要同时拒绝为单次运行 sideload plugins、agents 和 MCP servers 的 CLI 标志，请将其与 [`disableSideloadFlags`](/zh-CN/settings#available-settings) 配对。

684 684

685当在托管设置中配置 `strictKnownMarketplaces` 时，限制行为取决于值：685当在托管设置中配置 `strictKnownMarketplaces` 时，限制行为取决于值：

686 686

792<Warning>792<Warning>

793 设置 `version` 会固定 plugin。如果 `plugin.json` 声明 `"version": "1.0.0"`，推送新提交而不改变该字符串对现有用户没有任何作用，因为 Claude Code 看到相同的版本并保留缓存副本。在每个发布时提升该字段，或省略它以使用提交 SHA。793 设置 `version` 会固定 plugin。如果 `plugin.json` 声明 `"version": "1.0.0"`，推送新提交而不改变该字符串对现有用户没有任何作用，因为 Claude Code 看到相同的版本并保留缓存副本。在每个发布时提升该字段，或省略它以使用提交 SHA。

794 794

795 避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。`plugin.json` 值总是无声地获胜，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。795 避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。Claude Code 总是无声地使用 `plugin.json` 值，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。

796</Warning>796</Warning>

797 797

798<h4 id="set-up-release-channels">798<h4 id="set-up-release-channels">

881 881

882Plugin 可以将其依赖约束到 semver 范围，以便对依赖的更新不会破坏依赖的 plugin。有关 `{plugin-name}--v{version}` git 标签约定、范围语法以及如何组合对同一依赖的多个约束，请参阅[约束 plugin 依赖版本](/zh-CN/plugin-dependencies)。882Plugin 可以将其依赖约束到 semver 范围，以便对依赖的更新不会破坏依赖的 plugin。有关 `{plugin-name}--v{version}` git 标签约定、范围语法以及如何组合对同一依赖的多个约束，请参阅[约束 plugin 依赖版本](/zh-CN/plugin-dependencies)。

883 883

884<h3 id="rename-or-remove-a-plugin">

885 重命名或删除 plugin

886</h3>

887

888Plugin 的 `name` 是其稳定标识符。用户在 `enabledPlugins`、`pluginConfigs` 和 `/plugin install` 命令中引用它，所以改变它会破坏每个现有的安装。要改变 UI 中显示的标签而不破坏安装，请设置 [`displayName`](#optional-plugin-fields) 并保持 `name` 不变。

889

890如果你必须改变 plugin 的 `name`，或者你从 `plugins` 数组中删除 plugin，请添加顶级 `renames` 条目，以便现有用户迁移而不是看到 `plugin-not-found` 错误。自动迁移需要 Claude Code v2.1.193 或更高版本。将每个前名称映射到其当前名称，或映射到 `null` 如果 plugin 不再存在。以下示例将 `formatter` 重命名为 `code-formatter` 并记录 `legacy-linter` 已被删除：

891

892```json theme={null}

893{

894 "name": "acme-tools",

895 "owner": { "name": "Acme" },

896 "plugins": [

897 { "name": "code-formatter", "source": "./plugins/code-formatter" }

898 ],

899 "renames": {

900 "formatter": "code-formatter",

901 "legacy-linter": null

902 }

903}

904```

905

906当用户启动 Claude Code 时旧名称仍在其设置中，Claude Code 遵循 `renames` 映射：

907

908* 如果条目指向新名称，Claude Code 在其新名称下加载 plugin 并显示一行通知，例如 `在"acme-tools" marketplace 中重命名为"code-formatter"`。然后它在用户、项目和本地设置范围中为 `enabledPlugins` 和 `pluginConfigs` 都将旧键重写为新键，所以通知只出现一次。

909* 对于 `null` 条目，Claude Code 删除旧键，通知报告 plugin 已从 marketplace 中删除。

910* 如果重命名的 plugin 使用远程源，例如 `github` 或 `npm`，Claude Code 在重命名后报告 `plugin-cache-miss`，用户必须运行 `/plugin install` 一次以在新名称下获取它。

911

912将 `renames` 视为仅追加历史：即使在你期望每个用户都已迁移后，也要保持旧条目就位。Claude Code 遵循链，所以如果你稍后将 `code-formatter` 重命名为 `formatter-pro`，请添加第二个条目而不是编辑第一个。仍然启用原始 `formatter` 的用户然后通过两个条目解析到 `formatter-pro`。

913

914在编辑映射后运行 `claude plugin validate .`；它拒绝任何链形成循环或不终止于 `null` 或 `plugins` 中列出的名称的条目。

915

916<Note>

917 托管和策略设置对 Claude Code 是只读的，所以在那里启用的 plugins 无法自动重写。重命名的 plugin 仍然在每个会话中加载，但重命名通知会重复出现，直到管理员更新托管设置文件中的 `enabledPlugins` 以使用新名称。相同的情况适用于通过其他只读源（例如 `--add-dir`）启用的 plugins。

918</Note>

919

920早期版本的 Claude Code 忽略 `renames` 字段并为旧名称报告 `plugin-not-found`。

921

884<h2 id="validation-and-testing">922<h2 id="validation-and-testing">

885 验证和测试923 验证和测试

886</h2>924</h2>

933 971

934* `<source>`：GitHub `owner/repo` 简写、git URL、指向 `marketplace.json` 文件的远程 URL 或本地目录路径。要固定到分支或标签，请将 `@ref` 附加到 GitHub 简写或 `#ref` 附加到 git URL972* `<source>`：GitHub `owner/repo` 简写、git URL、指向 `marketplace.json` 文件的远程 URL 或本地目录路径。要固定到分支或标签，请将 `@ref` 附加到 GitHub 简写或 `#ref` 附加到 git URL

935 973

974URL 必须包含其方案。从 Claude Code v2.1.196 开始，没有方案的主机（如 `gitlab.example.com/team/plugins`）被拒绝为无效的 `owner/repo` 简写，错误会告诉你添加 `https://` 或为本地路径使用 `./`。早期版本会将其误读为 GitHub 存储库路径，并在克隆时失败，出现 GitHub 未找到错误。

975

936**选项：**976**选项：**

937 977

938| 选项 | 描述 | 默认值 |978| 选项 | 描述 | 默认值 |

1061 Marketplace 验证错误1101 Marketplace 验证错误

1062</h3>1102</h3>

1063 1103

1064从你的 marketplace 目录运行 `claude plugin validate .` 或 `/plugin validate .` 来检查问题。当指向 marketplace 目录时，验证器仅检查 `marketplace.json`：schema、重复的 plugin 名称、源路径遍历和版本不匹配与每个引用的 `plugin.json`。1104从你的 marketplace 目录运行 `claude plugin validate .` 或 `/plugin validate .` 来检查问题。当指向 marketplace 目录时，验证器检查 `marketplace.json` 是否存在 schema 错误、重复的 plugin 名称和源路径遍历。对于 `source` 是本地路径的每个条目，它还验证该 plugin 自己的 `plugin.json`，并在条目的 `version` 与 `plugin.json` 中的版本不匹配时发出警告。在 plugin 的 `plugin.json` 中发现的问题以条目索引为前缀，形式为 `plugins[2] plugin.json →`。

1105

1106从 Claude Code v2.1.196 开始，每个条目的检查还会：

1107

1108* 包括 `source` 为 `.` 的 plugins

1109* 在 `marketplace.json` 位于 `.claude-plugin` 目录外时运行，针对文件自己的目录解析源

1110* 即使文件的另一部分有 schema 错误，也报告每个条目的问题

1111

1112早期版本跳过 marketplace 根目录中的 plugins，仅从 `.claude-plugin/marketplace.json` 开始下降。

1065 1113

1066要验证单个 plugin 的 `plugin.json` 及其 skill、agent、command 和 hook 文件，请针对 plugin 目录本身运行该命令，例如 `claude plugin validate ./plugins/my-plugin`。常见错误：1114要验证单个 plugin 的 `plugin.json` 及其 skill、agent、command 和 hook 文件，请针对 plugin 目录本身运行该命令，例如 `claude plugin validate ./plugins/my-plugin`。常见错误：

1067 1115

1068| 错误 | 原因 | 解决方案 |1116| 错误 | 原因 | 解决方案 |

1069| :------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------- |1117| :------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------- |

1078 1126

1079* `Marketplace has no plugins defined`：将至少一个 plugin 添加到 `plugins` 数组1127* `Marketplace has no plugins defined`：将至少一个 plugin 添加到 `plugins` 数组

1080* `No marketplace description provided`：添加顶级 `description` 以帮助用户理解你的 marketplace1128* `No marketplace description provided`：添加顶级 `description` 以帮助用户理解你的 marketplace

1081* `Plugin name "x" is not kebab-case`：plugin 名称包含大写字母、空格或特殊字符。重命名为仅包含小写字母、数字和连字符（例如，`my-plugin`）。Claude Code 接受其他形式，但 Claude.ai marketplace 同步会拒绝它们。1129* `Plugin name "x" is not kebab-case`：plugin 名称包含大写字母、空格或特殊字符。重命名为仅包含小写字母、数字和连字符（例如，`my-plugin`）。Claude Code 接受其他形式，但 claude.ai marketplace 同步会拒绝它们。

1082 1130

1083<h3 id="plugin-installation-failures">1131<h3 id="plugin-installation-failures">

1084 Plugin 安装失败1132 Plugin 安装失败

plugins-reference.md +3 −3

Details

477如果包含清单，`name` 是唯一必需的字段。477如果包含清单，`name` 是唯一必需的字段。

478 478

479| 字段 | 类型 | 描述 | 示例 |479| 字段 | 类型 | 描述 | 示例 |

480| :----- | :----- | :-------------------- | :------------------- |480| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |

482 482

483此名称用于命名空间组件。例如，在 UI 中，名为 `plugin-dev` 的 plugin 的 agent `agent-creator` 将显示为 `plugin-dev:agent-creator`。483此名称用于命名空间组件。例如，在 UI 中，名为 `plugin-dev` 的 plugin 的 agent `agent-creator` 将显示为 `plugin-dev:agent-creator`。

484 484

632自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：632自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：

633 633

634* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认 `commands/` 目录。要保留默认值并添加更多，请明确列出它：`"commands": ["./commands/", "./extras/"]`634* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认 `commands/` 目录。要保留默认值并添加更多，请明确列出它：`"commands": ["./commands/", "./extras/"]`

635* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载。异常：对于[其 `source` 解析为市场根的市场条目](/zh-CN/plugin-marketplaces#advanced-plugin-entries)，声明特定子目录会替换扫描635* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载。异常：对于[其 `source` 解析为市场根的市场条目](/zh-CN/plugin-marketplaces#advanced-plugin-entries)，声明特定子目录会替换默认 `skills/` 扫描

636* **自己的合并规则**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。请参阅每个部分了解多个源如何组合636* **自己的合并规则**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。请参阅每个部分了解多个源如何组合

637 637

638当 plugin 同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本在 `/doctor`、`claude plugin list` 和 `/plugin` 详细视图中标记被忽略的文件夹。plugin 仍然使用清单路径加载。当清单键指向默认文件夹时不显示警告，例如 `"commands": ["./commands/deploy.md"]`，因为在这种情况下文件夹被明确寻址。638当 plugin 同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本在 `/doctor`、`claude plugin list` 和 `/plugin` 详细视图中标记被忽略的文件夹。plugin 仍然使用清单路径加载。当清单键指向默认文件夹时不显示警告，例如 `"commands": ["./commands/deploy.md"]`，因为在这种情况下文件夹被明确寻址。

quickstart.md +1 −0

Details

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

107* [Claude Console](https://console.anthropic.com/)（具有预付费额度的 API 访问）。首次登录时，Console 中会自动为集中成本跟踪创建一个"Claude Code"工作区。107* [Claude Console](https://console.anthropic.com/)（具有预付费额度的 API 访问）。首次登录时，Console 中会自动为集中成本跟踪创建一个"Claude Code"工作区。

108* [Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-CN/third-party-integrations)（企业云提供商）108* [Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-CN/third-party-integrations)（企业云提供商）

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

109 110

110登录后，您的凭证将被存储，您无需再次登录。111登录后，您的凭证将被存储，您无需再次登录。

111 112

remote-control.md +8 −1

Details

34 34

35* **订阅**：在 Pro、Max、Team 和 Enterprise 计划中可用。不支持 API 密钥。在 Team 和 Enterprise 上，Owner 必须首先在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用 Remote Control 切换。35* **订阅**：在 Pro、Max、Team 和 Enterprise 计划中可用。不支持 API 密钥。在 Team 和 Enterprise 上，Owner 必须首先在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用 Remote Control 切换。

36* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。36* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。

37* **API 端点**：在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机（例如 [LLM gateway](/zh-CN/llm-gateway) 或代理）时，Remote Control 也会被禁用。取消设置该变量以使用 Remote Control。

37* **工作区信任**：在您的项目目录中至少运行一次 `claude` 以接受工作区信任对话框。38* **工作区信任**：在您的项目目录中至少运行一次 `claude` 以接受工作区信任对话框。

38 39

39<h2 id="start-a-remote-control-session">40<h2 id="start-a-remote-control-session">

148 为所有会话启用 Remote Control149 为所有会话启用 Remote Control

149</h3>150</h3>

150 151

151默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置回 `false` 以禁用。在桌面应用中，您也可以从**设置 → Claude Code → 默认启用远程控制**切换此选项。152默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置为 `false` 以禁用，或将其保留为未设置以遵循您的组织的默认值。在桌面应用中，您也可以从**设置 → Claude Code → 默认启用远程控制**切换此选项。

152 153

153启用此设置后，每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例，每个实例都获得自己的环境和会话。要从单个进程运行多个并发会话，请改用[服务器模式](#start-a-remote-control-session)。154启用此设置后，每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例，每个实例都获得自己的环境和会话。要从单个进程运行多个并发会话，请改用[服务器模式](#start-a-remote-control-session)。

154 155

318 319

319Claude Code 无法到达功能标志服务以检查是否为您的账户启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"无法验证您的组织的 Remote Control 策略"具有相同的原因和相同的修复。这两条消息都在 v2.1.178 中添加。320Claude Code 无法到达功能标志服务以检查是否为您的账户启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"无法验证您的组织的 Remote Control 策略"具有相同的原因和相同的修复。这两条消息都在 v2.1.178 中添加。

320 321

322<h3 id="remote-control-is-only-available-when-using-claude-via-api-anthropic-com">

323 "Remote Control 仅在通过 api.anthropic.com 使用 Claude 时可用"

324</h3>

325

326该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端可配对。这发生在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录，也会发生这种情况。取消设置 `ANTHROPIC_BASE_URL` 并重启会话以使用 Remote Control。

327

321<h3 id="remote-control-is-disabled-by-your-organization’s-policy">328<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

322 "Remote Control 被您的组织的策略禁用"329 "Remote Control 被您的组织的策略禁用"

323</h3>330</h3>

scheduled-tasks.md +7 −2

Details

50 50

~~51您也可以将另一个命令作为提示词传递，例如 `/loop 20m /review-pr 1234`，以在每次迭代时重新运行保存的工作流或命令。~~51您也可以将 skill 作为提示词传递，例如 `/loop 20m /review-pr 1234`，以在每次迭代时重新运行该 skill。{/* min-version: 2.1.196 */}从 v2.1.196 开始，计划的触发仅运行 Claude [允许自己调用](/zh-CN/skills#control-who-invokes-a-skill)的 skill。以下内容作为纯文本到达 Claude，而不是执行：

53* 内置命令，例如 `/permissions`、`/model` 或 `/clear`

54* 标记为 [`disable-model-invocation: true`](/zh-CN/skills#frontmatter-reference) 的 skill

55* 由 [`skillOverrides`](/zh-CN/skills#override-skill-visibility-from-settings) 设置或 `Skill` [deny rule](/zh-CN/skills#restrict-claude’s-skill-access) 从 Claude 扣留的 skill

56* [MCP prompts](/zh-CN/mcp#use-mcp-prompts-as-commands)，例如 `/mcp__github__list_prs`；MCP 服务器公开的 skill 仍然运行

52 57

53<h3 id="run-on-a-fixed-interval">58<h3 id="run-on-a-fixed-interval">

54 在固定间隔上运行59 在固定间隔上运行

238 243

239会话范围的调度有固有的限制：244会话范围的调度有固有的限制：

240 245

241* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。246* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。[将会话放在后台](/zh-CN/agent-view#from-inside-a-session)会将 `/loop` 任务转移到后台会话，该会话继续运行而无需终端。

242* 没有错过触发的追赶。如果任务的计划时间在 Claude 忙于长时间运行的请求时经过，它会在 Claude 变为空闲时触发一次，而不是每个错过的间隔触发一次。247* 没有错过触发的追赶。如果任务的计划时间在 Claude 忙于长时间运行的请求时经过，它会在 Claude 变为空闲时触发一次，而不是每个错过的间隔触发一次。

243* 启动新对话会清除所有会话范围的任务。使用 `claude --resume` 或 `claude --continue` 恢复会恢复尚未过期的任务：创建后七天内的重复任务，以及计划时间尚未到达的一次性任务。后台 Bash 和监视器任务在恢复时永远不会被恢复。248* 启动新对话会清除所有会话范围的任务。使用 `claude --resume` 或 `claude --continue` 恢复会恢复尚未过期的任务：创建后七天内的重复任务，以及计划时间尚未到达的一次性任务。后台 Bash 和监视器任务在恢复时永远不会被恢复。

244 249

server-managed-settings.md +10 −4

Details

153 153

154服务器管理的设置和[端点管理的设置](/zh-CN/settings#settings-files)都占据 Claude Code [设置层次结构](/zh-CN/settings#settings-precedence)中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数。154服务器管理的设置和[端点管理的设置](/zh-CN/settings#settings-files)都占据 Claude Code [设置层次结构](/zh-CN/settings#settings-precedence)中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数。

155 155

156在托管层内，首先传递非空配置的源获胜。首先检查服务器管理的设置，然后检查端点管理的设置。源不合并：如果服务器管理的设置传递任何键，端点管理的设置将被完全忽略。如果服务器管理的设置不传递任何内容，端点管理的设置将应用。156在托管层内，配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 优先于所有其他托管源，包括服务器管理的设置：其输出成为该运行的唯一托管配置。否则，首先传递非空配置的源获胜。首先检查服务器管理的设置，然后检查端点管理的设置。源不合并：如果服务器管理的设置传递任何键，其他端点管理的设置将被完全忽略。有一个例外适用：当任何管理员控制的托管源设置一小组[跨源锁定键](/zh-CN/settings#settings-precedence)（例如沙箱允许列表锁）时，这些键会被遵守；用户可写的 HKCU 注册表层被排除。如果服务器管理的设置不传递任何内容，端点管理的设置将应用。

157 157

158如果您清除管理控制台中的服务器管理配置，意图回退到端点管理的 plist 或注册表策略，请注意[缓存的设置](#fetch-and-caching-behavior)在客户端机器上持久化，直到下次成功获取。运行 `/status` 查看哪个托管源处于活动状态。158如果您清除管理控制台中的服务器管理配置，意图回退到端点管理的 plist 或注册表策略，请注意[缓存的设置](#fetch-and-caching-behavior)在客户端机器上持久化，直到下次成功获取。运行 `/status` 查看哪个托管源处于活动状态。

159 159

222* **Shell 命令设置**：执行 shell 命令的设置222* **Shell 命令设置**：执行 shell 命令的设置

223* **自定义环境变量**：不在已知安全允许列表中的变量223* **自定义环境变量**：不在已知安全允许列表中的变量

224* **Hook 配置**：任何 hook 定义224* **Hook 配置**：任何 hook 定义

225* **托管 CLAUDE.md 内容**：通过托管设置传递的 `claudeMd` 值

225 226

226当这些设置存在时，用户会看到一个安全对话框，解释正在配置的内容。用户必须批准才能继续。如果用户拒绝设置，Claude Code 会退出。227当这些设置存在时，用户会看到一个安全对话框，解释正在配置的内容。用户必须批准才能继续。如果用户拒绝设置，Claude Code 会退出。

227 228

239* Google Vertex AI240* Google Vertex AI

240* Microsoft Foundry241* Microsoft Foundry

241* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)242* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)

242* 通过 `ANTHROPIC_BASE_URL` 或 [LLM gateways](/zh-CN/llm-gateway) 的自定义 API 端点243* 通过 `ANTHROPIC_BASE_URL` 或第三方 [LLM gateways](/zh-CN/llm-gateway) 的自定义 API 端点

244

245对于 Bedrock、Vertex AI 和 Foundry 部署，自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供等效的远程管理设置交付：网关登录的客户端从网关而不是 `api.anthropic.com` 获取管理设置。启动时的失败语义不同：无法到达网关的网关客户端以错误退出，而不是回退到缓存的设置，而每小时的后台刷新在两个通道上都是故障开放的。

243 246

244<h2 id="audit-logging">247<h2 id="audit-logging">

245 审计日志248 审计日志

253 安全考虑256 安全考虑

254</h2>257</h2>

255 258

256服务器管理的设置提供集中的策略强制执行，但它们作为客户端控制运行。在非托管设备上，具有管理员或 sudo 访问权限的用户可以修改 Claude Code 二进制文件、文件系统或网络配置。259服务器管理的设置提供集中的策略强制执行，但它们作为客户端控制运行，而不是安全边界。在非托管设备上，用户不需要管理员或 sudo 访问权限来绕过它们。

257 260

258| 场景 | 行为 |261| 场景 | 行为 |

259| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |262| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

260| 用户编辑缓存的设置文件 | 篡改的文件在启动时应用，但正确的设置在下次服务器获取时恢复 |263| 用户编辑缓存的设置文件 | 篡改的文件在启动时应用，但正确的设置在下次服务器获取时恢复 |

261| 用户删除缓存的设置文件 | 首次启动行为发生：设置异步获取，有一个简短的未强制执行的窗口 |264| 用户删除缓存的设置文件 | 首次启动行为发生：设置异步获取，有一个简短的未强制执行的窗口 |

265| 用户运行修改的 Claude Code 二进制文件 | 能够运行修改的客户端的用户可以绕过任何客户端控制 |

266| 用户运行较旧的 Claude Code 版本 | 早于服务器管理设置的版本不会获取或应用它们 |

262| API 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |267| API 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |

263| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |268| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |

264| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非默认的 `ANTHROPIC_BASE_URL` |269| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非默认的 `ANTHROPIC_BASE_URL` |

270| 网络流量被拦截或重定向 | 禁用的 TLS 验证或拦截的流量可以改变客户端接收的设置 |

265 271

266要检测运行时配置更改，请使用 [`ConfigChange` hooks](/zh-CN/hooks#configchange) 来记录修改或在未授权的更改生效前阻止它们。272要检测运行时配置更改，请使用 [`ConfigChange` hooks](/zh-CN/hooks#configchange) 来记录修改或在未授权的更改生效前阻止它们。

267 273

268为了获得更强的强制执行保证，请在已在 MDM 解决方案中注册的设备上使用[端点管理的设置](/zh-CN/settings#settings-files)。274要限制用户可以使用客户端提供的凭证访问的组织，请参阅 Claude 帮助中心中的[使用租户限制强制执行网络级访问控制](https://support.claude.com/en/articles/13198485-enforce-network-level-access-control-with-tenant-restrictions)。为了获得更强的强制执行保证，请在已在 MDM 解决方案中注册的设备上使用[端点管理的设置](/zh-CN/settings#settings-files)。

269 275

270<h2 id="see-also">276<h2 id="see-also">

271 另请参阅277 另请参阅

sessions.md +8 −2

Details

30 会话选择器查看的位置30 会话选择器查看的位置

31</h3>31</h3>

32 32

33会话按项目目录存储。默认情况下，会话选择器显示来自当前 worktree 的交互式会话，以及在其他地方启动但使用 `/add-dir` 添加了当前目录的会话。从 v2.1.169 开始，使用 [`/cd`](/zh-CN/commands) 移动会话会将其重新定位到新目录的项目存储中，因此之后它会出现在该目录的选择器中。使用 `Ctrl+W` 扩展到存储库的所有 worktree，或使用 `Ctrl+A` 扩展到此计算机上的每个项目。33会话按项目目录存储。默认情况下，会话选择器显示来自当前 worktree 的交互式会话，以及在其他地方启动但使用 `/add-dir` 添加了当前目录的会话。使用 `Ctrl+W` 扩展到存储库的所有 worktree，或使用 `Ctrl+A` 扩展到此计算机上的每个项目。

35从 v2.1.169 开始，使用 [`/cd`](/zh-CN/commands) 移动会话会将其重新定位到新目录的项目存储中，因此之后它会出现在该目录的选择器中。从 v2.1.196 开始，移动的会话在崩溃或强制退出后会保持不在旧目录的选择器中。在较早的版本中，当旧路径包含下划线等特殊字符时，在不干净的退出后，它也可能在旧目录的列表中重新出现。

34 36

35从同一存储库的另一个 worktree 选择会话会在原地恢复它。从不相关项目选择会话会将 `cd` 和恢复命令复制到您的剪贴板。37从同一存储库的另一个 worktree 选择会话会在原地恢复它。从不相关项目选择会话会将 `cd` 和恢复命令复制到您的剪贴板。

36 38

56 58

57会话命名后，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它。有关名称解析如何跨 worktrees 工作的信息，请参阅[恢复会话](#resume-a-session)。59会话命名后，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它。有关名称解析如何跨 worktrees 工作的信息，请参阅[恢复会话](#resume-a-session)。

58 60

61{/* min-version: 2.1.196 */}您从未命名的交互式会话在启动时仍会获得默认显示名称。需要 Claude Code v2.1.196 或更高版本。默认名称将工作目录的名称与两个字符的后缀组合在一起，例如 `my-app-3f`，并在运行会话的列表中标识会话，例如 [agent view](/zh-CN/agent-view) 和 `claude agents --json` 输出。

63默认名称不是恢复句柄：`claude --resume <name>`、`/resume <name>` 和会话选择器仅匹配您设置的名称。命名会话会替换默认名称。

59<h2 id="use-the-session-picker">65<h2 id="use-the-session-picker">

60 使用会话选择器66 使用会话选择器

61</h2>67</h2>

117 导出和定位会话数据123 导出和定位会话数据

118</h2>124</h2>

119 125

120运行 `/export` 将当前对话复制到您的剪贴板或将其保存为纯文本文件，消息和工具输出呈现为可读文本。传递文件名以直接写入该文件。126运行 `/export` 打开一个菜单，让您将当前对话复制到剪贴板或将其保存为纯文本文件，消息和工具输出呈现为可读文本。传递文件名以跳过菜单并直接写入该文件。

121 127

122<h3 id="access-conversations-from-scripts">128<h3 id="access-conversations-from-scripts">

123 从脚本访问对话129 从脚本访问对话

settings.md +31 −25

Details

12 配置作用域12 配置作用域

13</h2>13</h2>

14 14

~~15Claude Code 使用**作用域系统**来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。~~15Claude Code 使用作用域系统来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。

16 16

17<h3 id="available-scopes">17<h3 id="available-scopes">

18 可用作用域18 可用作用域

97 * `.claude/settings.local.json` 用于未检入的设置，适用于个人偏好和实验。Claude Code 创建 `.claude/settings.local.json` 时，会配置 git 以忽略该文件。如果您自己创建该文件，请手动将其添加到 gitignore。97 * `.claude/settings.local.json` 用于未检入的设置，适用于个人偏好和实验。Claude Code 创建 `.claude/settings.local.json` 时，会配置 git 以忽略该文件。如果您自己创建该文件，请手动将其添加到 gitignore。

98* **Managed 设置**：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：98* **Managed 设置**：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：

99 99

100 * **服务器管理的设置**：通过 Claude.ai 管理员控制台从 Anthropic 的服务器交付。请参阅[服务器管理的设置](/zh-CN/server-managed-settings)。100 * **服务器管理的设置**：通过 Anthropic 的服务器从 claude.ai 管理员控制台交付，或从自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)。请参阅[服务器管理的设置](/zh-CN/server-managed-settings)。

101 * **MDM/OS 级别策略**：通过 macOS 和 Windows 上的本机设备管理交付：101 * **MDM/OS 级别策略**：通过 macOS 和 Windows 上的本机设备管理交付：

102 * macOS：`com.anthropic.claudecode` managed preferences 域。plist 的顶级键镜像 `managed-settings.json`，嵌套设置为字典，数组为 plist 数组。通过 Jamf、Iru (Kandji) 或类似 MDM 工具中的配置文件部署。102 * macOS：`com.anthropic.claudecode` managed preferences 域。plist 的顶级键镜像 `managed-settings.json`，嵌套设置为字典，数组为 plist 数组。通过 Jamf、Iru (Kandji) 或类似 MDM 工具中的配置文件部署。

103 * Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 注册表项，带有包含 JSON 的 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ）（通过组策略或 Intune 部署）103 * Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 注册表项，带有包含 JSON 的 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ）（通过组策略或 Intune 部署）

211`settings.json` 支持多个选项：211`settings.json` 支持多个选项：

212 212

213| 键 | 描述 | 示例 |213| 键 | 描述 | 示例 |

214| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |214| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |

215| `advisorModel` | {/* min-version: 2.1.98 */}服务器端 [advisor tool](/zh-CN/advisor) 的模型。接受模型别名，如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。当您运行 `/advisor` 时自动写入。取消设置以禁用 advisor。需要 Claude Code v2.1.98 或更高版本 | `"opus"` |215| `advisorModel` | {/* min-version: 2.1.98 */}服务器端 [advisor tool](/zh-CN/advisor) 的模型。接受模型别名，如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。当您运行 `/advisor` 时自动写入。取消设置以禁用 advisor。需要 Claude Code v2.1.98 或更高版本 | `"opus"` |

216| `agent` | 将主线程作为命名 subagent 运行，并为从 `claude agents` 分派的会话设置默认 agent。应用该 subagent 的系统提示、工具限制和模型。请参阅[显式调用 subagents](/zh-CN/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |216| `agent` | 将主线程作为命名 subagent 运行，并为从 `claude agents` 分派的会话设置默认 agent。应用该 subagent 的系统提示、工具限制和模型。请参阅[显式调用 subagents](/zh-CN/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

217| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，允许 Claude 向您的手机发送主动推送通知，例如当长任务完成时。在 `/config` 中显示为**Claude 决定时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |217| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，允许 Claude 向您的手机发送主动推送通知，例如当长任务完成时。在 `/config` 中显示为**Claude 决定时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |

230| `autoMemoryEnabled` | **默认**：`true`。启用[自动内存](/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不从自动内存目录读取或写入。您也可以在会话期间使用 `/memory` 切换此选项。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-CN/env-vars) | `false` |230| `autoMemoryEnabled` | **默认**：`true`。启用[自动内存](/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不从自动内存目录读取或写入。您也可以在会话期间使用 `/memory` 切换此选项。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-CN/env-vars) | `false` |

231| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |231| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

232| `autoMode.classifyAllShell` | {/* min-version: 2.1.193 */}**默认**：`false`。当为 `true` 时，在自动模式活跃时暂停每个 Bash 和 PowerShell 允许规则，以便所有 shell 命令通过分类器路由，而不仅仅是匹配任意代码执行模式的规则。请参阅[通过分类器路由所有 shell 命令](/zh-CN/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更高版本 | `true` |

233| `autoUpdatesChannel` | **默认**：`"latest"`。遵循更新的发布渠道。使用 `"stable"` 获取通常约一周前的版本并跳过有主要回归的版本，或使用 `"latest"` 获取最新版本。要完全禁用自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/zh-CN/setup#disable-auto-updates) | `"stable"` |234| `autoUpdatesChannel` | **默认**：`"latest"`。遵循更新的发布渠道。使用 `"stable"` 获取通常约一周前的版本并跳过有主要回归的版本，或使用 `"latest"` 获取最新版本。要完全禁用自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/zh-CN/setup#disable-auto-updates) | `"stable"` |

234| `availableModels` | 限制用户可以为主会话、[subagents](/zh-CN/sub-agents)、[skills](/zh-CN/skills) 和 [advisor](/zh-CN/advisor) 选择的模型。不影响默认选项，除非 `enforceAvailableModels` 也被设置。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |235| `availableModels` | 限制用户可以为主会话、[subagents](/zh-CN/sub-agents)、[skills](/zh-CN/skills) 和 [advisor](/zh-CN/advisor) 选择的模型。不影响默认选项，除非 `enforceAvailableModels` 也被设置。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

253| `disableDeepLinkRegistration` | 设置为 `"disable"` 以防止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理程序。[深链接](/zh-CN/deep-links)让外部工具通过预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中很有用 | `"disable"` |254| `disableDeepLinkRegistration` | 设置为 `"disable"` 以防止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理程序。[深链接](/zh-CN/deep-links)让外部工具通过预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中很有用 | `"disable"` |

255| `disableRemoteControl` | {/* min-version: 2.1.128 */}禁用[远程控制](/zh-CN/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[managed 设置](/zh-CN/permissions#managed-settings)中用于每设备 MDM 强制执行，但适用于任何作用域。需要 Claude Code v2.1.128 或更高版本 | `true` |256| `disableRemoteControl` | {/* min-version: 2.1.128 */}禁用[远程控制](/zh-CN/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[managed 设置](/zh-CN/permissions#managed-settings)中用于每设备 MDM 强制执行，但适用于任何作用域。需要 Claude Code v2.1.128 或更高版本 | `true` |

257| `disableSideloadFlags` | {/* min-version: 2.1.193 */}（仅 Managed 设置）在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志，用户可能会传递这些标志以绕过单次运行的 [`strictKnownMarketplaces`](#strictknownmarketplaces)。也拒绝从任何内部生成带有它们的 CLI 的表面这些标志，当前 [Cowork](/zh-CN/desktop) 桌面应用中的本地会话。其服务器都是进程内 `type: "sdk"` 条目的 `--mcp-config` 仍被接受，因此 Agent SDK 和 VS Code 扩展保持工作。不阻止 `claude mcp add`、`.mcp.json` 或 SDK `setMcpServers()`；与 [`allowedMcpServers`](/zh-CN/managed-mcp) 配对以获得每个 server 的 MCP 控制。需要 Claude Code v2.1.193 或更高版本 | `true` |

256| `disableSkillShellExecution` | 禁用 [skills](/zh-CN/skills) 和来自用户、项目、插件或额外目录源的自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和 managed skills 不受影响。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `true` |258| `disableSkillShellExecution` | 禁用 [skills](/zh-CN/skills) 和来自用户、项目、插件或额外目录源的自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和 managed skills 不受影响。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `true` |

258| `editorMode` | **默认**：`"normal"`。输入提示的快捷键模式：`"normal"` 或 `"vim"`。在 `/config` 中显示为**快捷键模式** | `"vim"` |260| `editorMode` | **默认**：`"normal"`。输入提示的快捷键模式：`"normal"` 或 `"vim"`。在 `/config` 中显示为**快捷键模式** | `"vim"` |

259| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |261| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |

260| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers | `true` |262| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `true` |

261| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP servers 的列表 | `["memory", "github"]` |263| `enableArtifact` | {/* min-version: 2.1.196 */}为此用户启用或禁用 [Artifact](/zh-CN/artifacts) 工具。未设置时，默认遵循该功能对您账户的[可用性](/zh-CN/artifacts#availability)。`/config` 中的**Artifacts** 行写入此键。managed `disableArtifact` 和您的组织的[管理员设置](/zh-CN/artifacts#manage-artifacts-for-your-organization)优先，该键在项目和本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，存储库可能会检入。需要 Claude Code v2.1.196 或更高版本 | `true` |

264| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP servers 的列表。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `["memory", "github"]` |

262| `enforceAvailableModels` | {/* min-version: 2.1.175 */}将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |265| `enforceAvailableModels` | {/* min-version: 2.1.175 */}将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |

263| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色 | `{"FOO": "bar"}` |266| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Claude Code 的托管环境设置的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，在此处设置时被忽略 | `{"FOO": "bar"}` |

264| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |267| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |

265| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |268| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |

266| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-CN/env-vars)。在使用 Bedrock、Vertex 或 Foundry 时很有用，其中默认采样率不适用 | `0.05` |269| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-CN/env-vars)。在使用 Bedrock、Vertex 或 Foundry 时很有用，其中默认采样率不适用 | `0.05` |

267| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。在每次编辑前快照文件，以便 [`/rewind`](/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（checkpoints）**。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-CN/env-vars) | `false` |270| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。在每次编辑前快照文件，以便 [`/rewind`](/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（checkpoints）**。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-CN/env-vars) | `false` |

268| `fileSuggestion` | 为 `@` 文件自动完成配置自定义脚本。请参阅[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |271| `fileSuggestion` | 为 `@` 文件自动完成配置自定义脚本。请参阅[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

269| `footerLinksRegexes` | {/* min-version: 2.1.176 */}当正则表达式匹配轮次输出时渲染额外的可点击徽章在页脚中。每个条目有一个 `pattern`、一个 URL 模板，其中 `{name}` 占位符从命名捕获组填充，以及一个可选的 `label`。仅从用户、`--settings` 标志和 managed 设置读取。请参阅[页脚链接徽章](#footer-link-badges)了解 URL 约束、方案允许列表和限制。需要 Claude Code v2.1.176 或更高版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |272| `footerLinksRegexes` | {/* min-version: 2.1.176 */}当正则表达式匹配轮次输出时渲染额外的可点击徽章在页脚中。每个条目有一个 `pattern`、一个 URL 模板，其中 `{name}` 占位符从命名捕获组填充，以及一个可选的 `label`。仅从用户、`--settings` 标志和 managed 设置读取。请参阅[页脚链接徽章](#footer-link-badges)了解 URL 约束、方案允许列表和限制。需要 Claude Code v2.1.176 或更高版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

270| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console 账户。在 managed 设置中设置时，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为两个值都无法在没有第一方 OAuth 的情况下满足。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：它们针对您的云提供商而不是 Anthropic 进行身份验证 | `claudeai` |273| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console 账户，或 `gateway` 限制登录到云网关；请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway)。在 managed 设置中设置为任何值时，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为环境凭证无法满足所需的登录方法。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：它们针对您的云提供商而不是 Anthropic 进行身份验证 | `claudeai` |

274| `forceLoginGatewayUrl` | 在 `/login` 云网关屏幕上预填充并锁定网关 URL。此键或 `forceLoginMethod: "gateway"` 中的任一个都会显示该屏幕；同时设置两者以便 URL 被填充。仅在 managed 策略层受尊重；在用户和项目设置中被忽略。请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |

271| `forceLoginOrgUUID` | 要求登录属于特定 Anthropic 组织。接受单个 UUID 字符串（也在登录期间预选该组织）或 UUID 数组，其中任何列出的组织都被接受而无需预选。在 managed 设置中设置时，如果经过身份验证的账户不属于列出的组织，登录失败；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为无法为它们验证组织成员身份。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：使用您的云 IAM 限制哪些云账户可以被使用。空数组失败关闭并使用配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |275| `forceLoginOrgUUID` | 要求登录属于特定 Anthropic 组织。接受单个 UUID 字符串（也在登录期间预选该组织）或 UUID 数组，其中任何列出的组织都被接受而无需预选。在 managed 设置中设置时，如果经过身份验证的账户不属于列出的组织，登录失败；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为无法为它们验证组织成员身份。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：使用您的云 IAM 限制哪些云账户可以被使用。空数组失败关闭并使用配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

272| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |276| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |

273| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/zh-CN/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |277| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/zh-CN/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

276| `includeGitInstructions` | **默认**：`true`。在 Claude 的系统提示中包含内置提交和 PR 工作流说明和 git 状态快照。设置为 `false` 以删除这两者，例如在使用您自己的 git 工作流 skills 时。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 环境变量在设置时优先于此设置 | `false` |280| `includeGitInstructions` | **默认**：`true`。在 Claude 的系统提示中包含内置提交和 PR 工作流说明和 git 状态快照。设置为 `false` 以删除这两者，例如在使用您自己的 git 工作流 skills 时。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 环境变量在设置时优先于此设置 | `false` |

277| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，当权限提示或问题等待您的输入时向您的手机发送推送通知。在 `/config` 中显示为**需要操作时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |281| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，当权限提示或问题等待您的输入时向您的手机发送推送通知。在 `/config` 中显示为**需要操作时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |

278| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/zh-CN/voice-dictation#change-the-dictation-language)语言和自动生成的会话标题。{/* min-version: 2.1.176 */}从 v2.1.176 开始，未设置时，会话标题与您的对话语言匹配 | `"japanese"` |282| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/zh-CN/voice-dictation#change-the-dictation-language)语言和自动生成的会话标题。{/* min-version: 2.1.176 */}从 v2.1.176 开始，未设置时，会话标题与您的对话语言匹配 | `"japanese"` |

279| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}**默认**：`1536`。[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)中每个 skill 的 `description` 和 `when_to_use` 文本组合的字符上限。超过此长度的文本被截断。提高以保持长描述完整，代价是每轮更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下适应更多 skills。需要 Claude Code v2.1.105 或更高版本 | `2048` |

280| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本。对于阻止启动的硬下限，请参阅 `requiredMinimumVersion` | `"2.1.100"` |283| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本。对于阻止启动的硬下限，请参阅 `requiredMinimumVersion` | `"2.1.100"` |

282| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |285| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

283| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |286| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

300| `showThinkingSummaries` | **默认**：`false`。在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false` 时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |303| `showThinkingSummaries` | **默认**：`false`。在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false` 时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |

302| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**默认**：`0.01`（1%）。为[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)预留的模型上下文窗口的分数，Claude 每轮看到。当列表超过预算时，最少使用的 skills 的描述被折叠为仅名称，以便 Claude 仍可以调用它们但不会看到原因。提高以保持更多描述可见，代价是每轮更多上下文。`/doctor` 显示当前截断计数和受影响的 skills。需要 Claude Code v2.1.105 或更高版本 | `0.02` |305| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**默认**：`0.01`（1%）。为[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)预留的模型上下文窗口的分数，Claude 每轮看到。当列表超过预算时，最少使用的 skills 的描述被折叠为仅名称，以便 Claude 仍可以调用它们但不会看到原因。提高以保持更多描述可见，代价是每轮更多上下文。`/doctor` 显示当前截断计数和受影响的 skills。需要 Claude Code v2.1.105 或更高版本 | `0.02` |

306| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**默认**：`1536`。[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)中每个 skill 的 `description` 和 `when_to_use` 文本组合的字符上限。超过此长度的文本被截断。提高以保持长描述完整，代价是每轮更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下适应更多 skills。需要 Claude Code v2.1.105 或更高版本 | `2048` |

303| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名称键入的每个 skill 可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让您隐藏或折叠 skill 而无需编辑其 SKILL.md。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |307| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名称键入的每个 skill 可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让您隐藏或折叠 skill 而无需编辑其 SKILL.md。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

304| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |308| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |

306| `spinnerTipsOverride` | 使用自定义字符串覆盖微调器提示。`tips`：提示字符串数组。`excludeDefault`：如果为 `true`，仅显示自定义提示；如果为 `false` 或不存在，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |310| `spinnerTipsOverride` | 使用自定义字符串覆盖微调器提示。`tips`：提示字符串数组。`excludeDefault`：如果为 `true`，仅显示自定义提示；如果为 `false` 或不存在，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

307| `spinnerVerbs` | 自定义在微调器中显示的操作动词。将 `mode` 设置为 `"replace"` 以仅使用您的动词，或 `"append"` 以将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |311| `spinnerVerbs` | 自定义在微调器中显示的操作动词。将 `mode` 设置为 `"replace"` 以仅使用您的动词，或 `"append"` 以将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

308| `sshConfigs` | 要在[桌面](/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉菜单中显示的 SSH 连接。每个条目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是可选的。在 managed 设置中设置时，连接对用户是只读的。仅从 managed 和用户设置读取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |312| `sshConfigs` | 要在[桌面](/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉菜单中显示的 SSH 连接。每个条目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是可选的。在 managed 设置中设置时，连接对用户是只读的。仅从 managed 和用户设置读取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

309| `statusLine` | 配置自定义状态行以显示上下文。请参阅[`statusLine` 文档](/zh-CN/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |313| `statusLine` | 配置自定义状态行以显示上下文。对象的可选 `padding`、`refreshInterval` 和 `hideVimModeIndicator` 字段控制间距、定期重新运行和是否隐藏提示下方的内置 vim 模式指示器。请参阅[`statusLine` 文档](/zh-CN/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

310| `strictKnownMarketplaces` | （仅 Managed 设置）插件市场源的允许列表。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |314| `strictKnownMarketplaces` | （仅 Managed 设置）插件市场源的允许列表。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

311| `strictPluginOnlyCustomization` | （仅 Managed 设置）阻止 skills、agents、hooks 和 MCP servers 来自用户和项目源，因此它们只能来自插件或 managed 设置。`true` 锁定所有四个表面；数组仅锁定命名的表面。请参阅 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |315| `strictPluginOnlyCustomization` | （仅 Managed 设置）阻止 skills、agents、hooks 和 MCP servers 来自用户和项目源，因此它们只能来自插件或 managed 设置。`true` 锁定所有四个表面；数组仅锁定命名的表面。请参阅 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |

331这些设置存储在 `~/.claude.json` 中，而不是 `settings.json`。将它们添加到 `settings.json` 将触发架构验证错误。335这些设置存储在 `~/.claude.json` 中，而不是 `settings.json`。将它们添加到 `settings.json` 将触发架构验证错误。

332 336

333<Note>337<Note>

334 v2.1.119 之前的版本也在此处而不是在 `settings.json` 中存储 `theme`、`verbose`、`editorMode`、`autoCompactEnabled` 和 `preferredNotifChannel`。338 v2.1.119 之前的版本也在此处而不是在 `settings.json` 中存储多个 `/config` 偏好键，包括 `theme`、`verbose`、`editorMode`、`autoCompactEnabled` 和 `preferredNotifChannel`。

335</Note>339</Note>

336 340

337| 键 | 描述 | 示例 |341| 键 | 描述 | 示例 |

483**默认提交归属：**487**默认提交归属：**

484 488

485```text theme={null}489```text theme={null}

486Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>490Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

487```491```

488 492

489会话的活跃模型在 trailer 中反映。493会话的活跃模型在 trailer 中反映。

653 657

654设置按优先级顺序应用。从最高到最低：658设置按优先级顺序应用。从最高到最低：

655 659

6561. **Managed 设置**（[服务器管理](/zh-CN/server-managed-settings)、[MDM/OS 级别策略](#configuration-scopes) 或 [managed 设置](/zh-CN/settings#settings-files)）6601. **Managed 设置**（[服务器管理](/zh-CN/server-managed-settings)、[MDM/OS 级别策略](#configuration-scopes) 或 [managed 设置](#settings-files)）

657 * 由 IT 通过服务器交付、MDM 配置文件、注册表策略或 managed 设置文件部署的策略661 * 由 IT 通过服务器交付、MDM 配置文件、注册表策略或 managed 设置文件部署的策略

658 * 无法被任何其他级别覆盖，包括命令行参数662 * 无法被任何其他级别覆盖，包括命令行参数

659 * 在 managed 层内，优先级为：server-managed > MDM/OS 级别策略 > 基于文件（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 注册表（仅 Windows）。仅使用一个 managed 源；源不合并跨层。在基于文件的层内，放入文件和基础文件被合并在一起。663 * 在 managed 层内，优先级为：[`policyHelper`](#compute-managed-settings-with-a-policy-helper) 输出，当配置时是唯一使用的 managed 源 > 远程（claude.ai [服务器管理](/zh-CN/server-managed-settings)或 [Claude apps gateway](/zh-CN/claude-apps-gateway) 交付）> MDM/OS 级别策略 > 基于文件（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 注册表（仅 Windows）。仅使用一个 managed 源；源不合并跨层，有一个例外：sandbox 锁定键 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，带有其关联的允许列表，`allowAllClaudeAiMcps` 和 sandbox 二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath` 在任何管理员控制的 managed 源设置它们时被尊重；用户可写的 HKCU 层被排除。在基于文件的层内，放入文件和基础文件被合并在一起。

660 * 嵌入主机（如 Claude Desktop）可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何 managed-settings 层时，这被忽略。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。664 * 嵌入主机（如 Claude Desktop）可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何管理员部署的 managed 源时，这被忽略：服务器管理的设置、MDM 或 OS 级别策略或 managed 设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。

661 665

6622. **命令行参数**6662. **命令行参数**

663 * 特定会话的临时覆盖。通过 `--settings <file-or-json>` 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并：此处设置的键覆盖本地、项目或用户设置中的相同键，省略键会保留较低层的值667 * 特定会话的临时覆盖。通过 `--settings <file-or-json>` 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并：此处设置的键覆盖本地、项目或用户设置中的相同键，省略键会保留较低层的值

711 715

712Claude Code 的内部系统提示未发布。要添加自定义说明，请使用 `CLAUDE.md` 文件或 `--append-system-prompt` 标志。716Claude Code 的内部系统提示未发布。要添加自定义说明，请使用 `CLAUDE.md` 文件或 `--append-system-prompt` 标志。

713 717

714<h3 id="excluding-sensitive-files">718<h3 id="exclude-sensitive-files">

715 排除敏感文件719 排除敏感文件

716</h3>720</h3>

717 721

739 743

740Claude Code 支持可在用户和项目级别配置的自定义 AI subagents。这些 subagents 存储为带有 YAML frontmatter 的 Markdown 文件：744Claude Code 支持可在用户和项目级别配置的自定义 AI subagents。这些 subagents 存储为带有 YAML frontmatter 的 Markdown 文件：

741 745

742* **用户 subagents**：`~/.claude/agents/` - 在所有项目中可用746* **用户 subagents**：`~/.claude/agents/`，在所有项目中可用

743* **项目 subagents**：`.claude/agents/` - 特定于您的项目，可与您的团队共享747* **项目 subagents**：`.claude/agents/`，特定于您的项目，可与您的团队共享

744 748

745Subagent 文件定义具有自定义提示和工具权限的专门 AI 助手。在 [subagents 文档](/zh-CN/sub-agents)中了解有关创建和使用 subagents 的更多信息。749Subagent 文件定义具有自定义提示和工具权限的专门 AI 助手。在 [subagents 文档](/zh-CN/sub-agents)中了解有关创建和使用 subagents 的更多信息。

746 750

791 项目设置优先于用户设置，因此在 `~/.claude/settings.json` 中将插件设置为 `false` 不会禁用项目的 `.claude/settings.json` 启用的插件。要在您的机器上选择退出项目启用的插件，请改为在 `.claude/settings.local.json` 中将其设置为 `false`。795 项目设置优先于用户设置，因此在 `~/.claude/settings.json` 中将插件设置为 `false` 不会禁用项目的 `.claude/settings.json` 启用的插件。要在您的机器上选择退出项目启用的插件，请改为在 `.claude/settings.local.json` 中将其设置为 `false`。

792 796

793 由 managed 设置强制启用的插件无法以这种方式禁用，因为 managed 设置会覆盖本地设置。797 由 managed 设置强制启用的插件无法以这种方式禁用，因为 managed 设置会覆盖本地设置。

798

799 从外部源（如 GitHub 存储库或 npm 包）在项目的 `.claude/settings.json` 中启用插件不会为其他人安装它。从 Claude Code v2.1.195 开始，加载插件的每条路径都会要求每个用户在运行前[安装并信任插件](/zh-CN/discover-plugins#configure-team-marketplaces)。

794</Note>800</Note>

795 801

796**示例**：802**示例**：

914{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }920{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

915```921```

916 922

917字段：`repo`（必需）、`ref`（可选：分支/标签/SHA）、`path`（可选：子目录）923字段：`repo`（必需）、`ref`（可选：分支或标签）、`path`（可选：子目录）

918 924

9192. **Git 存储库**：9252. **Git 存储库**：

920 926

924{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }930{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

925```931```

926 932

927字段：`url`（必需）、`ref`（可选：分支/标签/SHA）、`path`（可选：子目录）933字段：`url`（必需）、`ref`（可选：分支或标签）、`path`（可选：子目录）

928 934

9293. **基于 URL 的市场**：9353. **基于 URL 的市场**：

930 936

1023}1029}

1024```1030```

1025 1031

1026示例 - 禁用所有市场添加：1032示例：禁用所有市场添加：

1027 1033

1028```json theme={null}1034```json theme={null}

1029{1035{

1046 1052

1047**精确匹配要求**：1053**精确匹配要求**：

1048 1054

1049市场源必须**精确**匹配才能允许用户的添加。对于基于 git 的源（`github` 和 `git`），这包括所有可选字段：1055市场源必须精确匹配才能允许用户的添加。对于基于 git 的源（`github` 和 `git`），这包括所有可选字段：

1050 1056

1051* `repo` 或 `url` 必须精确匹配1057* `repo` 或 `url` 必须精确匹配

1052* `ref` 字段必须精确匹配（或两者都未定义）1058* `ref` 字段必须精确匹配（或两者都未定义）

1053* `path` 字段必须精确匹配（或两者都未定义）1059* `path` 字段必须精确匹配（或两者都未定义）

1054 1060

1055**不匹配**的源示例：1061不匹配的源示例：

1056 1062

1057```json theme={null}1063```json theme={null}

1058// 这些是不同的源：1064// 这些是不同的源：

1157 1163

1158Claude Code 版本不识别的表面名称被忽略而不是导致设置文件失败，因此您可以在所有客户端更新之前添加新的表面名称。1164Claude Code 版本不识别的表面名称被忽略而不是导致设置文件失败，因此您可以在所有客户端更新之前添加新的表面名称。

1159 1165

1160<h3 id="managing-plugins">1166<h3 id="manage-plugins">

1161 管理插件1167 管理插件

1162</h3>1168</h3>

1163 1169

setup.md +1 −1

Details

36</h2>36</h2>

37 37

38<Tip>38<Tip>

39 更喜欢图形界面？[桌面应用](/zh-CN/desktop-quickstart)让您无需使用终端即可使用 Claude Code。下载适用于 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本。39 更喜欢图形界面？[桌面应用](/zh-CN/desktop-quickstart)让您无需使用终端即可使用 Claude Code。下载适用于 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)、[Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 或 [Linux](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本。

40 40

41 初次使用终端？请参阅[终端指南](/zh-CN/terminal-guide)获取分步说明。41 初次使用终端？请参阅[终端指南](/zh-CN/terminal-guide)获取分步说明。

42</Tip>42</Tip>

skills.md +9 −4

Details

245所有字段都是可选的。建议使用 `description`，以便 Claude 知道何时使用该 skill。245所有字段都是可选的。建议使用 `description`，以便 Claude 知道何时使用该 skill。

246 246

247| 字段 | 必需 | 描述 |247| 字段 | 必需 | 描述 |

248| :------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |248| :------------------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

249| `name` | 否 | Skill 列表中显示的显示名称。默认为目录名称。请参阅[Skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解这与你输入的名称在 `/` 后的调用方式有何不同。 |249| `name` | 否 | Skill 列表中显示的显示名称。默认为目录名称。请参阅[Skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解这与你输入的名称在 `/` 后的调用方式有何不同。 |

250| `description` | 推荐 | Skill 的功能以及何时使用它。Claude 使用它来决定何时应用该 skill。如果省略，使用 markdown 内容的第一段。将关键用例放在前面：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |250| `description` | 推荐 | Skill 的功能以及何时使用它。Claude 使用它来决定何时应用该 skill。如果省略，使用 markdown 内容的第一段。将关键用例放在前面：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |

251| `when_to_use` | 否 | 关于 Claude 何时应该调用该 skill 的额外上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 个字符的上限。 |251| `when_to_use` | 否 | 关于 Claude 何时应该调用该 skill 的额外上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 个字符的上限。 |

252| `argument-hint` | 否 | 自动完成期间显示的提示，指示预期的参数。示例：`[issue-number]` 或 `[filename] [format]`。 |252| `argument-hint` | 否 | 自动完成期间显示的提示，指示预期的参数。示例：`[issue-number]` 或 `[filename] [format]`。 |

253| `arguments` | 否 | 用于 skill 内容中[`$name` 替换](#available-string-substitutions)的命名位置参数。接受空格分隔的字符串或 YAML 列表。名称按顺序映射到参数位置。 |253| `arguments` | 否 | 用于 skill 内容中[`$name` 替换](#available-string-substitutions)的命名位置参数。接受空格分隔的字符串或 YAML 列表。名称按顺序映射到参数位置。 |

254| `disable-model-invocation` | 否 | 设置为 `true` 以防止 Claude 自动加载此 skill。用于你想使用 `/name` 手动触发的工作流。也防止该 skill 被[预加载到 subagents](/zh-CN/sub-agents#preload-skills-into-subagents) 中。默认值：`false`。 |254| `disable-model-invocation` | 否 | 设置为 `true` 以防止 Claude 自动加载此 skill。用于你想使用 `/name` 手动触发的工作流。也防止该 skill 被[预加载到 subagents](/zh-CN/sub-agents#preload-skills-into-subagents) 中。从 v2.1.196 开始，也防止该 skill 在[计划任务](/zh-CN/scheduled-tasks)使用该 skill 作为其提示时运行。默认值：`false`。 |

255| `user-invocable` | 否 | 设置为 `false` 以从 `/` 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：`true`。 |255| `user-invocable` | 否 | 设置为 `false` 以从 `/` 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：`true`。 |

256| `allowed-tools` | 否 | 当此 skill 处于活动状态时，Claude 可以使用而无需请求权限的工具。接受空格分隔的字符串或 YAML 列表。 |256| `allowed-tools` | 否 | 当此 skill 处于活动状态时，Claude 可以使用而无需请求权限的工具。接受空格分隔的字符串或 YAML 列表。 |

257| `disallowed-tools` | 否 | 当此 skill 处于活动状态时从 Claude 的可用工具池中移除的工具。用于不应该调用某些工具的自主 skills，例如用于后台循环的 `AskUserQuestion`。接受空格分隔的字符串或 YAML 列表。当你发送下一条消息时，限制会清除。 |257| `disallowed-tools` | 否 | 当此 skill 处于活动状态时从 Claude 的可用工具池中移除的工具。用于不应该调用某些工具的自主 skills，例如用于后台循环的 `AskUserQuestion`。接受空格分隔的字符串或 YAML 列表。当你发送下一条消息时，限制会清除。 |

288Skills 支持 skill 内容中动态值的字符串替换：288Skills 支持 skill 内容中动态值的字符串替换：

289 289

290| 变量 | 描述 |290| 变量 | 描述 |

291| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |291| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

294| `$N` | `$ARGUMENTS[N]` 的简写，如 `$0` 表示第一个参数或 `$1` 表示第二个参数。 |294| `$N` | `$ARGUMENTS[N]` 的简写，如 `$0` 表示第一个参数或 `$1` 表示第二个参数。 |

296| `${CLAUDE_SESSION_ID}` | 当前会话 ID。适用于日志记录、创建会话特定文件或将 skill 输出与会话关联。 |296| `${CLAUDE_SESSION_ID}` | 当前会话 ID。适用于日志记录、创建会话特定文件或将 skill 输出与会话关联。 |

297| `${CLAUDE_EFFORT}` | 当前工作量级别：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一个不同的级别，报告为 `xhigh`。使用此来根据活动工作量设置调整 skill 说明。 |297| `${CLAUDE_EFFORT}` | 当前工作量级别：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一个不同的级别，报告为 `xhigh`。使用此来根据活动工作量设置调整 skill 说明。 |

298| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 文件的目录。对于插件 skills，这是插件内 skill 的子目录，而不是插件根目录。在 bash 注入命令中使用它来引用与 skill 捆绑的脚本或文件，无论当前工作目录如何。 |298| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 文件的目录。对于插件 skills，这是插件内 skill 的子目录，而不是插件根目录。在 bash 注入命令中使用它来引用与 skill 捆绑的脚本或文件，无论当前工作目录如何。 |

299| `${CLAUDE_PROJECT_DIR}` | 项目根目录。这是与 [hooks](/zh-CN/hooks#reference-scripts-by-path) 和 MCP 服务器相同的路径，作为 `CLAUDE_PROJECT_DIR` 接收。使用此来引用项目本地脚本或文件，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，独立于 skill 的安装位置。 |

300

301`${CLAUDE_PROJECT_DIR}` 替换需要 Claude Code v2.1.196 或更高版本。它适用于 skill 主体和 [`allowed-tools`](#frontmatter-reference) frontmatter，因此权限规则如 `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` 解析为 skill 主体使用的相同路径。

299 302

300索引参数使用 shell 风格的引用，因此用引号包装多词值以将其作为单个参数传递。例如，`/my-skill "hello world" second` 使 `$0` 扩展为 `hello world`，`$1` 扩展为 `second`。`$ARGUMENTS` 占位符始终扩展为完整的参数字符串，如输入的那样。303索引参数使用 shell 风格的引用，因此用引号包装多词值以将其作为单个参数传递。例如，`/my-skill "hello world" second` 使 `$0` 扩展为 `hello world`，`$1` 扩展为 `second`。`$ARGUMENTS` 占位符始终扩展为完整的参数字符串，如输入的那样。

301 304

899 902

900Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算按模型上下文窗口的 1% 进行扩展。当预算溢出时，你调用最少的 skills 的描述会首先被删除，因此你实际使用的 skills 会保留其完整文本。运行 `/doctor` 以查看有多少 skill 描述被缩短或删除以及哪些 skills 受到影响。903Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算按模型上下文窗口的 1% 进行扩展。当预算溢出时，你调用最少的 skills 的描述会首先被删除，因此你实际使用的 skills 会保留其完整文本。运行 `/doctor` 以查看有多少 skill 描述被缩短或删除以及哪些 skills 受到影响。

901 904

902要提高预算，设置 [`skillListingBudgetFraction`](/zh-CN/settings#available-settings) 设置（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量为固定字符数。要为其他 skills 释放预算，在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将低优先级条目设置为 `"name-only"`，以便它们列出而不显示描述。你也可以在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。该限制可通过 [`maxSkillDescriptionChars`](/zh-CN/settings#available-settings) 进行配置。905从 v2.1.196 开始，`/context` 中的 Skills 行报告应用预算后的列表大小，因此它与模型接收的内容相匹配。早期版本计算每个描述的完整文本，因此该行可能显示的值比预算 `/doctor` 报告的值大几倍。

906

907要提高预算，设置 [`skillListingBudgetFraction`](/zh-CN/settings#available-settings) 设置（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量为固定字符数。要为其他 skills 释放预算，在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将低优先级条目设置为 `"name-only"`，以便它们列出而不显示描述。你也可以在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。该限制可通过 [`skillListingMaxDescChars`](/zh-CN/settings#available-settings) 进行配置。

903 908

904<h2 id="related-resources">909<h2 id="related-resources">

905 相关资源910 相关资源

statusline.md +4 −1

Details

171Claude Code 通过 stdin 向你的脚本发送以下 JSON 字段：171Claude Code 通过 stdin 向你的脚本发送以下 JSON 字段：

172 172

173| 字段 | 描述 |173| 字段 | 描述 |

174| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |174| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

197| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 OpenTelemetry 事件上的 [`prompt.id` 属性](/zh-CN/monitoring-usage#event-correlation-attributes)匹配。在第一次用户输入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本 |

215 "cwd": "/current/working/directory",216 "cwd": "/current/working/directory",

216 "session_id": "abc123...",217 "session_id": "abc123...",

217 "session_name": "my-session",218 "session_name": "my-session",

219 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",

218 "transcript_path": "/path/to/transcript.jsonl",220 "transcript_path": "/path/to/transcript.jsonl",

219 "model": {221 "model": {

220 "id": "claude-opus-4-8",222 "id": "claude-opus-4-8",

296 **可能不存在的字段**（不在 JSON 中）：298 **可能不存在的字段**（不在 JSON 中）：

297 299

298 * `session_name`：仅在使用 `--name` 或 `/rename` 设置自定义名称时出现300 * `session_name`：仅在使用 `--name` 或 `/rename` 设置自定义名称时出现

301 * `prompt_id`：仅在第一次用户输入后出现

299 * `workspace.git_worktree`：仅当当前目录在链接的 git worktree 内时出现302 * `workspace.git_worktree`：仅当当前目录在链接的 git worktree 内时出现

300 * `workspace.repo`：仅在 git 存储库内且配置了 `origin` 远程时出现303 * `workspace.repo`：仅在 git 存储库内且配置了 `origin` 远程时出现

301 * `effort`：仅当当前模型支持推理工作量参数时出现304 * `effort`：仅当当前模型支持推理工作量参数时出现

sub-agents.md +36 −24

Details

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

40 40

41 * **Model**: Haiku（快速、低延迟）41 * **Model**: Haiku（快速、低延迟）

~~42 * **Tools**: 只读工具（拒绝访问 Write 和 Edit 工具）~~42 * **Tools**: 只读工具；拒绝访问 Write 和 Edit

43 * **Purpose**: 文件发现、代码搜索、代码库探索43 * **Purpose**: 文件发现、代码搜索、代码库探索

44 44

45 当 Claude 需要搜索或理解代码库而不进行更改时，它会委托给 Explore。这样可以将探索结果保持在主对话上下文之外。45 当 Claude 需要搜索或理解代码库而不进行更改时，它会委托给 Explore。这样可以将探索结果保持在主对话上下文之外。

51 一个研究代理，在 [plan mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 期间使用，以在呈现计划之前收集上下文。51 一个研究代理，在 [plan mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 期间使用，以在呈现计划之前收集上下文。

52 52

53 * **Model**: 从主对话继承53 * **Model**: 从主对话继承

~~54 * **Tools**: 只读工具（拒绝访问 Write 和 Edit 工具）~~54 * **Tools**: 只读工具；拒绝访问 Write 和 Edit

55 * **Purpose**: 用于规划的代码库研究55 * **Purpose**: 用于规划的代码库研究

56 56

57 当您处于 plan mode 并且 Claude 需要理解您的代码库时，它会将研究委托给 Plan subagent，以便探索输出保持在单独的上下文窗口中，而主对话保持只读。57 当您处于 plan mode 并且 Claude 需要理解您的代码库时，它会将研究委托给 Plan subagent，以便探索输出保持在单独的上下文窗口中，而主对话保持只读。

77 </Tab>77 </Tab>

78</Tabs>78</Tabs>

79 79

80内置 subagents 在交互式会话中始终被注册。要阻止特定的内置类型，请将其添加到 `permissions.deny`，如[禁用特定 subagents](#disable-specific-subagents) 中所示。要防止 Claude 委托给任何 subagent，请使用 [`permissions.deny`](/zh-CN/permissions#tool-specific-permission-rules) 拒绝 `Agent` 工具本身。在[非交互模式](/zh-CN/headless) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，设置 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-CN/env-vars) 以移除所有内置类型并仅提供您自己的。80内置 subagents 在交互式会话中始终被注册。要限制它们：

82* 要阻止特定的内置类型，请将其添加到 `permissions.deny`，如[禁用特定 subagents](#disable-specific-subagents) 中所示。

83* 要防止 Claude 委托给任何 subagent，请使用 [`permissions.deny`](/zh-CN/permissions#tool-specific-permission-rules) 拒绝 `Agent` 工具本身。

84* 在[非交互模式](/zh-CN/headless) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，设置 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-CN/env-vars) 以移除所有内置类型并仅提供您自己的。

81 85

82除了这些内置 subagents，您可以创建自己的，具有自定义提示、工具限制、权限模式、hooks 和 skills。以下部分展示了如何开始和自定义 subagents。86除了这些内置 subagents，您可以创建自己的，具有自定义提示、工具限制、权限模式、hooks 和 skills。以下部分展示了如何开始和自定义 subagents。

83 87

93 <Step title="打开 subagents 界面">97 <Step title="打开 subagents 界面">

94 在 Claude Code 中，运行：98 在 Claude Code 中，运行：

95 99

~~96 ```text theme={null}~~100 ```text wrap theme={null}

97 /agents101 /agents

98 ```102 ```

99 </Step>103 </Step>

105 <Step title="使用 Claude 生成">109 <Step title="使用 Claude 生成">

106 选择 **Generate with Claude**。出现提示时，描述 subagent：110 选择 **Generate with Claude**。出现提示时，描述 subagent：

107 111

108 ```text theme={null}112 ```text wrap theme={null}

109 A code improvement agent that scans files and suggests improvements113 A code improvement agent that scans files and suggests improvements

110 for readability, performance, and best practices. It should explain114 for readability, performance, and best practices. It should explain

111 each issue, show the current code, and provide an improved version.115 each issue, show the current code, and provide an improved version.

133 <Step title="保存并尝试">137 <Step title="保存并尝试">

134 查看配置摘要。按 `s` 或 `Enter` 保存，或按 `e` 在编辑器中保存并编辑文件。Subagent 立即可用。尝试它：138 查看配置摘要。按 `s` 或 `Enter` 保存，或按 `e` 在编辑器中保存并编辑文件。Subagent 立即可用。尝试它：

135 139

136 ```text theme={null}140 ```text wrap theme={null}

137 Use the code-improver agent to suggest improvements in this project141 Use the code-improver agent to suggest improvements in this project

138 ```142 ```

139 143

167 选择 subagent 范围171 选择 subagent 范围

168</h3>172</h3>

169 173

170Subagents 是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。当多个 subagents 共享相同的名称时，更高优先级的位置获胜。174Subagents 是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。当多个 subagents 共享相同的名称时，Claude Code 使用来自更高优先级位置的那个。

171 175

173| :-------------------- | :------------ | :------- | :---------------------------------------- |177| :-------------------- | :------------ | :------- | :---------------------------------------- |

185 189

186**用户 subagents**（`~/.claude/agents/`）是在所有项目中可用的个人 subagents。190**用户 subagents**（`~/.claude/agents/`）是在所有项目中可用的个人 subagents。

187 191

188Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。在整个树中保持 `name` 值唯一：如果一个范围内的两个文件声明相同的名称，Claude Code 会保留一个并丢弃另一个而不发出警告。192Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。

193

194在整个树中保持 `name` 值唯一：如果一个范围内的两个文件声明相同的名称，Claude Code 仅加载其中一个。{/* min-version: 2.1.196 */}从 v2.1.196 开始，运行 `/doctor` 会报告同范围内的重复代理名称，并显示哪个定义是活跃的。

189 195

190Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。196Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。

191 197

299`model` 字段控制 subagent 使用的 [AI model](/zh-CN/model-config)：305`model` 字段控制 subagent 使用的 [AI model](/zh-CN/model-config)：

300 306

301* **Model alias**: 使用可用的别名之一：`sonnet`、`opus`、`haiku` 或 `fable`307* **Model alias**: 使用可用的别名之一：`sonnet`、`opus`、`haiku` 或 `fable`

302* **Full model ID**: 使用完整的模型 ID，如 `claude-opus-4-8` 或 `claude-sonnet-4-6`。接受与 `--model` 标志相同的值308* **Full model ID**: 使用完整的模型 ID，如 `claude-opus-4-8` 或 `claude-sonnet-5`。接受与 `--model` 标志相同的值

303* **inherit**: 使用与主对话相同的模型309* **inherit**: 使用与主对话相同的模型

304* **Omitted**: 如果未指定，默认为 `inherit`（使用与主对话相同的模型）310* **Omitted**: 默认为 `inherit` 并使用与主对话相同的模型

305 311

306当 Claude 调用 subagent 时，它也可以为该特定调用传递 `model` 参数。Claude Code 按以下顺序解析 subagent 的模型：312当 Claude 调用 subagent 时，它也可以为该特定调用传递 `model` 参数。Claude Code 按以下顺序解析 subagent 的模型：

307 313

3081. [`CLAUDE_CODE_SUBAGENT_MODEL`](/zh-CN/model-config#environment-variables) 环境变量，如果设置3141. [`CLAUDE_CODE_SUBAGENT_MODEL`](/zh-CN/model-config#environment-variables) 环境变量，当设置为模型别名或模型 ID 时

3092. 每次调用的 `model` 参数3152. 每次调用的 `model` 参数

3103. Subagent 定义的 `model` frontmatter3163. Subagent 定义的 `model` frontmatter

3114. 主对话的模型3174. 主对话的模型

312 318

319{/* min-version: 2.1.196 */}从 v2.1.196 开始，将 `CLAUDE_CODE_SUBAGENT_MODEL` 设置为 `inherit` 与不设置它相同：解析继续使用每次调用的 `model` 参数，然后是 frontmatter。在早期版本中，`inherit` 强制 subagents 使用主对话的模型，并忽略这两个来源。

320

313环境变量、每次调用的参数和 frontmatter 值会根据您组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表进行检查。解析为排除模型的值不会被使用，subagent 会改为在继承的模型上运行。321环境变量、每次调用的参数和 frontmatter 值会根据您组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表进行检查。解析为排除模型的值不会被使用，subagent 会改为在继承的模型上运行。

314 322

315<h3 id="control-subagent-capabilities">323<h3 id="control-subagent-capabilities">

602 610

603Subagents 可以定义在 subagent 的生命周期中运行的 [hooks](/zh-CN/hooks)。有两种方式来配置 hooks：611Subagents 可以定义在 subagent 的生命周期中运行的 [hooks](/zh-CN/hooks)。有两种方式来配置 hooks：

604 612

6051. **在 subagent 的 frontmatter 中**：定义仅在该 subagent 活跃时运行的 hooks613* **在 subagent 的 frontmatter 中**：定义仅在该 subagent 活跃时运行的 hooks

6062. **在 `settings.json` 中**：定义在 subagents 启动或停止时在主会话中运行的 hooks614* **在 `settings.json` 中**：定义在 subagents 启动或停止时在主会话中运行的 hooks

607 615

608<h4 id="hooks-in-subagent-frontmatter">616<h4 id="hooks-in-subagent-frontmatter">

609 Subagent frontmatter 中的 Hooks617 Subagent frontmatter 中的 Hooks

658 666

659两个事件都支持匹配器以按名称针对特定代理类型。此示例仅在 `db-agent` subagent 启动时运行设置脚本，并在任何 subagent 停止时运行清理脚本：667两个事件都支持匹配器以按名称针对特定代理类型。匹配器值是项目级和用户级 subagents 的代理 frontmatter `name`，或 [plugin subagents](/zh-CN/plugins) 的 plugin 范围标识符，例如 `my-plugin:db-agent`。范围名称包含冒号，因此它被评估为 [unanchored regular expression](/zh-CN/hooks#matcher-patterns)；使用 `^` 和 `$` 锚定它，如 `^my-plugin:db-agent$`，以仅匹配该代理。

668

669此示例仅在 `db-agent` subagent 启动时运行设置脚本，并在任何 subagent 停止时运行清理脚本：

660 670

661```json theme={null}671```json theme={null}

662{672{

680}690}

681```691```

682 692

693一个带连字符的匹配器，如 `db-agent`，在 Claude Code v2.1.195 或更高版本上精确匹配。在早期版本上，它被评估为 unanchored regular expression，也会为任何包含它的代理类型触发，例如 `prod-db-agent`；在这些版本上使用 `^db-agent$` 锚定它。

694

683有关完整的 hook 配置格式，请参阅 [Hooks](/zh-CN/hooks)。695有关完整的 hook 配置格式，请参阅 [Hooks](/zh-CN/hooks)。

684 696

685<h2 id="work-with-subagents">697<h2 id="work-with-subagents">

704 716

705对于自然语言，没有特殊语法。命名 subagent，Claude 通常会委托：717对于自然语言，没有特殊语法。命名 subagent，Claude 通常会委托：

706 718

707```text theme={null}719```text wrap theme={null}

708Use the test-runner subagent to fix failing tests720Use the test-runner subagent to fix failing tests

709Have the code-reviewer subagent look at my recent changes721Have the code-reviewer subagent look at my recent changes

710```722```

711 723

712**@-mention subagent。** 输入 `@` 并从类型提前中选择 subagent，就像您 @-mention 文件一样。这确保特定 subagent 运行，而不是将选择留给 Claude：724**@-mention subagent。** 输入 `@` 并从类型提前中选择 subagent，就像您 @-mention 文件一样。这确保特定 subagent 运行，而不是将选择留给 Claude：

713 725

714```text theme={null}726```text wrap theme={null}

715@"code-reviewer (agent)" look at the auth changes727@"code-reviewer (agent)" look at the auth changes

716```728```

717 729

757 在前台或后台运行 subagents769 在前台或后台运行 subagents

758</h3>770</h3>

759 771

760Subagents 可以在前台（阻塞）或后台（并发）运行：772Subagents 可以在前台或后台运行：

761 773

762* **前台 subagents** 阻塞主对话直到完成。权限提示会在出现时传递给您。774* **前台 subagents** 阻塞主对话直到完成。权限提示会在出现时传递给您。

763* **后台 subagents** 在您继续工作时并发运行。{/* min-version: 2.1.186 */}从 v2.1.186 开始，当后台 subagent 到达需要权限的工具调用时，提示会在您的主会话中显示，并命名正在请求的 subagent。批准以让 subagent 继续，或按 Esc 拒绝该单个工具调用而不停止 subagent。在 v2.1.186 之前，后台 subagents 自动拒绝任何会提示的工具调用。775* **后台 subagents** 在您继续工作时并发运行。{/* min-version: 2.1.186 */}从 v2.1.186 开始，当后台 subagent 到达需要权限的工具调用时，提示会在您的主会话中显示，并命名正在请求的 subagent。批准以让 subagent 继续，或按 Esc 拒绝该单个工具调用而不停止 subagent。在 v2.1.186 之前，后台 subagents 自动拒绝任何会提示的工具调用。

781 793

782subagents 最有效的用途之一是隔离产生大量输出的操作。运行测试、获取文档或处理日志文件可能会消耗大量上下文。通过将这些委托给 subagent，详细输出保留在 subagent 的上下文中，而只有相关摘要返回到您的主对话。794subagents 最有效的用途之一是隔离产生大量输出的操作。运行测试、获取文档或处理日志文件可能会消耗大量上下文。通过将这些委托给 subagent，详细输出保留在 subagent 的上下文中，而只有相关摘要返回到您的主对话。

783 795

784```text theme={null}796```text wrap theme={null}

785Use a subagent to run the test suite and report only the failing tests with their error messages797Use a subagent to run the test suite and report only the failing tests with their error messages

786```798```

787 799

791 803

792对于独立的调查，生成多个 subagents 以同时工作：804对于独立的调查，生成多个 subagents 以同时工作：

793 805

794```text theme={null}806```text wrap theme={null}

795Research the authentication, database, and API modules in parallel using separate subagents807Research the authentication, database, and API modules in parallel using separate subagents

796```808```

797 809

809 821

810对于多步骤工作流，要求 Claude 按顺序使用 subagents。每个 subagent 完成其任务并将结果返回给 Claude，然后将相关上下文传递给下一个 subagent。822对于多步骤工作流，要求 Claude 按顺序使用 subagents。每个 subagent 完成其任务并将结果返回给 Claude，然后将相关上下文传递给下一个 subagent。

811 823

812```text theme={null}824```text wrap theme={null}

813Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them825Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

814```826```

815 827

820在以下情况下使用 **主对话**：832在以下情况下使用 **主对话**：

821 833

822* 任务需要频繁的来回或迭代细化834* 任务需要频繁的来回或迭代细化

823* 多个阶段共享重要上下文（规划 → 实现 → 测试）835* 多个阶段共享重要上下文，例如规划、实现和测试

824* 您正在进行快速、有针对性的更改836* 您正在进行快速、有针对性的更改

825* 延迟很重要。Subagents 从头开始，可能需要时间来收集上下文837* 延迟很重要。Subagents 从头开始，可能需要时间来收集上下文

826 838

840 852

841{/* min-version: 2.1.172 */}从 Claude Code v2.1.172 开始，subagent 可以生成自己的 subagents。当委托的任务本身分裂成并行子任务时使用这个，例如审查者 subagent 为每个发现分派一个验证者，所以中间输出永远不会到达您的主对话。只有顶级 subagent 的摘要返回给您。853{/* min-version: 2.1.172 */}从 Claude Code v2.1.172 开始，subagent 可以生成自己的 subagents。当委托的任务本身分裂成并行子任务时使用这个，例如审查者 subagent 为每个发现分派一个验证者，所以中间输出永远不会到达您的主对话。只有顶级 subagent 的摘要返回给您。

842 854

843嵌套 subagent 的配置方式与顶级 subagent 相同，并从相同的 [scopes](#choose-the-subagent-scope) 解析。提示输入下方的 subagent 面板显示完整的树：每行显示后代的 `(+N)` 计数，打开一行显示该 subagent 的直接子代，带有返回到 `main` 的路径。[`/agents`](#use-the-%2Fagents-command) 中的 Running 选项卡将运行中的 subagents 列为平面列表。855嵌套 subagent 的配置方式与顶级 subagent 相同，并从相同的 [scopes](#choose-the-subagent-scope) 解析。提示输入下方的 subagent 面板显示完整的树：每行显示后代的 `(+N)` 计数，{/* min-version: 2.1.193 */}从 v2.1.193 开始，打开一行显示该 subagent 的兄弟和直接子代，带有返回到 `main` 的路径。[`/agents`](#use-the-%2Fagents-command) 中的 Running 选项卡将运行中的 subagents 列为平面列表。

844 856

845深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。857深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。

846 858

884 896

885要恢复 subagent，要求 Claude 继续之前的工作：897要恢复 subagent，要求 Claude 继续之前的工作：

886 898

887```text theme={null}899```text wrap theme={null}

888Use the code-reviewer subagent to review the authentication module900Use the code-reviewer subagent to review the authentication module

889[Agent completes]901[Agent completes]

890 902

942 954

943您可以使用 `/fork` 后跟指令自己启动分叉，无论是否设置了变量。Claude Code 从指令的前几个单词命名分叉。以下示例分叉对话以在您继续主会话中的实现时草拟测试用例：955您可以使用 `/fork` 后跟指令自己启动分叉，无论是否设置了变量。Claude Code 从指令的前几个单词命名分叉。以下示例分叉对话以在您继续主会话中的实现时草拟测试用例：

944 956

945```text theme={null}957```text wrap theme={null}

946/fork draft unit tests for the parser changes so far958/fork draft unit tests for the parser changes so far

947```959```

948 960

third-party-integrations.md +1 −0

Details

196 196

197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)

199* [Claude 应用网关](/zh-CN/claude-apps-gateway)，一个自托管网关，在 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登录

199* [Amazon Bedrock](/zh-CN/amazon-bedrock)200* [Amazon Bedrock](/zh-CN/amazon-bedrock)

200* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)201* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)

201* [Google Vertex AI](/zh-CN/google-vertex-ai)202* [Google Vertex AI](/zh-CN/google-vertex-ai)

tools-reference.md +42 −5

Details

11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。

12 12

13| 工具 | 描述 | 需要权限 |13| 工具 | 描述 | 需要权限 |

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

15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |

16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面，您可以在组织内共享。{/* plan-availability: feature=artifacts plans=team,enterprise providers=anthropic */}需要 Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面，您可以在组织内共享。{/* plan-availability: feature=artifacts plans=team,enterprise providers=anthropic */}需要 Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |

17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义 | 否 |17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义 | 否 |

28| `Grep` | 在文件内容中搜索模式。请参阅 [Grep 工具行为](#grep-tool-behavior) | 否 |28| `Grep` | 在文件内容中搜索模式。请参阅 [Grep 工具行为](#grep-tool-behavior) | 否 |

29| `ListMcpResourcesTool` | 列出连接的 [MCP servers](/zh-CN/mcp) 公开的资源 | 否 |29| `ListMcpResourcesTool` | 列出连接的 [MCP servers](/zh-CN/mcp) 公开的资源 | 否 |

30| `LSP` | 通过语言服务器进行代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |30| `LSP` | 通过语言服务器进行代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |

31| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。请参阅 [Monitor 工具](#monitor-tool) | 是 |31| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。还可以打开 WebSocket 并将每条传入消息视为事件。请参阅 [Monitor 工具](#monitor-tool) | 是 |

32| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |32| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |

33| `PowerShell` | 本地执行 PowerShell 命令。请参阅 [PowerShell 工具](#powershell-tool)了解可用性 | 是 |33| `PowerShell` | 本地执行 PowerShell 命令。请参阅 [PowerShell 工具](#powershell-tool)了解可用性 | 是 |

34| `PushNotification` | 发送桌面通知，以及当 [Remote Control](/zh-CN/remote-control) 已连接时发送手机推送，以便长时间运行的任务或[计划任务](/zh-CN/scheduled-tasks)可以在您离开时联系您。{/* plan-availability: feature=push-notifications providers=anthropic */}推送传递通过 Anthropic 托管的基础设施运行，该基础设施无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |34| `PushNotification` | 发送桌面通知，以及当 [Remote Control](/zh-CN/remote-control) 已连接时发送手机推送，以便长时间运行的任务或[计划任务](/zh-CN/scheduled-tasks)可以在您离开时联系您。{/* plan-availability: feature=push-notifications providers=anthropic */}推送传递通过 Anthropic 托管的基础设施运行，该基础设施无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |

35| `Read` | 读取文件内容。请参阅 [Read 工具行为](#read-tool-behavior) | 否 |35| `Read` | 读取文件内容。请参阅 [Read 工具行为](#read-tool-behavior) | 否 |

36| `ReadMcpResourceTool` | 按 URI 读取特定 MCP 资源 | 否 |36| `ReadMcpResourceTool` | 按 URI 读取特定 MCP 资源 | 否 |

37| `RemoteTrigger` | 在 claude.ai 上创建、更新、运行和列出 [Routines](/zh-CN/routines)。支持 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 存在于 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 计划，因此此工具无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |37| `RemoteTrigger` | 在 claude.ai 上创建、更新、运行和列出 [Routines](/zh-CN/routines)。支持 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 存在于 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 计划，因此此工具无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |

38| `ReportFindings` | 将代码审查发现报告为结构化列表，每个发现包含文件、摘要和失败场景，以便 Claude Code 可以呈现它们而不是将其打印为文本。当活跃的代码审查指令告诉它时，Claude 会调用它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本 | 否 |

38| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。待处理的唤醒显示在 [Stop hook input](/zh-CN/hooks#stop-input) 中的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中没有间隔的 `/loop` 提示按固定时间表运行 | 否 |39| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。待处理的唤醒显示在 [Stop hook input](/zh-CN/hooks#stop-input) 中的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中没有间隔的 `/loop` 提示按固定时间表运行 | 否 |

39| `SendMessage` | 向 [agent team](/zh-CN/agent-teams) 队友发送消息，或按 agent ID [恢复 subagent](/zh-CN/sub-agents#resume-subagents)。已停止的 subagents 在后台自动恢复。结构化的团队协议消息需要 agent teams | 否 |40| `SendMessage` | 向 [agent team](/zh-CN/agent-teams) 队友发送消息，或按 agent ID [恢复 subagent](/zh-CN/sub-agents#resume-subagents)。已停止的 subagents 在后台自动恢复。结构化的团队协议消息需要 agent teams | 否 |

41| `SendUserFile` | 将会话中的文件发送给您，带有可选的标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅是在记录中提及。{/* min-version: 2.1.196 */}从 v2.1.196 起，可选的 `display` 输入控制呈现方式：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。当连接了 [Remote Control](/zh-CN/remote-control) 客户端或会话在托管云环境（如 [Claude Code on the web](/zh-CN/claude-code-on-the-web)）中运行时可用。传递通过 Anthropic 托管的基础设施运行，因此该工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用 | 否 |

40| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |

41| `Skill` | 在主对话中执行 [skill](/zh-CN/skills#control-who-invokes-a-skill) | 是 |43| `Skill` | 在主对话中执行 [skill](/zh-CN/skills#control-who-invokes-a-skill) | 是 |

42| `TaskCreate` | 在任务列表中创建新任务 | 否 |44| `TaskCreate` | 在任务列表中创建新任务 | 否 |

206* 轮询 PR 或 CI 作业并在其状态更改时报告208* 轮询 PR 或 CI 作业并在其状态更改时报告

207* 监视目录以查找文件更改209* 监视目录以查找文件更改

208* 跟踪您指向的任何长时间运行脚本的输出210* 跟踪您指向的任何长时间运行脚本的输出

211* 连接到 WebSocket 源并在每条消息到达时报告

209 212

210Claude 为监视编写一个小脚本，在后台运行它，并在每行到达时接收它。您可以在同一会话中继续工作，Claude 在事件到达时插入。通过要求 Claude 取消它或结束会话来停止监视。213对于大多数监视，Claude 编写一个小脚本，在后台运行它，并在每行到达时接收它。对于已经推送事件的服务器，Claude 可以打开 [WebSocket](#websocket-source) 而不是运行脚本。

211 214

212Monitor 使用与 [Bash 相同的权限规则](/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。当设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，它也不可用。215您可以在同一会话中继续工作，Claude 在事件到达时插入。通过要求 Claude 取消它或结束会话来停止监视。

216

217当 Monitor 运行命令时，它使用与 [Bash 相同的权限规则](/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。[WebSocket 源](#websocket-source)有其自己的批准提示。

218

219该工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。当设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，它也不可用。

213 220

214插件可以声明在插件处于活动状态时自动启动的监视，而不是要求 Claude 启动它们。请参阅 [plugin monitors](/zh-CN/plugins-reference#monitors)。221插件可以声明在插件处于活动状态时自动启动的监视，而不是要求 Claude 启动它们。请参阅 [plugin monitors](/zh-CN/plugins-reference#monitors)。

215 222

223<h3 id="websocket-source">

224 WebSocket 源

225</h3>

226

227<Note>

228 WebSocket 源需要 Claude Code v2.1.195 或更高版本。

229</Note>

230

231当服务器已经通过 WebSocket 推送事件时，Claude 可以直接连接到它，而不是编写轮询脚本。每种套接字活动要么成为一个事件，要么结束监视：

232

233* **文本消息**：每条消息都成为一个事件，即使消息跨越多行。

234* **二进制消息**：不通过。Claude 接收一个占位符行，例如 `[binary frame, 512 bytes]`。

235* **大于 1 MiB 的消息**：监视结束，因此请订阅存在的过滤源。

236* **套接字关闭**：监视结束，Claude 接收关闭代码。

237

238WebSocket 监视使用 `ws` 输入代替 `command`，单个 Monitor 调用不能将两者结合。`ws` 输入有两个字段：

239

240| 字段 | 必需 | 描述 |

241| :---------- | :- | :--------------------------------------------------------- |

242| `url` | 是 | 要连接的端点。必须是 `ws://` 或 `wss://` URL，不包含嵌入的凭证或空格，仅使用 ASCII 字符 |

243| `protocols` | 否 | 在握手期间提供的 WebSocket 子协议名称。每个条目必须是有效的子协议令牌，列表不能包含重复项 |

244

245`timeout_ms` 和 `persistent` 输入的行为与它们对命令的行为相同：监视在截止时间结束，除非设置了 `persistent`，`TaskStop` 会提前取消它。

246

247打开 WebSocket 会提示批准，提示不提供跳过同一主机的未来提示的选项。

248

249Claude Code 拒绝指向私有、链接本地或云元数据地址的 URL，包括解析为这些地址的主机名。它还拒绝 `sandbox.network.deniedDomains` 中的主机，以及当在托管设置中设置了 [`allowManagedDomainsOnly`](/zh-CN/settings#sandbox-settings) 时，任何在托管允许列表之外的主机。

250

216<h2 id="notebookedit-tool-behavior">251<h2 id="notebookedit-tool-behavior">

217 NotebookEdit 工具行为252 NotebookEdit 工具行为

218</h2>253</h2>

265 300

266同样的主会话工作目录重置行为（如 Bash 工具部分所述）适用于 PowerShell 命令，包括 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` 环境变量。301同样的主会话工作目录重置行为（如 Bash 工具部分所述）适用于 PowerShell 命令，包括 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` 环境变量。

267 302

303从 v2.1.196 开始，PowerShell 工具与 Bash 工具的搜索和 diff 退出代码处理方式相匹配。来自 `grep`、`egrep`、`fgrep` 和 `git grep` 的退出代码 1 表示没有匹配项，来自 `git diff` 的退出代码 1 表示存在差异，因此这些结果不会作为命令失败报告给 Claude。

304

268<h3 id="preview-limitations">305<h3 id="preview-limitations">

269 预览限制306 预览限制

270</h3>307</h3>

284 321

285Read 处理纯文本之外的几种文件类型：322Read 处理纯文本之外的几种文件类型：

286 323

287* **图像**：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送前调整大小并重新压缩大图像以适应模型的图像大小限制，因此 Claude 可能会看到大截图的缩小版本。如果 Claude 在大图像中遗漏了细微的像素级细节，请要求它首先裁剪感兴趣的区域，例如使用 ImageMagick 通过 Bash。324* **图像**：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送前调整大小并重新压缩大图像以适应模型的图像大小限制，因此 Claude 可能会看到大截图的缩小版本。{/* min-version: 2.1.196 */}从 v2.1.196 开始，调整大小后仍然大于 500KB 的图像会以降低质量的 JPEG 格式重新编码，其像素尺寸保持不变。如果 Claude 在大图像中遗漏了细微的像素级细节，请要求它首先裁剪感兴趣的区域，例如使用 ImageMagick 通过 Bash。

288* **PDFs**：Claude 完整读取短 `.pdf` 文件。对于超过 10 页的 PDFs，它使用 `pages` 参数（例如 `"1-5"`）按范围读取，一次最多 20 页。325* **PDFs**：Claude 完整读取短 `.pdf` 文件。对于超过 10 页的 PDFs，它使用 `pages` 参数（例如 `"1-5"`）按范围读取，一次最多 20 页。

289* **Jupyter notebooks**：`.ipynb` 文件返回所有单元格及其输出，包括代码、markdown 和可视化。326* **Jupyter notebooks**：`.ipynb` 文件返回所有单元格及其输出，包括代码、markdown 和可视化。

290 327

troubleshoot-install.md +1 −1

Details

45如果您的问题未列出，请按照下面的诊断检查来缩小原因范围。45如果您的问题未列出，请按照下面的诊断检查来缩小原因范围。

46 46

47<Tip>47<Tip>

48 如果您宁愿完全跳过终端，[Claude Code Desktop 应用](/zh-CN/desktop-quickstart)可让您通过图形界面安装和使用 Claude Code。为 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 下载它，无需任何命令行设置即可开始编码。48 如果您宁愿完全跳过终端，[Claude Code Desktop 应用](/zh-CN/desktop-quickstart)可让您通过图形界面安装和使用 Claude Code。为 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)、[Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 或 [Linux](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 下载它，无需任何命令行设置即可开始编码。

49</Tip>49</Tip>

50 50

51<h2 id="run-diagnostic-checks">51<h2 id="run-diagnostic-checks">

voice-dictation.md +14 −3

Details

18 要求18 要求

19</h2>19</h2>

20 20

21语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。当你的组织启用了 HIPAA 合规性时，语音听写也不可用。转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/zh-CN/data-usage)。21语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。它需要以下所有条件：

22 22

23语音听写还需要本地麦克风访问权限，因此在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 或 SSH 会话。在 WSL 中，语音听写需要 WSLg 来访问音频。WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。23* **一个 Claude.ai 账户**：语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。

24* **一个未启用 HIPAA 合规性的组织**：当此限制适用时，`/voice` 显示 `Voice mode is disabled by your organization's policy`。

25* **一个本地麦克风**：语音听写在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)或 SSH 会话。

26* **如果你在 WSL 中运行 Claude Code，则需要 WSLg**：WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。

28转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/zh-CN/data-usage)。

24 29

25音频录制在 macOS、Linux 和 Windows 上使用内置的本机模块。在 Linux 上，如果本机模块无法加载，Claude Code 会回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果两者都不可用，`/voice` 会打印你的包管理器的安装命令。30音频录制在 macOS、Linux 和 Windows 上使用内置的本机模块。在 Linux 上，如果本机模块无法加载，Claude Code 会回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果两者都不可用，`/voice` 会打印你的包管理器的安装命令。

26 31

91 96

92点击模式使用单个按键切换录制：点击一次开始，说话，然后再点击一次发送提示词。没有预热，你不需要保持键被按住。97点击模式使用单个按键切换录制：点击一次开始，说话，然后再点击一次发送提示词。没有预热，你不需要保持键被按住。

93 98

94使用 `/voice tap` 启用点击模式。当提示词输入为空时，点击 `Space` 开始录制。页脚在录制时显示实时波形。再次点击 `Space` 停止。Claude Code 插入转录并在转录至少有三个单词时自动提交提示词。较短的转录被插入但不提交，所以意外点击不会发送一个杂散的单词。99使用 `/voice tap` 启用点击模式。当提示词输入为空时，点击 `Space` 开始录制。页脚在录制时显示实时波形。再次点击 `Space` 停止。

100

101Claude Code 插入转录并在转录至少有三个单词时自动提交提示词。较短的转录被插入但不提交，所以意外点击不会发送一个杂散的单词。

102

103三个单词的阈值计算不使用空格书写的语言中的单词。从 v2.1.195 开始，日语、中文和泰语转录计算单个单词，所以它们在点击模式和带有 `autoSubmit` 的保持模式下自动提交。早期版本将没有空格的转录计为一个单词，从不自动提交。

95 104

96第一次点击仅在提示词输入为空时开始录制，所以你仍然可以在撰写消息时正常输入空格。第二次点击停止录制，无论输入内容如何。录制也会在 15 秒无声或总共两分钟后自动停止。105第一次点击仅在提示词输入为空时开始录制，所以你仍然可以在撰写消息时正常输入空格。第二次点击停止录制，无论输入内容如何。录制也会在 15 秒无声或总共两分钟后自动停止。

97 106

169语音听写不激活或不录制时的常见问题：178语音听写不激活或不录制时的常见问题：

170 179

171* **`Voice mode requires a Claude.ai account`**：你使用 API 密钥或第三方提供商进行了身份验证。运行 `/login` 以使用 Claude.ai 账户登录。180* **`Voice mode requires a Claude.ai account`**：你使用 API 密钥或第三方提供商进行了身份验证。运行 `/login` 以使用 Claude.ai 账户登录。

181* **`Voice mode is disabled by your organization's policy`**：你的组织的合规配置禁用了语音听写，如[要求](#requirements)中所述。联系你的组织管理员以确认你的组织是否可以使用语音听写。

172* **`Microphone access is denied`**：在系统设置中授予你的终端麦克风权限。在 macOS 上，转到系统设置 → 隐私和安全 → 麦克风并启用你的终端应用，然后再次运行 `/voice`。在 Windows 上，转到设置 → 隐私和安全 → 麦克风并为桌面应用打开麦克风访问，然后再次运行 `/voice`。如果你的终端未在 macOS 设置中列出，请参阅[终端未在 macOS 麦克风设置中列出](#terminal-not-listed-in-macos-microphone-settings)。182* **`Microphone access is denied`**：在系统设置中授予你的终端麦克风权限。在 macOS 上，转到系统设置 → 隐私和安全 → 麦克风并启用你的终端应用，然后再次运行 `/voice`。在 Windows 上，转到设置 → 隐私和安全 → 麦克风并为桌面应用打开麦克风访问，然后再次运行 `/voice`。如果你的终端未在 macOS 设置中列出，请参阅[终端未在 macOS 麦克风设置中列出](#terminal-not-listed-in-macos-microphone-settings)。

173* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。183* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。

184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安装，但主机没有音频捕获设备，例如无头服务器或容器。在有麦克风的机器上运行 Claude Code。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Linux 上的 Claude Code 在这种情况下报告此消息；早期版本即使已安装 SoX 也会要求你安装 SoX。

174* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。

175* **`Voice input is failing repeatedly and has been paused`**：语音听写连续遇到多个启动失败，并停止尝试新会话，直到一个成功。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。186* **`Voice input is failing repeatedly and has been paused`**：语音听写连续遇到多个启动失败，并停止尝试新会话，直到一个成功。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。

176* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。187* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。

whats-new.md +16 −0

Details

8 8

9每周开发摘要突出了最有可能改变您工作方式的功能。每个条目都包括可运行的代码、简短的演示和完整文档的链接。有关每个错误修复和次要改进，请参阅[更新日志](/zh-CN/changelog)。9每周开发摘要突出了最有可能改变您工作方式的功能。每个条目都包括可运行的代码、简短的演示和完整文档的链接。有关每个错误修复和次要改进，请参阅[更新日志](/zh-CN/changelog)。

10 10

11<Update label="Week 26" description="June 22–26, 2026" tags={["v2.1.185–v2.1.193"]}>

12 **`claude mcp login`**：从您的 shell 中验证配置的 MCP 服务器，而不是使用交互式 `/mcp` 菜单，稍后可以使用 `claude mcp logout` 清除其存储的凭证。

14 本周还有：**shell 模式响应命令输出**（`! npm test` 无需第二个提示即可获得解释）；**`/rewind`** 可以从运行 `/clear` 之前恢复对话；**后台子代理**现在在主会话中显示权限提示，而不是自动拒绝。

16 [阅读 Week 26 摘要 →](/zh-CN/whats-new/2026-w26)

17</Update>

19<Update label="Week 25" description="June 15–19, 2026" tags={["v2.1.178–v2.1.183"]}>

20 **Artifacts**：将会话的输出转换为 claude.ai 上的实时、可共享页面，在会话工作时原地更新，现在在 Team 和 Enterprise 计划中处于测试版。

22 本周还有：**拒绝和询问规则与工具参数匹配**，使用 `Tool(param:value)`，例如 `Agent(model:opus)`；**`/config key=value`** 从提示、`-p` 模式和远程控制中设置任何设置；**自动模式阻止破坏性 git 命令**，当您没有要求丢弃本地工作时。

24 [阅读 Week 25 摘要 →](/zh-CN/whats-new/2026-w25)

25</Update>

11<Update label="Week 24" description="June 8–12, 2026" tags={["v2.1.166–v2.1.176"]}>27<Update label="Week 24" description="June 8–12, 2026" tags={["v2.1.166–v2.1.176"]}>

12 **`/cd`**：在对话中途将当前会话移动到新的工作目录，无需重建提示缓存。28 **`/cd`**：在对话中途将当前会话移动到新的工作目录，无需重建提示缓存。

13 29

whats-new/2026-w23.md +2 −0

Details

73 <p className="digest-feature-try">向托管设置添加下限，以便较旧的客户端拒绝启动：</p>73 <p className="digest-feature-try">向托管设置添加下限，以便较旧的客户端拒绝启动：</p>

74 74

75 ```json managed-settings.json theme={null}75 ```json managed-settings.json theme={null}

76 {

76 "requiredMinimumVersion": "2.1.163"77 "requiredMinimumVersion": "2.1.163"

78 }

77 ```79 ```

78 80

79 <a className="digest-feature-link" href="/zh-CN/docs/admin-setup#decide-what-to-enforce">决定要强制执行的内容</a>81 <a className="digest-feature-link" href="/zh-CN/docs/admin-setup#decide-what-to-enforce">决定要强制执行的内容</a>

whats-new/2026-w25.md +90 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 25 周 · 2026 年 6 月 15–19 日

7> 从您的会话中使用 Artifacts 发布实时可共享页面，在拒绝和询问规则中匹配工具参数，以及使用 /config 从提示中设置任何设置。

9<div className="digest-meta">

10 <span>发布版本 <a href="/zh-CN/docs/changelog#2-1-178">v2.1.178 → v2.1.183</a></span>

11 <span>3 项功能 · 6 月 15–19 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Artifacts</span>

17 </div>

19 <p className="digest-feature-lede">Artifact 是一个实时交互式页面，Claude Code 从您的会话发布到 claude.ai 上的私有 URL，并在会话继续工作时实时更新。当终端文本不是合适的媒介时，请要求创建一个，例如带有内联注释差异的 PR 演练或从会话数据构建的仪表板。Artifacts 在 Team 和 Enterprise 计划中处于测试阶段。</p>

21 <Frame>

22 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/1ylKDoQynT1UgfEK/images/whats-new/artifacts.mp4?fit=max&auto=format&n=1ylKDoQynT1UgfEK&q=85&s=7f5391559d2bc69989621b36322fcff1" data-path="images/whats-new/artifacts.mp4" />

23 </Frame>

25 <p className="digest-feature-try">向 Claude 要求一个页面，然后批准发布提示：</p>

27 ```text Claude Code theme={null}

28 > Make an artifact that walks through this PR with the diff annotated inline.

29 ```

31 <a className="digest-feature-link" href="/zh-CN/docs/artifacts#create-an-artifact">创建 Artifact</a>

32</div>

34<div className="digest-feature">

35 <div className="digest-feature-header">

36 <span className="digest-feature-title">按输入参数匹配</span>

37 <span className="digest-feature-pill">v2.1.178</span>

38 </div>

40 <p className="digest-feature-lede">拒绝和询问权限规则现在可以使用 <code>Tool(param:value)</code> 语法匹配工具的输入参数。例如，<code>Agent(model:opus)</code> 匹配请求 Opus 模型层级的子代理生成。该值接受 `*` 作为通配符，因此 `Agent(isolation:*)` 匹配任何显式隔离值。</p>

42 <p className="digest-feature-try">在 <code>settings.json</code> 中的拒绝列表中添加参数规则：</p>

44 ```json .claude/settings.json {3} theme={null}

45 {

46 "permissions": {

47 "deny": ["Agent(model:opus)"]

48 }

49 }

50 ```

52 <a className="digest-feature-link" href="/zh-CN/docs/permissions#match-by-input-parameter">按输入参数匹配</a>

53</div>

55<div className="digest-feature">

56 <div className="digest-feature-header">

57 <span className="digest-feature-title">从提示中设置任何设置</span>

58 <span className="digest-feature-pill">v2.1.181</span>

59 </div>

61 <p className="digest-feature-lede">将 <code>key=value</code> 传递给 <code>/config</code> 以直接更改设置，无需打开设置界面。该语法也适用于使用 <code>-p</code> 标志的非交互模式和远程控制。</p>

63 <p className="digest-feature-try">从提示中设置 <code>thinking</code> 设置：</p>

65 ```text Claude Code theme={null}

66 > /config thinking=false

67 ```

69 <a className="digest-feature-link" href="/zh-CN/docs/commands#all-commands">命令参考</a>

70</div>

72<div className="digest-wins">

73 <p className="digest-wins-title">其他改进</p>

75 <div className="digest-wins-grid">

76 <div>自动模式现在在您未要求丢弃本地工作时阻止破坏性 git 命令（`git reset --hard`、`git clean -fd`、`git stash drop`），并在您未要求特定堆栈时阻止 <code>terraform destroy</code></div>

77 <div>将新的 <code>attribution.sessionUrl</code> 设置设为 <code>false</code> 以在 web 和远程控制会话中的提交和 PR 中省略 claude.ai 会话链接</div>

78 <div>在 <code>/config</code> 界面中，Enter 和 Space 都可以更改选定的设置，Esc 现在保存并关闭而不是还原</div>

79 <div>新的 <code>sandbox.allowAppleEvents</code> 选择加入设置允许沙箱命令在 macOS 上发送 Apple Events</div>

80 <div>指向 <code>CLAUDE\_CLIENT\_PRESENCE\_FILE</code> 到标记文件以在您在机器上时抑制移动推送通知</div>

81 <div>长段落现在逐行流式传输，而不是等待第一个换行符</div>

82 <div>API 连接在思考中断开现在自动重试，而不是显示"思考时连接已关闭"</div>

83 <div>设置 <code>CLAUDE\_CODE\_EXPERIMENTAL\_AGENT\_TEAMS=1</code> 后，每个会话都有一个隐式团队，因此您可以直接使用 Agent 工具的 <code>name</code> 参数生成队友</div>

84 <div>嵌套 <code>.claude/skills</code> 目录中的 Skills 在处理那里的文件时加载；在名称冲突时，嵌套 skill 显示为 `<dir>:<name>`，以便两者都保持可用</div>

85 <div>修复了 prompt caching 在自定义 <code>ANTHROPIC\_BASE\_URL</code> 和 Foundry 上不读取的问题</div>

86 <div>修复了 Write 和 Edit 在网络驱动器和云同步文件夹上生成零字节或截断文件的问题</div>

87 </div>

88</div>

90[v2.1.178–v2.1.183 完整更新日志 →](/zh-CN/changelog#2-1-178)

whats-new/2026-w26.md +66 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 26 周 · 2026 年 6 月 22–26 日

7> 使用 claude mcp login 从 shell 中对 MCP 服务器进行身份验证，使用 ! 前缀获取对 shell 模式命令输出的响应，以及使用 /rewind 从 /clear 之前恢复对话。

9<div className="digest-meta">

10 <span>发布版本 <a href="/zh-CN/docs/changelog#2-1-185">v2.1.185 → v2.1.193</a></span>

11 <span>2 项功能 · 6 月 22–26 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">从 CLI 对 MCP 服务器进行身份验证</span>

17 <span className="digest-feature-pill">v2.1.186</span>

18 </div>

20 <p className="digest-feature-lede">新的 `claude mcp login <name>` 和 `claude mcp logout <name>` 命令从 shell 而不是交互式 <code>/mcp</code> 菜单对配置的 MCP 服务器进行身份验证。`claude mcp login` 直接运行服务器的 OAuth 流程，`claude mcp logout` 清除存储的凭证。</p>

22 <p className="digest-feature-try">为配置的服务器运行 OAuth 流程而无需打开会话：</p>

24 ```bash terminal theme={null}

25 claude mcp login sentry

26 ```

28 <a className="digest-feature-link" href="/zh-CN/docs/mcp#authenticate-from-the-command-line">从命令行进行身份验证</a>

29</div>

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Shell 模式响应命令输出</span>

34 <span className="digest-feature-pill">v2.1.186</span>

35 </div>

37 <p className="digest-feature-lede">使用 <code>!</code> 前缀运行的命令现在会在输出进入记录后从 Claude 获得响应，因此您可以运行 <code>! npm test</code> 并获得对失败的解释，而无需第二个提示。响应成本与发送普通提示相同。要保持之前的行为（其中输出被添加到上下文而不获得响应），请在 <code>settings.json</code> 中将 <code>respondToBashCommands</code> 设置为 <code>false</code>。</p>

39 <p className="digest-feature-try">运行命令并获得对其输出的响应：</p>

41 ```text Claude Code theme={null}

42 > ! npm test

43 ```

45 <a className="digest-feature-link" href="/zh-CN/docs/interactive-mode#shell-mode-with-prefix">带有 ! 前缀的 Shell 模式</a>

46</div>

48<div className="digest-wins">

49 <p className="digest-wins-title">其他改进</p>

51 <div className="digest-wins-grid">

52 <div><code>/rewind</code> 现在可以从运行 <code>/clear</code> 之前恢复对话</div>

53 <div>新的 <code>sandbox.credentials</code> 设置阻止沙箱命令读取凭证文件和秘密环境变量</div>

54 <div>组织配置的模型限制现在适用于模型选择器、`--model`、<code>/model</code> 和 <code>ANTHROPIC\_MODEL</code>，当选择受限制的模型时显示"受您的组织设置限制"消息</div>

55 <div>新的 <code>autoMode.classifyAllShell</code> 设置将所有 Bash 和 PowerShell 命令路由通过自动模式分类器，拒绝原因现在显示在记录、拒绝提示和 <code>/permissions</code> 中</div>

56 <div>新的 <code>claude\_code.assistant\_response</code> OpenTelemetry 日志事件携带模型的响应文本；已经记录提示内容的部署在升级时开始接收它，因此设置 <code>OTEL\_LOG\_ASSISTANT\_RESPONSES=0</code> 以仅保留提示</div>

57 <div>后台子代理现在在主会话中显示权限提示而不是自动拒绝；对话框显示哪个代理在请求，Esc 仅拒绝该工具</div>

58 <div><code>/install-github-app</code> 现在可以仅安装 GitHub App 并跳过 Actions 工作流和秘密步骤</div>

59 <div>您在沙箱网络权限对话框中允许的主机在会话的其余部分被记住，而不是在每次连接时重新提示</div>

60 <div>流式响应使用的 CPU 减少约 37%，来自终端输出缓存的长会话内存增长被减少</div>

61 <div>`/review <pr>` 现在使用与 <code>/code-review medium</code> 相同的审查引擎</div>

62 <div>Bash 模式 <code>!</code> 命令获得实时文件路径自动完成</div>

63 </div>

64</div>

66[v2.1.185–v2.1.193 的完整更改日志 →](/zh-CN/changelog#2-1-185)

workflows.md +2 −0

Details

68 68

69 <Step title="阅读报告">69 <Step title="阅读报告">

70 运行完成后，报告进入您的会话。它引用每个声明来自的来源，未通过交叉检查的声明已被过滤掉。70 运行完成后，报告进入您的会话。它引用每个声明来自的来源，未通过交叉检查的声明已被过滤掉。

72 {/* min-version: 2.1.196 */}从 v2.1.196 开始，当验证代理无法检查声明时（例如在速率限制或 API 错误之后），报告将该声明列为未验证，而不是计为被驳回。

71 </Step>73 </Step>

72</Steps>74</Steps>

73 75

Documentation 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC