Claude Code 安装与认证 — 原生安装 / npm / API Key / OAuth Token / SSO / 云服务商

简介

认证是 Claude Code 使用的第一步，也是确保安全访问的基石。本文将深入剖析 Claude Code 当前支持的安装方式与六种认证机制，涵盖原生安装、npm 包管理、Bearer Token、API Key、OAuth Token、SSO 企业登录及云服务商（Bedrock/Vertex/Foundry）认证，帮助开发者根据场景选择最合适的安装和认证策略，并排查常见问题。

Claude Code 的安装方式和认证体系在近半年发生了显著变化。从最初仅支持 npm 全局安装 + ANTHROPIC_API_KEY 的单一模式，演进为原生二进制分发 + 多级认证优先级的现代化架构。安装不再依赖 Node.js 运行时，认证不再只有 API Key 一种选择。

本文将从安装方式讲起，逐层拆解六种认证机制的工作原理、优先级规则、配置流程和最佳实践，最后通过对比表格和决策树帮助你做出正确选择。无论你是个人开发者、CI/CD 工程师还是企业 IT 管理员，都能在这里找到适合的方案。

一、安装方式
二、认证方式总览
三、云服务商认证（最高优先级）
四、Bearer Token 认证
五、API Key 认证
六、自定义脚本认证（apiKeyHelper）
七、OAuth Token 认证（长期令牌）
八、Subscription OAuth（默认流程）
九、SSO 企业单点登录
十、认证方式对比与选型指南
十一、常见认证问题排查
十二、真实经验与踩坑
十三、落地检查清单
十四、总结
十五、下篇预告

一、安装方式

1.1 原生安装（推荐）

自 Claude Code v2.x 起，推荐通过原生二进制方式安装，不再依赖 Node.js 运行时。

bash

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

powershell

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

cmd

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

原生安装的优势：

零依赖 — 不需要 Node.js、npm 或任何运行时环境
自包含 — 二进制文件包含所有依赖，版本隔离
跨平台一致 — 在 macOS ARM、Linux x86、Windows 上的行为完全一致
自动后台更新 — 原生安装会在后台自动检查并下载新版本，无需手动执行 claude upgrade，确保始终运行最新稳定版

1.2 npm 安装（备用）

对于已经安装了 Node.js 的开发环境，npm 安装依然是可用的方式，但不再是官方推荐的主路径。npm 包 @anthropic-ai/claude-code 作为一个 launcher，在安装时自动下载对应平台的原生二进制文件。

bash

# 需要 Node.js >= 18
npm install -g @anthropic-ai/claude-code

1.3 Homebrew / WinGet

bash

# macOS（Homebrew）
# stable 频道：通常滞后约一周，跳过有问题的版本
brew install --cask claude-code

# latest 频道：第一时间获取最新版本
brew install --cask claude-code@latest

Homebrew 频道说明：claude-code 跟踪 stable 发行频道，通常比最新版本延迟约一周，会跳过有重大回归的版本。claude-code@latest 跟踪最新频道，发布即更新。Homebrew 安装不会自动更新，需要手动执行：
bash
brew upgrade claude-code        # stable 频道
brew upgrade claude-code@latest # latest 频道

powershell

# Windows（WinGet）
winget install Anthropic.ClaudeCode

WinGet 自动更新：WinGet 安装同样不会自动更新，建议定期执行：
powershell
winget upgrade Anthropic.ClaudeCode

1.4 验证安装

bash

# 查看版本
claude --version

# 运行诊断
claude doctor

二、认证方式总览

Claude Code 的认证层支持多种凭证来源，按优先级从高到低依次尝试。这意味着如果你同时配置了多个认证方式，最高优先级的方式会生效。

text

优先级 1 (最高)    Cloud Provider（Bedrock / Vertex / Foundry）
优先级 2          ANTHROPIC_AUTH_TOKEN（Bearer Token）
优先级 3          ANTHROPIC_API_KEY（传统 API Key）
优先级 4          apiKeyHelper（自定义凭证脚本）
优先级 5          CLAUDE_CODE_OAUTH_TOKEN（长期 OAuth 令牌）
优先级 6 (最低)    Subscription OAuth（交互式登录，默认）

