Cursor自定义API怎么配置？把自己的模型接入IDE

Cursor 是目前最流行的 AI 编程 IDE，但它默认的模型套餐不一定适合所有人：价格可能偏贵、模型版本可能滞后、或者公司要求走自己的 API 账号。好消息是，Cursor 支持自定义 API 配置，把任何 OpenAI 兼容协议的服务接进来。

这篇把配置流程、常见坑和验证方法讲清楚。

前提条件

开始配置之前，确认三件事：

条件	说明
Cursor Pro 或 Pro+ 会员	Free Plan 无法配置自定义 API Key 和 Base URL，设置项会灰显
一个 OpenAI 兼容协议的 API Key	从你的服务商控制台获取
对应的 Base URL	以 /v1 结尾的 API 地址

如果你的 Cursor 账号还是 Free Plan，需要先升级到 Pro 才能继续。

配置入口

打开 Cursor，点击左下角设置图标（⚙️），进入 Cursor Settings → Models。

这个页面有三个关键区域：

• OpenAI API Key：填入你的 API Key
• Override OpenAI Base URL：填入你的 Base URL
• Add new models：手动添加自定义模型名称

第一步：填入 API Key

在 OpenAI API Key 旁边的输入框里，粘贴你的 API Key，点击 Verify 验证。

如果显示绿色 ✓，说明 Key 有效；如果报错，检查：

• Key 是否复制完整，前后有没有空格
• Key 是否已过期或被禁用
• 服务商是否支持 OpenAI 兼容协议

第二步：开启 Override OpenAI Base URL

默认情况下，Cursor 把 OpenAI API Key 的请求发到 https://api.openai.com/v1。如果你用的是其他服务商，需要开启 Override OpenAI Base URL，把地址改成你的服务商地址。

https://your-provider.com/v1

注意：

• Base URL 必须以 /v1 结尾（OpenAI 兼容协议的惯例）
• 不要带尾部斜杠
• 不要把完整接口路径写进去，只需要到 /v1

第三步：添加自定义模型

Cursor 内置的模型列表不一定包含你想用的模型。需要在 Add new models 输入框里手动添加模型名称。

输入模型 ID，点击 Add Custom Model。添加后，模型会出现在左侧模型列表中，点击启用。

模型 ID 必须和你的服务商支持的完全一致。在服务商控制台查看可用模型列表，不要凭印象手打。

验证配置

配置完成后，验证是否生效：

1. 关闭设置页面
2. 在 AI 对话面板（Ctrl+L 或 Cmd+L）中，选择你刚添加的自定义模型
3. 发一条简单消息测试

如果正常返回内容，配置成功。如果报错，对照下面的排错表逐一检查。

常见报错与排查

“This model does not support custom API keys”

原因：你选择的模型不在 Cursor 的自定义 Key 支持列表里。

解决方法：确认你添加的是自定义模型（通过 Add Custom Model 添加的），而不是 Cursor 内置的模型。内置模型走 Cursor 自己的账号体系，不能用你自己的 Key。

401 Unauthorized

原因：API Key 无效、过期，或服务商不支持 OpenAI 兼容协议。

排查方法：

• 用 curl 直接请求一次你的 Base URL，确认 Key 有效
• 确认服务商明确支持 OpenAI 兼容协议

404 Not Found

原因：Base URL 写错了，或者模型 ID 不存在。

排查方法：

• 检查 Base URL 是否以 /v1 结尾，没有尾部斜杠
• 确认模型 ID 和服务商控制台显示的一致
• 用模型列表接口确认可用模型

请求超时

原因：网络无法到达 Base URL 地址。

排查方法：

• 检查网络环境和代理配置
• 确认服务商地址没有被防火墙拦截

模型列表里没有我要的模型

原因：服务商不支持该模型，或者模型名称写错了。

排查方法：

• 在服务商控制台查看支持的模型列表
• 确认模型 ID 拼写完全一致，注意大小写和日期后缀

配置检查清单

检查项	怎么确认
Cursor Pro 会员	Account 页面显示 “Pro” 或 “Pro+”
API Key 有效	Verify 按钮显示绿色 ✓
Base URL 格式正确	以 /v1 结尾，无尾部斜杠
模型已添加	在模型列表中可见且已启用
网络可达	能正常对话并返回内容

和 Claude Code 的配置区别

如果你同时用 Cursor 和 Claude Code，注意两者的配置逻辑不同：

维度	Cursor	Claude Code
协议	OpenAI 兼容	Anthropic 兼容
配置方式	图形界面设置	环境变量
Base URL 格式	以 /v1 结尾	通常不带 /v1
会员要求	需要 Pro 才能自定义	无会员要求
模型选择	在设置界面手动添加	通过 ANTHROPIC_MODEL 环境变量

快速排错表

报错	常见原因	排查方法
设置项灰显	不是 Pro 会员	升级到 Pro 或 Pro+
Verify 失败	Key 无效或过期	在服务商控制台确认 Key 状态
“does not support custom API keys”	选了内置模型	用 Add Custom Model 添加自定义模型
404	Base URL 或模型 ID 错误	核对 Base URL 格式和模型 ID
401	Key 无效	重新复制 Key，确认无空格
超时	网络不通	检查代理和防火墙

Cursor 自定义 API 配置的核心就三步：填 Key、改 Base URL、加模型名。大部分问题都出在这三个值上，对着检查清单过一遍，基本都能解决。