Cursor 自定义 API

在 Cursor 中填写自定义 OpenAI / Anthropic Base URL 与 API Key 接入 QCode，含模型 ID、设置步骤与自定义端点限制（2026）。

需要 API Key？ 前往注册 →·端点与 Base URL →

最后核实：2026-10-20 · 📄 依据官方文档（Cursor 官方下载页 2026-10-20 仍列 3.24 为最新，官方 changelog 最新一条为 2026-10-16；BYOK 帮助页同日核对；Override 字段的 3.15.6 论坛答复作为 2026-08-11 的历史记录保留）

可以。 Cursor 支持填入自己的 API Key，并打开 Override OpenAI Base URL（或 Override Anthropic Base URL）指向 QCode；Chat、Composer 与 Inline Edit 走 QCode 的端点。Tab 补全仍由 Cursor 内置模型提供，请求也依旧经 Cursor 后端组装 prompt。

接入速览¶

字段位置与已知问题¶

要填地址的地方在 Settings → Models → API Keys。 官方帮助中心的 BYOK 页（cursor.com/help/models-and-usage/api-keys）只写了四步：打开 Cursor Settings → Models → 找到目标 provider（OpenAI、Anthropic、Google、Azure 或 AWS Bedrock）→ 把 API Key 贴进文本框 → Save，正文没有逐字段列出 Override 输入框。字段本身确实存在——Cursor 员工 deanrie 在官方论坛里点名确认过：

"The fix for the OpenAI API Key and Override OpenAI Base URL fields, and other provider key fields, that didn't focus on mouse click has been merged and will ship in an upcoming 3.15 update. It's not in 3.15.6 yet. Once you update to a version newer than 3.15.6, please try again."（2026-08-11，论坛原帖）

三条可操作结论：

• 字段名是 Override OpenAI Base URL（OpenAI 协议）与 Override Anthropic Base URL（Anthropic 协议），各自旁边有一个启用开关（toggle）。
• 3.15.6 有已知回归：鼠标点不进这些输入框。官方给的绕法是在 Settings → Models 里先打开对应 toggle，再按 Tab 把焦点移进文本框，之后键入和 Ctrl+V 粘贴都正常；也可以临时回退 3.14.27。修复随 3.15 的后续版本发布，3.15.6 还没有，所以先升级到比 3.15.6 更新的版本再试（2026-10-20 复核：官方下载页已是 3.24，这条 2026-08-11 的论坛答复作为 3.15.6 时期的历史记录保留）。
• 同一页还逐字写着：「Your API key is not stored on our servers. It is sent to our backend with every request because all requests are routed through Cursor's servers for final prompt building」——即便自带 Key，请求仍要经 Cursor 后端组装 prompt，不是「编辑器直连你的模型提供方」。

另外三条限制与一条时效风险：

• Teams / Enterprise 套餐即使自带 Key 也仍按 Cursor Token Rate 计费；自带 OpenAI Key 的官方描述限定在 "Standard, non-reasoning chat models"（标准、非推理的对话模型）。
• 要让流量完全绕开 Cursor 后端，只能改用支持自定义 Base URL 的客户端：Claude Code、Codex CLI、Cline、Zed 等。
• 时效风险：OpenAI 在 2026-08-28 的官方声明写的是「we intend to wind down our contract providing OpenAI models to Cursor, with a proposed shutoff date of November 12, 2026」——拟于 2026-11-12 终止向 Cursor 供模型，尚未生效；Cursor 侧截至 2026-09-18 没有对应公告。原文：openai.com。

Cursor 是基于 VS Code 的 AI-native 编辑器。官方 changelog 不按版本号组织内容，最新一条发布于 2026-10-16；2026-10-20 官方下载页列出的最新版是 3.24。本文说明怎样把 QCode.cc 接进 Cursor —— 但请先读下一节，它决定了这条路在你那儿通不通。

为什么用 Cursor¶

