Claude-Code-Compiled/docs/API-CONFIG.md

Claude Code API 配置指南

基于 2026-03-31 泄露的 Claude Code CLI 源码 最后更新：2026-04-01

---

1. API 提供商概览

Claude Code 支持 4 种 API 后端，通过环境变量切换：

提供商	启用变量	说明
Direct API	默认（无需设置）	Anthropic 官方 API
AWS Bedrock	CLAUDE_CODE_USE_BEDROCK=1	AWS 托管的 Claude
Google Vertex AI	CLAUDE_CODE_USE_VERTEX=1	GCP 托管的 Claude
Azure Foundry	CLAUDE_CODE_USE_FOUNDRY=1	Azure 托管的 Claude

优先级判断逻辑（src/utils/model/providers.ts）：

export function getAPIProvider(): APIProvider {
  return isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK) ? 'bedrock'
    : isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX) ? 'vertex'
    : isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY) ? 'foundry'
    : 'firstParty'
}

---

2. Direct API（默认）

2.1 认证

环境变量	必需	说明
ANTHROPIC_API_KEY	✅	Anthropic API 密钥
ANTHROPIC_AUTH_TOKEN	—	Bearer token 替代方式

二选一，ANTHROPIC_API_KEY 优先级更高。也支持 OAuth 登录（/login 命令），token 存储在 ~/.claude/ 配置目录。

2.2 端点配置

环境变量	默认值	说明
ANTHROPIC_BASE_URL	https://api.anthropic.com	API 基础 URL
ANTHROPIC_UNIX_SOCKET	—	Unix socket 路径（替代 TCP）

自定义代理或本地网关时设置 ANTHROPIC_BASE_URL。代码中通过 isFirstPartyAnthropicBaseUrl() 判断是否为官方端点：

export function isFirstPartyAnthropicBaseUrl(): boolean {
  const baseUrl = process.env.ANTHROPIC_BASE_URL
  if (!baseUrl) return true
  const host = new URL(baseUrl).host
  return ['api.anthropic.com'].includes(host)
}

2.3 模型选择

环境变量	说明
ANTHROPIC_MODEL	主循环模型（最高优先级的用户可配变量）
ANTHROPIC_SMALL_FAST_MODEL	轻量模型（默认 Haiku，用于 token 估算等）
ANTHROPIC_DEFAULT_OPUS_MODEL	覆盖默认 Opus 模型
ANTHROPIC_DEFAULT_SONNET_MODEL	覆盖默认 Sonnet 模型
ANTHROPIC_DEFAULT_HAIKU_MODEL	覆盖默认 Haiku 模型

模型选择优先级（getMainLoopModel()）：

1. 会话中 /model 命令覆盖 — 最高
2. --model CLI 参数
3. ANTHROPIC_MODEL 环境变量
4. 用户 settings 中保存的模型
5. 内置默认值（Sonnet）

2.4 Beta 功能

环境变量	说明
ANTHROPIC_BETAS	追加 beta header（逗号分隔）

Claude Code 内部会自动附加多个 beta header，如 files-api-2025-04-14、oauth-2025-04-20 等。

2.5 请求自定义

环境变量	说明
ANTHROPIC_CUSTOM_HEADERS	自定义 HTTP 头（JSON 格式）
CLAUDE_CODE_EXTRA_BODY	请求体额外字段（JSON 格式）

---

3. AWS Bedrock

3.1 启用

export CLAUDE_CODE_USE_BEDROCK=1

3.2 认证

使用 AWS SDK 默认凭证链（@aws-sdk/credential-provider-node）：

• 环境变量：AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_SESSION_TOKEN
• AWS CLI 配置：~/.aws/credentials
• IAM Role（EC2 / ECS / Lambda）
• SSO

跳过 Bedrock 认证检查（开发/测试用）：

export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

3.3 区域配置

环境变量	默认值	说明
AWS_REGION / AWS_DEFAULT_REGION	us-east-1	全局 AWS 区域
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	—	轻量模型独立区域

3.4 端点

环境变量	说明
ANTHROPIC_BEDROCK_BASE_URL	自定义 Bedrock 端点

---

4. Google Vertex AI

4.1 启用

export CLAUDE_CODE_USE_VERTEX=1

4.2 认证

使用 google-auth-library 默认凭证链：

• GOOGLE_APPLICATION_CREDENTIALS — 服务账号 JSON 路径
• gcloud auth application-default login — 用户凭证
• Workload Identity（GKE / Cloud Run）

