Documentation 2026-11-12 23:02 UTC to 2026-11-13 02:58 UTC

349 349 

350### 当模型在会话中被禁用时350### 当模型在会话中被禁用时

351 351 

352如果您的账户失去对会话正在运行的模型的访问权限，例如因为管理员在您的 Amazon Bedrock 账户中禁用了它，Claude Code 会将会话切换到另一个模型，而不是使每个请求都失败，并显示 `Switched to <fallback> because <model> is not available`。它尝试与启动回退相同的模型：首先尝试同一层级的早期版本，对于没有可用 Opus 版本的 Opus 会话，则使用默认 Sonnet 模型。352当 Amazon Bedrock 以您的账户无法使用为由拒绝您会话的模型时，Claude Code 会将您的会话切换到另一个模型，您可以继续工作。您会看到一条以 `Switched to <fallback> because <model> is not available` 开头的消息。例如，当管理员禁用该模型，或者最新模型尚未对您的账户开放时，就会发生这种情况。

353 353 

354切换仅适用于您未固定的层级，这与启动回退的条件相同。在您选择的特定版本上的会话，或在[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 上的会话，会保持其模型；如果没有备用模型链，请求会改为失败。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 仅切换到自动模式在 Amazon Bedrock 上支持的模型。如果这些模型中也没有可用的，请求会失败并显示 [AWS 身份验证失败](https://code.claude.com/docs/zh-CN/errors.md#aws-authentication-failed)，并提示启用该模型。354如果您配置了[备用模型链](https://code.claude.com/docs/zh-CN/model-config.md#fallback-model-chains)，Claude Code 会改为切换到您配置的备用模型。如果没有备用模型链，请求会在以下情况下失败：

355 355 

356您配置的[备用模型链](https://code.claude.com/docs/zh-CN/model-config.md#fallback-model-chains)会替换层级切换：在这些拒绝上，Claude Code 会切换到您配置的备用模型。要使被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-CN/env-vars)。您配置的备用链仍会在这些拒绝上切换；如果您希望每个被拒绝的请求都失败，也请移除该链。356* 您的会话使用的是固定模型、您选择的特定版本，或[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile)

357* [Claude Code 尝试的模型](#startup-model-checks)均不可用。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 仅切换到自动模式在 Amazon Bedrock 上支持的模型。

358 

359要继续工作，请在会话中运行 `/model`，并在您的账户可以使用的模型上按 `s`，这不会更改您的默认模型。`403` 会显示为 [AWS 身份验证失败](https://code.claude.com/docs/zh-CN/errors.md#aws-authentication-failed)。

360 

361要使被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-CN/env-vars)。如果您配置了备用模型链，也请将其移除，因为 Claude Code 仍会切换到该备用模型。

357 362 

358## 跨区域推理配置文件前缀363## 跨区域推理配置文件前缀

359 364 

315 {315 {

316 "matcher": "Edit|Write",316 "matcher": "Edit|Write",

317 "hooks": [317 "hooks": [

318 { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }318 { "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }

319 ]319 ]

320 }320 }

321 ]321 ]

74| PostgreSQL 11 或更高版本 | 支持设备登录流和速率限制计数器。托管 PostgreSQL 服务均可使用，包括最小层级；请参阅[支持哪些数据库](https://code.claude.com/docs/zh-CN/claude-apps-gateway-deploy.md#postgres)。使用[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)时，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 要求网关服务器上的 Claude Code 为 v2.1.290 或更高版本。PostgreSQL 项目已不再维护这些版本，因此请尽可能使用更新的版本。 |74| PostgreSQL 11 或更高版本 | 支持设备登录流和速率限制计数器。托管 PostgreSQL 服务均可使用，包括最小层级；请参阅[支持哪些数据库](https://code.claude.com/docs/zh-CN/claude-apps-gateway-deploy.md#postgres)。使用[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)时，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 要求网关服务器上的 Claude Code 为 v2.1.290 或更高版本。PostgreSQL 项目已不再维护这些版本，因此请尽可能使用更新的版本。 |

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

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

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

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

79 79 

80当 `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机时，登录还需要满足以下条件之一：代理的主机名解析为私有地址，或者开发人员机器上的 `NO_PROXY` 中包含网关主机。如果这些机器还设置了 `no_proxy`，也请将网关主机添加到其中，否则模型请求仍会通过代理。

81 

80### 步骤82### 步骤

81 83 

82**1. 在您的 IdP 中注册 OAuth 客户端**84**1. 在您的 IdP 中注册 OAuth 客户端**

656 656 

657| 设置 | 如何 |657| 设置 | 如何 |

658| - | - |658| - | - |

659| RBAC | 授予网关的身份 Microsoft Foundry 资源上的 `Azure AI User` 或 `Cognitive Services User` |659| RBAC | 在 Microsoft Foundry 资源上为网关的身份授予 `Foundry User` 或 `Cognitive Services User` 角色 |

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

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

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

902 902 

903#### 共享预算顺序903#### 共享预算顺序

904 904 

905共享预算是整个组共同消耗的一个月度限额。要设置共享预算，请在[设置该组月度上限的请求](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md#set-a-cap)中添加 `pooled_budget`，例如 `"pooled_budget": {"amount": "500000"}` 表示 \$5,000。该请求还需要该组的 `scope`、`"period": "monthly"` 和 `amount`，其中 `amount` 仍是每位成员自己的上限。905共享预算是整个组共同消耗的一个月度限额。要设置共享预算，请在[设置该组月度上限的请求](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md#set-a-cap)中添加 `pooled_budget`，例如用 `"pooled_budget": {"amount": "500000"}` 表示 \$5,000。该请求还需要该组的 `scope`、`"period": "monthly"` 以及 `amount`，后者仍是每位成员各自的上限。

906 906 

907对于属于多个此类组的开发者，每个请求都会计入第一个支出低于其限额的预算；当所有预算都已用完时，请求会被拒绝。`pooled_conflict_rule` 设置网关尝试这些预算的顺序：907对于属于多个此类组的开发者，每个请求都会计入第一个支出低于其限额的预算；当所有预算都已用完时，请求会被拒绝。`pooled_conflict_rule` 设置网关尝试这些预算的顺序：

908 908 

1001 1001 

1002`upstream_model` 下的每个键必须与已配置上游的 `name` 匹配，该名称默认为提供商名称。不匹配任何上游的键会导致启动失败，因此请省略您不使用的提供商对应的行。1002`upstream_model` 下的每个键必须与已配置上游的 `name` 匹配，该名称默认为提供商名称。不匹配任何上游的键会导致启动失败，因此请省略您不使用的提供商对应的行。

1003 1003 

1004要在 `auto_include_builtin_models: false` 的情况下让开发者使用 `fable` 别名，请在 `models` 中添加一个 `claude-fable-5` 条目。对于登录到网关的开发者，[`fable` 别名](https://code.claude.com/docs/zh-CN/model-config#fable-alias-resolution)解析为该 ID。没有该条目时，他们的消息会失败，错误以 `API Error: 400 model claude-fable-5 is not in the operator's model allowlist` 开头。

1005 

1004### `managed`1006### `managed`

1005 1007 

1006`managed` 块定义基于 IdP 组或电子邮件域的基于角色的访问策略。策略按顺序评估；默认情况下选择第一个匹配项，然后将其合并到 `match: {}` 兜底基础层上。匹配两个角色策略的用户只会获得第一个，因此除非您[应用所有匹配的策略](#apply-every-matching-policy)，否则第二个策略的拒绝规则不会生效。策略按用户在 `GET /managed/settings` 提供，并使用 ETag/304 缓存。1008`managed` 块定义基于 IdP 组或电子邮件域的基于角色的访问策略。策略按顺序评估；默认情况下选择第一个匹配项，然后将其合并到 `match: {}` 兜底基础层上。匹配两个角色策略的用户只会获得第一个，因此除非您[应用所有匹配的策略](#apply-every-matching-policy)，否则第二个策略的拒绝规则不会生效。策略按用户在 `GET /managed/settings` 提供，并使用 ETag/304 缓存。

1025`match: {}` 兜底策略按惯例放在最后，被视为基础层。其他每个策略都会从兜底策略继承自己未设置的任何键，因此按角色的条目只需列出与组织默认值不同的内容。合并规则取决于键的类型：1027`match: {}` 兜底策略按惯例放在最后，被视为基础层。其他每个策略都会从兜底策略继承自己未设置的任何键，因此按角色的条目只需列出与组织默认值不同的内容。合并规则取决于键的类型：

1026 1028 

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

1028* **拒绝列表和 hook 数组**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces`、`deniedModels` 以及每个 `hooks` 事件类型数组。这些取基础层与策略的并集，因此组织范围的拒绝规则或审计 hook 不会被按角色的覆盖意外丢弃。1030* **拒绝列表和 hook 数组**：取基础策略与该策略的并集：

1031 * `permissions.deny` 和 `permissions.ask`

1032 * `disabledMcpjsonServers` 和 `deniedMcpServers`

1033 * `blockedMarketplaces` 和 `deniedModels`

1034 * `hooks` 事件类型数组

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

1030 1036 

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

1593 1599 

1594终端会话将 `user.groups` 放在 OTLP 资源上，并再次放在每个指标数据点和事件上。如果开发者的组在会话打开期间发生变化，下一次[静默刷新](#session)之后的使用情况所对应的数据点和事件会带有新的组。资源会保留旧的组，直到开发者重启 Claude Code，因此请按数据点或事件上的属性进行分组。1600终端会话将 `user.groups` 放在 OTLP 资源上，并再次放在每个指标数据点和事件上。如果开发者的组在会话打开期间发生变化，下一次[静默刷新](#session)之后的使用情况所对应的数据点和事件会带有新的组。资源会保留旧的组，直到开发者重启 Claude Code，因此请按数据点或事件上的属性进行分组。

1595 1601 

1596如果您在 OpenTelemetry Collector 的 Prometheus remote write 导出器中启用了 `resource_to_telemetry_conversion`，该导出器会用资源的 `user.groups` 替换每个数据点的 `user.groups`，因此每个数据点都会显示旧的组。要保留数据点的值，请在该导出器之前从资源中删除 `user.groups`。1602如果您在 OpenTelemetry Collector 的 Prometheus remote write 导出器中启用了 `resource_to_telemetry_conversion`，该导出器会用资源上的值替换每个数据点的 `user.groups`，因此每个数据点都会显示旧的组。要保留数据点上的值，请在该导出器之前从资源中删除 `user.groups`。

1597 1603 

1598此 OpenTelemetry Collector `resource` 处理器会在列出它的管道中删除该属性：1604此 OpenTelemetry Collector `resource` 处理器会在列出它的管道中删除该属性：

1599 1605 

51 51 

52## 部署52## 部署

53 53 

54网关是一个单一的无状态 Linux 二进制文件，通过 Postgres 进行协调，因此按照您在环境中部署任何其他无状态服务的方式部署它。将其保持在您的网络内，让您的开发者可以通过 HTTPS 到达它，且它可以到达您的 IdP，并将网关视为任何持有生产凭据的服务。54网关是一个单一的无状态 Linux 二进制文件，通过 Postgres 进行协调，因此请按照您在环境中部署任何其他无状态服务的方式来部署它。将其保留在您的网络内部，使开发人员可以通过 HTTPS 访问它，并且它可以访问您的 IdP；并像对待任何持有生产凭据的服务一样对待它。

55 55 

56除了运行位置外，还有一些决策塑造部署：56除了运行位置之外，还有几个决策会影响部署：

57 57 

58* **成本**：没有单独的许可证或按座位费用。网关是 `claude` 二进制文件的一部分，因此您通过现有承诺为推理付费，加上它运行的计算。58* **成本**：没有单独的许可证费用或按席位收费。网关是 `claude` 二进制文件的一部分，因此您通过现有的承诺用量支付推理费用，外加运行它所需的计算资源。

59* **绕过**：网关不强制执行通过它的唯一模型路由。具有自己凭证的开发者仍然可以直接调用提供商，因此关闭该路径是网络策略决策，例如阻止到 `api.anthropic.com` 的出口，除了来自网关的。阻止该出口也会破坏 [WebFetch 域安全检查](https://code.claude.com/docs/zh-CN/data-usage.md#webfetch-domain-safety-check)，它从每个开发者的机器调用 `api.anthropic.com`。在托管策略中设置 `skipWebFetchPreflight: true` 以禁用它。59* **绕过**：网关并不强制要求访问模型的唯一途径必须经过它。拥有自己凭据的开发人员仍然可以直接调用提供商，因此关闭该路径属于网络策略决策，例如阻止除网关之外的出站流量访问 `api.anthropic.com`。阻止该出站流量也会破坏 [WebFetch 域安全检查](https://code.claude.com/docs/zh-CN/data-usage.md#webfetch-domain-safety-check)，该检查会从每位开发人员的机器调用 `api.anthropic.com`。在托管策略中设置 `skipWebFetchPreflight: true` 以禁用它。

60* **多个网关**：每个是一个单独的部署，有自己的配置，CLI 按网关主机名存储信任和凭证，因此团队可以使用不同的网关而不会冲突。要提供多个 OIDC 发行者，运行单独的实例。60* **多个网关**：每个网关都是一个独立的部署，拥有自己的配置，并且 CLI 按网关主机名存储信任和凭据，因此不同团队可以使用不同的网关而不会产生冲突。要服务多个 OIDC 颁发者，请运行单独的实例。

61* **无服务器**：Cloud Run 可以工作，如果您设置 `min-instances: 1` 以避免冷 OIDC 发现。Lambda 和 Cloud Functions 不行，因为网关是一个长时间运行的 HTTP 服务器。61* **无服务器**：如果设置 `min-instances: 1` 以避免冷启动时的 OIDC 发现，Cloud Run 可以正常工作。Lambda 和 Cloud Functions 无法使用，因为网关是一个长时间运行的 HTTP 服务器。

62 62 

63这里的每个生产拓扑都在普通 HTTP 副本前面放置一个 L7 代理，如 Ingress、Cloud Run 的前端或 ALB。设置 [`listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen) 为代理的源范围，以便网关从 `X-Forwarded-For` 读取客户端 IP。网关仅在 TCP 对等体受信任时才遵守该标头。[Google Cloud](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md) 和 [AWS](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md) 工作示例为每个拓扑提供具体值。没有受信任的代理，每个请求似乎都来自代理的 IP，这会将按 IP 速率限制折叠为一个共享桶，并在审计事件中记录代理的 IP。63此处的每种生产拓扑都在纯 HTTP 副本前面放置了一个 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。将 [`listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen) 设置为代理的源地址范围，以便网关从 `X-Forwarded-For` 读取客户端 IP。仅当 TCP 对端受信任时，网关才会采用该标头。[Google Cloud](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md) 和 [AWS](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md) 完整示例提供了每种拓扑的具体值。如果没有受信任的代理，每个请求看起来都来自代理的 IP，这会使按 IP 的速率限制合并为一个共享配额，并在审计事件中记录代理的 IP。

64 64 

65不要在网关的设备授权和令牌端点处重定向请求，例如在入口处使用 HTTP 到 HTTPS 或主机规范化重写。Claude Code 不会在这些请求上跟随重定向，因此会破坏登录和令牌刷新的入口规则。65不要将请求重定向到网关的设备授权端点和令牌端点，例如在 ingress 处使用 HTTP 到 HTTPS 或主机名规范化的重写。Claude Code 不会跟随这些请求上的重定向，因此对这些请求进行重定向的 ingress 规则会导致登录和令牌刷新失败。

66 66 

67给代理任何空闲超时时间长于网关的保活间隔，这取决于上游：67为代理设置任意长于网关保活间隔的空闲超时时间，该间隔取决于上游：

68 68 

69* 在除 `provider: anthropic` 之外的每个上游上，一旦流已经沉默约 15 秒，网关就会写入一个 SSE `ping`。69* 在除 `provider: anthropic` 之外的所有上游上，一旦流静默约 15 秒，网关就会写入一个 SSE `ping`。

70* 在 `provider: anthropic` 上，网关原样传递响应，包括 Anthropic API 自己的 ping。70* 在 `provider: anthropic` 上，网关会原样透传响应，包括 Anthropic API 自身的 ping。

71 71 

72默认值（如 ALB 的 60 秒）足以保持安静的流打开。[AWS 工作示例](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md#troubleshooting) 无论如何将其提高到一小时，其故障排除行涵盖早于 v2.1.229 的网关，这些网关在现在获得 ping 的上游上的安静期间没有发送任何内容。72诸如 ALB 默认的 60 秒这样的值足以保持安静的流处于打开状态。[AWS 完整示例](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md#troubleshooting)仍将其提高到一小时，其故障排除条目涵盖了早于 v2.1.229 的网关，这些网关在现在会收到 ping 的上游上，于安静期间不发送任何内容。

73 73 

74### 为网关选择地址74### 为网关选择地址

75 75 

76Claude Code 通过以下两种方式之一接受网关的地址：76Claude Code 通过以下两种方式之一接受网关的地址：

77 77 

78* **私有地址**：将网关置于内部负载均衡器或 VPN 之后，并使用仅解析为私有地址（如 RFC 1918 或 CGNAT `100.64.0.0/10`）的主机名。用户的机器可以使用任何地址。[私有网络前提条件](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites) 列出了可接受的地址范围。78* **私有地址**：将网关置于内部负载均衡器或 VPN 之后，并使用仅解析为私有地址的主机名，例如 RFC 1918 或 CGNAT `100.64.0.0/10`。用户的机器可以使用任何地址。[私有网络前提条件](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites)列出了接受的地址范围。

79* **声明的地址块**：如果您的内部网络使用贵组织拥有的公共 IPv4 地址空间，请在 `gatewayInternalNetworks` 托管设置中列出该地址块。网关和用户的机器都必须位于该地址块内。请参阅 [允许网关使用您拥有的公共地址空间](https://code.claude.com/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。79* **声明的地址块**：如果您的内部网络使用您的组织拥有的公共 IPv4 地址空间，请在 `gatewayInternalNetworks` 托管设置中列出该地址块。网关和用户的机器都必须位于该地址块中。请参阅[允许网关使用您拥有的公共地址空间](https://code.claude.com/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。

80 80 

81如果没有单个地址块能同时包含两者，请改为给网关分配私有地址。81如果没有单个地址块能同时包含两者，请改为给网关分配私有地址。

82 82 

83### 容器镜像83### 容器镜像

84 84 

85围绕标准 Claude Code 版本中的本机 `claude` 二进制文件构建您自己的镜像：85围绕标准 Claude Code 发行版中的原生 `claude` 二进制文件构建您自己的镜像：

86 86 

871. 从固定版本下载您的镜像架构的 Linux 构建；请参阅 [安装特定版本](https://code.claude.com/docs/zh-CN/setup.md#install-a-specific-version) 了解下载 URL。871. 从固定版本中下载适用于您镜像架构的 Linux 构建版本；下载 URL 请参阅[安装特定版本](https://code.claude.com/docs/zh-CN/setup.md#install-a-specific-version)。

882. 根据版本的 GPG 签名 `manifest.json` 验证它，如 [二进制完整性和代码签名](https://code.claude.com/docs/zh-CN/setup.md#binary-integrity-and-code-signing) 中所述。882. 按照[二进制完整性和代码签名](https://code.claude.com/docs/zh-CN/setup.md#binary-integrity-and-code-signing)中的说明，根据该版本经过 GPG 签名的 `manifest.json` 对其进行验证。

893. 将其复制到构建上下文中。893. 将其复制到构建上下文中。

90 90 

91如果您的构建无法到达版本主机，请将版本镜像到您的内部注册表中，并固定您的舰队运行的版本。91如果您的构建无法访问发布主机，请将该版本镜像到您的内部镜像仓库，并固定您的机群所运行的版本。

92 92 

93除了二进制文件外，镜像还需要：93除了二进制文件之外，镜像还需要：

94 94 

95* **基于 glibc 的镜像**：glibc 构建的唯一动态依赖项是 glibc 库。基于 Musl 的镜像需要 `linux-x64-musl` 或 `linux-arm64-musl` 构建加上额外的包；请参阅 [Alpine Linux 设置](https://code.claude.com/docs/zh-CN/setup.md#alpine-linux-and-musl-based-distributions)。95* **基于 glibc 的镜像**：glibc 构建版本唯一的动态依赖是 glibc 库。基于 musl 的镜像需要 `linux-x64-musl` 或 `linux-arm64-musl` 构建版本，其唯一的动态依赖是 musl。

96* **可写状态目录**：网关以任何用户身份运行，但最小镜像没有可写的主目录。将 `CLAUDE_CONFIG_DIR` 设置为可写路径，如 `/tmp/.claude`。96* **可写的状态目录**：网关可以以任何用户身份运行，但精简镜像没有可写的主目录。将 `CLAUDE_CONFIG_DIR` 设置为可写路径，例如 `/tmp/.claude`。

97* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置文件以只读方式挂载，密钥作为环境变量提供；网关在 `listen.port` 上监听，默认为 `8080`。97* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，以只读方式挂载配置文件，并以环境变量的形式提供密钥；网关在 `listen.port` 上监听，默认为 `8080`。

98 98 

99### Kubernetes99### Kubernetes

100 100 

101将网关作为 Deployment 运行，就像任何无状态服务一样：101像任何无状态服务一样，将网关作为 Deployment 运行：

102 102 

103* 从 ConfigMap 挂载配置，从 Secret 挂载密钥；通过 `${file:/path/to/secret}` 或作为环境变量在 YAML 中引用密钥103* 从 ConfigMap 挂载配置，从 Secret 挂载密钥；在 YAML 中通过 `${file:/path/to/secret}` 或以环境变量的形式引用密钥

104* 在 Ingress 处终止 TLS 并将 `listen.public_url` 设置为 Ingress 主机名104* 在 Ingress 处终止 TLS，并将 `listen.public_url` 设置为 Ingress 主机名

105* 将就绪探针指向 `GET /readyz`，将活跃探针指向 `GET /healthz`105* 将就绪探针指向 `GET /readyz`，将存活探针指向 `GET /healthz`

106 106 

107有关 AWS 上的完整工作示例，涵盖 ECS Fargate 或 EKS、Amazon RDS 和 AWS Secrets Manager，请参阅 [在 AWS 上部署](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md)。107有关 AWS 上的完整示例（涵盖 ECS Fargate 或 EKS、Amazon RDS 和 AWS Secrets Manager），请参阅[在 AWS 上部署](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-aws.md)。

108 108 

109优先使用平台的工作负载身份而不是静态密钥；[`upstreams` 参考](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#upstreams) 有每个平台的设置详情。对于跨云配对，如 GKE 上的 Amazon Bedrock 上游，在上游的 `auth` 块中设置显式凭证。109优先使用平台的工作负载身份而不是静态密钥；[`upstreams` 参考](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#upstreams)提供了各平台的设置详情。对于跨云组合，例如在 GKE 上使用 Amazon Bedrock 上游，请改为在上游的 `auth` 块中设置显式凭据。

110 110 

111### Cloud Run111### Cloud Run

112 112 

113按如下方式配置服务：113按如下方式配置服务：

114 114 

115* 将 `listen.port` 保留在其默认值 `8080`，这与 Cloud Run 的默认 `PORT` 匹配，或设置 `port: ${PORT}`115* 将 `listen.port` 保留为默认值 `8080`（与 Cloud Run 的默认 `PORT` 一致），或设置 `port: ${PORT}`

116* 将 `public_url` 设置为外部可达的源。对于生产，这通常是内部负载均衡器的主机名，因为 `/login` [拒绝公共地址](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析为一个，所以单独的 Cloud Run URL 仅适用于 `curl` 或浏览器烟雾测试。例外是一个网络，其中 `*.run.app` 通过 Private Service Connect 和 Cloud DNS 私有区域私下解析；在该拓扑中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 工作示例](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md#deploy-the-gateway) 涵盖两者。116* 将 `public_url` 设置为外部可访问的源。对于生产环境，这通常是内部负载均衡器的主机名，因为 `/login` [会拒绝公共地址](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 会解析为公共地址，因此仅使用 Cloud Run URL 只适用于 `curl` 或浏览器冒烟测试。例外情况是 `*.run.app` 通过 Private Service Connect 和 Cloud DNS 私有区域解析为私有地址的网络；在该拓扑中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 完整示例](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md#deploy-the-gateway)涵盖了这两种情况。

117* 将配置作为密钥卷挂载117* 将配置作为密钥卷挂载

118* 设置 `min-instances: 1` 以避免首次请求时的冷 OIDC 发现118* 设置 `min-instances: 1`，以避免在首次请求时进行冷启动的 OIDC 发现

119 119 

120有关 Google Cloud 上的完整工作示例，涵盖 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，请参阅 [在 Google Cloud 上部署](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md)。120有关 Google Cloud 上的完整示例（涵盖 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager），请参阅[在 Google Cloud 上部署](https://code.claude.com/docs/zh-CN/claude-apps-gateway-on-gcp.md)。

121 121 

122### 将网关 URL 推送到开发者机器122### 将网关 URL 推送到开发人员机器

123 123 

124一旦网关开始提供服务，通过托管设置、MDM 或直接写入每个操作系统的 `managed-settings.json` 将 `forceLoginMethod`、`forceLoginGatewayUrl` 和 `parentSettingsBehavior: "merge"` 推送到每个开发者的机器。124网关开始提供服务后，通过托管设置将 `forceLoginMethod`、`forceLoginGatewayUrl` 和 `parentSettingsBehavior: "merge"` 推送到每位开发人员的机器上，可以通过 MDM 或直接写入各操作系统对应的 `managed-settings.json` 来完成。

125 125 

126一旦您部署密钥，Claude Code 停止使用机器上剩余的 API 密钥或 claude.ai 登录，因此计划与您的登录说明一起推送。[管理员策略需要 Cloud 网关登录](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in) 描述开发者看到的消息。126部署这些设置项后，Claude Code 将停止使用机器上残留的 API 密钥或 claude.ai 登录，因此请将推送与您的登录说明一起规划。[Administrator policy requires a Cloud gateway sign-in](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in) 描述了开发人员会看到的消息。

127 127 

128请参阅 [每个机制存储策略的位置](https://code.claude.com/docs/zh-CN/managed-settings.md#where-each-mechanism-stores-the-policy) 了解文件路径，以及 [客户端托管设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#client-side-managed-settings) 了解 Claude Desktop `bootstrapUrl` 等效项。128有关文件路径，请参阅[每种机制存储策略的位置](https://code.claude.com/docs/zh-CN/managed-settings.md#where-each-mechanism-stores-the-policy)；有关 Claude Desktop 的等效设置 `bootstrapUrl`，请参阅[客户端托管设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#client-side-managed-settings)。

129 129 

130### 大规模推出130### 大规模推广

131 131 

132登录按客户端 IP 地址进行速率限制，默认值适合小团队。每个地址每 10 分钟获得 30 次登录开始和 10 次代码提交。向数千名开发者的推出可能在第一个早上达到这些限制，原因有两个：132登录按客户端 IP 地址进行速率限制，默认值适合小型团队。每个地址每 10 分钟可发起 30 次登录和提交 10 次代码。面向数千名开发人员的推广可能在第一天早上就达到这些限制，原因有以下两种：

133 133 

134* **网关看不到您的负载均衡器后面。** 没有 [`listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen)，每个开发者似乎都来自负载均衡器的地址并共享一个限制。网关在第一次忽略 `X-Forwarded-For` 标头时会记录警告。如果该负载均衡器[应列入 `listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen)，请在更改其他任何内容之前先将其列入。如果开发者仍然共享一个地址，请提高 [`rate_limits`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning)。134* **网关无法看到负载均衡器之后的地址。** 如果没有 [`listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen)，每位开发人员看起来都来自负载均衡器的地址，并共享一个限制。网关首次忽略 `X-Forwarded-For` 标头时会记录一条警告。如果负载均衡器[应当列入 `listen.trusted_proxies`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#listen)，请在更改任何其他内容之前先将其列入。如果开发人员仍然共享一个地址，请提高 [`rate_limits`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning)。

135* **许多开发者共享几个 NAT 或 VPN 出口地址。** 即使 `trusted_proxies` 正确，他们也共享这些地址的限制。提高 [`rate_limits`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning) 以适应。135* **许多开发人员共享少量 NAT 或 VPN 出口地址。** 即使 `trusted_proxies` 设置正确，他们也会共享这些地址的限制。请相应提高 [`rate_limits`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning)。

136 136 

137要调整 `max`，将开发者数除以他们共享的出口地址数。估计在一个 `window_seconds` 周期内有多少人登录，默认为 10 分钟。然后将其加倍以覆盖重试和同时登录 Claude Code 和 Claude Desktop 的开发者。137要确定 `max` 的大小，请用开发人员数量除以他们共享的出口地址数量。估算其中有多少人会在一个 `window_seconds` 周期（默认为 10 分钟）内登录。然后将其翻倍，以覆盖重试以及同时登录 Claude Code 和 Claude Desktop 的开发人员。

138 138 

139例如，10,000 名开发者在 4 个出口地址后面在一小时内均匀登录。这是每个地址 2,500 名开发者，每 10 分钟约 420 名，您将其加倍并四舍五入到 1,000。下面的示例将两个限制都设置为 1,000：139例如，位于 4 个出口地址之后的 10,000 名开发人员在一小时内均匀登录。即每个地址 2,500 名开发人员，每 10 分钟约有 420 人登录，将其翻倍并向上取整为 1,000。下面的示例将两个限制都设置为 1,000：

140 140 

141```yaml theme={null}141```yaml theme={null}

142rate_limits:142rate_limits:

144 device_verify: { max: 1000, window_seconds: 600 }144 device_verify: { max: 1000, window_seconds: 600 }

145```145```

146 146 

147`device_verify` 是阻止某人猜测另一个开发者登录代码的原因，因此仅在您的估计需要的范围内提高它。即使在这些限制下，代码也是来自 20 字符字母表的 8 个字符，并在 10 分钟后过期，因此猜测仍然不切实际；请参阅 [用户代码暴力破解抵抗](#user-code-brute-force-resistance)。147`device_verify` 用于防止有人猜测其他开发人员的登录代码，因此只需将其提高到您的估算所需的程度。即使在这些限制下，代码也是由 20 个字符的字母表组成的 8 个字符，并在 10 分钟后过期，因此猜测仍然不切实际；请参阅[用户代码防暴力破解](#user-code-brute-force-resistance)。

148 148 

149当您的 IdP 发出刷新令牌时，Claude Code 会无声地续订会话，因此您可以在推出后将限制放回。没有刷新令牌，开发者每 [`session.ttl_hours`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#session) 再次登录。为该稳定速率调整两个限制的大小，并保持它们提高。149当您的 IdP 颁发刷新令牌时，Claude Code 会静默续订会话，因此您可以在推广完成后恢复限制。如果没有刷新令牌，开发人员每隔 [`session.ttl_hours`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#session) 就需要重新登录。请同样按照该稳定速率确定两个限制的大小，并保持提高后的值。

150 150 

151当达到限制时，Claude Code v2.1.274 或更高版本显示 `The gateway is limiting sign-in attempts right now`。v2.1.274 或更高版本的网关在验证页面上显示 `Too many attempts came from your network address`，并提供要检查的设置。它还写入一条 `sign-in refused` 日志行，命名要更改的设置。151达到限制时，Claude Code v2.1.274 或更高版本会显示 `The gateway is limiting sign-in attempts right now`。v2.1.274 或更高版本的网关会在验证页面上显示 `Too many attempts came from your network address`，并列出需要检查的设置。它还会写入一条 `sign-in refused` 日志，指明需要更改的设置。

152 152 

153## 运维153## 运维

154 154 

274 274 

275线程在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)中运行，因此 Claude 在该文件夹中运行命令和编辑文件而不每次都询问你。如果自动模式在该计算机的 Claude Code 中不可用或已关闭，线程在没有它的情况下运行，它引发的任何权限提示都会在线程中等待你的答案，如[解除等待批准的线程](#unblock-a-thread-waiting-on-approval)所述。275线程在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)中运行，因此 Claude 在该文件夹中运行命令和编辑文件而不每次都询问你。如果自动模式在该计算机的 Claude Code 中不可用或已关闭，线程在没有它的情况下运行，它引发的任何权限提示都会在线程中等待你的答案，如[解除等待批准的线程](#unblock-a-thread-waiting-on-approval)所述。

276 276 

277要以其他模式运行线程，请使用 [`--settings`](https://code.claude.com/docs/zh-CN/remote-control#start-a-remote-control-session) 启动 `claude remote-control`。然后，该文件中或该计算机设置中的 [`permissions.defaultMode`](https://code.claude.com/docs/zh-CN/permission-modes#start-in-a-different-mode) 可以选择其他模式。

278 

277线程运行时，其标题中的笔记本电脑图标会显示您的计算机是否已连接。点击该图标可查看线程正在使用哪个文件夹，或关闭连接。当该计算机处于睡眠状态时，线程会暂停；如果桌面应用或 `claude remote-control` 退出，线程会停止。279线程运行时，其标题中的笔记本电脑图标会显示您的计算机是否已连接。点击该图标可查看线程正在使用哪个文件夹，或关闭连接。当该计算机处于睡眠状态时，线程会暂停；如果桌面应用或 `claude remote-control` 退出，线程会停止。

278 280 

279* **要让线程重新运行**：请参阅[与您的文件夹失去联系](#lost-contact-with-your-folder)281* **要让线程重新运行**：请参阅[与您的文件夹失去联系](#lost-contact-with-your-folder)

35下表列出了 Claude Code 中包含的所有命令。大多数是内置命令，其行为编码在 CLI 中。有两类条目带有标记：35下表列出了 Claude Code 中包含的所有命令。大多数是内置命令，其行为编码在 CLI 中。有两类条目带有标记：

36 36 

37* **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)**：随附 skill。它的工作方式与您自己编写的 skill 相同：是交给 Claude 的提示词。37* **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)**：随附 skill。它的工作方式与您自己编写的 skill 相同：是交给 Claude 的提示词。

38 * `/verify` 仅在您调用时运行。

39* **[工作流](https://code.claude.com/docs/zh-CN/workflows.md#bundled-workflows)**：随附的[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)，会将工作分发到多个子代理并在后台运行。38* **[工作流](https://code.claude.com/docs/zh-CN/workflows.md#bundled-workflows)**：随附的[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)，会将工作分发到多个子代理并在后台运行。

40 * `/deep-research` 仅在您调用时运行。

41 39 

42要添加您自己的命令，请参阅 [skill](https://code.claude.com/docs/zh-CN/skills.md)。40要添加您自己的命令，请参阅 [skill](https://code.claude.com/docs/zh-CN/skills.md)。

43 41 

71 71 

72从应用启动器启动 **Claude**，或从终端运行 `claude-desktop`，然后使用您的 Anthropic 账户登录。72从应用启动器启动 **Claude**，或从终端运行 `claude-desktop`，然后使用您的 Anthropic 账户登录。

73 73 

74Linux 应用的登录方式与 macOS 和 Windows 上相同：使用 claude.ai 订阅或通过您组织的 SSO。如需使用 API 密钥身份验证，请使用 [CLI](https://code.claude.com/docs/zh-CN/quickstart.md)。如果要改为将 Desktop 与 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关配合使用，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。有关这些部署中的代理服务器和自定义证书颁发机构，请参阅 [网络配置](https://code.claude.com/docs/zh-CN/network-config.md)。74Linux 应用的登录方式与 macOS 和 Windows 上相同：使用 claude.ai 订阅或通过您组织的 SSO。如果要改为将 Desktop 与 Claude API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关配合使用，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。有关这些部署中的代理服务器和自定义证书颁发机构，请参阅 [网络配置](https://code.claude.com/docs/zh-CN/network-config.md)。

75 75 

76### 从下载的文件安装76### 从下载的文件安装

77 77 

83 83 

84**8. 选择权限模式和模型**84**8. 选择权限模式和模型**

85 85 

86在指令输入框的工具栏中，选择[权限模式](#permissions-for-scheduled-tasks)和模型。如果保持不变，运行时将使用您的 Claude Code 设置和默认模型。86在指令输入框的工具栏中，选择[权限模式](#permissions-for-scheduled-tasks)和模型。

87 

88* **权限模式**：如果保持不变，运行时将使用您的 Claude Code 设置。

89* **模型**：如果模型菜单显示 **Default · Set by admin**，且您没有选择其他模型，运行时将使用您的组织在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置的模型。在应用打开时启动的[补运行](#missed-runs)可能会改为使用[您账户的运行时默认模型](https://code.claude.com/docs/zh-CN/model-config.md#default-model-setting)。

87 90 

88**9. 创建任务**91**9. 创建任务**

89 92 

90单击 **Create**。如果您尚未信任该文件夹，Desktop 会在此时要求您信任它。随后将打开该任务的详情页面。93单击 **Create**。如果您尚未信任该文件夹，Desktop 会在此时要求您信任它。随后将打开该任务的详情页面。

91 94 

95要查看 **Default · Set by admin** 代表哪个模型，请在详情页面上单击 **Run now** 以立即运行该任务。然后[打开该次运行的会话](#find-a-runs-session)，输入框下方的行会显示该模型的名称。

96 

92在详情页面上，单击铅笔图标以打开 [**Edit** 表单](#manage-scheduled-tasks)。在该表单中，您可以更改 Desktop 根据您的指令填写的 **Description**、选择 **Worktree**，或将计划切换为 **Manual** 或 **Custom**。97在详情页面上，单击铅笔图标以打开 [**Edit** 表单](#manage-scheduled-tasks)。在该表单中，您可以更改 Desktop 根据您的指令填写的 **Description**、选择 **Worktree**，或将计划切换为 **Manual** 或 **Custom**。

93 98 

94您也可以通过在任何会话中描述您想要的内容来创建任务。例如，"设置一个每天早上 9 点运行的日常代码审查"会创建一个周期性任务。像"提醒我明天下午 3 点检查部署"这样的请求会创建一个一次性任务，该任务在触发后会自行禁用。99您也可以通过在任何会话中描述您想要的内容来创建任务。例如，"设置一个每天早上 9 点运行的日常代码审查"会创建一个周期性任务。像"提醒我明天下午 3 点检查部署"这样的请求会创建一个一次性任务，该任务在触发后会自行禁用。

181 186 

182要让任务使用 `update_scheduled_task` MCP 工具更改其自己的调度或提示词，请单击 **Run now** 并每次批准该调用。187要让任务使用 `update_scheduled_task` MCP 工具更改其自己的调度或提示词，请单击 **Run now** 并每次批准该调用。

183 188 

184要在磁盘上编辑任务的提示，请打开 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars)，则在其下）。该文件使用 YAML frontmatter 表示 `name` 和 `description`，提示作为正文。更改在下一次运行时生效。Schedule、folder、model 和 enabled 状态不在此文件中：通过 Edit 表单更改它们或询问 Claude。189要在磁盘上编辑任务的提示词，请打开 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars)，则在其下）。该文件使用 YAML frontmatter 表示 `name` 和 `description`，提示词作为正文。更改在下一次运行时生效。Schedule、folder 和 enabled 状态不在此文件中：通过 Edit 表单更改它们或询问 Claude。

185 190 

186## 相关资源191## 相关资源

187 192 

122| `A request to MCP server "<name>" was sent without your stored credentials` | [身份验证](#couldnt-read-the-stored-credentials-for-mcp-server) |122| `A request to MCP server "<name>" was sent without your stored credentials` | [身份验证](#couldnt-read-the-stored-credentials-for-mcp-server) |

123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [身份验证](#mcp-server-url-is-missing-or-not-a-valid-url) |123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [身份验证](#mcp-server-url-is-missing-or-not-a-valid-url) |

124| `Issuer mismatch in authorization response (RFC 9207)` | [身份验证](#issuer-mismatch-in-authorization-response) |124| `Issuer mismatch in authorization response (RFC 9207)` | [身份验证](#issuer-mismatch-in-authorization-response) |

125| `Stopped an OAuth request` | [身份验证](#stopped-an-oauth-request) |

125| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [身份验证](#refusing-to-send-credentials-to-non-https-token-endpoint) |126| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [身份验证](#refusing-to-send-credentials-to-non-https-token-endpoint) |

126| `Cloud gateway session expired — run /login to reconnect.` | [身份验证](#cloud-gateway-session-expired) |127| `Cloud gateway session expired — run /login to reconnect.` | [身份验证](#cloud-gateway-session-expired) |

127| `Cloud gateway <url> no longer accepts this session` | [身份验证](#cloud-gateway-session-expired) |128| `Cloud gateway <url> no longer accepts this session` | [身份验证](#cloud-gateway-session-expired) |

251| `Ultrareview did not start` | [命令行错误](#ultrareview-did-not-start) |252| `Ultrareview did not start` | [命令行错误](#ultrareview-did-not-start) |

252| `Remote Control did not start: "<question>" got no answer` | [命令行错误](#remote-control-did-not-start-got-no-answer) |253| `Remote Control did not start: "<question>" got no answer` | [命令行错误](#remote-control-did-not-start-got-no-answer) |

253| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令行错误](#not-carried-over-to-the-sessions-remote-control-starts) |254| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令行错误](#not-carried-over-to-the-sessions-remote-control-starts) |

255| `Remote Control did not start, because sessions would skip part or all of the --settings file` | [命令行错误](#remote-control-did-not-start-because-of-the-settings-file) |

256| `The settings file <file> has changed since Remote Control started, so this session did not start` | [命令行错误](#settings-file-changed-since-remote-control-started) |

254| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [命令行错误](#sandbox-is-not-supported-by-claude-remote-control) |257| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [命令行错误](#sandbox-is-not-supported-by-claude-remote-control) |

255| `` `claude import` is not yet available in this build `` | [命令行错误](#claude-import-is-not-yet-available-in-this-build) |258| `` `claude import` is not yet available in this build `` | [命令行错误](#claude-import-is-not-yet-available-in-this-build) |

256| `Could not read Claude Code config` | [命令行错误](#could-not-read-claude-code-config) |259| `Could not read Claude Code config` | [命令行错误](#could-not-read-claude-code-config) |

825同一 Claude 回复中的后续调用可能会以此原因被拒绝：828同一 Claude 回复中的后续调用可能会以此原因被拒绝：

826 829 

827```text theme={null}830```text theme={null}

828another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged831another call in this response was changed after auto mode reviewed it, or could not be confirmed unchanged

829```832```

830 833 

831Claude 随后可以再次发出每个被拒绝的调用，以便服务器对其进行审查。如果打开了权限提示，请作出回应。除非 Claude 在回复中说明自动模式无法检查该调用，否则您无需执行其他任何操作。在这种情况下，请停止该更改或自行批准该调用，然后让 Claude 再次尝试该调用：834Claude 随后可以再次发出每个被拒绝的调用，以便服务器对其进行审查。如果打开了权限提示，请作出回应。除非 Claude 在回复中说明自动模式无法检查该调用，否则您无需执行其他任何操作。在这种情况下，请停止该更改或自行批准该调用，然后让 Claude 再次尝试该调用：

1822 1825 

1823在 v2.1.232 之前，Claude Code 仅在逐步推出时或您设置 `MCP_SDK_GENERATION=v2` 时才使用 v2 运行时。1826在 v2.1.232 之前，Claude Code 仅在逐步推出时或您设置 `MCP_SDK_GENERATION=v2` 时才使用 v2 运行时。

1824 1827 

1828### Stopped an OAuth request

1829 

1830此消息表示 Claude Code 停止了一个[针对 MCP 服务器的 OAuth 请求](https://code.claude.com/docs/zh-CN/mcp.md#authenticate-with-remote-mcp-servers)，因为某个 OAuth 端点对其进行了重定向。在该消息的两种形式中，第一个地址都是发送重定向的地址：

1831 

1832```text theme={null}

1833Stopped an OAuth request, which can hold secrets: https://auth.example.com redirected it to https://other.example.com. Ask the owner of https://auth.example.com to remove that redirect.

1834Stopped an OAuth request: https://auth.example.com redirected it more than 5 times. Ask the owner of https://auth.example.com to fix those redirects.

1835```

1836 

1837**解决方法：**

1838 

1839* 请第一个地址的运营者（例如 MCP 服务器的运营方）移除或修复该重定向。然后从 `/mcp` 再次尝试。

1840 

1825### 拒绝向非 https 令牌端点发送凭据1841### 拒绝向非 https 令牌端点发送凭据

1826 1842 

1827在 [v2 运行时](https://code.claude.com/docs/zh-CN/mcp.md#mcp-client-runtimes)上，Claude Code 只会将 [MCP OAuth](https://code.claude.com/docs/zh-CN/mcp.md#authenticate-with-remote-mcp-servers) 令牌请求发送到通过 HTTPS 提供服务的令牌端点，或位于 `localhost`、`127.0.0.1` 或 `::1` 的令牌端点。此消息表示服务器的令牌端点两者都不是，因此 Claude Code 在发送请求前就停止了。这发生在浏览器登录之后，因此浏览器步骤会先成功，并且每当 Claude Code 刷新该服务器的令牌时都会再次发生。1843在 [v2 运行时](https://code.claude.com/docs/zh-CN/mcp.md#mcp-client-runtimes)上，Claude Code 只会将 [MCP OAuth](https://code.claude.com/docs/zh-CN/mcp.md#authenticate-with-remote-mcp-servers) 令牌请求发送到通过 HTTPS 提供服务的令牌端点，或位于 `localhost`、`127.0.0.1` 或 `::1` 的令牌端点。此消息表示服务器的令牌端点两者都不是，因此 Claude Code 在发送请求前就停止了。这发生在浏览器登录之后，因此浏览器步骤会先成功，并且每当 Claude Code 刷新该服务器的令牌时都会再次发生。

2207 2223 

2208### 云端会话中不允许访问该主机2224### 云端会话中不允许访问该主机

2209 2225 

2210来自云端会话或云端定时任务的出站 HTTP 请求被环境的网络策略阻止。2226在云端会话或云端定时任务中，`403` 或 DNS 错误（例如 `ENOTFOUND`）可能意味着所请求的主机不在[云环境的允许列表](https://code.claude.com/docs/zh-CN/cloud-environments.md#access-levels)中。要确认这一点，请将该主机与该列表进行核对。带有以下标头的 `403` 可以确认请求已被阻止，但并非每个被阻止请求的 `403` 都带有该标头：

2211 2227 

2212```text theme={null}2228```text theme={null}

2213HTTP 4032229HTTP 403

2565 2581 

2566Claude Code 通常会自动调整大型图像的大小。这些错误意味着无法解码或调整图像大小以适应 API 限制。2582Claude Code 通常会自动调整大型图像的大小。这些错误意味着无法解码或调整图像大小以适应 API 限制。

2567 2583 

2584您看到的错误可能会指明不同的像素限制，例如在这些示例显示 `2000x2000px` 的位置显示 `2576x2576px`。

2585 

2568**要做什么：**2586**要做什么：**

2569 2587 

2570* 如果消息要求您转换图像，请将其转换为 PNG、JPEG、GIF 或 WebP，然后再次附加。Claude Code 可以从文件头为这些格式验证尺寸，而无需解码图像。2588* 如果消息要求您转换图像，请将其转换为 PNG、JPEG、GIF 或 WebP，然后再次附加。Claude Code 可以从文件头为这些格式验证尺寸，而无需解码图像。

2873* **hook 写入的原因**：PreModelSwitch hook 在[拒绝切换或要求确认](https://code.claude.com/docs/zh-CN/hooks.md#premodelswitch-decision-control)时提供了该原因。解决它要求的内容，或选择您的 hook 允许的模型。2891* **hook 写入的原因**：PreModelSwitch hook 在[拒绝切换或要求确认](https://code.claude.com/docs/zh-CN/hooks.md#premodelswitch-decision-control)时提供了该原因。解决它要求的内容，或选择您的 hook 允许的模型。

2874* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[超时](https://code.claude.com/docs/zh-CN/hooks.md#timeouts)之前不回答的 hook 阻止切换。修复挂起的命令或提高该 hook 的 `timeout`，然后再次切换。2892* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[超时](https://code.claude.com/docs/zh-CN/hooks.md#timeouts)之前不回答的 hook 阻止切换。修复挂起的命令或提高该 hook 的 `timeout`，然后再次切换。

2875* **`confirmation required, and this session cannot ask`**：hook 回答 `ask` 而没有原因，控制请求无法显示确认提示。[`-p` 运行](https://code.claude.com/docs/zh-CN/headless)中的 `/model` 命令以原因后的 `(run /model interactively to confirm)` 报告相同条件。从交互式会话进行切换，或更改 hook 对此模型的决定。2893* **`confirmation required, and this session cannot ask`**：hook 回答 `ask` 而没有原因，控制请求无法显示确认提示。[`-p` 运行](https://code.claude.com/docs/zh-CN/headless)中的 `/model` 命令以原因后的 `(run /model interactively to confirm)` 报告相同条件。从交互式会话进行切换，或更改 hook 对此模型的决定。

2876* **`so organization-managed PreModelSwitch hooks could not be checked`**：Claude Code 无法判断您的组织的[托管插件](https://code.claude.com/docs/zh-CN/settings-reference.md#enabledplugins)提供哪些 PreModelSwitch hook，例如因为托管插件加载失败。这些 hook 之一可能阻止切换，因此 Claude Code 拒绝而不是应用未检查的切换。原因的开头命名失败的内容。Claude Code 在每次切换尝试时重新检查，因此已清除的失败不再阻止；如果它继续失败，运行 `claude --debug` 并再次切换以捕获详细信息，然后修复插件或要求您的管理员修复它。2894* **`so organization-managed PreModelSwitch hooks could not be checked`**：v2.1.323 之前的 Claude Code 在无法判断您的[托管插件](https://code.claude.com/docs/zh-CN/settings-reference.md#enabledplugins)提供了哪些 PreModelSwitch hook 时会拒绝切换。此短语之前的文本指出了失败的内容。要停止拒绝，请更新 Claude Code。若还要让失败插件的 hook 运行起来，请修复该插件或联系管理员。有关详细信息，请在 shell 中启动 `claude --debug` 并切换模型，然后阅读[调试日志](https://code.claude.com/docs/zh-CN/hooks.md#debug-hooks)。

2877* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 运行在没有判决的情况下结束，Claude Code 不将其视为批准。运行 `claude --debug` 以查看失败的内容，然后再次切换。2895* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 运行在没有判决的情况下结束，Claude Code 不将其视为批准。运行 `claude --debug` 以查看失败的内容，然后再次切换。

2878 2896 

2879在 v2.1.260 之前，托管插件拒绝读取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重试了一次插件加载，然后在会话中拒绝了后来的切换，即使您的组织没有管理任何插件。在这些版本上重启会话以再次运行插件加载。2897在 v2.1.260 之前，托管插件拒绝读取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重试了一次插件加载，然后在会话中拒绝了后来的切换，即使您的组织没有管理任何插件。在这些版本上重启会话以再次运行插件加载。

3499* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。3517* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。

3500* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。3518* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。

3501* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。3519* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。

3502* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟了非标志的内容，例如 PR 编号或 `false`。如果您不信任该文件夹，请不要使用该标志。如果要在本次运行中信任它，请将 PR 编号或基准分支放在该标志之前：`claude ultrareview 1234 --trust-workspace`。3520* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟着的不是标志，例如 PR 编号或 `false`。如果您不信任该文件夹，请不要使用该标志。如果要在此次运行中信任它，请将 PR 编号或基础分支放在该标志之前：`claude ultrareview 1234 --trust-workspace`。

3503 3521 

3504在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。3522在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。

3505 3523 

3522您在 `remote-control` 动词之前使用了一个全局 `claude` 标志来启动 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md)，而该标志会限制或配置 Remote Control 启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会传递到这些会话。Claude Code 会拒绝启动，并指出该标志：3540您在 `remote-control` 动词之前使用了一个全局 `claude` 标志来启动 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md)，而该标志会限制或配置 Remote Control 启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会传递到这些会话。Claude Code 会拒绝启动，并指出该标志：

3523 3541 

3524```text theme={null}3542```text theme={null}

3525Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3543Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`). Pass settings with `claude remote-control --settings <file>`.

3526```3544```

3527 3545 

3528对于丢弃后无害的全局标志，例如 `--verbose`、`--model`，或由包装器注入的 `--session-id` 或 `--plugin-dir`，Claude Code 不会拒绝：它会忽略这些标志，Remote Control 照常启动。3546对于丢弃后无害的全局标志，例如 `--verbose`、`--model`，或由包装器注入的 `--session-id` 或 `--plugin-dir`，Claude Code 不会拒绝：它会忽略这些标志，Remote Control 照常启动。

3536 3554 

3537在 v2.1.248 之前，当全局标志在前时，`claude remote-control` 不接受其自身的标志，命令会以 `unknown option` 错误失败。3555在 v2.1.248 之前，当全局标志在前时，`claude remote-control` 不接受其自身的标志，命令会以 `unknown option` 错误失败。

3538 3556 

3557### 由于 `--settings` 文件，Remote Control 未启动

3558 

3559您传给 [`claude remote-control --settings`](https://code.claude.com/docs/zh-CN/remote-control#start-a-remote-control-session) 的文件存在问题：

3560 

3561```text theme={null}

3562Error: Remote Control did not start, because sessions would skip part or all of the --settings file ./rc-settings.json: Invalid or malformed JSON

3563```

3564 

3565**解决方法：**

3566 

3567* 修复消息中指出的问题，然后再次运行您的 `claude remote-control` 命令

3568 

3569### The settings file has changed since Remote Control started

3570 

3571在运行 `claude remote-control` 的终端中出现此消息，表示会话不会基于您传给 [`--settings`](https://code.claude.com/docs/zh-CN/remote-control#start-a-remote-control-session) 的文件的当前内容启动：

3572 

3573```text theme={null}

3574Session failed: Error: The settings file /path/to/settings.json has changed since Remote Control started, so this session did not start. Restart `claude remote-control` to use it as it is now.

3575```

3576 

3577**解决方法：**

3578 

3579* 如果要使用该文件的当前内容，请停止 `claude remote-control` 并再次运行相同的命令。要恢复它之前提供服务的会话，请参阅[停止服务器后恢复会话](https://code.claude.com/docs/zh-CN/remote-control.md#resume-sessions-after-stopping-the-server)。

3580* 如果要保留 Remote Control 启动时使用的设置，请将文件内容恢复原样；如果 `claude remote-control` 已退出，则再次运行该命令

3581 

3539### `--sandbox` or `--no-sandbox` is not supported by claude remote-control3582### `--sandbox` or `--no-sandbox` is not supported by claude remote-control

3540 3583 

3541此错误表示启动您 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 服务器的命令在 `remote-control` 之后传入了 `--sandbox` 或 `--no-sandbox`，而 `claude remote-control` 不接受这两个标志中的任何一个。服务器以退出码 1 退出，而不会启动：3584此错误表示启动您 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 服务器的命令在 `remote-control` 之后传入了 `--sandbox` 或 `--no-sandbox`，而 `claude remote-control` 不接受这两个标志中的任何一个。服务器以退出码 1 退出，而不会启动：

3806 3849 

3807以下相关消息会在命令运行之前就出现：3850以下相关消息会在命令运行之前就出现：

3808 3851 

3809* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许它运行。[注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在各权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令3852* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许它运行。[注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在每种权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令

3810* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求 bash，但机器上没有 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令的运行方式](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)3853* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求使用 bash，而机器上没有 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令的运行方式](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)

3811 3854 

3812**解决方法：**3855**解决方法：**

3813 3856 

3960 4003 

3961* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示4004* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示

3962* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``4005* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3963* **您传入的基础分支不在您的克隆中**：Claude Code 在比较之前从 origin 获取了该分支。提示为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上，该命令会失败并显示 `fatal: --unshallow on a complete repository does not make sense`。4006* **您传入的基础分支不在您的克隆中**：Claude Code 在比较之前从 origin 获取了该分支。提示内容为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上该命令会失败并显示 `fatal: --unshallow on a complete repository does not make sense`。

3964 4007 

3965**解决方法：**4008**解决方法：**

3966 4009 

63* **客户端遥测**：当会话登录到 Claude 应用网关时，Claude Code 会禁用其 Anthropic 绑定的客户端分析。要在登录前启动分析也保持关闭，请在每个设备上的 [客户端托管设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#client-side-managed-settings) 中提供 [`DISABLE_TELEMETRY`](https://code.claude.com/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization)。63* **客户端遥测**：当会话登录到 Claude 应用网关时，Claude Code 会禁用其 Anthropic 绑定的客户端分析。要在登录前启动分析也保持关闭，请在每个设备上的 [客户端托管设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#client-side-managed-settings) 中提供 [`DISABLE_TELEMETRY`](https://code.claude.com/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization)。

64* **其他网关上的客户端遥测**：Claude Code 是否发送可选的客户端遥测流取决于您的提供商，[遥测默认值表](https://code.claude.com/docs/zh-CN/data-usage.md#default-behaviors-by-api-provider) 涵盖每种情况。64* **其他网关上的客户端遥测**：Claude Code 是否发送可选的客户端遥测流取决于您的提供商，[遥测默认值表](https://code.claude.com/docs/zh-CN/data-usage.md#default-behaviors-by-api-provider) 涵盖每种情况。

65* **遥测目标**：Claude Code 发送网关会话遥测的位置取决于会话如何登录，[开发人员上强制执行的内容](https://code.claude.com/docs/zh-CN/claude-apps-gateway#whats-enforced-on-developers) 说明每种会话的导出去向。65* **遥测目标**：Claude Code 发送网关会话遥测的位置取决于会话如何登录，[开发人员上强制执行的内容](https://code.claude.com/docs/zh-CN/claude-apps-gateway#whats-enforced-on-developers) 说明每种会话的导出去向。

66* **企业 HTTP 代理**：`HTTPS_PROXY` 位于 Claude Code 和它与之通信的每个服务器之间，包括网关。如果您的网络需要一个，[配置代理](https://code.claude.com/docs/zh-CN/network-config.md) 以及网关。对于您托管的 Claude 应用网关，[登录检查代理主机也在私有网络上](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites)；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接到它。66* **企业 HTTP 代理**：Claude Code 通过 `HTTPS_PROXY` 中的代理发送其请求，包括发往网关的请求。如果您的网络需要代理，请[配置代理](https://code.claude.com/docs/zh-CN/network-config.md)。如果该代理适用于您托管的 Claude 应用网关，[登录](https://code.claude.com/docs/zh-CN/claude-apps-gateway#prerequisites)要求代理的主机名解析为私有地址，或者要求将网关主机添加到 `NO_PROXY` 中。

67 67 

68## Next steps68## Next steps

69 69 

83>83>

84> 创建一个 Microsoft Entra 应用程序，其中包含您的存储库的联合凭证，遵循 [Microsoft 的 GitHub Actions 身份验证指南](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect)：84> 创建一个 Microsoft Entra 应用程序，其中包含您的存储库的联合凭证，遵循 [Microsoft 的 GitHub Actions 身份验证指南](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect)：

85>85>

86> * 注册一个 Microsoft Entra 应用程序，并添加一个联合身份凭证，该凭证信任 GitHub 向您的存储库颁发的令牌。用户分配的托管身份可以代替应用程序。两者都有您在下面记下的客户端 ID86> * 注册一个 Microsoft Entra 应用程序，并添加一个联合身份凭据，该凭据信任 GitHub 向您的仓库颁发的令牌。用户分配的托管身份可以代替应用程序。两者都有您在下面记下的客户端 ID

87> * 在您的 Foundry 资源上为应用程序分配 `Azure AI User` 角色。有关更窄的自定义角色，请参阅 [Azure RBAC 配置](https://code.claude.com/docs/zh-CN/microsoft-foundry.md#azure-rbac-configuration)87> * 在您的 Foundry 资源上为应用程序分配 `Foundry User` 角色。有关另一个内置角色和自定义角色，请参阅 [Azure RBAC 配置](https://code.claude.com/docs/zh-CN/microsoft-foundry.md#azure-rbac-configuration)

88>88>

89> 记下应用程序的客户端 ID、您的租户 ID 和您的订阅 ID。您将在下一步中将它们添加为密钥。89> 记下应用程序的客户端 ID、您的租户 ID 和您的订阅 ID。您将在下一步中将它们添加为密钥。

90 90 

228 228 

229### 当模型在会话中途被禁用时229### 当模型在会话中途被禁用时

230 230 

231如果您的项目失去对会话正在运行的模型的访问权限，例如因为管理员在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中禁用了它，Claude Code 会将会话切换到另一个模型，而不是让每个请求都失败，并显示 `Switched to <fallback> because <model> is not available`。它尝试与启动回退相同的模型：首先尝试同一层级的早期版本，对于没有可用 Opus 版本的 Opus 会话，则使用默认 Sonnet 模型。231当 Agent Platform 以会话模型在您的项目或区域中不可用为由拒绝该模型时，Claude Code 会将您的会话切换到另一个模型，您可以继续工作。您会看到一条以 `Switched to <fallback> because <model> is not available` 开头的消息。例如，当管理员在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中禁用该模型，或者该模型在您的区域中不提供服务时，就会发生这种情况。

232 232 

233切换仅适用于您未固定的层级，这与启动回退的条件相同。在您选择的特定版本上的会话保持其模型，没有回退模型链，请求会失败。在 [auto mode](https://code.claude.com/docs/zh-CN/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) 中，Claude Code 仅切换到 auto mode 在 Agent Platform 上支持的模型。如果这些模型都不可用，请求会失败。233如果您配置了[备用模型链](https://code.claude.com/docs/zh-CN/model-config.md#fallback-model-chains)，Claude Code 会改为切换到您配置的备用模型。如果没有配置模型链，请求会在以下情况下失败：

234 234 

235您配置的[回退模型链](https://code.claude.com/docs/zh-CN/model-config.md#fallback-model-chains)会替换层级切换：在这些拒绝上，Claude Code 会切换到您配置的回退。要使被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-CN/env-vars)。您配置的回退链仍会在这些拒绝上切换；如果您希望每个被拒绝的请求都失败，也要移除该链。235* 您的会话使用的是固定模型或您选择的特定版本

236* [Claude Code 尝试的模型](#startup-model-checks)均不可用。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)下，Claude Code 仅切换到自动模式在 Agent Platform 上支持的模型。

237 

238要继续工作，请在会话中运行 `/model`，并在您的项目和区域中可用的模型上按 `s`，这样不会更改您的默认模型。

239 

240要让被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-CN/env-vars)。如果您配置了备用模型链，也请将其移除，因为 Claude Code 仍会切换到该备用模型。

236 241 

237## IAM 配置242## IAM 配置

238 243 

2999 2999 

3000在会话期间配置文件发生更改时运行。可用于审计设置更改、强制执行安全策略，或阻止对配置文件的未授权修改。3000在会话期间配置文件发生更改时运行。可用于审计设置更改、强制执行安全策略，或阻止对配置文件的未授权修改。

3001 3001 

3002当设置文件、托管策略文件或 skill 文件发生更改时，Claude Code 会运行 ConfigChange hook。对于托管策略，仅当 `managed-settings.json` 或 `managed-settings.d/` 中的文件发生更改时才会运行。Claude Code 在应用[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)以及 macOS 托管偏好设置或 Windows 注册表策略的更改时不会运行这些 hook。在启用了 [`wslInheritsWindowsSettings`](https://code.claude.com/docs/zh-CN/settings-reference#wslinheritswindowssettings) 的 WSL 上，它在策略轮询时应用已更改的 Windows 端托管设置文件，同样不会运行这些 hook。3002当设置文件、托管策略文件或 skill 文件发生变更时，Claude Code 会运行 ConfigChange hook。对于托管策略，仅当 `managed-settings.json` 或 `managed-settings.d/` 中的文件发生变更时才会运行。

3003 3003 

3004匹配器按配置来源进行过滤：3004匹配器按配置来源进行过滤：

3005 3005 

3011| `policy_settings` | `managed-settings.json` 或 `managed-settings.d/` 中的文件发生更改 |3011| `policy_settings` | `managed-settings.json` 或 `managed-settings.d/` 中的文件发生更改 |

3012| `skills` | `.claude/skills/` 中的 skill 文件发生更改 |3012| `skills` | `.claude/skills/` 中的 skill 文件发生更改 |

3013 3013 

3014此示例记录所有配置更改，用于安全审计：3014以下这类更改无需运行 hook 即可生效：

3015 

3016* 通过 **Yes, and don't ask again**、`/permissions` 或 `/model` 保存的规则和设置，仅限于保存它们的那个会话。如果另一个打开的会话加载了同一文件，hook 会在该会话中运行。

3017* [服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)、macOS 托管偏好设置或 Windows 注册表策略的更新

3018* 在启用了 [`wslInheritsWindowsSettings`](https://code.claude.com/docs/zh-CN/settings-reference#wslinheritswindowssettings) 的 WSL 上，Windows 端托管设置文件发生的更改，Claude Code 会在其策略轮询中获取该更改

3019 

3020以下示例记录配置更改以进行安全审计：

3015 3021 

3016```json theme={null}3022```json theme={null}

3017{3023{

3334 "hooks": [3340 "hooks": [

3335 {3341 {

3336 "type": "command",3342 "type": "command",

3337 "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"3343 "command": "bash -c 'p=$(jq -er .worktree_path) && rm -rf -- \"$p\"'"

3338 }3344 }

3339 ]3345 ]

3340 }3346 }

50 "PostToolUse": [50 "PostToolUse": [

51 {51 {

52 "matcher": "Edit|Write",52 "matcher": "Edit|Write",

53 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]53 "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }]

54 }54 }

55 ],55 ],

56 "Notification": [56 "Notification": [

221 "hooks": [221 "hooks": [

222 {222 {

223 "type": "command",223 "type": "command",

224 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"224 "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""

225 }225 }

226 ]226 ]

227 }227 }

336 336 

337跟踪会话期间设置文件或 skill 文件何时发生变更。当外部进程或编辑器修改配置文件时，会触发 `ConfigChange` 事件，因此您可以记录变更以满足合规要求，或阻止未经授权的修改。337跟踪会话期间设置文件或 skill 文件何时发生变更。当外部进程或编辑器修改配置文件时，会触发 `ConfigChange` 事件，因此您可以记录变更以满足合规要求，或阻止未经授权的修改。

338 338 

339此示例将每次变更追加到审计日志中。将以下内容添加到 `~/.claude/settings.json`：339此示例将每个事件追加到审计日志中。将以下内容添加到 `~/.claude/settings.json`：

340 340 

341```json theme={null}341```json theme={null}

342{342{

36| `Esc` | 中断 Claude 或关闭对话框 | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止所做的工作。如果您有[排队的消息](#queue-messages-while-claude-works)，Claude Code 会在下一步发送它们。当对话框打开时，`Esc` 会关闭对话框。当选中页脚项目时，例如提示下方的[子代理面板](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)中的一行，`Esc` 会[取消选择它](https://code.claude.com/docs/zh-CN/keybindings.md#footer-actions)而不是中断。在权限提示上，`Esc` 会拒绝该操作，与[**否**不带注释](https://code.claude.com/docs/zh-CN/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)相同 |36| `Esc` | 中断 Claude 或关闭对话框 | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止所做的工作。如果您有[排队的消息](#queue-messages-while-claude-works)，Claude Code 会在下一步发送它们。当对话框打开时，`Esc` 会关闭对话框。当选中页脚项目时，例如提示下方的[子代理面板](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)中的一行，`Esc` 会[取消选择它](https://code.claude.com/docs/zh-CN/keybindings.md#footer-actions)而不是中断。在权限提示上，`Esc` 会拒绝该操作，与[**否**不带注释](https://code.claude.com/docs/zh-CN/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)相同 |

37| `Esc` + `Esc` | 清除输入草稿或回退 | 当提示输入包含文本时，双 `Esc` 会清除它并将草稿保存到历史记录，以便 `Up` 可以调用它。当输入为空时，双 `Esc` 会打开[回退菜单](https://code.claude.com/docs/zh-CN/checkpointing.md)以从之前的某个点恢复或总结代码和对话 |37| `Esc` + `Esc` | 清除输入草稿或回退 | 当提示输入包含文本时，双 `Esc` 会清除它并将草稿保存到历史记录，以便 `Up` 可以调用它。当输入为空时，双 `Esc` 会打开[回退菜单](https://code.claude.com/docs/zh-CN/checkpointing.md)以从之前的某个点恢复或总结代码和对话 |

38| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |38| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |

39| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环通过 `default`（在模式指示器中标记为 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions` 然后 `auto`。从 `auto`，第一次按下切换到 `default`。请参阅[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)。在文件权限提示上，相同的键会关闭打开的[注释字段](https://code.claude.com/docs/zh-CN/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，它会选择允许该操作在会话其余部分的选项，当提示提供该选项时 |39| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环切换 `default`（在模式指示器中标记为 Manual）、`acceptEdits` 和 `plan`，然后在可用时切换到 `bypassPermissions` 和 `auto`。请参阅[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)。在文件权限提示上，相同的键会关闭打开的[注释字段](https://code.claude.com/docs/zh-CN/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，当提示提供该选项时，它会选择在会话剩余时间内允许该操作的选项。在计划批准提示上，它会批准该计划 |

40| `Option+P`（macOS）或 `Alt+P`（Windows/Linux） | 切换模型 | 在不清除提示的情况下切换模型 |40| `Option+P`（macOS）或 `Alt+P`（Windows/Linux） | 切换模型 | 在不清除提示的情况下切换模型 |

41| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切换扩展思考 | 启用或禁用扩展思考模式。对 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型无效，它们始终使用扩展思考。在 macOS 上无需配置 Option 为 Meta 即可工作 |41| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切换扩展思考 | 启用或禁用扩展思考模式。对 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型无效，它们始终使用扩展思考。在 macOS 上无需配置 Option 为 Meta 即可工作 |

42| `Option+O`（macOS）或 `Alt+O`（Windows/Linux） | 切换快速模式 | 启用或禁用[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md) |42| `Option+O`（macOS）或 `Alt+O`（Windows/Linux） | 切换快速模式 | 启用或禁用[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md) |

81| :- | :- | :- |81| :- | :- | :- |

82| 快速转义 | `\` + `Enter` | 在所有终端中工作 |82| 快速转义 | `\` + `Enter` | 在所有终端中工作 |

83| Option 键 | `Option+Enter` | 在 macOS 上启用[Option 作为 Meta](https://code.claude.com/docs/zh-CN/terminal-config.md#enable-option-key-shortcuts-on-macos)后 |83| Option 键 | `Option+Enter` | 在 macOS 上启用[Option 作为 Meta](https://code.claude.com/docs/zh-CN/terminal-config.md#enable-option-key-shortcuts-on-macos)后 |

84| Shift+Enter | `Shift+Enter` | 在 iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 中原生支持。对于其他终端，请参阅[输入多行提示](https://code.claude.com/docs/zh-CN/terminal-config.md#enter-multiline-prompts) |84| Shift+Enter | `Shift+Enter` | 在 iTerm2、WezTerm、Ghostty、Kitty、Warp、Windows Terminal 中原生支持。对于其他终端，请参阅[输入多行提示](https://code.claude.com/docs/zh-CN/terminal-config.md#enter-multiline-prompts) |

85| 控制序列 | `Ctrl+J` | 在任何终端中无需配置即可工作 |85| 控制序列 | `Ctrl+J` | 在任何终端中无需配置即可工作 |

86| 粘贴模式 | 直接粘贴 | 对于代码块、日志 |86| 粘贴模式 | 直接粘贴 | 对于代码块、日志 |

87 87 

137 137 

138通过 `/config` → Editor mode 启用 vim 风格编辑。138通过 `/config` → Editor mode 启用 vim 风格编辑。

139 139 

140Claude Code 在你使用 `Ctrl+O` 切换[文字记录查看器](#transcript-viewer)或打开和关闭面板（如 `/config`）时保持你的 vim 模式和光标位置。如果你在 NORMAL 模式下离开提示符，当你返回时它仍然处于 NORMAL 模式，光标位置与你离开时相同。

141 

142### 模式切换140### 模式切换

143 141 

144| 命令 | 操作 | 来自模式 |142| 命令 | 操作 | 来自模式 |

302 * 按 `Ctrl+C` 取消并恢复你的原始输入300 * 按 `Ctrl+C` 取消并恢复你的原始输入

303 * 在空搜索上按 `Backspace` 取消301 * 在空搜索上按 `Backspace` 取消

304 302 

305接受匹配项或取消搜索立即生效，即使 Claude Code 仍在加载历史记录。

306 

307如果您只记得之前某个提示词中粘贴过的一段较长内容（例如错误日志），要找到该提示词，请按 `Ctrl+R` 并输入该粘贴内容中的某个词。需要 Claude Code v2.1.314 或更高版本。303如果您只记得之前某个提示词中粘贴过的一段较长内容（例如错误日志），要找到该提示词，请按 `Ctrl+R` 并输入该粘贴内容中的某个词。需要 Claude Code v2.1.314 或更高版本。

308 304 

309## 后台 Bash 命令305## 后台 Bash 命令

600 596 

601### Claude Code 加下划线的内容597### Claude Code 加下划线的内容

602 598 

603在您暂停输入后不久，Claude Code 会为字典不知道的单词加下划线。它会将您仍在输入的单词单独留下，直到您越过它，并且它永远不会更改您的文本。它也会跳过看起来像代码的文本：599在您暂停输入后不久，Claude Code 会为字典不知道的单词加下划线。它会将您仍在输入的单词单独留下，直到您越过它。它也会跳过看起来像代码的文本：

604 600 

605* 命令，例如 `/help`、`@` 提及、URL、文件路径和标志，例如 `--verbose`601* 命令，例如 `/help`、`@` 提及、URL、文件路径和标志，例如 `--verbose`

606* 包含数字、下划线或第一个字母后的大写字母的单词，以及反引号中的文本602* 包含数字、下划线或第一个字母后的大写字母的单词，以及反引号中的文本

581 581 

582Claude Code 在 `ctrl+x` 前缀上按上下文绑定以下默认和弦：582Claude Code 在 `ctrl+x` 前缀上按上下文绑定以下默认和弦：

583 583 

584* `Chat`：`ctrl+x ctrl+k`、`ctrl+x ctrl+e`、`ctrl+x enter`、`ctrl+x ctrl+a`、`ctrl+x ctrl+s` 和 `ctrl+x tab`584* `Chat`：`ctrl+x ctrl+k`、`ctrl+x ctrl+e`、`ctrl+x enter`、`ctrl+x ctrl+a`、`ctrl+x ctrl+s`、`ctrl+x tab`、`ctrl+x ctrl+=`、`ctrl+x ctrl+-`、`ctrl+x ctrl+_`、`ctrl+x =` 和 `ctrl+x -`

585* `Task`：`ctrl+x ctrl+b`585* `Task`：`ctrl+x ctrl+b`

586* `DiffPanel`：`ctrl+x b`586* `DiffPanel`：`ctrl+x b`

587* `Pane`：`ctrl+x left`、`ctrl+x right`、`ctrl+x up`、`ctrl+x down` 和 `ctrl+x x`587* `Pane`：`ctrl+x left`、`ctrl+x right`、`ctrl+x up`、`ctrl+x down` 和 `ctrl+x x`

631 "ctrl+x ctrl+a": null,631 "ctrl+x ctrl+a": null,

632 "ctrl+x ctrl+s": null,632 "ctrl+x ctrl+s": null,

633 "ctrl+x tab": null,633 "ctrl+x tab": null,

634 "ctrl+x ctrl+=": null,

635 "ctrl+x ctrl+-": null,

636 "ctrl+x ctrl+_": null,

637 "ctrl+x =": null,

638 "ctrl+x -": null,

634 "ctrl+x": "chat:newline"639 "ctrl+x": "chat:newline"

635 }640 }

636 }641 }

156 156 

157### 与现有登录的冲突157### 与现有登录的冲突

158 158 

159网关凭据变量优先于保存的 claude.ai 登录或 Console 密钥。使用 `ANTHROPIC_AUTH_TOKEN`，变量立即优先。使用 `ANTHROPIC_API_KEY`，在交互模式下提示您一次以批准密钥，然后它接管。159您的请求使用网关凭据变量，而不是保存的 claude.ai 登录。使用 `ANTHROPIC_AUTH_TOKEN` 时，该变量立即优先。使用 `ANTHROPIC_API_KEY` 时，在交互模式下会提示您一次以批准该密钥，之后它才会接管。

160 160 

161运行 `/status` 以确认哪个凭证源处于活动状态。如果启动显示命名两个源的身份验证冲突警告，请参阅[故障排除表](#troubleshoot-gateway-errors)的第一行，了解要删除哪一个。要清除保存的登录，以便仅保留网关凭证，请运行 `/logout`。161运行 `/status` 以确认哪个凭证源处于活动状态。如果启动显示命名两个源的身份验证冲突警告，请参阅[故障排除表](#troubleshoot-gateway-errors)的第一行，了解要删除哪一个。要清除保存的登录，以便仅保留网关凭证，请运行 `/logout`。

162 162 

506 506 

507| 错误 | 原因 | 修复 |507| 错误 | 原因 | 修复 |

508| :- | :- | :- |508| :- | :- | :- |

509| 启动警告命名两个凭证源并以 `auth may not work as expected` 结尾。较旧的版本显示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 网关凭证和保存的登录都处于活动状态；变量用于请求，但过时的登录可能导致意外的身份验证行为 | 取消设置变量以使用保存的登录，或运行 `/logout` 以使用网关凭证 |509| 启动警告命名两个凭据源并以 `auth may not work as expected` 结尾。较旧的版本显示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 网关凭据和保存的登录都处于活动状态 | 取消设置变量以使用保存的登录，或运行 `/logout` 以使用网关凭据 |

510| `401` 错误命名无效或无法识别的令牌 | 凭证不是网关颁发的，或它处于网关不读取的标头中 | 确认变量与[凭证表](#set-the-credential-variable)中的凭证类型匹配，如果凭证被撤销，请在网关处重新生成密钥 |510| `401` 错误命名无效或无法识别的令牌 | 凭证不是网关颁发的，或它处于网关不读取的标头中 | 确认变量与[凭证表](#set-the-credential-variable)中的凭证类型匹配，如果凭证被撤销，请在网关处重新生成密钥 |

511| `Your apiKeyHelper script is failing`，或在非交互模式下 stderr 上的 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper) 设置中的命令未生成可用的密钥，因此请求携带占位符密钥 | 直接运行该命令以查看失败原因，如果报告会话过期，请使用您的凭证提供商重新身份验证；请参阅[错误参考](https://code.claude.com/docs/zh-CN/errors.md#your-apikeyhelper-script-is-failing) |511| `Your apiKeyHelper script is failing`，或在非交互模式下 stderr 上的 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper) 设置中的命令未生成可用的密钥，因此请求携带占位符密钥 | 直接运行该命令以查看失败原因，如果报告会话过期，请使用您的凭证提供商重新身份验证；请参阅[错误参考](https://code.claude.com/docs/zh-CN/errors.md#your-apikeyhelper-script-is-failing) |

512| 当没有任何东西在地址处应答时 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`，或当主机名无法解析时 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`，通常在 Claude Code [使用退避重试](https://code.claude.com/docs/zh-CN/errors.md#automatic-retries)时的静默暂停之后。括号中的代码会变化；[Unable to connect to API](https://code.claude.com/docs/zh-CN/errors.md#unable-to-connect-to-api) 涵盖代码拼写和较早的措辞 | 没有任何东西在基础 URL 处应答：地址错误，或 VPN 或防火墙阻止了网关的路径 | 运行上面的 [curl 测试](#verify-the-connection)，它会立即因相同原因失败，并与您的网关团队确认 URL 和网络路径 |512| 当没有任何东西在地址处应答时 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`，或当主机名无法解析时 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`，通常在 Claude Code [使用退避重试](https://code.claude.com/docs/zh-CN/errors.md#automatic-retries)时的静默暂停之后。括号中的代码会变化；[Unable to connect to API](https://code.claude.com/docs/zh-CN/errors.md#unable-to-connect-to-api) 涵盖代码拼写和较早的措辞 | 没有任何东西在基础 URL 处应答：地址错误，或 VPN 或防火墙阻止了网关的路径 | 运行上面的 [curl 测试](#verify-the-connection)，它会立即因相同原因失败，并与您的网关团队确认 URL 和网络路径 |

520| `/fast` 报告 `Fast mode unavailable due to network connectivity issues`，而推理请求有效 | [快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)可用性检查直接转到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此阻止的直接出口会导致检查失败 | 如果出口被阻止，请将 `api.anthropic.com` 加入允许列表，或设置跳过变量。请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |520| `/fast` 报告 `Fast mode unavailable due to network connectivity issues`，而推理请求有效 | [快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)可用性检查直接转到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此阻止的直接出口会导致检查失败 | 如果出口被阻止，请将 `api.anthropic.com` 加入允许列表，或设置跳过变量。请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

521| `/fast` 在使用 `ANTHROPIC_API_KEY` 中网关颁发的密钥进行身份验证的会话中报告 `Fast mode is currently unavailable` | 当 `ANTHROPIC_BASE_URL` 指向您的网关且密钥不符合 Anthropic API 密钥的格式时，Claude Code 不会发送[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)可用性检查。在没有缓存先前成功检查结果的情况下，它会将快速模式视为不可用 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |521| `/fast` 在使用 `ANTHROPIC_API_KEY` 中网关颁发的密钥进行身份验证的会话中报告 `Fast mode is currently unavailable` | 当 `ANTHROPIC_BASE_URL` 指向您的网关且密钥不符合 Anthropic API 密钥的格式时，Claude Code 不会发送[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)可用性检查。在没有缓存先前成功检查结果的情况下，它会将快速模式视为不可用 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

522| `/fast` 在使用 `ANTHROPIC_AUTH_TOKEN` 进行身份验证的会话中报告 `Fast mode has been disabled by your organization`，即使组织已启用快速模式 | 可用性检查需要 claude.ai 登录或 API 密钥；仅使用持有者令牌，Claude Code 会将快速模式视为已禁用，而不发送检查 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |522| `/fast` 在使用 `ANTHROPIC_AUTH_TOKEN` 进行身份验证的会话中报告 `Fast mode has been disabled by your organization`，即使组织已启用快速模式 | 可用性检查需要 claude.ai 登录或 API 密钥；仅使用持有者令牌，Claude Code 会将快速模式视为已禁用，而不发送检查 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；请参阅[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

523| `/feedback` 在使用 `ANTHROPIC_BASE_URL` 的会话中保存本地文件 | 在网关后面，`ANTHROPIC_AUTH_TOKEN` 以及不符合 Anthropic API 密钥格式的密钥都不是 Anthropic 凭据。在没有此类凭据的情况下，Claude Code 会将报告写入 `~/.claude/feedback-bundles/` 下的本地归档，而不是发送它 | 将该文件发送给您的 Anthropic 客户代表，或将其附加到支持请求中。请参阅[遥测服务](https://code.claude.com/docs/zh-CN/data-usage.md#telemetry-services) |

523| Claude Code 要求您登录，即使 [curl 测试](#verify-the-connection)成功 | CLI 没有自己的凭证：可达的基础 URL 不是一个，在交互会话中，项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 块仅在首次运行向导和[信任提示](https://code.claude.com/docs/zh-CN/permissions.md#what-runs-before-you-trust-a-folder)之后应用 | 在 Claude Code 在首次运行设置之前读取的某处设置 `ANTHROPIC_AUTH_TOKEN`：shell 导出、`~/.claude/settings.json` 中的 `env` 块或托管设置 |524| Claude Code 要求您登录，即使 [curl 测试](#verify-the-connection)成功 | CLI 没有自己的凭证：可达的基础 URL 不是一个，在交互会话中，项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 块仅在首次运行向导和[信任提示](https://code.claude.com/docs/zh-CN/permissions.md#what-runs-before-you-trust-a-folder)之后应用 | 在 Claude Code 在首次运行设置之前读取的某处设置 `ANTHROPIC_AUTH_TOKEN`：shell 导出、`~/.claude/settings.json` 中的 `env` 块或托管设置 |

524| `ANTHROPIC_API_KEY` 已设置但被忽略，没有提示 | 密钥需要在交互会话中进行一次性批准，之前拒绝的密钥被忽略而不再询问 | 在 `/config` 下使用 `Use custom API key` 选项启用它 |525| `ANTHROPIC_API_KEY` 已设置但被忽略，没有提示 | 密钥需要在交互会话中进行一次性批准，之前拒绝的密钥被忽略而不再询问 | 在 `/config` 下使用 `Use custom API key` 选项启用它 |

525| `This machine's managed settings require a first-party login`，或当托管设置将 `forceLoginMethod` 设置为 `"gateway"` 或也设置 `forceLoginGatewayUrl` 时 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 托管设置包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能与 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理员必须从托管设置中删除 `forceLoginMethod`、`forceLoginOrgUUID` 和 `forceLoginGatewayUrl` 以使用网关凭证，或删除网关凭证以使用托管设置要求的登录。两者不能组合 |526| `This machine's managed settings require a first-party login`，或当托管设置将 `forceLoginMethod` 设置为 `"gateway"` 或也设置 `forceLoginGatewayUrl` 时 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 托管设置包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能与 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理员必须从托管设置中删除 `forceLoginMethod`、`forceLoginOrgUUID` 和 `forceLoginGatewayUrl` 以使用网关凭证，或删除网关凭证以使用托管设置要求的登录。两者不能组合 |

142claude -p "Reply with one word: connected"142claude -p "Reply with one word: connected"

143```143```

144 144 

145**检查点**：提示返回响应，请求在网关日志中显示为对 `/v1/messages` 路径的 `POST`，状态为 `200`。Claude Code 附加查询字符串，例如 `?beta=true`，因此匹配路径，而不是完整 URL。两条失败消息指向不同的方向：145**检查点**：提示词返回响应，请求在网关日志中显示为对 `/v1/messages` 路径的 `POST`，状态为 `200`。Claude Code 附加查询字符串，例如 `?beta=true`，因此匹配路径，而不是完整 URL。检查失败消息：

146 146 

147* `Not logged in`：检查网关日志以区分两个原因。如果它是空的，没有凭证到达会话，没有请求离开机器；在您测试的 shell 中重新运行导出。如果它显示在 `401` 正文中带有 `x-api-key` 的被拒绝请求，网关期望密钥在该标头中；切换到 `ANTHROPIC_API_KEY`147* `Not logged in`：检查网关日志。如果它是空的，没有凭据到达会话，也没有请求离开机器；在您测试的 shell 中重新运行导出。如果它显示来自网关且提及 `x-api-key` 的 `401`，说明网关期望密钥在该标头中；切换到 `ANTHROPIC_API_KEY`。如果它显示来自 `api.anthropic.com` 或您的提供商端点的 `401`，请修复网关持有的提供商凭据

148* `Failed to authenticate. API Error: 401` 意味着凭证被发送并被拒绝，网关日志说明了在哪里：命名 `api.anthropic.com` 或您的提供商端点的 `401` 意味着网关到达了上游但其提供商凭证被拒绝，因此开发者密钥有效，网关持有的提供商凭证错误或是占位符148* `Failed to authenticate. API Error: 401` 意味着凭证被发送并被拒绝，网关日志说明了在哪里：命名 `api.anthropic.com` 或您的提供商端点的 `401` 意味着网关到达了上游但其提供商凭证被拒绝，因此开发者密钥有效，网关持有的提供商凭证错误或是占位符

149 149 

150错误或无法到达的基础 URL 会产生不同的症状：Claude Code [以退避方式重试连接](https://code.claude.com/docs/zh-CN/errors.md#automatic-retries)，在报告错误之前可能会坐着没有输出几分钟。如果命令似乎挂起，请检查网关日志而不是等待；没有到达的请求意味着 `ANTHROPIC_BASE_URL` 不指向网关。150错误或无法到达的基础 URL 会产生不同的症状：Claude Code [以退避方式重试连接](https://code.claude.com/docs/zh-CN/errors.md#automatic-retries)，在报告错误之前可能会坐着没有输出几分钟。如果命令似乎挂起，请检查网关日志而不是等待；没有到达的请求意味着 `ANTHROPIC_BASE_URL` 不指向网关。

247 247 

248您应该看到 `data:` 行逐步到达。整个响应在暂停后一次到达意味着网关正在缓冲，这会停滞 Claude Code；`404` 意味着模型名称未路由。每个模型名称重复。248您应该看到 `data:` 行逐步到达。整个响应在暂停后一次到达意味着网关正在缓冲，这会停滞 Claude Code；`404` 意味着模型名称未路由。每个模型名称重复。

249 249 

250然后启动 `claude` 并发送消息。此步骤的每个症状都有一个原因：250然后启动 `claude`，发送消息，并对照您看到的情况：

251 251 

252* 登录提示意味着凭证缺口。运行 `/status` 并打开**状态**选项卡：当 `Setting sources` 行不包括托管设置时，分发没有到达机器；当它包括时，开发者凭证没有被交付，因此设置 `ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`252* 登录屏幕，或 `Not logged in` 且网关日志中没有新内容，意味着凭据缺口。运行 `/status` 并打开 **Status** 选项卡：当 `Setting sources` 行不包括托管设置时，分发没有到达机器；当它包括时，开发者凭据没有被交付，因此设置 `ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`

253* `Failed to authenticate` 错误意味着网关拒绝请求；其日志说明了哪个凭证失败。网关自己记录的拒绝命名开发者密钥，而来自 `api.anthropic.com` 或您的提供商端点的 `401` 意味着网关持有的提供商凭证被拒绝253* `Please run /login · API Error: 401`、`Not logged in` 或 `Invalid API key`，且网关日志中有 `401`：检查是谁返回了该 `401`。如果是网关返回的，请修复开发者密钥或其标头；如果它来自 `api.anthropic.com` 或您的提供商端点，请修复网关持有的提供商凭据

254* 当网关期望密钥在 `x-api-key` 标头中（设置为 `ANTHROPIC_API_KEY`）时，首次使用时出现针对该密钥的一次性批准提示是预期行为254* 当网关期望密钥在 `x-api-key` 标头中（设置为 `ANTHROPIC_API_KEY`）时，首次使用时出现针对该密钥的一次性批准提示是预期行为

255 255 

256如果您的组织使用[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)，也在这里运行 `/fast`：可用性检查直接调用 `api.anthropic.com` 而不是遵循网关基础 URL，因此网关路由的会话可以报告快速模式不可用或禁用，即使推理有效。[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)将每条消息映射到恢复它的变量，与[配置的其余部分](#distribute-the-configuration)一起分发。256如果您的组织使用[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)，也在这里运行 `/fast`：可用性检查直接调用 `api.anthropic.com` 而不是遵循网关基础 URL，因此网关路由的会话可以报告快速模式不可用或禁用，即使推理有效。[在代理和 LLM 网关后面使用快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)将每条消息映射到恢复它的变量，与[配置的其余部分](#distribute-the-configuration)一起分发。

147 147 

148## Azure RBAC 配置148## Azure RBAC 配置

149 149 

150`Azure AI User` 和 `Cognitive Services User` 默认角色包括调用 Claude 模型所需的所有权限。150如果您使用 Microsoft Entra ID 或其颁发的 bearer 令牌进行身份验证，请在您的 Foundry 资源上为您的身份分配 `Foundry User` 或 `Cognitive Services User` 角色。您可能仍会看到 `Foundry User` 以其旧名称 `Azure AI User` 显示。

151 151 

152对于更严格的权限，请创建具有以下内容的自定义角色：152如果这些角色无法满足您的需求，请参阅 [Microsoft Foundry RBAC 文档](https://learn.microsoft.com/en-us/azure/foundry/concepts/rbac-foundry)了解自定义角色。

153 

154```json theme={null}

155{

156 "permissions": [

157 {

158 "dataActions": [

159 "Microsoft.CognitiveServices/accounts/providers/*"

160 ]

161 }

162 ]

163}

164```

165 

166有关详情，请参阅 [Microsoft Foundry RBAC 文档](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)。

167 153 

168## 1M token 上下文窗口154## 1M token 上下文窗口

169 155 

157 157 

158当启动时的活动模型来自项目或托管设置而不是您自己的选择时，启动标题会显示是哪个设置文件设置了它。运行 `/model` 可覆盖；项目或托管设置会在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表仍然有效，除非主机提供自己的允许列表；[Exceptions to managed settings precedence](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence) 说明主机会覆盖哪些键和变量。158当启动时的活动模型来自项目或托管设置而不是您自己的选择时，启动标题会显示是哪个设置文件设置了它。运行 `/model` 可覆盖；项目或托管设置会在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表仍然有效，除非主机提供自己的允许列表；[Exceptions to managed settings precedence](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence) 说明主机会覆盖哪些键和变量。

159 159 

160如果您或您的组织配置了 [PreModelSwitch hook](https://code.claude.com/docs/zh-CN/hooks.md#premodelswitch)，它们会在请求的切换生效之前运行，并可以阻止切换或要求您确认。160如果您或您的组织配置了 [PreModelSwitch hook](https://code.claude.com/docs/zh-CN/hooks.md#premodelswitch)，它们会在请求的切换生效之前运行，并可以阻止切换或要求您确认。要了解 hook 阻止切换的原因以及应如何处理，请参阅 [Model switch was blocked by a PreModelSwitch hook](https://code.claude.com/docs/zh-CN/errors.md#model-switch-was-blocked-by-a-premodelswitch-hook)。

161 161 

162当 Claude Code 无法判断您组织的[托管插件](https://code.claude.com/docs/zh-CN/settings-reference.md#enabledplugins)提供了哪些 PreModelSwitch hook 时（例如因为某个托管插件加载失败），它会拒绝切换而不是在未经检查的情况下应用，并在每次新尝试时再次检查。有关消息和恢复方法，请参阅 [Model switch was blocked by a PreModelSwitch hook](https://code.claude.com/docs/zh-CN/errors.md#model-switch-was-blocked-by-a-premodelswitch-hook)。162如果某个[托管插件](https://code.claude.com/docs/zh-CN/settings-reference.md#enabledplugins)或其 hook 加载失败，您仍然可以切换模型。该插件的 PreModelSwitch hook 不会运行，因此原本会被其中某个 hook 阻止的切换可以继续进行。其他已加载的 PreModelSwitch hook 仍会运行，并可以阻止切换。如果 v2.1.323 之前的 Claude Code 以 `so organization-managed PreModelSwitch hooks could not be checked` 拒绝切换，请更新 Claude Code。

163 

164要查看失败的内容，请在会话中运行 `/plugin` 并打开 [**Errors** 选项卡](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#failed-to-load-hooks-from-and-hooks-that-dont-fire)。如果其中没有列出任何内容，请从 shell 使用 `claude --debug` 启动新会话并切换到其他模型，然后阅读[调试日志](https://code.claude.com/docs/zh-CN/hooks.md#debug-hooks)。在您修复插件后，或者[插件更新](https://code.claude.com/docs/zh-CN/plugins/install.md#keep-plugins-updated)将管理员的修复带到您的计算机上后，请在会话中运行 `/reload-plugins` 以使其 hook 运行。

163 165 

164当您通过 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 的 `setModel()` 方法、通过应用（如 [Desktop app](https://code.claude.com/docs/zh-CN/desktop.md)）或从通过 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 连接的设备切换模型时，Claude Code 会在切换时检查该值：166当您通过 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 的 `setModel()` 方法、通过应用（如 [Desktop app](https://code.claude.com/docs/zh-CN/desktop.md)）或从通过 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 连接的设备切换模型时，Claude Code 会在切换时检查该值：

165 167 

903 905 

904### 为网关或自定义模型 ID 更正窗口906### 为网关或自定义模型 ID 更正窗口

905 907 

906以下任一启动警告都表示 Claude Code 无法识别您会话的模型 ID，因此无法得知该模型的上下文窗口，并假设其为 200K token：908以下任一警告都表示 Claude Code 无法识别您会话的模型 ID，因此无法得知该模型的上下文窗口，并假设其为 200K token：

907 909 

908```text theme={null}910```text theme={null}

909⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...911⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...

431> * **不允许空格**：值不能包含空格。例如，`user.organizationName=My Company` 无效431> * **不允许空格**：值不能包含空格。例如，`user.organizationName=My Company` 无效

432> * **格式**：必须是逗号分隔的键=值对：`key1=value1,key2=value2`432> * **格式**：必须是逗号分隔的键=值对：`key1=value1,key2=value2`

433> * **允许的字符**：仅限 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠433> * **允许的字符**：仅限 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠

434> * **特殊字符**：允许范围之外的字符必须进行百分比编码434> * **特殊字符**：允许范围之外的字符必须进行百分比编码，值中的 `=` 必须写为 `%3D`

435>435>

436> 对于需要空格的值，请改用下划线或 camelCase。以下示例使用每种形式设置 `org.name`：436> 对于需要空格的值，请改用下划线或 camelCase。以下示例使用每种形式设置 `org.name`：

437>437>

304claude --permission-mode plan304claude --permission-mode plan

305```305```

306 306 

307再次按 `Shift+Tab` 可在不批准计划的情况下退出计划模式。307在没有打开批准提示时，再次按 `Shift+Tab` 可退出计划模式。在批准提示中，请先按 `Esc`，因为在该提示中按 `Shift+Tab` 会批准计划。

308 308 

309### 审阅并批准计划309### 审阅并批准计划

310 310 

344 "PostToolUse": [344 "PostToolUse": [

345 {345 {

346 "matcher": "Write|Edit",346 "matcher": "Write|Edit",

347 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]347 "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npm run lint:fix -- \"$f\"" }]

348 }348 }

349 ]349 ]

350 }350 }

196 196 

197### 使用 `expect` 检查结果197### 使用 `expect` 检查结果

198 198 

199工具包提供以下断言，所选的断言跟在您要检查的值之后，例如 `expect(answer.text).toBe('ok')`：199`expect` 有自己的一组断言，例如 `toEqual` 和 `toHaveLength`，它们跟在您要检查的值之后，例如 `expect(answer.text).toBe('ok')`。如需完整列表，请在[您的构建版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)中的 `claude-code/index.d.ts` 里搜索 `type Matchers`。在断言前加上 `.not` 可检查相反的情况。要检查 promise 最终兑现或拒绝的结果，请紧接在 `expect(...)` 之后加上 `.resolves` 或 `.rejects`，并对该行使用 `await`，例如 `await expect(promise).rejects.toThrow()`。

200 

201* **相等性**：`toBe` 用于相同的值或对象，`toEqual` 用于结构，`toStrictEqual` 用于结构以及 `undefined` 字段和原型，`toMatchObject` 用于您指定的字段

202* **文本**：`toMatch`（接受正则表达式或子字符串）、`toStartWith` 和 `toEndWith`

203* **数字**：`toBeGreaterThan`、`toBeGreaterThanOrEqual`、`toBeLessThan`、`toBeLessThanOrEqual`

204* **内容**：`toContain` 用于子字符串或成员，`toContainEqual` 用于按结构比较的成员，以及 `toHaveLength` 和 `toHaveProperty`

205* **存在性和类型**：`toBeDefined`、`toBeUndefined`、`toBeNull`、`toBeTruthy`、`toBeFalsy`、`toBeNaN`、`toBeInstanceOf`

206* **抛出**：`toThrow`，用于由 `expect` 调用的函数，或用于您通过 `.rejects` 检查的 promise

207 

208在断言前加上 `.not` 可检查相反的情况，加上 `.resolves` 或 `.rejects` 可检查 promise 最终兑现或拒绝的结果。

209 200 

210当 `expect` 在您以普通函数（而非异步生成器）形式传给 `on` 的 stub 或 hook 中失败时，测试会失败。引擎会跳过该 hook，失败输出会指出其名称，例如 `in the test's store.set hook`。201当 `expect` 在您以普通函数（而非异步生成器）形式传给 `on` 的 stub 或 hook 中失败时，测试会失败。引擎会跳过该 hook，失败输出会指出其名称，例如 `in the test's store.set hook`。

211 202 

67> | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |67> | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |

68> | `--[no-]create-session-in-dir` | 服务器启动时在当前目录中预先创建一个会话，以便您可以立即开始输入。在 `worktree` 模式下，此会话保留在当前目录中，而按需创建的会话则获得独立的 worktree。默认开启。如果您传入 `--no-create-session-in-dir` 以不带任何会话启动，Claude Code 会在您停止服务器时归档服务器的会话，因此将没有可[恢复](#resume-sessions-after-stopping-the-server)的会话。 |68> | `--[no-]create-session-in-dir` | 服务器启动时在当前目录中预先创建一个会话，以便您可以立即开始输入。在 `worktree` 模式下，此会话保留在当前目录中，而按需创建的会话则获得独立的 worktree。默认开启。如果您传入 `--no-create-session-in-dir` 以不带任何会话启动，Claude Code 会在您停止服务器时归档服务器的会话，因此将没有可[恢复](#resume-sessions-after-stopping-the-server)的会话。 |

69> | `--permission-mode <mode>` | 为服务器的会话设置初始[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)，例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名；无法识别的模式会使服务器在启动时停止并列出有效模式。 |69> | `--permission-mode <mode>` | 为服务器的会话设置初始[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)，例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名；无法识别的模式会使服务器在启动时停止并列出有效模式。 |

70> | `--settings <file>` | 将 JSON 设置文件应用于服务器的会话，其[优先级](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence)与 `claude --settings` 相同。请提供文件路径，而不是 JSON 字符串。需要 Claude Code v2.1.321 或更高版本。 |

70> | `--chrome` / `--no-chrome` | 在服务器创建的会话中打开或关闭 [Chrome 集成](https://code.claude.com/docs/zh-CN/chrome.md)，以便您在另一台设备上工作时 Claude 可以使用您机器上的 Chrome。如果不带任一标志，服务器预先创建的会话以及您自己从 claude.ai/code 或 Claude 应用启动的任何会话都会以关闭 Chrome 的状态开始，即使您已[默认启用 Chrome](https://code.claude.com/docs/zh-CN/chrome.md#enable-chrome-by-default)。服务器为您的某个[项目](https://code.claude.com/docs/zh-CN/claude-projects.md)线程启动的会话则遵循该设置，但 `bypassPermissions` 模式除外。需要 Claude Code v2.1.273 或更高版本。 |71> | `--chrome` / `--no-chrome` | 在服务器创建的会话中打开或关闭 [Chrome 集成](https://code.claude.com/docs/zh-CN/chrome.md)，以便您在另一台设备上工作时 Claude 可以使用您机器上的 Chrome。如果不带任一标志，服务器预先创建的会话以及您自己从 claude.ai/code 或 Claude 应用启动的任何会话都会以关闭 Chrome 的状态开始，即使您已[默认启用 Chrome](https://code.claude.com/docs/zh-CN/chrome.md#enable-chrome-by-default)。服务器为您的某个[项目](https://code.claude.com/docs/zh-CN/claude-projects.md)线程启动的会话则遵循该设置，但 `bypassPermissions` 模式除外。需要 Claude Code v2.1.273 或更高版本。 |

71> | `-d`, `--debug[=<filter>]` | 为服务器开启调试日志，可选择按类别过滤。只能以 `=` 形式传入过滤器，例如 `--debug=api,hooks`。需要 Claude Code v2.1.282 或更高版本。 |72> | `-d`, `--debug[=<filter>]` | 为服务器开启调试日志，可选择按类别过滤。只能以 `=` 形式传入过滤器，例如 `--debug=api,hooks`。需要 Claude Code v2.1.282 或更高版本。 |

72> | `--debug-file <path>` | 将调试日志写入指定文件。 |73> | `--debug-file <path>` | 将调试日志写入指定文件。 |

73> | `--verbose` | 显示详细的连接和会话日志。 |74> | `--verbose` | 显示详细的连接和会话日志。 |

74> | `--sandbox`, `--no-sandbox` | 已在 v2.1.300 中移除。如果您传入任一标志，服务器会[报错退出](https://code.claude.com/docs/zh-CN/errors.md#sandbox-is-not-supported-by-claude-remote-control)，而不是启动。 |75> | `--sandbox`, `--no-sandbox` | 已在 v2.1.300 中移除。如果您传入任一标志，服务器会[报错退出](https://code.claude.com/docs/zh-CN/errors.md#sandbox-is-not-supported-by-claude-remote-control)，而不是启动。 |

75>76>

76> 如果您在 `remote-control` 之前传入全局 `claude` 标志，或者包装脚本添加了此类标志，Claude Code 不会将该标志传递给服务器创建的会话。只有在确知丢弃该标志不会改变这些会话的能力时，Claude Code 才会放行该标志，例如 `--verbose` 或 `--model`。对于任何其他标志，例如 `--settings`，Claude Code 会[拒绝启动](https://code.claude.com/docs/zh-CN/errors.md#not-carried-over-to-the-sessions-remote-control-starts)并指出需要移除的标志。77> 如果您在 `remote-control` 之前传入全局 `claude` 标志，或者包装脚本添加了此类标志，Claude Code 不会将该标志传递给服务器创建的会话。对于某些标志，例如 `--verbose` 或 `--model`，服务器仍会启动。对于任何其他标志，服务器[不会启动](https://code.claude.com/docs/zh-CN/errors.md#not-carried-over-to-the-sessions-remote-control-starts)。要传入设置文件，请将 `--settings` 放在 `remote-control` 之后。

77>78>

78> 要对服务器启动的会话进行沙箱隔离，请在设置文件中开启[沙箱隔离](https://code.claude.com/docs/zh-CN/sandboxing.md)。79> 要对服务器启动的会话进行沙箱隔离，请在设置文件中开启[沙箱隔离](https://code.claude.com/docs/zh-CN/sandboxing.md)。

79>80>

431 431 

432每个定时任务都使用一个[云环境](https://code.claude.com/docs/zh-CN/cloud-environments.md)，用于控制网络访问、环境变量和设置脚本。任务在每次运行时都会继承该环境的网络策略。432每个定时任务都使用一个[云环境](https://code.claude.com/docs/zh-CN/cloud-environments.md)，用于控制网络访问、环境变量和设置脚本。任务在每次运行时都会继承该环境的网络策略。

433 433 

434**Default** 环境使用 **Limited** 访问并勾选了 **Allow package managers**，因此其运行可以访问[默认允许列表](https://code.claude.com/docs/zh-CN/cloud-environments.md#default-allowed-domains)中的主机。向被阻止的主机发出的请求会失败，并返回 `403` 和 `x-deny-reason: host_not_allowed`。MCP 连接器流量通过 Anthropic 的服务器路由，因此您添加到任务中的连接器无需将其主机添加到 **Allowed domains** 即可正常工作。请在[连接器](#connectors)下移除您不需要的任何连接器。434**Default** 环境使用 **Limited** 访问并勾选了 **Allow package managers**，因此其运行可以访问[默认允许列表](https://code.claude.com/docs/zh-CN/cloud-environments.md#default-allowed-domains)中的主机。向被阻止的主机发出的请求会失败，并返回[诸如 `403` 或 `ENOTFOUND` 之类的错误](https://code.claude.com/docs/zh-CN/errors#host-not-allowed-in-a-cloud-session)。MCP 连接器流量通过 Anthropic 的服务器路由，因此您添加到任务中的连接器无需将其主机添加到 **Allowed domains** 即可正常工作。请在[连接器](#connectors)下移除您不需要的任何连接器。

435 435 

436要在您自己的某个环境中允许更多域名，请按照以下步骤操作。[组织共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)在此处以只读方式打开，因此需要由 Owner 在[管理设置](https://claude.ai/admin-settings)的 **Cloud environments** 页面中更改其网络访问。436要在您自己的某个环境中允许更多域名，请按照以下步骤操作。[组织共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)在此处以只读方式打开，因此需要由 Owner 在[管理设置](https://claude.ai/admin-settings)的 **Cloud environments** 页面中更改其网络访问。

437 437 

276 276 

277这些路径在操作系统层面强制执行，因此在沙箱内运行的所有命令（包括其子进程）都会遵守这些限制。当某个工具需要对特定位置的写入权限时，推荐使用这种方法，而不是使用 `excludedCommands` 将该工具完全排除在沙箱之外。277这些路径在操作系统层面强制执行，因此在沙箱内运行的所有命令（包括其子进程）都会遵守这些限制。当某个工具需要对特定位置的写入权限时，推荐使用这种方法，而不是使用 `excludedCommands` 将该工具完全排除在沙箱之外。

278 278 

279在 Linux 和 WSL2 上，针对尚不存在的路径的条目不会生效，因此请先创建该路径。

280 

279当您在多个[设置作用域](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence)中定义同一个文件系统数组时，Claude Code 会将它们合并，组合来自每个作用域的路径，而不是用一个作用域的数组替换另一个作用域的数组。当某个条目受到[防止开发者放宽策略](#keep-developers-from-widening-the-policy)中的锁定约束时，Claude Code 会将该条目排除在合并之外。281当您在多个[设置作用域](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence)中定义同一个文件系统数组时，Claude Code 会将它们合并，组合来自每个作用域的路径，而不是用一个作用域的数组替换另一个作用域的数组。当某个条目受到[防止开发者放宽策略](#keep-developers-from-widening-the-policy)中的锁定约束时，Claude Code 会将该条目排除在合并之外。

280 282 

281如果您在 CLI 上使用 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference) 或在 Agent SDK 中使用 [`settingSources`](https://code.claude.com/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 排除了某个来源，Claude Code 在构建沙箱配置时会忽略该来源的 `sandbox.filesystem` 条目、`Edit` 权限规则以及 `Read` 拒绝规则。需要 Claude Code v2.1.246 或更高版本。283如果您在 CLI 上使用 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference) 或在 Agent SDK 中使用 [`settingSources`](https://code.claude.com/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 排除了某个来源，Claude Code 在构建沙箱配置时会忽略该来源的 `sandbox.filesystem` 条目、`Edit` 权限规则以及 `Read` 拒绝规则。需要 Claude Code v2.1.246 或更高版本。

376 378 

377由于关闭文件系统隔离会扩大沙箱命令的能力范围，Claude Code 仅接受来自以下设置来源的 `filesystem.disabled`：379由于关闭文件系统隔离会扩大沙箱命令的能力范围，Claude Code 仅接受来自以下设置来源的 `filesystem.disabled`：

378 380 

379* 用户设置、托管设置和 `--settings` CLI 标志可以设置它。`.claude/settings.json` 和 `.claude/settings.local.json` 中的项目设置不能设置它，因此检出的项目无法关闭文件系统隔离。381* 用户设置、托管设置和 `--settings` CLI 标志可以设置它。`.claude/settings.json` 和 `.claude/settings.local.json` 中的项目设置不能设置它。

380* 当托管设置配置了任何 `sandbox.filesystem` 内容，或列出了任何 `"mode": "deny"` 的 `sandbox.credentials.files` 条目时，只有托管设置可以设置该键。这可防止开发者在此类部署中关闭文件系统隔离；要为所有人关闭它，请在托管设置中设置 `"disabled": true`。382* 当托管设置配置了任何 `sandbox.filesystem` 内容，或列出了任何 `"mode": "deny"` 的 `sandbox.credentials.files` 条目时，只有托管设置可以设置该键。要为所有人关闭文件系统隔离，请在托管设置中设置 `"disabled": true`。

381* 当设置了 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/zh-CN/env-vars) 时，Claude Code 会忽略来自所有来源（包括托管设置）的 `filesystem.disabled`，并保持文件系统隔离开启。383* 当设置了 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/zh-CN/env-vars) 时，Claude Code 会忽略来自所有来源（包括托管设置）的 `filesystem.disabled`。

382 384 

383[有效的](https://code.claude.com/docs/zh-CN/settings-reference.md#invalid-credential-entries-in-managed-settings) `mask` 条目不会锁定该键，即使 Claude Code 在启动时对其[回退为 `deny`](#mask-credential-files) 也是如此。请将无法掩码的路径（例如凭据目录）在托管设置中列为显式的 `deny` 条目，这样会锁定该键。385[有效的](https://code.claude.com/docs/zh-CN/settings-reference.md#invalid-credential-entries-in-managed-settings) `mask` 条目不会锁定该键，即使 Claude Code 在启动时对其[回退为 `deny`](#mask-credential-files) 也是如此。请将无法掩码的路径（例如凭据目录）在托管设置中列为显式的 `deny` 条目，这样会锁定该键。

384 386 

177 177 

178Claude Code 监视您的设置文件并在它们更改时重新加载它们，因此它在运行的会话中应用大多数编辑而不需要重启，包括对 `permissions`、`hooks` 和凭证助手（如 `apiKeyHelper`）的编辑。Claude Code 也在会话中期加载您创建的设置文件，如果其文件夹在会话启动时存在。对于项目的 `.claude/` 文件夹，即使您在同一会话中创建文件夹，它也加载文件。178Claude Code 监视您的设置文件并在它们更改时重新加载它们，因此它在运行的会话中应用大多数编辑而不需要重启，包括对 `permissions`、`hooks` 和凭证助手（如 `apiKeyHelper`）的编辑。Claude Code 也在会话中期加载您创建的设置文件，如果其文件夹在会话启动时存在。对于项目的 `.claude/` 文件夹，即使您在同一会话中创建文件夹，它也加载文件。

179 179 

180重新加载涵盖用户、项目、本地和托管设置，Claude Code 为每个它检测到的设置文件更改运行 [`ConfigChange` hook](https://code.claude.com/docs/zh-CN/hooks#configchange)，而不是来自 MDM 或 claude.ai 控制台的托管设置。来自 MDM 或 claude.ai 控制台的托管设置按计划而不是保存时到达运行的会话；[传递表](https://code.claude.com/docs/zh-CN/managed-settings.md#choose-a-delivery-mechanism)给出每个来源的。180重新加载涵盖用户、项目、本地和托管设置。Claude Code 会针对设置文件的直接编辑运行 [`ConfigChange` hook](https://code.claude.com/docs/zh-CN/hooks#configchange)，而不会针对来自 MDM 或 claude.ai 控制台的托管设置运行。通过 MDM 或来自 claude.ai 控制台的托管设置按计划而不是保存时到达运行的会话；[传递表](https://code.claude.com/docs/zh-CN/managed-settings.md#choose-a-delivery-mechanism)给出每个来源的情况。

181 181 

182Claude Code 仅在会话启动时读取某些键一次，因此对其中一个的编辑不会到达运行的会话。也等待重启的管理员端键，如 `requiredMinimumVersion`，在[策略适用的位置和时间](https://code.claude.com/docs/zh-CN/managed-settings.md#where-and-when-a-policy-applies)下列出。您最可能在会话中期编辑的：182Claude Code 仅在会话启动时读取某些键一次，因此对其中一个的编辑不会到达运行的会话。也等待重启的管理员端键，如 `requiredMinimumVersion`，在[策略适用的位置和时间](https://code.claude.com/docs/zh-CN/managed-settings.md#where-and-when-a-policy-applies)下列出。您最可能在会话中期编辑的：

183 183 

1533}1533}

1534```1534```

1535 1535 

1536在 Linux 和 WSL2 上，针对尚不存在的路径的条目不会生效，因此请先创建该路径。

1537 

1536Claude Code 会在会话加载的各设置作用域之间合并 `allowWrite` 条目以及来自您的 `Edit(...)` 允许权限规则的路径，当 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 启用时，会排除来自仓库设置的条目。[仓库锁定](https://code.claude.com/docs/zh-CN/sandboxing.md#repository-settings-under-an-admin-required-sandbox)也可能排除仓库的条目。`allowWrite` 条目无法解除[受保护路径](https://code.claude.com/docs/zh-CN/sandboxing.md#protected-paths)的保护。1538Claude Code 会在会话加载的各设置作用域之间合并 `allowWrite` 条目以及来自您的 `Edit(...)` 允许权限规则的路径，当 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 启用时，会排除来自仓库设置的条目。[仓库锁定](https://code.claude.com/docs/zh-CN/sandboxing.md#repository-settings-under-an-admin-required-sandbox)也可能排除仓库的条目。`allowWrite` 条目无法解除[受保护路径](https://code.claude.com/docs/zh-CN/sandboxing.md#protected-paths)的保护。

1537 1539 

1538### `sandbox.filesystem.denyWrite`1540### `sandbox.filesystem.denyWrite`

40>40>

41> **macOS、Linux、WSL：**41> **macOS、Linux、WSL：**

42>42>

43> ```bash theme={null}43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell：**49> **Windows PowerShell：**

50>50>

51> ```powershell theme={null}51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD：**55> **Windows CMD：**

56>56>

57> ```batch theme={null}57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72 

73> [tab] Homebrew73> [tab] Homebrew

74>74>

75> ```bash theme={null}75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84 

85> [tab] WinGet85> [tab] WinGet

86>86>

87> ```powershell theme={null}87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

141 141 

142### Alpine Linux 和基于 musl 的发行版142### Alpine Linux 和基于 musl 的发行版

143 143 

144在 Alpine 和其他 musl/uClibc 基础发行版上安装 Claude Code 需要 `bash` 和 `curl` 用于安装命令，以及 `libgcc`、`libstdc++` 和 `ripgrep` 用于运行时。Alpine 默认不包含 `bash` 或 `curl`，因此在您安装它们之前，文档中的安装命令会失败并显示 `not found` 错误。使用您的发行版的包管理器安装这些包，然后设置 `USE_BUILTIN_RIPGREP=0`。144在 Alpine 和其他基于 musl 的发行版上，[安装命令](#install-claude-code)需要 `bash` 和 `curl`，而 Claude Code 本身需要 `bash` 或 `zsh`。Alpine 默认不包含 `bash` 或 `curl`，因此在您安装它们之前，文档中的安装命令会失败并显示 `not found` 错误。

145 145 

146此示例在 Alpine 上安装所需的包：146此示例在 Alpine 上安装所需的包：

147 147 

148```bash theme={null}148```bash theme={null}

149apk add bash curl libgcc libstdc++ ripgrep149apk add bash curl

150```

151 

152在 Alpine 上，`ripgrep` 位于社区存储库中。如果 `apk` 报告该包缺失，请将社区存储库添加到 `/etc/apk/repositories`，使用您的 Alpine 版本：

153 

154```bash theme={null}

155echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositories

156```

157 

158运行 `apk update` 以刷新包索引，然后重试 `apk add` 命令。

159 

160然后在您的 [`settings.json`](https://code.claude.com/docs/zh-CN/settings-reference#all-settings) 文件中将 `USE_BUILTIN_RIPGREP` 设置为 `0`：

161 

162```json theme={null}

163{

164 "env": {

165 "USE_BUILTIN_RIPGREP": "0"

166 }

167}

168```150```

169 151 

170## 验证您的安装152## 验证您的安装

443> wget -O /etc/apk/keys/claude-code.rsa.pub \425> wget -O /etc/apk/keys/claude-code.rsa.pub \

444> https://downloads.claude.ai/keys/claude-code.rsa.pub426> https://downloads.claude.ai/keys/claude-code.rsa.pub

445> echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories427> echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories

446> apk add claude-code428> apk add bash claude-code

447> ```429> ```

448>430>

449> 要切换到 `latest` 渠道，删除 `stable` 存储库行并添加 `latest` 存储库：431> 要切换到 `latest` 渠道，删除 `stable` 存储库行并添加 `latest` 存储库：

26 26 

27| 终端 | Shift+Enter 换行 |27| 终端 | Shift+Enter 换行 |

28| :- | :- |28| :- | :- |

29| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal | 无需设置即可工作 |29| Ghostty、Kitty、iTerm2、WezTerm、Warp、Windows Terminal | 无需设置即可工作 |

30| 支持 kitty 键盘协议的其他终端，例如 foot 和 Alacritty 0.16 或更高版本 | 无需设置即可工作。需要 Claude Code v2.1.269 或更高版本 |30| 支持 kitty 键盘协议的其他终端，例如 foot 和 Alacritty 0.16 或更高版本 | 无需设置即可工作。需要 Claude Code v2.1.269 或更高版本 |

31| VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前版本、Zed | 运行一次 `/terminal-setup` |31| VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前版本、Zed | 运行一次 `/terminal-setup` |

32| gnome-terminal、JetBrains IDE（如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然后 Enter |32| gnome-terminal、JetBrains IDE（如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然后 Enter |

127 127 

128Claude 使用 `AskUserQuestion` 在需要决策或澄清时向您提出多选题。通过选择一个选项来回答，或通过 `Other` 行或备注字段输入您自己的文本。128Claude 使用 `AskUserQuestion` 在需要决策或澄清时向您提出多选题。通过选择一个选项来回答，或通过 `Other` 行或备注字段输入您自己的文本。

129 129 

130当您通过输入自己的文本来回答时，Claude Code 会用中立的措辞转达答案，以便 Claude 遵循您写的内容，包括等待或先解释的请求。

131 

132### 问题自动继续超时130### 问题自动继续超时

133 131 

134问题保持打开状态，直到您回答。如果您想让一个未回答的问题最终关闭并让 Claude 在没有您的情况下继续，请在您的用户 `settings.json` 中或从 `/config` 中的 **Question auto-continue timeout** 行设置 [`askUserQuestionTimeout`](https://code.claude.com/docs/zh-CN/settings-reference#askuserquestiontimeout) 为 `60s`、`5m` 或 `10m`。132问题保持打开状态，直到您回答。如果您想让一个未回答的问题最终关闭并让 Claude 在没有您的情况下继续，请在您的用户 `settings.json` 中或从 `/config` 中的 **Question auto-continue timeout** 行设置 [`askUserQuestionTimeout`](https://code.claude.com/docs/zh-CN/settings-reference#askuserquestiontimeout) 为 `60s`、`5m` 或 `10m`。

525 523 

526## Read 工具行为524## Read 工具行为

527 525 

528Read 工具接收文件路径并返回带有行号的文件内容。Claude 被指示始终传递绝对路径。526Read 工具接收文件路径并返回带有行号的文件内容。

529 527 

530读取空文件会返回一个通知，说明文件存在但内容为空，而 `offset` 超过最后一行会返回一个通知，给出文件的行数。528读取空文件会返回一个通知，说明文件存在但内容为空，而 `offset` 超过最后一行会返回一个通知，给出文件的行数。

531 529 

388> Get-Command claude | Select-Object Source388> Get-Command claude | Select-Object Source

389> ```389> ```

390 390 

391在 Linux 上，检查缺失的共享库。如果 `ldd` 显示缺失的库，您可能需要安装系统包。在 Alpine Linux 和其他基于 musl 的发行版上，请参阅 [Alpine Linux setup](https://code.claude.com/docs/zh-CN/setup.md#alpine-linux-and-musl-based-distributions)。391在 Linux 上，检查缺失的共享库。如果 `ldd` 显示缺失的库，您可能需要安装系统包。在 Alpine Linux 和其他基于 musl 的发行版上，请参阅 [Linux musl 或 glibc 二进制文件不匹配](#linux-musl-or-glibc-binary-mismatch)。

392 392 

393```bash theme={null}393```bash theme={null}

394ldd "$(command -v claude)" | grep "not found"394ldd "$(command -v claude)" | grep "not found"

906 906 

907### Linux musl 或 glibc 二进制不匹配907### Linux musl 或 glibc 二进制不匹配

908 908 

909如果在安装后看到有关缺失共享库的错误，例如 `libstdc++.so.6` 或 `libgcc_s.so.1`，安装程序可能为您的系统下载了错误的二进制变体。909如果在安装后看到有关缺失共享库的错误，例如 `ld-linux-x86-64.so.2` 或 `ld-linux-aarch64.so.1`，安装程序可能为您的系统下载了错误的二进制变体。

910 910 

911```text theme={null}911```text theme={null}

912Error loading shared library libstdc++.so.6: No such file or directory912Error loading shared library ld-linux-x86-64.so.2: No such file or directory

913```913```

914 914 

915这可能发生在安装了 musl 交叉编译包的基于 glibc 的系统上，导致安装程序将系统误检测为 musl。

916 

917**解决方案：**915**解决方案：**

918 916 

9191. **检查您的系统使用哪个 libc**：9171. **检查您的系统使用哪个 libc**：

924 922 

9252. **如果您在 glibc 上但获得了 musl 二进制文件**，删除安装并重新安装。您也可以使用 `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json` 处的清单手动下载正确的二进制文件。使用 `ldd --version` 和 `ls /lib/libc.musl*` 的输出提交 [GitHub 问题](https://github.com/anthropics/claude-code/issues)。9232. **如果您在 glibc 上但获得了 musl 二进制文件**，删除安装并重新安装。您也可以使用 `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json` 处的清单手动下载正确的二进制文件。使用 `ldd --version` 和 `ls /lib/libc.musl*` 的输出提交 [GitHub 问题](https://github.com/anthropics/claude-code/issues)。

926 924 

9273. **如果您实际上在 musl 上**，例如 Alpine Linux，请安装所需的包：9253. **如果您在 musl 上但获得了 glibc 二进制文件**，请[删除安装](https://code.claude.com/docs/zh-CN/setup.md#uninstall-claude-code)。在 Alpine Linux 上，请先安装 [Alpine Linux 设置](https://code.claude.com/docs/zh-CN/setup.md#alpine-linux-and-musl-based-distributions)中列出的包。然后运行[安装命令](https://code.claude.com/docs/zh-CN/setup.md#install-claude-code)，它会安装 musl 二进制文件。

928 ```bash theme={null}

929 apk add libgcc libstdc++ ripgrep

930 ```

931 在 Alpine 上，`ripgrep` 在社区仓库中。如果 `apk` 报告包丢失，请参阅 [Alpine Linux 设置](https://code.claude.com/docs/zh-CN/setup.md#alpine-linux-and-musl-based-distributions)。

932 926 

933### `Illegal instruction`927### `Illegal instruction`

934 928 

152> apk add ripgrep152> apk add ripgrep

153> ```153> ```

154>154>

155> `ripgrep` 在 Alpine 的社区存储库中。如果 `apk` 报告包缺失，请参阅 [Alpine Linux 设置](https://code.claude.com/docs/zh-CN/setup.md#alpine-linux-and-musl-based-distributions)。155> `ripgrep` 位于 Alpine 的 community 仓库中。

156 156 

157> [tab] Arch157> [tab] Arch

158>158>

75| :- | :- |75| :- | :- |

76| `/deep-research <question>` | 在多个角度上扇出网络搜索问题，获取并交叉检查它找到的来源，对每个声明投票，并返回一份引用的报告，其中未通过交叉检查的声明已被过滤掉。需要[WebSearch 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#websearch-tool-behavior)可用 |76| `/deep-research <question>` | 在多个角度上扇出网络搜索问题，获取并交叉检查它找到的来源，对每个声明投票，并返回一份引用的报告，其中未通过交叉检查的声明已被过滤掉。需要[WebSearch 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#websearch-tool-behavior)可用 |

77 77 

78`/deep-research` 仅在您调用它时运行。

79 

80[您自己保存的工作流](#save-the-workflow-for-reuse)以相同方式成为命令，并在 `/` 自动完成中与捆绑的工作流一起出现。78[您自己保存的工作流](#save-the-workflow-for-reuse)以相同方式成为命令，并在 `/` 自动完成中与捆绑的工作流一起出现。

81 79 

82### 观看运行80### 观看运行