• Agents Window（v3 新增）：在侧边栏并行跑多个 AI agent，互相不干扰
• Cursor Composer：多文件编辑 + 上下文感知重构，比 Cursor Chat 更适合大改
• Inline Edit (Cmd+K)：选中代码后直接给指令，最快速的迭代方式
• 基于 VS Code：所有 VS Code 扩展生态可继承（包括 Claude Code 的 VS Code 扩展）

前置条件¶

• 已安装 Cursor（macOS / Windows / Linux）
• 拥有 QCode.cc API Key（cr_ 开头），在 控制台 获取
• 同一把 API Key 通吃 QCode 全部协议与三个接入域（api / asia / us），中国大陆用户首选 asia.qcode.cc

可用模型¶

下表是 QCode 侧常用的模型 id（实时清单与单价看 qcode.cc/models）。填进 Cursor 时用的就是这些 id，字段位置与 3.15.6 的输入框问题见上面「字段位置与已知问题」。

QCode 暂不提供 Gemini 系列，也不提供 gpt-6-luna / gpt-5.6-luna。上表是当前推荐；claude-opus-5、claude-sonnet-5、claude-sonnet-4-6、claude-opus-4-8 等仍可调用，可调型号与单价以 qcode.cc/models 为准。

配置步骤¶

下面两条路径分别对应那两个 Override 字段；路径 A（OpenAI 协议）兼容性最好。如果输入框点不动，用上面写的 Tab 绕法或升级到比 3.15.6 更新的版本。

路径 A：Custom OpenAI-compatible endpoint（推荐）¶

走 OpenAI 协议接 QCode 的 /openai/v1 路径，可用 GPT 系与国产四家族（GLM / Kimi / DeepSeek / Qwen）。

🔴 这条路径不能用 Claude。 QCode 的 OpenAI 端点只接受上述两类模型，填 claude-… 会返回 model_not_available_on_endpoint。QCode 暂不提供 Gemini 模型。Claude 请走下面的路径 B。对照表见 接入点与 API 格式。

1. 打开 Cursor 设置：Cmd + ,（macOS）/ Ctrl + ,（Windows/Linux）
2. Models → 滚到底部 Override OpenAI Base URL
3. 填写：

1. 在 Models 列表勾选要启用的模型（如 gpt-6.1-sol、gpt-5.6-terra），未列出的可点 + Add model 手动加 model id
2. 点 Verify 测试连通；通过后即可在 Cursor Chat / Composer 中使用

Base URL 末尾不要带斜杠。QCode 的自检请求返回 401 表示路径正确、只是缺鉴权——这是正常现象，说明端点能连通。

各协议的 Base URL 对照（同一把 Key 全部通用）：

路径 B：Custom Anthropic endpoint（接 Claude 原生协议）¶

如果你想用 Claude 模型的 Anthropic 原生协议，QCode 的 Anthropic Base URL 是 https://api.qcode.cc/api（SDK 会自动追加 /v1/messages）。

在 Cursor 设置的 Models → Anthropic API 里填入你的 QCode Key，并打开 Override Anthropic Base URL 填上面这个地址。

🔴 两个 override 会互相干扰。 社区反馈：一旦设置了 Override OpenAI Base URL，Cursor 会把 Claude 流量也塞进那个 OpenAI 端点，导致 Claude 模型报 422。Cursor 官方文档没有记录这一行为，它属于社区观察，可能随版本变化。要用 Claude，就只设 Anthropic 的 override，把 OpenAI override 留空；两者都要用时，建议分开的 Cursor 配置或按需切换。

⚠️ Agent 模式下部分能力会用 OpenAI Responses API 风格，与 Anthropic 协议路径在某些场景不兼容（典型表现为工具调用 schema 转换失败）。Cursor 的端点开关时有变动，具体以 Cursor 官方文档为准。

自定义端点能用哪些功能¶

Cursor 把它的 AI 能力分成几类，自定义 OpenAI 端点对它们的覆盖程度不同。下表是按当前观察给出的实用判断，Cursor 升级频繁，最终以 Cursor 官方为准：