每种认证方式都有其特定的适用场景和配置方法，下面逐一展开。

三、云服务商认证（最高优先级）

如果通过环境变量设置了云服务商凭证，Claude Code 会优先使用对应的云 AI 服务，完全绕过 Anthropic API。这对于已经有 AWS/GCP/Azure 合同的企业来说，可以统一账单和合规管理。

bash

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=true
# 配置 AWS 凭证（可通过 AWS CLI、环境变量或 IAM Role）
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=true
# 配置 GCP 凭证
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=true
# 配置 Azure 凭证
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=https://...

注意事项：

云服务商认证的优先级最高，一旦启用，其他所有认证方式都会被忽略
需要对应的云服务账户有 Anthropic 模型的使用权限
不同云商支持的 Claude 模型版本可能不同

四、Bearer Token 认证

ANTHROPIC_AUTH_TOKEN 是新增的认证方式，使用标准的 Authorization: Bearer 头部（而不是 API Key 的 X-Api-Key 头部）。这一设计主要是为了支持网关/代理路由场景——当你的请求需要经过一个 API 网关转发到不同的模型提供商时，Bearer Token 比 API Key 更容易集成到标准 OAuth 2.0 流程中。

bash

# 设置 Bearer Token
export ANTHROPIC_AUTH_TOKEN="sk-ant-auth-token...xxxx"

# Claude Code 自动使用此 Token
claude -p "Hello"

与 API Key 的区别：

Bearer Token 通过 Authorization: Bearer 头发送
API Key 通过 X-Api-Key 头发送
Bearer Token 优先级更高（优先级 2 vs 优先级 3）
Bearer Token 更适合反向代理和网关场景

五、API Key 认证

5.1 获取 API Key

访问 Anthropic Console
点击 "Create Key"
复制并安全存储密钥

5.2 配置 API Key

bash

# 方式一：环境变量（推荐用于 CI/CD）
export ANTHROPIC_API_KEY="sk-ant-api...xxxx"

# 方式二：Claude Code 配置命令
claude auth login --api-key sk-ant-api...xxxx

# 方式三：写入配置文件（~/.claude/settings.json）
cat > ~/.claude/settings.json << 'EOF'
{
  "apiKey": "sk-ant-api...xxxx"
}
EOF

环境变量方式是最灵活的选择，特别适合 CI/CD 和容器化部署——你可以通过 CI 平台的 Secret 管理机制注入密钥，无需将敏感信息写入任何文件。

5.3 在 CI/CD 中使用 API Key

yaml

# GitHub Actions 示例
name: Claude Code CI
on: [push]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash
      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review all changes in the last commit" \
            --output-format json \
            > review-result.json

5.4 API Key 的局限性

API Key 仅在本地 CLI 和 CI 环境中有效。在 Claude Code Desktop 或 Cloud Session 模式下，API Key 和 apiKeyHelper 不会被使用——这些环境默认使用 OAuth 认证。

六、自定义脚本认证（apiKeyHelper）

当需要动态生成或定期轮换凭证时，可以使用 apiKeyHelper 配置。Claude Code 会调用指定脚本获取凭证，并在凭证过期（HTTP 401）或达到 TTL 后自动重新获取。

6.1 配置

json

// ~/.claude/settings.json
{
  "apiKeyHelper": {
    "command": "/path/to/get-creds.sh",
    "ttl": 300  // 可选，缓存时间（秒），默认 300
  }
}

bash

#!/bin/bash
# get-creds.sh — 从密钥管理服务获取临时 API Key
# 脚本需向 stdout 输出裸 API Key（不含换行以外的额外字符）

vault read -field=api_key secret/claude/production

6.2 适用场景

企业密钥管理（Vault / AWS Secrets Manager / GCP Secret Manager）
短期有效、自动轮换的临时凭证
合规要求严格、密钥必须集中管理的团队

