常见错误排查

接入 AI API 出错时，最怕同时改 Key、Base URL、模型名、SDK 版本、Prompt 和业 务代码。正确做法是把问题压缩到一个最小请求里：先验证 OfApp.cn API Key、 https://api.ofapp.cn/v1、模型名和端点，再决定是否继续查 SDK、Codex CLI 或网络环境。

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。具体可用模型、价格、额度、 套餐和能力，请以 OfApp.cn 控制台或官方文档为准。

把排错回到统一入口

先用 OfApp.cn Base URL、API Key 和最小请求确认连通性，再排查 SDK、Codex CLI 或业务代码。

查看官方接入说明

适合谁读

• 第一次用 OfApp.cn 接入 OpenAI-compatible API，遇到 401、404 或模型错误的人。
• 正在把 OpenAI SDK、Codex CLI、AI 客户端或自动化脚本切到统一 API 入口的开发者。
• 需要把错误日志交给同事、Codex 或 AI 排查，但又不想泄露 API Key 的团队成员。
• 本地能跑、服务器失败，或 cURL 成功、SDK 失败，想快速分层定位的人。

排错流程图

这张图的意思很简单：先证明入口是否可用，再处理调用方式。如果最小 cURL 失 败，SDK 和业务代码还没有排查价值；如果最小 cURL 成功，才继续看 OpenAI SDK、 Codex CLI、代理、超时或你的应用逻辑。

先分层定位

层级	看什么	典型现象	下一步
账号与 Key	API Key 是否来自 OfApp.cn，是否复制完整	401、invalid API key	重新复制 Key，检查 Authorization: Bearer。
Base URL	是否使用 https://api.ofapp.cn/v1，是否重复拼接 /v1	404、请求打到错误域名	打印最终请求 URL。
端点	OpenAI 生态和 Claude 生态是否混用	404、参数不被识别	OpenAI/Codex 用 /v1，Claude Messages 看 /v1/messages。
模型	模型名是否当前账号可用	model not found	从 OfApp.cn 控制台或 /v1/models 重新确认。
参数	是否一上来就加 tools、图片、JSON、stream	400、输出为空、中断	回到只含 model 和 messages 的请求。
SDK	SDK 是否读取到正确环境变量	cURL 成功但代码失败	打印 SDK 初始化配置的脱敏值。
Codex CLI	config.toml、登录方式、模型配置是否一致	Codex 登录失败或调用失败	检查 ~/.codex/config.toml 和 codex login --with-api-key。
网络	本地、服务器、代理、公司网络是否不同	timeout、streaming interrupted	换网络或关闭代理做对照。

不要把这些层级混在一起改。一次只改一个变量，改完立刻用同一条最小请求复测。

最小复现命令

1. 打印脱敏配置

这一步不发请求，只确认当前终端读到的变量是不是你以为的值。

node -e 'const k=process.env.OPENAI_API_KEY||""; console.log({ base_url: process.env.OPENAI_BASE_URL, model: process.env.OPENAI_MODEL, key: k ? `${k.slice(0,6)}...${k.slice(-4)}` : "missing" })'

期望看到：

base_url: https://api.ofapp.cn/v1
model: 以 OfApp.cn 控制台可用模型为准
key: sk-xxx...last4

2. 查询可用模型

OfApp.cn 官方文档展示了 GET /v1/models 的用法。它适合在排查时确认 Key、 Base URL 和模型列表是否同属一个入口。

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果这里失败，先不要看业务代码。优先检查 Key、Base URL、网络和账户状态。

3. 发一个最小聊天请求

排错时不要一上来使用复杂参数。先用最小 Chat Completions 请求确认基础通路。

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d "{
    \"model\": \"$OPENAI_MODEL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"用一句话回复：接口已连通。\"
      }
    ]
  }"

若这个请求成功，说明 Key、Base URL、模型和基础端点大概率没有问题。接下来 再查 SDK 读取环境变量、部署平台 Secret、代理、超时、流式处理或业务参数。

常见现象速查

