Cursor
Cursor 支持为标准聊天模型配置自定义 API Key、OpenAI base URL 覆盖值和自定义模型名称。配置这些设置后，可通过 AISIX 发送 Cursor Ask 模式的请求。
本指南将使用 AISIX 调用方 API Key 配置 Cursor，并将 AISIX 模型别名用作自定义模型名称。随后，AISIX 会认证调用方、应用网关策略，并将请求转发到为该别名配置的上游模型。
此配置适用于 Ask 模式。Agent 模式、嵌套智能体、后台智能体、Tab Completion、行内编辑以及其他使用 Cursor 专用模型的功能会使用 Cursor 管理的路径，而不是 AISIX base URL。要通过 AISIX 路由 Agent 模式的 MCP 工具调用，请参阅将 Cursor 连接到 MCP 网关。
准备工作
开始前，请准备以下内容：
- Cursor Pro 或更高套餐。免费套餐可以保存 API Key、base URL 和自定义模型，但必须升级后才能在 Chat 中选择自定义模型。
- 已运行且 Cursor 可以访问其代理 URL 的 AISIX 网关。
- AISIX 调用方 API Key。
- 调用方 API Key 可通过 兼容 OpenAI 的 API访问的模型别名。
如果你的组织已经部署 AISIX，请向管理团队获取网关 URL、模型别名和调用方 API Key。否则，请按照开源 AISIX 网关快速上手或 AISIX Cloud 快速上手完成部署，也可以联系 API7申请 Hybrid Cloud 访问权限。
设置网关源地址和调用方 API Key，然后在配置 Cursor 前确认 AISIX 已公开该别名：
# AISIX_PROXY 不含末尾斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
curl -sS "${AISIX_PROXY}/v1/models" \
-H "Authorization: Bearer ${AISIX_API_KEY}"
配置 Cursor
-
打开 Cursor Settings，选择 Models。
-
在 OpenAI API Key 字段中输入 AISIX 调用方 API Key。
-
在 Override OpenAI Base URL 中输入 AISIX 代理 API 根路径，并包含
/v1。例如：YOUR_AISIX_GATEWAY_URL/v1 -
在 Add or search model 中输入 AISIX 模型别名并按 Enter。例如，输入
aisix_cursor。 -
启用该自定义模型。
-
打开 Cursor Chat，选择 Ask 模式，然后选择该自定义模型。
请使用既不包含服务提供方模型 ID、也不与其相似的中性模型别名。例如，使用 aisix_cursor，而不是 gpt-4o-prod。否则 Cursor 可能会将别名解释为内置模型，并以不同方式路由或格式化请求。Cursor 发送的自定义模型名称必须与 AISIX 模型别名一致，而不是上游服务提供方的模型名称。
Cursor 设置与 AISIX 的映射如下：
| Cursor 设置 | AISIX 值 |
|---|---|
| OpenAI API Key | AISIX 调用方 API Key |
| Override OpenAI Base URL | 包含 /v1 的 AISIX 代理 URL |
| Custom model | AISIX 模型别名 |
验证集成
在 macOS 上使用 Cmd+L，或在 Windows 和 Linux 上使用 Ctrl+L 打开 Ask 模式。选择自定义模型，然后发送一条简短提示词，例如让模型返回一个指定单 词或短语。
请求成功后，请验证以下结果：
- Cursor Chat 显示预期响应。
- AISIX 记录成功的
POST /v1/chat/completions请求。 - AISIX 请求记录标识预期的调用方 API Key 和模型别名。
AISIX 会将别名解析为已配置的上游服务提供方和模型。Cursor 不需要上游服务提供方凭证或上游模型名称。
排查 Cursor 请求问题
如果请求失败，请检查以下事项：
| 现象 | 检查项 |
|---|---|
| 打开模型选择器时 Cursor 提示升级 | 确认正在使用 Cursor Pro 或更高套餐。免费套餐可以保存配置，但不能选择自定义模型。 |
| 认证失败 | 确认 OpenAI API Key 中的值是 AISIX 调用方 API Key，而不是上游服务提供方 Key。 |
| 找不到模型 | 确认自定义模型名称与调用方可用的 AISIX 模型别名完全一致。 |
| Cursor 报告连接或端点错误 | 确认 Cursor 可以访问 base URL，该 URL 在环境要求时使用 HTTPS，并以 /v1 结尾。 |
| 请求使用了非预期模型或负载 | 使用不包含服务提供方模型 ID 的中性别名，然后在 Ask 模式中明确选择该别名。 |
| 内置模型返回错误 | 切回内置模型时清除 Override OpenAI Base URL。该覆盖值全局应用于兼容 OpenAI 的请求。 |
| AISIX 日志中没有请求 | 确认已配置 Override OpenAI Base URL，并在 Ask 模式中选择了自定义模型。Agent 模式、Tab Completion 和其 他专用功能不使用此路径。 |
后续步骤
- 兼容 OpenAI 的 API：查看面向网关的请求格式。
- 指标与用量事件：查看网关指标和每次尝试的用量事件。
- API Key 与模型限流：为 Cursor 聊天流量添加调用方或模型限流。
- Cursor API Keys：查看哪些 Cursor 模型和功能支持自定义 API Key。