跳过 Vertex 认证检查：

export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

4.3 项目与区域

环境变量	必需	说明
ANTHROPIC_VERTEX_PROJECT_ID	✅	GCP 项目 ID
CLOUD_ML_REGION	—	默认区域（回退 us-east5）
VERTEX_REGION_CLAUDE_3_5_HAIKU	—	Claude 3.5 Haiku 专属区域
VERTEX_REGION_CLAUDE_HAIKU_4_5	—	Claude Haiku 4.5 专属区域
VERTEX_REGION_CLAUDE_3_5_SONNET	—	Claude 3.5 Sonnet 专属区域
VERTEX_REGION_CLAUDE_3_7_SONNET	—	Claude 3.7 Sonnet 专属区域

区域优先级：模型专属变量 > CLOUD_ML_REGION > 配置默认 > us-east5。

---

5. Azure Foundry

5.1 启用

export CLAUDE_CODE_USE_FOUNDRY=1

5.2 端点配置（二选一）

环境变量	说明
ANTHROPIC_FOUNDRY_RESOURCE	Azure 资源名，自动生成端点 https://{resource}.services.ai.azure.com/anthropic/v1/messages
ANTHROPIC_FOUNDRY_BASE_URL	完整端点 URL（优先级更高）

5.3 认证

方式	环境变量	说明
API Key	ANTHROPIC_FOUNDRY_API_KEY	直接使用密钥
Azure AD	—	无 API key 时自动使用 DefaultAzureCredential

Azure AD 支持的凭证方式：环境变量、Managed Identity、Azure CLI、Visual Studio Code 等。

跳过 Foundry 认证检查：

export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1

---

6. 代理（Proxy）

6.1 HTTP 代理

环境变量	优先级	说明
https_proxy	1	小写（最高优先级）
HTTPS_PROXY	2	大写
http_proxy	3	HTTP 代理
HTTP_PROXY	4	HTTP 大写
no_proxy / NO_PROXY	—	代理排除列表

6.2 代理行为

export function getProxyUrl(): string | undefined {
  return env.https_proxy || env.HTTPS_PROXY || env.http_proxy || env.HTTP_PROXY
}

NO_PROXY 支持逗号分隔的域名/IP 列表，支持通配符 *。

6.3 代理 DNS 解析

# 让代理端解析域名（适用于沙箱环境）
export CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1

---

7. mTLS 与 TLS 配置

环境变量	说明
CLAUDE_CODE_CLIENT_CERT	客户端证书文件路径
CLAUDE_CODE_CLIENT_KEY	客户端私钥文件路径
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	私钥密码
NODE_EXTRA_CA_CERTS	额外 CA 证书（Node.js 自动加载）

---

8. OAuth 认证

8.1 流程

Claude Code 实现了完整的 OAuth 2.0 流程（src/services/oauth/）：

1. 用户执行 /login
2. 浏览器打开 Anthropic 授权页面
3. 用户授权后回调到本地监听端口
4. 交换 access_token / refresh_token
5. Token 存储在 ~/.claude/ 安全存储中

8.2 OAuth Scopes

Scope	用途
user:inference	API 推理调用
user:profile	用户信息读取
user:sessions:claude_code	Claude Code 会话管理
user:mcp_servers	MCP 服务器管理
user:file_upload	文件上传
org:create_api_key	Console 端 API key 创建

8.3 OAuth 环境变量

环境变量	说明
CLAUDE_CODE_OAUTH_CLIENT_ID	自定义 OAuth client ID
CLAUDE_CODE_OAUTH_TOKEN	直接注入 OAuth token
CLAUDE_CODE_OAUTH_REFRESH_TOKEN	注入 refresh token
CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR	从文件描述符读取 token
CLAUDE_CODE_CUSTOM_OAUTH_URL	自定义 OAuth 端点 URL

---

9. 其他关键配置

9.1 会话与上下文

环境变量	默认值	说明
CLAUDE_CODE_MAX_CONTEXT_TOKENS	—	最大上下文 token 数
CLAUDE_CODE_MAX_OUTPUT_TOKENS	—	最大输出 token 数
CLAUDE_CODE_MAX_RETRIES	—	API 重试次数
CLAUDE_CODE_AUTO_COMPACT_WINDOW	—	自动压缩窗口大小
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	—	压缩阈值百分比

9.2 功能开关

