---
title: "Cursor 自定义 API 配置：Base URL 作用范围与不生效排查"
description: "讲清 Cursor 自定义 API Key 和 Override OpenAI Base URL 管哪些功能、不管哪些功能，为什么填 localhost 无效，并给出一条可照做的排查顺序和 curl 自检命令。"
url: https://cdnping.org/blog/cursor-override-openai-base-url
language: zh-CN
published: 2026-10-23
category: "开发工具"
tags: ["Cursor","自定义 API","Base URL","排查","开发工具"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Cursor 自定义 API 配置：Base URL 作用范围与不生效排查

Cursor 自定义 API 能做的事比很多教程说的要少：在设置里填 OpenAI API Key 并打开 Override OpenAI Base URL，只会影响聊天、Agent 这类会调用"OpenAI 格式模型"的功能，Tab 补全仍然走 Cursor 自家的模型；而且请求是先发到 Cursor 的云端、再由云端转发到你填的地址，所以 `localhost` 和内网地址填了也不会生效。弄清这两点，大部分"配了没反应"的问题就能定位。

下面先把作用范围列成一张表，再给一条排查顺序。文中提到的设置项名称以撰写时 Cursor 的英文界面为准，Cursor 更新频繁，菜单位置可能变化，遇到不一致请以 [Cursor 官方文档](https://docs.cursor.com) 和你当前版本的设置页为准。

## 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 时，代码和对话会被看到吗](/blog/ai-api-data-privacy-policy)。

## 为什么填了 Base URL 还是不生效？

Cursor 论坛里的同类求助，原因大致是这几类：

1. 地址从公网访问不到。 前面说过，请求由 Cursor 服务端发出。你本机能 curl 通，不代表 Cursor 的服务器能访问到。本地起的代理、公司内网网关、只在本机 hosts 里解析的域名都属于这一类。
2. 路径少了或多了 `/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。具体以端点方文档为准。
3. 接口格式不匹配。 Override OpenAI Base URL 只会发 OpenAI 格式的请求。如果端点只支持 Anthropic 的 Messages 格式，或者对 OpenAI 格式支持不完整（比如不支持流式、不支持 tools 字段），就会出现 Ask 能用、Agent 报错的情况。
4. 模型名不对。 你在 Cursor 里添加的模型名要和端点 `/v1/models` 返回的 id 完全一致，大小写和前缀都算。打开 Override 后，Cursor 内置的其他 OpenAI 模型名也会发到你的端点，端点不认识就报错，所以建议把用不到的模型在列表里关掉。
5. 网络层的 HTTP/2 问题。 有些网络环境（公司代理、部分安全软件）对 HTTP/2 长连接处理不好，表现为请求挂起或流式输出中断。Cursor 设置的 Network 部分提供 HTTP 兼容模式，可以切到 HTTP/1.1 再试。注意这个设置影响的是你的电脑到 Cursor 服务器这一段，不是 Cursor 到你端点的那一段。
6. Key 验证没过。点 Verify 时 Cursor 会发一个测试请求；验证没通过时，先看报错原文定位原因，不要反复重填。

## 一条可以照做的排查顺序

按下面顺序做，每一步只改一个变量。

### 第 1 步：先确认 Cursor 本身没出问题

自定义端点不通时，先排除 Cursor 服务端故障，因为请求必须经过它。打开 [Cursor 挂了吗](/down/cursor) 看当前报告，或在 [API 状态页](/status) 查同步过来的 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 状态页](/blog/how-to-read-ai-status-pages)，方法对 Cursor 状态页同样适用。如果同一时段其他 AI 服务也在报错，可以对照 [AI 服务故障盘点：2026 年 9–10 月](/blog/ai-service-incidents-sep-oct-2026) 判断是不是上游的共性问题。

### 第 2 步：用 curl 从公网验证端点

不要只在本机测。最好在一台云服务器上，或至少换一个网络执行：

```bash
# 把 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 时间](/blog/api-latency-connect-rtt-ttft)。

### 第 3 步：在 Cursor 里收窄变量

1. 在 Models 列表里只保留一个你确认存在的模型 id，其他 OpenAI 模型先关掉。
2. 重新点 Verify，记下报错原文。
3. 先在 Ask（问答）模式发一句简单的话；能用之后，再切到 Agent 模式试同样的问题。
4. Ask 正常、Agent 报错：大概率是端点对 tools/function calling 的支持不完整，或该功能本身不支持自定义模型。前者问端点方，后者看 Cursor 文档。
5. 两个模式都卡住、流式中断：到 Network 设置里切 HTTP 兼容模式（HTTP/1.1），重启 Cursor 后再试。

### 第 4 步：确认地址确实是公网可达的 HTTPS

如果你的端点跑在本地或内网，Cursor 服务端连不到它，这是架构决定的，换配置解决不了。需要部署到一个有公网域名、证书有效的地址上。顺带检查一下域名解析是否在不同网络下一致，以及证书链是否完整，浏览器打开 `https://你的域名/v1/models` 不报证书警告是最低要求。

## 排查检查表

把上面的内容压缩成一张表，排查时逐项勾：

| 检查项 | 怎么确认 | 通过标准 |
|---|---|---|
| Cursor 服务正常 | [/down/cursor](/down/cursor)、[/status](/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 给你的是哪个模型](/blog/verify-model-authenticity-relay)。
- 可用率和计费是否公开、可核对。 评估方法见 [AI API 中转站怎么选：可用率、计费、数据政策 8 项检查](/blog/api-relay-how-to-evaluate)。
- 其他工具能不能共用。 如果你同时在用 Claude Code、Codex，配置方式不一样，可以对照 [Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置](/blog/configure-custom-api-endpoint-claude-code-codex)。Claude Code 侧的连接报错见 [Claude Code 连接超时和报错怎么排查](/blog/claude-code-connection-troubleshooting)。

举个例子，[AGI Plan](https://agiplan.dev) 是一个同时兼容 OpenAI 和 Anthropic 接口格式的聚合网关（AGI Plan 是 cdnping 的商业合作方），Cursor 属于"能填接口地址 + API Key"的工具之一，接入方式就是上面这套：Base URL 填它的地址，模型名照它 `/models` 的返回填写。它在 `https://agiplan.dev/api/status/requests?month=YYYY-MM` 公开逐小时、逐能力组的请求成功与失败计数，不需要登录，可以自己下载核对；站方也明确说明自己不是官方授权渠道。无论选哪家，都请先读清服务条款，并遵守所在地的法规和各模型提供方的使用政策。