> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Cursor 搭配 CC Switch 使用指南，通过本地代理统一管理多模型供应商并一键切换

> 本文介绍如何将 AI 代码编辑器 **Cursor** 与开源配置管理工具 **CC Switch** 配合使用，实现多模型供应商的统一管理与一键切换。

## 一、什么是 Cursor

Cursor 是一款面向 AI 编程的代码编辑器。你可以使用 Cursor 进行：

* 代码补全
* 代码生成
* 代码修改
* 代码解释
* 项目分析
* Bug 排查
* Agent 编程

## 二、什么是 CC Switch

CC Switch 是一个**开源的本地图形化 AI 服务配置管理与反向代理工具**。

它主要解决两个问题：

1. **配置统一化**：将分散在 Claude Code、Cursor、OpenCode 等各类 AI 编程工具中的 API Key 与 Base URL 集中管理，避免多份配置文件互相冲突。
2. **协议中转**：让原本只支持特定原生协议的应用（如 Cursor 的 Codex 插件），也能通过标准接口调用更多第三方兼容 API。

使用 Cursor 接入 CC Switch 后，整体流程如下：

```text theme={null}
Cursor
   ↓
CC Switch API
   ↓
可用模型
   ↓
AI 返回结果
   ↓
Cursor
```

## 三、为什么要把 Cursor 与 CC Switch 搭配使用

在日常开发中，我们常常需要在多个模型供应商之间切换——例如官方 Anthropic、各类中转服务、自建网关等。传统方式下，每次切换都要手动修改各工具的配置文件，繁琐且容易出错。

CC Switch 带来的价值在于：

* **一处配置，处处生效**：在桌面端维护一套供应商配置，Cursor 等工具自动跟随。
* **一键切换，省时省力**：切换供应商通常在 10 秒以内完成，无需重复填写 Key。
* **资源复用，互不迁移**：Claude 额度用尽时可平滑切到 Codex、DeepSeek 等，工程文件无需迁移。
* **配置隔离，互不干扰**：可为不同项目、不同合规要求建立独立配置。

## 四、前置条件

* 在你的机器上已安装 Cursor 和 CC Switch
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`）

## 五、安装 Cursor 和 CC Switch

<Tabs>
  <Tab title="安装 Cursor">
    访问 [https://cursor.com/download](https://cursor.com/download) 下载，支持 macOS 与 Windows。
  </Tab>

  <Tab title="安装 CC Switch">
    参考本平台 [CC Switch 指南](/cn/integrations/cc-switch)。
  </Tab>
</Tabs>

## 六、在 Cursor 中配置 CC Switch

### 第一步：在 CC Switch 中配置供应商

1. 在 CC Switch 里配置好供应商（API Key + Base URL）。
2. 启动 CC Switch，进入 **设置 → 路由**，打开「路由总开关」并勾选需要路由的应用。
3. 确认本地代理已监听，并复制页面下方的「服务地址」（具体端口以软件界面显示为准，例如 `http://127.0.0.1:15721`）。

<Frame>
  <img src="https://mintcdn.com/gravitexai/YCzYS8JUSvjzZQaq/images/cursor1.png?fit=max&auto=format&n=YCzYS8JUSvjzZQaq&q=85&s=fcc803b138f0f45f36c5d69560bc9fa3" alt="CC Switch 本地路由与服务地址" width="2275" height="1280" data-path="images/cursor1.png" />
</Frame>

### 第二步：在 Cursor 中配置

1. 打开 Cursor，按 **Cmd + ,**（macOS）或 **Ctrl + ,**（Windows / Linux）进入 Settings。或者点击左下角的齿轮图标 ⚙️，选择 Models 选项。
2. 左侧导航进入 **Models** 面板。
3. 在 **OpenAI API Key** 字段填写 GravitexAI 密钥。
4. 找到 **OpenAI API** 相关设置区：
   * 打开 **Override OpenAI Base URL** 开关。
   * 填写 CC Switch 提供的本地端点 URL，例如 `http://127.0.0.1:15721/v1`（必须带 `/v1`，不能带末尾斜杠）。

