适用边界
Cursor 的自定义 API Key 和 Override OpenAI Base URL 能力会随版本、套餐和功能模式变化。本文只覆盖 Cursor 设置页里实际能看到 OpenAI API Key、Base URL 覆盖和自定义模型入口的版本。若当前版本没有这些入口，说明该版本不适合直接配置 Ling.AI。
先确认模式
公开资料显示，Cursor 的自定义 OpenAI Base URL 通常优先覆盖 Chat、Ask、Plan 等对话路径；Composer、Agent、Inline Edit、Autocomplete、Apply 等能力可能仍走 Cursor 自身后端或受套餐限制。不要用 Ask 成功来推断所有 Agent 功能都已走 Ling.AI。
准备
- API Key
- 登录 Ling.AI 后进入 API Keys 创建密钥。密钥只粘贴到 Cursor 本机设置，不写入项目文件。
- Base URL
- Cursor 的 OpenAI Base URL 覆盖项填写
https://api.lingyuncx.com/v1。不要填写网站首页，也不要填写/v1/chat/completions。 - 模型 ID
- 用
GET https://api.lingyuncx.com/v1/models查询当前账号可用模型，Cursor 里填写返回的id，不要复制外部平台展示名。 - 验证位置
- 发送短 prompt 后，到 用量统计、成本统计 和 钱包核对模型、状态、usage 和扣费。
打开设置
- 打开 Cursor。 进入一个项目或空窗口都可以，先不要启动 Agent 任务。
- 进入 Settings。 点击左下角齿轮，或使用命令面板搜索 Cursor Settings。
- 进入 Models。 在左侧或顶部设置分类中打开 Models，找到 API Keys / OpenAI 区域。
填写 OpenAI 配置
- 填写 API Key。 在 OpenAI API Key 输入框粘贴 Ling.AI API Key。
- 开启 Base URL 覆盖。 打开 Override OpenAI Base URL 或同义开关。
- 填写 Base URL。 输入
https://api.lingyuncx.com/v1，保存或验证。 - 添加模型。 点击 Add Custom Model 或模型列表中的添加入口，模型名填写
/v1/models返回的真实 ID。 - 临时减少干扰。 首次验证时可以只保留一个 Ling.AI 自定义模型，避免请求被默认模型误路由。
- 保存设置。 如果 Cursor 提供 Verify、Check 或 Save 按钮，先执行一次连接检查。
验证
- 打开 Cursor Chat / Ask，选择刚添加的模型。
- 发送短 prompt，例如“用一句话说明这个项目的作用”。
- 确认 Cursor 收到模型回复。
- 回到 Ling.AI 用量统计，核对请求模型 ID、状态、usage、费用和钱包扣减。
- 再按需测试 Plan 或 Agent；如果 Ask 可用但 Agent 不可用，优先判断 Cursor 模式限制，不要先扩大到 Ling.AI 网关排障。
排障
| 现象 | 先检查 | 处理方式 |
|---|---|---|
| 找不到 Override OpenAI Base URL | Cursor 版本和当前账号功能 | 升级 Cursor 或改用 Cline、OpenCode、Codex CLI 等明确支持自定义 provider 的工具。 |
| 401 / 403 | API Key、IP 白名单、模型授权、余额或套餐 | 重新创建 Key，确认当前网络出口允许访问，并用 curl https://api.lingyuncx.com/v1/models 验证。 |
| 404 | Base URL 是否写到 /v1 |
只填 https://api.lingyuncx.com/v1，不要把完整接口路径填进 Base URL。 |
| 模型不存在 | 模型名是否来自 /v1/models |
复制返回的 id，不要使用外部平台展示名或截图里的旧模型名。 |
| Ask 可用但 Agent 不可用 | Cursor Agent 模式、套餐和内部协议限制 | 用 Cline 或 OpenCode 做同一模型的只读验证，区分 Cursor 功能限制和 Ling.AI 接口问题。 |