认证、登录与多账户管理

Claude Code 的认证体系远比表面上复杂。它同时支持订阅账户（Pro / Max / Team / Enterprise）、Anthropic Console API Key、以及三大云提供商（AWS Bedrock / Google Vertex AI / Microsoft Foundry）三种完全不同的认证路径。每种路径的计费方式、使用限制、适用场景各不相同。本章将系统梳理所有认证方式，帮助你选择最适合自己的方案，并掌握多账户切换、故障排查的实用技巧。

一、Claude 订阅类型全景对比

Anthropic 提供五档订阅计划，覆盖从个人开发者到大型企业的全场景需求。

1.1 个人订阅：Free / Pro / Max

关键认知：Claude Code 不包含在 Free 计划中。使用 Claude Code 必须拥有 Pro、Max、Team 或 Enterprise 订阅，或 Anthropic Console API 账户。

1.2 团队订阅：Team

Team 计划适合 5-150 人的小型团队，支持混合配置（Standard + Premium 座位混用）。Premium 座位提供 5 倍于 Standard 的使用量。

1.3 企业订阅：Enterprise

Enterprise 在 Team 基础上增加了组织级安全与合规能力：

Enterprise 分为自助服务（Self-serve）和销售协助（Sales-assisted）两种模式。自助模式可立即开通，销售协助模式适用于需要 MSA、PO、使用承诺的大型组织。

1.4 如何选择订阅类型

决策树：
├─ 个人使用？
│  ├─ 轻度使用（每周 < 10 小时）→ Pro
│  ├─ 重度使用（每天编码）→ Max 5x
│  └─ 专业/商业用途 → Max 20x
├─ 团队 5-150 人？
│  └─ Team（Standard/Premium 混配）
└─ 企业级安全/合规要求？
   └─ Enterprise（SSO + SCIM + 审计日志）

二、Claude Console API：Key 获取与计费

Anthropic Console 是面向开发者的 API 管理平台，与 Claude.ai 订阅完全独立计费。

2.1 创建 API Key

1. 访问 console.claude.com 注册账户
2. 创建 Organization（组织）
3. 进入 Settings > API Keys 点击 "Create Key"
4. 复制 Key（仅显示一次，务必妥善保存）

首次登录 Claude Code 使用 Console 账户时，系统会自动创建一个 "Claude Code" Workspace 用于集中成本追踪。

2.2 预付费信用额度机制

Claude API 采用预付费信用额度（Prepaid Credits）模式：

• 必须先购买信用额度才能调用 API
• 失败请求不收费，仅对成功的 API 调用计费
• 信用额度自购买日起 1 年后过期，不可退款、不可延期
• 可设置自动充值（Auto-reload）：当余额低于设定阈值时自动购买

# 在 Claude Code 中使用 API Key 认证
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
claude

2.3 使用量等级（Usage Tiers）

API 使用量等级自动根据累计充值金额提升：

达到累计充值门槛后，等级立即自动提升。每月支出上限在当月达到后，需等到下月才能继续使用，或联系销售提升等级。

2.4 速率限制（Rate Limits）

速率限制按模型分别计算，采用 Token Bucket 算法（容量持续补充，非固定时间重置）：

关键优化点：对于大部分模型，仅未缓存的输入 Token 计入 ITPM 限制。缓存读取 Token（cache_read_input_tokens）不计入速率限制，且按基础价格的 10% 计费。这意味着通过 Prompt Caching 可以大幅提升有效吞吐量。

2.5 API 定价速查（2026 年 4 月）

• 批量处理（Batch API）：输入/输出均享 50% 折扣
• 快速模式（Fast Mode）：Opus 4.6 支持，6 倍标准价格
• 数据驻留（US-only）：1.1 倍价格乘数

三、登录流程详解

3.1 首次启动认证

安装完成后，在终端执行 claude 启动交互式会话：

# 进入项目目录并启动
cd /path/to/your/project
claude

首次启动时，Claude Code 会：

1. 自动打开浏览器跳转到 Anthropic OAuth 授权页面
2. 如果浏览器未自动打开，按 c 复制登录 URL，手动粘贴到浏览器
3. 登录后如果浏览器显示授权码而非自动跳转，将代码粘贴到终端的 Paste code here if prompted 提示处

