Claude Code 怎么用 OpenAI API？三种接入方式与报错排查

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

简答：Claude Code 默认调用 Anthropic Messages API，因此单独设置 OPENAI_API_KEY 通常不会生效。要使用 OpenAI 模型，需要让 Claude Code 连接一个能接收 Anthropic Messages 请求、再转发到 OpenAI 的兼容网关；最可复制的做法是自建 LiteLLM。本文同时给出兼容网关和 cc switch 两种配置路径。

定义：Claude Code 接入 OpenAI API，是指让 Claude Code 的 Anthropic Messages 请求先到兼容层，再由兼容层调用 OpenAI 模型，而不是让 Claude Code 原生读取 OPENAI_API_KEY。

先看结论：三种方式怎么选

本站为第三方指南，非 Claude Code 或 OpenAI 官方，以其官网为准。Claude Code 官方文档说明，工具默认使用 Anthropic API；其网关文档以 LiteLLM 为例，要求通过 ANTHROPIC_BASE_URL 指向兼容入口，而不是把 OpenAI 的 Base URL 直接填进去。

方案	请求链路	适合谁	关键配置
LiteLLM 自建	Claude Code → LiteLLM → OpenAI API	希望自己控制密钥、模型映射和日志的开发者	`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`
兼容网关	Claude Code → 第三方 Anthropic 兼容接口 → 上游模型	不想自己部署网关，只拿到网关地址和密钥的用户	网关提供的 Anthropic Messages 地址、认证方式、模型别名
cc switch	切换工具写入 Claude Code 配置或接管本地代理	需要在多个接口、账号或模型之间快速切换的用户	通常改写 `ANTHROPIC_*` 变量或 `settings.json`

先试这一步：如果你已经有兼容网关地址，先不要设置 OPENAI_API_KEY，而是配置 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN，再将 ANTHROPIC_MODEL 写成网关实际暴露的模型名。

接入前准备：安装、账号与密钥

按 Claude Code 官方安装文档完成安装。官方当前列出的常见环境包括 macOS、Linux、Windows WSL 或 Git for Windows；安装后可运行 claude doctor 检查安装状态。参考：Claude Code 安装与认证文档。
准备 OpenAI API 项目和 API Key。OpenAI API 使用 Bearer 认证，密钥应保存在服务端环境变量或密钥管理工具中，不要放进前端代码或提交到 Git。参考：OpenAI API Authentication。
确认你的网关支持 Anthropic Messages API，至少能处理 Claude Code 发出的 /v1/messages 请求，并支持流式响应、工具调用和你要使用的模型能力。只写“OpenAI 兼容”并不能证明它兼容 Claude Code。

OpenAI API 的账号计费与 ChatGPT 订阅是分开的。使用 OpenAI API 需要查看 API 平台自己的账单和用量；ChatGPT Plus、Pro 等订阅并不自动变成 API 余额。OpenAI 也说明，部分参与应用可以通过“使用 ChatGPT 登录”共享计划额度，但这与 API Key 调用是不同机制，是否支持取决于具体应用。参考：ChatGPT 与 API 平台账单说明。

方案一：自建 LiteLLM，把 OpenAI API 转成 Claude Code 可用的接口

这是最容易复现、也最容易定位问题的方案。LiteLLM 官方为 Claude Code 提供了专门的客户端配置：Claude Code 使用 Anthropic Messages 格式请求，LiteLLM 在 /v1/messages 提供兼容入口，再根据 model_list 把请求转发到 OpenAI。

1. 创建 LiteLLM 配置

下面示例中的 openai/your-openai-model-id 必须替换成你的 OpenAI 账户实际可用模型 ID；gpt-via-openai 是网关内部别名，Claude Code 后续要使用这个别名。

model_list:
- model_name: gpt-via-openai
litellm_params:
model: openai/your-openai-model-id
api_key: os.environ/OPENAI_API_KEY
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY

这里的关键点是：OpenAI Key 放在 LiteLLM 所在机器的 OPENAI_API_KEY 中，Claude Code 只拿 LiteLLM 的访问密钥。LiteLLM 的官方快速开始文档说明，代理可以通过模型配置调用 OpenAI，并在本地端口提供统一接口；Claude Code 专用文档则明确了 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_MODEL 的对应关系。参考：LiteLLM Proxy Quick Start、LiteLLM Claude Code Client Setup。

2. 启动代理

uv tool install 'litellm[proxy]'
export OPENAI_API_KEY='你的 OpenAI API Key'
export LITELLM_MASTER_KEY='sk-自定义管理密钥'
litellm --config ./config.yaml

