接入教程

Cursor 中转 API 配置:API Key、Base URL 与功能限制

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

Cursor BYOK 从 Settings 保存供应商 Key、验证聊天模型、经过 Cursor 后端到网关预检和网络诊断的四步边界
Cursor BYOK 依次在 Settings 配置 Key、只验证聊天模型、确认请求经过 Cursor 后端,并预检网关与网络。

Cursor 配置中转 API必须拆成两个验证阶段:先用 curl 证明网关的 URL、Key、模型和 Chat Completions 可用,再在 Cursor 中确认当前版本是否暴露对应设置以及哪项功能实际经过该路径。

“Cursor API 中转”并不对应 Cursor 提供的某个公开模型 API;本文核对的是 Cursor 模型配置里的自定义 API Key(BYOK)与官方提及的 OpenAI-compatible Base URL override。

直接答案:Cursor 配置中转 API 与网关预检

  1. 打开 Cursor Settings > Models。
  2. 找到官方支持的 provider,粘贴专用测试 Key,点击 Save。
  3. 若当前版本显示 OpenAI-compatible Base URL override,按网关文档填写;官方没有公开统一的尾部路径规则。
  4. 只选择一个 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 上用 Cursor 预检:GPT 模型、分组与价格

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 KeySettings > Models 支持粘贴后点击 Save
BYOK 覆盖范围chat modelsTab 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 Keychat model BYOK是当前页面讨论对象
CURSOR_API_KEYCursor 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 / rejectedprovider 与 Key 是否匹配更新或移除 Key
模型不出现provider 支持与地区限制BYOK 不能绕过 provider 地区限制
curl 成功、Cursor 失败当前版本的 URL 字段语义与模型支持不要继续猜路径,恢复原配置
流式连接失败代理、VPN、HTTP/2Run Diagnostics;必要时切 HTTP/1.1 并重启
Agent 循环或工具失败模型能力、工具 Schema、流事件复制 Request ID 与相关日志

网关请求 Schema 的迁移见 OpenAI 兼容 API 迁移;先用 OpenAI 兼容 API 快速验证确认端点;数据路径参考 中转站安全与隐私;Agent 工具链用 流式与工具兼容矩阵验收。

Cursor 验证指标与回滚

在固定小仓库中重复 10 次聊天和 5 次 Agent 任务,记录 Cursor version、Request ID、网关命中率、首字时间、完整结束率、工具成功率、测试退出码、实际 diff 与用量。网关命中率按“网关日志中可对应请求数 ÷ Cursor 发起任务数”计算,不能用模型下拉框代替证据。

  1. 停止 Agent 和长响应,保存 Request ID、日志与工作区 diff。
  2. 在 Settings > Models 移除测试 Key 和 override,恢复原 provider 或内置模型。
  3. 重启 Cursor,建立新会话,在同一测试仓库重跑基线。
  4. 确认网关不再收到请求、聊天恢复且没有重复文件修改后,撤销测试 Key。

官方资料

命令行工具的对应配置见 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;模型、价格、限额与客户端界面会变化,使用前请再次核对官方文档和当前控制台。