支持登录的账户类型：

• Claude Pro / Max：使用 Claude.ai 账户登录
• Claude for Teams / Enterprise：使用团队管理员邀请的 Claude.ai 账户
• Claude Console：使用 Console 凭据登录（需管理员先邀请）
• 云提供商：AWS Bedrock / Google Vertex AI / Microsoft Foundry（无需浏览器登录，通过环境变量配置）

3.2 浏览器 OAuth 流程

终端执行 claude
    ↓
生成 OAuth 请求 + state 参数
    ↓
打开浏览器（或提供 URL 手动打开）
    ↓
用户在浏览器完成 Anthropic 登录
    ↓
浏览器重定向回本地回调（或显示授权码）
    ↓
终端接收授权码，交换 Access Token + Refresh Token
    ↓
Token 存入系统安全存储（macOS Keychain / Windows Credential / ~/.claude/.credentials.json）
    ↓
认证完成，进入 Claude Code 交互界面

3.3 非交互式环境认证

对于 CI/CD 流水线、远程服务器、脚本自动化等无浏览器场景：

方案 A：API Key（最简单）

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
claude -p "your task"

方案 B：长期有效的 OAuth Token

# 生成为期一年的 OAuth Token
claude setup-token

# 将输出的 Token 设置到环境变量
export CLAUDE_CODE_OAUTH_TOKEN="your-token"
claude -p "your task"

claude setup-token 需要 Pro / Max / Team / Enterprise 订阅。Token 仅用于推理，不能建立 Remote Control 会话。--bare 模式不读取此 Token。

方案 C：apiKeyHelper 脚本（动态凭证）

在 ~/.claude/settings.json 中配置：

{
  "apiKeyHelper": "/path/to/get-api-key.sh"
}

脚本需输出有效的 API Key 到 stdout。默认每 5 分钟或遇到 HTTP 401 时重新调用。可通过 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 自定义刷新间隔。

四、多账户切换

4.1 内置 /login 命令

Claude Code 内置账户切换机制：

# 在 Claude Code 交互会话中
/login          # 重新登录，切换账户
/logout         # 登出当前账户
/status         # 查看当前认证状态和活跃凭证

切换账户时，Claude Code 会：

• 清除当前会话的环境变量 Token（如 CLAUDE_CODE_OAUTH_TOKEN）
• 启动新的 OAuth 流程
• 将新凭证存入系统安全存储

注意：如果交互式会话以 CLAUDE_CODE_OAUTH_TOKEN 环境变量启动，运行 /login 会清除该环境变量，使磁盘存储的凭证生效。

4.2 认证优先级规则

当多种凭证同时存在时，Claude Code 按以下优先级选择：

1. 云提供商凭证（CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRY）
2. ANTHROPIC_AUTH_TOKEN（Bearer Token，用于 LLM 网关/代理）
3. ANTHROPIC_API_KEY（直接 Anthropic API 访问）
4. apiKeyHelper 脚本输出（动态/轮换凭证）
5. CLAUDE_CODE_OAUTH_TOKEN（长期 OAuth Token）
6. 订阅 OAuth 凭证（/login 存储的 Pro/Max/Team/Enterprise 凭证）

常见陷阱：如果你同时拥有活跃订阅和环境变量 ANTHROPIC_API_KEY，API Key 会优先使用。如果该 Key 属于已禁用或过期的组织，会导致认证失败。执行 unset ANTHROPIC_API_KEY 可回退到订阅认证。

4.3 多账户隔离方案

Claude Code 官方不直接支持多账户配置切换，但可通过以下方式实现：

方案 A：环境变量隔离（推荐）

# 工作账户
alias claude-work='unset ANTHROPIC_API_KEY; CLAUDE_CONFIG_DIR=~/.claude-work claude'

# 个人账户
alias claude-personal='unset ANTHROPIC_API_KEY; CLAUDE_CONFIG_DIR=~/.claude-personal claude'

每个配置目录拥有独立的 settings.json 和 .credentials.json。

