Claude Code 怎么接入 API？

更新于 2026-10-23 · soleapi.cyou

简答：Claude Code 可以通过 Claude 订阅登录、Anthropic API Key、Amazon Bedrock、Google Cloud 的 Agent Platform，或兼容 Anthropic Messages API 的网关接入。个人开发者通常先用订阅登录或 API Key；团队需要统一凭证、预算和审计时，再考虑网关。配置后用 claude auth status、/status 或一次最小请求确认实际认证来源。

定义：Claude Code 接入 API，是为终端工具选择一种认证与模型服务来源，并通过登录、环境变量或网关地址让 Claude Code 发起模型请求。

先看接入方式：你需要的是订阅登录，还是 API Key

本站为第三方指南，非 Claude Code 官方，以其官网为准。Claude Code 当前支持 Claude 账户登录、Console 账户/API Key，以及 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 等云平台方式；兼容 Anthropic 支持 API 格式的企业网关也可以接入。具体可用能力会受当前版本、账户类型、地区和服务商配置影响，以下内容截至2026年10月23日整理。

方式	适合谁	主要配置	费用与凭证边界
Claude 订阅登录	个人使用 Claude Code，想用统一账户登录	运行 `claude` 后按浏览器提示登录	使用订阅对应的 Claude Code 访问方式，不等同于 API 按量 Key
Anthropic API Key	脚本、开发环境、希望直接使用 API 账单的用户	`ANTHROPIC_API_KEY` 或 Console 认证	请求使用 Claude API 认证与计费体系，具体额度和价格以官方页面为准
Amazon Bedrock	已有 AWS 账户、区域和模型权限的团队	`CLAUDE_CODE_USE_BEDROCK=1`、AWS 凭证和区域	凭证、权限和费用由 AWS 环境承担
Google Cloud Agent Platform	已有 Google Cloud 项目和身份认证配置的团队	`CLAUDE_CODE_USE_VERTEX=1`、项目 ID 和区域	凭证、权限和费用由 Google Cloud 项目承担
第三方 LLM Gateway	需要统一密钥、预算、限速、审计或路由的组织	`ANTHROPIC_BASE_URL` 加网关凭证	请求先经过网关；网关维护方可看到或处理请求，兼容性和数据政策需自行核对

官方文档明确区分 Claude Code 的账户登录与 Console/API 使用方式；Pro 或 Max 订阅可以连接 Claude Code，但如果设置并批准 API Key，Claude Code 会改用该 Key。开始前建议先决定“由谁承担认证和费用”，再写环境变量，避免误以为订阅额度与 API Key 额度是同一套。

参考：Claude Code 官方安装与认证文档、Pro 或 Max 计划使用 Claude Code 的官方说明。

标准流程：安装 Claude Code、创建 Key，再验证请求

安装并检查版本。macOS、Linux 或 WSL 可运行 curl -fsSL https://claude.ai/install.sh | bash；Windows PowerShell 可运行 irm https://claude.ai/install.ps1 | iex。安装完成后重新打开终端，执行 claude --version；如需查看安装和设置诊断，可执行 claude doctor。
创建 Anthropic API Key。进入 Claude Console 的 API keys 页面，查看已有 Key 或创建新 Key。官方 API 文档说明，API Key 用于 Claude API 请求，密钥应只保存在受控环境，不要提交到 Git 仓库、截图或聊天记录。
在当前终端设置 Key。Bash、Zsh 或 WSL 使用 export ANTHROPIC_API_KEY="你的API_KEY"；Windows PowerShell 使用 $env:ANTHROPIC_API_KEY = "你的API_KEY"。PowerShell 中的 $env: 设置只对当前会话及其启动的进程生效，关闭窗口后需要重新设置。
启动 Claude Code。在同一个终端运行 claude。如果 Claude Code 询问是否使用环境变量中的 Key，确认前先检查你是否确实要走 API 认证，而不是订阅登录。
确认认证来源。运行 claude auth status 查看认证状态；进入交互会话后运行 /status，检查当前账户、凭证来源和 Base URL。CLI 官方参考中列出了 api_key、claude.ai、third_party 等认证状态。

如果你只想使用订阅登录，不要设置 ANTHROPIC_API_KEY。直接运行 claude 并按浏览器提示登录即可；如果之前使用过 Console 或 API Key，可运行 /logout，再执行 claude update，重新启动终端后登录正确账户。

官方 API Key 页面：创建和管理 Claude API Key；CLI 命令参考：Claude Code CLI reference。

macOS、Linux、WSL 和 Windows 的环境变量写法

