返回指南
故障排查·2026年7月17日·更新于 2026年9月30日·阅读约 6 分钟

OpenAI 兼容 API 返回 401/403——base_url 和请求头陷阱

OpenAI 兼容 API 的核心就是让 SDK 直接工作——因此当它返回 401 时,问题几乎总是在你更改的两行中:base_url 和 api_key。下面按实际发生的顺序列出各种失败模式。

最后审核于 。

OpenAI 兼容 API 的核心就是让 SDK 直接工作——因此当它返回 401 时,问题几乎总是在你更改的两行中:base_url 和 api_key。下面按实际发生的顺序列出各种失败模式。

错误

响应(HTTP 401)
{
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid or missing API key.",
    "code": "invalid_api_key"
  }
}

原因和解决方法一览

原因解决方法
base_url 缺少 /v1 后缀(或重复添加)大多数网关要求的格式正好是 https://host/v1——SDK 会自行追加 /chat/completions。
来自不同主机的密钥sk-… 密钥只能向签发它的服务进行身份验证;检查前缀 ↔ 主机是否对应。
企业代理 / WAF 剥离 Authorization 请求头从干净的网络进行测试;配置代理以透传 Authorization。
OPENAI_API_KEY 环境变量覆盖了你显式传入的密钥SDK 默认读取环境变量——在某些配置中,过时的环境变量会静默生效;请显式传递 api_key。

验证 SDK 实际访问的确切 URL

打印 client.base_url,并调用 GET /v1/models——这是成本最低的身份验证端点。如果 /models 有效,说明身份验证正常,错误出在其他地方:

check.py
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # exactly one /v1
    api_key="sk-kn-...",                 # explicit beats env vars
)
print(client.base_url)
print([m.id for m in client.models.list().data][:5])

使用 Curl 访问同一主机,以排除 SDK 问题

如果带有 Authorization: Bearer 的 curl 有效而 SDK 无效,请比较 SDK 的实际请求(设置 OPENAI_LOG=debug)——十有八九是代理或环境变量重写了某些内容。

如果你通过 Kunavo 调用

Kunavo 的端点严格遵循 OpenAI 的接口格式,地址为 https://api.kunavo.com/v1,使用 Bearer 身份验证;GET /v1/models 可作为身份验证冒烟测试。如果你的代码能通过 api.openai.com 运行,将 base_url 指向 Kunavo 就是唯一需要做的更改——使用相同的 SDK、相同的数据传输格式,一个密钥即可调用 Claude、GPT 和媒体模型。

常见问题

网关上的 401 与 403——有什么区别?

401 = 凭据本身未被接受(缺少或无效的密钥)。403 = 密钥有效,但无权执行该操作(密钥已禁用、账户已暂停或不允许使用该模型)。请阅读错误正文——兼容 API 会在 error.message 中说明原因。

为什么我的代码在本地有效,在 CI 中却返回 401?

CI 是不同的环境:密钥未设置、设置成了其他服务的密钥,或者代理剥离了请求头。在 CI 内记录 repr(key[:12]) 和 base_url,查看实际发送的内容。

相关指南

更多错误语义请参阅 错误参考;通过 注册 和 身份验证指南 获取密钥只需一分钟。