方案 B：第三方工具（Claude Switch / CCS）

社区开发了专门的多账户切换工具：

• Claude Switch（claudeswitch.dev）：开源 CLI，macOS/Linux，一键切换工作/个人账户
• CCS (Claude Code Switch)（ccs.kaitran.ca）：支持多账户 + 成本优化的 GLM-5.1/Kimi 降级

方案 C：Docker 容器隔离

# 为每个账户构建独立的认证容器
docker run -e CLAUDE_CODE_OAUTH_TOKEN=$WORK_TOKEN -v $(pwd):/workspace claude-code

五、第三方云提供商接入

Claude 是目前唯一可在全球三大云平台同时使用的 Frontier AI 模型。

5.1 部署选项对比

5.2 AWS Bedrock

# 环境变量配置
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# 通过 AWS CLI 配置或 IAM Role 获取凭证

# 启动 Claude Code
claude

Bedrock 支持全球端点（动态路由）和区域端点（保证数据路由），区域端点有 10% 价格溢价。

5.3 Google Vertex AI

# 环境变量配置
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
# 通过 gcloud auth 或 Service Account 获取凭证

# 启动 Claude Code
claude

Vertex AI 提供全球、多区域和区域三种端点类型。新用户可获得 $300 试用额度。

5.4 Microsoft Foundry

# 环境变量配置
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key
# 或使用 Microsoft Entra ID 认证（省略 API Key）

# 启动 Claude Code
claude

5.5 企业代理与网关配置

企业代理（Corporate Proxy）：

export HTTPS_PROXY='https://proxy.example.com:8080'
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

LLM 网关（LLM Gateway）：

export ANTHROPIC_BASE_URL='https://your-llm-gateway.com'
# 或 Bedrock 专用网关
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1  # 网关处理 AWS 认证

六、企业 SSO 与团队管理

6.1 SSO 配置流程

Claude Enterprise 支持 SAML 2.0 和 OIDC 两种 SSO 协议，通过 WorkOS 集成：

Step 1：验证域名

• 在 Admin Console 中添加公司域名
• 通过 DNS TXT 记录验证域名所有权
• 支持多域名，但所有域名必须通过同一个 IdP 管理

Step 2：配置 IdP

• 支持 Okta、Azure AD、Ping Identity、Google Workspace 等主流 IdP
• 在 IdP 中创建 Anthropic 应用并配置 SAML/OIDC 参数
• 映射用户属性（email、name、groups）

Step 3：强制 SSO（可选）

• 开启 "Require SSO for Claude" 后，用户必须使用 SSO 登录
• 未开启时，用户可选择 SSO 或邮箱登录

Step 4：配置用户预配

6.2 团队管理最佳实践

分阶段推广：

1. 试点阶段：50-100 人，SCIM 同步试点组，运行 2-4 周
2. 扩展阶段：逐步增加 SCIM 组，覆盖更多部门
3. 全面推广：流程稳定后启用组织级访问

Claude Code 座位配置：

管理员在 Settings > Organization > Members 中分配座位并设置支出限制（默认 $0）。

七、安全存储机制

7.1 凭证存储位置

可通过 CLAUDE_CONFIG_DIR 环境变量自定义配置目录。

7.2 支持的认证类型

存储的凭证类型包括：

• Claude.ai 订阅凭证（OAuth）
• Claude API 凭证（API Key）
• Azure Auth（Foundry）
• Bedrock Auth（AWS）
• Vertex Auth（GCP）

7.3 插件凭证安全

Claude Code 2.1.83+ 将插件配置（API Key、Token 等）存储在系统级安全存储中：

• macOS：Keychain
• Windows：Credential Manager

不再写入 ~/.claude/settings.json 或项目目录的 .env 文件，避免凭证泄露风险。

7.4 SSH / 无 GUI 环境处理

SSH 会话默认无法访问 macOS Keychain。解决方案：

# 方案 1：手动解锁 Keychain
security unlock-keychain

# 方案 2：使用 .credentials.json 回退
# Claude Code 会自动在 Keychain 不可用时使用文件存储

# 方案 3：环境变量注入（CI/CD 推荐）
export CLAUDE_CODE_OAUTH_TOKEN="your-token"

