Tool Integrations2026年7月8日Flatkey

Cursor OpenAI 兼容 API 设置：基础 URL、模型名称和使用日志

谨慎设置 Cursor OpenAI 兼容 API 路径：在路由流量前，请验证基础 URL 支持、模型名称、使用日志、BYOK 策略和回滚。

如果您只考虑三个字段：API 密钥、基础 URL 和模型名称，那么 Cursor OpenAI 兼容 API 的设置看起来很简单。实际上，Cursor 是一个更高级别的编码工具，拥有自己的模型选择器、使用情况核算、团队控制和提示构建路径，因此更安全的设置是验证工作流，而不是盲目地复制粘贴。

截至 2026 年 7 月 8 日查阅的当前公开 Cursor API 密钥文档，Cursor 在“Cursor 设置 > 模型”中为指定提供商记录了“自带 API 密钥”（Bring Your Own API Key）功能。它记录了 OpenAI、Anthropic、Google、Azure OpenAI 和 AWS Bedrock 密钥；它还指出，自定义 API 密钥仅适用于聊天模型，Tab 补全会继续使用 Cursor 内置模型，而使用自有密钥的请求仍会通过 Cursor 服务器进行最终的提示构建。公开文档没有记录一个通用的、任意的 OpenAI 兼容基础 URL 字段。

这对 Flatkey 用户很重要。Flatkey 为团队提供一个密钥、一个位于 https://router.flatkey.ai/v1 的 OpenAI 兼容网关、跨提供商的模型访问权限，以及在一个地方审查使用情况和成本的功能。如果您的 Cursor 版本、管理策略或提供商配置公开了自定义 OpenAI 基础 URL 字段，请使用本指南来验证设置。如果您的 Cursor UI 仅支持提供商自有的 API 密钥，请使用相同的检查来决定何时让 Cursor 保持其文档化的提供商流程，并在明确公开自定义基础 URL 的工具（例如 Cline 或 Claude Code 路由器工作流）中使用 Flatkey。

目标不是要强制每个 Cursor 请求都通过网关。目标是让每个 Cursor OpenAI 兼容 API 的决策都可审查：谁拥有密钥、实际使用了哪个基础 URL、选择了哪个模型名称、使用情况出现在哪里，以及如何回滚。

Cursor OpenAI 兼容 API 设置：首先要验证什么

在更改任何设置之前，先从一个简短的决策表开始。

设置方面	Cursor 公开文档的内容	您必须在工作区中验证的内容
提供商 API 密钥	在“Cursor 设置 > 模型”中为支持的提供商添加密钥。	您正在编辑哪个提供商行，谁拥有该密钥，以及团队策略是否允许 BYOK。
自定义基础 URL	截至 2026 年 7 月 8 日查阅的 Cursor 公开文档没有记录一个通用的、任意的 OpenAI 兼容基础 URL 路径。	您安装的 Cursor 版本或企业配置是否公开了基础 URL 覆盖选项。
模型名称	Cursor 模型出现在模型选择器中；可用性取决于套餐、提供商和地区。	所选模型名称是 Cursor 模型、提供商模型还是网关模型别名。
使用日志	Cursor 使用情况仪表板显示 Cursor 使用情况的使用量、配额、按需费用、成本和模型选择。	请求是否也出现在 Flatkey 日志、提供商日志中，还是仅出现在 Cursor 使用情况中。
隐私模式	Cursor 表示，当您使用自己的 API 密钥时，“零数据保留”不适用。	您的安全审查是否接受 Cursor 的提示构建加上所选的提供商或网关路径。

这是 Cursor OpenAI 兼容 API 设置的第一条规则：不要将 API 密钥字段视为网关路由的证明。密钥字段证明了凭据的输入。基础 URL 字段、请求日志和使用记录才能证明路由。

在接触 Cursor 之前要收集的值

将设置值放在一个小型工作表中。与负责计费或安全的人员共享，而不仅仅是执行 UI 更改的开发人员。

字段	Flatkey 示例	重要性
API 密钥所有者	用于 Cursor 评估的专用 Flatkey 密钥	将 IDE 流量与应用流量分开，使回滚更干净。
基础 URL	`https://router.flatkey.ai/v1`	避免重复的 `/v1/v1` 路径，并保持路由与 OpenAI 兼容。
端点系列	首先是聊天补全 (Chat Completions)	Cursor BYOK 文档称自定义 API 密钥仅适用于聊天模型。
模型名称	团队选择的当前 Flatkey 目录别名	网关别名可能与 Cursor 模型选择器中的名称不同。
测试提示	一个低风险的 Agent 或聊天提示	使第一个请求在日志中易于查找。
使用情况负责人	Cursor 使用页面、Flatkey 使用/日志、财务负责人	防止测试后出现意外的计费纠纷。
回滚值	之前的 Cursor 模型/密钥设置	让团队可以在不删除证据的情况下进行恢复。

