10 10
11## 登录 Claude Code11## 登录 Claude Code
12 12
13[安装 Claude Code](/docs/zh-CN/setup#install-claude-code) 后,在终端中运行 `claude`。首次启动时,Claude Code 会打开浏览器窗口供您登录。如果您已设置 `ANTHROPIC_API_KEY` 环境变量,并在 Claude Code 询问是否使用该密钥时批准了它,Claude Code 会跳过登录提示。13[安装 Claude Code](/docs/zh-CN/setup.md#install-claude-code) 后,在终端中运行 `claude`。首次启动时,Claude Code 会打开浏览器窗口供您登录,但在以下情况下,它可以跳过登录提示:
14
15* **API 密钥**:您已设置 `ANTHROPIC_API_KEY` 环境变量,并在 Claude Code 询问是否使用该密钥时批准了它
16* **之前已登录**:您在首次会话之前已在 shell 中运行过 [`claude auth login`](/docs/zh-CN/cli-reference#cli-commands),或者您重建了一个将凭据保存在 [卷](/docs/zh-CN/devcontainer.md#persist-authentication-and-settings-across-rebuilds) 中的开发容器。如果仍然看到登录提示,请 [查看可能的原因](#login-prompt-still-appears-after-an-earlier-sign-in)。
14 17
15如果浏览器没有自动打开,请按 `c` 将登录 URL 复制到剪贴板,然后将其粘贴到浏览器中。18如果浏览器没有自动打开,请按 `c` 将登录 URL 复制到剪贴板,然后将其粘贴到浏览器中。
16 19
23* **Claude Pro 或 Max 订阅**:使用您的 claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。26* **Claude Pro 或 Max 订阅**:使用您的 claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。
24* **Claude for Teams 或 Enterprise**:使用您的团队管理员邀请您的 claude.ai 账户登录。27* **Claude for Teams 或 Enterprise**:使用您的团队管理员邀请您的 claude.ai 账户登录。
25* **Claude Console**:使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。您可以在有或没有 [创建 API 密钥](#sign-in-without-an-api-key) 的情况下登录。28* **Claude Console**:使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。您可以在有或没有 [创建 API 密钥](#sign-in-without-an-api-key) 的情况下登录。
26* **云提供商**:如果您的组织使用 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry),请在运行 `claude` 之前设置所需的环境变量,或在登录提示符处选择 **3rd-party platform**,这将为 Bedrock 和 Vertex AI 启动交互式设置向导。不需要浏览器登录。29* **云提供商**:如果您的组织使用 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock.md)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai.md) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry.md),请在运行 `claude` 之前设置所需的环境变量,或在登录提示符处选择 **3rd-party platform**,这将为 Bedrock 和 Vertex AI 启动交互式设置向导。不需要浏览器登录。
27* **云网关**:如果您的组织运行自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway),请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。30* **云网关**:如果您的组织运行自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway),请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。
28 31
29管理员可以指导开发人员使用哪种登录方法,并要求 claude.ai 登录属于特定组织;请参阅 [限制登录到您的组织](#restrict-login-to-your-organization)。32管理员可以指导开发人员使用哪种登录方法,并要求 claude.ai 登录属于特定组织;请参阅 [限制登录到您的组织](#restrict-login-to-your-organization)。
30 33
31要登出并重新身份验证,请在 Claude Code 提示符处输入 `/logout`。登出还会重置您的首次启动设置状态,因此下次运行 `claude` 时,它会再次引导您完成登录和设置。34要登出并重新身份验证,请在 Claude Code 提示符处输入 `/logout`。登出还会重置您的首次启动设置状态,因此下次运行 `claude` 时,它会再次引导您完成登录和设置。
32 35
33如果您在登录时遇到问题,请参阅 [身份验证故障排除](/docs/zh-CN/troubleshoot-install#login-and-authentication)。36如果您在登录时遇到问题,请参阅 [身份验证故障排除](/docs/zh-CN/troubleshoot-install.md#login-and-authentication)。
37
38### 之前已登录但仍出现登录提示
39
40如果您之前已登录,但首次启动设置仍显示登录提示而没有 [跳过它](#log-in-to-claude-code),请检查以下可能的原因:
41
42* **登录已过期**:您之前的登录已过期,且 Claude Code 无法刷新它。请在提示处重新登录。
43* **登录仅限于特定组织**:管理员在托管设置中设置了 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid),以 [要求使用特定组织的账户登录](#restrict-login-to-your-organization)。无论您的账户是否属于这些组织之一,都会出现该提示。请使用属于所要求组织的账户登录。如果您没有这样的账户,请联系管理员将您添加进去。
44* **要求特定登录方法**:您的登录类型不符合设置文件中 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的要求。设置为 `"claudeai"` 时,之前通过 Claude Console 登录获得的 API 密钥不算作已有登录。设置为 `"console"` 时,claude.ai 账户不算作已有登录。请使用该设置所指定类型的账户登录。
45* **旧版本**:在 v2.1.290 之前,无论您是否已登录,设置过程中都会出现该提示。[更新 Claude Code](/docs/zh-CN/setup.md#update-claude-code) 即可跳过它。
34 46
35### 使用多个账户登录47### 使用多个账户登录
36 48
49* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise),推荐用于大多数团队61* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise),推荐用于大多数团队
50* [Claude Console](#claude-console-authentication)62* [Claude Console](#claude-console-authentication)
51* [Claude apps gateway](/docs/zh-CN/claude-apps-gateway),一个自托管网关,使用您的 IdP 为开发人员签名,并将推理路由到您配置的云提供商63* [Claude apps gateway](/docs/zh-CN/claude-apps-gateway),一个自托管网关,使用您的 IdP 为开发人员签名,并将推理路由到您配置的云提供商
52* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)64* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock.md)
53* [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai)65* [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai.md)
54* [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)66* [Microsoft Foundry](/docs/zh-CN/microsoft-foundry.md)
55 67
56### Claude for Teams 或 Enterprise68### Claude for Teams 或 Enterprise
57 69
58[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) 为使用 Claude Code 的组织提供最佳体验。团队成员可以访问 Claude Code 和网络版 Claude,具有集中式计费和团队管理。70[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) 为使用 Claude Code 的组织提供最佳体验。团队成员可以访问 Claude Code 和网络版 Claude,具有集中式计费和团队管理。
59 71
60* **Claude for Teams**:自助服务计划,具有协作功能、管理工具、SSO、计费管理和 [服务器托管设置](/docs/zh-CN/server-managed-settings),用于组织范围的 Claude Code 配置。最适合较小的团队。72* **Claude for Teams**:自助服务计划,具有协作功能、管理工具、SSO、计费管理和 [服务器托管设置](/docs/zh-CN/server-managed-settings.md),用于组织范围的 Claude Code 配置。最适合较小的团队。
61* **Claude for Enterprise**:添加域名捕获、基于角色的权限和合规性 API。最适合具有安全和合规性要求的大型组织。73* **Claude for Enterprise**:添加域名捕获、基于角色的权限和合规性 API。最适合具有安全和合规性要求的大型组织。
62 74
63**1. 订阅**75**1. 订阅**
99每个受邀用户需要:111每个受邀用户需要:
100 112
101* 接受 Console 邀请113* 接受 Console 邀请
102* [检查系统要求](/docs/zh-CN/setup#system-requirements)114* [检查系统要求](/docs/zh-CN/setup.md#system-requirements)
103* [安装 Claude Code](/docs/zh-CN/setup#install-claude-code)115* [安装 Claude Code](/docs/zh-CN/setup.md#install-claude-code)
104* 使用 Console 账户凭据登录116* 使用 Console 账户凭据登录
105 117
106#### 无需 API 密钥登录118#### 无需 API 密钥登录
110* **使用您的 Console 账户登录**,标记为 `(recommended)`:Claude Code 保留该登录的 OAuth 令牌,并将其存储为 [Anthropic 配置文件](#anthropic-profiles-and-federation-credentials)。它不创建 API 密钥122* **使用您的 Console 账户登录**,标记为 `(recommended)`:Claude Code 保留该登录的 OAuth 令牌,并将其存储为 [Anthropic 配置文件](#anthropic-profiles-and-federation-credentials)。它不创建 API 密钥
111* **创建 API 密钥**,标记为 `(legacy)`:Claude Code 为您创建 Console API 密钥,并将其与您的其他凭证一起存储123* **创建 API 密钥**,标记为 `(legacy)`:Claude Code 为您创建 Console API 密钥,并将其与您的其他凭证一起存储
112 124
113实际上,配置文件存储的是 OAuth 登录,而 API 密钥是静态凭据。Claude Code 会自动刷新配置文件的登录;刷新失败时,请求会失败并显示 [配置文件登录已过期错误](/docs/zh-CN/errors#anthropic-profile-login-expired),直到您再次登录。125实际上,配置文件存储的是 OAuth 登录,而 API 密钥是静态凭据。Claude Code 会自动刷新配置文件的登录;刷新失败时,请求会失败并显示 [配置文件登录已过期错误](/docs/zh-CN/errors.md#anthropic-profile-login-expired),直到您再次登录。
114 126
115您不会在每台机器上都获得选择。Claude Code 在以下情况下会在不询问的情况下创建 API 密钥:127您不会在每台机器上都获得选择。Claude Code 在以下情况下会在不询问的情况下创建 API 密钥:
116 128
117* 您针对云提供商运行,例如 [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](/docs/zh-CN/third-party-integrations) 或 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)129* 您针对云提供商运行,例如 [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](/docs/zh-CN/third-party-integrations.md) 或 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws.md)
118* 任何设置文件设置 [`forceLoginOrgUUID`](#restrict-login-to-your-organization),或将 `forceLoginMethod` 设置为 `"claudeai"` 或 `"console"`130* 任何设置文件设置 [`forceLoginOrgUUID`](#restrict-login-to-your-organization),或将 `forceLoginMethod` 设置为 `"claudeai"` 或 `"console"`
119* 您机器上存在托管设置源(例如托管设置文件、MDM 配置文件或缓存的服务器托管设置),但 Claude Code [无法读取它](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings),且没有其他托管源提供策略131* 您机器上存在托管设置源(例如托管设置文件、MDM 配置文件或缓存的服务器托管设置),但 Claude Code [无法读取它](/docs/zh-CN/managed-settings.md#invalid-entries-in-managed-settings),且没有其他托管源提供策略
120 132
121在无密钥登录之前取消设置 `ANTHROPIC_API_KEY`。133在无密钥登录之前取消设置 `ANTHROPIC_API_KEY`。
122 134
134 146
135**1. 遵循提供商设置**147**1. 遵循提供商设置**
136 148
137遵循 [Amazon Bedrock 文档](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform 文档](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry 文档](/docs/zh-CN/microsoft-foundry)。149遵循 [Amazon Bedrock 文档](/docs/zh-CN/amazon-bedrock.md)、[Google Cloud's Agent Platform 文档](/docs/zh-CN/google-vertex-ai.md) 或 [Microsoft Foundry 文档](/docs/zh-CN/microsoft-foundry.md)。
138 150
139**2. 分发配置**151**2. 分发配置**
140 152
141将环境变量和生成云凭证的说明分发给您的用户。阅读有关如何 [在此处管理配置](/docs/zh-CN/settings) 的更多信息。153将环境变量和生成云凭证的说明分发给您的用户。阅读有关如何 [在此处管理配置](/docs/zh-CN/settings.md) 的更多信息。
142 154
143**3. 安装 Claude Code**155**3. 安装 Claude Code**
144 156
145用户可以 [安装 Claude Code](/docs/zh-CN/setup#install-claude-code)。157用户可以 [安装 Claude Code](/docs/zh-CN/setup.md#install-claude-code)。
146 158
147### 限制登录到您的组织159### 限制登录到您的组织
148 160
149要求开发人员的 claude.ai 登录属于特定的 Anthropic 组织,请在 [托管设置](/docs/zh-CN/managed-settings) 中设置 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。将 `forceLoginOrgUUID` 设置为您的组织 ID,该 ID 显示在 [claude.ai 管理员设置](https://claude.ai/admin-settings/organization) 中,适用于 Claude for Teams 或 Enterprise 组织。Claude Code 会为任何其他组织的 claude.ai 登录报告错误,如果使用中的 claude.ai 凭证属于未列出的组织,则在启动时退出。161要求开发人员的 claude.ai 登录属于特定的 Anthropic 组织,请在 [托管设置](/docs/zh-CN/managed-settings.md) 中设置 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。将 `forceLoginOrgUUID` 设置为您的组织 ID,该 ID 显示在 [claude.ai 管理员设置](https://claude.ai/admin-settings/organization) 中,适用于 Claude for Teams 或 Enterprise 组织。Claude Code 会为任何其他组织的 claude.ai 登录报告错误,如果使用中的 claude.ai 凭证属于未列出的组织,则在启动时退出。
150 162
151对于 Claude Console 登录,当您将其设置为单个 Console 组织 ID(显示在 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization))时,Claude Code 使用 `forceLoginOrgUUID` 在 Console 登录页面上预选组织。它不检查生成的 Console 凭证属于哪个组织,无论是在登录时还是在启动时。在您部署密钥之前使用 Console 账户登录的开发人员会保持登录状态,该保存的密钥在同时需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录的机器上被阻止,或在选择云提供商的会话中被阻止。163对于 Claude Console 登录,当您将其设置为单个 Console 组织 ID(显示在 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization))时,Claude Code 使用 `forceLoginOrgUUID` 在 Console 登录页面上预选组织。它不检查生成的 Console 凭证属于哪个组织,无论是在登录时还是在启动时。在您部署密钥之前使用 Console 账户登录的开发人员会保持登录状态,该保存的密钥在同时需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录的机器上被阻止,或在选择云提供商的会话中被阻止。
152 164
156 168
157这些路径在 `forceLoginOrgUUID` 上有所不同:169这些路径在 `forceLoginOrgUUID` 上有所不同:
158 170
159* **终端、[VS Code 扩展](/docs/zh-CN/vs-code) 和 Agent SDK 登录**:验证 claude.ai 账户登录的 `forceLoginOrgUUID`171* **终端、[VS Code 扩展](/docs/zh-CN/vs-code.md) 和 Agent SDK 登录**:验证 claude.ai 账户登录的 `forceLoginOrgUUID`
160* **`claude setup-token` 和 `/install-github-app`**:仅强制执行 `forceLoginMethod`,因此它们可以在不同的组织中铸造令牌172* **`claude setup-token` 和 `/install-github-app`**:仅强制执行 `forceLoginMethod`,因此它们可以在不同的组织中铸造令牌
161* **[网关](/docs/zh-CN/claude-apps-gateway) 登录**:由 `forceLoginMethod: "gateway"` 选择而不是受其限制,并且不针对 Anthropic 组织进行身份验证,因此 `forceLoginOrgUUID` 不适用;使用您的网关身份提供商来限制访问173* **[网关](/docs/zh-CN/claude-apps-gateway) 登录**:由 `forceLoginMethod: "gateway"` 选择而不是受其限制,并且不针对 Anthropic 组织进行身份验证,因此 `forceLoginOrgUUID` 不适用;使用您的网关身份提供商来限制访问
162 174
163通过您的设备管理工具部署密钥。[服务器托管设置](/docs/zh-CN/server-managed-settings) 仅到达已经通过您的组织身份验证的账户,因此它们无法重定向开发人员的首次登录。如果您的组织也分发服务器托管设置,请在两个地方设置密钥:托管设置源 [不合并](/docs/zh-CN/server-managed-settings#settings-precedence),缓存的服务器托管设置替换设备托管文件,除了几个 [按密钥例外](/docs/zh-CN/server-managed-settings#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在这些例外中,因此在两个地方都保留它们。175通过您的设备管理工具部署密钥。[服务器托管设置](/docs/zh-CN/server-managed-settings.md) 仅到达已经通过您的组织身份验证的账户,因此它们无法重定向开发人员的首次登录。如果您的组织也分发服务器托管设置,请在两个地方设置密钥:托管设置源 [不合并](/docs/zh-CN/server-managed-settings.md#settings-precedence),缓存的服务器托管设置替换设备托管文件,除了几个 [按密钥例外](/docs/zh-CN/server-managed-settings.md#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在这些例外中,因此在两个地方都保留它们。
164 176
165在 [网关](/docs/zh-CN/claude-apps-gateway) 部署中,也要将 `forceLoginMethod` 和 `forceLoginOrgUUID` 保留在 [网关提供的设置](/docs/zh-CN/claude-apps-gateway-config#managed) 之外。177在 [网关](/docs/zh-CN/claude-apps-gateway) 部署中,也要将 `forceLoginMethod` 和 `forceLoginOrgUUID` 保留在 [网关提供的设置](/docs/zh-CN/claude-apps-gateway-config.md#managed) 之外。
166 178
167这些密钥还决定不使用登录凭证的会话是否可以启动。有关完整行为,请参阅设置参考中的 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。179这些密钥还决定不使用登录凭证的会话是否可以启动。有关完整行为,请参阅设置参考中的 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。
168 180
169* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**:在启动时被阻止。在 `forceLoginOrgUUID` 下,无法验证环境凭证的组织成员身份,在 `forceLoginMethod` 下,凭证会代替所需的登录。当托管设置也需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录时,Claude Code 以相同方式阻止由早期 Claude Console 登录保存的 API 密钥。请参阅 [管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)181* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**:在启动时被阻止。在 `forceLoginOrgUUID` 下,无法验证环境凭证的组织成员身份,在 `forceLoginMethod` 下,凭证会代替所需的登录。当托管设置也需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录时,Claude Code 以相同方式阻止由早期 Claude Console 登录保存的 API 密钥。请参阅 [管理员策略需要云网关登录](/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)
170* **云提供商会话,例如 Amazon Bedrock**:仅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证,或由早期 Claude Console 登录保存的 API 密钥仍然存在于机器上时被阻止。删除它,会话就会启动。这些会话针对您的云提供商进行身份验证,其访问策略管理它们182* **云提供商会话,例如 Amazon Bedrock**:仅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证,或由早期 Claude Console 登录保存的 API 密钥仍然存在于机器上时被阻止。删除它,会话就会启动。这些会话针对您的云提供商进行身份验证,其访问策略管理它们
171* **[Anthropic 配置文件或联合凭证](#anthropic-profiles-and-federation-credentials)**:不被阻止,除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证,或由早期 Claude Console 登录保存的 API 密钥也存在于机器上。这些密钥不检查配置文件属于哪个组织183* **[Anthropic 配置文件或联合凭证](#anthropic-profiles-and-federation-credentials)**:不被阻止,除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证,或由早期 Claude Console 登录保存的 API 密钥也存在于机器上。这些密钥不检查配置文件属于哪个组织
172 184
173### 限制机器可能使用的 API 提供商185### 限制机器可能使用的 API 提供商
174 186
175[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 在 [托管设置](/docs/zh-CN/managed-settings) 中列出托管机器可能通过哪些服务访问 Claude,例如 Anthropic API、Amazon Bedrock 或 LLM 网关。它补充 `forceLoginMethod` 和 `forceLoginOrgUUID`,它们管理会话在与 Anthropic 通信时使用的账户。需要 Claude Code v2.1.285 或更高版本。187[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 在 [托管设置](/docs/zh-CN/managed-settings.md) 中列出托管机器可能通过哪些服务访问 Claude,例如 Anthropic API、Amazon Bedrock 或 LLM 网关。它补充 `forceLoginMethod` 和 `forceLoginOrgUUID`,它们管理会话在与 Anthropic 通信时使用的账户。需要 Claude Code v2.1.285 或更高版本。
176 188
177```json managed-settings.json theme={null}189```json managed-settings.json theme={null}
178{190{
182}194}
183```195```
184 196
185使用此文件,登录到您的 claude.ai 组织或为 Amazon Bedrock 配置的开发人员正常启动。为任何其他提供商设置的会话在启动时被拒绝,运行中切换到一个的会话在其下一个请求时被拒绝。[托管设置不允许此 API 提供商](/docs/zh-CN/errors#managed-settings-dont-allow-this-api-provider) 显示每条消息。197使用此文件,登录到您的 claude.ai 组织或为 Amazon Bedrock 配置的开发人员正常启动。为任何其他提供商设置的会话在启动时被拒绝,运行中切换到一个的会话在其下一个请求时被拒绝。[托管设置不允许此 API 提供商](/docs/zh-CN/errors.md#managed-settings-dont-allow-this-api-provider) 显示每条消息。
186 198
187* **允许 LLM 网关或代理**:列出 `"customEndpoint"` 并在同一源的托管 `env` 块中设置网关的 URL。[设置参考](/docs/zh-CN/settings-reference#allowedproviders) 列出每个值并说明哪些端点变量需要托管 `env` 引脚。199* **允许 LLM 网关或代理**:列出 `"customEndpoint"` 并在同一源的托管 `env` 块中设置网关的 URL。[设置参考](/docs/zh-CN/settings-reference.md#allowedproviders) 列出每个值并说明哪些端点变量需要托管 `env` 引脚。
188* **在托管机器上部署**:将列表放在承载您的其余策略的托管源中。条目的 [范围说明](/docs/zh-CN/settings-reference#allowedproviders) 说明服务器托管列表如何与其结合。200* **在托管机器上部署**:将列表放在承载您的其余策略的托管源中。条目的 [范围说明](/docs/zh-CN/settings-reference.md#allowedproviders) 说明服务器托管列表如何与其结合。
189* **仅服务器托管设置**:您仅在 [服务器托管设置](/docs/zh-CN/server-managed-settings) 中设置的列表仅到达获取您的组织设置的会话,因此将其视为您无法通过设备管理到达的机器的便利,而不是强制执行。[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability) 列出哪些会话获取它们。201* **仅服务器托管设置**:您仅在 [服务器托管设置](/docs/zh-CN/server-managed-settings.md) 中设置的列表仅到达获取您的组织设置的会话,因此将其视为您无法通过设备管理到达的机器的便利,而不是强制执行。[平台可用性](/docs/zh-CN/server-managed-settings.md#platform-availability) 列出哪些会话获取它们。
190 202
191## 凭证管理203## 凭证管理
192 204
193Claude Code 安全地管理您的身份验证凭证:205Claude Code 安全地管理您的身份验证凭证:
194 206
195* **存储位置**:207* **存储位置**:
196 * 在 macOS 上,凭证存储在加密的 macOS Keychain 中。当 Keychain 拒绝写入时,例如在 SSH 会话中被锁定时,Claude Code 会改为将您的登录存储在 `~/.claude/.credentials.json` 中,文件模式为 `0600`,这与它在 Linux 上使用的存储相同。使用 Console 登录创建 API 密钥的操作会失败,直到 Keychain 可写。要将您的登录移回 Keychain,请按照[恢复步骤](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)进行操作。208 * 在 macOS 上,凭证存储在加密的 macOS Keychain 中。当 Keychain 拒绝写入时,例如在 SSH 会话中被锁定时,Claude Code 会改为将您的登录存储在 `~/.claude/.credentials.json` 中,文件模式为 `0600`,这与它在 Linux 上使用的存储相同。使用 Console 登录创建 API 密钥的操作会失败,直到 Keychain 可写。要将您的登录移回 Keychain,请按照[恢复步骤](/docs/zh-CN/troubleshoot-install.md#not-logged-in-or-token-expired)进行操作。
197 * 在 Linux 上,凭证存储在 `~/.claude/.credentials.json` 中,文件模式为 `0600`。209 * 在 Linux 上,凭证存储在 `~/.claude/.credentials.json` 中,文件模式为 `0600`。
198 * 在 Windows 上,凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中,并继承您的用户配置文件目录的访问控制,默认情况下将文件限制为您的用户帐户。210 * 在 Windows 上,凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中,并继承您的用户配置文件目录的访问控制,默认情况下将文件限制为您的用户帐户。
199 * 如果您设置了 `CLAUDE_CONFIG_DIR` 环境变量,Claude Code 会将 `.credentials.json` 文件保存在该目录下,包括 macOS 回退写入的文件,并且还会将 macOS Keychain 条目绑定到该目录,因此使用不同 `CLAUDE_CONFIG_DIR` 的会话会读取不同的条目。211 * 如果您设置了 `CLAUDE_CONFIG_DIR` 环境变量,Claude Code 会将 `.credentials.json` 文件保存在该目录下,包括 macOS 回退写入的文件,并且还会将 macOS Keychain 条目绑定到该目录,因此使用不同 `CLAUDE_CONFIG_DIR` 的会话会读取不同的条目。
204* **缓慢助手通知**:如果 `apiKeyHelper` 返回密钥需要超过 10 秒,Claude Code 会在提示栏中显示警告通知,显示经过的时间。如果您经常看到此通知,请检查您的凭证脚本是否可以优化。216* **缓慢助手通知**:如果 `apiKeyHelper` 返回密钥需要超过 10 秒,Claude Code 会在提示栏中显示警告通知,显示经过的时间。如果您经常看到此通知,请检查您的凭证脚本是否可以优化。
205* **助手失败**:当脚本以错误退出、超时或不输出任何内容时,请求在三次尝试内失败,显示 [`Your apiKeyHelper script is failing`](/docs/zh-CN/errors#your-apikeyhelper-script-is-failing)。217* **助手失败**:当脚本以错误退出、超时或不输出任何内容时,请求在三次尝试内失败,显示 [`Your apiKeyHelper script is failing`](/docs/zh-CN/errors#your-apikeyhelper-script-is-failing)。
206 218
207`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面,包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量:它们使用 OAuth,除了运行[第三方推理配置](/docs/zh-CN/llm-gateway-connect#desktop-app)的桌面会话外,这些会话使用该配置的凭证进行身份验证。219`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面,包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量:它们使用 OAuth,除了运行[第三方推理配置](/docs/zh-CN/llm-gateway-connect.md#desktop-app)的桌面会话外,这些会话使用该配置的凭证进行身份验证。
208 220
209### 续期即将过期的登录221### 续期即将过期的登录
210 222
218 230
219该警告仅在 claude.ai 登录是活跃凭证时出现,而不是在云提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供凭证时出现。231该警告仅在 claude.ai 登录是活跃凭证时出现,而不是在云提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供凭证时出现。
220 232
221对于运行无人值守的会话,提前续期最为重要。在 [agent view 中的后台会话](/docs/zh-CN/agent-view)或 [Remote Control](/docs/zh-CN/remote-control) 会话一旦凭证过期,就会停止进行,并且在您再次登录之前无法恢复。233对于运行无人值守的会话,提前续期最为重要。在 [agent view 中的后台会话](/docs/zh-CN/agent-view.md)或 [Remote Control](/docs/zh-CN/remote-control.md) 会话一旦凭证过期,就会停止进行,并且在您再次登录之前无法恢复。
222 234
223### 身份验证优先级235### 身份验证优先级
224 236
225当存在多个凭证时,Claude Code 按以下顺序选择一个:237当存在多个凭证时,Claude Code 按以下顺序选择一个:
226 238
2271. 云提供商凭证,当设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 时。有关设置,请参阅[第三方集成](/docs/zh-CN/third-party-integrations)。2391. 云提供商凭证,当设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 时。有关设置,请参阅[第三方集成](/docs/zh-CN/third-party-integrations.md)。
2282. `ANTHROPIC_AUTH_TOKEN` 环境变量。作为 `Authorization: Bearer` 标头发送。当通过[LLM 网关或代理](/docs/zh-CN/llm-gateway)进行路由时使用此选项,该网关或代理使用持有者令牌而不是 Anthropic API 密钥进行身份验证。2402. `ANTHROPIC_AUTH_TOKEN` 环境变量。作为 `Authorization: Bearer` 标头发送。当通过[LLM 网关或代理](/docs/zh-CN/llm-gateway)进行路由时使用此选项,该网关或代理使用持有者令牌而不是 Anthropic API 密钥进行身份验证。
2293. `ANTHROPIC_API_KEY` 环境变量。作为 `X-Api-Key` 标头发送。用于直接 Anthropic API 访问,使用来自 [Claude Console](https://platform.claude.com) 的密钥。在交互模式下,系统会提示您一次批准或拒绝该密钥,您的选择会被记住。要稍后更改它,请使用 `/config` 中的"使用自定义 API 密钥"切换。该切换仅在 `ANTHROPIC_API_KEY` 在您的环境中设置时出现。在非交互模式(`-p`)下,当密钥存在时始终使用该密钥。2413. `ANTHROPIC_API_KEY` 环境变量。作为 `X-Api-Key` 标头发送。用于直接 Anthropic API 访问,使用来自 [Claude Console](https://platform.claude.com) 的密钥。在交互模式下,系统会提示您一次批准或拒绝该密钥,您的选择会被记住。要稍后更改它,请使用 `/config` 中的"使用自定义 API 密钥"切换。该切换仅在 `ANTHROPIC_API_KEY` 在您的环境中设置时出现。在非交互模式(`-p`)下,当密钥存在时始终使用该密钥。
2304. [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本输出。用于动态或轮换凭证,例如从保管库获取的短期令牌。2424. [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本输出。用于动态或轮换凭证,例如从保管库获取的短期令牌。
2315. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本,其中浏览器登录不可用。如果您在设置了该变量时运行 `/login`,Claude Code 会将当前会话切换到新登录,但在每个新会话中都会再次读取该变量,直到您从 shell 配置文件或[设置文件](/docs/zh-CN/settings)的 `env` 块中删除它。2435. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本,其中浏览器登录不可用。如果您在设置了该变量时运行 `/login`,Claude Code 会将当前会话切换到新登录,但在每个新会话中都会再次读取该变量,直到您从 shell 配置文件或[设置文件](/docs/zh-CN/settings.md)的 `env` 块中删除它。
2326. Anthropic 配置文件和联合凭证,即 `ant` CLI 和 Workload Identity Federation 使用的凭证。`ant auth login` 写入的配置文件仅在您在 `ANTHROPIC_PROFILE` 中命名它时才排在此处;否则它排在 `/login` 下方。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。2446. Anthropic 配置文件和联合凭证,即 `ant` CLI 和 Workload Identity Federation 使用的凭证。`ant auth login` 写入的配置文件仅在您在 `ANTHROPIC_PROFILE` 中命名它时才排在此处;否则它排在 `/login` 下方。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。
2337. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。2457. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。
234 246
235一个已签名的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话位于此列表之外:它是一个提供商选择,如 Amazon Bedrock 或 Google Cloud 的 Agent Platform,并且它优先于它们。当网关会话存在时,即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`,CLI 也会使用网关令牌进行身份验证,上面的持有者令牌、API 密钥、`apiKeyHelper` 和配置文件等凭证源不会被使用。247一个已签名的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话位于此列表之外:它是一个提供商选择,如 Amazon Bedrock 或 Google Cloud 的 Agent Platform,并且它优先于它们。当网关会话存在时,即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`,CLI 也会使用网关令牌进行身份验证,上面的持有者令牌、API 密钥、`apiKeyHelper` 和配置文件等凭证源不会被使用。
236 248
237如果您的机器的[托管设置](/docs/zh-CN/managed-settings)将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"` 或设置 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl),并且您没有通过 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX` 等变量选择云提供商,您的会话仅使用网关登录。Claude Code 跳过其他凭证源并要求您使用 `/login` 登录。有关每个剩余凭证的情况,请参阅[管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。需要 Claude Code v2.1.261 或更高版本,或在仅设置 `forceLoginGatewayUrl` 的机器上需要 v2.1.265 或更高版本。249如果您的机器的[托管设置](/docs/zh-CN/managed-settings.md)将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"` 或设置 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl),并且您没有通过 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX` 等变量选择云提供商,您的会话仅使用网关登录。Claude Code 跳过其他凭证源并要求您使用 `/login` 登录。有关每个剩余凭证的情况,请参阅[管理员策略需要云网关登录](/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)。需要 Claude Code v2.1.261 或更高版本,或在仅设置 `forceLoginGatewayUrl` 的机器上需要 v2.1.265 或更高版本。
238 250
239如果您有活跃的 Claude 订阅,但环境中也设置了 `ANTHROPIC_API_KEY`,Claude Code 会在您批准后使用 API 密钥。如果密钥属于已禁用或过期的组织,这可能会导致身份验证失败。251如果您有活跃的 Claude 订阅,但环境中也设置了 `ANTHROPIC_API_KEY`,Claude Code 会在您批准后使用 API 密钥。如果密钥属于已禁用或过期的组织,这可能会导致身份验证失败。
240 252
241运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅,并检查 `/status` 以确认哪种方法处于活跃状态。当登录和 API 密钥都已配置时,`/status` 会标记未在使用的凭证。253运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅,并检查 `/status` 以确认哪种方法处于活跃状态。当登录和 API 密钥都已配置时,`/status` 会标记未在使用的凭证。
242 254
243[Cloud sessions](/docs/zh-CN/claude-code-on-the-web) 始终使用您的订阅凭证。如果您在云环境中设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`,它不会覆盖您的订阅凭证。255[Cloud sessions](/docs/zh-CN/claude-code-on-the-web.md) 始终使用您的订阅凭证。如果您在云环境中设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`,它不会覆盖您的订阅凭证。
244 256
245#### Anthropic 配置文件和联合凭证257#### Anthropic 配置文件和联合凭证
246 258
247配置文件是您的 [Anthropic 配置目录](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory)中的命名凭证配置文件,在 macOS 和 Linux 上默认为 `~/.config/anthropic`,在 Windows 上为 `%APPDATA%\Anthropic`。当您为 [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 设置配置文件时,其身份验证模式为 `oidc_federation`,或当 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 写入它或您[在没有 API 密钥的情况下登录到 Console 帐户](#sign-in-without-an-api-key)时为 `user_oauth`。259配置文件是您的 [Anthropic 配置目录](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory)中的命名凭证配置文件,在 macOS 和 Linux 上默认为 `~/.config/anthropic`,在 Windows 上为 `%APPDATA%\Anthropic`。当您为 [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 设置配置文件时,其身份验证模式为 `oidc_federation`,或当 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 写入它或您[在没有 API 密钥的情况下登录到 Console 帐户](#sign-in-without-an-api-key)时为 `user_oauth`。
248 260
249Claude Code 不在[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)、Claude Desktop 或云会话中读取配置文件或联合变量。在这些会话中,`/status` 不显示 `Profile` 行。261Claude Code 不在[裸模式](/docs/zh-CN/headless.md#start-faster-with-bare-mode)、Claude Desktop 或云会话中读取配置文件或联合变量。在这些会话中,`/status` 不显示 `Profile` 行。
250 262
251Claude Code 按此顺序检查三个源,并在第一个设置的源处停止。该表显示设置每个源的内容以及它相对于您的 `/login` 凭证的排名。263Claude Code 按此顺序检查三个源,并在第一个设置的源处停止。该表显示设置每个源的内容以及它相对于您的 `/login` 凭证的排名。
252 264
260 272
261要确认 Claude Code 选择了哪个源,请运行 `/status`。`Profile` 行用源名称代替 `Login method` 行。当配置文件是正在使用的凭证时,`Organization` 和 `Email` 行显示其帐户。273要确认 Claude Code 选择了哪个源,请运行 `/status`。`Profile` 行用源名称代替 `Login method` 行。当配置文件是正在使用的凭证时,`Organization` 和 `Email` 行显示其帐户。
262 274
263当 `user_oauth` 配置文件的登录已过期且 Claude Code 无法续期时,请求会失败,显示 [Anthropic 配置文件登录已过期](/docs/zh-CN/errors#anthropic-profile-login-expired)。275当 `user_oauth` 配置文件的登录已过期且 Claude Code 无法续期时,请求会失败,显示 [Anthropic 配置文件登录已过期](/docs/zh-CN/errors.md#anthropic-profile-login-expired)。
264 276
265需要您的 claude.ai 登录的功能,例如 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)和 [`/schedule`](/docs/zh-CN/routines),在选择这些源之一时不可用。要停止 Claude Code 选择源:277需要您的 claude.ai 登录的功能,例如 [claude.ai 连接器](/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)和 [`/schedule`](/docs/zh-CN/routines),在选择这些源之一时不可用。要停止 Claude Code 选择源:
266 278
267* **命名配置文件或联合变量**:取消设置 `ANTHROPIC_PROFILE`,或取消设置任一联合变量279* **命名配置文件或联合变量**:取消设置 `ANTHROPIC_PROFILE`,或取消设置任一联合变量
268* **活跃配置文件**:对于通过[在没有 API 密钥的情况下登录到 Console 帐户](#sign-in-without-an-api-key)写入当前凭证的 `user_oauth` 配置文件运行 `/logout`,对于 `ant auth login` 写入当前凭证的配置文件运行 `ant auth logout`,或对于任一身份验证模式从您的配置目录中的 `configs/` 删除配置文件的文件280* **活跃配置文件**:对于通过[在没有 API 密钥的情况下登录到 Console 帐户](#sign-in-without-an-api-key)写入当前凭证的 `user_oauth` 配置文件运行 `/logout`,对于 `ant auth login` 写入当前凭证的配置文件运行 `ant auth logout`,或对于任一身份验证模式从您的配置目录中的 `configs/` 删除配置文件的文件
295set CLAUDE_CODE_OAUTH_TOKEN=your-token307set CLAUDE_CODE_OAUTH_TOKEN=your-token
296```308```
297 309
298此令牌使用您的 Claude 订阅进行身份验证,需要 Pro、Max、Team 或 Enterprise 计划。它只能进行模型请求,因此无法建立 [Remote Control](/docs/zh-CN/remote-control) 会话或获取 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。您在本地配置的 MCP 服务器仍然有效。310此令牌使用您的 Claude 订阅进行身份验证,需要 Pro、Max、Team 或 Enterprise 计划。它只能进行模型请求,因此无法建立 [Remote Control](/docs/zh-CN/remote-control.md) 会话或获取 [claude.ai 连接器](/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)。您在本地配置的 MCP 服务器仍然有效。
299 311
300[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)不读取 `CLAUDE_CODE_OAUTH_TOKEN`。如果您的脚本传递 `--bare`,请改用 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 进行身份验证。312[裸模式](/docs/zh-CN/headless.md#start-faster-with-bare-mode)不读取 `CLAUDE_CODE_OAUTH_TOKEN`。如果您的脚本传递 `--bare`,请改用 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 进行身份验证。