Claude Code 能用 OpenAI 兼容接口吗？API Key 与 Base URL 配置指南

更新于 2026-10-25 · unitysvc.cyou

简答：Claude Code 不能仅凭“OpenAI 兼容”就直接接入：只有 /v1/chat/completions 的接口通常不够。先确认服务是否支持 Anthropic Messages 或协议转换，再设置 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL，并按最终请求路径验证。

定义：Claude Code 的兼容接口配置，是让客户端通过 Anthropic Messages 兼容入口或协议转换网关访问模型，而不是把 OPENAI_API_KEY 直接替换进 Claude Code。

先用 30 秒判断卡确认接入方式

先看你拿到的接口文档，而不是先复制环境变量。Claude Code 的请求契约围绕 Anthropic Messages；官方 API 的消息接口是 POST /v1/messages，而不是 OpenAI 常见的 /v1/chat/completions。官方 Claude Code 文档也说明，ANTHROPIC_BASE_URL 用于把请求路由到代理或网关。可核对API overview与Environment variables。

核心结论：OpenAI Compatible 与 Anthropic Compatible 不是同一个协议标签。若服务商只提供 OpenAI 请求格式，不能假设 Claude Code 会自动把消息字段、认证头、流式事件和工具调用转换好。

只有 OpenAI 接口时怎么办：使用协议转换网关

如果你手里的服务只接受 /v1/chat/completions，可在 Claude Code 与模型服务之间加入协议转换网关。Anthropic 的 LLM gateway 文档以 LiteLLM 为例，说明 Claude Code 可以通过统一的 Anthropic 格式入口连接网关，也可以使用特定提供商的透传路径；该文档同时提醒，LiteLLM 是第三方代理，Anthropic 不负责维护、审计其安全性或功能。详情见LLM gateway configuration。

1. 部署或选择一个明确支持 Anthropic Messages 的网关。
2. 在网关中配置上游 OpenAI 兼容服务的 Base URL、Key 和模型映射。
3. 确认网关对外暴露的是 Anthropic 格式入口，而不是仅暴露 /v1/chat/completions。
4. 先用短文本验证普通响应，再测试流式输出、工具调用和 Claude Code 的后台模型。
5. 将 Claude Code 的 ANTHROPIC_BASE_URL 指向网关文档声明的根地址；不要自行追加 /messages 或 /chat/completions。

网关能返回普通文本，不代表已经完整兼容 Claude Code。工具字段、流式事件、模型别名和后台任务都应单独验证。

配置前准备：API Key、Base URL 和模型 ID

API Key：从实际使用的服务商或网关控制台获取。若直接调用 Claude API，官方认证文档说明静态 API Key 可通过 Authorization: Bearer 发送，x-api-key 也仍受支持；对于第三方网关，必须以它声明的认证头为准。可查看Authentication。

Base URL：复制服务商或网关文档中的接口根地址。是否包含 /v1 没有统一答案：文档要求就保留，文档没有就不要自行添加。通常不要把 /messages 或 /chat/completions 写进 Base URL，也要避免末尾斜杠导致路径重复。

Model ID：使用服务商明确提供的模型 ID。YOUR_MODEL_ID 只是占位符，必须替换成实际值。Claude Code 文档说明，Base URL 负责改变请求发送位置，模型仍由模型配置或 ANTHROPIC_MODEL 决定；模型别名和第三方网关的自定义模型名还需要额外映射，可参考Model configuration。

认证变量：ANTHROPIC_AUTH_TOKEN 会把值作为 Bearer 认证使用；ANTHROPIC_API_KEY 用于 API Key 认证。两者不要在同一环境中无意并存，否则可能让你误判实际使用的凭据。进入 Claude Code 后运行 /status，检查当前认证方式；环境变量 API Key 可能优先于订阅登录，具体行为见Manage API key environment variables in Claude Code。

macOS、Linux：先用临时变量验证

第一次配置建议只设置当前终端会话，验证成功后再决定是否长期保存。下面的地址、Key 和模型名都是占位符：

read -s ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"
claude

如果服务商明确要求 ANTHROPIC_API_KEY，改用下面的写法，不要同时设置两套认证变量：

read -s ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"
claude

read -s 可避免把 Key 直接写在命令行中。长期配置时，官方环境变量文档列出 macOS/Linux 可使用 ~/.zshrc、~/.bashrc 或对应 Shell 的 profile 文件；写入前应确认文件权限，并确保不会提交到 Git。可查看Environment variables。

