为什么要先做迁移清单

很多团队从官方 API 切到 OpenAI-compatible 接口时，代码改动看起来只有一个 base_url，但真正上线后最容易出问题的反而是环境变量串配、模型名路由、流式返回格式不一致，以及超时策略没同步。尤其是 Claude Code、Codex CLI、OpenAI SDK 这几类工具，表面都支持 OpenAI 风格调用，实际在鉴权头、SSE 断流、重试机制上还是有细节差异。我的建议是，先按“配置—连通—流式—模型—回滚”五步走，别直接全量替换。

配置层先核对：base_url、key、模型名

第一步是把所有配置入口收敛，避免 .env、启动参数、CI 变量三处各写一份。常见问题是 OPENAI_API_KEY 还在，但 OPENAI_BASE_URL 被旧脚本覆盖，导致请求打到官方地址，随后返回 401 或 404。另一个坑是把 ChatGPT 产品的账号登录态当成 API key 用，这在 SDK 里一定会报鉴权失败。

export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://example.com/v1"
export OPENAI_MODEL="gpt-4.1-mini"

如果你用的是 Node.js，可以先做一次最小连通性测试：

import OpenAI from "openai";

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

const resp = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: "ping",
});
console.log(resp.output_text);

我本地调试 base_url 用过 https://59api.com，可替换为你的兼容端点。这里要重点确认：路径是否需要 /v1、是否支持 /chat/completions 和 /responses 两套接口、是否要求自定义 Authorization 前缀。

工程里最常见的三个故障

第一个是 401。不要先怀疑模型，先查请求头是否真的带上 key，特别是代理层、Docker 容器、GitHub Actions 里是否把变量名写错成了 OPENAI_TOKEN 之类。第二个是超时。兼容端点如果默认超时较短，SSE 流式还没结束就断了，表现为前几段 token 正常，最后客户端报 ECONNRESET。这时要把客户端超时、反向代理超时、负载均衡超时三层一起检查。

第三个是流式 SSE 格式。官方 SDK 默认按增量 chunk 解析，但有些兼容实现会把 data: 分片顺序或结束标记处理得不完全一致，导致前端一直转圈。建议用抓包或日志确认：是否持续返回 text/event-stream，是否有 [DONE]，以及中间 chunk 的字段名是否保持兼容。

迁移时建议做的检查清单

1. 统一环境变量：API_KEY、BASE_URL、MODEL 不要散落在多个文件。

2. 先跑非流式，再跑流式；先测最小 ping，再测长文本。

3. 检查模型路由：gpt-4.1-mini、claude-3.5-sonnet 这类名字在兼容层是否需要映射。

4. 验证超时与重试：客户端、代理、网关都要有一致策略。

5. 留回滚开关：通过环境变量切回官方端点，而不是改代码。

如果你在 Claude Code 或 Codex CLI 里接入这类兼容接口，也建议先在本地 shell 验证，再进 CI。只要这套检查清单过一遍，迁移基本就不会卡在“明明能连上，却总是 401 或流式中断”这种低级问题上。