如果你使用虚拟 Key，应先在 LiteLLM 中生成一个只允许访问目标模型的 Key，再把它作为 Claude Code 的 ANTHROPIC_AUTH_TOKEN。不要把主密钥长期放在客户端配置中。

3. 配置 Claude Code

macOS、Linux、WSL Bash：

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-你的-LiteLLM-Key"
export ANTHROPIC_MODEL="gpt-via-openai"
unset ANTHROPIC_API_KEY
claude

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的-LiteLLM-Key"
$env:ANTHROPIC_MODEL = "gpt-via-openai"
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
claude

PowerShell 中的 $env: 只对当前会话生效。若要长期使用，应写入 Claude Code 的设置文件或用户环境变量。

方案二：使用 Anthropic 兼容网关或中转接口

如果你不想部署 LiteLLM，前提是服务方确实提供 Anthropic Messages 兼容接口。你需要向服务方确认四项内容：完整 Base URL、认证头格式、可用模型 ID、是否支持流式和工具调用。

常见配置如下，具体域名、模型名和认证方式必须以服务方文档为准：

ANTHROPIC_BASE_URL="https://gateway.example.com"
ANTHROPIC_AUTH_TOKEN="网关访问密钥"
ANTHROPIC_MODEL="网关公布的模型别名"

ANTHROPIC_AUTH_TOKEN通常对应 Authorization: Bearer，ANTHROPIC_API_KEY则用于 X-Api-Key。两者不要同时随意设置，否则可能导致 Claude Code 使用了错误的认证方式。Anthropic 的网关文档还说明，apiKeyHelper的优先级低于这两个环境变量。参考：Anthropic LLM Gateway 配置文档。

推荐先用网关的模型列表接口或控制台确认模型名，再运行最小请求。不要把 OpenAI 的 https://api.openai.com/v1 直接作为 ANTHROPIC_BASE_URL，因为 Claude Code 发出的请求协议是 Anthropic Messages，不是普通 OpenAI Chat Completions。

方案三：用 cc switch 切换配置，理解它到底改了什么

cc switch 不是把 Claude Code 原生改造成 OpenAI 客户端，而是帮助你切换供应商配置。根据其公开使用说明，Claude Code 的站点配置通常包含 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 等变量，并写入 Claude Code 的环境配置或由本地代理接管请求。参考：cc switch 配置说明。

在 cc switch 中添加或选择一个明确支持 Anthropic Messages 的接口。
检查它展示的 Base URL 是否指向 Anthropic 兼容入口，而不是 OpenAI 原生入口。
检查模型字段是否为该接口实际暴露的别名。
切换后重新打开终端，再运行 claude；如果工具启用了本地代理，确认本地端口正在监听。
用 /status 查看当前会话的认证和模型状态。

不同版本的界面、字段名称和代理接管方式可能变化，因此不要把某个版本的截图当成固定配置。cc switch 适合频繁切换；如果你需要审计、预算和稳定模型别名，LiteLLM 配置更容易纳入项目管理。

settings.json 持久化配置与模型映射

Claude Code 支持在 ~/.claude/settings.json 的 env 中保存环境变量；项目级配置则可放在 .claude/settings.json 或仅本机使用的 .claude/settings.local.json。官方设置文档说明，用户级文件影响本机所有项目，项目级文件可能随代码库共享，因此密钥不应写进会提交到 Git 的文件。参考：Claude Code Settings 文件与优先级、Claude Code 环境变量参考。

推荐的本机配置结构如下：

{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_AUTH_TOKEN": "sk-你的-LiteLLM-Key",
"ANTHROPIC_MODEL": "gpt-via-openai",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-via-openai",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-via-openai",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-via-openai",
"CLAUDE_CODE_SUBAGENT_MODEL": "gpt-via-openai"
}
}

小模型和后台任务是常见遗漏点。Claude Code 除主模型外，还可能使用 Opus、Sonnet、Haiku 别名以及子代理模型；如果网关只映射主模型，后台调用可能出现 404 或“模型不存在”。因此应先确认这些变量在当前版本是否启用，再让网关为每个实际请求到的模型名提供映射。不要照抄不存在的模型 ID，模型名称以当前客户端和网关模型列表为准。

接入成功后的最小验证

先验证网关本身，再验证 Claude Code，能更快区分“OpenAI Key 无效”和“Claude Code 配置错误”。

确认变量存在，但不要把完整密钥打印到终端：macOS/Linux/WSL 可用 test -n "$ANTHROPIC_AUTH_TOKEN" && echo configured；PowerShell 可用 if ($env:ANTHROPIC_AUTH_TOKEN) { 'configured' }。
查看网关提供的模型列表，确认 gpt-via-openai 或你的实际别名存在。
启动 claude 后运行 /status，确认没有继续使用原来的订阅登录或旧 Key。
先发送一个不涉及工具调用的短请求，再测试文件读取、编辑和流式输出。

