Cursor 怎么接入 KL API

Cursor 只能走 OpenAI 兼容协议,Base URL 填 agent.kl-api.info/v1,模型 ID 需手动添加。(2026-11-22)

适用系统:Windows / macOS / Linux · 更新于

准备工作

  • 已安装 Cursor,并且版本里有 Override OpenAI Base URL 这一项
  • 一个 KL API 的 API Key(在控制台创建)
  • 知道要用的模型 ID,见 [模型清单](/models)

配置项对照

Cursor 只认 OpenAI 兼容这一条路,先对上五个值:

配置项 应填值
Override OpenAI Base URL https://agent.kl-api.info/v1(必须带 /v1)
OpenAI API Key 你的 KL API Key
模型 ID gpt-5、claude-sonnet-4-6,或 模型清单 里其他 ID
请求路径 Cursor 会自动拼成 /v1/chat/completions(Chat)与 /v1/responses(Agent)
Anthropic 栏 留空,不要填——那一栏没有 Base URL 覆盖,填了也走官方地址

注意

Anthropic 栏的 Key 输入框看起来能用,实际上没有配套的 Base URL 覆盖开关。在那里填 KL API 的 Key,请求仍然发往官方 api.anthropic.com,只会得到 401,不要在这个方向上排查。

在 Cursor 里填什么

全在图形界面里,没有配置文件可改。顺序别乱:

  1. 打开 Cursor Settings → Models(快捷键 Windows/Linux 是 Ctrl+Shift+J,macOS 是 Cmd+Shift+J)。
  2. 在 API Keys 区域,找到 OpenAI API Key,粘贴你的 Key,点 Save。
  3. 打开 Override OpenAI Base URL,填 https://agent.kl-api.info/v1。
  4. 点 + Add Custom Model,输入模型 ID,把右侧开关打开。
  5. 回到对话窗口,在模型下拉里选中刚加的模型。

提示

如果你的版本里找不到 Override OpenAI Base URL,说明这个版本或套餐不支持把 OpenAI 兼容请求转到自定义端点,换最新版再试。找不到这一项时,填 Key 也不会生效。

先验证端点

填进 Cursor 之前,先确认这个地址真的是 API 端点。用一个假的 Key 打一次模型列表就够了:

Windows PowerShell
curl.exe https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"
macOS / Linux
curl https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"

判断标准只有一条:返回 JSON 格式的鉴权错误,说明端点真实存在。

json
{"error":{"message":"Invalid token (request id: 202611220119522926930721cafreY3)","type":"new_api_error"}}

如果返回的是一段 HTML(网站首页或错误页),说明这个路径没有实现 OpenAI 兼容接口,填进 Cursor 也用不了。

注意

同一条命令别连着重跑。同一出口 IP 在窗口内累计 6 次用错 Key 会进 120 秒黑名单(前面的零散失败也会计入,所以有时第 2 次就中),之后连正确的 Key 也会收到 You have used invalid tokens multiple times, please wait 120 seconds before trying again。这个限制按出口 IP 记,不按 Key 记,所以同一个办公室共用一条出口 IP 时,同事填错 Key 也可能连累你。而且封禁期内每重试一次都会续期,越试等得越久——看到这句就停手核对 Key,等满 120 秒再试,不要以为是 Key 或额度的问题。

哪些功能会走你的 Key

Cursor 不是「全部走同一个 API」的工具,这一点最容易误判:

功能 走自定义端点 说明
Chat(侧边对话) 走 按你填的地址和 Key
Agent / Composer(多文件改代码) 走 要求模型支持工具调用
Tab 补全(行内灰字) 不走 Cursor 自家模型,不读自定义端点
代码库索引 / embedding 不走 由 Cursor 服务端处理

所以「填了 Key,Tab 补全还在扣 Cursor 额度」是正常现象,不是配置失败。

关于模型 ID

模型 ID 必须和 模型清单 里的写法一字不差,包括连字符和版本后缀,claude-sonnet-4-6 不能写成 claude-sonnet-4.6。

Cursor 的校验只看 Key 和端点连通性,不校验模型是否存在,所以 Verify 通过不代表模型名对。名字错了要到真正发请求时才报错。

还有一个已知冲突:如果要加的模型 ID 和 Cursor 内置模型同名,会提示 The model "..." is already available as "...",加不进去。这种情况下从 模型清单 里换一个我们提供的等价 ID 使用。

