在 Cursor 里用 OpenRouter：cookbook 那一页没说的前置

2026-08-18

接入类文档最容易骗人的地方在于：步骤越少越像很简单，而让人卡住的东西全被挪到了步骤之外。OpenRouter 官方 cookbook 的 Cursor 那一页正是这样——正文只有四步，但「为什么 base URL 后面要多一段」「为什么模型 ID 前面有个波浪号」「为什么改了 key 补全还是老样子」这三类问题，答案分散在这一页的 Warning、Limitations、Troubleshooting 里，还有一部分在 Cursor 自己的文档里，而两边并不完全对得上。

这篇不重复讲 Cursor 侧的自定义模型配置（站内另有一篇专门讲：Cursor 接入 DeepSeek 等国产模型配置教程，自定义模型、Base URL、Verify 那一串步骤都在那边），只做一件事：把 OpenRouter 官方文档《Cursor》页和 Cursor 官方文档《Bring your own API key》页写明的机制放在一起对照，指出口径不重合的位置。两家都是闭源商业产品，我们没有装过、跑过，下面每一条都只是复述两边文档的白纸黑字。

先看清楚这是 beta

OpenRouter 官方文档在这一页开头就有一个 Note 标着 Beta，原话是这个集成目前处于 beta，行为可能随 Cursor 更新客户端而变化。

这句话的分量比看上去大：下面所有步骤里的字段名、菜单名、端点行为，都可能在 Cursor 的某次客户端更新之后对不上，而 OpenRouter 这边未必同步改文档。所以这篇里的每一条都只是「2026-08-18 那天官方文档的口径」，动手时以官方文档最新内容为准。

OpenRouter 侧写明的接法

OpenRouter 官方文档写明，Cursor 通过它的 Override OpenAI Base URL 能力支持 OpenRouter，请求会从 Cursor 的 OpenAI provider 覆盖走到 OpenRouter 一个专门的端点。文档写明的步骤是：

在 OpenRouter 的 API Keys 页面创建一个 key，文档写明 key 以 sk-or-... 开头；
打开 Cursor Settings（官方文档写明是齿轮图标或 Cmd/Ctrl + ,），进入 Models，展开 API Keys 小节；
打开 OpenAI API Key 开关，把 OpenRouter 的 key 粘进 OpenAI API Key 输入框；
打开 Override OpenAI Base URL 开关，填入：
```
https://openrouter.ai/api/v1/cursor
```
在 Models 小节里点 + Add model，填入 OpenRouter 的 model ID；
在聊天或 agent 面板的模型选择器里选中刚加的模型。

这里的菜单名与按钮名都是官方文档写明的原文，不是我们看到的界面。

第 4 步是整页唯一带 Warning 的地方：官方文档写明 base URL 必须是 https://openrouter.ai/api/v1/cursor，不能是 /api/v1。文档自述这个专用端点会先把 Cursor 的请求格式规范成标准的 OpenAI Chat Completions 格式，再去做路由。

填错会怎样，文档在 Troubleshooting 里给了很具体的因果：指向不带 /cursor 的通用 /v1 端点时，tool call 和某些请求格式可能不正常；专用端点处理的是 Cursor 的扁平 tool 格式，通用 /v1 端点不处理。「模型能聊天但一调工具就出错」这个现象，官方文档已经把它绑定到 base URL 少了一段。 这句在 Troubleshooting 的最后一条，很容易被跳过。

口径差异一：Cursor 自己的文档里没有 base URL 这一步

Cursor 官方文档《Bring your own API key》页写明的加 key 流程是：打开 Cursor Settings > Models，找到你要用的提供方，把 key 粘进输入框，点 Save。这一页是按提供方分节写的，OpenAI 是其中一节（具体支持哪几家随平台变动，这里不列清单），并写明自定义 key 只对 chat 模型生效。

这一页从头到尾没有提到 base URL 覆盖。 先翻 Cursor 的 BYOK 帮助页是找不到 OpenRouter 接法的——它只说「粘 key、保存」，而 OpenRouter 的接法额外依赖一个这一页没写的开关；反过来 OpenRouter 那一页的 Resources 小节又把 Cursor BYOK Help 列为参考。两边互相指，覆盖范围却不一样。

实际影响：出问题时别拿 Cursor 的 BYOK 页去核对步骤，那一页描述的是「原生填某家提供方的 key」，和「借 OpenAI 这一格转出去」不是同一件事。步骤口径以 OpenRouter 那一页为准，它是唯一写了 base URL 的一方。