6.3 注意事项

脚本必须输出纯文本 API Key（无 JSON 包装、无额外输出）
TTL 到期后或收到 HTTP 401 时，Claude Code 会自动重新执行脚本
脚本路径建议使用绝对路径，避免 PATH 解析问题

七、OAuth Token 认证（长期令牌）

CLAUDE_CODE_OAUTH_TOKEN 是专为自动化场景设计的长效认证方式。通过 claude setup-token 命令可以生成有效期长达 1 年的 OAuth Token，适合 CI/CD、定时任务和后台服务使用。

bash

# 生成长期 OAuth Token（交互式，需要浏览器授权）
claude setup-token

# 输出示例：
# ✅ Token generated: claude-code-token-xxxxx...yyyyy
# ℹ️  Token expires: 2027-06-10 (365 days)

bash

# 在 CI/CD 中使用 Token
export CLAUDE_CODE_OAUTH_TOKEN="claude-code-token-xxxxx...yyyyy"

claude -p "Run daily code quality check"

7.1 OAuth 刷新令牌（完全自动化）

对于需要完全无人值守的场景，可以同时设置刷新令牌和作用域，实现 OAuth Token 的自动续期：

bash

export CLAUDE_CODE_OAUTH_TOKEN="claude-code-token-xxxxx"
export CLAUDE_CODE_OAUTH_REFRESH_TOKEN="claude-code-refresh-yyyyy"
export CLAUDE_CODE_OAUTH_SCOPES="read write"  # 可选，限制令牌权限

八、Subscription OAuth（默认流程）

这是 Claude Code 默认使用的认证方式——通过浏览器完成 Anthropic 账户的交互式授权。

8.1 首次登录

bash

# 安装后首次运行，自动触发 OAuth 流程
claude

终端会输出类似如下信息：

text

🔐 Authenticate with Anthropic
Opening browser for authentication...

If the browser doesn't open automatically, visit:
https://console.anthropic.com/authorize?code_challenge=xxxxx&state=yyyyy

Waiting for authentication...

OAuth 流程使用 PKCE（Proof Key for Code Exchange）增强安全性，适合命令行应用这种无法安全存储客户端密钥的场景。

8.2 令牌管理

OAuth 使用刷新令牌机制，将"长期访问权限"和"短期访问凭证"分离开来：

访问令牌（Access Token）：短期有效（通常 1 小时），用于实际 API 请求
刷新令牌（Refresh Token）：长期有效，用于获取新的访问令牌
自动刷新：Claude Code 在访问令牌过期前自动刷新，无需用户干预

bash

# 查看当前认证状态
claude auth status

# 输出示例:
# Authenticated via OAuth
# Account: user@example.com
# Plan: Claude Pro
# Expires: 2026-06-11T10:30:00Z

8.3 多账户切换

bash

# 退出当前 OAuth 认证
claude auth logout

# 重新认证（可切换账户）
claude auth login

# 使用特定工作账户
claude auth login --account work

九、SSO 企业单点登录

9.1 企业账户配置

对于使用 Anthropic 企业版的团队，SSO 认证通过组织提供的身份提供商（IdP）完成。企业 SSO 的核心优势在于集中化的身份管理——管理员可以从一个控制台管理所有成员的访问权限，统一设置安全策略，并获取完整的审计日志。

bash

# SSO 登录
claude auth login --sso --organization your-org-id

# 或设置环境变量
export CLAUDE_SSO_ORGANIZATION="your-org-id"
claude auth login --sso

9.2 SAML/OIDC 集成

企业 SSO 通常基于 SAML 或 OIDC 协议：

text

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Claude   │───▶│  IdP     │───▶│  User    │───▶│  Claude   │
│ Code     │    │ (Okta/   │    │  Login   │    │  API     │
│          │◀───│  ADFS)   │◀───│  Prompt  │◀───│          │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

9.3 SSO 策略管理

企业管理员可在控制台配置：

会话超时：强制定期重新认证
IP 白名单：限制可访问的 IP 范围
设备管理：仅允许注册设备访问
MFA 强制：多因素认证，增强安全性
审批流程：新成员加入需管理员审批

