2026 OmniRoute Cursor 配置：共用多模型网关

最后更新于 2026 年 8 月 12 日，命令与 endpoint 已核对 OmniRoute 当前默认分支、release 文档、Cursor 官方文档及 Anthropic 网关文档。

症状： 你把 http://localhost:20128/v1 同时填进 Cursor 和 Claude Code，结果一端报鉴权错误，另一端模型列表为空。
最快解法： 保留同一个 OmniRoute 实例，但不要复用完全相同的 URL；Claude Code 使用不带 /v1 的网关根地址，Cursor 则先区分桌面端、Cursor CLI 和 MCP，再选择兼容入口。

这篇文章适合同时使用 Cursor 与 Claude Code、想统一维护模型凭据和路由规则的个人开发者，也适合需要持续运行 AI Gateway 的 Agent 工程师，以及正在设计多 provider 容错和权限隔离的小团队负责人。

同一网关，不同入口

典型失败配置是这样：

Cursor：      http://localhost:20128/v1
Claude Code： http://localhost:20128/v1

问题不在于 OmniRoute 不能同时服务两个客户端，而在于两个客户端使用的协议入口不同。OmniRoute 可以作为统一网关，把多个 provider 接到同一个服务实例；但客户端是否使用 OpenAI 兼容路径、Anthropic Messages 路径，取决于客户端自身的配置方式。

请求链路应该理解为：

Cursor 桌面端或 Cursor CLI
        │
        ├─ 兼容入口 /v1，或客户端支持的自定义 endpoint
        │
        ▼
OmniRoute：http://主机:20128
        │
        ├─ Provider A
        ├─ Provider B
        └─ Provider C

Claude Code 的链路不同：

Claude Code
        │
        └─ ANTHROPIC_BASE_URL=http://主机:20128
                         │
                         └─ 客户端继续请求网关下的 Anthropic Messages 路径

OmniRoute 的 CLI 配置文档明确把 Claude Code 的 ANTHROPIC_BASE_URL 定义为网关根地址，并注明不要添加 /v1；Anthropic 的网关说明也采用统一 endpoint，而不是把 OpenAI 兼容路径机械套到 Claude Code 上。(github.com)

这里有 3 个容易被忽略的限制：

• 路径限制： /v1 适合 OpenAI 兼容请求，不等于所有客户端都接受它。
• 协议限制： Claude Code 依赖 Anthropic Messages API 的请求格式，不只是修改一个 URL。
• 功能限制： Cursor 自定义 API key 只覆盖标准聊天模型，Tab Completion 等专用功能仍可能使用 Cursor 自身模型。(docs.cursor.com)

因此，“共用一个网关实例”是正确目标，“两个客户端填完全相同 URL”不是正确配置方法。

最小可用闭环

先不要同时调 Cursor、Claude Code、MCP 和远程访问。按照下面的顺序，把 OmniRoute 单独验收，再接客户端。

1．安装并启动网关

按 OmniRoute 当前快速开始文档，最小安装方式是：

npm install -g omniroute
omniroute

默认控制台位于：

http://localhost:20128

OpenAI 兼容 API 位于：

http://localhost:20128/v1

官方快速开始同时给出了 /v1/models 的验证方式，并要求先在控制台连接至少一个 provider。(github.com)

如果你更偏向服务常驻，也可以使用 Docker：

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

本地绑定 127.0.0.1 的好处是默认不暴露到局域网；代价是其他设备无法直接访问。远程 Mac 场景不能照抄这个绑定方式，必须改为受控的可达地址，并配合防火墙、HTTPS 或 Tailnet。

2．创建推理 API key

在 OmniRoute 控制台创建用于推理请求的 API key。不要把管理 token 和推理 key 混在一起：

• 推理 key：用于 /v1/models、聊天请求等 API 调用。
• 远程管理 token：用于 CLI 连接、读取配置和执行管理操作。
• 客户端密钥：只给需要调用模型的 Cursor 或 Claude Code 使用。

远程模式文档说明，管理 token 与推理 API key 是两套不同凭据；远程 token 还可以按 read、write、admin 进行权限区分。(github.com)

3．读取模型目录

先验证网关确实能看到模型：

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer YOUR_INFERENCE_KEY"

如果返回空目录，不要急着改 Cursor 配置。优先检查：

• provider 是否完成连接；
• provider 的 key 是否过期；
• 模型是否被禁用；
• OmniRoute 是否启动的是你刚刚配置的实例；
• API key 是否属于当前实例。

