很多人拿到一个 Key，看到文档写着「兼容 OpenAI」，就照着老代码复制粘贴，结果 401、404 一起报，还搞不清是 Key 错还是地址错。这篇不重复协议字段的细节，只聚焦一件事：兼容接口下 Key 该放在哪、以什么形式传、什么情况下会失效，以及怎么一步步验证它真的通了。
拿到一个 Key，看到文档写着「兼容 OpenAI」，很多人直接复制老代码跑，结果 401 和 404 一起报，分不清是 Key 错还是地址错。这篇只讲一件事：兼容接口下 Key 该放在哪、以什么形式传、什么情况下会失效，以及怎么一步步验证它真的通了。协议字段的细节不在这里展开。
先记住一个前提：所谓「兼容」，兼容的是请求和响应的结构，不是鉴权链路的每一个实现细节。同一段代码在 A 平台能跑、到 B 平台报错，大概率不是你的代码坏了，而是两边对 Key 的传递方式要求不同。所以排查顺序要固定下来，别东改一处西改一处。
先分清 Key 和 Base URL 是两个独立的东西
Key 是身份凭证，Base URL 是请求入口，这两样出问题给出的信号完全不同。地址写错，通常得到 404、连接超时或者一个空响应；鉴权写错，通常是 401 或 403。报错码本身就是最好的线索，先看码，再决定去改哪一项，能省掉一大半瞎试的时间。
| 现象 | 更可能的原因 | 先动哪里 |
|---|---|---|
| 404、找不到路径 | Base URL 拼错或多写/少写后缀 | 核对请求入口完整路径 |
| 401、403 | Key 无效、过期或传递格式不对 | 检查请求头写法与 Key 本身 |
| 连接超时、无响应 | 网络不可达或地址指向了不存在的域 | 先确认网络能否触达目标地址 |
| 部分请求成功部分报错 | 额度、分组或权限范围限制 | 看该 Key 的可用范围 |
有一点要特别注意：兼容层只保证请求结构像，不保证每个中转站都接受同一种 Key 传递方式。有的实现只认标准请求头，有的要求额外带一个自定义字段，还有的对大小写和空格宽容度不一样。别凭经验套用，以你实际接入的那个平台的文档为准。
Key 的三种常见放置位置
- Authorization 请求头：多数兼容实现只看 Bearer 后面那一串，前缀写错、多一个空格、少一个空格都会失败，复制粘贴时尤其容易带上不可见字符；
- 自定义请求头：部分平台要求额外字段来区分租户或分组，字段名和取值必须以该平台文档为准，不要照搬别家的写法；
- 配置文件或环境变量：本地开发建议走环境变量，避免 Key 被提交进代码仓库，也避免被日志或异常堆栈打印出来
如果你在本地反复调试，建议给自己定一个规矩：代码里只读变量名，不出现 Key 的字面量。这样换 Key、换环境都只是改变量的事，不用动代码，也不会出现「改了一处忘了另一处」的情况。
代码里怎么传：从环境变量到 SDK
用官方 SDK 时，通常只需要改两个地方：把请求入口指向兼容地址，把 Key 从环境变量读进来，其余参数全部保持默认，先让它跑通一次最小请求。很多人一上来就把超时、重试、代理全配一遍，出问题时反而不知道是哪一项在捣乱。
- 第一步：把 Key 放进环境变量在本机设置一个变量名清晰的变量，例如带项目前缀的名字。验证方式是重启终端后打印变量名，确认读得到且没有多余空格。
- 第二步：代码里只引用变量名初始化客户端时从环境变量取值，不要在源码里写 Key 字符串。验证方式是全局搜索 Key 的前几位，源码里应当搜不到。
- 第三步：先跑一个最小请求不改任何可选参数，只发一次最简单的调用。通了再逐步加参数，每加一项就复测一次。
用裸 HTTP 请求时，活儿多一点：请求头名称、大小写、是否带 Bearer 前缀，都得自己确认。不同实现宽容度不同，有的会把缺前缀的请求直接拒掉，有的则默默接受。多环境共存时，给每个环境的 Key 起不同的变量名，别让测试流量打到正式业务上。
客户端和工具里的 Key 填在哪
图形客户端确实省事，但它的 Key 输入框多数是明文落盘。公用电脑上用完记得清理，别只关窗口。另外有些客户端把「服务地址」和「Key」放在两个不同页面，改完一处没保存就跳走，也会出现「明明改对了却没生效」。
- 图形客户端
- Key 多存明文配置，公共设备用完要清；地址与 Key 常在两个页面，改完都要保存
- 命令行工具
- 往往同时读环境变量和配置文件，优先级不明确时先只留一处配置，排除干扰
- 多工具共存
- 把 Key 和地址写进各自的配置域，不要几个工具共用同一个全局变量，否则改一处全乱
判断「改了没生效」有个笨但有效的办法：临时把地址改成一个明显错误的写法，看工具是否真的报错。如果照样「成功」，说明你改的那份配置压根没被读取，问题在配置优先级上，不在 Key 上。
四步验证 Key 是否真的可用
验证不要一步到位，拆成四步，每一步只回答一个问题。这样即使失败，你也能立刻定位到是哪一环，而不是笼统地觉得「接口不行」。这套顺序在任何兼容平台上都通用。
- 第一步：通网络只发一个最小请求，确认能触达目标地址。看的是能不能连上，不是返回内容对不对。
- 第二步：故意用错 Key用一串明显无效的 Key 发一次，记住返回的报错形态。日后看到同样形态，就知道是鉴权问题而不是地址问题。
- 第三步：换回正确 Key确认返回结构里该有的字段都在，没有缺字段或字段变成错误信息的情况。
- 第四步：量一次延迟基线到站内接口测速页面跑一次，记住正常情况下的响应区间。以后变慢你能分清是网络慢还是 Key 出了问题，别把慢当成错。
哪些情况下这套做法不适用
- 平台要求签名或短期令牌时，静态 Key 直接调用不成立，必须先走换取流程拿到临时凭证；
- 浏览器和移动端直连会暴露 Key，任何人打开开发者工具都能看到，必须经自有服务端转发；
- Key 绑定了来源 IP、来源域名或额度分组时，换机器、换网络、换入口就会失效，这属于策略限制不是配置错误
还有一类容易误判的情况：Key 本身没问题，但账号或分组层面没有对应模型的权限。表现可能是能连上、鉴权也过，但请求被拒。这时候去改代码没用，得回去看这个 Key 被授权了什么范围。具体到某个平台支持哪些模型和权限，可以到 /models 核对当时的资料。
泄漏和轮换：把 Key 当临时凭证
Key 只要进过聊天记录、截图或者公开仓库，就该当成已经泄漏，直接换，不要心存侥幸去判断「应该没人看到」。轮换的时候别一次性全换，留一个新旧并存的小窗口，避免上线瞬间全量失败。
| 动作 | 怎么做 | 为什么 |
|---|---|---|
| 按用途拆分 | 不同业务用不同 Key | 出问题时只停掉一个，不影响全部 |
| 定期更换 | 设置提醒，到期就换 | 缩短泄漏后的有效窗口 |
| 新旧并存 | 先上新 Key 再下线旧 Key | 避免切换瞬间全量失败 |
| 留好记录 | 记清每个 Key 用在哪 | 排查时不用靠猜 |
选接入的兼容平台时，别只看能不能连上。有的平台在可观测性和稳定性上做得好一些，有的就差一点。想横向比一比，可以到 /sites 看各家平台的检测记录，再到 /price-watch 核对当时的计价口径，把「能连上」和「长期稳定」分开评估。
下一步把上面四步验证走一遍，再顺手确认你的 Key 有没有被写进代码或日志里。想省事的可以到站内接口测速页面量一次基线，以后遇到变慢变错就能快速分清是哪一类问题。→常见问题
同一个 Key 能用在多个兼容平台上吗？
通常不行，也不建议。Key 一般和某个平台或某个账号绑定，拿到别处用要么直接鉴权失败，要么在计费归属上出问题。跨平台切换时更稳的做法是每个平台单独申请一个 Key，按用途命名，出问题能快速定位是哪一路。
Key 没错为什么还是 401？
先排除三个常见原因：请求头里多了引号或换行、Bearer 前缀拼写或空格不对、Key 前后带上了复制时混进来的隐藏字符。如果都正常，再确认这个 Key 是否被平台限定了来源或额度分组，以及是否已经过期或被禁用。
Key 放在前端页面里行不行？
不建议。前端代码、浏览器请求记录和网络面板都能看到它，等于公开。要做浏览器端直连，应通过自己的服务端做一层转发并做来源校验；纯静态站点想省这一步，就得接受 Key 被刷的风险。
怎么知道 Key 消耗的是哪个额度？
不同平台的额度口径不一样，有的按 Key 分组，有的按账号统一扣。别凭感觉猜，去站内用量榜和价格变动追踪页面看你这类接口的计费方式，再对照平台后台的用量明细确认归属。
多个项目共用一个 Key 有问题吗？
短期图省事可以，但会带来两个麻烦：一是某个项目跑飞时很难单独限流，二是轮换时所有项目要一起改。建议至少按环境拆开，开发、测试、生产各一个，成本没增加多少，排错省很多事。
