Claude Code 如何配置 API：Key、网关与 Windows 验证步骤
简答：Claude Code 配置 API 先判断认证场景：直连 API 使用 ANTHROPIC_API_KEY，网关按要求使用 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，云平台则按对应变量配置。设置后用 claude -p 和 /status 验证。
定义：Claude Code API 配置，是为 Claude Code 指定认证凭证、请求入口和模型，使终端请求能够发送到 Anthropic API、兼容网关或云平台。
先判断：你需要哪种 API 配置
如果你只是使用个人订阅，Claude Code 可以通过 claude.ai 账号登录；如果要按 API 用量计费或接入开发环境，应使用 Claude Console 凭证；如果组织提供了网关，则需要使用网关地址和管理员发放的凭证。官方文档将这些认证路径分别列为 Claude.ai、Claude Console、Amazon Bedrock、Google Cloud’s Agent Platform 和 Microsoft Foundry。详情可查看 Claude Code Authentication。
| 场景 | 主要凭证 | 需要确认的内容 | 适合方式 |
|---|---|---|---|
| Claude.ai 订阅登录 | 账号登录 | 订阅和组织登录权限 | 直接运行 claude 后登录 |
| Claude Console API | ANTHROPIC_API_KEY | API Key、工作区和用量限制 | 本地开发、脚本和 API 测试 |
| Anthropic 兼容网关 | ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY | Base URL、请求头类型、模型名 | 组织路由、审计或统一用量管理 |
| 云平台 | 云平台身份或平台凭证 | IAM、区域、部署名或版本名 | 已有云账号和模型部署的团队 |
本文是独立第三方接入指南，不代表 Claude Code 或 Anthropic 官方。第三方兼容 API 的 Base URL、凭证类型和模型名必须以供应商当前文档为准，本文不填写具体服务商地址或模型 ID。
从零配置 Claude Console API
1. 创建并保存 API Key
在 Claude Console 的 API Keys 页面创建密钥，并在创建时保存完整值。官方文档说明，创建密钥时可以选择名称、过期时间、关联账号和工作区范围；密钥应存放在密钥管理工具或安全的本地环境中，不要提交到代码仓库、共享项目配置或公开日志。创建步骤见 Get your Claude API key 和 Claude API Authentication。
2. macOS、Linux 和 WSL 设置变量
当前终端临时设置：
export ANTHROPIC_API_KEY="<YOUR_API_KEY>"
希望每次打开终端都生效，可将这行加入实际使用的 ~/.bashrc 或 ~/.zshrc，再重新打开终端。官方环境变量文档说明，Shell 中设置的变量只对当前终端及其启动的程序有效；settings 文件中的变量则会在 Claude Code 启动时读取。参考 Claude Code Environment variables。
不打印密钥内容，只检查是否为空和长度：
if [ -n "${ANTHROPIC_API_KEY:-}" ]; then echo "ANTHROPIC_API_KEY is set (length ${#ANTHROPIC_API_KEY})"; else echo "ANTHROPIC_API_KEY is empty"; fi
3. Windows PowerShell 和 CMD 设置变量
| 终端 | 当前窗口设置 | 持久设置 | 状态检查 |
|---|---|---|---|
| PowerShell | $env:ANTHROPIC_API_KEY = "<YOUR_API_KEY>" | [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "<YOUR_API_KEY>", "User") | if ([string]::IsNullOrEmpty($env:ANTHROPIC_API_KEY)) { "empty" } else { "set length $($env:ANTHROPIC_API_KEY.Length)" } |
| CMD | set ANTHROPIC_API_KEY=<YOUR_API_KEY> | setx ANTHROPIC_API_KEY "<YOUR_API_KEY>" | if defined ANTHROPIC_API_KEY (echo set) else (echo empty) |
| WSL | export ANTHROPIC_API_KEY="<YOUR_API_KEY>" | 加入 ~/.bashrc 或 ~/.zshrc | if [ -n "${ANTHROPIC_API_KEY:-}" ]; then echo set; else echo empty; fi |
PowerShell 的 $env: 和 CMD 的 set 只影响当前窗口；SetEnvironmentVariable、setx 和 Shell profile 用于后续会话。设置后要打开新的终端窗口，避免继续使用旧环境。命令形式可核对 官方环境变量参考。
使用 settings.json 持久化配置
如果需要让 Claude Code 在不同项目和后台会话中都读取配置，可以把变量放在 settings 文件的 env 字段。用户级文件是 macOS、Linux、WSL 下的 ~/.claude/settings.json，Windows 对应 %USERPROFILE%\.claude\settings.json；项目级本地文件是项目目录内的 .claude/settings.local.json。项目共享文件 .claude/settings.json 会随仓库共享，不应放个人 API Key。文件作用域见 Settings files and precedence。
修改已有文件前先备份并确认目录存在：
mkdir -p ~/.claude && cp ~/.claude/settings.json ~/.claude/settings.json.bak 2>/dev/null || true
Windows PowerShell 可先执行：
New-Item -ItemType Directory -Force "$HOME\.claude" | Out-Null; if (Test-Path "$HOME\.claude\settings.json") { Copy-Item "$HOME\.claude\settings.json" "$HOME\.claude\settings.json.bak" -Force }
备份后再把变量合并到现有 JSON 的 env 对象中，不要用整体重定向命令覆盖原配置。最小结构如下：
{"env":{"ANTHROPIC_API_KEY":"<YOUR_API_KEY>"}}
如果文件已有权限、模型或其他字段，应保留原字段，只新增或修改 env。个人密钥不要放进项目共享文件；手动创建 .claude/settings.local.json 时，将它加入项目的 gitignore。
Shell、settings 文件、命令行参数和组织托管设置可能同时影响最终配置。不要凭猜测判断哪一个生效，修改后进入 Claude Code 运行 /status，确认实际认证来源和 Base URL。环境变量的读取方式与设置文件范围见 Environment variables，设置文件的合并规则见 Settings files and precedence。
接入 Anthropic 兼容 API 或组织网关
变量与请求头如何对应
| 供应商或网关说明 | Claude Code 变量 | 对应请求头 |
|---|---|---|
| 要求 Bearer token 或 Authorization header | ANTHROPIC_AUTH_TOKEN | Authorization: Bearer <value> |
| 要求 API key 或 x-api-key | ANTHROPIC_API_KEY | x-api-key: <value> |
| 凭证需要轮换或从密钥库读取 | apiKeyHelper | 由帮助程序按官方机制提供 |
Claude Code 官方网关文档明确区分了 Bearer token、API key 和 apiKeyHelper。如果供应商没有说明凭证类型，不要根据变量名猜测；先向供应商或管理员确认。详见 Connect Claude Code to an LLM gateway。
网关地址使用 ANTHROPIC_BASE_URL。优先填写供应商文档给出的根地址，并确认客户端与网关约定的 Messages API 路径只添加一次。Claude Code 的网关兼容性文档说明，兼容网关需要处理 Claude Code 使用的 API 格式、请求头、请求体字段和流式响应；不能把只支持 OpenAI Chat Completions 的地址直接当作 Anthropic Messages 接口使用。参考 Claude Code gateway compatibility guide。
通用配置示例只使用占位符：
export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="<GATEWAY_TOKEN>"
claude -p "请只回复：API 已连通"
第三方兼容 API 的具体域名、模型名、认证头和路径可能不同，应以其当前文档为准。模型位置使用 <MODEL_ID> 占位，不将某个平台的模型 ID 复制到另一个连接方式中。
用 curl 验证 Anthropic Messages 接口
如果你需要绕过 Claude Code，单独验证网关是否接受 Anthropic Messages 请求，可以使用以下占位命令。它不会输出密钥本身：
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: <API_VERSION>" -H "content-type: application/json" -d '{"model":"<MODEL_ID>","max_tokens":64,"messages":[{"role":"user","content":"Reply with OK"}]}'
如果网关要求 Bearer token，应将认证头改为：
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
Anthropic API 官方文档列出了 Authorization、x-api-key、anthropic-version 和 content-type 的用途；API 端点和版本要求见 API overview 与 API versions。
启动、选择模型与验证请求
最小验证命令
安装完成后先确认命令可用：
claude --version
设置凭证后，在同一个终端运行：
claude -p "请只回复：API 已连通"
Claude Code CLI 官方参考将 claude -p 定义为发送查询后退出的打印模式。进入交互会话后运行 /status，可以查看认证来源和 Base URL；网关文档还建议发送一条普通测试消息确认请求确实成功。参考 CLI reference 和 网关连接验证说明。
如何指定模型
/model 是选择或切换模型的入口，不等于查询当前 API Key 可以访问的全部模型。模型可以是别名、Anthropic API 的完整模型名、Amazon Bedrock 的推理配置 ARN、Microsoft Foundry 的部署名或 Google Cloud’s Agent Platform 的版本名。兼容网关则应使用供应商确认的模型标识。模型配置规则见 Model configuration。
如果只想临时指定模型，可使用官方支持的模型参数或进入会话后使用 /model。不要把 ANTHROPIC_BASE_URL 当成模型选择变量：它只改变请求发送到哪里，不决定由哪个模型回答。
报错速查：原因、修复、验证
| 现象 | 常见方向 | 先做什么 |
|---|---|---|
| 401 或 invalid API key | 凭证为空、过期、撤销，或请求头类型不匹配 | 检查变量是否为空，确认 API Key 对应 x-api-key，Bearer token 对应 Authorization，再运行 claude -p |
| 403 | 凭证没有访问指定资源的权限 | 检查工作区、云平台 IAM 或网关权限，不要将 403 当成限速；修复后重新发最小请求 |
| 404 | 路径或资源不存在，常见于 Base URL 重复拼接 | 确认 Base URL、/v1/messages 和模型资源路径只按供应商文档添加一次，再用 curl 验证 |
| 429 | 请求速率、输入或输出速率、用量层级或支出限制 | 查看控制台限额，降低并发并按响应中的 retry-after 等信息处理，不要通过更换模型 ID 排查认证 |
| claude 找不到 | 安装目录未加入 PATH，或终端未重新打开 | 重新打开终端并运行 claude --version，再检查当前终端的 PATH |
| 流式响应中断 | 网关未正确转发 SSE、事件或响应头 | 先用非流式最小请求区分 API 与流式链路，再检查网关兼容性和 SSE 转发 |
Anthropic 官方错误文档将 401 定义为认证错误、403 定义为权限错误、404 定义为资源不存在、429 定义为限速或相关用量限制；429 的具体处理应结合控制台限制和响应头。错误码对照见 Claude API errors，速率和支出限制见 Rate limits。
Key 安全、网关可信度与费用控制
API Key 会产生调用权限和费用风险。使用任何兼容 API 或组织网关前，至少确认四点：凭证由谁保管、请求内容是否经过第三方、日志保留多久、是否提供轮换和撤销机制。不要把真实 Key 放进共享仓库、截图、工单或命令输出；需要轮换时优先使用密钥管理系统或官方支持的 apiKeyHelper 机制。Anthropic 官方认证文档建议使用密钥管理工具、定期轮换，并在怀疑泄露时禁用或删除密钥。
费用控制可以从三处入手：在 Claude Console 查看用量和组织限额；为组织或工作区设置支出上限；在网关侧配置额度、并发和日志策略。官方 Rate limits 文档说明，速率限制和支出限制是不同概念，达到不同限制时可能返回不同错误。没有实际账单数据时，不应根据本文推算具体价格或耗时。
配置完成后的自查清单
- 场景：已确认使用订阅登录、Console、兼容网关还是云平台。
- 凭证：已确认
ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN的请求头映射。 - 变量：只在当前终端或 settings 文件中保留需要的变量，没有遗留旧 Base URL。
- 文件：修改 settings 前已备份，个人密钥没有放入项目共享文件。
- 路径：Base URL 和 Messages API 路径没有重复拼接。
- 模型：模型名来自当前平台或网关文档，未混用不同平台的模型 ID。
- 验证：已用
claude -p完成最小请求，并通过/status核对认证来源。 - 安全：检查命令只显示是否为空或长度，没有打印密钥片段。
常见问题
Claude.ai 订阅可以直接当作 Claude API Key 使用吗？
不能把两者视为同一种凭证。订阅使用账号登录路径；Claude API Key 需要在 Claude Console 创建，或使用组织提供的其他认证方式。
ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 怎么选？
网关要求 Bearer token 或 Authorization header 时使用 ANTHROPIC_AUTH_TOKEN；要求 API key 或 x-api-key 时使用 ANTHROPIC_API_KEY。直连 API 的具体认证方式以官方文档为准。
ANTHROPIC_BASE_URL 应该填什么？
填写供应商或网关文档提供的入口地址，并确认 /v1/messages 等路径只添加一次。不要把某个 OpenAI Chat Completions 地址直接当作 Anthropic Messages 接口。
为什么设置 API Key 后仍然出现登录提示？
先确认变量是在启动 claude 的同一个终端中设置的，再检查 settings 文件是否存在旧值。进入会话运行 /status，查看当前认证来源；必要时退出旧登录后重新启动。
如何确认配置成功但不泄露密钥？
只输出变量是否为空或长度，不要 echo 密钥内容；随后运行 claude -p 发送最小请求，并在交互会话中运行 /status 核对认证来源和 Base URL。
Windows PowerShell、CMD 和 WSL 的设置命令一样吗？
不一样。PowerShell 使用 $env:，CMD 使用 set 或 setx，WSL 使用 export。持久化后都应打开新的终端窗口，再运行状态检查和最小请求。
429 应该更换模型还是调整认证变量？
429 主要应检查速率、并发、用量层级或支出限制。先查看控制台限额和响应头，必要时降低并发并按 retry-after 等信息重试；它不是优先更换认证变量的错误。
相关阅读
参考资料
- Get your Claude API key - Claude Platform Docs（platform.claude.com）
- Authentication - Claude Platform Docs（platform.claude.com）
- Environment variables - Claude Code Docs（code.claude.com）
- Connect Claude Code to an LLM gateway - Claude Code Docs（code.claude.com）
- Claude Code gateway compatibility guide - Claude Code Docs（code.claude.com）
- API overview - Claude Platform Docs（platform.claude.com）
- Versions - Claude Platform Docs（platform.claude.com）
- Claude API errors - Claude Platform Docs（platform.claude.com）
- Rate limits - Claude Platform Docs（platform.claude.com）