提示

Cursor 的请求是从它自己的服务器发出的,不是从你本机直连。所以端点必须公网可达——agent.kl-api.info 是公网域名,127.0.0.1 或内网地址在这里填了不会通。

验证

在 Chat 里问一句「这个文件是做什么的」,能正常返回就通了。再做一个最小编码任务确认工具调用也正常,比如:

text
把 src/hello.ts 里输出的字符串改成 OK,只改这一处

然后去看文件真的变了没有。Agent 模式下最典型的失败是「只在对话里告诉你改了什么,文件没动」,那是端点不支持工具调用,不是配置错。

要在 Cursor 之外单独验证同一个 Key,用 快速开始 里那段 curl,地址和 Key 用同一份。curl 能返回、Cursor 不能,问题就在 Cursor 这一侧的配置,不在 Key 或额度。

一个必须知道的副作用

Override OpenAI Base URL 是全局开关,不是按模型生效。

打开之后,所有 OpenAI 系请求都会发到 https://agent.kl-api.info/v1,包括你从 Cursor 内置列表里选的模型。想同时保留 Cursor 自带模型和 KL API,只能在两者之间切换:

想用 操作
KL API 的模型 打开 Override,选你加的自定义模型
Cursor 自带模型 关掉 Override,选内置模型

切完重开一次对话,避免旧会话沿用之前的连接。

验证状态

项目 状态
/v1/models、/v1/chat/completions、/v1/responses、/v1/messages 四个端点存在,错误 Key 返回 JSON 401 已实测(2026-11-22,原文 Invalid token)
连续错误 Key 触发 120 秒限制,且按出口 IP 记:封禁期间换一把从未用过的全新错 Key 仍返回 429 已实测(2026-11-22)
限流检查在鉴权之前:封禁期间连不带 Authorization 头的请求也返回同一条 429;解封后不带 Key 则回到 401 lab token denied 已实测(2026-11-22)
Cursor 只有 OpenAI 栏有 Base URL 覆盖,Anthropic 栏没有 官方论坛功能请求帖,2026-10 仍未有该功能
Override 打开后内置模型也走自定义端点 Cursor 官方员工在论坛确认(2026-08-21)
与内置模型同名的 ID 无法添加为自定义模型 论坛复现记录(2026-10-29)
Tab 补全、索引不走自定义端点 多方一致,未在本机复现
真 Key 在 Cursor 客户端端到端跑通 未验证

未验证项会在真机跑通后更新本表,不提前标成「已验证」。

参考来源(核对于 2026-11-22)

常见问题

Cursor 填了 Override OpenAI Base URL 还是报 404 或模型不存在?

先看地址结尾:这条要填 OpenAI SDK 的 base 地址,必须带 /v1,即 https://agent.kl-api.info/v1,既不能只填域名,也不能填到 /v1/chat/completions 那一层。再看模型 ID 是否和 模型清单 一字不差。最后用一个错误 Key 跑一遍本文的 curl:返回 JSON 鉴权错误才算端点真实存在,返回 HTML 页面说明地址错了。

Cursor 里能给 Claude 单独填自己的 Base URL 吗?

目前不能。Cursor 只有 OpenAI 栏有 Base URL 覆盖开关,Anthropic 栏只有 Key 输入框,填了也照样打到官方 api.anthropic.com。想用 claude-sonnet-4-6 走 KL API,只能在上面的 OpenAI 兼容配置里,把模型 ID 手动加成自定义模型。

开了 Override 之后 Cursor 自带的模型都用不了了?

是预期行为。这个开关是全局的:打开后所有 OpenAI 系请求都发到你的端点,包括从内置列表里选的那些。要同时保留 Cursor 自带模型,只能在两者之间来回切换开关,切换后重开一次对话。

Cursor 的 Tab 补全为什么还在消耗 Cursor 的额度?

Tab 补全和代码库索引用的是 Cursor 自己的模型,不读你填的端点,这一点改不了。自定义 Key 只作用于 Chat、Agent 和多文件编辑,账单要分开看。

在 Cursor 里点 Verify 一直不通过,后来网关返回 429 了?

连续用错误 Key 重试会触发网关的临时限制,原文是 You have used invalid tokens multiple times, please wait 120 seconds before trying again。看到这个先停手等两分钟,把 Key 复制完整再试,别继续连点 Verify。