bash

# 查看当前组织的 SSO 策略
claude auth policy list

# 输出示例:
# Organization: acme-corp
# SSO Provider: Okta
# Session Timeout: 8h
# IP Restriction: 10.0.0.0/8
# MFA Required: Yes

十、认证方式对比与选型指南

特性	Cloud Provider	Bearer Token	API Key	OAuth Token	Subscription OAuth	SSO
适用场景	有云合同的企业	API 网关/代理	CI/CD、自动化	长期自动化任务	个人日常开发	企业团队
安全性	最高（云 IAM）	高	中（需妥善存储）	高（1 年有效期）	高（自动刷新）	最高（集中管理）
配置复杂度	中	低	低	中	低	中
MFA 支持	✅（云 IAM）	❌	❌	❌	✅（可选）	✅
自动化	✅	✅	✅	✅	❌（需浏览器）	❌
有效期	云 IAM 管理	自定义	手动轮换	1 年	长期（自动刷新）	集中管理
审计日志	云审计	网关日志	需自行记录	有限	个人	企业级审计

10.1 选型决策树

text

是否有 AWS/GCP/Azure 云合同？
├── 是 → 使用 Cloud Provider（Bedrock / Vertex / Foundry）
└── 否 → 是否在企业环境中？
    ├── 是 → 使用 SSO
    └── 否 → 是否需要完全无人值守的自动化？
        ├── 是 → 是否有 API 网关/代理？
        │   ├── 是 → 使用 Bearer Token（ANTHROPIC_AUTH_TOKEN）
        │   └── 否 → 是否需要 1 年有效期？
        │       ├── 是 → 使用 OAuth Token（CLAUDE_CODE_OAUTH_TOKEN）
        │       └── 否 → 使用 API Key（ANTHROPIC_API_KEY）
        └── 否 → 使用 Subscription OAuth（默认交互式登录）

十一、常见认证问题排查

11.1 问题 1：OAuth 令牌过期

bash

# 症状: "Authentication expired" 或 "Token refresh failed"

# 解决方案: 重新认证
claude auth logout
claude auth login

# 检查本地凭证文件权限
ls -la ~/.claude/credentials.json 2>/dev/null
# macOS: 检查 Keychain
security find-generic-password -a claude-code 2>/dev/null
# Linux: 检查 Secret Service
secret-tool lookup service claude-code 2>/dev/null

11.2 问题 2：API Key 无效

bash

# 症状: "Invalid API key" 或 "401 Unauthorized"

# 验证 Key 格式（应以 sk-ant-api 开头）
echo $ANTHROPIC_API_KEY | grep -c "^sk-ant-api"
# 应输出 1

# 检查 Key 是否被吊销
curl -s -o /dev/null -w "%{http_code}" \
  https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
# 200 = 有效, 401 = 无效

11.3 问题 3：多个认证方式冲突

bash

# 症状: 使用了错误的认证方式

# 查看当前生效的认证方式
claude auth status

# 检查所有环境变量
env | grep -E "^(ANTHROPIC_|CLAUDE_CODE_)" | sort

# 如要强制使用特定方式，取消设置高优先级变量
unset ANTHROPIC_AUTH_TOKEN       # 禁用 Bearer Token
unset CLAUDE_CODE_USE_BEDROCK    # 禁用 Bedrock
unset ANTHROPIC_API_KEY          # 禁用 API Key

11.4 问题 4：网络代理导致认证失败

bash

# 症状: "Connection refused" 或 "Timeout"

# 配置代理
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# 或使用 .npmrc 配置（npm 安装方式）
echo "https-proxy=http://proxy.company.com:8080" >> ~/.npmrc

# 重试认证
claude auth login

11.5 问题 5：云服务商认证失败

bash

# 症状: "Bedrock access denied" 或 "Vertex API error"

# 检查云服务商凭证是否有效
# AWS
aws sts get-caller-identity

# GCP
gcloud auth print-access-token

