Cursor 中转 API 配置:API Key、Base URL 与功能限制
Cursor 中转 API 配置先用 curl 预检 OpenAI 兼容网关,再在 Settings > Models 保存 API Key 与 Override Base URL;聊天、Agent、Tab、工具和流式兼容性必须按当前版本分别验证。

Cursor 配置中转 API必须拆成两个验证阶段:先用 curl 证明网关的 URL、Key、模型和 Chat Completions 可用,再在 Cursor 中确认当前版本是否暴露对应设置以及哪项功能实际经过该路径。
“Cursor API 中转”并不对应 Cursor 提供的某个公开模型 API;本文核对的是 Cursor 模型配置里的自定义 API Key(BYOK)与官方提及的 OpenAI-compatible Base URL override。
直接答案:Cursor 配置中转 API 与网关预检
- 打开
Cursor Settings > Models。 - 找到官方支持的 provider,粘贴专用测试 Key,点击 Save。
- 若当前版本显示 OpenAI-compatible Base URL override,按网关文档填写;官方没有公开统一的尾部路径规则。
- 只选择一个 chat model 建立新会话,并用网关日志与用量核对请求。
export GPTZZZ_BASE_URL="https://gptzzz.ai/v1"
export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"
export CURSOR_TEST_MODEL="gpt-5.5"
curl --fail-with-body -sS \
"$GPTZZZ_BASE_URL/chat/completions" \
-H "Authorization: Bearer $GPTZZZ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$CURSOR_TEST_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复 CURSOR_OK\"}],\"stream\":false}"
Windows PowerShell:
$env:GPTZZZ_BASE_URL = "https://gptzzz.ai/v1"
$env:GPTZZZ_API_KEY = "YOUR_GPTZZZ_API_KEY"
$env:CURSOR_TEST_MODEL = "gpt-5.5"
$body = @{
model = $env:CURSOR_TEST_MODEL
messages = @(@{ role = "user"; content = "只回复 CURSOR_OK" })
stream = $false
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "$env:GPTZZZ_BASE_URL/chat/completions" `
-Headers @{ Authorization = "Bearer $env:GPTZZZ_API_KEY" } `
-ContentType "application/json; charset=utf-8" `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
import os
from openai import OpenAI
gateway = OpenAI(
api_key=os.environ["GPTZZZ_API_KEY"],
base_url=os.environ["GPTZZZ_BASE_URL"],
)
response = gateway.chat.completions.create(
model=os.environ["CURSOR_TEST_MODEL"],
messages=[{"role": "user", "content": "只回复 CURSOR_OK"}],
)
choice = response.choices[0]
if not choice.message.content or choice.finish_reason is None:
raise RuntimeError(response.model_dump_json())
print(response.model, choice.finish_reason, response.usage.total_tokens)
这条 curl 只是网关 preflight,不是 Cursor API 调用。Cursor 官方没有提供让用户用 curl 调模型的“Cursor 中转 Endpoint”。
GPTZZZ 的 OpenAI 兼容 Base URL 是 https://gptzzz.ai/v1。Key 在控制台 /keys 页面创建,一个 Key 只属于一个分组,Cursor 里切换的模型也必须在这个分组里。下面两个 GPT 模型可以直接用于上面的 curl 预检;在 Cursor chat 里能不能选用,要看表后的说明并按功能验证:
| 模型 | 分组 · 倍率 | 输入 ¥/百万 Token | 输出 ¥/百万 Token |
|---|---|---|---|
| gpt-5.5 价格 | opai puls · 0.05x | ¥0.25 | ¥1.50 |
| gpt-5.5 价格 | opai pro · 0.1x | ¥0.50 | ¥3.00 |
| gpt-5.5 价格 | pro200-500不降智 · 0.25x | ¥1.25 | ¥7.50 |
| gpt-5.5 价格 | GPT官key · 0.54x | ¥3.91 | ¥23.40 |
| gpt-5.4 价格 | opai puls · 0.05x | ¥0.13 | ¥0.75 |
| gpt-5.4 价格 | opai pro · 0.1x | ¥0.25 | ¥1.50 |
| gpt-5.4 价格 | GPT官key · 0.54x | ¥7.81 | ¥46.90 |
Cursor 官方 BYOK 说明对 OpenAI 写的是“标准、非推理的 chat models”,而 OpenAI 的 gpt-5.5 模型页和 gpt-5.4 模型页都把它们列为支持推理 Token 的模型;它们在你的 Cursor 版本里能否选用、能否正常对话,以 model picker 和下文的按功能验证为准。表中价格取自 2026-10-09 的模型价格页,单位是元/百万 Token(充值 ¥1 = 余额 $1),已乘分组倍率;实际扣费以 GPTZZZ 模型价格页和控制台为准。
Cursor 官方确认与未正式文档化的边界
| 项目 | 官方状态 | 文章结论 |
|---|---|---|
| OpenAI、Anthropic、Gemini 等 provider Key | Settings > Models 支持 | 粘贴后点击 Save |
| BYOK 覆盖范围 | chat models | Tab Completion 仍走内置模型 |
| OpenAI-compatible Base URL override | 官方隐私文档确认概念存在 | 精确 UI、尾部路径与 Endpoint 拼接未公开 |
| 任意自定义模型 ID | 无完整官方配置说明 | 不能保证 |
| Agent / tools / streaming 完整兼容 | 无通用保证 | 逐功能实测 |
| Anthropic Base URL override | 未找到官方证明 | 不要写成正式能力 |
Cursor Base URL 并不是所有版本都有的通用字段;只有当前客户端显示 OpenAI-compatible override 时才按网关文档填写,并以最终请求路径验证。
三类 Key 不要混用
| Key | 用途 | 是否为模型中转 Key |
|---|---|---|
| Models 中的 provider Key | chat model BYOK | 是当前页面讨论对象 |
CURSOR_API_KEY | Cursor CLI 自身认证 | 否 |
| Cursor Admin API Key | 团队管理与用量 API | 否 |
Cursor Desktop 没有官方文档说明可用环境变量配置 provider Key 或 Base URL,不要发明 CURSOR_BASE_URL 或把 OPENAI_BASE_URL 当作 Cursor 自动配置。
Cursor BYOK 的真实数据路径
Cursor 官方说明:Key 不会持久化存储,但请求会先送到 Cursor backend,由它构造最终 prompt,再发往 provider 或 third-party gateway。因此“使用自己的 Key”不等于代码上下文绕过 Cursor 服务器,也不等于直接从桌面客户端连接中转站。
BYOK 不适用 Cursor 的 ZDR 承诺;数据处理还受所选 provider 与网关政策影响,US-only data residency 也不覆盖 BYOK。团队验收应记录代码上下文范围、网关日志保留、地区、访问控制和删除流程。
按功能验证聊天、Agent、Tab 与流式
| 功能 | 可接受证据 | 不能据此推断 |
|---|---|---|
| chat model | 模型出现在 picker,新会话成功,网关请求与用量对应 | Tab 或 Agent 已切换 |
| 代码上下文聊天 | 受控测试仓库、请求 ID、上下文行为 | 所有文件都不会发送 |
| Agent | 工具名、调用 ID、参数、结果和结束状态完整 | 普通问答成功即可 |
| Tab Completion | 官方明确仍使用内置模型 | BYOK 用量可证明 Tab |
| 流式输出 | 首字、正常结束、取消、错误与网关日志 | 收到首段文本即完整 |
最小验证任务应在非敏感小仓库中进行:让 chat 解释一个文件、让 Agent 修改一处并运行测试、主动取消一次长响应,再恢复内置配置对照。每步都保存 Cursor version、Request ID、网关请求 ID 与实际用量。
Base URL、Key 与网络报错排查
| 现象 | 优先检查 | 动作 |
|---|---|---|
| Key invalid / rejected | provider 与 Key 是否匹配 | 更新或移除 Key |
| 模型不出现 | provider 支持与地区限制 | BYOK 不能绕过 provider 地区限制 |
| curl 成功、Cursor 失败 | 当前版本的 URL 字段语义与模型支持 | 不要继续猜路径,恢复原配置 |
| 流式连接失败 | 代理、VPN、HTTP/2 | Run Diagnostics;必要时切 HTTP/1.1 并重启 |
| Agent 循环或工具失败 | 模型能力、工具 Schema、流事件 | 复制 Request ID 与相关日志 |
网关请求 Schema 的迁移见 OpenAI 兼容 API 迁移;先用 OpenAI 兼容 API 快速验证确认端点;数据路径参考 中转站安全与隐私;Agent 工具链用 流式与工具兼容矩阵验收。
Cursor 验证指标与回滚
在固定小仓库中重复 10 次聊天和 5 次 Agent 任务,记录 Cursor version、Request ID、网关命中率、首字时间、完整结束率、工具成功率、测试退出码、实际 diff 与用量。网关命中率按“网关日志中可对应请求数 ÷ Cursor 发起任务数”计算,不能用模型下拉框代替证据。
- 停止 Agent 和长响应,保存 Request ID、日志与工作区 diff。
- 在 Settings > Models 移除测试 Key 和 override,恢复原 provider 或内置模型。
- 重启 Cursor,建立新会话,在同一测试仓库重跑基线。
- 确认网关不再收到请求、聊天恢复且没有重复文件修改后,撤销测试 Key。
官方资料
- Cursor API Keys / BYOK
- Cursor Privacy and Data Governance
- Cursor Regions
- Cursor Network troubleshooting
- Cursor Agent troubleshooting
- Cursor CLI authentication
命令行工具的对应配置见 Claude Code 中转站配置 与 Codex CLI 中转 API 配置。
常见问题
Cursor 配置中转 API 的入口在哪里?
当前官方步骤是 Cursor Settings > Models,找到供应商,粘贴 Key 后选择 Save。设置界面会随版本变化;官方未公开 Base URL override 的精确 UI 层级,应以当前客户端可见项为准。
Cursor 自定义 API Key 支持哪些功能?
Cursor 官方只承诺 BYOK 适用于 chat models;Tab Completion 继续使用 Cursor 内置模型。不要用一次聊天成功推断 Tab、Agent、Cloud Agent 或全部工具都已走中转。
Cursor 是否正式支持 OpenAI 兼容 Base URL?
官方隐私文档确认存在 OpenAI-compatible base URL override 或第三方 gateway 的概念,但未正式公开 URL 应含 /v1 还是完整 Endpoint、资源拼接、每模型配置或完整 Agent 兼容保证。
Cursor 的请求会直接从编辑器发往供应商吗?
不会。Cursor 官方说明 Key 不持久化保存,但每次请求会送到 Cursor backend 完成最终 prompt 构造,再到供应商或网关。BYOK 也不适用 Cursor 的 ZDR 承诺。
CURSOR_API_KEY 可以当作模型中转 Key 吗?
不可以。CURSOR_API_KEY 是 Cursor CLI 自身认证凭据,不是 Models 中的供应商 Key,也不是中转站模型 Key。Cursor Desktop 没有官方环境变量方式配置供应商 Key 或 Base URL。
Cursor 流式连接失败怎样运行网络诊断?
在 Cursor Settings > Network 运行 Run Diagnostics。Cursor 默认使用 HTTP/2 流;若代理拦截,可按官方指引把 HTTP Compatibility Mode 改为 HTTP/1.1 并重启,再保存 Request ID 与日志。
Cursor 自定义 API Key 怎样保存和验证?
在 Cursor Settings > Models 找到 provider,粘贴 Key 后点击 Save;选择一个受支持的 chat model 建立新会话,并以 provider 或网关用量、Request ID 和响应完成状态验证。
Cursor 接入中转站前怎样用 curl 预检?
先向网关文档给出的 Chat Completions Endpoint 发送 Bearer Key、当前模型与最小消息,核对状态、文本、finish_reason 和 usage。该 curl 只是网关 preflight,不是 Cursor API。
Cursor BYOK 支持哪些聊天模型?
官方列出 OpenAI 的标准非推理 chat models、Anthropic 可用 Claude、Google Gemini、Azure OpenAI deployments 与 AWS Bedrock 等;具体模型仍受账户、地区和当前客户端限制。
Cursor Tab Completion 会使用自定义 API Key 吗?
不会。Cursor 官方明确说明 Tab Completion 继续使用 Cursor 内置模型,因此不能用 Tab 行为判断 BYOK 或中转站是否配置成功。
Cursor Agent 能否保证兼容任意中转站?
不能。官方未承诺任意 OpenAI-compatible Base URL 都完整支持 Agent、tools 和 streaming;必须用真实受控任务验证工具事件、文件修改、测试结果和正常结束。
本文技术参数与官方资料复核于 2026-10-09;模型、价格、限额与客户端界面会变化,使用前请再次核对官方文档和当前控制台。