简言之：Chat / Composer / Inline Edit 三件套用 QCode 端点最可靠；高度托管的特性（部分 agent 流程）可能保留在 Cursor 自家模型上。Tab 补全这一条已由官方原文确认（2026-10-20 核对，见上表），其余判断来自观察而非官方文档，Cursor 升级频繁，请以官方公告为准。

一个典型工作流¶

接好端点后，Composer 的日常用法大致如此：

1. 在 Composer 里选好模型（例如 claude-sonnet-5-5 日常、claude-opus-5-5 啃大改）
2. Cmd + I 打开 Composer，把要改的文件拖进上下文区
3. 用自然语言描述目标，例如"把这个组件的状态管理从 useState 迁到 useReducer，保持现有 props 不变"
4. 审阅 diff，逐块 Accept / Reject
5. 需要快速局部修改时用 Inline Edit（Cmd + K），不必每次开 Composer

这套流程完全跑在你配的 QCode 端点上，配额按 计费说明 统一结算。

其他接入点¶

三个域是同一套服务的不同入口，同一把 API Key 通用。完整说明见 接入点与 API 格式。

图像输入与图像生成¶

• 图像输入（让模型"看图"）：Cursor 支持把截图 / 设计稿粘贴或拖入对话，让视觉模型读图——例如照着 UI 草图写组件、用报错截图排查 bug。QCode 上具备视觉能力的模型包括 Claude Opus 5.5 / Sonnet 5.5 / Haiku 5.5 与 GPT 系（如 gpt-6.1-sol、gpt-5.6-terra）。
• 图像生成（让模型"画图"）：这是另一回事。生成图片用 QCode 的 gpt-image-2 模型，走专用图像端点，不在 Cursor 编辑器流程里。详见 gpt-image-2 图像生成。

与 Claude Code 同时使用¶

Cursor 的内置 AI 与独立的 Claude Code CLI 并不冲突——两者都可在同一个 Cursor 窗口里用：

