Claude Code 怎么使用 Anthropic 兼容 API
简答：可以：先安装并确认 Claude Code，再设置 ANTHROPIC_BASE_URL 和正确的鉴权变量，使用 Messages API 的最小请求验证接口，最后用 claude --model 或 ANTHROPIC_MODEL 选择后端支持的模型。最容易出错的是 Base URL 路径、Authorization 与 x-api-key 的区别，以及模型 ID 不匹配。
定义：Anthropic 兼容 API 是指能够接收 Anthropic Messages API 请求格式，并按约定返回消息响应的接口或网关。
先做这一步：确认变量、路径和鉴权方式
本站为第三方指南，非 Claude Code 或 Anthropic 官方，以其官网为准。截至 2026年10月23日，Claude Code 官方网关文档将连接拆成两个核心配置：网关地址和凭据；官方示例通过 ANTHROPIC_BASE_URL 指定地址，并向 /v1/messages 发送 Messages API 请求。可先查看 Claude Code 连接 LLM 网关文档 和 网关兼容性说明。
| 项目 | 应填写什么 | 常见误区 |
|---|---|---|
ANTHROPIC_BASE_URL | 服务商提供的 Anthropic 兼容基础地址 | 不要擅自重复添加 /v1 或 /anthropic |
ANTHROPIC_AUTH_TOKEN | 服务商要求放入 Bearer Authorization 的 Token | 会发送为 Authorization: Bearer ... |
ANTHROPIC_API_KEY | 服务商要求使用 API Key 或 x-api-key 的 Key | 会发送为 x-api-key: ... |
| 模型 ID | 后端真实支持的模型名称 | 不能只填 Claude Code 的别名并假设后端一定支持 |
Base URL 的判断方法是：先看服务商文档给出的“基础地址”和完整请求示例。如果文档明确要求客户端请求 BASE_URL/v1/messages，通常填写不含 /v1/messages 的基础地址；如果服务商已经把版本路径包含在 Base URL 中，就不要再次拼接。无法从文档确认时，不要猜，直接以服务商给出的完整 Messages API 地址为准。
安装 Claude Code 并检查版本
Claude Code 官方安装文档列出了 macOS、Linux、WSL、Windows PowerShell 和 Windows CMD 的安装方式。安装完成后应重新打开终端，再运行版本检查。
- macOS、Linux 或 WSL：
curl -fsSL https://claude.ai/install.sh | bash - Windows PowerShell：
irm https://claude.ai/install.ps1 | iex - Windows CMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd - 检查版本：
claude --version
官方安装说明还指出，Windows 可以原生运行，也可以在 WSL 中运行；两者应根据项目所在环境和所需工具链选择。详细要求与安装命令见 Claude Code Advanced setup。如果命令提示找不到 claude，先关闭当前终端并重新打开；仍然无效时再检查 PATH。
macOS、Linux、WSL：临时配置与永久配置
第一次接入建议只在当前终端临时设置变量，先验证接口，再决定是否写入配置文件。这样可以把“接口本身不可用”和“Claude Code 没读到配置”区分开。
如果网关使用 Bearer Token：
export ANTHROPIC_BASE_URL='https://api.example.com'
export ANTHROPIC_AUTH_TOKEN='your-token'
claude --version
如果网关要求 x-api-key：
export ANTHROPIC_BASE_URL='https://api.example.com'
export ANTHROPIC_API_KEY='your-api-key'
claude --version
环境变量只对当前终端会话及其启动的程序生效。需要长期使用时，可以将配置写入 ~/.bashrc、~/.zshrc 或其他 Shell 配置文件，但不要把真实 Key 提交到 Git 仓库。更适合 Claude Code 的持久化方式是用户级 ~/.claude/settings.json，其 env 字段示例为：
{"env":{"ANTHROPIC_BASE_URL":"https://api.example.com","ANTHROPIC_AUTH_TOKEN":"your-token"}}
官方文档说明，用户级配置适用于所有项目；项目级 .claude/settings.json 会进入版本控制，不应放真实凭据。只想对当前项目生效时，可以使用 .claude/settings.local.json，并确认它已加入 Git 忽略规则。配置文件层级与 env 行为可参考 Claude Code 环境变量文档。
Windows PowerShell：不要混用 CMD 和 Bash 写法
PowerShell 使用 $env: 设置当前会话变量，关闭窗口后不会自动保留。可先执行：
$env:ANTHROPIC_BASE_URL = 'https://api.example.com'
$env:ANTHROPIC_AUTH_TOKEN = 'your-token'
claude --version
如果接口要求 x-api-key，改用：
$env:ANTHROPIC_BASE_URL = 'https://api.example.com'
$env:ANTHROPIC_API_KEY = 'your-api-key'
需要永久设置时，可使用用户环境变量命令，然后重新打开 PowerShell：
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.example.com', 'User')
不建议把真实 Key 直接写进 PowerShell 历史记录、截图或项目文件。验证时只检查变量是否存在，不要把完整 Key 打印出来：
if ($env:ANTHROPIC_API_KEY) { 'API key is set' } elseif ($env:ANTHROPIC_AUTH_TOKEN) { 'Auth token is set' } else { 'Credential is missing' }
先用 curl 验证 Messages API，再启动 Claude Code
官方连接文档建议先向 Messages API 发一个最小请求。这个步骤的价值是：如果请求已经返回 JSON，说明地址、路径和鉴权至少基本可用；如果返回 401，优先检查鉴权变量和请求头；如果返回模型不存在，反而说明请求已经到达后端，下一步应核对模型 ID。
下面的 MODEL_ID 必须替换为服务商文档中真实存在的模型名称。若服务商要求 Bearer Token，在 macOS、Linux 或 WSL 中执行：
curl -i -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":"MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
若服务商要求 API Key，改用：
curl -i -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
PowerShell 建议使用 Invoke-RestMethod，避免把 Bash 的反斜杠续行写法直接复制过来：
$body = '{"model":"MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
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 $body
如果使用 ANTHROPIC_API_KEY，将 Headers 中的 Authorization 项替换为 "x-api-key" = $env:ANTHROPIC_API_KEY。官方文档说明，Bearer Token 与 API Key 会映射到不同的请求头，变量选错会导致 401。
启动 Claude Code、指定模型并确认请求走向
最小请求通过后，从同一个终端启动：
claude
进入会话后运行 /status，确认状态中能看到 Anthropic Base URL 和当前鉴权来源。官方连接文档将这两项作为确认网关配置是否生效的重要检查点。
指定本次会话模型可以使用：
claude --model MODEL_ID- 进入会话后运行
/model MODEL_ID
也可以设置 ANTHROPIC_MODEL：
export ANTHROPIC_MODEL='MODEL_ID'
PowerShell 写法为：
$env:ANTHROPIC_MODEL = 'MODEL_ID'
Claude Code 官方模型配置文档说明，模型选择可以使用别名或完整模型名，但 ANTHROPIC_BASE_URL 只改变请求发送到哪里，不会自动把一个模型名称转换成后端支持的模型。接入兼容服务时，优先使用服务商提供的完整模型 ID。若希望使用 opus、sonnet 或 haiku 等别名，需要额外配置对应的默认模型映射，例如 ANTHROPIC_DEFAULT_SONNET_MODEL；具体变量以当前版本的 模型配置文档 为准。
鉴权、模型与接口格式的关键区别
| 问题 | Anthropic 兼容接口 | OpenAI 兼容接口 |
|---|---|---|
| 主要请求格式 | 通常是 Messages API，常见路径为 /v1/messages | 常见为 Chat Completions 或 Responses 风格，路径和字段由服务商定义 |
| 常见鉴权 | Authorization: Bearer 或 x-api-key | 通常是 Authorization: Bearer |
| Claude Code 变量 | ANTHROPIC_BASE_URL 配合 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY | 不能仅因为接口支持 OpenAI SDK 就假设 Claude Code 可以直接使用 |
| 模型映射 | 模型 ID 必须能被后端识别；别名可能需要映射 | 字段名、工具调用和流式协议可能不同 |
核心判断不是“服务商宣传兼容哪种 SDK”，而是它是否真实接收 Claude Code 发出的 Anthropic 格式请求，并正确转发消息、工具调用、流式事件、上下文和错误响应。官方网关兼容性文档还提醒，Claude Code 持续增加能力，如果网关没有转发对应字段，部分功能可能无法工作。
常见错误对照表：先看状态码，再看请求是否到达
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 | 鉴权变量和请求头不匹配 | Bearer Token 用 ANTHROPIC_AUTH_TOKEN；x-api-key 用 ANTHROPIC_API_KEY，不要只设置变量而不确认后端要求 |
| 403 | Key 权限、来源限制、账户资格或网关策略 | 查看服务商返回的错误正文，确认 Key 是否允许调用该模型和接口 |
| 404 | Base URL 重复或缺少路径，模型 ID 不存在 | 对照完整请求地址，分别确认 /v1/messages 是否由客户端追加，以及模型名称是否准确 |
| 400 | JSON 字段、类型或请求格式错误 | 先用最小请求，只保留 model、max_tokens 和一条 user message |
unsupported_parameter | 网关或后端不支持 Claude Code 发送的字段 | 查看错误中指出的参数，确认网关是否完整转发 Anthropic Messages API；不要盲目删除字段后长期使用 |
| 模型不存在 | 模型 ID 或别名映射错误 | 用服务商模型列表中的完整 ID，并暂时使用 claude --model MODEL_ID 直接验证 |
| 429 | 限速、并发或账户额度 | 降低并发，等待后按服务商规则重试；不要通过快速循环重复发送 |
| 超时或流式中断 | 网关超时、代理缓冲、上游连接或流式事件转发 | 先用最小 max_tokens 测试，再检查网关是否支持 SSE、是否设置了过短的读取超时 |
| 工具调用失败 | 网关没有完整转发工具字段或事件 | 查看兼容性文档，确认工具定义、工具结果和流式事件没有被改写 |
| 上下文过长 | 后端上下文限制与 Claude Code 会话内容不匹配 | 缩短任务、开启自动压缩或换用服务商明确支持的上下文规格 |
一套可复用的排查顺序
- 运行
claude --version，确认安装命令和当前终端环境正常。 - 只设置一个鉴权变量：先根据服务商说明选择 Token 或 API Key，不要同时设置两个变量。
- 检查 Base URL 是否是基础地址，避免重复拼接
/v1。 - 使用
curl -i或 PowerShell 的Invoke-RestMethod发送最小 Messages 请求。 - 如果返回 401，先换正确的请求头；如果返回模型错误，说明地址和鉴权可能已经通过。
- 最小请求成功后，再运行
claude，用/status检查 Base URL 和鉴权来源。 - 最后再设置模型映射、项目级配置、工具调用和流式能力，避免一次修改太多变量。
建议把 API Key 放在环境变量、凭据管理器或服务商提供的安全配置中。不要把 Key 写入公开仓库、提交到项目级 .claude/settings.json，也不要把完整 Key 粘贴到错误报告中。
常见问题
Claude Code 接 Anthropic 兼容 API，一定要填写 /v1 吗？
不一定。应以服务商给出的完整请求示例为准。如果客户端请求形式是 BASE_URL/v1/messages，通常 Base URL 不包含 /v1；如果服务商明确把版本路径放进基础地址，则按其文档填写。重复添加路径会导致 404。
ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 能同时设置吗？
不建议。两者会产生不同请求头：ANTHROPIC_API_KEY 对应 x-api-key，ANTHROPIC_AUTH_TOKEN 对应 Authorization: Bearer。先确认服务商要求的鉴权方式，只设置其中一个，减少变量优先级和排错干扰。
最小 curl 请求返回“模型不存在”，是不是 Base URL 配错了？
不一定。官方连接文档指出，未知模型错误也可能说明地址和凭据已经通过，只是模型名称不被后端支持。此时应核对服务商的模型列表、大小写和完整模型 ID。
为什么 Claude Code 能启动，但请求仍然返回 401？
启动成功只代表本地程序可运行，不代表接口鉴权正确。检查是否从同一个终端启动、是否只设置了一个鉴权变量，以及后端要求的是 Bearer Token 还是 x-api-key；再用 curl 的最小请求单独验证。
可以把 API Key 写进项目的 .claude/settings.json 吗？
不建议。官方文档说明项目级 settings.json 可能被提交并分享给其他协作者。个人项目可以使用用户级配置或被 Git 忽略的 .claude/settings.local.json，并检查忽略规则确实生效。
OpenAI 兼容 API 能直接给 Claude Code 使用吗？
不能仅凭“兼容 OpenAI”这一描述直接判断。Claude Code 通常需要 Anthropic Messages API 格式，包括消息、工具和流式事件。只有服务商明确提供 Anthropic 兼容入口，并能处理 Claude Code 所需字段时，才适合按本文方法接入。
参考资料
- Claude Code 官方文档：连接 LLM 网关（code.claude.com）
- Claude Code 官方文档：网关兼容性说明（code.claude.com）
- Claude Code 官方文档：环境变量（code.claude.com）