环境变量	说明
CLAUDE_CODE_DISABLE_THINKING	禁用 thinking 模式
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING	禁用自适应 thinking
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	禁用非必要网络请求
CLAUDE_CODE_DISABLE_AUTO_MEMORY	禁用自动记忆提取
CLAUDE_CODE_DISABLE_CRON	禁用定时任务
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	禁用后台任务
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT	始终启用 extended thinking
CLAUDE_CODE_EFFORT_LEVEL	thinking effort 级别
CLAUDE_CODE_SIMPLE	简化模式（减少输出）
CLAUDE_CODE_BRIEF	简洁模式

9.3 调试与诊断

环境变量	说明
CLAUDE_DEBUG	调试模式
CLAUDE_CODE_DEBUG_LOGS_DIR	调试日志目录
CLAUDE_CODE_DEBUG_LOG_LEVEL	调试日志级别
CLAUDE_CODE_PROFILE_STARTUP	启动性能分析
CLAUDE_CODE_PROFILE_QUERY	查询性能分析
CLAUDE_CODE_DIAGNOSTICS_FILE	诊断输出文件
CLAUDE_CODE_JSONL_TRANSCRIPT	JSONL 格式对话记录

9.4 配置目录

环境变量	默认值	说明
CLAUDE_CONFIG_DIR	~/.claude	配置目录

配置目录结构：

~/.claude/
├── config.json          # 全局配置（模型、设置）
├── settings.json        # 用户设置
├── oauth-tokens.json    # OAuth token 存储
├── mcp-servers.json     # MCP 服务器配置
├── projects/            # 项目级配置
└── memory/              # 持久化记忆

---

10. 自定义模型选项

允许在模型选择菜单中添加自定义模型：

环境变量	说明
ANTHROPIC_CUSTOM_MODEL_OPTION	自定义模型 ID
ANTHROPIC_CUSTOM_MODEL_OPTION_NAME	显示名称
ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION	模型描述

---

11. 完整配置示例

11.1 Direct API（最简）

export ANTHROPIC_API_KEY=sk-ant-xxx
bun dist/bundle.js -p "hello"

11.2 自定义代理

export ANTHROPIC_API_KEY=sk-ant-xxx
export ANTHROPIC_BASE_URL=https://my-proxy.example.com
bun dist/bundle.js

11.3 AWS Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2
export AWS_ACCESS_KEY_ID=AKIAxxx
export AWS_SECRET_ACCESS_KEY=xxx
bun dist/bundle.js

11.4 Vertex AI

export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export CLOUD_ML_REGION=us-central1
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
bun dist/bundle.js

11.5 Azure Foundry + API Key

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=my-azure-resource
export ANTHROPIC_FOUNDRY_API_KEY=xxx
bun dist/bundle.js

11.6 带代理 + mTLS

export ANTHROPIC_API_KEY=sk-ant-xxx
export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1
export CLAUDE_CODE_CLIENT_CERT=/path/to/client.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
bun dist/bundle.js

11.7 调试模式

export ANTHROPIC_API_KEY=sk-ant-xxx
export CLAUDE_DEBUG=1
export CLAUDE_CODE_DEBUG_LOGS_DIR=/tmp/claude-debug
export CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose
bun dist/bundle.js

---

12. 认证优先级

Claude Code 的认证解析顺序（src/utils/auth.ts）：

1. 文件描述符注入 — CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR / CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR
2. 环境变量 — ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN
3. macOS Keychain — 安全存储的凭证
4. 配置文件 — ~/.claude/config.json 中的 API key
5. API key helper — CLAUDE_CODE_API_KEY_HELPER_TTL_MS 控制的外部脚本
6. OAuth 登录 — /login 流程获取的 token

---

13. 注意事项

1. isFirstPartyAnthropicBaseUrl() 影响行为 — 只有指向 api.anthropic.com 时才被视为官方端点，影响 bootstrap 请求、模型默认值等
2. 第三方提供商模型延迟 — Bedrock/Vertex/Foundry 的模型可用性滞后于 Direct API，代码中为它们保留了独立的默认模型分支
3. macOS Keychain 回退 — Linux 环境下安全存储回退到明文文件，注意权限控制
4. 代理 + mTLS 同时使用 — 代码同时支持 HTTPS 代理 + 客户端证书认证，按需组合
5. OAuth token 自动刷新 — withOAuth401Retry() 会自动处理 401 错误并刷新 token