Cursor 自定义 API 配置：Base URL 作用范围与不生效排查
Cursor 自定义 API 能做的事比很多教程说的要少：在设置里填 OpenAI API Key 并打开 Override OpenAI Base URL，只会影响聊天、Agent 这类会调用"OpenAI 格式模型"的功能，Tab 补全仍然走 Cursor 自家的模型；而且请求是先发到 Cursor 的云端、再由云端转发到你填的地址，所以 localhost 和内网地址填了也不会生效。弄清这两点，大部分"配了没反应"的问题就能定位。
下面先把作用范围列成一张表，再给一条排查顺序。文中提到的设置项名称以撰写时 Cursor 的英文界面为准，Cursor 更新频繁，菜单位置可能变化，遇到不一致请以 Cursor 官方文档 和你当前版本的设置页为准。
Cursor 的自定义 API Key 和 Base URL 到底管什么？
在 Cursor Settings 的 Models 页面里，通常能看到几组 API Key 输入框（OpenAI、Anthropic、Google 等），OpenAI 那一组下面有一个 Override OpenAI Base URL 的开关。它的含义是：凡是 Cursor 按 OpenAI 接口格式去调用的模型，都改为把请求发到你填的地址，并带上你填的 Key。
几个容易误解的地方：
| 问题 | 实际情况 | 影响 |
|---|---|---|
| 覆盖的是一个模型还是全部？ | 打开 Override 后作用于所有走 OpenAI 格式的模型，不是只改你新加的那个 | 你的端点不认识的模型名会直接报错 |
| Tab 补全会走自定义端点吗？ | 不会。Tab 用的是 Cursor 自家的补全模型 | 自定义 Key 不能替代 Cursor 订阅里的补全额度 |
| 请求从哪里发出？ | 从 Cursor 的服务器发出，不是从你的电脑直接发出 | localhost、127.0.0.1、192.168.x.x 无效，地址必须公网可达 |
| 所有功能都能用自定义模型吗？ | 不一定。部分功能（例如某些 Agent 能力、代码应用）依赖 Cursor 自己的模型或特定能力，自定义模型可能不可选或表现不同 | 同一个模型在 Ask 能用、在 Agent 报错是常见现象 |
| 填了 Key 会不会还走 Cursor 额度？ | 走自定义 Key 的那部分请求按你的 Key 计费；没被覆盖的功能（如 Tab）照常用 Cursor 的 | 账单要分两边看 |
| 代码会不会经过 Cursor？ | 会。即使用自己的 Key，提示词也是在 Cursor 服务端拼装后转发 | 涉及隐私时要同时看 Cursor 和端点方两边的数据政策 |
如果你选自定义端点是出于数据方面的考虑，要知道数据会同时经过 Cursor 和端点提供方两家，两份政策都要读。怎么读数据政策可以参考用第三方 AI API 时，代码和对话会被看到吗。
为什么填了 Base URL 还是不生效？
Cursor 论坛里的同类求助，原因大致是这几类：
- 地址从公网访问不到。 前面说过，请求由 Cursor 服务端发出。你本机能 curl 通，不代表 Cursor 的服务器能访问到。本地起的代理、公司内网网关、只在本机 hosts 里解析的域名都属于这一类。
- 路径少了或多了
/v1。 大多数 OpenAI 兼容端点要求 Base URL 写到/v1为止，例如https://api.example.com/v1，Cursor 再自己拼接/chat/completions。写成https://api.example.com或https://api.example.com/v1/chat/completions都可能 404。具体以端点方文档为准。 - 接口格式不匹配。 Override OpenAI Base URL 只会发 OpenAI 格式的请求。如果端点只支持 Anthropic 的 Messages 格式，或者对 OpenAI 格式支持不完整（比如不支持流式、不支持 tools 字段），就会出现 Ask 能用、Agent 报错的情况。
- 模型名不对。 你在 Cursor 里添加的模型名要和端点
/v1/models返回的 id 完全一致，大小写和前缀都算。打开 Override 后，Cursor 内置的其他 OpenAI 模型名也会发到你的端点，端点不认识就报错，所以建议把用不到的模型在列表里关掉。 - 网络层的 HTTP/2 问题。 有些网络环境（公司代理、部分安全软件）对 HTTP/2 长连接处理不好，表现为请求挂起或流式输出中断。Cursor 设置的 Network 部分提供 HTTP 兼容模式，可以切到 HTTP/1.1 再试。注意这个设置影响的是你的电脑到 Cursor 服务器这一段，不是 Cursor 到你端点的那一段。
- Key 验证没过。点 Verify 时 Cursor 会发一个测试请求；验证没通过时，先看报错原文定位原因，不要反复重填。
一条可以照做的排查顺序
按下面顺序做，每一步只改一个变量。
第 1 步：先确认 Cursor 本身没出问题
自定义端点不通时，先排除 Cursor 服务端故障，因为请求必须经过它。打开 Cursor 挂了吗 看当前报告，或在 API 状态页 查同步过来的 Cursor 官方状态页事件。cdnping 每 15 分钟同步一次 Cursor 官方状态页。按 cdnping 同步到的记录，2026-09-17 到 2026-10-17 期间 Cursor 状态页共有 25 起事件，其中 major 5 起、minor 20 起；例如 2026-10-13 00:22（UTC）开始的 "Degraded performance and errors across Cursor services" 持续约 165 分钟。cdnping 自己的探测从 2026-10-17 才开始，这里的事件数取自官方状态页的历史记录，窗口只有一个月，不是长期统计。
如果这段时间里 Cursor 有事件，先等它恢复再排查自己的配置。事件等级和组件怎么看，可以参考怎么看 OpenAI 状态页和 Claude 状态页，方法对 Cursor 状态页同样适用。如果同一时段其他 AI 服务也在报错，可以对照 AI 服务故障盘点：2026 年 9–10 月 判断是不是上游的共性问题。
第 2 步：用 curl 从公网验证端点
不要只在本机测。最好在一台云服务器上，或至少换一个网络执行：
# 把 BASE 换成你在 Cursor 里填的 Base URL（通常以 /v1 结尾）
BASE="https://api.example.com/v1"
KEY="sk-xxxx"
# 1) 列模型：确认地址可达、Key 有效，并拿到准确的模型 id
curl -sS "$BASE/models" -H "Authorization: Bearer $KEY" | head -c 800; echo
# 2) 非流式对话：把 your-model-id 换成上一步返回的 id
curl -sS "$BASE/chat/completions" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model":"your-model-id","messages":[{"role":"user","content":"ping"}]}'
# 3) 流式对话：Cursor 聊天使用流式，必须单独测
curl -sSN "$BASE/chat/completions" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model":"your-model-id","stream":true,"messages":[{"role":"user","content":"ping"}]}'
判断方法：
- 第 1 条返回 HTML 页面或 404：Base URL 路径不对。
- 第 1 条通、第 2 条报 model not found：模型名不对。
- 第 2 条通、第 3 条没有逐行返回
data:开头的内容：端点不支持流式，Cursor 里会表现为卡住或报错。 - 三条都通，Cursor 里仍然不行：问题在 Cursor 侧的配置或功能限制，继续第 3 步。
如果想顺便看连接质量，可以用 cdnping 首页的在线测速，它在浏览器里测各家 AI API 的首次连接（含 DNS 与 TLS 握手）和往返时间。不过这测的是"你的浏览器到端点"，和"Cursor 服务器到端点"不是同一条路径，只能作为参考。延迟由哪几段组成，见 AI API 延迟拆解：连接建立、网关往返与首 token 时间。
第 3 步：在 Cursor 里收窄变量
- 在 Models 列表里只保留一个你确认存在的模型 id，其他 OpenAI 模型先关掉。
- 重新点 Verify，记下报错原文。
- 先在 Ask（问答）模式发一句简单的话；能用之后，再切到 Agent 模式试同样的问题。
- Ask 正常、Agent 报错：大概率是端点对 tools/function calling 的支持不完整，或该功能本身不支持自定义模型。前者问端点方，后者看 Cursor 文档。
- 两个模式都卡住、流式中断：到 Network 设置里切 HTTP 兼容模式（HTTP/1.1），重启 Cursor 后再试。
第 4 步：确认地址确实是公网可达的 HTTPS
如果你的端点跑在本地或内网，Cursor 服务端连不到它，这是架构决定的，换配置解决不了。需要部署到一个有公网域名、证书有效的地址上。顺带检查一下域名解析是否在不同网络下一致，以及证书链是否完整，浏览器打开 https://你的域名/v1/models 不报证书警告是最低要求。
排查检查表
把上面的内容压缩成一张表，排查时逐项勾：
| 检查项 | 怎么确认 | 通过标准 |
|---|---|---|
| Cursor 服务正常 | /down/cursor、/status | 当前无进行中的事件 |
| Base URL 路径 | curl $BASE/models | 返回 JSON 模型列表 |
| 公网可达 | 在另一台机器或网络执行 curl | 与本机结果一致 |
| 模型 id | 对照 /models 返回 | 与 Cursor 中填写的完全一致 |
| 流式支持 | curl 带 "stream":true | 逐行返回 data: |
| 其他模型已关闭 | Cursor Models 列表 | 只启用端点支持的模型 |
| Verify 结果 | 设置页 | 无报错 |
| Ask / Agent 分别测试 | Cursor 聊天面板 | 至少 Ask 可用 |
| HTTP 兼容模式 | Network 设置 | 流式卡顿时切 HTTP/1.1 再试 |
选端点时还要看什么？
自定义端点接进 Cursor 以后，所有 OpenAI 格式的请求都会经过它，它出问题时 Cursor 的聊天和 Agent 也跟着不可用。接入前建议确认这几项：
- 它返回的是不是你选的模型。 可以做一些一致性检查，方法见怎么确认 API 给你的是哪个模型。
- 可用率和计费是否公开、可核对。 评估方法见 AI API 中转站怎么选：可用率、计费、数据政策 8 项检查。
- 其他工具能不能共用。 如果你同时在用 Claude Code、Codex，配置方式不一样，可以对照 Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置。Claude Code 侧的连接报错见 Claude Code 连接超时和报错怎么排查。
举个例子，AGI Plan 是一个同时兼容 OpenAI 和 Anthropic 接口格式的聚合网关（AGI Plan 是 cdnping 的商业合作方），Cursor 属于"能填接口地址 + API Key"的工具之一，接入方式就是上面这套：Base URL 填它的地址，模型名照它 /models 的返回填写。它在 https://agiplan.dev/api/status/requests?month=YYYY-MM 公开逐小时、逐能力组的请求成功与失败计数，不需要登录，可以自己下载核对；站方也明确说明自己不是官方授权渠道。无论选哪家，都请先读清服务条款，并遵守所在地的法规和各模型提供方的使用政策。