现象	更可能是哪层	先做什么	参考
401 Unauthorized	鉴权层	确认 Key、Bearer 头、环境变量加载	401 Unauthorized
invalid API key	Key 与入口不匹配	重新从 OfApp.cn 控制台复制 Key	invalid API key
404 Not Found	Base URL 或端点	检查是否漏写或重复拼接 /v1	404 Not Found
model not found	模型名或权限	不猜模型名，从控制台或模型接口确认	model not found
429 Rate Limit	频率、并发、额度	降低并发，加入退避重试	429 Rate Limit
500 Server Error	服务端或临时链路	保留请求 ID，有限重试	500 Server Error
context length exceeded	输入过长	分段、摘要、删掉无关上下文	context length exceeded
streaming interrupted	网络、代理、SSE 处理	先关闭 stream 验证非流式请求	streaming interrupted
cURL 成功，SDK 失败	SDK 配置层	打印 SDK 的脱敏 baseURL / apiKey	OpenAI SDK 接入
SDK 成功，Codex 失败	Codex 配置层	检查 config.toml 和登录凭证	Codex CLI 接入 OfApp.cn

Base URL 排查

OfApp.cn 官方接入说明中，OpenAI / Codex 生态的 Base URL 是：

https://api.ofapp.cn/v1

容易出错的是重复拼接。比如环境变量已经包含 /v1，代码里又手写 /v1/chat/completions，最终请求就会变成错误路径。

写法	是否推荐	原因
OPENAI_BASE_URL=https://api.ofapp.cn/v1，请求 /chat/completions	推荐	版本路径只出现一次。
OPENAI_BASE_URL=https://api.ofapp.cn，请求 /v1/chat/completions	可用但要统一	适合某些会自动拼路径的工具。
https://api.ofapp.cn/v1/v1/chat/completions	不推荐	重复 /v1，常见 404 来源。
Claude 客户端使用 OpenAI Chat Completions 格式	不推荐	Claude/Anthropic 生态应按 messages 兼容接口配置。

如果一个工具会自动拼接 /v1，就按该工具说明填写。无法确认时，以 OfApp.cn 控制台或官方文档为准。

OpenAI SDK 排查

OpenAI 官方 SDK 和 CLI 文档强调 API Key 应通过环境变量读取；使用兼容服务时， 还要确认 SDK 初始化时传入了正确的 Base URL。

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

排查时先打印脱敏配置，而不是打印完整 Key。

console.log({
  baseURL: process.env.OPENAI_BASE_URL,
  model: process.env.OPENAI_MODEL,
  keyLoaded: Boolean(process.env.OPENAI_API_KEY),
});

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

如果部署后失败，本地成功，优先检查部署平台的 Secret 名称、运行环境和进程重 启，而不是先改模型或 Prompt。

Codex CLI 排查

Codex CLI 的排查要分清两件事：Codex 自己的登录和配置，以及你项目代码里的 环境变量。它们不是同一层。

检查项	正确方向
Codex 用户配置	~/.codex/config.toml 管 Codex 默认模型、provider 和 openai_base_url。
API Key 登录	API Key 登录可用于本地 Codex CLI 工作流，常见写法是 codex login --with-api-key。
项目 .env	只给你的项目代码读取，不会自动替 Codex CLI 完成登录。
项目 .codex/config.toml	适合项目级偏好；Codex 文档说明项目配置不能覆盖 provider auth 或 openai_base_url 这类凭证重定向配置。

OfApp.cn 官方示例中，Codex 生态使用内置 OpenAI provider，并通过 openai_base_url = "https://api.ofapp.cn/v1" 指向统一入口。模型名、可用能力 和额度仍以 OfApp.cn 控制台或官方文档为准。

脱敏日志模板

把下面这段交给同事、Codex 或 AI 前，先替换敏感信息。不要粘贴完整 API Key、 Cookie、账号邮箱、用户数据、内部域名和业务请求体。

time: 2026-07-02 10:00:00
platform: local / vercel / server / codex-cli
base_url: https://api.ofapp.cn/v1
endpoint: /chat/completions
method: POST
model: 以 OfApp.cn 控制台可用模型为准
status: 401
request_id: 如响应中提供则记录
api_key: sk-****last4
stream: true / false
sdk: openai-js / openai-python / curl / codex-cli
network: home / company / proxy / server
response_excerpt: 删除敏感字段后的错误片段

这份日志的价值不在于长，而在于能让排查者判断问题发生在哪一层。

给 Codex 的排错 Prompt

请帮我排查 OfApp.cn OpenAI-compatible API 调用失败。

目标：只定位失败层，不要重写业务代码。

