Documentation 2026-10-03 23:57 UTC to 2026-10-04 19:59 UTC

137 已关联的 GitHub 账户137 已关联的 GitHub 账户

138</h3>138</h3>

139 139 

140在 Team 和 Enterprise 计划中，[**Admin settings > GitHub**](https://claude.ai/admin-settings/github) 列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您的 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享此列表。打开该页面需要在您的 Claude 组织中拥有管理员角色。140在 Team 和 Enterprise 计划中，[**Organization settings > GitHub**](https://claude.ai/admin-settings/github) 列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您的 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享此列表。打开该页面需要在您的 Claude 组织中拥有管理员角色。

141 141 

142管理员或成员都可以关联账户：142管理员或成员都可以关联账户：

143 143 

161| Usage monitoring | 会话、工具和令牌的 OpenTelemetry 导出 | 所有提供商 | [Monitoring usage](/docs/zh-CN/monitoring-usage) |161| Usage monitoring | 会话、工具和令牌的 OpenTelemetry 导出 | 所有提供商 | [Monitoring usage](/docs/zh-CN/monitoring-usage) |

162| Analytics dashboard | Teams / Enterprise 上具有排行榜的采用和贡献指标；Console 上的每用户使用情况和支出指标 | Teams / Enterprise 在 [claude.ai/analytics](https://claude.ai/analytics/claude-code)，Console 在 [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/zh-CN/analytics) |162| Analytics dashboard | Teams / Enterprise 上具有排行榜的采用和贡献指标；Console 上的每用户使用情况和支出指标 | Teams / Enterprise 在 [claude.ai/analytics](https://claude.ai/analytics/claude-code)，Console 在 [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/zh-CN/analytics) |

163| Programmatic reporting | 通过 API 的每用户使用情况和成本数据 | Enterprise 的 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics)，Console 的 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/zh-CN/costs#manage-costs-for-your-organization) |163| Programmatic reporting | 通过 API 的每用户使用情况和成本数据 | Enterprise 的 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics)，Console 的 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/zh-CN/costs#manage-costs-for-your-organization) |

164| Spend controls | 支出限制和速率限制 | Teams / Enterprise 的管理员设置，Console 的工作区限制；在第三方云上，云预算控制或具有每用户[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) | [Costs](/docs/zh-CN/costs#manage-costs-for-your-organization) |164| Spend controls | 支出限制和速率限制 | Teams / Enterprise 的组织设置，Console 的工作区限制；在第三方云上，云预算控制或具有每用户[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) | [Costs](/docs/zh-CN/costs#manage-costs-for-your-organization) |

165 165 

166在 Teams 和 Enterprise 上，每用户使用情况和支出数字来自您组织的分析设置中的[支出报告](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)，而不是分析仪表板。云提供商通过 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公开支出。有关跨 Claude chat、Claude Code 和 Cowork 规划企业预算的信息，请参阅 [Claude Enterprise consumption guide](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)。166在 Teams 和 Enterprise 上，每用户使用情况和支出数字来自您组织的分析设置中的[支出报告](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)，而不是分析仪表板。云提供商通过 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公开支出。有关跨 Claude chat、Claude Code 和 Cowork 规划企业预算的信息，请参阅 [Claude Enterprise consumption guide](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)。

167 167 

919 ```919 ```

920</CodeGroup>920</CodeGroup>

921 921 

922<h3 id="a-tool-is-missing-from-an-sdk-mcp-server">

923 SDK MCP 服务器中缺少某个工具

924</h3>

925 

926在 TypeScript SDK 中，当某个工具的输入 schema 无法转换为 JSON Schema 时，您使用 [`createSdkMcpServer()`](/docs/zh-CN/agent-sdk/typescript#createsdkmcpserver) 创建的服务器在列出其工具时会省略该工具。此时 SDK 会发出一条警告。在 Node.js 下，该警告是一个代码为 `CLAUDE_SDK_MCP_TOOL_SCHEMA_UNCONVERTIBLE` 的进程警告，并以以下文本开头：

927 

928```text theme={null}

929Tool "<name>" on SDK MCP server "<server>" was left out of the server's tool list, because its input schema cannot be converted to JSON Schema

930```

931 

932警告的其余部分会给出转换错误的消息（如果有），然后说明需要检查和更改的内容。

933 

934在 TypeScript Agent SDK v0.3.286 之前，只要有一个无法转换的 schema，就会导致该服务器的整个工具列表失败且不显示此警告，因此该服务器的所有工具都无法提供给 Claude。

935 

922<h3 id="connection-timeouts">936<h3 id="connection-timeouts">

923 连接超时937 连接超时

924</h3>938</h3>

13| 症状 | 转到 |13| 症状 | 转到 |

14| :- | :- |14| :- | :- |

15| 找不到 Skills、skill 未被使用、`Invalid skill name` 错误 | [Skills 故障排除](/docs/zh-CN/agent-sdk/skills#troubleshooting) |15| 找不到 Skills、skill 未被使用、`Invalid skill name` 错误 | [Skills 故障排除](/docs/zh-CN/agent-sdk/skills#troubleshooting) |

16| MCP 服务器显示 `failed` 状态、工具未被调用、连接超时、工具输出超过最大允许令牌数 | [MCP 故障排除](/docs/zh-CN/agent-sdk/mcp#troubleshooting) |16| MCP 服务器显示 `failed` 状态、工具未被调用、SDK MCP 服务器中缺少某个工具、连接超时、工具输出超过允许的最大 token 数 | [MCP 故障排除](/docs/zh-CN/agent-sdk/mcp#troubleshooting) |

17| Plugin 未加载、plugin skills 未出现 | [Plugins 故障排除](/docs/zh-CN/agent-sdk/plugins#troubleshooting) |17| Plugin 未加载、plugin skills 未出现 | [Plugins 故障排除](/docs/zh-CN/agent-sdk/plugins#troubleshooting) |

18| Claude 未委派给子代理、基于文件系统的代理未加载 | [Subagents 故障排除](/docs/zh-CN/agent-sdk/subagents#troubleshooting) |18| Claude 未委派给子代理、基于文件系统的代理未加载 | [Subagents 故障排除](/docs/zh-CN/agent-sdk/subagents#troubleshooting) |

19| Checkpointing 选项未被识别、没有 UUID 的用户消息、`No file checkpoint found`、`File rewinding is not enabled`、`ProcessTransport is not ready for writing` | [文件 checkpointing 故障排除](/docs/zh-CN/agent-sdk/file-checkpointing#troubleshooting) |19| Checkpointing 选项未被识别、没有 UUID 的用户消息、`No file checkpoint found`、`File rewinding is not enabled`、`ProcessTransport is not ready for writing` | [文件 checkpointing 故障排除](/docs/zh-CN/agent-sdk/file-checkpointing#troubleshooting) |

863 fast_mode_state?: "off" | "cooldown" | "on";863 fast_mode_state?: "off" | "cooldown" | "on";

864 fast_mode_disabled_reason?: FastModeDisabledReason;864 fast_mode_disabled_reason?: FastModeDisabledReason;

865 hooks_applied?: boolean;865 hooks_applied?: boolean;

866 sdk_mcp_manifests_parked?: Record<

867 string,

868 | "parked"

869 | "already_connected"

870 | "protocol_version_mismatch"

871 | "malformed"

872 | "not_honoured"

873 >;

866};874};

867```875```

868 876 

875 883 

876在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。884在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。

877 885 

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

887 

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

879 889 

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

1955| - | - |1965| - | - |

1956| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据解析，列出中断到达时待处理的消息 |1966| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据解析，列出中断到达时待处理的消息 |

1957| `interrupt_cancel_queued_v1` | `interrupt` 控制请求尊重 `cancel_queued: true`，取消收据在 `still_queued` 下列出的消息，并改为在 `cancelled` 下列出它们。请参阅 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |1967| `interrupt_cancel_queued_v1` | `interrupt` 控制请求尊重 `cancel_queued: true`，取消收据在 `still_queued` 下列出的消息，并改为在 `cancelled` 下列出它们。请参阅 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |

1968| `sdk_mcp_manifests` | `initialize` 控制请求接受 `sdkMcpServerManifests`，即从您的进程内 [SDK MCP 服务器](/docs/zh-CN/agent-sdk/custom-tools)捕获的 MCP 握手结果。Claude Code 在 v2.1.286 或更高版本中公布此能力 |

1969| `sdk_mcp_tools_list_changed` | 来自 [SDK MCP 服务器](/docs/zh-CN/agent-sdk/custom-tools)的 `tools/list_changed` 通知会使 Claude Code 重新列出该服务器的工具，因此服务器在会话中途添加的工具能够到达 Claude。Claude Code 在 v2.1.286 或更高版本中公布此能力 |

1958 1970 

1959`plugin_errors` 数组列出插件加载失败。一个条目描述要么是未加载的插件且在 `plugins` 中不存在，要么是加载但没有其部分之一（例如其 hooks 文件）的插件。当没有任何东西失败时，该键被省略。`SDKSystemMessage` 在 Agent SDK v0.3.283 或更高版本中声明 `plugin_errors`。1971`plugin_errors` 数组列出插件加载失败。一个条目描述要么是未加载的插件且在 `plugins` 中不存在，要么是加载但没有其部分之一（例如其 hooks 文件）的插件。当没有任何东西失败时，该键被省略。`SDKSystemMessage` 在 Agent SDK v0.3.283 或更高版本中声明 `plugin_errors`。

1960 1972 

347 347 

348要组合过滤器，请以 `a:`、`s:`、`n:` 或 `o:` 开头，再添加更多过滤器，以空格分隔。列表会显示同时匹配所有过滤器的会话。例如，`s:blocked a:reviewer` 会列出正在等待您的 `reviewer` 会话。348要组合过滤器，请以 `a:`、`s:`、`n:` 或 `o:` 开头，再添加更多过滤器，以空格分隔。列表会显示同时匹配所有过滤器的会话。例如，`s:blocked a:reviewer` 会列出正在等待您的 `reviewer` 会话。

349 349 

350过滤器处于活动状态时，您折叠的组会展开以显示匹配项，并且第一个匹配项会被选中，因此按 `Enter` 即可打开它。清空输入框即可移除过滤器，这些组会再次折叠。350过滤器处于活动状态时，您折叠的组会展开以显示匹配项，并且会选中一个匹配项，因此按 `Enter` 即可打开它。清空输入框即可移除过滤器，这些组会再次折叠。

351 351 

352<h3 id="keyboard-shortcuts">352<h3 id="keyboard-shortcuts">

353 快捷键353 快捷键

369| `Tab` | 在空输入上浏览所有 subagents。否则应用突出显示的建议 |369| `Tab` | 在空输入上浏览所有 subagents。否则应用突出显示的建议 |

370| `Ctrl+S` | 在状态和目录之间切换分组 |370| `Ctrl+S` | 在状态和目录之间切换分组 |

371| `Ctrl+T` | 固定或取消固定选定的会话 |371| `Ctrl+T` | 固定或取消固定选定的会话 |

372| `Ctrl+F` | 使用 [`n:` 过滤器](#filter-sessions)按名称查找会话 |

373| `Alt+↑` / `Alt+↓` | 跳到上一个或下一个组标题 |

372| `Ctrl+R` | 重命名选定的会话 |374| `Ctrl+R` | 重命名选定的会话 |

373| `Ctrl+G` | 在你的 `$VISUAL` 或 `$EDITOR` 中打开调度提示 |375| `Ctrl+G` | 在你的 `$VISUAL` 或 `$EDITOR` 中打开调度提示 |

374| `Ctrl+J` | 在调度输入中插入换行符 |376| `Ctrl+J` | 在调度输入中插入换行符 |

378| `Ctrl+C` | 清除输入；按两次退出 |380| `Ctrl+C` | 清除输入；按两次退出 |

379| `?` | 显示所有快捷键 |381| `?` | 显示所有快捷键 |

380 382 

381`Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` 遵循你的 [`keybindings.json`](/docs/zh-CN/keybindings)。在 [`Agents` 上下文](/docs/zh-CN/keybindings#agents-actions)中用 `agents:switchView` 和 `agents:togglePin` 操作重新绑定或取消绑定 `Ctrl+S` 和 `Ctrl+T`，以及通过 `Chat` 上下文的 `chat:externalEditor` 绑定的 `Ctrl+G`。表中的其他快捷键无法重新绑定。383在 [`Agents` 上下文](/docs/zh-CN/keybindings#agents-actions)中有对应操作的快捷键遵循您的 [`keybindings.json`](/docs/zh-CN/keybindings)。`Ctrl+G` 也是如此，它通过 `Chat` 上下文的 `chat:externalEditor` 绑定进行配置。

382 384 

383<h2 id="dispatch-new-agents">385<h2 id="dispatch-new-agents">

384 分派新的 agents386 分派新的 agents

1087 1089 

1088| 版本 | 更改 |1090| 版本 | 更改 |

1089| - | - |1091| - | - |

1092| v2.1.288 | `Ctrl+F` 按名称查找会话，`Alt+↑` / `Alt+↓` 在组标题之间跳转。这两者以及 `Ctrl+R` 都可以[重新绑定](/docs/zh-CN/keybindings#agents-actions)。 |

1090| v2.1.287 | [`n:<text>` 筛选器](#filter-sessions)按名称或第一个提示词查找会话。当任何筛选器处于活动状态时，您折叠的组会展开以显示其匹配项，并且第一个匹配项被选中，因此 `Enter` 会打开它。 |1093| v2.1.287 | [`n:<text>` 筛选器](#filter-sessions)按名称或第一个提示词查找会话。当任何筛选器处于活动状态时，您折叠的组会展开以显示其匹配项，并且第一个匹配项被选中，因此 `Enter` 会打开它。 |

1091| v2.1.287 | 作为[窥视回复](#peek-and-reply)发送的命令会在会话当前轮次结束时运行，包括在会话自身的输入框中一键入就立即运行的命令。内容恰好为 `/stop` 的回复会立即停止会话。 |1094| v2.1.287 | 作为[窥视回复](#peek-and-reply)发送的命令会在会话当前轮次结束时运行，包括在会话自身的输入框中一键入就立即运行的命令。内容恰好为 `/stop` 的回复会立即停止会话。 |

1092| v2.1.281 | [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 限制[转移](#what-carries-over-when-you-background)到你使用 `←` 或 `/bg` 后台的会话，以及你从 agent view 调度的会话。在此版本之前，生成的会话加载每个设置源。 |1095| v2.1.281 | [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 限制[转移](#what-carries-over-when-you-background)到你使用 `←` 或 `/bg` 后台的会话，以及你从 agent view 调度的会话。在此版本之前，生成的会话加载每个设置源。 |

386 386 

387当这些检查发现您的账户无法调用的模型时，Claude Code 会在这台机器上记住该拒绝长达一天，在此期间启动时会跳过记住的模型，而不再询问 Amazon Bedrock。Claude Code 会在距离上次检查已过十分钟后再次检查当前默认模型的记住拒绝，因此您的管理员重新启用的默认模型会恢复。要关闭此内存功能，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-CN/env-vars)。387当这些检查发现您的账户无法调用的模型时，Claude Code 会在这台机器上记住该拒绝长达一天，在此期间启动时会跳过记住的模型，而不再询问 Amazon Bedrock。Claude Code 会在距离上次检查已过十分钟后再次检查当前默认模型的记住拒绝，因此您的管理员重新启用的默认模型会恢复。要关闭此内存功能，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-CN/env-vars)。

388 388 

389<h3 id="when-your-organization-enforces-a-model-allowlist">

390 当您的组织强制执行模型允许列表时

391</h3>

392 

393如果您在托管设置中设置了 [`enforceAvailableModels`](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)，启动模型检查将仅使用您的 `availableModels` 列表允许的模型。这适用于 Amazon Bedrock Invoke API，并且需要 Claude Code v2.1.287 或更高版本。未设置 `enforceAvailableModels` 的列表不会限制这些检查。

394 

395检查会将每个条目与其将要发送的推理配置文件 ID（包括其[区域前缀](#cross-region-inference-profile-prefixes)）进行比较，因此请使用这些 ID 编写列表。此示例为模型解析为 `us.` 配置文件的部署允许 Opus 4.8 和 Sonnet 4.5：

396 

397```json theme={null}

398{

399 "availableModels": ["us.anthropic.claude-opus-4-8", "us.anthropic.claude-sonnet-4-5-20250929-v1:0"],

400 "enforceAvailableModels": true

401}

402```

403 

404有关别名、版本前缀和 `modelOverrides` 条目，请参阅[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)。

405 

389<h3 id="when-a-model-is-disabled-mid-session">406<h3 id="when-a-model-is-disabled-mid-session">

390 当模型在会话中被禁用时407 当模型在会话中被禁用时

391</h3>408</h3>

156 让 Claude 自动回复评论156 让 Claude 自动回复评论

157</h3>157</h3>

158 158 

159在您的会话发布工件后，Claude Code 会在会话运行期间监视该工件的评论。当可以编辑工件的人向 Claude 发送评论时，它会立即到达您的会话，Claude 可以读取线程并回复，而无需您询问。159在您的会话发布 Artifact 后，Claude Code 会监视该 Artifact 的评论。当可以编辑 Artifact 的人向 Claude 发送评论时，它会立即到达您的会话，Claude 可以读取线程并回复，而无需您询问。

160 160 

161您需要 Claude Code v2.1.228 或更高版本。如果您关闭了[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，Claude Code 不会监视评论。161您需要 Claude Code v2.1.228 或更高版本。如果您关闭了[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，Claude Code 不会监视评论。

162 162 

174* **在 `/tasks` 中停止任务**：Claude 停止回复该工件，直到您要求它在那里恢复回复。重新发布工件不会再次启动回复，当您稍后恢复会话时，停止仍然适用。174* **在 `/tasks` 中停止任务**：Claude 停止回复该工件，直到您要求它在那里恢复回复。重新发布工件不会再次启动回复，当您稍后恢复会话时，停止仍然适用。

175* **在 3 秒内按两次 `Ctrl+X Ctrl+K`**：[停止每个运行的后台子代理](/docs/zh-CN/interactive-mode#general-controls)的和弦也会停止 Claude 为会话的其余部分回复每个工件。要求 Claude 恢复回复不会撤销此停止。175* **在 3 秒内按两次 `Ctrl+X Ctrl+K`**：[停止每个运行的后台子代理](/docs/zh-CN/interactive-mode#general-controls)的和弦也会停止 Claude 为会话的其余部分回复每个工件。要求 Claude 恢复回复不会撤销此停止。

176 176 

177由 Claude Code 自行启动的监视可能会在 Artifact 数小时无活动后结束。要重新启动监视，请再次发布该 Artifact 或要求 Claude 监视它。

178 

177如果传递评论的服务变得不可用或停止响应，Claude Code 会尝试重新连接一段时间，然后停止监视您的会话正在监视的每个工件。179如果传递评论的服务变得不可用或停止响应，Claude Code 会尝试重新连接一段时间，然后停止监视您的会话正在监视的每个工件。

178 180 

179<h2 id="pull-live-data-with-mcp-connectors">181<h2 id="pull-live-data-with-mcp-connectors">

538</h3>538</h3>

539 539 

540<Tip>540<Tip>

541 循环遍历任务，为每个调用 `claude -p`。使用 `--allowedTools` 来限定批量操作的权限。541 循环遍历任务，为每个任务调用 `claude -p`。使用 `--allowedTools` 为批量操作预先批准工具。

542</Tip>542</Tip>

543 543 

544对于大型迁移或分析，你可以跨许多并行 Claude 调用分配工作。运行 [`/batch <instruction>`](/docs/zh-CN/commands#all-commands) 让 Claude 将更改分割到 5 到 30 个子代理中。每个子代理在自己的 worktree 中工作。要从你自己的脚本驱动扇出，请循环遍历 `claude -p`：544对于大型迁移或分析，你可以跨许多并行 Claude 调用分配工作。运行 [`/batch <instruction>`](/docs/zh-CN/commands#all-commands) 让 Claude 将更改分割到 5 到 30 个子代理中。每个子代理在自己的 worktree 中工作。要从你自己的脚本驱动扇出，请循环遍历 `claude -p`：

552 ```bash theme={null}552 ```bash theme={null}

553 for file in $(cat files.txt); do553 for file in $(cat files.txt); do

554 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \554 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \

555 --allowedTools "Edit,Bash(git commit *)"555 --allowedTools "Edit,Bash(git commit *)" \

556 --permission-mode dontAsk

556 done557 done

557 ```558 ```

558 </Step>559 </Step>

559 560 

560 <Step title="在几个文件上测试，然后大规模运行">561 <Step title="先在几个文件上测试，然后在全部文件上运行">

561 根据前 2-3 个文件出错的情况精化你的提示，然后在完整集合上运行。`--allowedTools` 标志限制 Claude 能做什么，这在你无人值守运行时很重要。562 根据前 2-3 个文件出现的问题改进提示词，然后在完整集合上运行。`--allowedTools` 标志预先批准迁移所需的工具，而 [`--permission-mode dontAsk`](/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 会拒绝其他任何需要批准的操作，这在无人值守运行时非常重要。

562 </Step>563 </Step>

563</Steps>564</Steps>

564 565 

326 为您的组织启用 channels326 为您的组织启用 channels

327</h3>327</h3>

328 328 

329可以从 [**claude.ai → 管理员设置 → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code) 为您的组织启用 channels（需要所有者角色），或通过在托管设置中将 `channelsEnabled` 设置为 `true`。329可以从 [**Organization settings > Claude Code > Channels**](https://claude.ai/admin-settings/claude-code) 为您的组织启用频道（需要所有者角色），或通过在托管设置中将 `channelsEnabled` 设置为 `true`。

330 330 

331启用后，您组织中的用户可以使用 `--channels` 将 channel 服务器选择加入到各个会话中。如果设置被禁用或未设置，MCP 服务器仍会连接，其工具可以工作，但 channel 消息不会到达。启动警告会告诉用户让管理员启用该设置。331启用后，您组织中的用户可以使用 `--channels` 将 channel 服务器选择加入到各个会话中。如果设置被禁用或未设置，MCP 服务器仍会连接，其工具可以工作，但 channel 消息不会到达。启动警告会告诉用户让管理员启用该设置。

332 332 

448 锁不涵盖的设置448 锁不涵盖的设置

449</h4>449</h4>

450 450 

451即使设置了所有五个锁，六个父提供的设置也会通过过滤器。在默认的先赢设置下，阻止父设置的管理员值是最高优先级管理员源中的值，除了 `allowedMcpServers` 当[MCP 服务器锁](#lock-behavior-across-sources)打开时。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。451即使设置了所有五个锁，这些父提供的设置也会通过过滤器：

452 452 

453* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值。453* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值。

454* **`allowedMcpServers`**：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。454* **`allowedMcpServers`**：当没有生效的管理员列表时，Claude Code 尊重父提供的允许列表。`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当没有管理员源提供列表时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。

455* **`availableModels`**：当赢家托管源未设置模型列表时，Claude Code 尊重父提供的模型列表。如果您的舰队限制模型，在赢家源中设置 `availableModels`。455* **`availableModels`**：当赢家托管源未设置模型列表时，Claude Code 尊重父提供的模型列表。如果您的舰队限制模型，在赢家源中设置 `availableModels`。

456* **`allowedProviders`**：当赢家托管源未设置 API 提供商允许列表时，Claude Code 尊重父提供的 API 提供商允许列表。如果您的舰队限制开发人员可以使用的 API 提供商，在赢家源中设置 `allowedProviders`。需要 Claude Code v2.1.285 或更高版本。

456* **`strictKnownMarketplaces`**：当赢家托管源未设置一个时，Claude Code 尊重父提供的插件市场允许列表。Claude Desktop 2.16120.0 或更高版本在其托管配置关闭用户添加的插件市场时发送一个。如果您的舰队限制市场，在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。457* **`strictKnownMarketplaces`**：当赢家托管源未设置一个时，Claude Code 尊重父提供的插件市场允许列表。Claude Desktop 2.16120.0 或更高版本在其托管配置关闭用户添加的插件市场时发送一个。如果您的舰队限制市场，在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。

457* **`blockedMarketplaces`**：父提供的市场阻止列表通过并添加到任何托管源设置的阻止列表，因为阻止列表只能进一步限制。需要 Claude Code v2.1.282 或更高版本。458* **`blockedMarketplaces`**：父提供的市场阻止列表通过并添加到任何托管源设置的阻止列表，因为阻止列表只能进一步限制。需要 Claude Code v2.1.282 或更高版本。

458* **`strictPluginOnlyCustomization`**：此密钥无论任何锁都通过过滤器，它使 Claude Code 忽略开发人员的自己定制，包括保护性 hooks。没有锁阻止它。459* **`strictPluginOnlyCustomization`**：此密钥无论任何锁都通过过滤器，它使 Claude Code 忽略开发人员的自己定制，包括保护性 hooks。没有锁阻止它。

459 460 

461在默认的先赢设置下，管理员值仅当位于最高优先级管理员源中时才阻止父的值，但 [MCP 服务器锁](#lock-behavior-across-sources)打开时的 `allowedMcpServers` 除外。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。

462 

460<h3 id="connect-claude-desktop">463<h3 id="connect-claude-desktop">

461 连接 Claude Desktop464 连接 Claude Desktop

462</h3>465</h3>

483 486 

484这些保证适用于每个通过 `/login` 登录的会话。Claude Desktop 启动的嵌入式会话按[将策略传递给 Claude Desktop 会话](#deliver-policy-to-claude-desktop-sessions)中所述获取其策略，遥测项目说明其导出的去向。487这些保证适用于每个通过 `/login` 登录的会话。Claude Desktop 启动的嵌入式会话按[将策略传递给 Claude Desktop 会话](#deliver-policy-to-claude-desktop-sessions)中所述获取其策略，遥测项目说明其导出的去向。

485 488 

486* **模型访问**：对策略未授予的模型的请求返回 400，`/model` 选择器被过滤到策略的 `availableModels` 允许列表。在策略中设置 [`enforceAvailableModels: true`](/docs/zh-CN/model-config#default-model-behavior)，以便 Default 选项解析为 `availableModels` 内的模型，而不是 Claude Code 的内置默认值；没有它，Default 保持可选，如果该模型未被授予，则在请求时被拒绝。489* **模型访问**：对策略未授予的模型的请求返回 400，`/model` 选择器被过滤到策略的 `availableModels` 允许列表。这包括开发人员选择模型之前会话启动时使用的模型；请参阅[在策略允许的模型上启动会话](/docs/zh-CN/claude-apps-gateway-config#start-sessions-on-a-model-the-policy-allows)。

487* **遥测目标**：在通过 `/login` 登录的会话中，CLI 将其 OTLP/HTTP 导出发送到网关，而不是任何本地设置的 `OTEL_EXPORTER_OTLP_ENDPOINT`，除非策略[将您的收集器命名为端点](/docs/zh-CN/claude-apps-gateway-config#export-directly-to-your-collector)。网关将它接收的导出中继到 [`telemetry.forward_to`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 中的目标。490* **遥测目标**：在通过 `/login` 登录的会话中，CLI 将其 OTLP/HTTP 导出发送到网关，而不是任何本地设置的 `OTEL_EXPORTER_OTLP_ENDPOINT`，除非策略[将您的收集器命名为端点](/docs/zh-CN/claude-apps-gateway-config#export-directly-to-your-collector)。网关将它接收的导出中继到 [`telemetry.forward_to`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 中的目标。

488 * 在[Claude Desktop 启动](#connect-claude-desktop)的嵌入式会话中，CLI 将其导出发送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 仅当该端点指向网关本身时才将网关会话令牌附加到这些导出。491 * 在[Claude Desktop 启动](#connect-claude-desktop)的嵌入式会话中，CLI 将其导出发送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 仅当该端点指向网关本身时才将网关会话令牌附加到这些导出。

489 * 没有为信号配置目标时，网关接受并丢弃它。492 * 没有为信号配置目标时，网关接受并丢弃它。

513 516 

514| 功能 | 状态 | 注释 |517| 功能 | 状态 | 注释 |

515| - | - | - |518| - | - | - |

516| 推理转发 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型转换和故障转移。Amazon Bedrock 上游使用 `bedrock-runtime` 端点和 AWS 默认凭证链；Amazon Bedrock [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)不是支持的上游。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)需要网关服务器上的 Claude Code v2.1.198 或更高版本。 |519| 推理转发 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型转换和故障转移。Amazon Bedrock 上游使用 `bedrock-runtime` 端点和 AWS 默认凭据链。[Amazon Bedrock Mantle 上游](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)需要网关服务器上的 Claude Code v2.1.283 或更高版本，[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)需要 v2.1.198 或更高版本。 |

517| 按 IdP 组的模型访问和托管设置 | 可用 | 模型访问在服务器端强制执行；托管设置按 IdP 组交付，由 CLI 在[托管设置层](/docs/zh-CN/settings#settings-precedence)应用 |520| 按 IdP 组的模型访问和托管设置 | 可用 | 模型访问在服务器端强制执行；托管设置按 IdP 组交付，由 CLI 在[托管设置层](/docs/zh-CN/settings#settings-precedence)应用 |

518| Claude Desktop | 可用（需要选择加入） | 网关在 `/user/bootstrap` 处为 Claude Desktop 的配置提供服务，一旦策略[使用 `desktop` 密钥选择加入](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 从其 Cowork 和 Code 选项卡以及从 Chat 选项卡（当您启用它时）发送模型请求通过网关。要打开 Chat 选项卡，请参阅[连接 Claude Desktop](#connect-claude-desktop)。需要网关服务器上的 Claude Code v2.1.203 或更高版本。 |521| Claude Desktop | 可用（需要选择加入） | 网关在 `/user/bootstrap` 处为 Claude Desktop 的配置提供服务，一旦策略[使用 `desktop` 密钥选择加入](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 从其 Cowork 和 Code 选项卡以及从 Chat 选项卡（当您启用它时）发送模型请求通过网关。要打开 Chat 选项卡，请参阅[连接 Claude Desktop](#connect-claude-desktop)。需要网关服务器上的 Claude Code v2.1.203 或更高版本。 |

519| 遥测扇出 (OTLP/HTTP) | 可用 | 按导出标识戳；protobuf 和 JSON 编码 |522| 遥测扇出 (OTLP/HTTP) | 可用 | 按导出标识戳；protobuf 和 JSON 编码 |

525| 需要功能标志获取的功能，例如 `/import` 和 `claude import` | 不可用 | CLI 在网关会话上跳过标志获取。[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)列出了关闭的内容 |528| 需要功能标志获取的功能，例如 `/import` 和 `claude import` | 不可用 | CLI 在网关会话上跳过标志获取。[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)列出了关闭的内容 |

526| 标准提示缓存 | 可用 | 网关将 `cache_control` 断点转发到每个上游。[缓存位置](/docs/zh-CN/prompt-caching#where-the-cache-lives)涵盖 CLI 标记的块，包括它在对话中途追加的系统上下文 |529| 标准提示缓存 | 可用 | 网关将 `cache_control` 断点转发到每个上游。[缓存位置](/docs/zh-CN/prompt-caching#where-the-cache-lives)涵盖 CLI 标记的块，包括它在对话中途追加的系统上下文 |

527| 1 小时缓存 TTL | 不可用 | CLI 在网关会话上省略扩展缓存 TTL beta，因为并非网关可以路由到的每个上游都支持 1 小时 TTL，因此通过网关的提示缓存使用 5 分钟 TTL；请参阅上面的 beta 标头注释 |530| 1 小时缓存 TTL | 不可用 | CLI 在网关会话上省略扩展缓存 TTL beta，因为并非网关可以路由到的每个上游都支持 1 小时 TTL，因此通过网关的提示缓存使用 5 分钟 TTL；请参阅上面的 beta 标头注释 |

528| Auto 模式 | 可用 | 遵循[第三方提供商规则](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：仅第三方提供商上符合条件的模型可以使用它。在 v2.1.207 之前，网关会话上的 auto 模式需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可通过托管策略 `env` 块交付 |531| 自动模式 | 可用 | 遵循[第三方提供商规则](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：仅第三方提供商上符合条件的模型可以使用它。在 v2.1.207 之前，网关会话上的自动模式需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可通过托管策略 `env` 块交付 |

529| 仅第一方优化，如全局缓存范围和令牌高效工具 | 不可用 | CLI 在网关会话上不启用它们；请参阅上面的 beta 标头注释 |532| 仅第一方优化，如全局缓存范围和令牌高效工具 | 不可用 | CLI 在网关会话上不启用它们；请参阅上面的 beta 标头注释 |

530| OTLP/gRPC | 不支持 | 仅 OTLP over HTTP |533| OTLP/gRPC | 不支持 | 仅 OTLP over HTTP |

531| SAML、LDAP 和其他非 OIDC 身份验证 | 不支持 | 仅 OIDC。如果需要，使用 OIDC 桥前置 |534| SAML、LDAP 和其他非 OIDC 身份验证 | 不支持 | 仅 OIDC。如果需要，使用 OIDC 桥前置 |

227 227 

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

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

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

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

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

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

234| `connect_timeout_seconds` | 否 | 网关打开 Postgres 连接时等待的秒数。从 `1` 到 `60` 的整数，默认 `5`。如果新网关实例启动时连接尝试超时，请提高它。需要网关服务器上的 Claude Code v2.1.274 或更高版本。早期版本在设置键时拒绝启动。 |234| `connect_timeout_seconds` | 否 | 网关打开 Postgres 连接时等待的秒数。从 `1` 到 `60` 的整数，默认 `5`。如果新网关实例启动时连接尝试超时，请提高它。需要网关服务器上的 Claude Code v2.1.274 或更高版本。早期版本在设置键时拒绝启动。 |

235| `readiness_grace_seconds` | 否 | Postgres 停止应答后 `/readyz` 继续报告就绪的秒数。从 `0` 到 `3600` 的整数，默认 `0`。请参阅[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)了解如何选择值。需要网关服务器上的 Claude Code v2.1.282 或更高版本。早期版本在设置键时拒绝启动。 |235| `readiness_grace_seconds` | 否 | Postgres 停止应答后 `/readyz` 继续报告就绪的秒数。从 `0` 到 `3600` 的整数，默认 `0`。请参阅[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)了解如何选择值。需要网关服务器上的 Claude Code v2.1.282 或更高版本。早期版本在设置键时拒绝启动。 |

242 242 

243`upstreams` 是一个有序列表。网关将推理转发到解析请求的模型的第一个上游。243`upstreams` 是一个有序列表。网关将推理转发到解析请求的模型的第一个上游。

244 244 

245在 `5xx`、`429`、`401`、`403`、`404` 或超时时，网关故障转移到下一个上游；其他 `4xx` 不会，因为这些错误可归因于请求而不是上游。`401` 或 `403` 意味着网关对该上游使用的凭证失败。`404` 意味着该上游不提供请求的模型，因此列表中的后续上游仍然可以。245在 `5xx`、`429`、`401`、`403`、`404` 或超时时，网关故障转移到下一个上游；其他 `4xx` 不会，因为这些错误可归因于请求而不是上游。`401` 或 `403` 意味着上游拒绝了网关使用的凭据，或拒绝其访问，例如对所请求模型的访问。`404` 意味着该上游不提供请求的模型，因此列表中的后续上游仍然可以。

246 246 

247如果您在上游上设置 `forward_user_identity: true`，它返回给携带开发人员电子邮件的请求的 `429` 不会故障转移。请参阅[每用户限制拒绝如何到达开发人员](#per-user-identity-headers-for-a-proxy-you-run)。247如果您在上游上设置 `forward_user_identity: true`，它返回给携带开发人员电子邮件的请求的 `429` 不会故障转移。请参阅[每用户限制拒绝如何到达开发人员](#per-user-identity-headers-for-a-proxy-you-run)。

248 248 

250 250 

251相同提供商的多个上游必须设置不同的 `name:`。251相同提供商的多个上游必须设置不同的 `name:`。

252 252 

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

254 254 

255<h4 id="upstream-error-messages">255<h4 id="upstream-error-messages">

256 上游错误消息256 上游错误消息

289 # base_url: https://api.anthropic.com # 默认；为前向代理覆盖289 # base_url: https://api.anthropic.com # 默认；为前向代理覆盖

290```290```

291 291 

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

293 293 

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

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

350upstreams:350upstreams:

351 - provider: bedrock351 - provider: bedrock

352 region: us-east-1352 region: us-east-1

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

354 # 或显式凭证：354 # 或显式凭据：

355 # auth:355 # auth:

356 # aws_access_key_id: ${AWS_AKID}356 # aws_access_key_id: ${AWS_AKID}

357 # aws_secret_access_key: ${AWS_SK}357 # aws_secret_access_key: ${AWS_SK}

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

364```364```

365 365 

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

367 367 

368显式凭证必须完整：当 `aws_access_key_id` 和 `aws_secret_access_key` 未一起设置时，或当 `aws_session_token` 在没有它们的情况下设置时，网关在启动时失败。在 v2.1.207 之前，部分 `auth:` 块通过验证。368显式凭据必须完整：当 `aws_access_key_id` 和 `aws_secret_access_key` 未一起设置时，或当 `aws_session_token` 在没有它们的情况下设置时，网关在启动时失败。在 v2.1.207 之前，部分 `auth:` 块通过验证。

369 369 

370| 设置 | 如何 |370| 设置 | 如何 |

371| - | - |371| - | - |

372| IAM 权限 | 授予网关的主体 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在推理配置文件 ARN 和底层基础模型 ARN 上。对于美国地区的内置目录：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。也在基础模型 ARN 上授予 `bedrock:CountTokens`。网关使用它（免费）来计算客户端放弃的请求的输入令牌，因此[支出限制](#admin)保持准确。没有它，网关回退到该计数的一令牌 Bedrock 请求。 |372| IAM 权限 | 授予网关的主体 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在推理配置文件 ARN 和底层基础模型 ARN 上。对于美国地区的内置目录：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。也在基础模型 ARN 上授予 `bedrock:CountTokens`。网关使用它（免费）来计算客户端放弃的请求的输入 token，因此[支出限制](#admin)保持准确。没有它，网关回退到针对该计数的单 token Bedrock 请求。 |

373| 模型访问 | Amazon Bedrock 在商业地区默认启用模型访问。剩余的帐户级门是 Anthropic 的一次性用例表：如果您的 AWS 帐户中没有人提交过，请打开 Amazon Bedrock 控制台，从模型目录中选择 Anthropic 模型，并完成表单。有关 AWS Organizations 表和提交者需要的权限，请参阅[提交用例详情](/docs/zh-CN/amazon-bedrock#1-submit-use-case-details)。 |373| 模型访问 | Amazon Bedrock 在商业地区默认启用模型访问。剩余的帐户级门是 Anthropic 的一次性用例表：如果您的 AWS 帐户中没有人提交过，请打开 Amazon Bedrock 控制台，从模型目录中选择 Anthropic 模型，并完成表单。有关 AWS Organizations 表和提交者需要的权限，请参阅[提交用例详情](/docs/zh-CN/amazon-bedrock#1-submit-use-case-details)。 |

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

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

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

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

378 378 

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

394```394```

395 395 

396<Warning>396<Warning>

397 网关不支持防护栏输入标签。它不向提示添加防护内容标签，因此 Amazon Bedrock 仅应用于标记输入的防护栏过滤器不在通过网关的流量上运行。对于哪些过滤器依赖输入标签，请参阅 Amazon Bedrock 文档中的[输入标签](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)。397 网关不支持防护栏输入标签。它不向提示词添加防护内容标签，因此 Amazon Bedrock 仅应用于标记输入的防护栏过滤器不在通过网关的流量上运行。对于哪些过滤器依赖输入标签，请参阅 Amazon Bedrock 文档中的[输入标签](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)。

398</Warning>398</Warning>

399 399 

400也在防护栏上授予 `bedrock:ApplyGuardrail` 给签署此上游请求的主体：网关的 AWS 主体，或使用 [`assume_role`](#bedrock-in-another-aws-account) 的 `role_arn` 中命名的角色。400也在防护栏上授予 `bedrock:ApplyGuardrail` 给签署此上游请求的主体：网关的 AWS 主体，或使用 [`assume_role`](#bedrock-in-another-aws-account) 的 `role_arn` 中命名的角色。

401 401 

402在每个 `bedrock` 上游或不在任何上游上设置 `guardrail`。网关拒绝在混合上启动，因为[故障转移](#multiple-upstreams)可能会将请求发送到没有防护栏的 Bedrock 上游。402在每个 `bedrock` 上游或不在任何上游上设置 `guardrail`。网关拒绝在混合上启动，因为[故障转移](#multiple-upstreams)可能会将请求发送到没有防护栏的 Bedrock 上游。

403 403 

404防护栏仅覆盖 Bedrock 上游。如果您在 `upstreams` 中列出另一个提供商，网关将请求发送到该提供商而不带防护栏。404防护栏仅覆盖 Bedrock 上游。如果您在 `upstreams` 中列出另一个提供商，网关将请求发送到该提供商而不带防护栏；如果该提供商是 [`mantle`](#amazon-bedrock-mantle-endpoint)，则网关拒绝启动。

405 405 

406当 `/v1/messages` 请求的正文携带 `amazon-bedrock-*` 字段（如 `amazon-bedrock-guardrailConfig`）到达设置了 `guardrail` 的 Bedrock 上游时，网关应答 400 而不是转发它。406当 `/v1/messages` 请求的正文携带 `amazon-bedrock-*` 字段（如 `amazon-bedrock-guardrailConfig`）到达设置了 `guardrail` 的 Bedrock 上游时，网关应答 400 而不是转发它。

407 407 

411 另一个 AWS 帐户中的 Bedrock411 另一个 AWS 帐户中的 Bedrock

412</h5>412</h5>

413 413 

414在 Bedrock 上游上设置 `assume_role`，网关仅使用其自己的 AWS 身份来调用您命名的角色上的 `sts:AssumeRole`，该角色可以在与网关不同的 AWS 帐户中。该上游的每个 Bedrock 请求都使用 STS 返回的一小时凭证签署，因此没有长期访问密钥跨帐户。414在 Bedrock 上游上设置 `assume_role`，网关仅使用其自己的 AWS 身份来调用您命名的角色上的 `sts:AssumeRole`，该角色可以在与网关不同的 AWS 帐户中。该上游的每个 Bedrock 请求都使用 STS 返回的一小时凭据签署，因此没有长期访问密钥跨帐户。

415 415 

416需要网关运行 Claude Code v2.1.281 或更高版本。早期网关在找到键时拒绝启动。416需要网关运行 Claude Code v2.1.281 或更高版本。早期网关在找到键时拒绝启动。

417 417 

448}448}

449```449```

450 450 

451* 如果 STS 拒绝或无法到达，网关不使用上游自己的凭证发送请求。它记录 STS 错误和要检查的内容，然后尝试您列出的下一个上游。[上游错误消息](#upstream-error-messages)覆盖当没有上游成功时客户端接收的内容。没有 `assume_role` 的后续上游将使用其自己的凭证提供请求，因此仅在这是您想要的情况下列出一个。451* 如果 STS 拒绝或无法到达，网关不使用上游自己的凭据发送请求。它记录 STS 错误和要检查的内容，然后尝试您列出的下一个上游。[上游错误消息](#upstream-error-messages)覆盖当没有上游成功时客户端接收的内容。没有 `assume_role` 的后续上游将使用其自己的凭据提供请求，因此仅在这是您想要的情况下列出一个。

452* 网关调用区域 STS 端点 `sts.<region>.amazonaws.com`，其网络必须到达。对于 FIPS 端点，在网关的环境中设置 `AWS_USE_FIPS_ENDPOINT=true` 而不是在 AWS 配置文件中的 `use_fips_endpoint`。452* 网关调用区域 STS 端点 `sts.<region>.amazonaws.com`，其网络必须到达。对于 FIPS 端点，在网关的环境中设置 `AWS_USE_FIPS_ENDPOINT=true` 而不是在 AWS 配置文件中的 `use_fips_endpoint`。

453* `assume_role` 仅适用于 `provider: bedrock` 并需要 SigV4 源凭证：当它在 `aws_bearer_token` 旁边设置时，网关拒绝启动。453* `assume_role` 仅适用于 `provider: bedrock` 并需要 SigV4 源凭据：当它在 `aws_bearer_token` 旁边设置时，网关拒绝启动。

454* 网关允许的每个开发人员都可以使用此上游；[`managed`](#managed) 控制哪些开发人员可能使用哪些模型。要保持通过角色提供的模型也不从另一个帐户提供，给它一个自定义 id，其 `upstream_model` 映射仅具有此上游的名称。对于这样的 id，网关跳过每个其他上游，因此请求和放弃请求的令牌计数都无法故障转移到另一个帐户。内置模型名称仍在每个上游按顺序尝试，包括这个，到达它的请求使用相同的角色签署，因此除非其帐户也应该提供它们，否则最后列出此上游。454* 网关允许的每个开发人员都可以使用此上游；[`managed`](#managed) 控制哪些开发人员可能使用哪些模型。要保持通过角色提供的模型也不从另一个帐户提供，给它一个自定义 id，其 `upstream_model` 映射仅具有此上游的名称。对于这样的 id，网关跳过每个其他上游，因此请求和放弃请求的 token 计数都无法故障转移到另一个帐户。对内置模型名称的请求仍可能[到达此上游](#multiple-upstreams)，网关会使用同一角色对其签名。除非其帐户也应该提供这些模型，否则请将此上游列在最后。

455 455 

456此示例给一个模型一个自定义 id，仅隔离上游提供：456此示例给一个模型一个自定义 id，仅隔离上游提供：

457 457 

468 每开发人员 AWS 成本属性468 每开发人员 AWS 成本属性

469</h5>469</h5>

470 470 

471默认情况下，网关使用一个凭证签署每个 Bedrock 请求，因此 AWS 在单个 IAM 主体下看到所有开发人员的请求。将 `session_name: email` 添加到 [`assume_role`](#bedrock-in-another-aws-account)，网关每个开发人员每小时调用一次 `sts:AssumeRole`，会话名称设置为该开发人员的电子邮件，并使用返回的凭证签署其请求，因此每个开发人员的请求在 AWS 下以其自己的假设角色会话到达。角色可以在网关自己的帐户中。471默认情况下，网关使用一个凭据签署每个 Bedrock 请求，因此 AWS 在单个 IAM 主体下看到所有开发人员的请求。将 `session_name: email` 添加到 [`assume_role`](#bedrock-in-another-aws-account)，网关每个开发人员每小时调用一次 `sts:AssumeRole`，会话名称设置为该开发人员的电子邮件，并使用返回的凭据签署其请求，因此每个开发人员的请求在 AWS 下以其自己的假设角色会话到达。角色可以在网关自己的帐户中。

472 472 

473需要网关运行 Claude Code v2.1.281 或更高版本。[AWS 上的成本属性](/docs/zh-CN/claude-apps-gateway-on-aws#cost-attribution)覆盖 IAM 角色和 AWS 计费显示会话的位置。473需要网关运行 Claude Code v2.1.281 或更高版本。[AWS 上的成本属性](/docs/zh-CN/claude-apps-gateway-on-aws#cost-attribution)覆盖 IAM 角色和 AWS 计费显示会话的位置。

474 474 

486 486 

487活跃开发人员每小时每个网关副本成本一个 STS 调用，并发首次请求共享一个调用。487活跃开发人员每小时每个网关副本成本一个 STS 调用，并发首次请求共享一个调用。

488 488 

489网关也在此角色上进行一个调用：客户端放弃的请求的令牌计数，因此[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)保持准确。该计数及其[一令牌回退请求](#amazon-bedrock)由共享 `claude-apps-gateway` 会话签署，因此 AWS 将回退属性到 `claude-apps-gateway` 而不是开发人员。489网关也在此角色上进行一个调用：客户端放弃的请求的 token 计数，因此[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)保持准确。该计数及其[单 token 回退请求](#amazon-bedrock)由共享 `claude-apps-gateway` 会话签署，因此 AWS 将回退属性到 `claude-apps-gateway` 而不是开发人员。

490 490 

491对于严格的每开发人员属性，在您列出的每个 Bedrock 上游上设置 `assume_role` 与 `session_name`。没有它的上游使用其自己的凭证签署它提供的请求。491对于严格的每开发人员属性，在您列出的每个 Bedrock 上游上设置 `assume_role` 与 `session_name`。没有它的上游使用其自己的凭据签署它提供的请求。

492 

493<h4 id="amazon-bedrock-mantle-endpoint">

494 Amazon Bedrock Mantle 端点

495</h4>

496 

497`mantle` 提供商将推理发送到 Amazon Bedrock 的 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。它需要网关服务器上的 Claude Code v2.1.283 或更高版本。早期网关版本在启动时拒绝它，因此请在添加之前升级每个副本。

498 

499下面的示例将 Mantle 放在首位，其后是一个 Amazon Bedrock 上游，用于提供 `models` 字段未列出的每个模型：

500 

501```yaml theme={null}

502upstreams:

503 - provider: mantle

504 region: us-east-1

505 models: [claude-opus-4-7, claude-haiku-4-5] # 必需

506 auth: {} # AWS 默认凭据链

507 - provider: bedrock

508 region: us-east-1

509 auth: {}

510```

511 

512下表列出 `mantle` 上游特有的字段。

513 

514| 字段 | 必需 | 描述 |

515| - | - | - |

516| `region` | 是 | AWS 区域。网关从它派生端点为 `https://bedrock-mantle.<region>.api.aws/anthropic`。 |

517| `models` | 是 | 您的 AWS 帐户在 Mantle 上获授权的模型，按客户端发送的名称命名，如 `claude-haiku-4-5`。只有这些模型会发送到此上游，其他每个模型都跳到下一个上游。 |

518| `auth` | 否 | 接受与 [Amazon Bedrock](#amazon-bedrock) 上游的 `auth` 块相同的键，遵循相同的规则。 |

519| `base_url` | 否 | 覆盖派生的端点。在末尾保留 `/anthropic` 路径。 |

520 

521为上游的 AWS 身份授予 Mantle 自己用于推理和 token 计数的 IAM 操作，[使用 Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)中列出了这些操作。

522 

523对于网关不知道的 Mantle 模型 ID，在顶层 [`models:`](#models) 块中添加一个条目，其 `upstream_model` 将此上游的名称映射到该 ID。然后也将该条目的 `id` 放入此上游的 `models` 字段。

524 

525`bedrock` 上游的 `guardrail` 和 `assume_role` 设置不会扩展到 Mantle 提供的请求：

526 

527* **`guardrail`**：网关不对发送到 Mantle 的请求应用 [Bedrock 防护栏](#apply-an-amazon-bedrock-guardrail)，因此当列出 `mantle` 上游而任何 `bedrock` 上游设置了 `guardrail` 时，网关拒绝启动。

528* **`assume_role`**：`mantle` 上游不接受 [`assume_role`](#bedrock-in-another-aws-account)。Mantle 提供的请求使用 `mantle` 上游自己的 `auth` 凭据发送，且不会[按开发人员归属](#per-developer-aws-cost-attribution)。

529 

530有关 Mantle 自身错误响应的含义，请参阅 [Mantle 端点错误](/docs/zh-CN/amazon-bedrock#mantle-endpoint-errors)。

492 531 

493<h4 id="claude-platform-on-aws">532<h4 id="claude-platform-on-aws">

494 AWS 上的 Claude Platform533 AWS 上的 Claude Platform

505 workspace_id: wrkspc_...544 workspace_id: wrkspc_...

506 auth:545 auth:

507 api_key: ${ANTHROPIC_AWS_API_KEY} # 作为 x-api-key 发送546 api_key: ${ANTHROPIC_AWS_API_KEY} # 作为 x-api-key 发送

508 # 或通过 AWS 默认凭证链的 SigV4：547 # 或通过 AWS 默认凭据链的 SigV4：

509 # auth: {}548 # auth: {}

510 # 或显式 SigV4 凭证：549 # 或显式 SigV4 凭据：

511 # auth:550 # auth:

512 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}551 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

513 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}552 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

515 # base_url: https://aws-external-anthropic.us-east-1.api.aws554 # base_url: https://aws-external-anthropic.us-east-1.api.aws

516```555```

517 556 

518平台在与 Amazon Bedrock 不同的 AWS 帐户中运行，并为其自己的服务名称 `aws-external-anthropic` 签署 SigV4 请求，因此 Bedrock 范围的 IAM 角色不授权它。`auth.api_key` 中的 API 密钥在同时设置 SigV4 凭证时优先。空 `auth` 块使用 AWS SDK 的默认凭证链，与 [Amazon Bedrock](#amazon-bedrock) 上游使用的链相同。557平台在与 Amazon Bedrock 不同的 AWS 帐户中运行，并为其自己的服务名称 `aws-external-anthropic` 签署 SigV4 请求，因此 Bedrock 范围的 IAM 角色不授权它。`auth.api_key` 中的 API 密钥在同时设置 SigV4 凭据时优先。空 `auth` 块使用 AWS SDK 的默认凭据链，与 [Amazon Bedrock](#amazon-bedrock) 上游使用的链相同。

519 558 

520| 字段 | 必需 | 描述 |559| 字段 | 必需 | 描述 |

521| - | - | - |560| - | - | - |

522| `region` | 是 | AWS 区域，小写字母、数字和连字符。网关从它派生端点为 `https://aws-external-anthropic.<region>.api.aws`。 |561| `region` | 是 | AWS 区域，小写字母、数字和连字符。网关从它派生端点为 `https://aws-external-anthropic.<region>.api.aws`。 |

523| `workspace_id` | 是 | 在每个请求上作为标头发送；平台需要它 |562| `workspace_id` | 是 | 在每个请求上作为标头发送；平台需要它 |

524| `auth.api_key` | 否 | 平台的 API 密钥，作为 `x-api-key` 发送。不是持有者令牌：两种身份验证模式是 API 密钥或 SigV4。 |563| `auth.api_key` | 否 | 平台的 API 密钥，作为 `x-api-key` 发送。不是持有者令牌：两种身份验证模式是 API 密钥或 SigV4。 |

525| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 否 | 显式 SigV4 凭证。在没有另一个的情况下设置一个在启动时失败。`auth.aws_session_token` 在它们旁边被接受。 |564| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 否 | 显式 SigV4 凭据。在没有另一个的情况下设置一个在启动时失败。`auth.aws_session_token` 在它们旁边被接受。 |

526| `base_url` | 否 | 覆盖派生的端点 |565| `base_url` | 否 | 覆盖派生的端点 |

527 566 

528因为平台解析第一方模型 ID，内置目录路由到它而不带 [`models:`](#models) 块。当您策划 `models:` 列表时，使用第一方 ID 键入条目 `anthropicAws:`。567因为平台解析第一方模型 ID，内置目录路由到它而不带 [`models:`](#models) 块。当您策划 `models:` 列表时，使用第一方 ID 键入条目 `anthropicAws:`。

538 - provider: vertex577 - provider: vertex

539 region: us-east5578 region: us-east5

540 project_id: example-prod579 project_id: example-prod

541 auth: {} # 首选：应用默认凭证580 auth: {} # 首选：应用默认凭据

542 # 或服务帐户密钥文件：581 # 或服务帐户密钥文件：

543 # auth: { service_account_json: /secrets/sa.json }582 # auth: { service_account_json: /secrets/sa.json }

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

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

546```585```

547 586 

548空 `auth` 块使用应用默认凭证：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 元数据或 GKE Workload Identity。服务帐户 JSON 密钥文件被支持但不鼓励；使用 Workload Identity 或将服务帐户附加到 GCE 或 Cloud Run 实例。587空 `auth` 块使用应用默认凭据：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 元数据或 GKE Workload Identity。服务帐户 JSON 密钥文件被支持但不鼓励；使用 Workload Identity 或将服务帐户附加到 GCE 或 Cloud Run 实例。

549 588 

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

551 590 

573 # api_key: ${FOUNDRY_API_KEY}612 # api_key: ${FOUNDRY_API_KEY}

574```613```

575 614 

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

577 616 

578| 设置 | 如何 |617| 设置 | 如何 |

579| - | - |618| - | - |

617 656 

618| 网关发送到此上游的请求 | 携带 `headers:` |657| 网关发送到此上游的请求 | 携带 `headers:` |

619| - | - |658| - | - |

620| `/v1/messages`，流式或不流式，和 `/v1/messages/count_tokens` | 是 |659| `/v1/messages`，流式或非流式，和 `/v1/messages/count_tokens` | 是 |

621| 从另一个上游故障转移的请求 | 是，仅此上游的 `headers:` |660| 从另一个上游故障转移的请求 | 是，仅此上游的 `headers:` |

622| Amazon Bedrock 的 `CountTokens` 调用用于客户端放弃的请求 | 否 |661| Amazon Bedrock 的 `CountTokens` 调用用于客户端放弃的请求 | 否 |

623| Workload Identity Federation 令牌交换 | 否 |662| Workload Identity Federation 令牌交换 | 否 |

634 多个上游673 多个上游

635</h4>674</h4>

636 675 

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

638 677 

639网关按顺序尝试上游。`5xx`、`429`、`401`、`403`、`404`、超时和缺失端点 (`501`) 故障转移；其他 `4xx` 不会。678网关按顺序尝试上游。`5xx`、`429`、`401`、`403`、`404`、超时和缺失端点 (`501`) 故障转移；其他 `4xx` 不会。

640 679 

689| 杠杆 | 如何 |728| 杠杆 | 如何 |

690| - | - |729| - | - |

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

692| 不同帐户 | 每个帐户一个 Amazon Bedrock 上游。默认链 (`auth: {}`) 使用 pod 的身份；对于第二个帐户，添加 [`assume_role`](#bedrock-in-another-aws-account) 以使用短期凭证到达它，或在 `auth:` 中设置显式凭证或持有者令牌。 |731| 不同帐户 | 每个帐户一个 Amazon Bedrock 上游。默认链 (`auth: {}`) 使用 pod 的身份；对于第二个帐户，添加 [`assume_role`](#bedrock-in-another-aws-account) 以使用短期凭据到达它，或在 `auth:` 中设置显式凭据或持有者令牌。 |

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

694| VPC / FIPS 端点 | 在上游上设置 `base_url:` 到您的 VPC 端点或 FIPS 端点 URL |733| VPC / FIPS 端点 | 在上游上设置 `base_url:` 到您的 VPC 端点或 FIPS 端点 URL |

695| 模型范围路由 | 仅自定义模型 `id`，不是内置 Claude 模型，跳过其 `upstream_model:` 映射中不存在的上游。网关按顺序在每个上游上尝试内置模型，并在映射没有条目时使用提供商的默认 ID，因此对于内置模型，映射改变上游接收的 ID 而不是它是否被尝试；拒绝 ID 的上游遵循与任何其他上游错误相同的[故障转移规则](#upstreams)；不在其 `upstream_model:` 映射中的上游被跳过，因此请求和放弃请求的令牌计数都无法故障转移到另一个帐户。内置模型名称仍在每个上游按顺序尝试，包括这个，到达它的请求使用相同的角色签署，因此除非其帐户也应该提供它们，否则最后列出此上游。 |734| 模型范围路由 | 仅自定义模型 `id`（即不是内置 Claude 模型的 id）会跳过其 `upstream_model:` 映射中不存在的上游。`mantle` 上游仅针对其 [`models` 字段](#amazon-bedrock-mantle-endpoint)中列出的模型被尝试。在其他每个上游上，网关按顺序尝试内置模型，并在映射没有条目时使用提供商的默认 ID，因此对于内置模型，映射改变上游接收的 ID 而不是它是否被尝试；拒绝 ID 的上游遵循与任何其他上游错误相同的[故障转移规则](#upstreams)。 |

696 735 

697在云提供商之间或直接 Anthropic API 之间故障转移改变哪个协议、地理位置和其他条款控制请求。736在云提供商之间或直接 Anthropic API 之间故障转移改变哪个协议、地理位置和其他条款控制请求。

698 737 

848 - match: {}887 - match: {}

849 cli:888 cli:

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

890 # 使 /model 中的 Default 选项在每个策略的

891 # 列表内解析。eng-contractors 策略继承 enforceAvailableModels。

892 enforceAvailableModels: true

851```893```

852 894 

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

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

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

858 900 

859`availableModels` 也在 `/v1/messages` 服务器端强制执行，因此被拒绝的模型返回 `400`，无论客户端发送什么。901`availableModels` 也在 `/v1/messages` 服务器端强制执行，因此被拒绝的模型返回 `400`，无论客户端发送什么。空列表会拒绝所有模型。该检查还涵盖开发者选择模型之前会话开始时使用的模型，因此请[让会话从策略允许的模型开始](#start-sessions-on-a-model-the-policy-allows)。

860 902 

861网关在中继请求之前验证 `model` 值本身，因此格式错误的值永远不会到达上游。它在两种情况下以 `400` 拒绝请求：903网关在中继请求之前验证 `model` 值本身，因此格式错误的值永远不会到达上游。它在两种情况下以 `400` 拒绝请求：

862 904 

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

884</Note>926</Note>

885 927 

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

929 让会话从策略允许的模型开始

930</h4>

931 

932如果 `availableModels` 未包含 Claude Code 的默认模型，会话会收到 `400` 响应，直到开发者选择一个已列出的模型，例如通过 `/model`。在网关会话中，默认模型是 `opus` 别名解析到的 Opus 模型，仅设置 `availableModels` 不会改变它。

933 

934要解决此问题，请在同一 `cli` 块中设置 [`enforceAvailableModels: true`](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)，然后检查列表中包含哪种条目：

935 

936* **别名（如 `sonnet`）或内置 ID（如 `claude-sonnet-4-6`）**：会话从其中一个模型开始，`/model` 中的 Default 选项解析为该模型

937* **列表中没有别名或内置 ID**：会话可能仍从内置默认模型开始，因此还要在该策略的 `cli` 块中将 [`model`](/docs/zh-CN/model-config#control-the-model-users-run-on) 设置为已列出的 ID 之一

938 

939此策略列出一个由 [`models`](#models) 定义的自定义 ID，并让会话从该 ID 开始：

940 

941```yaml theme={null}

942managed:

943 policies:

944 - match: { groups: [restricted-projects] }

945 cli:

946 availableModels: [claude-opus-restricted]

947 enforceAvailableModels: true

948 model: claude-opus-restricted

949```

950 

886<h4 id="matcher-values-that-stop-the-gateway-at-boot">951<h4 id="matcher-values-that-stop-the-gateway-at-boot">

887 在启动时停止网关的匹配器值952 在启动时停止网关的匹配器值

888</h4>953</h4>

920 cli:985 cli:

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

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

988 enforceAvailableModels: true # Default 在列表内解析

923 989 

924 # 权限策略990 # 权限策略

925 permissions:991 permissions:

1041 - match: { groups: [eng-contractors] }1107 - match: { groups: [eng-contractors] }

1042 cli:1108 cli:

1043 availableModels: [claude-sonnet-4-6]1109 availableModels: [claude-sonnet-4-6]

1110 enforceAvailableModels: true

1044 desktop:1111 desktop:

1045 isLocalDevMcpEnabled: false1112 isLocalDevMcpEnabled: false

1046 disableAutoUpdates: true1113 disableAutoUpdates: true

1342 完整示例1409 完整示例

1343</h2>1410</h2>

1344 1411 

1345此完整参考配置演示了每个核心部分；[HTTP 调整块](#http-tuning)保持其默认值。复制它，删除你不需要的，并填入你的值。[快速入门](/docs/zh-CN/claude-apps-gateway#quickstart)中的配置是此的最小版本。1412此完整参考配置演示了每个核心部分；[HTTP 调整块](#http-tuning)保持其默认值。复制它，删除您不需要的，并填入您的值。[快速入门](/docs/zh-CN/claude-apps-gateway#quickstart)中的配置是此的最小版本。

1346 1413 

1347```yaml gateway.yaml theme={null}1414```yaml gateway.yaml theme={null}

1348# 运行方式：1415# 运行方式：

1434 # region: us-east-11501 # region: us-east-1

1435 # auth: {}1502 # auth: {}

1436 1503 

1504 # - provider: mantle

1505 # region: us-east-1

1506 # models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]

1507 # auth: {}

1508 

1437 # - provider: anthropicAws1509 # - provider: anthropicAws

1438 # region: us-east-11510 # region: us-east-1

1439 # workspace_id: wrkspc_...1511 # workspace_id: wrkspc_...

1456 upstream_model:1528 upstream_model:

1457 anthropic: claude-opus-4-81529 anthropic: claude-opus-4-8

1458 # bedrock: us.anthropic.claude-opus-4-81530 # bedrock: us.anthropic.claude-opus-4-8

1531 # mantle: anthropic.claude-opus-4-8

1459 # anthropicAws: claude-opus-4-81532 # anthropicAws: claude-opus-4-8

1460 # vertex: claude-opus-4-81533 # vertex: claude-opus-4-8

1461 # foundry: <your-opus-deployment-name>1534 # foundry: <your-opus-deployment-name>

1473 - match: { groups: [contractors] }1546 - match: { groups: [contractors] }

1474 cli:1547 cli:

1475 availableModels: [claude-haiku-4-5]1548 availableModels: [claude-haiku-4-5]

1476 # 将默认选择器选项限制为 availableModels 而不是

1477 # 层默认，因此承包商不会在默认上获得 400。

1478 enforceAvailableModels: true

1479 # allow 自动批准这些工具；它不阻止其余的。1549 # allow 自动批准这些工具；它不阻止其余的。

1480 # 添加拒绝规则以限制工具。1550 # 添加拒绝规则以限制工具。

1481 permissions: { allow: [Read, Grep] }1551 permissions: { allow: [Read, Grep] }

1482 - match: {}1552 - match: {}

1483 cli:1553 cli:

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

1555 # 将默认选择器选项限制为每个策略的 availableModels，

1556 # 而不是内置默认值，因此任何角色都不会在默认上获得 400。

1557 # 承包商策略继承此键。

1558 enforceAvailableModels: true

1485 permissions:1559 permissions:

1486 allow: [Read, Grep, Bash, Edit]1560 allow: [Read, Grep, Bash, Edit]

1487 deny: ["WebFetch"]1561 deny: ["WebFetch"]

429 429 

430当请求头总大小超过 256 KiB，或者在您设置了 [`limits.max_request_header_bytes`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 时超过该值，网关会返回 `431`。对于这些请求，网关不会写入任何日志行或审计事件。v2.1.284 之前的网关版本在超过 16 KiB 时返回 `431`。430当请求头总大小超过 256 KiB，或者在您设置了 [`limits.max_request_header_bytes`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 时超过该值，网关会返回 `431`。对于这些请求，网关不会写入任何日志行或审计事件。v2.1.284 之前的网关版本在超过 16 KiB 时返回 `431`。

431 431 

432需要更改的内容取决于网关的版本和配置：432从以下各项中第一个适用于您网关的情况开始处理：

433 433 

434* **网关版本早于 v2.1.284**：升级网关434* **网关版本早于 v2.1.284**：升级网关

435* **设置了 `limits.max_request_header_bytes`**：提高该值或删除该键435* **设置了 `limits.max_request_header_bytes`**：提高该值或删除该键

436* **以上均不适用，或之后仍出现 `431`**：让您的 IdP 发出更少的组。[身份提供者设置](#identity-provider-setup)介绍了 Okta、Microsoft Entra ID 和 Google Workspace 如何提供组436* **以上均不适用，或之后仍出现 `431`**：让您的 IdP 发出更少的组。[身份提供者设置](#identity-provider-setup)介绍了 Okta、Microsoft Entra ID 和 Google Workspace 如何提供组

437 437 

438精简组声明时，请保留您在以下设置中指定的组，这些设置决定开发者的访问权限、策略和支出上限：

439 

440* **[`oidc.allowed_groups`](/docs/zh-CN/claude-apps-gateway-config#oidc)**：决定谁可以登录

441* **[`admin.admin_groups`](/docs/zh-CN/claude-apps-gateway-config#admin)**：决定谁可以使用其网关会话调用管理 API

442* **[`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 中的 `match.groups`**：决定哪个策略适用于开发者

443* **`rbac_group` [支出上限](/docs/zh-CN/claude-apps-gateway-spend-limits)**：决定哪些组上限适用于开发者

444 

438<h2 id="related">445<h2 id="related">

439 相关446 相关

440</h2>447</h2>

12 12 

13云会话是在云基础设施上运行的 Claude Code 会话，而不是在你的机器上运行。默认情况下，它在 Anthropic 管理的基础设施上运行，或在路由到你的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。即使关闭笔记本电脑后，会话也会继续运行，你可以从任何设备检查或控制它。13云会话是在云基础设施上运行的 Claude Code 会话，而不是在你的机器上运行。默认情况下，它在 Anthropic 管理的基础设施上运行，或在路由到你的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。即使关闭笔记本电脑后，会话也会继续运行，你可以从任何设备检查或控制它。

14 14 

15要让云端会话从 GitHub 克隆代码并推送分支，请使用其中一种 [GitHub 连接方式](#github-authentication-options)连接 GitHub。如果您的仓库位于 GitLab、Bitbucket 或其他托管平台上，请参阅[平台限制](#limitations)了解哪些功能可用。

16 

15你可以从以下任何界面启动云会话：17你可以从以下任何界面启动云会话：

16 18 

17* **浏览器**：[claude.ai/code](https://claude.ai/code)，也称为网络上的 Claude Code19* **浏览器**：[claude.ai/code](https://claude.ai/code)，也称为网络上的 Claude Code

20* **终端**：[`claude --cloud`](#from-terminal-to-cloud)22* **终端**：[`claude --cloud`](#from-terminal-to-cloud)

21* **例程**：[计划和触发的运行](/docs/zh-CN/routines)每次都作为云会话运行23* **例程**：[计划和触发的运行](/docs/zh-CN/routines)每次都作为云会话运行

22 24 

23要让 Claude 为一项工作启动并跟踪许多云会话，请使用[项目](/docs/zh-CN/claude-projects)。在你的终端、IDE 或选择了 **Local** 的桌面应用中的会话在你自己的机器上运行。要从手机或浏览器控制这些本地会话之一，请使用[远程控制](/docs/zh-CN/remote-control)。25完成设置后，可使用本页在终端和云端之间移动工作、管理和共享会话、为 Pull Request 启用自动修复，以及进行故障排除。

24 

25<Tip>

26 初次使用云会话？从[入门](/docs/zh-CN/web-quickstart)开始，连接你的 GitHub 账户并提交你的第一个任务。

27</Tip>

28 26 

29本页涵盖：27<Note>

28 以下情况在其他页面中介绍：

30 29 

31* [云环境](#cloud-environments)：会话运行的位置，以及在哪里配置30 * **启动您的第一个云端会话**：[云端会话入门](/docs/zh-CN/web-quickstart)介绍如何连接 GitHub，并引导您在浏览器中完成一个任务

32* [GitHub 身份验证选项](#github-authentication-options)：两种连接 GitHub 的方式31 * **为一项工作使用多个云端会话**：[项目](/docs/zh-CN/claude-projects)可让 Claude 为您启动并跟踪这些会话

33* [在终端和云之间移动任务](#move-tasks-between-terminal-and-cloud)，使用 `--cloud` 和 `--teleport`32 * **从其他设备控制本地会话**：在终端、IDE 或选择了 **Local** 的桌面应用中的会话在您的机器上运行，[Remote Control](/docs/zh-CN/remote-control) 让您可以从手机或浏览器访问这些会话

34* [处理会话](#work-with-sessions)：权限模式、审查、共享、归档、删除33</Note>

35* [自动修复拉取请求](#auto-fix-pull-requests)：自动响应 CI 失败和审查评论

36* [安全和隔离](#security-and-isolation)：会话如何隔离

37* [限制](#limitations)：速率限制和平台限制

38 34 

39<h2 id="cloud-environments">35<h2 id="cloud-environments">

40 云环境36 云环境

41</h2>37</h2>

42 38 

43每个云会话都在一个[云环境](/docs/zh-CN/cloud-environments)中运行，这是一个保存的配置，控制网络访问、环境变量和设置脚本。如果你还没有环境，入门会设置一个**默认**环境，具有[**受信任**网络访问](/docs/zh-CN/cloud-environments#access-levels)，要么为你创建它，要么要求你创建它。请参阅[默认环境](/docs/zh-CN/cloud-environments#the-default-environment)，了解在你的计划上会发生哪种情况，以及当你有多个环境时会话如何选择环境。39每个云端会话都在一个[云环境](/docs/zh-CN/cloud-environments)中运行，这是一个保存的配置，控制网络访问、环境变量和设置脚本。

44 40 

45相同的环境适用于你启动云会话的任何地方：网络、终端、[Claude Tag](https://claude.com/docs/claude-tag/overview)、[routines](/docs/zh-CN/routines) 以及移动和 Desktop 应用。Claude Tag 频道会话仅使用组织级环境，要么是[共享环境](/docs/zh-CN/cloud-environments#organization-shared-environments)，要么是[自托管环境](/docs/zh-CN/self-hosted-environments)。41* **您的第一个环境**：如果您还没有环境，入门流程会设置一个具有[**受信任**网络访问](/docs/zh-CN/cloud-environments#access-levels)的**默认**环境，要么为您创建它，要么要求您创建它。请参阅[默认环境](/docs/zh-CN/cloud-environments#the-default-environment)，了解在您的计划上会发生哪种情况

46 42* **会话使用哪个环境**：请参阅[默认环境](/docs/zh-CN/cloud-environments#the-default-environment)，了解当您有多个环境时会话如何选择环境

47请参阅[配置云环境](/docs/zh-CN/cloud-environments)以更改环境允许的内容、设置变量或添加设置脚本，以及[已安装的工具](/docs/zh-CN/cloud-environments#installed-tools)以了解会话在没有任何配置的情况下包含的内容。43* **更改会话可以访问的内容或在启动时运行的内容**：请参阅[配置云环境](/docs/zh-CN/cloud-environments)

44* **无需任何配置即已安装的内容**：请参阅[已安装的工具](/docs/zh-CN/cloud-environments#installed-tools)

48 45 

49<h2 id="github-authentication-options">46<h2 id="github-authentication-options">

50 GitHub 身份验证选项47 GitHub 身份验证选项

57| **GitHub App** | 在[网络快速入门](/docs/zh-CN/web-quickstart)期间授权 Claude GitHub App | 任何公开存储库，以及安装了 Claude GitHub App 的私有存储库 | 浏览器入门；想要[自动修复](#auto-fix-pull-requests)的团队 |54| **GitHub App** | 在[网络快速入门](/docs/zh-CN/web-quickstart)期间授权 Claude GitHub App | 任何公开存储库，以及安装了 Claude GitHub App 的私有存储库 | 浏览器入门；想要[自动修复](#auto-fix-pull-requests)的团队 |

58| **`/web-setup`** | 在终端中运行 `/web-setup` 以将本地 `gh` CLI 令牌发送到你的 Claude 账户 | 你的 `gh` 令牌可以访问的任何存储库，无论是否安装了 Claude GitHub App | 已经使用 `gh` 的个人开发者 |55| **`/web-setup`** | 在终端中运行 `/web-setup` 以将本地 `gh` CLI 令牌发送到你的 Claude 账户 | 你的 `gh` 令牌可以访问的任何存储库，无论是否安装了 Claude GitHub App | 已经使用 `gh` 的个人开发者 |

59 56 

60在存储库上安装 Claude GitHub App 也会为其中的拉取请求启用[自动修复](#auto-fix-pull-requests)。57以下功能依赖于仓库上已安装 Claude GitHub App：

61 58 

62[项目](/docs/zh-CN/claude-projects)中的线程需要在每个克隆的存储库上安装 Claude GitHub App，无论你使用哪种连接方法。请参阅[设置 GitHub 访问权限](/docs/zh-CN/claude-projects#set-up-github-access)。59* **自动修复**：在仓库上安装 Claude GitHub App 也会为其中的 Pull Request 启用[自动修复](#auto-fix-pull-requests)

60* **项目**：[项目](/docs/zh-CN/claude-projects)中的线程需要在其克隆的每个仓库上安装 Claude GitHub App，无论您使用哪种方法连接。请参阅[设置 GitHub 访问权限](/docs/zh-CN/claude-projects#set-up-github-access)

63 61 

64在 Anthropic 托管的环境中，你的 GitHub 凭证在 Anthropic 的服务器上保持加密状态，永远不会进入会话的虚拟机。来自虚拟机的 GitHub 操作通过 [GitHub 代理](/docs/zh-CN/cloud-environments#github-proxy)进行，它在服务器端附加凭证。62在 Anthropic 托管的环境中，你的 GitHub 凭证在 Anthropic 的服务器上保持加密状态，永远不会进入会话的虚拟机。来自虚拟机的 GitHub 操作通过 [GitHub 代理](/docs/zh-CN/cloud-environments#github-proxy)进行，它在服务器端附加凭证。

65 63 

66有关 `/schedule` 如何在创建 routine 之前检查存储库访问权限，请参阅[存储库和分支权限](/docs/zh-CN/routines#repositories-and-branch-permissions)。有关 `/web-setup` 演练（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。64有关 `/web-setup` 的分步说明（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。

67 

68快速网络设置是一个组织设置，允许成员使用 `/web-setup` 连接 GitHub，在浏览器入门期间跳过 Claude GitHub App 安装提示，并让浏览器入门为他们创建[**默认**环境](/docs/zh-CN/cloud-environments#the-default-environment)，而不是显示环境表单。在 Team 和 Enterprise 计划上，默认情况下它是关闭的，这会隐藏 `/web-setup`。[所有者](/docs/zh-CN/server-managed-settings#access-control)可以在 [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code) 处使用**快速网络设置**切换来打开它。

69 65 

70<Note>66<Note>

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

72</Note>68</Note>

73 69 

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

71 面向 Team 和 Enterprise 的快速设置

72</h3>

73 

74快速设置是一项组织设置，可减少成员在 GitHub 和环境设置中的步骤。在 Team 和 Enterprise 计划中，该设置默认处于关闭状态。

75 

76启用后，成员会看到以下变化：

77 

78* **`/web-setup`**：成员可以使用 `/web-setup` 连接 GitHub。该设置关闭时，此命令处于隐藏状态

79* **GitHub App 提示**：浏览器入门引导会跳过 Claude GitHub App 安装提示

80* **第一个环境**：浏览器入门引导会为成员创建 [**Default** 环境](/docs/zh-CN/cloud-environments#the-default-environment)，而不是显示环境表单

81 

82[所有者](/docs/zh-CN/server-managed-settings#access-control)可以在 [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code) 处通过 **Quick setup** 开关启用该设置。

83 

74<h2 id="move-tasks-between-terminal-and-cloud">84<h2 id="move-tasks-between-terminal-and-cloud">

75 在终端和云之间移动任务85 在终端和云之间移动任务

76</h2>86</h2>

78这些工作流需要 [Claude Code CLI](/docs/zh-CN/quickstart) 登录到同一个 claude.ai 账户。您可以从终端启动新的云会话，或将云会话拉入终端以继续本地工作。云会话即使在您关闭笔记本电脑后也会持续存在，您可以从任何地方（包括 Claude 移动应用）监控它们。88这些工作流需要 [Claude Code CLI](/docs/zh-CN/quickstart) 登录到同一个 claude.ai 账户。您可以从终端启动新的云会话，或将云会话拉入终端以继续本地工作。云会话即使在您关闭笔记本电脑后也会持续存在，您可以从任何地方（包括 Claude 移动应用）监控它们。

79 89 

80<Note>90<Note>

81 从 CLI 来看，会话切换是单向的：您可以使用 `--teleport` 将云会话拉入终端，但无法将现有的终端会话推送到云。带有任务描述的 `--cloud` 标志为您当前的存储库创建新的云会话；带有 `-p` 和会话 ID 或 claude.ai/code URL 时，它会改为 [将消息排队到该现有会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。[Desktop 应用](/docs/zh-CN/desktop#continue-in-another-surface) 提供了一个"继续在"菜单，可以将本地会话发送到云。91 从 CLI 来看，会话切换是单向的：您可以使用 `--teleport` 将云端会话拉入终端，但无法将现有的终端会话推送到云端。带有任务描述的 `--cloud` 标志会为您当前的仓库创建新的云端会话；带有 `-p` 和会话 ID 或 claude.ai/code URL 时，它会改为[将消息排队到该现有会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。[Desktop 应用](/docs/zh-CN/desktop#continue-in-another-surface)可以通过其 **Open in** 菜单，将其 Code 标签页中的本地会话发送到云端。

82</Note>92</Note>

83 93 

84<h3 id="from-terminal-to-cloud">94<h3 id="from-terminal-to-cloud">

173 从 CLI 发送后续消息183 从 CLI 发送后续消息

174</h3>184</h3>

175 185 

176一旦云会话运行，无论它在哪里执行，都可以从任何您使用 `claude auth login` 登录的机器上的 `claude` CLI 向它发送后续消息。CLI 使用您的 Anthropic 账户凭据进行身份验证，不发送任何本地会话状态，因此该命令不需要从启动会话的机器运行，并且在每个 shell 中都是相同的，包括 PowerShell。186一旦云端会话运行，无论它在哪里执行，都可以从任何您使用 `claude auth login` 登录的机器上的 `claude` CLI 向它发送后续消息。CLI 使用您的 Anthropic 账户凭据进行身份验证，不发送任何本地会话状态，因此该命令不需要从启动会话的机器运行。

177 187 

178该命令发布一条消息并退出：188该命令发布一条消息并退出：

179 189 

189 `--cloud` 需要 Anthropic 账户。当 Claude Code 为 Amazon Bedrock、Google Cloud 的 Agent Platform 或其他第三方提供商配置时，它不可用。仅通过 `ANTHROPIC_BASE_URL` 配置的 [LLM 网关](/docs/zh-CN/llm-gateway) 不算作此检查的第三方提供商，但您仍需要使用 `claude auth login` 登录。您组织的 `allow_remote_sessions` 策略也必须启用。所有者可以在 claude.ai/admin-settings/claude-code 的 Claude Code 管理设置中打开它。199 `--cloud` 需要 Anthropic 账户。当 Claude Code 为 Amazon Bedrock、Google Cloud 的 Agent Platform 或其他第三方提供商配置时，它不可用。仅通过 `ANTHROPIC_BASE_URL` 配置的 [LLM 网关](/docs/zh-CN/llm-gateway) 不算作此检查的第三方提供商，但您仍需要使用 `claude auth login` 登录。您组织的 `allow_remote_sessions` 策略也必须启用。所有者可以在 claude.ai/admin-settings/claude-code 的 Claude Code 管理设置中打开它。

190</Note>200</Note>

191 201 

192<h4 id="output-and-errors">202<h4 id="output">

193 输出和错误203 输出

194</h4>204</h4>

195 205 

196成功时，该命令打印会话 ID 和查看会话的链接：206成功时，该命令打印会话 ID 和查看会话的链接：

203 213 

204传递 `--output-format json` 以获得机器可读的结果：成功时为 `{ok, session_id, url}`，或发送失败时为 `{ok: false, session_id, error}`，例如当会话缺失或已存档时。配置错误（例如不支持的提供商或禁用的组织策略）打印到 stderr，不带 JSON。`--output-format stream-json` 不支持 `--cloud <session-id>`。214传递 `--output-format json` 以获得机器可读的结果：成功时为 `{ok, session_id, url}`，或发送失败时为 `{ok: false, session_id, error}`，例如当会话缺失或已存档时。配置错误（例如不支持的提供商或禁用的组织策略）打印到 stderr，不带 JSON。`--output-format stream-json` 不支持 `--cloud <session-id>`。

205 215 

206CLI 在错误前加上 `Error: ` 前缀。失败的传递被包装为 `failed to send message to cloud session <id>: <reason>`。216如果发送失败，请参阅[发送到云端会话时的错误](#errors-when-sending-to-a-cloud-session)。

207 

208| 消息 | 含义 |

209| - | - |

210| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code 为第三方提供商配置。该消息使用您的配置使用的标签命名提供商，例如 `Amazon Bedrock` 或 `Google Vertex AI`。删除该提供商的配置，例如通过取消设置 `CLAUDE_CODE_USE_BEDROCK`，并使用 Anthropic 账户登录（`claude auth login`）。 |

211| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 组织策略已关闭。 |

212| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code 无法获取您的组织策略，因此它拒绝发送而不是假设云会话被允许。检查您的网络连接并重试。 |

213| `Attaching to an existing cloud session is not enabled for your account.` | 您运行了 `--cloud <session-id>` 而没有 `-p`。使用 `claude -p "your message" --cloud <session-id>` 发送消息。 |

214| `Session not found: <id>` | ID 或 URL 与您可以访问的会话不匹配。根据会话的 claude.ai/code URL 检查它。 |

215| `cloud session <id> is archived and cannot accept new messages` | 会话已被存档。改为启动新会话。 |

216 217 

217<h3 id="from-cloud-to-terminal">218<h3 id="from-cloud-to-terminal">

218 从云到终端219 从云到终端

239| 要求 | 详情 |240| 要求 | 详情 |

240| - | - |241| - | - |

241| 干净的 git 状态 | 您的工作目录必须没有未提交的更改。如果需要，Teleport 会提示您隐藏更改。 |242| 干净的 git 状态 | 您的工作目录必须没有未提交的更改。如果需要，Teleport 会提示您隐藏更改。 |

242| 正确的存储库 | 您必须从同一存储库的检出运行 `--teleport`，而不是 fork。如果您从不同存储库的检出运行它，Claude Code 会显示一个错误，命名会话的存储库和您的检出的存储库。在 v2.1.219 之前，错误没有命名您的检出的存储库。如果 Claude Code 无法将您的远程解析为主机名，例如 SSH 主机别名如 `git@work:owner/repo.git`，它会要求您确认，并在远程的所有者和存储库名称与会话的存储库匹配时接受检出。 |243| 正确的仓库 | 您必须从同一仓库的检出运行 `--teleport`，而不是 fork。如果您从不同仓库的检出运行它，Claude Code 会显示一个错误，指明会话的仓库和您的检出的仓库。如果 Claude Code 无法将您的远程解析为主机名，例如 SSH 主机别名如 `git@work:owner/repo.git`，它会要求您确认，并在远程的所有者和仓库名称与会话的仓库匹配时接受检出。 |

243| 分支可用 | 来自云会话的分支必须已推送到远程。Teleport 会自动获取并检出它。 |244| 分支可用 | 来自云会话的分支必须已推送到远程。Teleport 会自动获取并检出它。 |

244| 相同账户 | 您必须使用云会话中使用的相同 claude.ai 账户进行身份验证。 |245| 相同账户 | 您必须使用云会话中使用的相同 claude.ai 账户进行身份验证。 |

245 246 

249 `--teleport` 不可用250 `--teleport` 不可用

250</h4>251</h4>

251 252 

252Teleport 需要 claude.ai 订阅身份验证。如果您通过 API 密钥进行身份验证，请运行 `/login` 以改为使用您的 claude.ai 账户登录。如果错误命名您的提供商，云会话不可通过第三方提供商获得；请参阅 [错误表](#output-and-errors)。如果您已通过 claude.ai 登录且 `--teleport` 仍不可用，您的组织可能已禁用云会话。253Teleport 需要 claude.ai 订阅身份验证。请找到与您相符的情况：

254 

255* **您通过 API 密钥进行身份验证**：运行 `/login` 以改为使用您的 claude.ai 账户登录

256* **错误指明了您的提供商**：云端会话无法通过第三方提供商使用。请参阅[错误表](#errors-when-sending-to-a-cloud-session)

257* **您已通过 claude.ai 登录**：您的组织可能已禁用云端会话

253 258 

254<h2 id="work-with-sessions">259<h2 id="work-with-sessions">

255 处理会话260 处理会话

257 262 

258会话出现在 claude.ai/code 的侧边栏中。从那里你可以审查更改、与队友共享、归档完成的工作或永久删除会话。263会话出现在 claude.ai/code 的侧边栏中。从那里你可以审查更改、与队友共享、归档完成的工作或永久删除会话。

259 264 

260<h3 id="take-back-a-queued-message">265<h3 id="permission-modes-in-cloud-sessions">

261 取回已排队的消息266 云端会话中的权限模式

262</h3>267</h3>

263 268 

264如果你在 Claude 工作时发送消息，该消息会排队直到 Claude 读取它。要取回已排队的消息，请点击它上面的 ✕。文本返回到消息框，以便你可以编辑它或发送其他内容。269无论是在创建任务时还是在会话运行期间，您都可以从[模式下拉菜单](/docs/zh-CN/permission-modes#switch-permission-modes)为云端会话选择[权限模式](/docs/zh-CN/permission-modes)。

270 

271在以下任一情况下，Claude Code 会以会话原先所处的权限模式恢复该会话：

272 

273* 重新打开 Anthropic 托管的[环境已过期](#environment-expired)的会话

274* 向自托管运行程序[在空闲时释放](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)的会话发送消息

265 275 

266如果 Claude 已经读取了消息，它会保留在对话中。276<h3 id="review-changes">

277 审查更改

278</h3>

279 

280每个会话都会显示一个 diff 指示器，标示添加和删除的行数，例如 `+42 -18`。选择它即可打开 diff 视图，在特定行上添加内联评论，并随下一条消息将这些评论发送给 Claude。

281 

282diff 视图默认将会话的更改与其基础分支进行比较。要与仓库中的任何其他分支进行比较，请选择 **Compare against** 并选择一个分支。

283 

284Claude Code 根据原始 git blob 内容计算这些 diff，因此仓库中配置的 diff 驱动程序和 `textconv` 过滤器不适用。

285 

286以下步骤在其他文档中介绍：

287 

288* **完整演练（包括 PR 创建）**：请参阅[审查和迭代](/docs/zh-CN/web-quickstart#review-and-iterate)

289* **让 Claude 自动监控 PR 的 CI 失败和审查评论**：请参阅[自动修复 Pull Request](#auto-fix-pull-requests)

267 290 

268<h3 id="manage-context">291<h3 id="manage-context">

269 管理上下文292 管理上下文

291 314 

292[Agent teams](/docs/zh-CN/agent-teams) 默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)来启用。315[Agent teams](/docs/zh-CN/agent-teams) 默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)来启用。

293 316 

294<h3 id="permission-modes-in-cloud-sessions">317<h3 id="take-back-a-queued-message">

295 云会话中的权限模式318 取回已排队的消息

296</h3>

297 

298你从[模式下拉菜单](/docs/zh-CN/permission-modes#switch-permission-modes)为云会话选择[权限模式](/docs/zh-CN/permission-modes)，既在你创建任务时，也在会话运行时。当你重新打开其 Anthropic 托管[环境已过期](#environment-expired)的会话，或向自托管运行程序在空闲时[释放的会话](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)发送消息时，Claude Code 在它所在的权限模式中恢复会话。

299 

300<h3 id="review-changes">

301 审查更改

302</h3>319</h3>

303 320 

304每个会话显示一个 diff 指示器，显示添加和删除的行数，如 `+42 -18`。选择它以打开 diff 视图，在特定行上留下内联评论，并使用你的下一条消息将它们发送给 Claude。321如果您在 Claude 工作时发送消息，该消息会排队，直到 Claude 读取它。要取回已排队的消息，请点击消息上的 ✕。文本会返回到消息框，以便您编辑或发送其他内容。

305 

306diff 视图默认将会话的更改与其基础分支进行比较。要与存储库中的任何其他分支进行比较，请选择 **Compare against** 并选择一个分支。

307 

308Claude Code 从原始 git blob 内容计算这些 diffs，包括 Claude 编辑时显示的每个文件 diffs，所以存储库中配置的 diff 驱动程序和 `textconv` 过滤器不适用。对于不是会话自己的检出之一的存储库中的文件，如在会话期间克隆到工作区内的文件，每个文件 diff 显示 Claude 的编辑本身，而不是 git 比较。

309 322 

310有关完整演练（包括 PR 创建），请参阅[审查和迭代](/docs/zh-CN/web-quickstart#review-and-iterate)。要让 Claude 自动监控 PR 以查找 CI 失败和审查评论，请参阅[自动修复拉取请求](#auto-fix-pull-requests)。323如果 Claude 已经读取了该消息，它会保留在对话中。

311 324 

312<h3 id="share-sessions">325<h3 id="share-sessions">

313 共享会话326 共享会话

319 从 Enterprise 或 Team 账户共享332 从 Enterprise 或 Team 账户共享

320</h4>333</h4>

321 334 

322对于 Enterprise 和 Team 账户，两个可见性选项是**私有**和**团队**。团队可见性使会话对你的 claude.ai 组织的其他成员可见。[Claude in Slack](/docs/zh-CN/slack) 会话会自动以团队可见性共享。335Enterprise 和 Team 账户的共享方式如下：

323 336 

324默认情况下启用存储库访问验证，基于连接到收件人账户的 GitHub 账户。你的账户显示名称对所有有访问权限的收件人可见。337* **可见性选项**：**私有**和**团队**。团队可见性使会话对您的 claude.ai 组织中的其他成员可见

338* **仓库访问权限**：默认启用验证，基于收件人账户所连接的 GitHub 账户

339* **您的名称**：您账户的显示名称对所有有访问权限的收件人可见

340* **Slack 会话**：[Claude in Slack](/docs/zh-CN/slack) 会话会自动以团队可见性共享

325 341 

326<h4 id="share-from-a-max-or-pro-account">342<h4 id="share-from-a-max-or-pro-account">

327 从 Max 或 Pro 账户共享343 从 Max 或 Pro 账户共享

328</h4>344</h4>

329 345 

330对于 Max 和 Pro 账户，两个可见性选项是**私有**和**公开**。公开可见性使会话对任何登录到 claude.ai 的用户可见。346Max 和 Pro 账户的共享方式如下：

331 347 

332在共享之前检查你的会话是否包含敏感内容。会话可能包含来自私有 GitHub 存储库的代码和凭证。默认情况下不启用存储库访问验证。348* **可见性选项**：**私有**和**公开**。公开可见性使会话对任何登录 claude.ai 的用户可见

349* **仓库访问权限**：默认不启用验证

350* **敏感内容**：共享前请检查您的会话。会话可能包含来自私有 GitHub 仓库的代码和凭据

333 351 

334要要求收件人拥有存储库访问权限，或从共享会话中隐藏你的名称，请转到 [**Settings > Claude Code > Sharing settings**](https://claude.ai/settings/claude-code)。352要要求收件人拥有存储库访问权限，或从共享会话中隐藏你的名称，请转到 [**Settings > Claude Code > Sharing settings**](https://claude.ai/settings/claude-code)。

335 353 

421 无法获取组织 UUID439 无法获取组织 UUID

422</h3>440</h3>

423 441 

424`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 账户登录。如果你使用 API 密钥进行身份验证，或你的存储账户详情已过期，这些命令会失败，显示 `Unable to get organization UUID` 或消息 API 密钥身份验证不足。使用 API 密钥身份验证或过期账户详情，运行不带会话 ID 的 `claude --teleport` 会在会话选择器中显示 `Error loading Claude Code sessions`，而不是任一消息，相同的修复适用。442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 账户登录。如果您使用 API 密钥进行身份验证，或者存储的账户详情已过期，您会看到以下情况之一：

425 443 

426运行 `/login` 以使用你的 claude.ai 账户登录，然后重试命令。如果错误命名你的提供商，请参阅[错误表](#output-and-errors)：云会话不通过第三方提供商可用。444* `Unable to get organization UUID`

445* 提示 API 密钥身份验证不足的消息

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

447 

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

427 449 

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

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

435* 确认你已登录到拥有会话的相同账户457* 确认你已登录到拥有会话的相同账户

436* 如果你看到 `Remote Control may not be available for this organization`，所有者尚未为你的组织启用云会话458* 如果你看到 `Remote Control may not be available for this organization`，所有者尚未为你的组织启用云会话

437 459 

460<h3 id="errors-when-sending-to-a-cloud-session">

461 向云端会话发送消息时的错误

462</h3>

463 

464这些错误来自使用 [`--cloud <session-id>`](#send-follow-ups-from-the-cli) 运行 `claude`，无论是否带有 `-p`。CLI 会在错误前加上 `Error: ` 前缀。发送失败时会包装为 `failed to send message to cloud session <id>: <reason>`。

465 

466| 消息 | 含义 |

467| - | - |

468| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code 配置为使用第三方提供商。消息会使用您的配置中的标签显示提供商名称，例如 `Amazon Bedrock` 或 `Google Vertex AI`。请移除该提供商的配置（例如取消设置 `CLAUDE_CODE_USE_BEDROCK`），并使用 Anthropic 账户登录（`claude auth login`）。 |

469| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 组织策略已关闭。 |

470| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code 无法获取您组织的策略，因此拒绝发送，而不是假定云端会话已被允许。请检查网络连接并重试。 |

471| `Attaching to an existing cloud session is not enabled for your account.` | 您在运行 `--cloud <session-id>` 时未带 `-p`。请使用 `claude -p "your message" --cloud <session-id>` 发送消息。 |

472| `Session not found: <id>` | 该 ID 或 URL 与您可以访问的任何会话都不匹配。请对照该会话的 claude.ai/code URL 进行检查。 |

473| `cloud session <id> is archived and cannot accept new messages` | 该会话已归档。请改为启动一个新会话。 |

474 

438<h3 id="environment-expired">475<h3 id="environment-expired">

439 环境已过期476 环境已过期

440</h3>477</h3>

441 478 

442云会话在不活动一段时间后停止，会话的 VM 被回收。会话在等待你批准 [MCP 连接器](/docs/zh-CN/cloud-environments#network-access)工具调用或登录到 MCP 服务器时计为不活动，它可以在该等待期间过期。479云会话在不活动一段时间后停止，会话的 VM 被回收。会话在等待你批准 [MCP 连接器](/docs/zh-CN/cloud-environments#network-access)工具调用或登录到 MCP 服务器时计为不活动，它可以在该等待期间过期。

443 480 

444从 [claude.ai/code](https://claude.ai/code) 重新打开会话以配置新 VM，并恢复你的对话历史。在 VM 被回收时仍在运行的后台工作，如 subagents 和 shell 命令，不会被恢复。481从 [claude.ai/code](https://claude.ai/code) 重新打开会话以预配新的 VM：

482 

483* **会恢复**：您的对话历史

484* **不会恢复**：VM 被回收时仍在运行的后台工作，例如子代理和 shell 命令

445 485 

446<h2 id="limitations">486<h2 id="limitations">

447 限制487 限制

497 oneLiner: 'Custom keyboard shortcuts',497 oneLiner: 'Custom keyboard shortcuts',

498 when: 'Read at session start and hot-reloaded when you edit the file',498 when: 'Read at session start and hot-reloaded when you edit the file',

499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,

500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+U</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+S</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,

501 example: `{501 example: `{

502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

503 "$docs": "https://code.claude.com/docs/en/keybindings",503 "$docs": "https://code.claude.com/docs/en/keybindings",

506 "context": "Chat",506 "context": "Chat",

507 "bindings": {507 "bindings": {

508 "ctrl+e": "chat:externalEditor",508 "ctrl+e": "chat:externalEditor",

509 "ctrl+u": null509 "ctrl+s": null

510 }510 }

511 }511 }

512 ]512 ]

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

1456| `CLAUDE.local.md` | 项目根目录 | 您对此项目的私人偏好，与 CLAUDE.md 一起加载。手动创建它并将其添加到 `.gitignore`。 |1456| `CLAUDE.local.md` | 项目根目录 | 您对此项目的私人偏好，与 CLAUDE.md 一起加载。手动创建它并将其添加到 `.gitignore`。 |

1457| `AGENTS.md` | 项目根目录、`.claude/` 或任何目录 | 您为 AI 编码代理编写的项目说明。Claude Code 可以[自行加载它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起加载。 |1457| `AGENTS.md` | 项目根目录、`.claude/` 或任何目录 | 您为 AI 编码代理编写的项目说明。Claude Code 可以[自行加载它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起加载。 |

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

1459 1459 

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

1461 1461 

26 26 

27* **CLI 流程（例如 `/web-setup`）**：为您创建 **Default**27* **CLI 流程（例如 `/web-setup`）**：为您创建 **Default**

28* **Pro 和 Max 上的网页引导**：为您创建 **Default**28* **Pro 和 Max 上的网页引导**：为您创建 **Default**

29* **Team 和 Enterprise 上的网页引导**：显示 **Create your first cloud environment** 表单，除非所有者已启用[快速网页设置](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)；保持表单的默认值并点击 **Create & finish** 以获得相同的 **Default** 环境29* **Team 和 Enterprise 上的网页引导**：显示 **Create your first cloud environment** 表单，除非所有者已启用[快速设置](/docs/zh-CN/claude-code-on-the-web#quick-setup-for-team-and-enterprise)；保持表单的默认值并点击 **Create & finish** 以获得相同的 **Default** 环境

30 30 

31**Default** 本身不带有任何配置：31**Default** 本身不带有任何配置：

32 32 

111| 您的角色 | `/usage-credits` 的作用 |111| 您的角色 | `/usage-credits` 的作用 |

112| :- | :- |112| :- | :- |

113| Pro 或 Max 订阅者 | 在浏览器中打开 claude.ai 上的 [**Settings > Usage**](https://claude.ai/settings/usage)。在其 **Usage credits** 部分中，您可以打开或关闭使用额度，并检查您的额度余额、本月支出和每月支出限制 |113| Pro 或 Max 订阅者 | 在浏览器中打开 claude.ai 上的 [**Settings > Usage**](https://claude.ai/settings/usage)。在其 **Usage credits** 部分中，您可以打开或关闭使用额度，并检查您的额度余额、本月支出和每月支出限制 |

114| 具有计费访问权限的 Team 或 Enterprise 成员 | 在浏览器中打开您的组织的使用情况设置 [**Admin settings > Usage**](https://claude.ai/admin-settings/usage) |114| 具有计费访问权限的 Team 或 Enterprise 成员 | 在浏览器中打开您组织的用量设置 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) |

115| 没有计费访问权限的 Team 或 Enterprise 成员 | 要求您确认，然后向您的组织管理员发送请求。在 v2.1.211 之前，Claude Code 在没有确认步骤的情况下发送请求 |115| 没有计费访问权限的 Team 或 Enterprise 成员 | 要求您确认，然后向您的组织管理员发送请求。在 v2.1.211 之前，Claude Code 在没有确认步骤的情况下发送请求 |

116 116 

117对于没有计费访问权限的 Team 和 Enterprise 成员，确认仅在交互式会话中出现：在使用 `-p` 标志的非交互式模式和从[远程控制](/docs/zh-CN/remote-control)中，该命令不发送请求，并告诉您在交互式会话中运行它。117对于没有计费访问权限的 Team 和 Enterprise 成员，确认仅在交互式会话中出现：在使用 `-p` 标志的非交互式模式和从[远程控制](/docs/zh-CN/remote-control)中，该命令不发送请求，并告诉您在交互式会话中运行它。

229* **"您已达到会话限制"或"您已达到每周限制"**：订阅计划上基于座位的使用窗口，在所有模型中共享，因此开发者无法通过使用 `/model` 切换模型来恢复访问权限。该消息显示窗口何时重置。在模型特定的"您已达到 Opus 限制"或"您已达到 Sonnet 限制"消息之后，使用 `/model` 切换到该系列之外的模型确实会让开发者继续工作。请参阅[使用限制错误](/docs/zh-CN/errors#youve-hit-your-session-limit)。开发者在此期间可以做什么：229* **"您已达到会话限制"或"您已达到每周限制"**：订阅计划上基于座位的使用窗口，在所有模型中共享，因此开发者无法通过使用 `/model` 切换模型来恢复访问权限。该消息显示窗口何时重置。在模型特定的"您已达到 Opus 限制"或"您已达到 Sonnet 限制"消息之后，使用 `/model` 切换到该系列之外的模型确实会让开发者继续工作。请参阅[使用限制错误](/docs/zh-CN/errors#youve-hit-your-session-limit)。开发者在此期间可以做什么：

230 * 运行 `/usage-credits` 以请求超过额度的使用情况，如果您已启用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。230 * 运行 `/usage-credits` 以请求超过额度的使用情况，如果您已启用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

231 * 在 Claude Code v2.1.234 或更高版本上，[在重置后自动等待并继续中断的任务](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)；该部分列出了 Claude Code 何时自动启动等待以及开发者何时从 `/rate-limit-options` 中选择它。要控制您的车队 Claude Code 是否自动启动该等待，请在[托管设置](/docs/zh-CN/settings#settings-precedence)中设置 [`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit)。231 * 在 Claude Code v2.1.234 或更高版本上，[在重置后自动等待并继续中断的任务](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)；该部分列出了 Claude Code 何时自动启动等待以及开发者何时从 `/rate-limit-options` 中选择它。要控制您的车队 Claude Code 是否自动启动该等待，请在[托管设置](/docs/zh-CN/settings#settings-precedence)中设置 [`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit)。

232* **"您已达到个人支出限制"、"组织的月度支出限制"或"团队的共享预算"**：开发者的请求将被计费到使用额度，这些额度已达到您设置的支出限制。要让开发者继续，请转到[**管理员设置 > 使用**](https://claude.ai/admin-settings/usage)并增加消息命名的限制。当消息还命名计划重置时间时，开发者可以改为等待直到那时。请参阅[错误参考](/docs/zh-CN/errors#youve-hit-your-monthly-spend-limit)了解每个变体。232* **"You've hit your individual spend limit"、"org's monthly spend limit"或"team's shared budget"**：开发者的请求本应计费到使用额度，而这些额度已达到您设置的支出限制。要让开发者继续，请前往 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) 并提高消息中指出的限制。如果消息中还指出了套餐重置时间，开发者也可以等到那时。请参阅[错误参考](/docs/zh-CN/errors#youve-hit-your-monthly-spend-limit)了解各个变体。

233* **来自 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 的支出限制消息**：开发者超过了您在自托管网关上设置的支出上限，网关会阻止他们的请求，直到该期间重置或您提高上限。请参阅[网关支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)以了解上限、重置计划和开发者看到的消息。233* **来自 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 的支出限制消息**：开发者超过了您在自托管网关上设置的支出上限，网关会阻止他们的请求，直到该期间重置或您提高上限。请参阅[网关支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)以了解上限、重置计划和开发者看到的消息。

234* **上下文或自动压缩警告**：不是使用限制。对话已接近会话的[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，这是 Claude Code 总结较早历史以释放空间的阈值。将开发者指向[减少令牌使用](#reduce-token-usage)。234* **上下文或自动压缩警告**：不是使用限制。对话已接近会话的[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，这是 Claude Code 总结较早历史以释放空间的阈值。将开发者指向[减少令牌使用](#reduce-token-usage)。

235* **API 或云提供商计划上的意外高支出**：通常可以追溯到从未清除的长会话或将 Opus 作为默认模型。要分享的最高影响习惯是在不相关的任务之间清除和将模型与工作相匹配，两者都在[减少令牌使用](#reduce-token-usage)中涵盖。235* **API 或云提供商计划上的意外高支出**：通常可以追溯到从未清除的长会话或将 Opus 作为默认模型。要分享的最高影响习惯是在不相关的任务之间清除和将模型与工作相匹配，两者都在[减少令牌使用](#reduce-token-usage)中涵盖。

192以下任一方式都会向您显示完整文本：192以下任一方式都会向您显示完整文本：

193 193 

194* 按 `Ctrl+O` 打开[会话记录查看器](/docs/zh-CN/interactive-mode#transcript-viewer)，并在发送者的会话名称下阅读完整文本。194* 按 `Ctrl+O` 打开[会话记录查看器](/docs/zh-CN/interactive-mode#transcript-viewer)，并在发送者的会话名称下阅读完整文本。

195* 在[全屏渲染](/docs/zh-CN/fullscreen#use-the-mouse)中，点击未完整显示消息的预览行，即可将其就地展开。

195* 在使用 [`--verbose`](/docs/zh-CN/cli-reference#cli-flags) 启动的会话中，Claude Code 会显示完整文本而不是预览。196* 在使用 [`--verbose`](/docs/zh-CN/cli-reference#cli-flags) 启动的会话中，Claude Code 会显示完整文本而不是预览。

196 197 

197预览仅缩短您看到的内容。无论您是否展开它，Claude 都会读取完整消息。198预览仅缩短您看到的内容。无论您是否展开它，Claude 都会读取完整消息。

244 切换视图模式244 切换视图模式

245</h3>245</h3>

246 246 

247视图模式控制聊天记录中显示多少详细信息。从发送按钮旁的 **Transcript view** 下拉菜单切换模式，或在 macOS 或 Windows 上按 **Ctrl+O** 来循环浏览它们。Thinking 模式仅在 Claude 在你正在查看的会话中产生思考后才出现在下拉菜单中。247视图模式控制聊天会话记录中显示的详细程度。要切换视图模式，请从会话标题旁的插入符号打开会话菜单并选择 **Transcript view**，或在 macOS 或 Windows 上按 **Ctrl+O** 循环切换。只有在 Claude 于您正在查看的会话中产生思考后，Thinking 模式才会出现在菜单中。

248 248 

249| 模式 | 显示内容 |249| 模式 | 显示内容 |

250| - | - |250| - | - |

372 管理会话372 管理会话

373</h2>373</h2>

374 374 

375每个会话是一个独立的对话，拥有自己的上下文和更改。你可以并行运行多个会话、分支侧边聊天、让 Claude 检查并向你的其他会话发送消息、将工作发送到云，或让 Dispatch 从你的手机为你启动会话。375每个会话是一个独立的对话，拥有自己的上下文和更改。您可以并行运行多个会话、开启侧边聊天、让 Claude 查看您的其他会话并向其发送消息、将工作发送到云端，或让 Dispatch 从您的手机为您启动会话。

376 376 

377<h3 id="work-in-parallel-with-sessions">377<h3 id="work-in-parallel-with-sessions">

378 使用会话并行工作378 使用会话并行工作

379</h3>379</h3>

380 380 

381点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，来并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 来循环侧边栏中的会话。对于 Git 存储库，选择分支名称旁边的 **worktree** 选项，为会话提供使用 [Git worktrees](/docs/zh-CN/worktrees) 的项目隔离副本，因此一个会话中的更改不会影响其他会话，直到你提交它们。381点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N**、在 Windows 上按 **Ctrl+N**，即可并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 可在侧边栏中循环切换会话。对于 Git 仓库，选择分支名称旁边的 **worktree** 选项，即可使用 [Git worktrees](/docs/zh-CN/worktrees) 为会话提供项目的独立隔离副本，这样一个会话中的更改在您提交之前不会影响其他会话。

382 382 

383要同时查看两个会话，在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。会话在第二个窗格中打开，与你已经打开的窗格并排。当分割处于活跃状态时，点击另一个侧边栏会话会替换具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格并返回到单个会话。383要同时查看两个会话，请在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。该会话会在第二个窗格中打开，与您已打开的会话并排显示。分屏处于活跃状态时，点击侧边栏中的另一个会话会替换当前具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 可关闭具有焦点的窗格并返回单个会话。

384 384 

385Worktrees 默认存储在 `<project-root>/.claude/worktrees/` 中。你可以在设置 → Claude Code 中的"Worktree location"下将其更改为自定义目录。你也可以设置一个分支前缀，该前缀会添加到每个 worktree 分支名称前面，这对于保持 Claude 创建的分支有组织很有用。要在完成后删除 worktree，请将鼠标悬停在侧边栏中的会话上并点击存档图标。要在 PR 合并或关闭时让会话自动存档，在设置 → Claude Code 中打开 **Auto-archive after PR merge or close**。自动存档仅适用于已完成运行的本地会话。385Worktree 默认存储在 `<project-root>/.claude/worktrees/` 中。您可以在设置 → Claude Code 中的"Worktree location"下将其更改为自定义目录。您还可以设置一个分支前缀，该前缀会添加到每个 worktree 分支名称的前面，这有助于让 Claude 创建的分支保持条理。完成后要删除 worktree，请将鼠标悬停在侧边栏中的会话上并点击存档图标。要让会话在其 Pull Request 合并或关闭时自动存档，请在设置 → Claude Code 中打开 **Auto-archive after PR merge or close**。自动存档仅适用于已完成运行的本地会话。

386 386 

387要在新 worktrees 中包含 gitignored 文件（如 `.env`），在你的项目根目录中创建一个 [`.worktreeinclude` 文件](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。387要在新 worktree 中包含被 gitignore 的文件（如 `.env`），请在项目根目录中创建一个 [`.worktreeinclude` 文件](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。

388 388 

389<Note>389<Note>

390 会话隔离需要 [Git](https://git-scm.com/downloads)。大多数 Mac 默认包含 Git。在终端中运行 `git --version` 来检查；如果它打印版本号，则 Git 已安装。如果你遇到 Git 错误，请在 [Cowork 选项卡](https://claude.com/product/cowork) 中询问 Claude 来帮助排除你的设置。390 会话隔离需要 [Git](https://git-scm.com/downloads)。大多数 Mac 默认已包含 Git。在终端中运行 `git --version` 进行检查；如果输出了版本号，则说明 Git 已安装。如果遇到 Git 错误，请在 [Cowork 选项卡](https://claude.com/product/cowork)中请 Claude 帮助排查您的设置。

391</Note>391</Note>

392 392 

393使用侧边栏顶部的控制来按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活跃会话顶部工具栏中的会话标题。393使用侧边栏顶部的控件可按状态、项目或环境筛选会话，并按项目对会话分组。要重命名会话，请点击活跃会话顶部工具栏中的会话标题。

394 394 

395要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 自动总结对话并继续工作。你也可以输入 `/compact` 来更早触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/docs/zh-CN/how-claude-code-works#the-context-window)。395要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 会自动总结对话并继续工作。您也可以输入 `/compact` 提前触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/docs/zh-CN/how-claude-code-works#the-context-window)。

396 396 

397桌面应用在 Code 会话完成任务且你当前未查看该会话时发送操作系统通知。对于属于[项目](/docs/zh-CN/claude-projects#see-what-needs-you-in-overview)的会话，你会获得项目的通知。397当 Code 会话完成任务且您当前未在查看该会话时，桌面应用会发送操作系统通知。对于属于某个[项目](/docs/zh-CN/claude-projects#see-what-needs-you-in-overview)的会话，您将收到该项目的通知。

398 398 

399<h3 id="ask-a-side-question-without-derailing-the-session">399<h3 id="ask-a-side-question-without-derailing-the-session">

400 在不偏离会话的情况下提出侧边问题400 在不偏离会话的情况下提出侧边问题

401</h3>401</h3>

402 402 

403侧边聊天让你提出一个使用你的会话上下文的问题，但不会添加任何内容回到主对话。当你想要理解一段代码、检查一个假设或探索一个想法而不引导会话偏离时，使用它。403侧边聊天让您可以向 Claude 提出一个使用会话上下文的问题，但不会向主对话添加任何内容。当您想要理解一段代码、检查某个假设或探索某个想法，又不想让会话偏离方向时，可以使用它。

404 404 

405在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 来打开侧边聊天，或在提示框中输入 `/btw`。侧边聊天可以读取主线程中到该点为止的所有内容。完成后，关闭侧边聊天并在你离开的地方继续主会话。405在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 打开侧边聊天，或在输入框中输入 `/btw`。侧边聊天可以读取主线程中截至该时刻的所有内容。完成后，关闭侧边聊天，即可从中断处继续主会话。

406 406 

407侧边聊天在本地、SSH 和 WSL 会话中可用。桌面应用不会将侧边聊天保存到磁盘，因此你在关闭应用后无法返回到一个。407侧边聊天可在本地、SSH 和 WSL 会话中使用。桌面应用不会将侧边聊天保存到磁盘，因此关闭应用后无法再返回之前的侧边聊天。

408 408 

409<h3 id="watch-background-tasks">409<h3 id="watch-background-tasks">

410 观看后台任务410 查看后台任务

411</h3>411</h3>

412 412 

413任务窗格显示在当前会话内运行的后台工作：子代理、后台 shell 命令和[动态工作流](/docs/zh-CN/workflows)。从 **Views** 菜单打开它或将其拖入你的布局。413任务窗格显示当前会话内正在运行的后台工作：子代理、后台 shell 命令和[动态工作流](/docs/zh-CN/workflows)。可从 **Views** 菜单打开它，或将其拖入您的布局。

414 414 

415点击任何条目来在子代理窗格中查看其输出或停止它。要查看其他会话在做什么，使用[侧边栏](#work-in-parallel-with-sessions)，或要求 Claude [为你检查它们](#work-across-sessions)。415点击任意条目可在子代理窗格中查看其输出或将其停止。要查看其他会话正在做什么，请使用[侧边栏](#work-in-parallel-with-sessions)，或请 Claude [为您查看](#work-across-sessions)。

416 416 

417<h3 id="work-across-sessions">417<h3 id="work-across-sessions">

418 跨会话工作418 跨会话工作

419</h3>419</h3>

420 420 

421Claude 可以列出你的其他 Code 选项卡会话，读取每个会话一直在做什么，并在它们之间发送消息。用简单的语言提问："哪个会话涉及了身份验证重构？"、"API 会话得出了什么结论？"或"告诉支付会话模式已更改"。你也可以要求 Claude 重命名或存档会话。Claude 存档会话的方式与侧边栏的存档图标相同，因此要求它清理 PR 已合并的会话。421Claude 可以列出您的其他 Code 选项卡会话，读取每个会话一直在做的工作，并在它们之间发送消息。用自然语言提问即可："哪个会话涉及了身份验证重构？"、"API 会话得出了什么结论？"或"告诉支付会话 schema 已更改"。您也可以请 Claude 重命名或存档会话。Claude 存档会话的方式与侧边栏的存档图标相同，因此可以让它清理 PR 已合并的会话。

422 422 

423通过这个界面，Claude 只看到桌面应用本身运行的会话：本地、[SSH](#ssh-sessions) 和 [WSL](/docs/zh-CN/desktop-wsl) 会话在 Code 选项卡中。Claude 看不到云会话，或你从终端 CLI 或 VS Code 扩展启动的会话，即使在同一项目的 worktrees 中，所以有九个终端 worktrees 打开和两个桌面会话，Claude 在其中一个回答时报告另一个桌面会话。Claude 永远不会列出你提问的会话。默认情况下，它看到 20 个最近活跃的会话，并跳过存档的会话，除非你要求它们。[跨会话消息传递](/docs/zh-CN/cross-session-messaging) 单独让 Claude 向[你的其他 Claude Code 会话](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)发送消息，包括终端会话。423通过此使用入口，Claude 只能看到桌面应用自身运行的会话：Code 选项卡中的本地、[SSH](#ssh-sessions) 和 [WSL](/docs/zh-CN/desktop-wsl) 会话。Claude 看不到云端会话，也看不到您从终端 CLI 或 VS Code 扩展启动的会话，即使它们位于同一项目的 worktree 中也是如此。因此，如果打开了九个终端 worktree 和两个桌面会话，在其中一个桌面会话中回答的 Claude 只会报告另一个桌面会话。Claude 从不会列出您正在提问的那个会话。默认情况下，它可以看到最近活跃的 20 个会话，并跳过已存档的会话，除非您明确要求。[跨会话消息传递](/docs/zh-CN/cross-session-messaging)则另外让 Claude 可以向[您的其他 Claude Code 会话](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)发送消息，包括终端会话。

424 424 

425当 Claude 通过这个界面向另一个会话发送消息时，Claude Code 在那里将其显示为一张卡片，标记有发送会话的标题和返回链接，因此你总是可以看到消息来自哪里。如果接收会话正在执行任务中，Claude Code 会保留消息，Claude 在当前工作完成后读取它。接收的 Claude 可以回复，Claude Code 通过这个界面将回复传递回去。Claude 无法传递到存档的会话，并在消息未通过时告诉你。425当 Claude 通过此使用入口向另一个会话发送消息时，Claude Code 会在对方会话中将其显示为一张卡片，卡片标有发送会话的标题和返回链接，因此您始终可以知道消息来自何处。如果接收会话正在执行任务，Claude Code 会暂存该消息，Claude 会在当前工作完成后读取它。接收方的 Claude 可以回复，Claude Code 会通过此使用入口将回复传回。Claude 无法向已存档的会话发送消息，并会在消息未送达时告知您。

426 426 

427Claude Code 在会话间应用四个安全行为：427Claude Code 在跨会话时应用四项安全行为：

428 428 

429* 在存档任何会话之前，Claude 首先询问你。你在每个权限模式中看到批准卡片，包括自动和绕过权限。429* 在存档任何会话之前，Claude 会先询问您。在每种权限模式下您都会看到批准卡片，包括 Auto 和 Bypass permissions。

430* 通过这个界面，Claude 无法从没有人观看的会话（例如计划任务运行）发送跨会话消息，也无法将消息传递到一个。430* 通过此使用入口，Claude 无法从无人查看的会话（例如定时任务运行）发送跨会话消息，也无法向此类会话发送消息。

431* Claude Code 根据接收会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)检查来自这个界面的每条消息，即使接收会话本身没有[跨会话消息传递](/docs/zh-CN/cross-session-messaging#availability)。如果你在接收会话中将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 `refuse`，Claude Code 会丢弃来自这个界面的消息。Claude Code 向 Claude 桌面应用报告拒绝。在 v2.1.234 之前，Claude Code 丢弃来自这个界面到没有跨会话消息传递的接收会话的每条消息。431* Claude Code 会根据接收会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)检查来自此使用入口的每条消息，即使接收会话本身未启用[跨会话消息传递](/docs/zh-CN/cross-session-messaging#availability)。如果您在接收会话中将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 `refuse`，Claude Code 会丢弃来自此使用入口的消息。Claude Code 会向 Claude 桌面应用报告该拒绝。在 v2.1.234 之前，对于未启用跨会话消息传递的接收会话，Claude Code 会丢弃来自此使用入口的所有消息。

432* Claude Code 引用每条传入消息并将其归属于发送它的会话，Claude 在对其进行操作时仍然遵循接收会话自己的权限设置。432* Claude Code 会引用每条传入消息并注明其来自哪个发送会话，且 Claude 在据此执行操作时仍遵循接收会话自身的权限设置。

433 433 

434Claude 也可以建议新会话。当它注意到值得修复但超出当前任务范围的东西时，它在聊天中将工作作为任务芯片提供。点击芯片来在具有自己 worktree 的新会话中启动该工作；Claude 继续你的当前会话而不中断。434Claude 还可以建议新会话。当它注意到值得修复但超出当前任务范围的问题时，会在聊天中以任务标签的形式提供该工作。点击该标签即可在拥有独立 worktree 的新会话中开始该工作；Claude 会继续您的当前会话而不受干扰。

435 435 

436<h3 id="run-long-running-tasks-in-the-cloud">436<h3 id="run-long-running-tasks-in-the-cloud">

437 在云中运行长时间运行的任务437 在云端运行长时间运行的任务

438</h3>438</h3>

439 439 

440对于大型重构、测试套件、迁移或其他长时间运行的任务，在启动会话时选择 **Cloud** 而不是 **Local**。云会话默认在 Anthropic 管理的基础设施上运行，即使你关闭应用或关闭计算机，也会继续运行。随时检查进度或引导 Claude 朝不同方向发展。你也可以从 [claude.ai/code](https://claude.ai/code) 或 [Claude 移动应用](/docs/zh-CN/mobile)监控云会话。440对于大型重构、测试套件、迁移或其他长时间运行的任务，请在启动会话时选择 **Cloud** 而不是 **Local**。云端会话默认在 Anthropic 管理的基础设施上运行，即使您关闭应用或关闭计算机也会继续运行。您可以随时回来查看进度，或引导 Claude 转向不同的方向。您也可以从 [claude.ai/code](https://claude.ai/code) 或 [Claude 移动应用](/docs/zh-CN/mobile)监控云端会话。

441 441 

442云会话也支持多个存储库。选择云环境后，点击所选存储库旁边的 **+** 按钮向会话添加更多存储库。每个存储库都有自己的分支选择器。这对于跨越多个代码库的任务很有用，例如更新共享库及其使用者。442云端会话还支持多个仓库。选择云端环境后，点击所选仓库旁边的 **+** 按钮即可向会话添加更多仓库。每个仓库都有自己的分支选择器。这对于跨越多个代码库的任务很有用，例如更新共享库及其使用方。

443 443 

444有关云会话如何工作的更多信息，请参阅 [Web 上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)。当一项工作需要许多云会话时，在侧边栏中选择 **Projects** 来创建一个[项目](/docs/zh-CN/claude-projects)，Claude 从一个对话中为你启动和跟踪会话。444有关云端会话工作方式的更多信息，请参阅[在云端使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)。当一项工作需要许多云端会话时，请在侧边栏中选择 **Projects** 创建一个[项目](/docs/zh-CN/claude-projects)，Claude 会在一个对话中为您启动并跟踪这些会话。

445 445 

446<h3 id="continue-in-another-surface">446<h3 id="continue-in-another-surface">

447 在另一个表面继续447 在另一个使用入口继续

448</h3>448</h3>

449 449 

450**Continue in** 菜单，可从会话工具栏右下角的 VS Code 图标访问，让你将会话移动到另一个表面：450要在其他地方继续会话，请通过会话标题旁边的下拉箭头或侧边栏中该会话所在的行打开会话菜单，然后选择 **Open in**：

451 451 

452* **Web 上的 Claude Code**：将你的本地会话发送到云中继续运行。Desktop 推送你的分支，生成对话摘要，并创建具有完整上下文的新云会话。你可以然后选择存档本地会话或保留它。这需要干净的工作树，对于 SSH 会话不可用。452* 选择 **Cloud** 可将会话作为[云端会话](/docs/zh-CN/claude-code-on-the-web)继续，您的对话会以摘要形式带过去。在您确认之前，对话框会说明您的文件是否也会一并移动，以及云端会话就绪后此会话是否会被存档。通过 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-CN/desktop-wsl) 中运行的会话无法以这种方式移动。

453* **你的 IDE**：在当前工作目录的支持的 IDE 中打开你的项目。453* 选择已安装的编辑器或文件管理器，可在其中打开该会话在磁盘上的文件夹。

454 454 

455<h3 id="sessions-from-dispatch">455<h3 id="sessions-from-dispatch">

456 来自 Dispatch 的会话456 来自 Dispatch 的会话

457</h3>457</h3>

458 458 

459[Dispatch](https://support.claude.com/en/articles/13947068) 是一个与 Claude 的持久对话，存在于 [Cowork](https://claude.com/product/cowork) 选项卡中。你向 Dispatch 发送任务消息，它决定如何处理。459[Dispatch](https://support.claude.com/en/articles/13947068) 是一个与 Claude 的持久对话，位于 [Cowork](https://claude.com/product/cowork) 选项卡中。您向 Dispatch 发送任务消息，由它决定如何处理。

460 460 

461任务可以通过两种方式成为 Code 会话：你直接要求一个，例如"打开 Claude Code 会话并修复登录错误"，或 Dispatch 决定任务是开发工作并自己生成一个。通常路由到 Code 的任务包括修复错误、更新依赖项、运行测试或打开拉取请求。研究、文档编辑和电子表格工作保留在 Cowork 中。461任务可以通过两种方式成为 Code 会话：您直接提出要求，例如"打开一个 Claude Code 会话并修复登录错误"；或者 Dispatch 判断该任务属于开发工作，并自行创建一个会话。通常会路由到 Code 的任务包括修复错误、更新依赖、运行测试或创建 Pull Request。研究、文档编辑和电子表格工作则保留在 Cowork 中。

462 462 

463无论哪种方式，Code 会话都会在 Code 选项卡的侧边栏中出现，带有 **Dispatch** 徽章。当它完成或需要你的批准时，你会在手机上收到推送通知。463无论哪种方式，Code 会话都会出现在 Code 选项卡的侧边栏中，并带有 **Dispatch** 徽章。当它完成或需要您批准时，您会在手机上收到推送通知。

464 464 

465如果你启用了[计算机使用](#let-claude-use-your-computer)，Dispatch 生成的 Code 会话也可以使用它。这些会话中的应用批准在 30 分钟后过期并重新提示，而不是像常规 Code 会话那样持续整个会话。465如果您启用了[计算机使用](#let-claude-use-your-computer)，由 Dispatch 创建的 Code 会话也可以使用它。这些会话中的应用批准会在 30 分钟后过期并重新提示，而不是像常规 Code 会话那样在整个会话期间有效。

466 466 

467有关设置、配对和 Dispatch 设置，请参阅 [Dispatch 帮助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 计划，在 Team 或 Enterprise 计划上不可用。467有关设置、配对和 Dispatch 设置，请参阅 [Dispatch 帮助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 计划，Team 或 Enterprise 计划不可用。

468 468 

469Dispatch 是远离终端时与 Claude 合作的几种方式之一。有关与其他选项的比较，请参阅[平台和集成](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)。469Dispatch 是您离开终端时与 Claude 协作的几种方式之一。有关与其他选项的比较，请参阅[平台和集成](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)。

470 470 

471<h2 id="extend-claude-code">471<h2 id="extend-claude-code">

472 扩展 Claude Code472 扩展 Claude Code

739 739 

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

741 741 

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

743 743 

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

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

1005| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |1005| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |

1006| `--add-dir` | 在云会话中使用 **+** 按钮添加多个存储库 |1006| `--add-dir` | 在云会话中使用 **+** 按钮添加多个存储库 |

1007| `--allowedTools`, `--disallowedTools` | 无每个会话的等效项。[设置文件](/docs/zh-CN/settings)中的权限规则仍然适用。 |1007| `--allowedTools`, `--disallowedTools` | 无每个会话的等效项。[设置文件](/docs/zh-CN/settings)中的权限规则仍然适用。 |

1008| `--verbose` | [Verbose 视图模式](#switch-view-modes)在 Transcript 视图下拉菜单中 |1008| `--verbose` | [Verbose 视图模式](#switch-view-modes) |

1009| `--print`, `--output-format` | 不可用。Desktop 仅是交互式的。 |1009| `--print`, `--output-format` | 不可用。Desktop 仅是交互式的。 |

1010| `ANTHROPIC_MODEL` 环境变量 | 发送按钮旁的模型下拉菜单 |1010| `ANTHROPIC_MODEL` 环境变量 | 发送按钮旁的模型下拉菜单 |

1011| `MAX_THINKING_TOKENS` 环境变量 | 在本地环境编辑器中设置。请参阅[环境配置](#environment-configuration)。 |1011| `MAX_THINKING_TOKENS` 环境变量 | 在本地环境编辑器中设置。请参阅[环境配置](#environment-configuration)。 |

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

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

94 94 

95设备名称下的行调整来自模拟器的视频流。如果窗格对你的 Mac 造成压力，请降低**Frame rate** 或**Resolution**，在 H.264 和 JPEG 之间切换**Encoding**，或检查**FPS** 以显示窗格接收的帧速率。这些设置改变窗格显示设备的方式，而不是应用运行的方式。95要调整来自模拟器的视频流，请打开窗格的 **Display** 菜单。如果窗格对您的 Mac 造成压力，请降低**Frame rate** 或**Resolution**。这两项设置改变窗格显示设备的方式，而不是应用运行的方式。

96 96 

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

98 98 

135 135 

136**将 Claude 放在日程上。** 设置 [scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。136**将 Claude 放在日程上。** 设置 [scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。

137 137 

138**准备好时扩展。** 从侧边栏打开 [parallel sessions](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [tasks pane](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [side chat](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [long-running work 发送到云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud) 以便即使关闭应用也能继续，或 [在 web 或 IDE 中继续会话](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。138**准备好时扩展。** 从侧边栏打开 [parallel sessions](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [tasks pane](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [side chat](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [long-running work 发送到云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud) 以便即使关闭应用也能继续，或 [将您已开始的会话移至云端](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。

139 139 

140<h2 id="what’s-next">140<h2 id="what’s-next">

141 接下来141 接下来

124 变量124 变量

125</h2>125</h2>

126 126 

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

128 128 

129<Note>129<Note>

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

131 131 

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

133 133 

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140 

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

142</Note>142</Note>

143 143 

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

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

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

147| `ANTHROPIC_AUTH_TOKEN` | `Authorization` 标头的自定义值（您在此处设置的值将以 `Bearer ` 为前缀） |147| `ANTHROPIC_AUTH_TOKEN` | `Authorization` 请求头的自定义值（您在此设置的值将加上前缀 `Bearer `） |

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

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

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 必需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |150| `ANTHROPIC_AWS_WORKSPACE_ID` | 使用 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 时必需。在每个请求中作为 `anthropic-workspace-id` 请求头发送 |

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

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

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

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

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

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

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

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

159| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 选择器中自定义模型条目的显示描述。未设置时默认为 `Custom model (<model-id>)` |159| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 选择器中自定义模型条目的显示描述。未设置时默认为 `Custom model (<model-id>)` |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

184| `ANTHROPIC_MODEL` | 要使用的模型设置的名称（请参阅[模型配置](/docs/zh-CN/model-config#environment-variables)） |184| `ANTHROPIC_MODEL` | 要使用的模型设置名称（请参阅[模型配置](/docs/zh-CN/model-config#environment-variables)） |

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

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

187| `ANTHROPIC_SMALL_FAST_MODEL` | \[已弃用] [用于后台任务的 Haiku 级模型](/docs/zh-CN/costs)的名称 |187| `ANTHROPIC_SMALL_FAST_MODEL` | \[已弃用] [用于后台任务的 Haiku 级模型](/docs/zh-CN/costs)的名称 |

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

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

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

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

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