# macOS 默认常见为 zsh
printf '%s\n' 'export ANTHROPIC_BASE_URL="https://api.example.com"' >> ~/.zshrc
printf '%s\n' 'export ANTHROPIC_MODEL="YOUR_MODEL_ID"' >> ~/.zshrc
source ~/.zshrc

# Linux bash 常见写法
printf '%s\n' 'export ANTHROPIC_BASE_URL="https://api.example.com"' >> ~/.bashrc
printf '%s\n' 'export ANTHROPIC_MODEL="YOUR_MODEL_ID"' >> ~/.bashrc
source ~/.bashrc

不建议把真实 Key 直接写进上述命令或公开配置文件。更稳妥的做法是使用系统密钥管理器、CI/CD Secret 或服务商支持的加密变量。

Windows PowerShell、CMD 与 settings.json

PowerShell 临时配置

$env:ANTHROPIC_AUTH_TOKEN = Read-Host "API Key"
$env:ANTHROPIC_BASE_URL = "https://api.example.com"
$env:ANTHROPIC_MODEL = "YOUR_MODEL_ID"
claude

CMD 临时配置

set /p ANTHROPIC_AUTH_TOKEN=API Key:
set ANTHROPIC_BASE_URL=https://api.example.com
set ANTHROPIC_MODEL=YOUR_MODEL_ID
claude

如果使用 PowerShell 的永久用户变量，可执行后关闭并重新打开终端：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.example.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "YOUR_MODEL_ID", "User")

Windows 用户配置文件的常见路径是 %USERPROFILE%\.claude\settings.json，但应以当前版本文档和实际安装方式为准。文件内容可写成：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.example.com",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID"
  }
}

如果担心 Key 被写进文件，可只在 settings.json 保存 Base URL 和模型名，把认证变量留给 PowerShell、系统 Secret 或其他密钥管理方式。官方文档说明，用户级 ~/.claude/settings.json 的 env 变量会在启动 Claude Code 时生效。

别漏掉后台模型：主模型和 Haiku 模型分开核对

Claude Code 不只会调用主模型。官方环境变量参考将 ANTHROPIC_DEFAULT_HAIKU_MODEL 定义为 haiku 别名及后台功能使用的模型 ID；旧教程中的 ANTHROPIC_SMALL_FAST_MODEL 可能仍会出现，但新配置应优先按当前环境变量文档核对。模型变量名称和用途可查看Environment variables。

如果网关只映射了一个自定义模型，后台任务仍可能因为模型别名没有映射而失败。可以在服务商明确支持时补充：

export ANTHROPIC_MODEL="YOUR_MAIN_MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="YOUR_BACKGROUND_MODEL_ID"
# 旧版本或旧配置可能出现此变量，是否支持以当前文档为准
# export ANTHROPIC_SMALL_FAST_MODEL="YOUR_BACKGROUND_MODEL_ID"

不要凭空填写一个模型名。若网关只支持一个模型，可先将主模型和后台模型都设为同一个已确认的 Model ID；但这可能改变用量和响应特征，是否适合应以网关文档和实际测试为准。

Base URL 与最终请求路径：不要把操作路径填进去

官方 API overview 将消息请求列为 POST /v1/messages，并列出了认证、版本和内容类型请求头。官方版本文档还要求请求发送 anthropic-version；如果目标是第三方网关，版本号和认证头应先按网关文档填写，不要把直连官方 API 的示例原样套用到所有服务。可查看Versions。

常见 404 原因包括：把 /v1 重复成 /v1/v1、把 /messages 写进了不该包含操作路径的 Base URL，或把只有 OpenAI 格式的路径当作 Anthropic 入口。排查时记录客户端最终请求路径，不要只看你填写的变量值。

安全的最小验证流程：避免把 Key 放进进程参数

验证建议分四层：变量、路径、最小文本、Claude Code。先不要直接在大型项目中测试工具调用。

1. 确认变量：只打印 Base URL 和模型名；检查认证变量是否存在时不要输出完整 Key。
2. 确认路径：查看服务商文档是否提供 Anthropic Messages 入口，以及是否要求保留 /v1。
3. 发送最小请求：用请求头文件读取认证信息，避免把完整 Bearer 值直接放进命令参数。
4. 启动 Claude Code：先运行只读任务，再测试流式响应、文件操作和工具调用。

下面是使用独立请求头文件的示例。请根据服务商文档选择认证头，并替换所有占位符：

umask 077
read -s API_KEY
printf 'Authorization: Bearer %s\n' "$API_KEY" > /tmp/claude-headers.txt
printf '%s\n' 'content-type: application/json' >> /tmp/claude-headers.txt
printf '%s\n' 'anthropic-version: 2023-06-01' >> /tmp/claude-headers.txt
curl --fail-with-body -sS \
  'https://api.example.com/v1/messages' \
  -H @/tmp/claude-headers.txt \
  --data '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Reply with OK"}],
    "stream": false
  }'
