Cursor + OpenRouter + Google Gemini BYOK

受限网络下无需本地网关、避开内置模型名冲突，在 Cursor 中使用自有 Gemini 3.8 Flash

Cursor
OpenRouter
Gemini
BYOK
代理
Windows
Author

Harness 技术文档

Published

September 9, 2026

摘要

在 Windows + v2rayN（TUN / 系统代理） 的受限网络环境下，Cursor 桌面端常出现两类现象：

  1. 网络诊断全绿，但 Models 列表缺少 Claude / GPT / Gemini 等主流模型（模型目录按请求出口 IP 做地区过滤）；
  2. 试图用 OpenAI 兼容通道自定义添加 gemini-3.8-flash 时，Add 无效果（与 Cursor 内置模型 ID 重名）。

本文记录一条已验证路径：OpenRouter 作为云端 OpenAI 兼容网关 + Google AI Studio BYOK，在 Cursor 中以自定义模型 ID google/gemini-3.8-flash 使用自有 Google 额度，无需本机部署 LiteLLM / One API。

配套网络基础见 Cursor IDE 与 v2rayN 日常网络指南。

Important本文不涉及的内容
  • 不能把 Google 网页端「Gemini / Google AI Pro」订阅直接绑到 OpenRouter；OpenRouter 只接受 AI Studio API Key 或 Vertex 服务账号。
  • 文中不写真实密钥；示例一律用占位符。

1. 问题拆解

flowchart TB
  A[目标：在 Cursor 用 Gemini 3.8 Flash] --> B{内置模型列表是否可见？}
  B -->|否：地区过滤| C[无法点选内置 Gemini]
  B -->|是| D[Google API Key 原生 BYOK]
  C --> E{自定义名 gemini-3.8-flash？}
  E -->|Add 静默失败| F[与内置 ID 冲突]
  E -->|唯一别名 my-gemini-test-001| G[能进列表]
  G --> H{直连 Google OpenAI 兼容 URL？}
  H -->|无本地改写网关| I[上游收到错误 model 名 → 失败]
  F --> J[OpenRouter + 唯一 slug]
  I --> J
  J --> K[google/gemini-3.8-flash + BYOK]

现象 根因（已验证）
诊断 api2.cursor.sh 等全绿，仍看不到国外主流模型 连通性 ≠ 模型目录；目录按出口 IP 地区过滤
填 Base URL + Gemini Key 后列表仍无模型 Cursor 不会从自定义 Base URL 做 /v1/models 发现；须手动 Add
Add gemini-3.8-flash 无条目；Add my-gemini-test-001 成功 前者与内置 ID 重名冲突；后者唯一故可创建
直连 generativelanguage.googleapis.com/v1beta/openai + 别名 请求体里的 model 原样发出，Google 不认别名；需改写网关
无 LiteLLM / One API 用 OpenRouter 做云端改写与路由

2. 方案概览

flowchart LR
  subgraph local["本机"]
    C[Cursor IDE]
    V[v2rayN TUN / 系统代理]
  end
  subgraph or["OpenRouter"]
    E["/api/v1/cursor"]
    B[BYOK: Google AI Studio Key]
  end
  subgraph g["Google"]
    G[Gemini 3.8 Flash]
  end
  C -->|sk-or-v1-… + model google/gemini-3.8-flash| V
  V --> E
  E --> B
  B --> G

组件 作用
v2rayN 保证本机可达 openrouter.ai（及必要时 Google）；诊断通过不等于模型目录完整
OpenRouter Key sk-or-v1-… 填入 Cursor「OpenAI API Key」；应用侧只持有这一把
Base URL …/api/v1/cursor OpenRouter 为 Cursor 准备的专用端点（工具调用格式更稳）
模型 ID google/gemini-3.8-flash 避开内置名冲突；由 OpenRouter 映射到上游 Gemini
Google AI Studio Key（BYOK） 推理走自有 Google 额度；OpenRouter 仅收少量手续费

3. 前置条件

  1. 代理：v2rayN 已能稳定访问境外 HTTPS（推荐 TUN 或「自动配置系统代理」；Cursor Network 可设 HTTP/1.1）。细节见 v2rayN 指南。
  2. Google 侧：AI Studio / Cloud 项目已开通 Gemini API 计费，并持有 API Key（常见 AIza…，新版也可能为 AQ.）。
    • 若仅有网页 Gemini 订阅、无 API Key → 无法完成 BYOK，只能改用 OpenRouter 积分直购。
  3. OpenRouter：已注册账号，工作区可访问 BYOK 与 Keys。
  4. OpenRouter 余额：BYOK 仍可能收取约 5% 中转费（以官网为准）；账户保留少量余额即可。

4. 操作步骤

