Cursor 编辑器接入

在 Cursor IDE 中通过自定义 Anthropic / OpenAI Base URL + API Key 接入 QCode.cc，含模型配置、自定义端点限制说明与排错

Cursor 编辑器接入¶

Cursor 是基于 VS Code 的 AI-native 编辑器。Cursor v3（2026-04 发布）引入 Agents Window（多 agent 协调）、Design Mode（视觉设计 + 代码联动）、CLI agents（终端中的子 agent）三大新能力。本文介绍如何把 QCode.cc 配置为 Cursor 的上游模型来源：核心是在 Cursor 设置里填一个自定义 Base URL 加你的 QCode API Key。

为什么用 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 / eu），中国大陆用户首选 asia.qcode.cc

可用模型¶

QCode 通过同一把 Key 提供三大协议的模型。Cursor 的自定义端点走 OpenAI 协议最稳，模型 id 直接填下表的值即可：

Gemini 系列在 QCode 按 ×2 计费。完整价目见 qcode.cc/pricing。

配置步骤¶

Cursor 有两条接入路径，按场景选其一即可。路径 A（OpenAI 协议）兼容性最好，强烈推荐。

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

走 OpenAI 协议接 QCode 的 /openai/v1 路径，可用 GPT-5.5 / GPT-5.4 / Gemini 以及透传的 Claude 等多家模型。

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

1. 在 Models 列表勾选要启用的模型（如 gpt-5.5、gpt-5.4、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 对自定义 Anthropic 端点的支持随版本变化，且 Agent 模式下部分能力会用 OpenAI Responses API 风格，与 QCode 的 Anthropic 协议路径在某些场景下不兼容（典型表现为某些工具调用 schema 转换失败）。建议优先用路径 A 走 OpenAI 协议；如果要用 Claude 模型，可在路径 A 里加 claude-opus-4-8 / claude-opus-4-7 等 model id（QCode 在 OpenAI 协议层做透传）。Cursor 的端点开关时有变动，具体以 Cursor 官方文档为准。

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

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

简言之：Chat / Composer / Inline Edit 三件套用 QCode 端点最可靠；高度托管的特性（Tab 补全、部分 agent 流程）可能保留在 Cursor 自家模型上。Cursor 何时放开自定义端点用于某个 agent 特性，请以官方公告为准。

一个典型工作流¶

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

1. 在 Composer 里选好模型（例如 claude-sonnet-4-6 日常、claude-opus-4-8 啃大改）
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 4.8 / Sonnet 4.6 与 GPT-5.x。
• 图像生成（让模型"画图"）：这是另一回事。生成图片用 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 走我们家的中转池。两者都在用时按 Cursor 设置的优先级路由
• Cursor v3 Agents Window 当前对 OpenAI / Anthropic 协议的兼容性最稳；非主流 provider（如自建 OSS 模型）支持度参差
• 覆盖是全局开关：Override OpenAI Base URL 一旦填上，Cursor 内默认走 OpenAI 协议的请求都会改道 QCode。想临时回 Cursor 默认，清空该字段即可

实用建议¶

• 按任务选模型：日常编辑用 claude-sonnet-4-6 性价比最高；大型重构 / 长上下文上 claude-opus-4-8；纯代码补全可试 gpt-5.6-terra
• 长上下文优先 1M 档：claude-opus-4-8 / gpt-5.5 等 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 模型¶

Cursor v2 起 Composer 默认走 OpenAI 协议；选 Claude 时需要在 Models 列表里手动添加 claude-opus-4-8 等 model id（即使 QCode 通过 OpenAI 协议透传 Claude 模型，Cursor 也需要识别 model id 才能下拉显示）。

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 和所有支持自定义端点的工具里通用。