API Key 报 401 Unauthorized：从 Key、地址到请求头逐项排查

401 Unauthorized 的含义很直接：服务端没有确认这次请求的身份。它通常与模型能力无关，也不是“服务器不稳定”。最常见的原因是 Key 复制不完整、请求头写错、客户端仍在使用旧 Key，或者把网页登录密码当成了 API Key。

这篇按成功率从高到低排查，不需要反复重装客户端。

第一步：确认你拿到的是 API Key

Zivv 的 API Key 在控制台的 API 令牌页面创建，通常以 sk- 开头。下面这些都不能替代 API Key：

• 网站登录密码
• 浏览器 Cookie
• 充值订单号
• Key 名称或备注

如果刚创建 Key，先复制到纯文本编辑器检查前后有没有空格或换行。聊天软件和富文本工具有时会自动补空格，肉眼不容易发现。

第二步：用最小请求排除客户端问题

先绕过 Claude Code、Codex 或桌面客户端，直接请求模型列表：

curl https://zivv.pro/v1/models \
  -H "Authorization: Bearer sk-your-key"

结果可以这样判断：

OpenAI 兼容请求的标准写法是 Authorization: Bearer <KEY>。注意 Bearer 后面有一个空格，不要加中文引号。

第三步：检查 API 地址

不同工具使用的地址不完全相同：

• OpenAI SDK、Codex、Cherry Studio 等通常填写 https://zivv.pro/v1
• Claude Code 设置 ANTHROPIC_BASE_URL=https://zivv.pro，不要在后面加 /v1

地址写错更常见的是 404，但有些客户端会拼接出错误路径，最终表现成鉴权失败。完整地址规则可查看 API 端点说明。

第四步：确认客户端真的用了新 Key

很多“我明明换了 Key，为什么还是 401”来自缓存：

1. 修改环境变量后没有重启终端
2. 系统变量和当前终端变量同时存在，旧值覆盖新值
3. 客户端有多个服务商配置，当前模型仍绑定旧服务
4. Docker 或远程开发环境没有同步本机变量

Claude Code 用户可以重新打开终端，再按 Claude Code 配置文档 检查两个变量。Codex 用户查看 Codex 配置文档。

第五步：检查 Key 状态和权限

进入控制台确认：

• Key 没有被删除或禁用
• Key 的有效期没有结束
• Key 所属分组允许访问目标接口
• 账号余额和 Key 限额仍可用

余额问题通常有独立提示，但不同客户端可能只展示一条笼统的“认证失败”。可以在用量记录中确认请求是否到达平台。

如果 Key 可能泄露

不要继续测试旧 Key，也不要把完整 Key 发给客服。正确处理方式是：

1. 立即删除或禁用旧 Key
2. 创建一个新 Key
3. 更新所有使用位置
4. 查看最近用量是否有异常

团队使用建议每个成员、项目和自动化任务单独建 Key。这样单个 Key 泄露时可以精准停用，不影响其他业务。需要统一额度管理时可使用 团队模式。

最短排查顺序

1. 确认使用的是 sk- API Key
2. 用 curl 请求 /v1/models
3. 检查 Authorization: Bearer 格式
4. 核对 OpenAI 与 Claude Code 的地址差异
5. 重启客户端或终端，排除旧配置
6. 查看 Key 状态、余额和用量记录

如果仍然失败，联系支持时提供发生时间、客户端、请求地址、错误码和 Key 的末四位，不要发送完整 Key。更多错误含义可查 错误码说明，第一次接入也可以从 AI API 新手指南 重新核对。