API 错误排查
401 鉴权失败排查
401 鉴权失败排查讲清 OpenAI-compatible API 中 401 Unauthorized、API Key、Authorization Bearer、环境变量、Base URL、部署 Secret 和 OfApp.cn 接入检查。
401 Unauthorized 表示请求没有通过鉴权。对 OpenAI-compatible API 来说，请求
还没有真正进入模型调用层，常见问题集中在 API Key、Authorization 请求头、
环境变量、Base URL、账号项目、部署 Secret 或客户端配置。
排查 401 的重点不是换模型、改 Prompt 或增加重试，而是确认“请求里到底带了 哪个身份凭证”。本文示例按 OfApp.cn 的 OpenAI 兼容入口组织；具体模型、端点 能力、额度和价格请以 OfApp.cn 控制台或官方文档为准。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 6 分钟 |
| 更新时间 | 2026-07-03 |
| 适合读者 | AI 初学者、开发者、运维、产品经理、使用 Codex 或 AI 客户端的人 |
| 适合任务 | 排查 401 Unauthorized、API Key 缺失、Bearer 请求头、环境变量、部署 Secret、Base URL 不匹配 |
401 Unauthorized 是什么
Section titled “401 Unauthorized 是什么”HTTP 401 表示服务端没有接受当前请求的身份凭证。OpenAI 官方错误码文档把 401 归为 authentication issues，常见原因包括 API Key 不正确、项目或组织不 匹配、Key 被删除或停用、本地缓存了旧 Key，或 IP allowlist 等访问策略不允 许当前请求。
在 OfApp.cn 或其他 OpenAI-compatible API 场景里，可以把 401 理解成“门口的 身份检查没通过”。它通常不是模型名、上下文长度、Prompt 质量或输出格式问题。 短请求和长请求都会失败时，更要先查鉴权链路。
401 和 invalid API key 怎么分
Section titled “401 和 invalid API key 怎么分”这两个错误都在鉴权层，但排查重点不同：
| 错误 | 更像什么问题 | 排查入口 |
|---|---|---|
| 401 Unauthorized | 没有发凭证、Bearer 格式错、运行时没读到 Key | 本页 |
| invalid API key | Key 存在但无效、复制损坏、Key 与入口不匹配 | invalid API key |
| 403 Forbidden | 身份可识别，但没有权限访问某个资源或能力 | 403 Forbidden 错误排查 |
| 404 Not Found | 端点路径、HTTP 方法或资源 ID 不存在 | 404 Not Found 错误排查 |
如果错误体只写 unauthorized，按 401 排查；如果明确出现 invalid API key，可 以直接转到密钥无效页面。两者都不要靠无限重试解决。
常见触发场景
Section titled “常见触发场景”| 场景 | 典型表现 | 优先检查 |
|---|---|---|
| API Key 为空 | 本地或线上一直 401 | 环境变量是否存在，进程是否重启 |
| Bearer 头缺失 | curl、SDK 或代理没有传 Authorization |
请求头拼接和代理转发 |
| Key 前后有空白 | 看起来填了 Key，仍然失败 | 复制来源、换行、引号、空格 |
| Key 与 Base URL 不匹配 | 换服务商或中转后报 401 | Key、Base URL、模型名是否同源 |
| 部署 Secret 没生效 | 本地能跑，线上 401 | 平台 Secret、预览环境、生产环境 |
| 客户端读旧配置 | 改了 Key，但工具仍失败 | Codex、SDK、AI 客户端自己的配置 |
| 前端直连接口 | 浏览器里暴露或丢失 Key | 改为服务端代理 |
| 访问策略限制 | 特定网络、机器或项目失败 | 项目、组织、IP allowlist 或账号状态 |
先记录哪些证据
Section titled “先记录哪些证据”排查 401 时要保留证据，但不能暴露密钥。
| 应记录 | 不应记录 |
|---|---|
| 状态码、错误类型、请求时间 | 完整 API Key |
| 最终请求 URL 和端点 | 完整 Authorization Header |
Base URL 的域名和是否带 /v1 |
Cookie、访问令牌、账号密码 |
| Key 长度、前后少量脱敏字符 | 未脱敏用户文件、客户文本 |
| 运行环境：本地、Docker、CI、生产 | 带密钥的终端截图 |
| SDK 或客户端名称与版本 | 可还原身份的内部 URL |
可以记录这种脱敏摘要：
status: 401endpoint: /v1/chat/completionsbase_url_host: api.ofapp.cnkey_present: truekey_length: 67key_hint: sk-...abcdruntime: production server最小 cURL 验证
Section titled “最小 cURL 验证”先绕开 SDK、前端框架、业务代码和代理。OfApp.cn 官方文档展示的 OpenAI 兼容
Base URL 是 https://api.ofapp.cn/v1，并展示了使用
Authorization: Bearer 填入你的 API Key 的请求示例。
export OPENAI_BASE_URL="https://api.ofapp.cn/v1"export OPENAI_API_KEY="sk-xxxx"
echo "key length: ${#OPENAI_API_KEY}"
curl -i "$OPENAI_BASE_URL/models" \ -H "Authorization: Bearer $OPENAI_API_KEY"看三件事：
| 结果 | 判断 |
|---|---|
| 返回模型列表或可解析响应 | Key、Base URL 和 Bearer 头基本匹配 |
| 仍然 401 | Key 来源、请求头、账号状态或入口不匹配 |
| 网络层失败 | 先查 DNS、代理、防火墙或公司网络 |
如果当前服务商不支持 /models，可以换成官方文档推荐的最小端点。排查目的不
是生成内容，而是证明当前凭证能被服务端接受。
环境变量怎么查
Section titled “环境变量怎么查”很多 401 不是 Key 错，而是当前进程没有读到 Key。
| 运行环境 | 检查方式 | 注意事项 |
|---|---|---|
| 终端 | echo ${#OPENAI_API_KEY} |
只打印长度，不打印完整 Key |
| Node.js 服务 | 检查 process.env.OPENAI_API_KEY 是否存在 |
修改 .env 后重启 dev server |
| Python 脚本 | 检查 os.environ.get("OPENAI_API_KEY") 是否存在 |
Notebook 内核可能缓存旧变量 |
| Docker | 检查 Compose、docker run -e 或 Secret |
不要写进 Dockerfile |
| CI/CD | 检查环境、分支和 Secret 名称 | 预览环境与生产环境可能不同 |
| Codex / CLI | 检查工具自己的配置和登录状态 | 不一定读取当前 shell 变量 |
如果本地 echo 有值，但应用里没有值，说明变量没有进入运行时。不要继续改
请求体，先修启动方式、配置文件或部署 Secret。
Base URL 怎么查
Section titled “Base URL 怎么查”API Key 和 Base URL 必须来自同一套入口。OfApp.cn 官方页面展示的进阶接入
入口是 https://api.ofapp.cn/v1；如果某个工具会自动拼接 /v1，则按工具
说明和 OfApp.cn 当前文档填写。
| 现象 | 可能原因 | 修法 |
|---|---|---|
| OfApp Key 请求其他域名 | Key 与服务商不匹配 | 把 Base URL 改回 OfApp.cn 入口 |
Base URL 少了或多了 /v1 |
最终路径被拼错 | 打印最终 URL，不打印 Header |
| SDK 默认请求官方域名 | 没设置 baseURL 或 base_url |
显式配置兼容入口 |
| 客户端有多个配置页 | 只改了一处配置 | 搜索旧 Key 和旧 URL |
Base URL 不是模型名，也不是 API Key。把三者分开排查，会比同时修改更稳。
SDK 和客户端怎么查
Section titled “SDK 和客户端怎么查”不同工具读取配置的方式不同。401 出现在 SDK 或客户端里时，建议先用 cURL 证 明 Key 可用，再回到工具配置。
| 工具 | 检查点 |
|---|---|
| OpenAI JavaScript SDK | apiKey 是否从服务端环境变量读取，baseURL 是否指向兼容入口 |
| OpenAI Python SDK | api_key、base_url 是否来自当前进程环境 |
| Codex CLI | 登录方式、配置文件、Base URL 和当前项目环境变量是否一致 |
| AI 客户端 | API Key、Base URL、模型名是否填在同一服务商配置里 |
| 后端代理 | 是否转发或重写了 Authorization，是否把 Header 删除 |
| 前端页面 | 不应持有真实 Key，应请求自己的后端接口 |
如果 cURL 成功而 SDK 失败，问题通常在 SDK 初始化、运行时环境、代理层或客户 端缓存；如果 cURL 也失败，回到 Key 来源和控制台状态。
部署环境怎么查
Section titled “部署环境怎么查”本地可用、线上 401，是最常见的鉴权问题之一。
| 检查项 | 问题示例 |
|---|---|
| Secret 名称 | 平台里叫 OFAPP_API_KEY，代码读 OPENAI_API_KEY |
| 环境范围 | 只给 Production 配了 Key，Preview 没有 |
| 重启部署 | 更新 Secret 后没有重新部署或重启 |
| 构建时读取 | build 阶段把空值写进产物 |
| 日志脱敏 | 错误上报打印了完整 Header |
| 多服务调用 | Worker、API Route、队列任务用的不是同一套 Secret |
线上排查时，可以打印 key_present、key_length 和 Base URL host，不要打印
完整 Key。若怀疑泄露，先轮换密钥，再补日志脱敏。
前端为什么不能保存 API Key
Section titled “前端为什么不能保存 API Key”OpenAI API Reference 明确提醒 API Key 是秘密，不应暴露在浏览器或客户端代 码中。原因很简单：前端 JavaScript、Source Map、浏览器插件、网络面板和错 误日志都可能被用户看到。
更稳的结构是：
| 层级 | 负责什么 |
|---|---|
| 浏览器前端 | 收集用户输入、展示结果、处理加载和取消 |
| 你的后端 | 保存 API Key、校验用户、限流、转发请求、脱敏日志 |
| OfApp.cn 入口 | 作为 OpenAI-compatible API 入口处理模型调用 |
普通用户如果只是想聊天、写作、读文件或生图，可以先用 OfApp.cn 的天才游乐场 体验；开发者把能力接进应用时，应让真实 Key 留在服务端、终端或安全配置里。
什么时候要轮换 Key
Section titled “什么时候要轮换 Key”不是所有 401 都要立刻轮换，但这些情况建议生成新 Key 并撤销旧 Key：
| 情况 | 处理 |
|---|---|
| Key 出现在截图、日志、仓库或聊天记录里 | 立即轮换 |
| 团队成员离职或权限变化 | 轮换并更新部署 Secret |
| 工具读取旧 Key，且无法确认来源 | 轮换后全链路验证 |
| 控制台显示 Key 已删除、停用或状态异常 | 使用新 Key |
| 怀疑被第三方使用 | 轮换、检查日志和访问来源 |
轮换后要更新本地、CI、生产、队列、客户端和自动化任务。只改一个地方，常常 会导致部分服务继续 401。
- OpenAI API Reference: Authentication：说明 API 使用 Bearer credentials，API Key 应保密并从服务端环境变量或密钥管理服务读取。
- OpenAI Error codes：说明 401 可能来自 Key 不正确、项目或组织不匹配、Key 被删除或停用、本地缓存旧 Key、IP allowlist 等。
- OfApp.cn API 文档：展示 OfApp.cn 的 Base URL、OpenAI 兼容端点和
Authorization: Bearer示例。 - OfApp.cn：说明普通用户可创建 Key，进阶用户可配置 Base URL 和 Key 接入工具或项目。
- OfApp.cn 天才游乐场：普通用户可以先从网页入口体验聊天、写作、读文件和生图。
401 可以通过重试解决吗？
Section titled “401 可以通过重试解决吗？”通常不能。401 是鉴权层没有通过，重试同一个错误请求只会重复失败。先修 Key、 Bearer 请求头、环境变量和 Base URL。
本地可以，部署后 401 怎么办？
Section titled “本地可以，部署后 401 怎么办？”先检查线上运行时是否真的读到了 Key，而不是只看本地终端。确认 Secret 名称、 环境范围、重新部署、服务重启和队列任务配置。
401 和 403 有什么区别？
Section titled “401 和 403 有什么区别？”401 是身份凭证没有通过；403 是身份可能已经被识别，但没有权限访问某个资源、 模型、项目或策略范围。401 先查 Key 和请求头，403 再查权限和策略。
401 和 invalid API key 一样吗？
Section titled “401 和 invalid API key 一样吗？”不完全一样。401 更宽泛，可能是没有发送 Authorization，也可能是 Bearer 格
式错误；invalid API key 更明确指向密钥无效、复制损坏或入口不匹配。
可以把 API Key 发给同事或 AI 帮我排查吗？
Section titled “可以把 API Key 发给同事或 AI 帮我排查吗？”不建议。排查时只提供脱敏摘要，例如 Key 是否存在、长度、前后少量字符、Base URL host、状态码和错误体。真实 Key 泄露后应立即轮换。
前端项目怎么避免 401？
Section titled “前端项目怎么避免 401？”前端不要直接持有 Key。让前端调用自己的后端接口，后端读取环境变量或 Secret， 再请求 OfApp.cn 或其他 OpenAI-compatible API。
- invalid API key：排查密钥无效、复制损坏和 Base URL 不匹配。
- 403 Forbidden 错误排查：区分鉴权失败和权限不足。
- 如何获取 OfApp.cn API Key：准备、保存和验证密钥。
- 如何配置 Base URL：理解入口地址、
/v1和工具配置。 - curl 示例：用最小请求确认 Header、状态码和响应体。
- JavaScript SDK 示例：服务端读取环境变量并接入 SDK。
- Python SDK 示例：脚本和后台任务里的鉴权配置。
- 常见错误排查：从 Key、Base URL、模型名和端点逐层定位。
401 鉴权失败要先查身份凭证链路：Key 是否来自当前入口、运行时是否读到环境
变量、请求头是否是 Authorization: Bearer、Base URL 是否匹配、部署 Secret
是否生效。最小 cURL 请求通过后，再回到 SDK、Codex、AI 客户端或业务后端。