OpenRouter 接入 Cursor 的配置方法与生效验证

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

这件事的关键只有一句话：Base URL 必须填 OpenRouter 的专用 Cursor 端点 https://openrouter.ai/api/v1/cursor，而不是平时那个 https://openrouter.ai/api/v1。 官方文档在这里专门加了一个警告框，理由是这个专用端点会把 Cursor 的请求格式先归一化成标准的 OpenAI Chat Completions 格式再往下路由；填成通用的 /api/v1，官方原话是工具调用和某些请求格式可能不能正确工作。配置本身只有四步——拿 key、在 Cursor 的 Models 设置里打开 OpenAI API Key 并覆盖 Base URL、手动把要用的模型 ID 加进去、在模型选择器里选中它。配完之后别急着相信它生效了：Cursor 有几个功能官方明确说不受 BYOK 设置影响，真正的验证要去 OpenRouter 那边看有没有对应的记录。另外，官方给这条集成路径标了 Beta，并写明「行为可能随 Cursor 客户端更新而变化」，所以下面每一步都以你打开文档时的官方版本为准。

这条路径到底是怎么接上的

Cursor 是一个基于 VS Code 的 AI 代码编辑器，官方对它的描述里提到 agent 模式、tab 补全、行内编辑、CLI 和云端 agent，并且它自己也有自研模型，同时接了几家前沿厂商的模型。按官方的说法，Cursor 是通过它的 Override OpenAI Base URL 功能来支持 OpenRouter 的——你把 OpenAI provider 的 key 和 base URL 一起换掉，请求就从 Cursor 的 OpenAI 通道流向了你指定的地址。

OpenRouter 这边的做法是单独开了一个 /api/v1/cursor 端点来接这股流量。官方在「How It Works」一节只写了一句：这个专用端点把 Cursor 的请求格式归一化成标准 OpenAI Chat Completions 格式，然后再路由。这句话解释了后面所有的坑——为什么不能用通用端点、为什么工具调用出问题第一件事是回去看 base URL 有没有带 /cursor。官方在排查一节里把这层说得更直白：专用端点处理的是 Cursor 的扁平工具格式（flat tool format），通用的 /v1 端点不处理。

至于为什么要绕这一圈，官方给的理由是三条：Cursor 自带的 BYOK 只支持少数几家供应商，走 OpenRouter 之后可以用一个 key 访问数量大得多的模型；某家供应商不可用或被限流时会自动路由到另一家；以及用量集中可见——团队场景下可以在 Activity 面板里按模型、按人、按成本看使用情况，并做统一的预算管理与额度分配。这些都是官方陈述的能力，不是我替它总结的效果。

四步配置，逐步说清每一步在改什么

第一步是拿 key。 在 OpenRouter 注册或登录后进 API Keys 页面新建一个 key，官方提示这个 key 以 sk-or- 开头。这一点后面排查时有用：Cursor 里如果报「Invalid API key」，官方给的第一个检查项就是确认你粘进去的是 OpenRouter 的 key（sk-or- 开头），不是 OpenAI 的 key。两者都填在同一个叫「OpenAI API Key」的框里，肉眼很容易混。

第二步是改 Cursor 的设置。 官方给的路径是：打开 Cursor Settings（齿轮图标或 Cmd/Ctrl + ,），进 Models，展开 API Keys 这一节，把 OpenAI API Key 打开，粘贴你的 OpenRouter key；然后把 Override OpenAI Base URL 也打开（官方要求这两个开关都要打开），填上面那个带 /cursor 的地址。注意这是两个独立的开关，只填 key 不覆盖 base URL，请求还是发往 OpenAI。

第三步是手动加模型。 官方写的是连上之后要自己把想用的模型加进来——在 Models 一节点 + Add model，填 OpenRouter 的模型 ID。这一步经常被跳过，因为直觉上会以为换了 base URL 模型列表就自动变了。文档里给的示例写法之一是 ~anthropic/claude-opus-latest 这种带波浪号的别名。

第四步是在聊天或 agent 面板的模型选择器里选中你加的那个模型，官方说到这里请求就会经由 OpenRouter 路由。

模型 ID 写错是最高频的一类失败

官方排查一节里「Model not found」的处置写得很具体：模型 ID 必须和 OpenRouter 模型页上的格式完全一致；并且路由器别名需要带 ~ 前缀——文档举的反例就是要写 ~anthropic/claude-sonnet-latest，而不是 anthropic/claude-sonnet-latest。

这个 ~ 不是装饰。OpenRouter 有一套「最新模型解析」机制：~author/family-latest 形式的 slug 永远解析到该系列当前最新的那个具体模型，作者发布新版本之后，同一个别名会自动指向新版本，旧代码不用改。官方给这套机制列的适用场景是产品团队想始终用某家最新旗舰、内部工具与原型、以及想把版本钉死的时间点往后推的滚动迁移。反过来说，如果你要的是可复现——比如做评测——就该填具体版本的 slug，而具体版本的 slug 是不带 ~ 的。Cursor 文档里给的示例同时出现了带 ~ 的别名和不带 ~ 的具体模型 slug，这不是笔误，是两类不同的东西。

模型 ID 后面还可以挂路由后缀。官方在 Cursor 这篇末尾指向了 Provider Routing 文档，提到 :nitro 和 :floor 这类后缀。它们的定义在路由文档里：:nitro 把该模型的所有端点按吞吐排序，并让优先级服务层的端点进入这个排序；:floor 按价格排序，并让 flex 服务层端点可参与。要注意官方补的那句限制——这两个变体的服务层准入依赖于「排序」这个动作本身，所以一旦你设了 provider.order（它用你的显式顺序取代排序），变体的服务层准入就失效了。具体价格一律以官方定价页为准，本文不列数字。

