Cursor 除了内置订阅，还支持填入自己的 OpenAI 兼容 API Key。把 Key 换成中转站的 Key、Base URL 换成中转站地址，就能在 Cursor 里按量调用 Claude、GPT、Gemini 等模型，用哪个模型、花多少钱都由自己控制。配置本身只有两三个输入框，但 Base URL 格式和模型名是两个高频翻车点，很多人卡在 Verify 按钮上反复失败。这篇按步骤讲清配置方法，把常见坑逐个拆开。
为什么要在 Cursor 里配自定义 API
三类用户适合这么做：
- 订阅额度经常提前用完，快速请求次数不够，想用按量付费补充重度用量
- 想在 Cursor 里用到订阅方案覆盖不到的模型，或者自由指定模型版本
- 团队已经统一采购 API，希望 Cursor、Claude Code、服务端脚本共用一套 Key 和一张账单
以 Zivv 为例：一个 Key 可以调用 100+ 模型，充值汇率 ¥1 = $1，价格低至官方几折。Cursor 走的是标准 OpenAI 兼容协议，属于最容易接入的一类客户端，整个过程大约五分钟。
这里先澄清一个常见误解：配自定义 API 不是「破解」Cursor，而是 Cursor 官方提供的标准能力。编辑器功能照常，只是模型请求从 Cursor 的托管后端换成了你指定的端点。这也让排查思路变得很清晰：出问题要么是填写不对，要么是 Key 或模型不对，范围非常小。
配置前准备
建议给这个 Key 单独命名为 Cursor 专用。之后在用量页能直接看到 Cursor 消耗了多少，不会和 Claude Code、脚本任务混在一起，排查异常消耗时也只需要停这一个 Key。
另外确认一下客户端版本。Cursor 更新很快，设置页的布局和字段名偶尔会调整，如果你的界面和本文描述对不上，以「OpenAI API Key + Base URL 覆盖」这两个关键字段为锚点去找即可，接入原理不变。
三步完成配置
第一步：打开模型设置
点击 Cursor 右上角齿轮进入 Cursor Settings，找到 Models 相关设置页（不同版本入口名称略有差异，通常叫 Models 或 Models & API Keys）。
第二步：填写 Key 与 Base URL
在 OpenAI API Key 区域依次操作：
- 粘贴 Zivv 的 sk- Key
- 勾选 Override OpenAI Base URL（覆盖默认地址）
- Base URL 填入：
https://zivv.pro/v1注意结尾是 /v1：不要只填域名，不要补全到 /chat/completions，也不要在末尾多加一个斜杠。这一个输入框贡献了大部分的接入失败。
第三步：添加模型并验证
点击 Verify 之前，先做两件事：把模型列表里用不到的内置模型名取消勾选；再通过 Add model 手动添加你确认存在的模型名，例如：
- claude-sonnet-5
- claude-opus-4-8
- gpt-5.5
模型名必须与平台返回的 id 完全一致，大小写、连字符、版本号都不能差一个字符。然后点 Verify，通过后在对话窗口的模型下拉里选中刚添加的模型即可使用。
一个容易误解的细节：Verify 失败不一定代表配置全错。它做的是抽样测试，只要勾选中有一个模型的请求失败，整体就报失败。所以正确顺序是先做减法（取消全部内置模型），再做加法（逐个添加确认可用的模型），每加一个验证一次，哪个模型有问题一目了然。
先用 curl 验证链路
如果 Verify 一直失败，不要在客户端里反复试。先在终端确认 Key 和地址本身是通的，把「客户端填写问题」和「API 侧问题」分开：
curl https://zivv.pro/v1/chat/completions \
-H "Authorization: Bearer sk-your-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [{"role": "user", "content": "回复 OK"}]
}'curl 正常返回而 Cursor 失败，说明问题出在客户端填写，回头检查 Base URL 和勾选的模型；curl 也失败，就先对照 错误码说明 排查 Key 是否有效、模型名是否可用。这条 curl 也适合放进团队的接入文档，新人配置前先跑一遍，能把「Key 无效」和「客户端没配好」两类问题在源头分开。
坑一：Base URL 格式
| 填写内容 | 结果 |
|---|---|
| https://zivv.pro | 404，缺少 /v1 前缀 |
| https://zivv.pro/v1/chat/completions | 客户端再拼一次路径，请求失败 |
| https://zivv.pro/v1/ | 结尾多斜杠，部分版本拼出双斜杠导致 404 |
| https://zivv.pro/v1 | 正确 |
规则只有一条：OpenAI 兼容入口填到 /v1 为止，具体接口路径由客户端自动拼接。这条规则同样适用于 Cline、Cherry Studio 等其他客户端，记住一次就够了。
坑二：模型名不匹配
模型名问题有两种典型表现。
表现一：Verify 直接失败。 Cursor 验证时会拿列表里勾选的模型发送测试请求。如果勾选项里还留着中转站没有的内置模型名，验证会因为其中某一个模型不存在而失败。解决办法是只保留你手动添加、确认存在的模型名，其余全部取消勾选。
表现二：平时能用，某次对话突然报 model not found。 通常是对话窗口当前选中的模型不在这个 Key 可用的模型分组里。到模型广场确认分组包含该模型，或者切回一个确认可用的模型名重试。模型 id 以当前 模型列表文档 为准，不要凭记忆手打。
模型选择建议
| 场景 | 建议模型 |
|---|---|
| 日常问答、改小函数 | claude-sonnet-5 或 gpt-5.4 |
| 多文件重构、复杂逻辑推理 | claude-opus-4-8 |
| 长文档、大段粘贴材料 | gemini-3.5-flash |
| 生成测试、补注释、写文档 | 中档模型即可 |
不必把所有对话都默认到最强模型。日常用中档模型，遇到难题临时切到 claude-opus-4-8，用完再切回来，账单会明显更好看。
一个实用约定：中档模型两次没解决就升档。这样既不会在便宜模型上无限耗时间，也不会默认高档模型白烧钱。选模型时把输入和输出单价都看一眼，输出单价的档位差距往往更大。
用得省的三个习惯
配置成功只是开始，Cursor 这类编辑器的消耗大头在上下文，三个习惯能省下明显的一截：
控制上下文范围。 整仓库检索、@codebase 这类操作会把大量文件内容塞进请求。日常提问尽量用 @file 指定具体文件，只有真正需要全局理解时才用大范围检索，两者的单次成本可以差一个数量级。
长对话适时重开。 对话历史会随每次请求重复发送。一个聊了一下午的对话，每条新消息都背着全部历史在计费。任务告一段落就新开对话，让上下文归零。
按任务切模型。 模型下拉切换只要两秒。把「默认中档、难题升档、用完切回」变成肌肉记忆，比任何单项优化技巧都省钱。
和 Claude Code 怎么分工
很多开发者两个工具都在用，推荐这样分：Cursor 负责编辑器内的即时问答、局部修改、边写边问；Claude Code 负责跑得久的任务——大型重构、批量迁移、测试修复循环。两者接同一个 Zivv 账号的不同 Key，模型和账单统一管理，Claude Code 侧只需要换两个环境变量，做法见 Claude Code 配置文档。
团队统一接入
如果是团队集体从订阅切到 API 模式，不要把同一个 Key 群发给所有人。正确姿势：
- Owner 开通团队模式，成员各自持有独立 Key
- 每人自己在 Cursor 里填 Key，Base URL 统一写进内部文档
- 给新人和实习生设小额预算，用量跑飞有边界
- 每周看一次用量排行，异常消耗一眼定位到人
这样成本从「一笔糊涂账」变成「每人一行数据」，泄露时也只需要停掉单个 Key，不影响其他人。
已知限制
自定义 API Key 主要作用于 Chat、Composer 这类对话与 Agent 能力。Cursor 的 Tab 补全等部分功能由官方服务提供，不走自定义 Key。所以常见的组合用法是：保留最低档订阅负责补全体验，重度对话和 Agent 任务走中转按量付费。两边各管一段，成本都可控。
另外，Cursor 版本更新偶尔会调整自定义 API 相关的界面和行为。升级后如果突然失效，先重新走一遍 Verify 流程，再确认设置有没有被重置，一般两分钟内能恢复。
常见问题 FAQ
Q：配置了自定义 Key 之后还需要 Cursor 订阅吗？ A：取决于你是否依赖 Tab 补全等官方功能。只用 Chat 和 Agent 的话，自定义 Key 可以承担绝大部分用量；依赖补全就保留低档订阅搭配使用。
Q：一个 Key 能同时给 Cursor 和 Claude Code 用吗？ A：可以。Zivv 的 Key 同时兼容 OpenAI、Anthropic、Gemini 三种协议。但更推荐分工具建 Key，用量分开统计，泄露时也能单独停用。
Q：Verify 通过了，用着用着报 401 是怎么回事？ A：验证通过说明当时链路正常，后来的 401 一般是 Key 被删除、被停用或余额耗尽。到控制台确认 Key 状态和余额即可。
Q：怎么切回官方或订阅模式？ A：把 Override OpenAI Base URL 的开关关掉即可，填过的配置会保留，随时可以再切回来，两边互不影响。
Q：中转会不会影响响应速度？ A：中转增加的是毫秒级转发开销，主要耗时仍在模型推理本身。实际体感和直连基本一致。
Q：偶尔报 429 或提示速率限制怎么办？ A：先换一个模型试，能立即恢复的多为单模型高峰拥堵；持续 429 则检查是否有脚本在共用这把 Key，把编辑器和脚本的 Key 分开就能定位。
写在最后
接入完成后，Cursor 的用法没有任何变化，变化的是你对模型和成本的控制权：想用什么模型自己挑，花了多少钱随时看，不再受单一订阅的模型范围束缚。如果团队多人都在用 Cursor，建议配合 团队模式 做到一人一 Key、独立预算。现在就可以 注册 Zivv，五分钟把 Cursor 切到按量计费。