已知信息：
- Base URL: https://api.ofapp.cn/v1
- 端点: /chat/completions
- SDK/工具: [curl / openai-js / openai-python / codex-cli]
- 状态码: [401 / 404 / 429 / timeout / ...]
- 模型名: [已脱敏或写“以控制台可用模型为准”]
- 脱敏错误日志: [粘贴日志]

请按顺序检查：
1. API Key 和 Authorization 头。
2. Base URL 是否漏写或重复拼接 /v1。
3. 模型名是否需要从 OfApp.cn 控制台重新复制。
4. 最小 cURL 是否能复现。
5. 如果 cURL 成功，再指出 SDK 或 Codex CLI 配置里最可能的问题。

输出：
- 可能原因排序。
- 每个原因的验证命令。
- 不应修改的内容。
- 修复后的复测步骤。

这个 Prompt 的重点是约束排查范围。排错任务越克制，越不容易把一个配置问题改 成多个新问题。

上线前检查

检查项	做法
Key 存放	使用环境变量或 Secret，不写进前端代码、Git 仓库、截图和公开日志。
Base URL	在本地、CI、服务器分别打印脱敏值。
模型名	从 OfApp.cn 控制台或官方文档确认，不凭记忆写。
错误处理	401/403/404 不盲目重试，429/5xx/网络中断才做有限退避。
日志	记录状态码、端点、请求 ID、SDK、stream 开关，不记录完整输入和密钥。
流式输出	先验证非流式请求，再打开 stream。
Codex	Codex 配置与项目 .env 分开检查。

常见问题

报错时要不要立刻换模型？

不要。先确认 API Key、Base URL、端点和最小请求。只有 model not found，或 控制台显示当前模型不可用时，才考虑换成当前账号可用模型。

401 和 invalid API key 有什么区别？

两者都指向鉴权层。401 更偏向请求没有被正确认证；invalid API key 更偏向 Key 缺失、复制错误、格式错误，或 Key 与当前 Base URL 不匹配。

Base URL 一定要带 /v1 吗？

OfApp.cn 官方文档给 OpenAI / Codex 生态展示的 Base URL 是 https://api.ofapp.cn/v1。如果某个客户端会自动拼接 /v1，按客户端说明填 写，避免重复。

cURL 成功但 JavaScript 或 Python 失败怎么办？

说明入口大概率可用。继续检查 SDK 初始化参数、环境变量名称、部署平台 Secret、 运行目录和进程是否重启。不要先改 Prompt。

Codex CLI 接入成功后还需要项目 .env 吗？

看任务。Codex CLI 自己的登录和 config.toml 用来让 Codex 工作；你的项目代 码如果也要调用 API，仍然应该有自己的 .env 或部署 Secret。

什么时候应该关闭 stream？

排查网络、代理、超时或前端 SSE 处理问题时，先关闭 stream。非流式请求成功 后，再单独排查流式解析和中断恢复。

可以把完整错误日志发给 AI 吗？

不建议。先删除 API Key、Cookie、账号、用户内容、内部 URL、请求体敏感字段 和业务数据，只保留排查所需的状态码、端点、脱敏配置和错误片段。

OfApp.cn 支持哪些模型？

请以 OfApp.cn 控制台或官方文档为准。教程页面不猜测模型清单、价格、套餐、 额度或临时可用性。

相关文章

• 如何获取 OfApp.cn API Key：先确认 Key 来源和保存方式。
• 如何配置 Base URL：避免漏写或重复拼接 /v1。
• OpenAI-compatible API 快速开始：用 cURL、JavaScript 和 Python 验证通路。
• 如何用 OpenAI SDK 接入：排查 SDK 初始化和环境变量。
• Codex CLI 接入 OfApp.cn：检查 Codex 登录、config.toml 和模型配置。
• API 错误排查中心：按状态码进入更细的错误页。
• 错误重试示例：为 429、5xx 和网络中断设计退避。
• 用 Codex 排查报错：把脱敏日志交给 Codex 做定位。

参考资料

• OfApp.cn 官方接入说明
• OfApp.cn 首页
• OpenAI SDKs and CLI
• OpenAI Codex manual

带走什么

常见错误排查不是背状态码，而是分层定位。先用 OfApp.cn API Key、 https://api.ofapp.cn/v1、控制台可用模型和最小请求证明入口，再把问题交还 给 SDK、Codex CLI、网络或业务代码。每一步都保留脱敏日志，下一次排错会快很 多。