Claude Code 深度学习手册

主题

企业身份与访问（IAM） ​

Claude Code 的认证与凭证管理：覆盖个人/团队/企业/云厂商的多种登录方式、凭证在各 OS 的存储位置，以及多凭证并存时的认证优先级。

是什么 ​

该页是 Claude Code 官方文档的 IAM 入口页（URL /en/iam），但实际标题与内容为「Authentication」（认证与登录）。它讲三件事：1) 个人/团队/组织如何登录 Claude Code；2) 凭证在各操作系统上如何安全存储；3) 多种认证方式（订阅 OAuth、API key、云厂商、长期 token、apiKeyHelper）的优先级与配置方式。注意：本页不包含权限规则（allow/ask/deny）、权限模式（default/acceptEdits/plan/bypassPermissions）、/permissions 命令、企业托管策略文件等内容——这些在文档其他页面，本稿严格不涉及。

怎么工作 ​

  • 个人登录流程：终端跑 claude → 首次启动唤起浏览器 OAuth 登录 → 登录后浏览器跳回 Claude Code 本地 callback 服务器完成认证。本地 callback 不可达时（WSL2/SSH/容器）改走「复制登录码粘回终端」的兜底路径（在 Paste code here if prompted 处粘贴）。
  • 凭证管理：登录成功后凭证按平台落地——macOS 进加密 Keychain，Linux 进 ~/.claude/.credentials.json(0600)，Windows 进 %USERPROFILE%\.claude\.credentials.json。该文件由 /login//logout 维护，不手动编辑。
  • 认证方式优先级（多凭证并存时按序选一）：1) 云厂商凭证（设了 CLAUDE_CODE_USE_BEDROCK/CLAUDE_CODE_USE_VERTEX/CLAUDE_CODE_USE_FOUNDRY）；2) ANTHROPIC_AUTH_TOKEN（作 Authorization: Bearer 头）；3) ANTHROPIC_API_KEY（作 X-Api-Key 头）；4) apiKeyHelper 脚本输出；5) CLAUDE_CODE_OAUTH_TOKEN；6) /login 得到的订阅 OAuth 凭证（Pro/Max/Team/Enterprise 默认）。
  • apiKeyHelper 动态凭证机制：配置后由 Claude Code 周期性调用脚本拿 key，默认触发条件是「上次调用过 5 分钟」或「收到 HTTP 401」；可用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 改间隔。适合 vault 里取短时 token 这类轮换场景。
  • 长期 token 机制：claude setup-token 走一遍 OAuth 授权后把一个 1 年期 OAuth token 打印到终端但不保存，需自行复制并设为 CLAUDE_CODE_OAUTH_TOKEN；它绑定订阅、仅限 inference 用途，无法建立 Remote Control 会话。
  • 云厂商认证无需浏览器登录：跑 claude 前设好对应环境变量即可（Bedrock/Vertex/Foundry）。
  • ANTHROPIC_API_KEY 在交互模式下首次会提示批准/拒绝并记住选择（之后可用 /config 的「Use custom API key」开关改）；非交互模式 -p 下只要存在就一定使用。

怎么配置 / 用法 ​

该页面 URL 为 https://code.claude.com/docs/en/iam，但实际渲染标题为「Authentication」，内容只覆盖登录与凭证管理（不含权限规则/权限模式/托管策略文件）。

【个人登录】 终端运行 claude，首次启动自动打开浏览器登录。浏览器没自动开时按 c 复制登录 URL 手动粘贴。若浏览器显示登录码而非跳回（WSL2/SSH/容器常见），把码粘贴到终端的 Paste code here if prompted 提示处。登出/重新认证：在 Claude Code 提示符输入 /logout。

【团队/企业认证】Claude Console 加用户两种方式：

  • Console 内批量邀请：Settings -> Members -> Invite
  • 配置 SSO 邀请时分配角色：Claude Code 角色（只能建 Claude Code API key）/ Developer 角色（可建任意 API key）。

【凭证存储位置】

  • macOS：加密的 macOS Keychain
  • Linux：~/.claude/.credentials.json，文件权限 0600
  • Windows：%USERPROFILE%\.claude\.credentials.json，继承用户配置目录访问控制
  • Linux/Windows 若设了 CLAUDE_CONFIG_DIR，.credentials.json 改放在该目录下 .credentials.json 由 /login 和 /logout 管理。自定义 API 端点用 env ANTHROPIC_BASE_URL。

【apiKeyHelper】 settings 里 apiKeyHelper 可配一个返回 API key 的 shell 脚本。默认 5 分钟后或收到 HTTP 401 时再次调用；自定义刷新间隔用 env CLAUDE_CODE_API_KEY_HELPER_TTL_MS。脚本超过 10 秒返回会在提示栏显示告警。

【生成长期 token（CI/脚本）】

bash
claude setup-token        # 走 OAuth，打印 1 年期 token（不落盘）
export CLAUDE_CODE_OAUTH_TOKEN=your-token