4.1 将 Google API Key 绑到 OpenRouter（BYOK）

  1. 打开 Google AI Studio → API keys，创建并复制密钥。
  2. 打开 OpenRouter BYOK。
  3. 选择 Google AI Studio（个人付费 API；企业 Vertex 则选 Google Vertex + 服务账号 JSON）。
  4. Add key → 粘贴 Google API Key → 保存。
  5. 建议开启 Always use for this provider，减少落到 OpenRouter 共享容量的 fallback。

4.2 获取 OpenRouter API Key

  1. 打开 Settings → Keys。
  2. 列表中的 sk-or-v1-416…877 多为脱敏预览，创建后往往无法再看全文。
  3. 推荐：点 Create Key，命名如 cursor，创建后立即复制完整 sk-or-v1-…。

4.3 配置 Cursor

在 Cursor Settings → Models：

字段 填写
OpenAI API Key 完整 sk-or-v1-…（OpenRouter，不是 Google Key）
Override OpenAI Base URL https://openrouter.ai/api/v1/cursor
+ Add Model google/gemini-3.8-flash（须手动添加；Refresh 不会拉取第三方目录）

建议：

  • 暂时关闭未使用的 Anthropic / Google 原生 Key，避免与 Override 抢路由。
  • 完全退出 Cursor 再打开（不要只 Reload Window）。
  • 新开 Chat，在模型下拉里选择 google/gemini-3.8-flash。
Tip为何必须用 /api/v1/cursor

OpenRouter 文档指出：通用 https://openrouter.ai/api/v1 可能无法正确处理 Cursor 的工具调用格式；专用 /cursor 端点会先规范化再路由。Agent 场景优先使用该 URL。

4.4 验证闭环

  1. 对话自检：询问当前模型身份；应识别为 Gemini 3.8 Flash 一族。
  2. OpenRouter Activity（activity）应看到类似：
    • App：Cursor
    • Model：Gemini 3.8 Flash / google/gemini-3.8-flash
    • Usage type：BYOK
    • 可能有少量 OpenRouter Spend（手续费），推理主费用应在 Google 侧
  3. Google AI Studio / Cloud：对应项目 API 请求量有递增。

5. 已知限制与排障

现象 处理
切换回 Cursor Grok 4.6 / Composer 2.5 报 “This model does not support custom API keys” 已知副作用：OpenAI Key/Override 处于全局激活状态，Cursor 会错误地将自定义 Key 附带给官方托管模型；使用官方模型前在 Settings → Models 临时关闭 OpenAI API Key 开关（Key 无需删除）
Add gemini-3.8-flash 无反应，但 my-gemini-test-001 成功 内置名冲突；改用 google/gemini-3.8-flash
Chat 通、Agent 报 Unauthorized / 格式错误 确认 Base URL 含 /cursor；新开会话；Cursor 对 OpenRouter 非官方一等公民 BYOK
Activity 有请求但 Usage type 非 BYOK 检查 BYOK 是否启用、Always use；是否 fallback 到共享提供商
Override 开启后其它原生模型异常 Override 全局影响 OpenAI 形态请求；用完可关 Override 恢复
Tab / 部分 Auto、Composer 常仍走 Cursor 内置路径，不经过你的 OpenRouter Key
downloads.cursor.com 403、cursor-cdn.com 404 诊断探活常见噪声，一般可忽略

Cursor 侧代理加固（可选，网络不稳时） 在 User settings.json 一并写入（端口改为本机 v2rayN HTTP 入站）：

{
  "cursor.general.disableHttp2": true,
  "http.proxy": "http://127.0.0.1:10809",
  "http.proxySupport": "override",
  "http.proxyStrictSSL": false
}

然后完全退出再启动。仅勾选 Network「HTTP/1.1」而不写 http.proxy，在部分版本仍可能漏真实出口 IP。

6. 与其它路径的对比

方案 是否需要本地网关 模型名冲突 依赖出口 IP 目录 适合本经验场景
修代理 → 内置 Gemini + Google Key 否 无 强依赖 出口稳定且目录可见时更「正统」
直连 Google OpenAI 兼容 URL + 别名 需要改写 须用别名 弱 无 LiteLLM 时不可行
OpenRouter + BYOK + google/… slug 否 可避开 弱（只需达 OpenRouter） 本文路径

7. 安全与仓库卫生

Warning密钥
  • 勿将 sk-or-v1-…、Google API Key 写入本仓库或文档截图。
  • OpenRouter Keys 页若只显示截断串，视为已丢失全文 → 轮换新建，旧 Key 可禁用。
  • 分享 Activity 截图时注意脱敏 Key 后缀与邮箱。

8. 参考链接

链接以各站当前版本文档为准。