用 OpenAI SDK 配置自定义 Base URL：一次多模型接入实践

用 OpenAI SDK 配置自定义 Base URL：一次多模型接入实践

最近在整理 AI 开发工具的接入流程，发现很多场景其实不需要大改代码。只要服务端兼容 OpenAI SDK，客户端通常只需要调整两个地方：apiKey 和 baseURL。

这篇记录一下我在 Node.js 项目里配置自定义 Base URL 的过程，以及接入 Cursor、Codex、Claude Code 这类工具时容易踩到的几个点。

基础调用

先安装 SDK：

npm install openai

一个最小调用示例：

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: process.env.MODEL_NAME,
  messages: [
    {
      role: "user",
      content: "帮我写一个 Next.js API Route 示例"
    }
  ]
});

console.log(completion.choices[0].message.content);

这里最关键的是 baseURL。如果服务端提供的是 OpenAI-compatible 接口，一般可以继续使用 OpenAI SDK 的请求结构，不需要自己重新封装一套 HTTP 请求。

环境变量

我习惯把配置放到 .env 里：

API_KEY=你的 API Key
API_BASE_URL=https://example.com/v1
MODEL_NAME=模型名称

代码里只读取环境变量：

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

这样后面切换不同模型或不同环境时，不需要改业务代码。

常见问题

1. baseURL 末尾路径不一致

有些服务要求带 /v1，有些文档里会直接给完整地址。这里最好按实际文档填写，不要自己猜。

例如：

https://example.com/v1

如果路径少了一段，常见结果是 404 或接口找不到。

2. 模型名不能随便写

OpenAI SDK 只负责发请求，不会帮你判断模型名是否存在。模型名要以服务端实际支持的列表为准。

建议先用一个确定可用的模型跑通最小请求，再切换到其他模型。

3. 工具配置和代码配置不是一回事

在代码里配置 baseURL 比较直观，但 Cursor、Codex、Claude Code 这类工具通常有自己的配置入口。

排查时可以按这个顺序看：

1. API Key 是否填对
2. Base URL 是否带了正确路径
3. 模型名是否在支持列表里
4. 工具是否真的读取到了新配置
5. 报错是鉴权问题、模型问题，还是网络问题

一个简单排查脚本

如果不确定是工具配置问题，还是接口本身没通，可以先用 Node.js 单独测一下：

import OpenAI from "openai";

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

async function main() {
  const res = await client.chat.completions.create({
    model: process.env.MODEL_NAME,
    messages: [{ role: "user", content: "ping" }]
  });

  console.log(res.choices[0].message.content);
}

main().catch((error) => {
  console.error(error);
});

如果这个脚本能跑通，再去配置开发工具会省很多时间。反过来，如果脚本都跑不通，就先别怀疑工具，优先检查 Key、Base URL 和模型名。

OpenAI-compatible 接口的好处是迁移成本比较低。对已有项目来说，很多时候不用改调用结构，只需要把 apiKey、baseURL、model 这几个配置项抽出来。

我现在的习惯是：

1. 先用最小 Node.js 脚本跑通
2. 再接入实际项目
3. 最后配置 Cursor、Codex、Claude Code 这类开发工具
4. 出问题时按 Key、Base URL、模型名、工具配置顺序排查

这样排查路径会清楚很多，也不容易把 SDK、模型和工具配置的问题混在一起。