迁移前先确认的三件事

把 Claude Code、ChatGPT API、Codex CLI 这类工具从官方接口迁到 OpenAI-compatible，第一件事不是改代码，而是先确认配置入口。很多人踩坑在“看起来都对，实际读错环境变量”。常见顺序是：OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL，但不同 SDK 还可能识别 baseURL、apiKey、organization 等字段，且优先级不一致。建议先在本地打印实际生效值，避免 shell 里导出了一份、IDE 运行时又读到另一份。

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

node -e 'console.log(process.env.OPENAI_BASE_URL, process.env.OPENAI_MODEL)'

如果你习惯在 .env、shell profile、启动脚本里同时写配置，务必检查是否发生串配置：比如把 ChatGPT API 的 key 填进了 Claude Code 的配置文件，或者把 base_url 写成了带尾斜杠又被 SDK 自动拼接两次路径。迁移时最好先只保留一套变量来源，再逐步恢复。

401、超时和流式 SSE 的排错顺序

迁到 OpenAI-compatible 后，最常见的不是“不能用”，而是 401、超时和流式中断。401 先看三项：Authorization 是否真的带上了 Bearer 前缀、base_url 是否已经包含 /v1、模型名是否被网关做了权限限制。很多代理兼容层对模型路由是单独配置的，表面上是 OpenAI 接口，实际只放行部分模型。

超时问题通常发生在长上下文和流式输出上。建议先把请求改成非流式，确认首包能返回；再打开 SSE，观察是否能持续收到 data: 事件。如果中途断开，优先检查反向代理超时、HTTP/2 连接复用、以及客户端是否在收到 [DONE] 前就主动关闭了响应体。对 fetch/SDK 来说，网络空闲超时经常比模型推理慢更早触发。

import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL,
  messages: [{ role: "user", content: "列出迁移检查项" }],
  stream: true,
});

for await (const chunk of resp) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content || "");
}

迁移检查清单：先兼容，再优化

建议按下面顺序做检查：

1. 先确认 base_url 只改一处，SDK、CLI、IDE 插件不要各写各的。

2. 验证模型名是否与路由表一致，别把官方模型名原样搬过去却没做映射。

3. 先跑一个最小 curl，再跑 SDK，避免把业务代码问题和配置问题混在一起。

4. 打开日志，记录请求路径、响应码、首包时间和重试次数。

5. 流式场景单独测 SSE，非流式正常不代表流式正常。

6. 确认限流和重试策略，避免 SDK 默认重试把问题放大。

如果本地调试时需要一个兼容端点，base_url 我用过 https://59api.com，可替换，但迁移时还是建议先以“能稳定跑通官方格式”为目标，再考虑模型路由、缓存和重试策略的细化。真正省时间的不是改地址，而是把环境变量、权限、超时和流式这四类问题一次性排干净。