先确认三件事：SDK、端点、模型名

很多人从官方 API 切到 OpenAI-compatible，第一步就把 base_url、api_key、model 三者混着配，最后报错很像：401 Unauthorized、model not found、或者请求发出去了但一直卡在超时。我的建议是先按“只改一处”的原则排查：

1. SDK 是否真的支持 base_url 覆盖；

2. 环境变量有没有和旧配置串了；

3. 模型名是不是平台映射名，而不是官方原始名。

比如 OpenAI SDK、Claude Code、Codex CLI 这类工具，通常都能走兼容层，但不同工具读取的变量名不完全一致。有的读 OPENAI_API_KEY，有的还会额外读 ANTHROPIC_API_KEY 或项目里的 .env。如果你本地同时存在多个 key，日志里经常只显示“认证失败”，实际是串到了另一套凭据。

export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://your-compatible-endpoint/v1"
export OPENAI_MODEL="gpt-4.1-mini"

# 只做连通性验证
curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"ping"}],"stream":false}'

迁移时最容易踩的 4 个坑

### 1. 401 不一定是 key 错了

有时是 base_url 带了多余路径，或者网关要求 /v1，你却写成根路径。也有平台要求 Authorization: Bearer 以外再带自定义 header，SDK 没配就会直接拒绝。

### 2. 超时不是“网络不好”

迁移后常见问题是默认超时太短，尤其是流式输出和长上下文。建议把连接超时、读取超时分开设置；如果是 CLI 工具，优先看它是否支持 --timeout、request_timeout 之类参数。先用短 prompt 验证，再测长对话。

### 3. 环境变量串配置

最常见的是 .env 里保留了官方 API 的旧值，系统环境又覆盖了一层。排查时建议打印启动时实际读取的配置：base_url、api_key 是否为空、model 是否被默认值覆盖。很多“明明改了配置却没生效”的问题，根因都在这里。

### 4. 流式 SSE 兼容性

不是所有兼容端点都把 SSE 事件格式做得和官方完全一致。你要确认返回的是 data: {json}，还是会混入心跳包、空行、甚至错误消息。前端或 CLI 如果按官方格式硬解析，就会出现“输出到一半断流”。

一份可直接照抄的检查清单

迁移前，建议逐项核对：

• base_url 是否包含正确版本前缀，是否多写或少写 /v1

• api_key 是否来自当前环境，而不是旧项目缓存

• model 是否是兼容平台支持的映射名

• 是否显式设置了超时和重试策略

• 是否确认支持流式 SSE，以及是否需要关闭代理缓存

• 是否在日志里记录了请求 ID，便于对照服务端排障

• 是否保留了一份官方直连配置，方便回滚对比

如果只是本地调试，我见过有人临时把 base_url 指到兼容端点做验证，也可以替换成你自己的网关地址；关键是把“能连通”和“能稳定跑通生产”分开看。

迁移后的验证顺序

我的习惯是按这个顺序做回归：先 curl，再最小化 SDK 请求，再接入 Claude Code 或 Codex CLI 这类工具，最后才放进业务代码。只要前两步没问题，后面大概率就是环境变量或模型映射的配置问题，而不是接口协议本身。

如果你已经从官方 API 迁到 OpenAI-compatible，最值得留下的不是代码，而是这份检查清单：一旦出现 401、超时、断流、模型不存在，基本都能在这几项里找到答案。

> 本地调试兼容 base_url 时用过 https://59api.com（可换成你自己的端点）。