环境变量适合先做一次连接验证。它们通常只影响当前终端启动的 Claude Code 进程；如果需要长期保存，可以写入个人 Shell 配置文件或 Claude Code 的用户级设置文件，但不要把真实密钥放进项目共享配置。

macOS、Linux、WSL：Bash 或 Zsh

设置官方 API Key：export ANTHROPIC_API_KEY="你的API_KEY"
启动工具：claude
检查变量是否存在，不打印密钥：test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY 已设置" || echo "未设置"
需要持久化时，可将设置写入 ~/.zshrc 或 ~/.bashrc，然后重新加载对应配置文件。

Windows PowerShell

设置官方 API Key：$env:ANTHROPIC_API_KEY = "你的API_KEY"
启动工具：claude
只检查是否存在：if ($env:ANTHROPIC_API_KEY) { "ANTHROPIC_API_KEY 已设置" } else { "未设置" }
需要持久化时，可按官方文档将变量加入 PowerShell 配置或用户级环境设置；验证时只判断变量是否存在，不要输出完整内容。

如果使用第三方网关，通常还需要设置 Base URL 和网关凭证。例如网关团队要求使用 Bearer Token 时，Bash 或 Zsh 可写为 export ANTHROPIC_BASE_URL="https://llm-gateway.example.com" 与 export ANTHROPIC_AUTH_TOKEN="网关凭证"；PowerShell 可写为 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com" 与 $env:ANTHROPIC_AUTH_TOKEN = "网关凭证"。如果网关明确要求 x-api-key，则应按其说明使用 ANTHROPIC_API_KEY。

官方文档说明，ANTHROPIC_AUTH_TOKEN 会映射到 Authorization: Bearer，ANTHROPIC_API_KEY 会映射到 x-api-key。变量选错时，常见表现是请求返回 401。网关配置参考：连接 Claude Code 到 LLM Gateway。

第三方网关怎么接：先测 URL 和凭证，再启动 Claude Code

第三方网关的基本作用是在 Claude Code 与模型服务之间增加一层路由。官方文档提到，网关可以集中管理凭证、用量统计、预算和速率限制，但 Anthropic 不为第三方网关背书、维护或审计。因此，接入前至少核对 API 格式、数据保留、日志权限、密钥轮换、限速规则、错误透传和模型映射。

向网关维护方确认 Base URL 是否需要包含版本路径，以及接口是否支持 Anthropic Messages API。
确认凭证类型：是 Bearer Token，还是 x-api-key。
先在当前终端设置 Base URL 与凭证，不要立刻写入项目文件。
发送一个只包含一个输出 Token 的最小请求，确认 URL 和认证能工作。
请求成功后，再启动 claude，进入会话运行 /status，确认实际使用的 Base URL 和凭证来源。

Bash 或 Zsh 的最小验证请求示例：

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Windows PowerShell 示例：

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } -ContentType "application/json" -Body '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

如果网关要求 x-api-key，将请求头替换为对应的 x-api-key。返回 401 时，优先检查凭证是否放进了正确的变量；返回模型不存在但已经完成认证，仍可能说明 URL 和凭证有效，下一步应核对网关支持的模型名。不要把真实 Key 写入仓库中的项目级设置文件。

Bedrock 和 Google Cloud：什么时候不该使用 ANTHROPIC_API_KEY

如果团队已经在云平台管理身份、权限和账单，Claude Code 可以直接走云平台集成，不必把 Anthropic API Key 放到本地环境。两种方式都需要先完成对应云平台的账户、项目、权限和模型可用性配置，具体授权步骤应以云平台及 Claude Code 当前文档为准。

