# Cursor 编辑器接入

[Cursor](https://cursor.com) 是基于 VS Code 的 AI-native 编辑器。Cursor 3.5（2026-05-20 发布）带来 **Cloud Agents**（在隔离云端 VM 里跑 agent，带终端与浏览器）；此前的 3.x 已引入 **Agents Window**（多 agent 协调）、**Design Mode**（视觉设计 + 代码联动）、**CLI agents**（终端中的子 agent），自研模型也升到 **Composer 2.5**。本文介绍如何把 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](https://cursor.com/download)（macOS / Windows / Linux）
- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- 同一把 API Key 通吃 QCode 全部协议与四个接入域（`api` / `asia` / `us` / `eu`），中国大陆用户首选 `asia.qcode.cc`

## 可用模型

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

| 模型 | 输入 / 输出（每百万 token） | 上下文 | 适用 |
|------|------|------|------|
| `claude-opus-5` | $5 / $25 | 1M | 旗舰，复杂重构 / 长上下文 |
| `claude-opus-4-7` | 旗舰价 | 1M | 旗舰备选 |
| `claude-sonnet-5` | $2 / $10 | 1M | 日常主力，性价比高 |
| `claude-haiku-4-5` | $1 / $5 | 200K | 快速补全 / 轻量任务 |
| `gpt-5.5` | $5 / $30 | 1M | OpenAI 旗舰 |
| `gpt-5.4` | $2.5 / $15 | 1M | 均衡 |
| `gpt-5.6-mini` | — | 272K | 低成本 |
| `gpt-5.6-terra` | — | 272K | 代码专用 |
| `gemini-2.5-pro` | 见定价页 | — | Gemini 旗舰 |
| `gemini-3.5-flash` | 见定价页 | — | Gemini 快速档 |

> Gemini 单价与是否有套餐倍率以 [qcode.cc/models](https://qcode.cc/models) 为准，不要沿用口头「×2」。上表是当前推荐；`claude-sonnet-4-6` / `claude-opus-4-8` / `claude-opus-4-7` 等 4.x 仍在售。

## 配置步骤

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

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

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

> 🔴 **这条腿不能用 Claude，也不能用 Gemini。** QCode 的 OpenAI 端点只接受上述两类模型，填 `claude-…` 或 `gemini-…` 会返回 `model_not_available_on_endpoint`。Claude 请走下面的路径 B。对照表见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

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

   | 字段 | 值 |
   |------|-----|
   | OpenAI API Key | 你的 QCode.cc API Key（`cr_` 开头）|
   | Override OpenAI Base URL | `https://api.qcode.cc/openai/v1` |

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

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

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

| 协议 | Base URL | SDK 实际追加 | Cursor 里用 |
|------|----------|------|------|
| OpenAI Chat | `https://api.qcode.cc/openai/v1` | `/chat/completions` | ✅ 路径 A 填这个 |
| OpenAI Responses（Codex 风格） | `https://api.qcode.cc/openai` | `/v1/responses` | 一般无需手填 |
| Anthropic | `https://api.qcode.cc/api` | `/v1/messages` | 路径 B / Claude Code CLI |
| Gemini | `https://api.qcode.cc/gemini` | `/v1beta/...` | 只能走这条，**不能经 OpenAI 透传** |

### 路径 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。**要用 Claude，就只设 Anthropic 的 override，把 OpenAI override 留空**；两者都要用时，建议分开的 Cursor 配置或按需切换。

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

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

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

| 功能 | 自定义端点支持 | 说明 |
|------|------|------|
| Cursor Chat | ✅ 稳定 | 直接走你配的 Base URL |
| Composer（多文件编辑） | ✅ 稳定 | 选已 enable 的 model id |
| Inline Edit (Cmd+K) | ✅ 可用 | 见下方延迟提示 |
| Cursor Tab（行内补全） | ⚠️ 受限 | 该特性多绑 Cursor 自家专有模型，自定义端点常无法替代 |
| Agents Window / 后台 agent | ⚠️ 视版本 | 对 OpenAI/Anthropic 主流协议最稳，部分 agent 子能力可能要求 Cursor 内置模型 |
| Bug Bot / 索引等托管特性 | ⚠️ 视版本 | 这类特性可能只对 Cursor 内置模型开放 |

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

## 一个典型工作流

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

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

这套流程完全跑在你配的 QCode 端点上，配额按 [计费说明](/docs/reference/billing) 统一结算。

## 备用节点

| 节点 | OpenAI Base URL | Anthropic Base URL |
|------|-----------------|--------------------|
| 全球通用（境外用户首选） | `https://api.qcode.cc/openai/v1` | `https://api.qcode.cc/api` |
| 亚洲（中国大陆首选） | `https://asia.qcode.cc/openai/v1` | `https://asia.qcode.cc/api` |
| 北美 | `https://us.qcode.cc/openai/v1` | `https://us.qcode.cc/api` |
| 欧洲 | `https://eu.qcode.cc/openai/v1` | `https://eu.qcode.cc/api` |

四个域是同一套服务的不同入口，**同一把 API Key 通用**。完整说明见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 图像输入与图像生成

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

## 与 Claude Code 同时使用

Cursor 的内置 AI 与独立的 [Claude Code CLI](/docs/getting-started/installation) 并不冲突——两者都可在同一个 Cursor 窗口里用：

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

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

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

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

## 限制与注意

- **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 3.5 Agents Window** 当前对 OpenAI / Anthropic 协议的兼容性最稳；非主流 provider（如自建 OSS 模型）支持度参差
- **覆盖是全局开关**：Override OpenAI Base URL 一旦填上，Cursor 内默认走 OpenAI 协议的请求都会改道 QCode。想临时回 Cursor 默认，清空该字段即可

## 实用建议

- **按任务选模型**：走路径 B（Anthropic，`https://api.qcode.cc/api`）时，日常编辑用 `claude-sonnet-5` 性价比最高、大型重构上 `claude-opus-5`；走路径 A（OpenAI）时，纯代码补全可试 `gpt-5.6-terra`、通用任务用 `gpt-5.5`
- **长上下文优先 1M 档**：`claude-opus-5` / `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 模型

Composer 默认走 OpenAI 协议，而 QCode 的 OpenAI 端点**不接受 Claude 模型**——把 `claude-opus-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 集成](/docs/ide/vscode) — 同源编辑器，通用配置思路
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — QCode.cc 三协议四接入域全表
- [gpt-image-2 图像生成](/docs/usage/image-2) — 图像生成专用端点
- [子代理](/docs/advanced/subagents) — Claude Code 子代理用法
- [自动化与 CI/CD](/docs/advanced/headless) — headless 工作流
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — CLI 工作流参考
- [计费说明](/docs/reference/billing) — 共享配额规则

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