OpenAI 官方建议在排错时记录请求 ID 和限流响应头；对于网关场景，也应保留网关日志中的请求时间、模型别名和 HTTP 状态码，但不要记录完整 API Key。参考：OpenAI Authentication 与请求排错。

常见错误排查表

现象	优先检查	处理方法
400	JSON 字段、消息格式、工具参数	先用网关支持的最小请求验证；删除网关不支持的字段，确认 Claude Code 与网关协议版本匹配。
`unsupported_parameter`	请求中包含上游不接受的参数	检查网关是否把 Anthropic 字段原样转发给 OpenAI；升级或调整协议映射，不要只重复发送请求。
401	Key、认证头、环境变量优先级	确认 `ANTHROPIC_AUTH_TOKEN` 是否为网关 Key；清理旧的 `ANTHROPIC_API_KEY`，再重启终端。
403	Key 没有模型权限、项目权限或网关策略拒绝	检查虚拟 Key 的模型白名单、团队权限和网关访问策略。
404 或模型不存在	Base URL 路径或模型映射	确认 Claude Code 指向网关根地址；检查 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL` 和 `CLAUDE_CODE_SUBAGENT_MODEL` 是否都能被网关识别。
429	上游或网关限流、余额或并发限制	查看响应头和网关日志，降低并发并采用带上限的退避；不要无间隔无限重试。
超时	Base URL、代理、防火墙、网关响应时间	先用同一地址做最小请求；再检查 HTTPS 代理、证书和网关超时设置。
流式输出中断	SSE 转换、反向代理缓冲、上游超时	确认网关支持 Anthropic 流式响应，关闭不必要的代理缓冲，并查看网关是否在请求完成前断开连接。

Key 安全与费用边界

OpenAI Key 只放在 LiteLLM 或服务端，不要放入网页、插件仓库或公共 .claude/settings.json。
本机设置文件若包含 Key，应加入 Git 忽略规则；更稳妥的方式是使用环境变量或密钥管理服务。
发现 Key 泄露后，应立即在对应平台撤销并重新生成，同时检查用量和账单。
第三方网关可能有自己的费用、限速、日志和数据处理规则；没有公开且可核验的条款时，不要假设其价格、隐私或可用性。
Claude Code 订阅、OpenAI API 按量计费和网关费用是三条不同的计费链路，接入前分别核对。

如果你只想让 Claude Code 调用 OpenAI 模型，最稳妥的决策顺序是：先确认接口协议，再确认模型别名，最后配置 Key。不要从“把 OPENAI_API_KEY 填进去”开始。

常见问题

Claude Code 能不能直接使用 OPENAI_API_KEY？

通常不能。Claude Code 默认发送 Anthropic Messages API 请求，因此单独设置 OPENAI_API_KEY 不会自动把请求改成 OpenAI 协议。需要使用 LiteLLM 或其他 Anthropic 兼容网关做协议转换。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 选哪个？

如果网关要求 Bearer 认证，优先使用 ANTHROPIC_AUTH_TOKEN；如果网关要求 X-Api-Key，则使用 ANTHROPIC_API_KEY。不要同时保留旧变量，以免认证优先级导致请求发到错误账户。

为什么主模型能用，但 Claude Code 仍提示模型不存在？

Claude Code 可能还会调用 Haiku、Sonnet、Opus 别名或子代理模型。检查 ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL，并确保网关为这些名称提供映射。

Claude Code 的 settings.json 放在哪里？

个人全局配置通常放在 ~/.claude/settings.json；项目共享配置放在项目内的 .claude/settings.json；只想本机使用的项目配置可放在 .claude/settings.local.json。含密钥的文件不要提交到 Git。

ChatGPT Plus 或 Pro 能直接抵扣 OpenAI API 用量吗？

一般不能。ChatGPT 订阅与 API 平台是独立计费系统。只有在特定应用支持“使用 ChatGPT 登录”并且你主动授权时，才可能使用计划额度；这不等同于把 ChatGPT 订阅转换成 API Key。

参考资料

Anthropic：Claude Code 安装与认证
Anthropic：Claude Code LLM Gateway 配置
Claude Code：Settings 文件与优先级（code.claude.com）
OpenAI：API Authentication
OpenAI：ChatGPT 与 API 平台账单说明
LiteLLM：Claude Code Client Setup（docs.litellm.ai）
cc switch：Claude Code 配置说明（ccswitch.io）