什么时候用 ​

  • 个人用户首次配置：直接跑 claude 用 Claude.ai 账号（Pro/Max 订阅）或 Console 凭证登录。
  • 团队/组织选型：多数团队推荐 Claude for Teams 或 Enterprise（成员用 Claude.ai 账号登录，集中计费）；偏好按 API 计费的组织走 Claude Console。Enterprise 额外提供 SSO、域捕获、基于角色的权限、合规 API、托管策略设置。
  • CI/脚本/无浏览器环境：用 claude setup-token 生成 CLAUDE_CODE_OAUTH_TOKEN（需 Pro/Max/Team/Enterprise 订阅）。
  • 走 LLM gateway/proxy 且用 bearer token 认证时：用 ANTHROPIC_AUTH_TOKEN 而非 API key。
  • 直连 Anthropic API：用 ANTHROPIC_API_KEY。
  • 动态/轮换凭证（如 vault 短时 token）：用 apiKeyHelper 脚本。
  • 别用 CLAUDE_CODE_OAUTH_TOKEN 的场景：需要建立 Remote Control 会话时（它仅限 inference）；脚本带 --bare（bare 模式不读该 token，改用 ANTHROPIC_API_KEY 或 apiKeyHelper）。
  • Claude Desktop / 远程会话：只用 OAuth，配 apiKeyHelper/API key env 无效，不用在这类环境折腾它们。

限制 / 坑 ​

  • 有订阅但又设了 ANTHROPIC_API_KEY 时，API key（一经批准）优先级更高，会盖过订阅；若该 key 属于已禁用/过期组织会导致认证失败。解法：unset ANTHROPIC_API_KEY 回退订阅，用 /status 确认当前生效方式。
  • apiKeyHelper、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 仅对终端 CLI 会话生效；Claude Desktop 和远程会话只用 OAuth，不调用 apiKeyHelper、不读这些 API key 环境变量。
  • Claude Code on the Web 始终用订阅凭证；sandbox 环境里的 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 不能覆盖它。
  • CLAUDE_CODE_OAUTH_TOKEN 仅限 inference 用途，无法建立 Remote Control 会话；需订阅（Pro/Max/Team/Enterprise）。
  • Bare 模式不读 CLAUDE_CODE_OAUTH_TOKEN：脚本带 --bare 时须改用 ANTHROPIC_API_KEY 或 apiKeyHelper。
  • apiKeyHelper 脚本超过 10 秒返回 key，会在提示栏显示带耗时的告警；频繁出现需优化脚本。
  • 本地 callback 服务器不可达（WSL2/SSH/容器）时浏览器会显示登录码而非自动跳回，需手动把码粘回终端。
  • 政策变化：自 2026 年 6 月 15 日起，订阅计划下的 Agent SDK 与 claude -p 用量将从独立的月度 Agent SDK 额度扣减，与交互用量额度分开。

硬事实速查（29 条） ​

  • 凭证文件名：.credentials.json，由 /login 和 /logout 管理
  • macOS 凭证：存于加密的 macOS Keychain
  • Linux 凭证路径：~/.claude/.credentials.json，文件权限 0600
  • Windows 凭证路径：%USERPROFILE%\.claude\.credentials.json，继承用户配置目录访问控制
  • env CLAUDE_CONFIG_DIR（Linux/Windows）：设了之后 .credentials.json 改放到该目录下
  • setting apiKeyHelper：配 shell 脚本返回 API key（位于 settings，见 /en/settings#available-settings）
  • apiKeyHelper 默认刷新触发：5 分钟后 或 HTTP 401 响应时
  • env CLAUDE_CODE_API_KEY_HELPER_TTL_MS：自定义 apiKeyHelper 刷新间隔
  • apiKeyHelper 慢告警阈值：超过 10 秒返回 key
  • 认证优先级第1：云厂商凭证（CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRY）
  • 认证优先级第2：ANTHROPIC_AUTH_TOKEN → 发送为 Authorization: Bearer 头
  • 认证优先级第3：ANTHROPIC_API_KEY → 发送为 X-Api-Key 头
  • 认证优先级第4：apiKeyHelper 脚本输出
  • 认证优先级第5：CLAUDE_CODE_OAUTH_TOKEN
  • 认证优先级第6：/login 的订阅 OAuth 凭证（Pro/Max/Team/Enterprise 默认）
  • 命令 claude setup-token：走 OAuth，打印 1 年期（one-year）OAuth token，不落盘
  • env CLAUDE_CODE_OAUTH_TOKEN：存放 setup-token 生成的长期 token，仅限 inference，不能建 Remote Control 会话
  • env ANTHROPIC_BASE_URL：路由到自定义 API 端点
  • 命令 /logout：登出并重新认证；/login：登录
  • 命令 /status：确认当前生效的认证方式
  • 命令 /config：含「Use custom API key」开关，可改 ANTHROPIC_API_KEY 的批准选择
  • 首次登录粘码提示文案：Paste code here if prompted；按 c 复制登录 URL
  • 非交互模式 -p：ANTHROPIC_API_KEY 存在则一定使用
  • --bare（Bare 模式）：不读 CLAUDE_CODE_OAUTH_TOKEN
  • 支持的认证类型：Claude.ai credentials、Claude API credentials、Azure Auth、Bedrock Auth、Vertex Auth
  • Console 角色：Claude Code（只能建 Claude Code API key）/ Developer（可建任意 API key）
  • Console 加用户路径：Settings -> Members -> Invite
  • Enterprise 额外能力：SSO、域捕获(domain capture)、基于角色的权限、合规 API、托管策略设置(managed policy settings)
  • 日期：2026-06-15 起 Agent SDK 与 claude -p 订阅用量改走独立月度 Agent SDK 额度

官方出处：https://code.claude.com/docs/en/authentication