口径差异二：模型 ID 的波浪号前缀

OpenRouter 文档在 Troubleshooting 里写明，如果提示 model not found，要确认 model ID 与 openrouter.ai/models 上的格式逐字一致，并且router 的模型别名需要 ~ 前缀，文档给的反例是要写 ~anthropic/claude-sonnet-latest 而不是 anthropic/claude-sonnet-latest。

这个前缀不是装饰。OpenRouter 官方文档《Latest Resolution》页写明了 ~author/family-latest 这类 slug 的语义：它总是解析到某个模型家族里最新的那个具体模型，作者发布新版本后，别名会自动指向新版本，调用方不用改代码。文档写明的解析过程里，~ 前缀就是识别位——平台先看到 ~ 才知道这是个别名而不是具体 slug。

这一页还写明了两件与 Cursor 用户直接相关的事：

响应的 model 字段会报告真正服务这次请求的那个具体模型，也可以在 activity log 里查到上一次请求解析到了哪个 slug；
版本随时可能变。Limitations 里明说，新模型被推为 latest 之后后续请求就解析到它；别名没有「回退到上一个」的机制，要固定版本只能写具体 slug。文档还写明别名不会解析到另一个别名，也不会解析到已隐藏的模型。

还有一条容易忽略的兼容契约：文档写明如果别名指向的新模型强制要求 reasoning，reasoning: { effort: "none" } 会被上调到该模型支持的最低档，reasoning: { enabled: false } 会被翻成启用；而这套重映射只对 ~latest 生效，具体 slug 仍然严格校验，对强制 reasoning 的模型发 effort: "none" 会返回 400。

放到 Cursor 的场景里，你在 + Add model 里填 ~anthropic/claude-opus-latest 这种别名，和填 deepseek/deepseek-v4-flash 这种具体 slug，行为契约不一样：前者会随平台改目标、参数会被重映射，后者严格但需要你自己跟版本。（这两个值都是官方文档当时的示例，平台上有哪些模型随时在变，不要当清单用。）

至于「在 Cursor 的模型 ID 框里能不能直接加 :nitro、:floor 这类路由后缀」——OpenRouter 那一页只在讲用量可见性时提了一句这些后缀的存在，并让你去看 Provider Routing 文档，没有写明这个输入框接不接受带后缀的 slug。官方文档没有说明这一点，我们不猜。后缀本身的语义倒是清楚：:nitro 等价于把 provider.sort 设成 "throughput"，:floor 等价于设成 "price"。

口径差异三：哪些功能根本不走你的 key

这块两边一半重合、一半是空的。

重合的部分是 tab 补全。OpenRouter 文档写明 tab completions 不受 BYOK 设置影响，始终用 Cursor 内置模型；Cursor 文档写明自定义 key 只对 chat 模型生效，tab 补全继续用内置模型。两边说的是同一件事，可以放心当结论用——接了 OpenRouter，补全那一路不会有变化，看不到变化不代表你配错了。

空的部分是 Auto 与 Composer 2。OpenRouter 文档在 Limitations 里写这两种模式「可能不会走你的 API key」，并让你去 Cursor 的文档确认当前行为；而 Cursor 这份 BYOK 页并没有对它们是否走自带 key 给出说明。OpenRouter 把问题指给了 Cursor，Cursor 这一页没接住。这一点我们在 Cursor 的文档里没有找到对应说明，不比，也不猜。 实际影响是：若你的目的是「所有请求都走我自己的账」，Auto 这类模式是个说不清的口子。

还有一条边界：OpenRouter 文档写明只有通过它的 OpenAI 兼容端点可访问的模型才能用，并自述大多数 chat 与 reasoning 模型受支持。这句自带「大多数」的限定，别读成全量。

口径差异四：key 和数据走了哪条路

Cursor 官方文档写明：你的 API key 不存在他们的服务器上，但每次请求都会随请求发到他们的后端，因为所有请求都经由 Cursor 的服务器做最终的 prompt 组装；key 通过加密连接传输，请求完成后不做持久化。

同一页还写明了更硬的一条：Cursor 的 Zero Data Retention 政策在使用自带 API key 时不适用，数据处理遵循你所选提供方的隐私政策；如果团队依赖 ZDR，文档建议改用 Cursor 内置模型。