# Azure
az account show

# 确认已安装对应云 CLI 工具
which aws gcloud az 2>/dev/null || echo "Missing CLI tool"

十二、真实经验与踩坑

12.1 经验 1：npm 全局安装与原生安装冲突

场景：团队中有人用 npm 全局安装，有人用原生 curl 安装，升级时版本行为不一致
问题：原生安装已发布 v2.1.158，但 npm 包的自动更新机制不同，导致部分成员无法使用最新特性
解决方案：统一使用原生安装（curl/Homebrew/WinGet），享受自动后台更新；npm 仅作备用，并定期执行 npm update -g @anthropic-ai/claude-code

12.2 经验 2：OAuth Token 在 CI 中过期

场景：CI 流水线使用 Subscription OAuth 运行夜间代码审查任务
问题：访问令牌有效期仅 1 小时，中途过期导致任务失败，刷新令牌又因网络波动失败
解决方案：CI 环境改用 CLAUDE_CODE_OAUTH_TOKEN（1 年有效期），搭配 CLAUDE_CODE_OAUTH_REFRESH_TOKEN 确保完全自动化续期

十三、落地检查清单

验证 claude --version 输出 >= v2.1.154
运行 claude auth status 确认当前认证方式和状态
检查认证优先级是否符合预期（无意外的高优先级认证覆盖）
API Key / OAuth Token 存储在环境变量中，未写入配置文件
团队项目已通过版本控制共享统一的认证规范
原生安装已启用自动后台更新，无需手动 claude upgrade

十四、总结

Claude Code 的认证体系已经从单一的 API Key 模式演进为多级优先级的现代架构：

认证方式	优先级	一句话总结
Cloud Provider	1（最高）	已有云合同企业的首选
Bearer Token	2	网关/代理场景的最佳选择
API Key	3	CI/CD 自动化标配
apiKeyHelper	4	企业动态凭证管理
OAuth Token	5	1 年有效期的无人值守认证
Subscription OAuth	6（最低）	个人开发者的默认方案

理解认证机制的优先级和适用场景，能帮助你在不同环境下选择最合适的方案。下一章我们将进入 Claude Code 的核心功能之一——打印模式（-p），探索非交互式单任务的最佳实践。

十五、下篇预告

打印模式 (-p) 深度指南 — 掌握非交互式单任务执行模式，学习 JSON 输出格式化、CI 脚本集成、管道处理、超时控制和错误处理策略。适合自动化流水线、代码审查、批量文件处理等场景。

Claude Code 安装与认证 — 原生安装 / npm / API Key / OAuth Token / SSO / 云服务商

简介

目录

一、安装方式

1.1 原生安装（推荐）

1.2 npm 安装（备用）

1.3 Homebrew / WinGet

1.4 验证安装

二、认证方式总览

三、云服务商认证（最高优先级）

四、Bearer Token 认证

五、API Key 认证

5.1 获取 API Key

5.2 配置 API Key

5.3 在 CI/CD 中使用 API Key

5.4 API Key 的局限性

六、自定义脚本认证（apiKeyHelper）

6.1 配置

6.2 适用场景

6.3 注意事项

七、OAuth Token 认证（长期令牌）

7.1 OAuth 刷新令牌（完全自动化）

八、Subscription OAuth（默认流程）

8.1 首次登录

8.2 令牌管理

8.3 多账户切换

九、SSO 企业单点登录

9.1 企业账户配置

9.2 SAML/OIDC 集成

9.3 SSO 策略管理

十、认证方式对比与选型指南

10.1 选型决策树

十一、常见认证问题排查

11.1 问题 1：OAuth 令牌过期

11.2 问题 2：API Key 无效

11.3 问题 3：多个认证方式冲突

11.4 问题 4：网络代理导致认证失败

11.5 问题 5：云服务商认证失败

十二、真实经验与踩坑

12.1 经验 1：npm 全局安装与原生安装冲突

12.2 经验 2：OAuth Token 在 CI 中过期

十三、落地检查清单

十四、总结

十五、下篇预告