### 第三步：添加模型 ID

1. 在 Models 列表顶部的 **Add or search model** 输入框中填写需要使用的模型 ID。
2. 模型 ID 按 CC Switch 中配置的供应商约定填写，例如 `gemini-3-flash-preview`、`seed-2-1-turbo-260628`、`claude-sonnet-4-6`。

<Frame>
  <img src="https://mintcdn.com/gravitexai/YCzYS8JUSvjzZQaq/images/cursor2.png?fit=max&auto=format&n=YCzYS8JUSvjzZQaq&q=85&s=fa6f0ac7183c14aee806dcaa37f59682" alt="Cursor Models 面板配置 API Key 与 Base URL" width="2704" height="1696" data-path="images/cursor2.png" />
</Frame>

<Warning>
  重要提示：目前 Cursor 官方限制，使用第三方 API Key（包括 GravitexAI）需要满足以下条件：

  * 必须开通 Pro Plan（付费订阅），Free Plan 无法使用第三方 API Key
  * 需要配置科学上网（VPN/代理）才能正常连接第三方 API 服务
</Warning>

## 七、支持的模型

通过 GravitexAI，Cursor 支持 100+ 主流 AI 模型，包括 OpenAI、Google Gemini、Claude、DeepSeek、国产模型等。

<Card title="查看当下热门模型推荐" icon="star" href="https://maas.gravitex.ai/#/api-models">
  查看最新的模型推荐、性能对比和场景化使用建议。覆盖文本创作、编程开发、快速响应、图像生成、视频生成等全场景。
</Card>

<Info>
  **为什么不在此列出具体模型？**

  AI 模型更新迭代速度非常快，为了确保你获取最准确的模型推荐信息，我们统一在 [模型推荐页面](https://maas.gravitex.ai/#/api-models) 维护最新的模型列表、性能数据和使用建议。
</Info>

## 八、常见配置问题

<AccordionGroup>
  <Accordion title="API Key 填写错误">
    如果出现：

    ```text theme={null}
    401 Unauthorized
    ```

    优先检查：

    1. API Key 是否正确
    2. 是否复制了多余的空格
    3. API Key 是否已经失效
    4. 是否误用了其他平台的 API Key
  </Accordion>

  <Accordion title="Model 不存在">
    如果出现类似：

    ```text theme={null}
    Model not found
    ```

    请检查 Model 名称。常见原因：

    * 模型名称拼写错误
    * 当前 Key 没有该模型权限
    * 模型已经下线或变更
    * 使用了其他用户的 Model 名称
  </Accordion>

  <Accordion title="API 可以调用，但 Cursor 无法正常使用">
    这种情况通常需要检查 API 兼容性。

    Cursor 发出的请求需要与 CC Switch 支持的 API 协议匹配。如果请求格式、模型名称或响应结构不符合客户端预期，就可能出现：

    * 请求成功但没有内容
    * 模型无法正常返回
    * Cursor 无法解析响应
    * 对话过程中断

    遇到此类问题，可以先使用 `curl` 或其他 API 工具测试 API 是否能够正常返回。
  </Accordion>

  <Accordion title="Cursor AI 无响应、加载转圈">
    1. 检查 CC Switch 节点是否断开，重新连接低延迟节点；
    2. 确认 `settings.json` 代理配置已保存、端口无误；
    3. 彻底关闭 Cursor 后台重新启动；
    4. 关闭严格 SSL 校验，切换稳定海外节点。
  </Accordion>

  <Accordion title="偶尔模型调用超时">
    排查方案：节点网络波动导致，切换备用节点，或重启 CC Switch 重新连接即可。
  </Accordion>
</AccordionGroup>

<Info>
  **更多帮助**：技术支持联系 [bd@gravitex.ai](mailto:bd@gravitex.ai)，或致电 13603055233。
</Info>