OpenRouter 那一页对这两件事都没有提。所以图景要你自己拼：走这条路之后，OpenRouter 的 key 会经过 Cursor 后端，而 Cursor 的 ZDR 承诺按其文档口径不覆盖这条路径。至于经过 OpenRouter 之后上游怎么留存，是另一套机制，不在这两页的范围内，不展开也不推断。这一段涉及密钥与数据处理，请结合自身合规要求评估。

决策路径

把上面几条倒过来用，从处境走到结论：

要「团队所有 AI 编码请求集中记账、集中控预算」：OpenRouter 文档自述它提供集中的预算管理（设置支出上限、分配额度、跨开发者监控用量）与按模型/用户/成本拆分的用量视图。这条路径成立，但得接受两个已知缺口：tab 补全一定不走你的 key（两边文档一致），Auto 与 Composer 2 是否走没有定论。所以「全部集中」这个目标，按官方文档现在的口径达不到。
要用 Cursor 自带 BYOK 之外的模型：OpenRouter 文档自述 Cursor 自带的 BYOK 只支持少数几家提供方，走 OpenAI provider 覆盖这一格可以接到更多模型。这是这套接法最直接的收益，前提是那个模型在 OpenRouter 的 OpenAI 兼容端点上可用。
团队依赖 ZDR：Cursor 文档已经把话说死了——自带 key 时 ZDR 不适用，并建议改用内置模型。这种情况下不必往下折腾接入步骤，先解决合规口径。
要可复现的固定模型版本：别用 ~...-latest 别名，直接填具体 slug；别名的语义就是会跟着平台走。
只是想让补全变快：这条路不解决这个问题，两边文档都写明补全用的是 Cursor 内置模型。

排障时按这张表对

下面每一行都来自 OpenRouter 官方文档的 Troubleshooting 小节：

现象	官方文档给出的检查点
提示 Invalid API key	确认填的是 OpenRouter 的 key（`sk-or-...` 开头），不是 OpenAI 的 key
提示 model not found	model ID 要与 openrouter.ai/models 上的格式逐字一致；router 别名要带 `~` 前缀
tool call 莫名失败	确认 base URL 指的是 `/cursor` 端点；专用端点处理 Cursor 的扁平 tool 格式，通用 `/v1` 不处理
请求格式相关的杂症	覆盖用的 URL 必须是 `https://openrouter.ai/api/v1/cursor`，用 `https://openrouter.ai/api/v1` 会出问题

顺序上建议先核 base URL，再核 model ID，最后才怀疑 key——前两个的现象更具体（tool 失败 / model not found），而 key 的问题会给出明确的 Invalid API key。

Windows 与 macOS 的差别

几乎没有，而这本身值得说一句。OpenRouter 这一页写明的全部步骤都在 Cursor 的设置里完成，官方文档没有给出任何命令行写法或配置文件路径，所以不存在 Windows 与 Linux/macOS 的路径分隔符、环境变量写法之类的差异。唯一带平台字样的是文档写明的那个快捷键 Cmd/Ctrl + ,，Windows 侧对应 Ctrl。如果你在别处看到「改某个 JSON 配置文件就能接 OpenRouter」的写法，那不是这一页的内容，我们无法从这两份文档里核到。

我们没有依据、因此不比的部分

走 OpenRouter 之后的实际延迟、成功率、生成质量——两边文档都没有可核的依据，我们也没有跑过，不比；
/api/v1/cursor 内部怎么做格式规范化——文档只写了「会规范成 OpenAI Chat Completions 格式」，再往下是实现，闭源，不推断；
Auto 与 Composer 2 的当前实际行为——如上，两边都没有定论；
Cursor 端会不会把 OpenRouter 响应里的 model 字段展示出来——这一点我们在 Cursor 的文档里没有找到对应说明。

回到开头那个 Beta 标记：这整套接法目前是 beta，OpenRouter 文档自己写了行为可能随 Cursor 客户端更新而变化。把这篇当成一张「该去文档哪一段找答案」的地图就好，具体值以官方文档最新内容为准。

本文依据 OpenRouter 官方文档（openrouter.ai/docs）于 2026-08-18 的公开内容整理。该平台闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观与运行表现的任何描述。该平台的供应商、模型与路由策略随时变动，文中不列具体供应商名单与模型清单；价格、额度与限流的具体数值请以官方定价页与用量说明为准。

本文涉及的另一方内容依据其官方文档整理（Cursor：cursor.com/docs 与 cursor.com/help）。双方均为闭源商业产品，本文只对照各方公开写明的机制，不推断实现，也不对产品做优劣排名。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。合规与许可条款请以官方原文与你所在组织的要求为准，本文不构成法律意见。