云平台	关键变量	配置检查点
Amazon Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`、`AWS_REGION`	AWS 凭证是否可用、目标区域是否提供对应模型、IAM 权限是否完整
Google Cloud Agent Platform	`CLAUDE_CODE_USE_VERTEX=1`、`CLOUD_ML_REGION`、`ANTHROPIC_VERTEX_PROJECT_ID`	项目 ID、区域、身份认证和目标模型是否已启用

Bedrock 的 Bash 示例是 export CLAUDE_CODE_USE_BEDROCK=1 与 export AWS_REGION=us-east-1；Google Cloud 的示例是 export CLAUDE_CODE_USE_VERTEX=1、export CLOUD_ML_REGION=global 和 export ANTHROPIC_VERTEX_PROJECT_ID="你的项目ID"。这些只是官方文档给出的配置变量示例，不代表所有账户、区域和模型都能直接使用。

遇到区域或模型错误时，先运行 /status 查看 Claude Code 解析到的区域，再回到云平台控制台核对模型可用性和权限。官方说明：Claude Code on Amazon Bedrock、Claude Code on Google Cloud Agent Platform。

常见错误：按认证来源和请求路径排查

现象	优先检查	处理方法
无法登录或登录了错误账户	是否已有旧登录、是否需要订阅账户	运行 `/logout`，更新 Claude Code 后重新执行 `claude`；用 `claude auth status` 查看状态。
401 Unauthorized	凭证变量和请求头是否匹配	Bearer 使用 `ANTHROPIC_AUTH_TOKEN`，`x-api-key` 使用 `ANTHROPIC_API_KEY`，再做最小请求。
403 Forbidden	账户、云平台 IAM、区域或模型权限	确认账户类型、组织权限、AWS/GCP 项目权限和模型是否在目标区域可用。
404 Not Found	Base URL 是否重复或缺少路径	用官方要求的 Base URL 拼接 `/v1/messages`，避免把完整接口路径重复拼接。
429 Too Many Requests	网关或云平台限速、并发量	降低并发，检查网关限速和账户用量；不要用无限重试放大请求。
400 Bad Request	请求 JSON、模型名、必填字段或版本头	先复制官方最小 Messages API 请求，逐项恢复自定义字段。
unsupported_parameter	客户端发送了当前接口不支持的参数	删除不属于 Anthropic Messages API 的字段，检查网关是否错误转发了其他协议参数。
变量已设置但没有生效	是否在同一个终端启动 Claude Code	Bash 使用 `printenv` 检查变量存在，PowerShell 使用 `$env:变量名` 检查；再运行 `/status`。
网关请求超时	Base URL、网络路径、网关上游和超时策略	先用最小请求测试网关，再分别判断本机到网关、网关到模型服务哪一段失败。

API Key 安全：保存、轮换和撤销

不要把 Key 写进 Git 仓库、项目共享配置、终端录屏、截图或公开 issue。
本地验证时优先使用当前会话环境变量；持久化时使用用户级配置，并限制文件访问权限。
项目级配置文件可能被提交或共享，除非确认已加入忽略规则，否则不要放入真实凭证。
怀疑泄露时，立即在对应控制台撤销旧 Key，创建新 Key，并检查使用记录和用量变化。
团队环境优先考虑短期凭证、身份联邦或网关托管，不要让每位开发者复制长期主 Key。

Claude API 官方认证文档将 API Key 描述为适合本地开发、原型和由开发者自行控制密钥存储的方式；生产环境可根据平台能力考虑更短期的身份凭证。无论使用官方 API、云平台还是网关，都应把“凭证由谁保管、请求经过谁、日志保留多久、如何撤销”写进接入清单。

认证参考：Claude API Authentication。

常见问题

Claude Code 必须购买订阅才能接 API 吗？

不一定。Claude Code 可以使用支持的 Claude 账户登录，也可以使用 Console/API Key、Amazon Bedrock、Google Cloud Agent Platform 或兼容 Anthropic API 的网关。是否需要订阅取决于你选择的认证方式和账户类型。

设置 ANTHROPIC_API_KEY 后，还会使用 Pro 或 Max 订阅额度吗？

不要默认认为两者共用额度。设置并批准 API Key 后，Claude Code 可能优先使用 API Key 对应的 API 认证路径；如果想回到订阅登录，应清理环境变量或运行 /logout 后重新登录，并用 /status 确认。

Windows PowerShell 设置的 API Key 为什么重开窗口就没了？

因为 $env: 变量默认只对当前 PowerShell 会话及其子进程生效。重新打开窗口后需要重新设置，或按官方文档将变量加入用户级环境配置；验证时只检查变量是否存在，不要输出完整 Key。

第三方网关应该使用 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY？

看网关要求的请求头。要求 Authorization: Bearer 时使用 ANTHROPIC_AUTH_TOKEN；要求 x-api-key 时使用 ANTHROPIC_API_KEY。无法确定时，先按网关文档选择，再用最小请求验证，401 通常说明凭证变量与请求头不匹配。

Claude Code 显示 403 或模型不可用，应该先查什么？

先确认当前认证来源，再查账户权限、组织策略、云平台 IAM、区域和模型可用性。Bedrock 和 Google Cloud 场景尤其要核对区域与项目权限；运行 /status 查看 Claude Code 实际解析到的配置。

参考资料

Claude Code 官方安装、系统要求与认证文档（code.claude.com）
Claude API Key 创建与管理文档（platform.claude.com）
Claude API Authentication 官方文档（platform.claude.com）
Pro 或 Max 计划使用 Claude Code 的官方帮助文档（support.claude.com）
Claude Code on Amazon Bedrock 官方文档（code.claude.com）