对于 Cursor OpenAI 兼容 API 测试，最常见的错误是在一个系统中使用另一个系统的模型显示名称。Cursor 模型名称、提供商模型 ID 和 Flatkey 路由别名不是自动可互换的。从将接收请求的地方选择模型名称。

首先运行外部冒烟测试

在 Cursor 内部测试之前，先在 Cursor 外部验证网关值。这些代码片段仅为模板；请将密钥和模型替换为您当前 Flatkey 帐户和目录中的值。

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_MODEL="your-current-model-alias"

curl -sS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

使用模型响应来确认确切的模型 ID 或别名。然后测试聊天路径：

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: cursor route probe ok"
      }
    ]
  }'

如果响应中包含 usage 对象，请保存请求时间戳、模型名称、HTTP 状态、响应正文和该对象。OpenAI 的 Chat Completions API 结构是围绕 model 和 messages 构建的，成功的响应可以包含令牌使用情况。OpenAI 的 models 端点列出了账户当前可用的模型。这两个事实使得在您引入 Cursor 之前，这个冒烟测试非常有用。

如果此外部测试失败，请不要继续操作 Cursor。请先修复密钥、模型别名、配额或端点族。在 Cursor 添加了自己的模型选择器、提示构建和请求路径后，失败的外部测试不会变得更容易调试。

仅在路由验证通过后配置 Cursor

现在打开 Cursor 并检查您账户可用的实际设置。

打开 Cursor 设置 > 模型。
检查您的组织是否允许个人 API 密钥。企业管理员可以限制 BYOK 的使用。
如果您正在使用 Cursor 文档中记录的 BYOK 路径，请选择 Cursor 支持的提供商行，并输入该提供商的密钥。
如果您的 Cursor 环境提供了一个自定义的 OpenAI 兼容基础 URL 字段，请仅输入基础 URL 的根部分，例如 https://router.flatkey.ai/v1，而不是完整的 /chat/completions 路径。
从接收系统中输入或选择模型名称。对于 Flatkey，请使用在 Flatkey 目录或 /v1/models 冒烟测试中确认的模型别名。
保存设置，然后如果 Cursor 在模型选择器中显示了目标模型，请在那里选择它。

这就是文章标题可能会误导团队的地方：当设置页面保存时，Cursor OpenAI 兼容 API 的设置并未完成。只有当您从 Cursor 发送的请求出现在预期的使用记录中时，设置才算完成。

用于 Cursor 模型路由的模型名称清单

当有人问“我应该输入哪个模型名称？”时，请使用此表。

问题	好的证据	不好的捷径
Cursor 是否在其选择器中显示该模型？	活动模型在聊天或 Agent 面板中可见。	假设因为密钥已保存，提供商 ID 就会出现。
网关是否知道模型别名？	`/v1/models` 或 Flatkey 目录显示了您账户的别名。	从博客文章中复制营销模型名称。
端点族是否匹配？	为聊天模型流量选择了 Chat Completions 路由。	通过错误的 OpenAI 兼容路径发送仅限本机的模型。
模型是否支持您的功能？	如果需要，为纯聊天、流式传输和工具调用保存一个测试。	将纯文本补全视为所有功能都可用的证明。
财务以后能找到它吗？	使用记录条目包含足够的路由/模型上下文以供审查。	仅依赖编辑器中的成功回答。

对于 Cursor OpenAI 兼容 API 的推广，请从纯聊天开始。不要使用大型代码库重构、大量使用工具的 Agent 运行或长时间的 Max Mode 会话作为首次测试。让第一个提示足够简单，以便使用记录成为主要结果。

在三个地方验证使用日志

一个返回文本但没有留下使用记录的网关设置尚未准备好用于生产。在第一次请求后检查三个层面。

层面	检查内容	负责人
Cursor 使用情况	Cursor 仪表板使用情况、模型选择、配额和按需费用。	Cursor 席位所有者或团队管理员。
Flatkey 使用情况/日志	请求时间戳、密钥、模型别名、端点族、令牌使用情况、成本上下文以及可用的错误信息。	平台或运营负责人。
提供商或网关响应	HTTP 状态、响应中的 `usage`、模型字段以及任何请求 ID 或错误代码。	进行冒烟测试的开发人员。