生效验证：别靠「感觉它换了」

配完之后最该做的是回 OpenRouter 侧找证据，而不是看编辑器里回答的风格变了没有。官方文档里可用的验证入口有这么几个：

Activity 页。 官方说这里能看到按模型、按用户、按成本拆分的用量明细，无论底层是哪家供应商。你在 Cursor 里发一轮对话，回来看这条记录在不在、模型对不对，是最直接的确认方式。

GET /api/v1/key。 这个接口返回当前 key 的信息，响应结构官方列了字段：label、limit（该 key 的额度上限，无限制时为 null）、limit_reset（重置类型，永不重置时为 null）、limit_remaining（剩余额度），以及 usage（全部历史用量）、usage_daily、usage_weekly、usage_monthly 这几个按 UTC 日/周/月切分的累计值——官方注明周是从周一开始算。还有 is_free_tier 表示该用户此前是否付过费，以及 include_byok_in_limit 表示外部 BYOK 用量是否计入额度限制。用 Cursor 跑一轮之后再调一次这个接口，看当日累计值有没有动，是不带界面也能做的验证。

/api/v1/generation。 每次生成返回的 id 可以用来事后查这次生成的统计，包括 token 数与成本。官方说明这个接口适合审计历史用量或异步取数。另外非流式响应体里本来就带 usage 字段。

顺带一个细节：用 ~...-latest 别名时，响应里的 model 字段会写明这次实际服务的具体版本。这意味着你不用猜别名今天解析到了哪一版，查一下生成记录就知道。

更多入口和它们口径为什么会对不上，可以看余额和用量怎么查的四个入口。

官方明说不会走你 key 的那几处

这一节是最容易产生误会的地方，官方在「Limitations」里列了三条：

• Tab 补全不受 BYOK 设置影响，它始终使用 Cursor 自带的模型。这是「always」，没有余地。
• Auto 与 Composer 2 模式可能不会经由你的 API key 路由。官方用的是 may not，并让读者去查 Cursor 自己的文档看当前行为——也就是说这条的最终解释权在 Cursor 那边，会变。
• 只有通过 OpenRouter 的 OpenAI 兼容端点可访问的模型才能用，官方补充说大多数聊天与推理类模型是支持的。

把这三条摆在一起就能明白：账单和 Activity 里看不到某类操作的记录，未必是你配错了，有可能它本来就不走这条路。判断的顺序应该是先看这个功能在不在上面三条里，再去怀疑配置。

报错对照：官方给的四条排查线

官方 Troubleshooting 一节给了四条，我按它原本的意思复述：

1. Invalid API key——确认用的是 OpenRouter 的 key（sk-or- 开头），不是 OpenAI 的 key。
2. Model not found——确认模型 ID 与 OpenRouter 模型页上的格式完全一致；别名要带 ~ 前缀。
3. Base URL——覆盖用的 URL 必须是 https://openrouter.ai/api/v1/cursor；如果你用的是不带 /cursor 的 https://openrouter.ai/api/v1，工具调用和某些请求格式可能不能正确工作。
4. 工具调用报错——看到意料之外的工具调用失败，先回去确认是不是指向了 /cursor 端点，因为扁平工具格式只有专用端点处理。

第 1 条如果确认 key 没错还是过不去，就不是 Cursor 的问题了，按 OpenRouter 自己的鉴权错误处置走，参见 401 鉴权失败的排查顺序。

花钱这块，你要盯的是哪几个开关

请求经由你的 key 之后，费用就落在你的 OpenRouter 账户上，规则和你直接调 API 时是同一套。有两处限制会导致请求被拒：一是账户余额，二是单个 API key 上可选配置的消费上限——后者对应的就是上面那三个字段 limit / limit_reset / limit_remaining。官方给的处置顺序是：先充值把余额补到零以上；再看 key 的 limit_remaining 是不是已经耗尽，必要时提高该 key 的上限或等它按 limit_reset 重置；平时则主动调 GET /api/v1/key 提前监控，别等到请求开始失败才发现。

还有一条容易被忽略：官方写明账户余额为负时可能会看到报错，而且这种失败包括免费模型在内——把余额补到零以上就能恢复使用。给编辑器配 key 的场景下这条尤其值得记住，因为你不会盯着终端看返回。

团队场景下，OpenRouter 侧提供的是集中式预算管理：设置消费上限、分配额度、在 Activity 面板监控开发者的用量。具体价格与费率一律看官方定价页，这里只说机制。接入的基础配置与 OpenAI 兼容写法可以看 OpenRouter API 怎么接入；把 key 交给一个桌面客户端之前，API Key 怎么管才不泄漏里那几条也适用。

最后：最容易栽的两个地方

第一个是 base URL 少了 /cursor。官方对这种情况的说法是：用不带 /cursor 的地址时，工具调用和某些请求格式可能无法正常工作。官方没有说明其他类型的请求会怎样，所以别假设「只是工具调用受影响」。所以配完先确认这一栏，比事后排查省事得多。

第二个是把「没记录」等同于「没配好」。Tab 补全官方说了始终用 Cursor 自带模型，Auto 与 Composer 2 官方说了可能不走你的 key，这两处产生不了 OpenRouter 侧的记录是符合文档描述的行为。真正该拿来验证的是你在聊天或 agent 面板里手动选中某个 OpenRouter 模型之后的那次请求。

再提醒一次：这条集成官方标注为 Beta，并说明行为可能随 Cursor 客户端更新而变化。上面每一处配置项名称、端点地址和限制条款，都以你操作当天的官方文档为准。