401 Unauthorized 的含义很直接：服务端没有确认这次请求的身份。它与模型能力无关，也不是「服务器不稳定」，更不需要重装客户端。最常见的原因是 Key 复制不完整、请求头写错、客户端仍在用旧 Key，或者把网页登录密码当成了 API Key。这篇按成功率从高到低给出完整排查路径，多数人在前三步就能解决。
先分清 401、403、429 和 404
排查之前先确认你面对的确实是鉴权问题：
- 401：身份没被识别——Key 错、没带、格式不对
- 403：身份有效但没有权限——分组、模型白名单或额度策略拦截
- 429：身份和权限都对，但请求频率超限
- 404：路径或模型不存在，见 404 排查指南
一句话：401 几乎总是「Key 没有被正确送到服务端」，所以排查重点是 Key 本身、请求头和配置生效链路，而不是模型和参数。反过来这也是个好消息：401 是所有 API 报错里最机械、最可穷举的一类，不存在玄学，按清单走完必有结论。
现象 → 原因 → 解法 对照表
| 现象 | 原因 | 解法 |
|---|---|---|
| curl 直接请求就 401 | Key 复制不完整、带空格换行，或已被删除 | 重新复制到纯文本编辑器检查，必要时重建 Key |
| 网页能登录，API 却 401 | 把登录密码或 Cookie 当成了 API Key | 到控制台创建 sk- 开头的 API Key |
| 换了新 Key 仍然 401 | 客户端缓存旧配置，或旧环境变量覆盖新值 | 重启终端与客户端，检查变量来源 |
| curl 正常，SDK 却 401 | SDK 的 api_key 或 base_url 传参错误 | 检查代码里实际读取的变量名 |
| 只有某个工具 401 | 该工具配置了另一个（旧）服务商条目 | 确认当前模型绑定的是新配置 |
| 偶发、时好时坏的 401 | 多处配置互相覆盖（全局、项目、环境变量） | 统一保留唯一配置来源 |
第一步：确认你拿到的是 API Key
Zivv 的 API Key 在控制台的 API 令牌页面创建，以 sk- 开头。下面这些都不能替代 API Key：
- 网站登录密码
- 浏览器 Cookie
- 充值订单号
- Key 的名称或备注
刚创建的 Key 先粘贴到纯文本编辑器里检查：前后有没有空格、中间有没有被聊天软件插入的换行。富文本工具经常自动补空格，肉眼很难发现，但服务端会因此判定 Key 无效。
另外注意，完整的 Key 值通常只在创建时展示一次。如果不确定手里的 Key 是否完整，不要纠结——删掉重建只要十秒，重建一个新 Key 往往比反复排查一个可疑的旧 Key 更快。
第二步：用最小请求排除客户端问题
先绕过 Claude Code、Codex 或桌面客户端，用 curl 直接请求模型列表：
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key"结果这样判断：
| 结果 | 说明 | 下一步 |
|---|---|---|
| 返回模型列表 | Key 有效 | 问题在客户端，去第四步查缓存 |
| 仍然 401 | Key 或请求头有问题 | 重新复制 Key，检查 Bearer 格式 |
| 无法连接 | 不是鉴权问题 | 检查网络、域名和代理设置 |
这一步是整个排查的分水岭：curl 通了，问题一定在客户端配置；curl 不通，问题一定在 Key 或请求头。
第三步：检查 Authorization 请求头写法
OpenAI 兼容请求的标准写法是 Authorization: Bearer <KEY>。注意 Bearer 后面有且只有一个英文空格，不要用中文引号包裹 Key。用 SDK 时不需要手写请求头，把参数传对即可：
from openai import OpenAI
client = OpenAI(
api_key="sk-your-key", # 不要多包一层引号或空格
base_url="https://zivv.pro/v1",
)
print(client.models.list().data[0].id)常见的写错方式：Bearer 拼错或丢失、Key 外面套了引号一起发送、从配置文件读取时带上了行尾换行符。如果代码从环境变量读 Key，确认读取的变量名和你导出的一致——OPENAI_API_KEY 和 OPENAI_KEY 差一个词，SDK 只认前者。
还有一种隐蔽情况：反向代理或网关会剥掉自定义请求头。如果你的请求经过公司内网代理或自建转发层，确认 Authorization 头被原样透传，必要时抓一下出口请求对比。
第四步：检查 API 地址
不同协议的地址不同，写错时部分客户端会拼出错误路径，最终表现成鉴权失败：
- OpenAI SDK、Codex、Cherry Studio 等填
https://zivv.pro/v1 - Claude Code 设置
ANTHROPIC_BASE_URL=https://zivv.pro，不要加/v1 - Gemini 协议用
https://zivv.pro/v1beta
一个方便记忆的规律：OpenAI 协议带 /v1，Anthropic 协议不带，Gemini 用 /v1beta。把这三条写进团队的接入文档，能替新人省下大量试错时间。完整地址规则见 API 端点说明。
第五步：确认客户端真的用了新 Key
大量「我明明换了 Key 为什么还是 401」来自缓存与覆盖：
- 修改环境变量后没有重启终端，旧进程还带着旧值
- 系统级变量和当前终端变量同时存在，旧值覆盖新值
- 客户端里存了多个服务商配置，当前模型仍绑定旧条目
- Docker、远程开发环境、CI 没有同步本机的新变量
macOS / Linux 可以直接检查当前终端实际生效的值：
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN | cut -c1-6 # 只看前缀，避免泄露完整 Key
env | grep -iE "openai|anthropic" # 找出所有相关变量，看有没有旧值Claude Code 用户重开终端后按 Claude Code 配置文档核对两个变量；Codex 用户对照 Codex 配置文档。
各客户端的高发点速查
不同客户端触发 401 的姿势不太一样，对号入座能更快命中：
Claude Code
- Key 要放在
ANTHROPIC_AUTH_TOKEN，写成ANTHROPIC_API_KEY是最高频的错误 ANTHROPIC_BASE_URL只填https://zivv.pro，不加/v1- 改完变量必须重开终端；写进了
~/.zshrc但当前窗口没有source，等于没改
Codex
- 用的是
OPENAI_API_KEY和OPENAI_BASE_URL（带/v1），别和 Anthropic 那组变量搞混 - 项目级配置文件可能覆盖环境变量，检查项目目录下有没有残留的旧配置
Cherry Studio 等桌面客户端
- 服务商条目里存的是旧 Key：界面上看着改了，实际保存的还是旧值，删掉整个条目重建最干净
- 配了多个服务商时，当前对话绑定的可能不是你刚改的那个
- 改完配置完全退出进程再重开，不要只关窗口
服务器与 CI
- 本机能跑、服务器 401，几乎都是环境变量没同步：检查部署脚本、容器环境变量和密钥管理服务里的值
- CI 的 Secret 更新后要重新触发构建才会生效
第六步：检查 Key 状态和权限
前五步都过了还 401，进控制台确认：
- Key 没有被删除或禁用
- Key 的有效期没有结束
- Key 所属分组允许访问目标接口
- 账号余额和 Key 限额仍然可用
余额问题通常有独立提示，但个别客户端会把一切失败都显示成笼统的「认证失败」。到用量记录里看请求有没有到达平台，是判断问题在哪一侧的可靠办法：用量里完全没有记录，说明请求被挡在鉴权层之前或没发出来；有记录但失败，错误详情里会写明真实原因。
顺带说一句：不建议一上来就重装客户端。401 是配置层面的问题，重装既不清理环境变量，也不重建 Key，大概率装完还是 401，反而把之前的排查线索清空了。按本文顺序走一遍，几乎总能在某一步找到确切原因。
如果 Key 可能泄露
不要继续测试旧 Key，也不要把完整 Key 发给任何人（包括客服）。正确处理：
- 立即删除或禁用旧 Key
- 创建新 Key 并更新所有使用位置
- 检查最近用量是否有异常调用
- 排查泄露渠道：Git 提交、截图、共享文档
最常见的泄露渠道是 Git：Key 被写进代码或配置文件后 push 到了仓库。注意即使后来删掉了文件，历史提交里仍然能翻到，所以只要进过 Git 历史就应当视为已泄露，直接换 Key，而不是删文件了事。日常预防的办法是把含 Key 的文件加进 .gitignore，提交前过一眼 diff。
团队使用时给每个成员、项目、自动化任务单独建 Key，单个 Key 泄露可以精准停用而不影响其他业务；统一的额度与用量管理用团队模式。
常见问题 FAQ
Q：401 的请求会扣费吗？ A：不会。鉴权失败的请求没有进入模型计费环节，不消耗余额。
Q：OpenAI 或 Anthropic 官方的 Key 能直接在 Zivv 用吗？ A：不能。请求发给哪个平台就要用哪个平台的 Key，接 Zivv 就用控制台创建的 sk- Key。
Q：余额不足报的是 401 吗？ A：通常是独立的错误提示，但个别客户端会笼统显示为认证失败，以用量记录和控制台余额为准。
Q：多个工具共用一个 Key 会导致 401 吗？ A：不会直接导致，但强烈建议一工具一 Key：排查时能立刻定位是哪个工具的配置问题，泄露时也能单独停用。
Q：昨天还能用的 Key，今天突然 401 是怎么回事？ A：Key 本身不会「自己坏掉」。优先检查：Key 是否被管理员禁用或到期、账号余额是否耗尽、是否有人在控制台做过清理。团队场景里成员 Key 被误删是常见原因，这也是给团队做分级权限管理的意义。
最短排查顺序
- 确认用的是
sk-开头的 API Key - curl 请求
/v1/models - 检查
Authorization: Bearer格式 - 核对 OpenAI 与 Claude Code 的地址差异
- 重启终端和客户端，排除旧配置
- 控制台查 Key 状态、余额和用量记录
这个顺序的设计逻辑：先排除「根本不是 Key」的乌龙，再用最小请求二分定位，最后才碰状态和权限这些需要进控制台的项。多数人会在第 2、3 步命中原因。
仍然失败时联系支持，提供发生时间、客户端、请求地址、错误码和 Key 的末四位，不要发送完整 Key。更多错误含义见错误码说明。还没有 Key 的话，注册 Zivv 一分钟就能创建第一个，从一开始就按本文的规范配置，基本不会再见到 401。