重要的所有权细节是，Cursor 自己的文档中提到，您的 API 密钥会在每次使用自有密钥的请求中发送到 Cursor 的后端，用于最终的提示构建。这意味着 Cursor OpenAI 兼容 API 测试应被视为一个“工具+网关”路径进行审查，而不是从您的笔记本电脑到提供商的直接本地调用。

如果您的团队依赖 Cursor 的零数据保留政策，请在使用自己的密钥前阅读 Cursor 的 BYOK 隐私声明。Cursor 声明，其零数据保留政策不适用于使用您自己的 API 密钥的情况；数据处理将遵循所选提供商的政策。如果您通过 Flatkey 进行路由，请将 Flatkey 的当前政策、仪表板和保留证据添加到同一审查包中。

基础 URL、密钥和模型故障排查

大多数故障都可归结为少数几个原因。

症状	可能原因	解决方法
`401` 或身份验证错误	密钥错误、复制了空格、密钥已撤销或密钥不允许用于该路由。	重新复制密钥，使用专用的测试密钥，并首先重试外部 curl。
`403` 或权限错误	团队策略、提供商授权、区域或网关权限阻止了请求。	检查 Cursor BYOK 策略、Flatkey 账户访问权限和提供商可用性。
`404` 或模型未找到	模型名称对于接收系统无效。	使用模型选择器、`/v1/models` 或当前的 Flatkey 目录作为事实来源。
`429` 或配额错误	超出了 Cursor 计划限额、提供商配额、Flatkey 配额或请求速率。	降低测试量，检查限制，并指派负责人来增加配额。
返回文本但没有出现 Flatkey 日志	请求未通过 Flatkey 路由。	重新检查 Cursor 是否接受自定义基础 URL 或仅接受提供商密钥。
Cursor Tab 行为未改变	Cursor 文档指出自定义 API 密钥仅适用于聊天模型。	不要使用 Tab 补全作为验证信号。

OpenAI 自己的错误指南将身份验证、速率限制、配额和过载服务错误视为不同的所有者操作。在您的 Cursor 操作手册中保持这种区分。重试策略无法修复错误模型名称，而新的模型名称也无法修复 BYOK 策略的阻止。

何时不应为 Cursor 使用 Flatkey

在某些情况下，关于 Cursor OpenAI 兼容 API 的最佳决策是停止使用。

如果您当前的 Cursor 版本没有提供基础 URL 覆盖选项，而您的工作流需要一个真正的自定义端点，请不要通过 Flatkey 路由 Cursor。如果您的企业管理员已禁用个人 API 密钥，请不要通过 Flatkey 路由 Cursor。如果您的安全审查依赖于 Cursor 内置模型的隐私控制，而这些控制不适用于自有密钥的流量，请不要通过 Flatkey 路由 Cursor。

在这些情况下，请让 Cursor 保持在文档化的提供商路径上，并在客户端明确支持 OpenAI 兼容基础 URL 的地方使用 Flatkey：应用程序 SDK、内部工具、评估脚本、Cline、Open WebUI、LangChain、LlamaIndex 或其他集成界面。如果您需要通用的迁移模式，请从OpenAI 兼容 API 迁移指南开始。对于编码代理路由模式，请比较Claude Code API 路由设置和Cline OpenAI 兼容 API 设置。

生产环境清单

在宣布 Cursor OpenAI 兼容 API 设置完成之前，请保存以下证据：

证据	完成条件
Cursor 设置	截图或管理员备注显示了所使用的提供商/密钥/基础 URL 路径，并隐藏了机密信息。
模型证明	模型名称来源于 Cursor 的模型选择器、Flatkey 目录或 `/v1/models`，而不是猜测。
外部冒烟测试	`https://router.flatkey.ai/v1/chat/completions` 使用所选模型返回一个纯文本响应。
Cursor 请求证明	一个小的 Cursor 提示使用了预期的模型，并且不依赖于 Tab 补全。
使用证明	Cursor 使用情况和 Flatkey 使用情况/日志证据已保存并带有时间戳。
错误映射	`401`、`403`、`404`、`429` 和 `5xx` 的所有者操作已记录在案。
回滚	之前的 Cursor 模型/密钥路径已记录，并且可以在不删除日志的情况下恢复。

当 Cursor OpenAI 兼容 API 设置能将编码工具的流量转化为受治理、可审查的模型使用时，它就非常有价值。请将基础 URL、模型名称和使用日志证明保存在一起。当您需要一个网关密钥和一个地方来审查模型流量时，请获取一个 Flatkey 密钥，首先测试一个低风险的聊天请求，并在日志证明路由正确后再进行迁移。