控制台页面能打开，只能证明前端端口可访问，不能证明推理 API、模型目录和 provider 都正常。

4．发送最小对话请求

使用一个明确存在的模型 ID，或者先用项目支持的 auto 路由：

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {
        "role": "user",
        "content": "只返回：gateway-ok"
      }
    ]
  }'

验收标准不是“返回了一个网页”，而是同时满足：

✅ /v1/models 能返回模型目录；
✅ /v1/chat/completions 能返回有效响应；
✅ 响应中能确认实际使用的模型或 provider；
✅ 更换模型选择后，请求仍然经过同一个 OmniRoute 实例。

Claude Code 的根地址规则

主流程：直接让 Claude Code 读取环境变量

Claude Code 配置 OmniRoute 时，关键变量如下：

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="YOUR_INFERENCE_KEY"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"

claude

注意第一行没有 /v1。OmniRoute 的 Claude Code 配置说明指出，Claude Code 会在网关根地址后继续拼接自己的 Messages API 路径；如果你写成 http://localhost:20128/v1，最终路径可能会多出一层 /v1，从而出现 404、鉴权失败或网关完全没有请求记录。(github.com)

Anthropic 官方网关文档也使用 ANTHROPIC_BASE_URL=https://gateway.example.com 这种根地址形式，并把统一入口与 fallback、负载均衡联系起来。(docs.anthropic.com)

变量修改后必须重新启动 Claude Code。环境变量通常在进程启动时读取，已经打开的终端会话不会自动刷新。

⚠️ 如果你用 settings.json 保存环境变量，密钥不要提交到 Git 仓库。团队环境应使用每个开发者独立的推理 key，并通过网关日志追踪调用来源。

OmniRoute 还提供自动配置路径，例如：

omniroute setup-claude
omniroute launch

也可以按模型生成 profile：

omniroute setup-claude --only YOUR_PROVIDER
omniroute launch --profile YOUR_PROFILE

自动配置适合你希望减少手工字段错误的情况；手动环境变量更适合临时测试和远程脚本。本文建议先采用手动主流程，确认根地址、认证和模型都正常后，再切换到自动 profile。

模型列表为空时的处理

Claude Code 的模型发现并不等于 OmniRoute 的完整模型目录。项目文档说明，原生 /model 选择器只会显示符合其发现规则的模型；非 Claude 命名的模型可能不会自动出现。此时可以显式指定：

export ANTHROPIC_MODEL="provider/model-id"
claude

如果你需要排查模型发现，再根据当前 Claude Code 版本和 OmniRoute 文档启用相应的 gateway discovery 变量。不要自行添加上下文窗口数字，也不要把某个模型的输出上限当成所有 provider 的统一能力。

Cursor 桌面端、CLI 与 MCP

配置差异

Cursor 不是单一路径。至少要拆成下面 3 类：

Cursor 官方文档明确说明，自定义 API key 只适用于标准聊天模型，专用模型功能不会全部改走你的 provider。(docs.cursor.com) Cursor CLI 文档则提供了 --endpoint、CURSOR_API_KEY 和登录状态检查等能力。(docs.cursor.com)

所以，不要把 MCP 的 URL 填到模型设置里，也不要假设 Cursor 桌面端的每一次补全、Tab Completion 或后台 Agent 请求都会经过 OmniRoute。

排查顺序

遇到 Cursor 验证失败，按这个顺序走：

1. 确认你使用的是桌面端还是 cursor-agent CLI。
2. 桌面端先检查 provider 类型、API key 和模型名称。
3. CLI 先运行 cursor-agent status，确认认证状态和 endpoint。
4. CLI 临时指定 endpoint，避免旧配置干扰：

export CURSOR_API_KEY="YOUR_INFERENCE_KEY"

cursor-agent \
  --endpoint "http://localhost:20128/v1" \
  "只返回：cursor-ok"

1. 在 OmniRoute 日志中确认确实出现请求。
2. 最后再测试工具调用、补全和 MCP，不要把它们混在第一次验证中。

OmniRoute 的 CLI 集成文档对 Cursor 的处理方式是输出应用内配置步骤，而不是替桌面端写入完整配置文件；这是因为 Cursor 桌面端配置并非普通的公开文本配置。

fallback 不生效的原因

模型能调用，不代表多模型 fallback 已经生效。最常见的错误是只接入了一个 provider，然后把 auto 当成了备用链。