• Cursor 的 Chat / Composer：编辑器内的 AI，走 Cursor 设置中配的端点
• Claude Code CLI：在 Cursor 集成终端（Ctrl + `）里运行 claude，走 CLI 自身的 ANTHROPIC_BASE_URL 环境变量

在集成终端里把 Claude Code 指向 QCode（Anthropic 协议）：

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的Key"
claude

两条路径独立认证，但用同一个 QCode API Key 就共享配额（详见 计费说明）。Claude Code 的 子代理 与 自动化与 CI/CD 都能在这个终端里直接用。

限制与注意¶

• Privacy Mode：Cursor 默认会把代码片段发给配置的端点。如果你在 Cursor 设置里启用了 Privacy Mode，请确认 API Key 配置后仍然能接到 QCode；Privacy Mode 不影响外发流量，只阻止 Cursor 自己存储 prompt
• Cursor Pro 订阅 与 QCode API Key 是独立的两套 — Cursor Pro 给你 Cursor 内置 quota（走 Cursor 自己的模型池），QCode API Key 走 QCode 的服务。两者都在用时按 Cursor 设置的优先级路由
• Agents Window 与后台 agent 对主流 provider（OpenAI / Anthropic 协议）兼容性最好；自建 OSS 模型一类支持度参差
• Override 是全局开关：填上 Override OpenAI Base URL 后，Cursor 内默认走 OpenAI 协议的请求会指向 QCode 地址，清空即回默认。但按官方说法，请求仍先经 Cursor 后端组装 prompt，所以「只有流量改道、隐私边界不变」这类理解并不成立
• Zero Data Retention 不适用于自带 Key（官方 BYOK 页，2026-10-20 核对）：使用自己的 API Key 时，Cursor 的 Zero Data Retention 政策不适用；数据处理遵循你所选 provider（OpenAI、Anthropic、Google、Azure 或 AWS）的隐私政策
• Teams / Enterprise 仍收 Cursor Token Rate（官方 BYOK 页，2026-10-20 核对）：即使自带 Key，Teams / Enterprise 上每个第三方模型请求仍按 Cursor Token Rate 计费，标准为每百万 token $0.25，输入、输出与缓存 token 均计；个人套餐（Premium / Super / Ultra 及旧 Pro 等）下，自带 Key 的请求不计入套餐额度

实用建议¶

• 按任务选模型：走路径 B（Anthropic，https://api.qcode.cc/api）时，日常编辑用 claude-sonnet-5-5 性价比最高、大型重构上 claude-opus-5-5；走路径 A（OpenAI）时，纯代码补全可试 gpt-5.6-terra、通用任务用 gpt-6.1-sol
• 长上下文优先 1M 档：claude-opus-5-5 / gpt-6.1-sol 等 1M 上下文模型适合喂整个仓库的 Composer 大改
• 省钱：把 Composer 默认模型设成中档，只在啃硬骨头时手动切旗舰
• 端点就近：中国大陆可把 Base URL 换成亚洲接入点 https://asia.qcode.cc/openai/v1（大陆推荐）
• 遇到诡异行为先 Verify：Cursor 升级后端点行为可能变化，先点一次 Verify 再排其它问题

常见问题¶

Cursor 提示 "API key not valid"¶

1. 确认 API Key 完整、cr_ 开头、无前后空格
2. 在 Cursor 设置里点 Verify 看具体错误
3. 命令行测试连通： bash curl -H "Authorization: Bearer YOUR_KEY" \ https://api.qcode.cc/openai/v1/models 返回 JSON 列表则端点 + API Key 都 OK

Verify 失败但 curl 能通¶

多半是 Base URL 末尾多了斜杠 或写成了不带 /v1 的路径。确认填的是 https://api.qcode.cc/openai/v1（OpenAI 协议）且末尾无 /。注意：直接打 base 路径返回 401 是正常的（路径对、缺鉴权），不代表配置错。

Composer 用不了 Claude 模型¶

Composer 默认走 OpenAI 协议，而 QCode 的 OpenAI 端点不接受 Claude 模型——把 claude-opus-5-5 加进 Models 列表也没用，请求会被以 model_not_available_on_endpoint 拒绝。

正确做法是走路径 B：在 Models → Anthropic API 填 QCode Key，打开 Override Anthropic Base URL 填 https://api.qcode.cc/api，并清空 Override OpenAI Base URL（否则 Cursor 会把 Claude 流量也发到 OpenAI 端点，报 422）。

Inline Edit (Cmd+K) 速度慢¶

Cursor 的 Cmd+K 默认用 Cursor 自家 fast model；切换到 QCode 后改走配置的 base URL，首次延迟会比 Cursor 内置稍高（多一跳中转）。可在设置里勾选 Cursor Tab 用 Cursor 默认，Chat / Composer 用 QCode 端点。

Agents Window / 后台 agent 报错或不走 QCode¶

部分 agent 子能力对模型来源有要求，可能强制使用 Cursor 内置模型而非自定义端点。这是 Cursor 侧的设计，随版本变化，以 Cursor 官方文档为准；可先把 Chat / Composer 切到 QCode 用，agent 流程保留 Cursor 默认。

模型下拉里看不到我加的 model id¶

确认在 Models 列表里既勾选了该模型、又通过 + Add model 正确填了 id（区分大小写、不要多空格）。改完后重启一次 Cursor 让列表刷新。

下一步¶

• VS Code 集成 — 同源编辑器，通用配置思路
• 接入点与 API 格式 — QCode.cc 三协议三接入域全表
• gpt-image-2 图像生成 — 图像生成专用端点
• 子代理 — Claude Code 子代理用法
• 自动化与 CI/CD — headless 工作流
• Claude Code 完整教程 — CLI 工作流参考
• 计费说明 — 共享配额规则

还没有 API Key？到 qcode.cc/pricing 选套餐，一把 Key 在 Cursor、Claude Code 和所有支持自定义端点的工具里通用。

企业团队版 →