附录 G：认证与订阅系统 — 从 OAuth 到合规边界

本附录基于 Claude Code v2.1.88 源码分析其认证架构和订阅系统，并结合 2026 年 4 月 Anthropic 封禁第三方工具事件，分析开发者构建 Agent 时的合规边界。

G.1 双轨 OAuth 认证架构

Claude Code 支持两条截然不同的认证路径，服务两类用户群体。

G.1.1 Claude.ai 订阅用户

订阅用户（Pro/Max/Team/Enterprise）通过 Claude.ai 的 OAuth 端点认证：

用户 → claude login → claude.com/cai/oauth/authorize
  → 授权页面（PKCE flow）
  → 回调 → exchangeCodeForTokens()
  → OAuth access_token + refresh_token
  → 直接用 token 调用 Anthropic API（无需 API key）

// restored-src/src/constants/oauth.ts:18-20
const CLAUDE_AI_INFERENCE_SCOPE = 'user:inference'
const CLAUDE_AI_PROFILE_SCOPE = 'user:profile'

关键 scope：

• user:inference — 调用模型的权限
• user:profile — 读取账户信息
• user:sessions — 会话管理
• user:mcp — MCP 服务器访问
• user:file_upload — 文件上传

OAuth 配置（restored-src/src/constants/oauth.ts:60-234）：

G.1.2 Console API 用户

Console 用户（按量付费）通过 Anthropic 开发平台认证：

用户 → claude login → platform.claude.com/oauth/authorize
  → 授权（scope: org:create_api_key）
  → 回调 → exchangeCodeForTokens()
  → OAuth token → createAndStoreApiKey()
  → 生成临时 API key → 用 key 调用 API

区别：Console 用户多了一步——OAuth 后创建 API key，实际 API 调用走 key 认证而非 token 认证。

G.1.3 第三方提供商

除了 Anthropic 自有认证，Claude Code 还支持：

// restored-src/src/utils/auth.ts:208-212
type ApiKeySource =
  | 'ANTHROPIC_API_KEY'     // 环境变量
  | 'apiKeyHelper'          // 自定义命令
  | '/login managed key'    // OAuth 生成的 key
  | 'none'                  // 无认证

G.2 订阅层级与速率限制

G.2.1 四级订阅

源码中的订阅判断函数（restored-src/src/utils/auth.ts:1662-1711）揭示了完整的层级体系：

// restored-src/src/utils/auth.ts:1662-1711
function getSubscriptionType(): 'max' | 'pro' | 'team' | 'enterprise' | null
function isMaxSubscriber(): boolean
function isTeamPremiumSubscriber(): boolean  // Team with 5x rate limit
function getRateLimitTier(): string  // e.g., 'default_claude_max_20x'

G.2.2 速率限制层

getRateLimitTier() 返回的值直接影响 API 调用频率上限：

• default_claude_max_20x — Max 最高档，20 倍默认速率
• default_claude_max_5x — Max 标准档 / Team Premium
• 默认 — Pro 和普通 Team

G.2.3 Extra Usage（额外用量）

某些操作会触发额外计费（restored-src/src/utils/extraUsage.ts:4-24）：

function isBilledAsExtraUsage(): boolean {
  // 以下情况触发 Extra Usage 计费：
  // 1. Claude.ai 订阅用户使用 Fast Mode
  // 2. 使用 1M 上下文窗口模型（Opus 4.6, Sonnet 4.6）
}

支持的计费类型：

• stripe_subscription — 标准 Stripe 订阅
• stripe_subscription_contracted — 合同制
• apple_subscription — Apple IAP
• google_play_subscription — Google Play

G.3 Token 管理与安全存储

G.3.1 Token 生命周期

获取 token → 存储到 macOS Keychain → 使用时从 Keychain 读取
  → 过期前 5 分钟自动刷新 → 刷新失败重试（最多 3 次）
  → 全部失败 → 提示用户重新登录

关键实现（restored-src/src/utils/auth.ts）：

// 过期检查：5 分钟缓冲
function isOAuthTokenExpired(token): boolean {
  return token.expires_at < Date.now() + 5 * 60 * 1000
}