八、故障排查指南

8.1 登录失败（401 错误）

症状：API Error: 401 · authentication_error，/login 和 /logout 也返回 401。

根因：OAuth Token 过期或损坏，导致认证命令自身也无法执行。

修复步骤：

# Step 1：手动删除认证文件（绕过 CLI）

# macOS
security delete-generic-password -s "claude-code" 2>/dev/null
rm -f ~/.claude/.credentials.json

# Linux / Windows
rm -f ~/.claude/.credentials.json

# Step 2：重新登录
claude
# 按提示完成浏览器 OAuth 流程

# Step 3：验证
# 在 Claude Code 中运行 /status，确认账户信息正确

如果仍无法解决：

# 检查系统时间（时间不同步会导致 OAuth 失败）
date  # 应与网络时间同步

# 更新 Claude Code 到最新版
claude update

# 临时使用 API Key 绕过
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
claude

8.2 Token 过期 / 被撤销

症状：OAuth token revoked · Please run /login 或 OAuth token has expired。

处理：

# 在 Claude Code 中
/logout          # 完全清除存储的 Token
/login           # 重新认证

如果反复提示登录，检查：

• 系统时钟是否准确（NTP 同步）
• macOS Keychain 是否被锁定（SSH 会话常见问题）
• 账户是否被管理员移除访问权限

8.3 权限不足

症状：This organization has been disabled 或 Claude Opus is not available with the Claude Pro plan。

排查：

# 检查活跃凭证来源
/status

# 检查环境变量是否覆盖订阅
env | grep ANTHROPIC

# 如发现 ANTHROPIC_API_KEY 属于已禁用组织
unset ANTHROPIC_API_KEY
/logout
/login

模型不可用：升级计划后，需要 /logout + /login 重新认证，存储的 Token 反映的是登录时的计划状态。

8.4 网络连接问题

症状：Unable to connect to API。

诊断：

# 测试 API 连通性
curl -I https://api.anthropic.com

# Windows PowerShell
curl.exe -I https://api.anthropic.com

常见原因：

• 企业代理未配置：设置 HTTPS_PROXY
• VPN 阻止：检查 ifconfig 中是否有 stale utun 接口
• DNS 解析失败（WSL 常见问题）：检查 /etc/resolv.conf
• SSL 证书拦截：设置 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

8.5 使用量达到限制

症状：You've hit your session limit · resets 3:45pm 或 You've hit your weekly limit。

处理：

# 查看剩余用量和重置时间
/usage

# 购买额外用量（Pro / Max）
/extra-usage

# 查看当前会话花费（API Key 用户）
/cost

API Key 用户的 429 错误：

# 确认活跃凭证
/status

# 检查 Console 中的速率限制等级
# 降低并发：减少并行子代理，切换到较小模型
/model sonnet

8.6 快速诊断清单

九、参考来源

1. 官方文档
   • Authentication - Claude Code Docs — 认证方式、凭证管理、Token 生成
   • Error reference - Claude Code Docs — 所有运行时错误代码和修复方法
   • Quickstart - Claude Code Docs — 首次登录和账户类型说明
   • Enterprise deployment overview — 云提供商部署对比
   • Pricing - Claude API Docs — API 定价详情
   • Rate limits - Claude API Docs — 速率限制和使用量等级
2. 官方支持中心
   • Set up single sign-on (SSO) — SSO 配置步骤
   • Models, usage, and limits in Claude Code — 使用量计量和限制说明
   • How do I pay for my Claude API usage? — API 预付费机制
   • Use Claude Code with your Team or Enterprise plan — 企业计划使用指南
3. 企业部署资源
   • Claude Enterprise Administrator Guide — 四阶段企业部署 playbook
   • Claude Pricing — 所有计划的官方定价和功能对比
4. 社区资源
   • How to Fix Claude Code "API Error: 401" — 401 错误的系统修复方法
   • Claude Code OAuth Token Expiry: Fixes & Alternatives — Token 过期机制和替代方案
   • Claude Switch — 多账户切换开源工具
   • Claude Code Multi-Account Setup — 多账户配置实践