rm -f /tmp/claude-headers.txt
unset API_KEY

如果网关要求 x-api-key，将请求头文件中的认证行改成 x-api-key: YOUR_API_KEY，并按服务商要求处理临时文件。不要把真实 Key 粘贴进公开工单、截图、Shell 历史或 Git 提交。官方安全建议也要求使用 Secret 存储，并定期检查用量和日志，可参考API key best practices。

401、403、404、429 和工具调用失败排查表

排错时一次只改一个变量：先固定认证，再核对路径；先完成普通文本，再验证流式；最后再测工具调用和后台任务。响应中的请求 ID 可以保留给服务商支持团队，但不要同时提交完整 Key、完整提示词和敏感业务数据。

最后检查清单

• 接口是否明确支持 Anthropic Messages，或已经部署协议转换网关。
• ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY 是否只启用服务商要求的一种。
• ANTHROPIC_BASE_URL 是否来自公开文档，且没有盲目追加 /messages 或 /chat/completions。
• ANTHROPIC_MODEL 是否替换成真实 Model ID，而不是展示名称或猜测别名。
• 后台模型是否需要配置 ANTHROPIC_DEFAULT_HAIKU_MODEL。
• 是否已用最小文本请求验证，再启动 Claude Code。
• 是否已通过 /status 确认当前认证方式。
• 真实 Key 是否没有进入公开仓库、截图、命令历史或共享配置。

目前未核实到 UnitySVC 的专属 Claude Code 接口地址、Key 格式、模型列表或协议支持情况，因此本文不提供专属配置值。本文是独立的第三方 AI API 接入指南，与 UnitySVC、Anthropic 均无官方关系；具体地址、模型、认证方式和限额应以实际服务商文档为准。

常见问题

Claude Code 可以直接使用 OpenAI 兼容接口吗？

不一定。只有 OpenAI 的 /v1/chat/completions 时，通常不能直接接入 Claude Code；需要服务商提供 Anthropic Messages 入口，或使用协议转换网关。先查公开文档中的请求格式、认证头和完整路径。

Claude Code 的 Base URL 要不要加 /v1？

没有统一答案，以服务商文档为准。文档要求 /v1 就保留，文档没有就不要自行添加；通常不要把 /messages 或 /chat/completions 写进 Base URL，并检查是否出现 /v1/v1 重复路径。

应该使用 ANTHROPIC_API_KEY 还是 ANTHROPIC_AUTH_TOKEN？

按服务商认证说明选择一种。官方环境变量参考将 ANTHROPIC_API_KEY 用于 API Key 认证，将 ANTHROPIC_AUTH_TOKEN 用于 Authorization Bearer 值；不要无意中同时设置两套变量。

为什么设置 API Key 后，Claude Code 没有使用订阅登录？

Claude Code 可能优先读取环境变量中的 API Key。进入会话后运行 /status 查看当前认证方式；如果要切回订阅登录，先清理相关环境变量并重新打开终端。

只有 OpenAI 的 /v1/chat/completions，没有 /v1/messages，怎么办？

不能仅修改变量名解决。应使用明确支持 Anthropic Messages 的协议转换网关，并在网关中配置上游 OpenAI 接口、模型映射和认证信息；完成后把 ANTHROPIC_BASE_URL 指向网关的 Anthropic 格式入口。

为什么普通文本请求成功，工具调用仍然失败？

文本成功只证明基础消息请求可用，不代表网关支持工具字段、工具结果事件和流式协议。需要查看服务商是否明确声明支持 Anthropic 工具调用，并单独进行工具测试。

后台模型变量应该怎么配置？

主模型使用 ANTHROPIC_MODEL；当前 Claude Code 环境变量参考将 ANTHROPIC_DEFAULT_HAIKU_MODEL 用于 haiku 别名和后台功能。若服务商只提供自定义模型，应将其设置为服务商实际存在的 Model ID；旧教程中的 ANTHROPIC_SMALL_FAST_MODEL 是否适用，要以当前版本文档为准。

参考资料

1. Environment variables - Claude Code Docs（code.claude.com）
2. LLM gateway configuration - Anthropic
3. API overview - Claude Platform Docs（platform.claude.com）
4. Versions - Claude Platform Docs（platform.claude.com）
5. Authentication - Claude Platform Docs（platform.claude.com）
6. Manage API key environment variables in Claude Code（support.claude.com）
7. API key best practices: keep your keys safe and secure（support.claude.com）