// 自动刷新
async function checkAndRefreshOAuthTokenIfNeeded() {
  // 带重试逻辑的 token 刷新
  // 失败时清除缓存，下次调用重新获取
}

G.3.2 安全存储

• macOS：Keychain Services（加密存储）
• Linux：libsecret / 文件系统回退
• 子进程传递：通过 File Descriptor（CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR），避免环境变量泄露
• API Key Helper：支持自定义命令获取 key，默认 5 分钟缓存 TTL

G.3.3 登出清理

performLogout()（restored-src/src/commands/logout/logout.tsx:16-48）执行完整清理：

1. 刷新遥测数据（确保不丢失）
2. 移除 API key
3. 擦除 Keychain 中的所有凭证
4. 清除配置中的 OAuth 账户信息
5. 可选：清除 onboarding 状态
6. 失效所有缓存：OAuth token、用户数据、beta feature、GrowthBook、policy limits

G.4 权限与角色

OAuth profile 返回的组织角色决定了用户的能力边界：

// restored-src/src/utils/billing.ts
// Console 计费访问
function hasConsoleBillingAccess(): boolean {
  // 需要：非订阅用户 + admin 或 billing 角色
}

// Claude.ai 计费访问
function hasClaudeAiBillingAccess(): boolean {
  // Max/Pro 自动有
  // Team/Enterprise 需要 admin, billing, owner, 或 primary_owner
}

G.5 遥测与账户追踪

认证系统与遥测深度集成（restored-src/src/services/analytics/metadata.ts）：

• isClaudeAiAuth — 是否使用 Claude.ai 认证
• subscriptionType — 用于 DAU-by-tier 分析
• accountUuid / emailAddress — 遥测 header 中传递

关键分析事件：

tengu_oauth_flow_start          → 开始 OAuth 流程
tengu_oauth_success             → OAuth 成功
tengu_oauth_token_refresh_success/failure → token 刷新结果
tengu_oauth_profile_fetch_success → 获取 profile 成功

G.6 合规边界分析

G.6.1 背景：2026 年 4 月 OpenClaw 事件

Anthropic 于 2026 年 4 月正式封禁第三方工具通过 OAuth 使用订阅额度。核心原因：

1. 成本不可承受：OpenClaw 等工具 7×24 运行自动化 Agent，每天消耗 $1,000-5,000 API 成本，$200/月的 Max 订阅无法覆盖
2. 绕过缓存优化：Claude Code 的四层 prompt cache（详见第 13-14 章）能降低 90% 成本，第三方工具直接调 API 全是 cache miss
3. 条款修改：OAuth user:inference scope 限定为官方产品使用

G.6.2 行为分类

G.6.3 关键区分：走不走 Claude Code 的基础设施

这是最核心的判断标准：

安全路径:
  你的代码 → cc-sdk → claude CLI 子进程 → CC 基础设施（含缓存）→ API
  ↑ 走了 prompt cache，Anthropic 的成本可控

危险路径:
  你的代码 → 提取 OAuth token → 直接调 Anthropic API
  ↑ 绕过 prompt cache，每次请求都是 full price

Claude Code 的 getCacheControl() 函数（restored-src/src/services/api/claude.ts:358-374）精心设计了全局/组织/会话三级缓存断点。通过 CLI 发送的请求自动享受这套缓存优化。直接调 API 的第三方工具无法复用这些缓存——这正是成本问题的根源。

一键判断：是否 spawn claude 子进程？

这是最简洁的合规判断标准。所有通过 claude CLI 子进程通信的方式都走了 CC 的完整基础设施（prompt cache + 遥测 + 权限检查），Anthropic 的成本可控；直接调 API 则绕过了一切。

G.6.4 本书示例代码的合规性

本书第 30 章的 Code Review Agent 使用以下方式：

建议：

1. 不要从 ~/.claude/ 提取 OAuth token 用于其他用途
2. 不要构建 7×24 运行的自动化 daemon
3. 保留 CodexBackend 作为不依赖 Anthropic 订阅的替代方案
4. 如果需要高频自动化，使用 API key 按量付费而非订阅

G.7 关键环境变量索引