至少要准备两个可用目标：

首选：provider-a/model-a
备用：provider-b/model-b

三种模式要分开理解：

• 单模型直连： 请求固定发给一个模型，额度耗尽后只能失败。
• 自动路由： OmniRoute 根据当前可用性、额度、延迟或策略选择目标。
• 自定义 fallback 链： 你明确规定首选和后备顺序，故障时切换到下一个目标。

项目仓库把 quota、健康状态、成本、延迟和成功率列为自动路由参考因素，并提供 priority、headroom、reset-aware 等策略。这里的策略能力属于项目文档说明，不应当写成独立第三方性能结论。(github.com)

可重复的故障演练

按以下步骤验证，而不是等真实额度耗尽：

1. 连接 provider-a 和 provider-b。
2. 固定首选模型或 combo 顺序。
3. 暂时撤销 provider-a 的 key，或让该 provider 返回可识别的失败。
4. 发送同一个最小请求。
5. 检查 OmniRoute 路由日志。
6. 确认最终响应来自 provider-b。
7. 恢复 provider-a，再重复一次，确认不会永久卡在备用目标。

成功标准包括 3 项：

✅ 日志显示首选目标失败；
✅ 路由决策显示切换动作；
✅ 最终响应的模型或 provider 标识发生变化。

经验判断：如果日志里根本没有第二次尝试，问题通常不是“额度不够”，而是你使用了单模型直连、fallback 链没有保存，或者两个目标实际指向同一个 provider 账户。

远程 Mac 的访问边界

本机测试时，localhost 最简单。Cursor、Claude Code 和 OmniRoute 在同一台 Mac 上，回环地址不会经过局域网，也不需要额外开放端口。

远程 Mac 则必须改成客户端可达的地址：

export ANTHROPIC_BASE_URL="https://mac-gateway.example.com"

Cursor CLI：

cursor-agent \
  --endpoint "https://mac-gateway.example.com/v1" \
  "检查远程网关"

远程部署至少要处理 4 个问题：

• 网络可达： 客户端能否访问远程 Mac 的监听地址。
• 访问范围： 不要把管理控制台和推理 API 无限制暴露到公网。
• 凭据隔离： 推理 key、管理 token、provider key 分开保存。
• 自动恢复： Mac 重启、OmniRoute 重启或网络短暂中断后，服务能否自动拉起。

OmniRoute 远程模式支持通过 omniroute connect 连接另一台机器，并使用受限访问 token；官方文档建议优先采用 HTTPS 或 Tailnet，而不是直接裸露一个 HTTP 主机地址。(github.com)

双工具交付验收

完成部署后，不要只验收“能不能发一句话”。你可以按下面的决策条件选择部署方式：

• 若只是个人短时测试，且 Mac 不会休眠： 先在本机运行 OmniRoute。
• 若需要跨设备访问： 把 OmniRoute 迁移到持续在线的远程 Mac。
• 若 Cursor 与 Claude Code 要共享同一组路由规则： provider 和 fallback 放在网关侧，不要分别在客户端维护两套。
• 若团队成员需要不同权限： 每人使用独立推理 key，管理操作使用受限 token。
• 若需要 MCP 工具： 单独验收 MCP 服务，不要用 MCP 连通性证明模型 endpoint 正常。
• 若 fallback 没有完成一次真实切换： 暂时不要把环境交付给团队，回退到单 provider 的显式模型配置。

最终验收表可以这样执行：

当前方案如果是“每个客户端单独配置 provider”，真实缺点通常是凭据重复、fallback 规则不一致、额度耗尽后难以追踪，而且本地 Mac 休眠或网络变化会直接中断长任务。对短时实验来说，本地运行最省步骤；但需要持续在线、跨设备调用或团队共享时，受控的远程 Mac 更适合作为 OmniRoute 和编码 Agent 的常驻环境。

如果你已经完成本地双工具验证，下一步应根据在线时长、跨设备访问和团队权限需求评估远程部署，而不是继续给两个客户端复制同一条 URL。你可以先查看 MacHTML 的帮助中心 了解远程环境交付方式；如果本地设备经常休眠、网络变化频繁，再结合 MacHTML 的美国节点方案 判断是否需要一台持续在线的云端 Mac。

延伸阅读: AI 编程工具算力对比：了解不同客户端与终端智能体的内存占用和云端部署取舍 模型故障转移与供应商路由：设计主备模型、限流重试和降级演练