从 OpenRouter 迁移到 OminiGate：分步实操手册

OpenRouter 与 OminiGate 都对外暴露 OpenAI 兼容协议，因此把流量从前者 切到后者基本是机械动作——改 base URL、换 key、调几个 Header、核对 model slug。出错往往出在细节：一个看上去合理但其实 没上架的 slug、一个忘了去掉的归因 Header、一个你的代码还在引用 但 Anthropic 已经退役的模型。本文以 2026-04-28 当天可核对的官方 文档为依据，逐步给出可操作步骤。

前提两条：你的应用通过 OpenAI 兼容的 /v1/chat/completions 端点调 OpenRouter（最常见），并 且希望整个切换可以从负载均衡层一键回滚。如果你用 Anthropic 兼容的 /v1/messages 端点，OminiGate 的对等地址是 https://api.ominigate.ai，本文其余内容 同样适用。

迁移动机

OpenRouter 是一款合格的网关，对许多团队来说是合理的默认选择。我们 听到的迁移理由都很务实，不带情绪：

• 计费结构。OpenRouter 在非加密支付的充值环节收取 5.5%（最低 0.80 美元）平台费，token 本身按上游 原价透传无加价（来源）。 BYOK 模式下，每月前 100 万次请求免费，超出部分目前按 5% 收费， 但官方公告该费率将被替换为月费订阅，新价尚未 公布（来源）。 需要做 12 个月成本测算的团队不喜欢这种不确定性。
• 归因暴露面。OpenRouter 鼓励发 HTTP-Referer 和 X-OpenRouter-Title， 以便你的应用出现在公开排行榜上（文档）。 有些团队不希望内部应用名出现在公共榜单。
• 路由意外。当某个 model slug 没直接上架时， OpenRouter 可能转路由或返回 not available。截至成 文时，google/gemini-3-pro 和 google/gemini-3.1-pro都返回“不可用” 并引导到 Discord 申请。实际可用的 slug 是 google/gemini-3.1-pro-preview。
• 统一供应商。有些团队已经在 OminiGate 上使用图像 和视频模型（截至 2026-04-28 共 81 个图像 + 80 个视频），希望 chat / image / video 的账单合并到一个供应商。

以上都不是对 OpenRouter 的批评，只是这些场景下的一日迁移值得花 工程师时间。如果以上都跟你无关，留在 OpenRouter 上没问题。

第 1 步：替换 base URL

OpenRouter 的 OpenAI 兼容 base URL 是 https://openrouter.ai/api/v1（官方 Quickstart）。 OminiGate 的 OpenAI 兼容 base URL 是 https://api.ominigate.ai/v1，Anthropic 兼容地址为 https://api.ominigate.ai。

用官方 OpenAI SDK 时只改一行：

# 改前
from openai import OpenAI
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=OPENROUTER_API_KEY,
)

# 改后
client = OpenAI(
    base_url="https://api.ominigate.ai/v1",
    api_key=OMINIGATE_API_KEY,
)

Node 同理：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ominigate.ai/v1",
  apiKey: process.env.OMINIGATE_API_KEY,
});

不要试图在一个 client 实例里靠特性开关切换两个供应商。灰度阶段保留 两个 client，路由放在调用点——这样回滚只是改一行配置， 不必重新初始化 SDK。

第 2 步：替换 API Key

OminiGate 的 key 前缀为 sk-omg-（OminiGate 文档与 控制台均可见）。直接在 Dashboard 新建 key，不要复用 OpenRouter 的 key——两边的格式不互通，且第一天就要拿到一条干净的成本 线。

两条运维注意事项：

• 把新 key 加为新的环境变量（如 OMINIGATE_API_KEY），不要覆盖OPENROUTER_API_KEY。灰度期间两边都需要。
• 如果你按租户发 key，按 1:1 与 OpenRouter 现有 key 对齐，方便审计 日志比对。

第 3 步：清理 Header

OpenRouter 的归因 Header 是 HTTP-Referer（必填，否则“不会创建 app 页面，使用量也不会 出现在排行榜”）和 X-OpenRouter-Title（选填；X-Title 仍向后兼容）（App Attribution 文档）， 另外还有 X-OpenRouter-Categories 用于市场分类标签。

OminiGate 没有排行榜，因此这些 Header 在 OminiGate 侧不会触发任何 逻辑。调 OminiGate 时把它们删掉——留着也无害，但双路由 代码的 diff 会更干净。

  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
-   "HTTP-Referer": "https://your-app.example.com",
-   "X-OpenRouter-Title": "Your App",
  }

如果双路由层用 feature flag 切两边，更建议把 Header 放在按 provider 分支的配置块里，而不是全局删——只要还有一个 token 流量 走 OpenRouter，那条路径仍然需要这些 Header。

第 4 步：映射 model slug

这是迁移最容易翻车的地方，所以本节列得很细。下表每一行的两端 slug 都对照了上游官方退役页 / 各网关的实时 model 页核对（核对日期 2026-04-28）。

Anthropic

两个关键事实：(1) Anthropic 在 2026-04-14 弃用了 claude-sonnet-4-20250514 和 claude-opus-4-20250514，预定退役日为 2026-06-15；(2) 官方推荐替代分别是 claude-sonnet-4-6 和 claude-opus-4-7（Anthropic 退役表）。 如果你的代码还固定用 Claude Sonnet 4 或 Opus 4 基础版，本次迁移 正好顺手升级到 4.6 / 4.7——反正 60 天内都得动。

OpenRouter slug                         OminiGate slug
─────────────────────────────────────   ─────────────────────────────────────
anthropic/claude-opus-4.7            →  anthropic/claude-opus-4.7
anthropic/claude-opus-4.6            →  anthropic/claude-opus-4.6
anthropic/claude-opus-4.5            →  anthropic/claude-opus-4.5
anthropic/claude-sonnet-4.6          →  anthropic/claude-sonnet-4.6
anthropic/claude-sonnet-4.5          →  anthropic/claude-sonnet-4.5
anthropic/claude-haiku-4.5           →  anthropic/claude-haiku-4.5
anthropic/claude-3.7-sonnet  (已退役) → anthropic/claude-sonnet-4.6
anthropic/claude-3.5-sonnet  (legacy) → anthropic/claude-sonnet-4.6
anthropic/claude-3.5-haiku   (已退役) → anthropic/claude-haiku-4.5

来源：OminiGate 模型列表（2026-04-28 核对）；OpenRouter 产品页 claude-opus-4.7、claude-sonnet-4.6；退役状态见前述 Anthropic 官方表。

一个细节：anthropic/claude-3.5-sonnet 在 OpenRouter 上仍然显示，但其底层权重 claude-3-5-sonnet-20241022 已在 2025-10-28 由 Anthropic 正式退役。OpenRouter 的路由层在做兜底，但新代码应直接指向 claude-sonnet-4.6。

OpenAI

OpenAI 于 2026-04-23 发布 GPT-5.5，次日开放 API（发布公告）， 是当前 GPT-5 家族的旗舰；GPT-5.4 仍在线，是很多团队对延迟和成本敏感场景的日常主力。

OpenRouter slug                  OminiGate slug
──────────────────────────────   ──────────────────────────────
openai/gpt-5.5                →  openai/gpt-5.5
openai/gpt-5.5-pro            →  openai/gpt-5.5-pro
openai/gpt-5.4                →  openai/gpt-5.4
openai/gpt-5.4-mini           →  openai/gpt-5.4-mini
openai/gpt-5.4-nano           →  openai/gpt-5.4-nano
openai/gpt-5.4-pro            →  openai/gpt-5.4-pro
openai/gpt-5                  →  openai/gpt-5
openai/gpt-5-pro              →  openai/gpt-5-pro
openai/gpt-5-mini             →  openai/gpt-5-mini
openai/o3                     →  openai/o3
openai/o4-mini                →  openai/o4-mini

来源：OpenRouter 页 openai/gpt-5.5、openai/gpt-5； OminiGate 模型列表（2026-04-28 核对）。

Google

这是最容易踩坑的家族。Gemini 3.1 Pro 在 2026-02-19 发布（model card）， 但在两个网关上都以 -preview后缀挂载。不带后缀的 slug 不存在——OpenRouter 上 google/gemini-3.1-pro直接返回“不可用”。

OpenRouter slug                              OminiGate slug
──────────────────────────────────────────   ──────────────────────────────────────────
google/gemini-3.1-pro-preview            →   google/gemini-3.1-pro-preview
google/gemini-3.1-pro-preview-customtools →  google/gemini-3.1-pro-preview-customtools
google/gemini-3.1-flash-lite-preview      →  google/gemini-3.1-flash-lite-preview
google/gemini-3.1-flash-image-preview     →  google/gemini-3.1-flash-image-preview

来源：OpenRouter 详情页 google/gemini-3.1-pro-preview； OminiGate 模型列表（2026-04-28 核对）。

如果代码当前还在用 google/gemini-2.5-pro，先在 OpenRouter 和 OminiGate 两端同时升到 3.1-preview，不要把版本 升级和供应商切换合并到同一次发布。

DeepSeek

DeepSeek 在 2026-04-24 发布 V4 双预览（DeepSeek changelog）。 老的 deepseek-chat / deepseek-reasoner 别名 将在 2026-07-24 15:59 UTC 完全退役，本表有明确的时间窗。

OpenRouter slug                  OminiGate slug
──────────────────────────────   ──────────────────────────────
deepseek/deepseek-v4-pro      →  deepseek/deepseek-v4-pro
deepseek/deepseek-v4-flash    →  deepseek/deepseek-v4-flash
deepseek/deepseek-v3.2        →  deepseek/deepseek-v3.2
deepseek/deepseek-v3.2-exp    →  deepseek/deepseek-v3.2-exp
deepseek/deepseek-chat        →  deepseek/deepseek-v4-flash  (chat 即将退役)

来源：OpenRouter 页 deepseek/deepseek-v4-pro； OminiGate 模型列表（2026-04-28 核对）。

Meta Llama

OpenRouter slug                                OminiGate slug
────────────────────────────────────────────   ────────────────────────────────────────────
meta-llama/llama-4-maverick                →   meta-llama/llama-4-maverick
meta-llama/llama-4-scout                   →   meta-llama/llama-4-scout
meta-llama/llama-3.3-70b-instruct          →   meta-llama/llama-3.3-70b-instruct
meta-llama/llama-3.1-70b-instruct          →   meta-llama/llama-3.1-70b-instruct

来源：OminiGate 模型列表（2026-04-28 核对）；Llama 4 发布背景见 Meta Llama 4 公告。

务实建议：不要让 LLM “贴心地” 帮你重写 slug 列表。把上面 的字符串原样写进代码，再加一条冒烟测试——断言响应里返回 的 model 字段等于你发出去的 slug。

第 5 步：验证流式响应

两边都遵循 OpenAI SSE 协议：以 data: {...} 分块、以 data: [DONE] 结束。OpenAI SDK 自带的流迭代 器对两个端点都开箱可用。两个实战注意点：

• 末尾 usage 块。如果计费 / 分析依赖最末一帧的 usage 字段，记得在两端都发 stream_options: { include_usage: true }（OpenAI 标准），否则末帧不会带 token 计数。
• 透传字段差异。OpenRouter 有时会回传上游特有字段 （如 provider、Anthropic 的 cache_read_input_tokens）。OminiGate 在调 Anthropic 家族时也会回传 cache_creation_input_tokens / cache_read_input_tokens，但其它字段集合略有不同。 如果你持久化整段响应，注意非计费字段的 schema 漂移。

建议同一 prompt 用 temperature=0 在两端各跑一次，对 流出文本和 token 计数做 byte-diff，整套切换以一个稳定 fixture 集 全部一致为准入门槛。

第 6 步：对账与可观测性

关心的数字是每千 token 成本，但出现在哪个账单行不同。OpenRouter 在 Dashboard 显示信用扣减，token 透传，非加密充值时收 5.5% 平台费。OminiGate 是按 token 计费、无 per-call 加价、无充值附加费（OminiGate 定价）。

举例：Claude Sonnet 4.6 在 OpenRouter 上是 $3/M 输入、$15/M 输出（来源）。 OminiGate 上同 token 单价透传，差异出现在充值环节。如果你向 OpenRouter 用 Stripe 充 1000 美元，实际付 1055 美元（5.5%）； OminiGate 是按用量直接扣信用卡。

可观测性方面，两端都返回标准 OpenAI 字段： usage.prompt_tokens、 usage.completion_tokens、 usage.total_tokens。如果你记录了 response.id 用于 tracing，请注意前缀格式按 provider 变化，不要写死断言。

灰度策略

非平凡生产系统的安全切换路径：

1. Day 0 — 双写、单读。引入特性开关 llm_provider，取值 openrouter | ominigate，默认 openrouter。结构化日志记录 provider、model slug、 延迟、token 计数。
2. Day 1 — 影子流量。取 1-5% 请求，同 prompt 并行打到两端，返回 OpenRouter 结果，记录 OminiGate 结果与差异。 跑 24-72 小时。任何 token 计数偏差超过几个 token（少量分词漂移 正常，倍数不正常）都要排查。
3. Day 3 — 10% 金丝雀。把 10% 用户切到 OminiGate，观察错误率、p95 延迟、单次成本。
4. Day 5-7 — 25 / 50 / 100% 上量。每一步等两个 工作日时间窗的指标干净。
5. Day 14 — 退役。100% 稳定一周后，移除 OpenRouter 路径并轮换 OpenRouter 的 key。

必须有一键回滚：在配置层把 llm_provider 翻回 openrouter，无需重新部署。如果回滚不能在 60 秒内完成， 说明第 1 步还没做完。

切换前自检清单

• Slug 审计。grep 仓库里所有打到网关的 model 字符串， 逐个对照第 4 步映射表。重点关注包含 claude-sonnet-4-2025、 claude-opus-4-2025、 claude-3-5-sonnet、或不带 -preview 的 gemini-3.1-pro 的命中项。
• Header 审计。确认 HTTP-Referer、 X-OpenRouter-Title、 X-Title 仅出现在调 OpenRouter 的代码路径上。
• 流式冒烟。同一 temperature=0 prompt 在两端跑， 做 byte diff。
• Tool / function calling。每个模型家族至少跑一个 tool calling fixture。
• Anthropic 缓存字段。如果依赖 prompt 缓存，验证 cache_creation_input_tokens 和 cache_read_input_tokens 出现在 usage 中。
• 限流响应头。对比代码假设的 schema 与实际响应头。
• 对账脚本。5 行内的脚本，按天汇总日志的 total_tokens 与 provider 账单做差，迁移期间和之后 都跑。
• 回滚开关压测。在 staging 来回切 llm_provider，确认会话中切换不破坏 provider-specific 代码路径。

参考来源

本文所有事实可追溯到下列 URL，均于 2026-04-28 当日核对。

• OpenRouter Quickstart — 当前 base URL https://openrouter.ai/api/v1、 认证、示例请求。
• OpenRouter App Attribution — HTTP-Referer 必填、X-OpenRouter-Title 选填、X-Title 仍兼容、X-OpenRouter-Categories 市场分类。
• OpenRouter 平台费公告 — 非加密 5.5% / 最低 0.80 美元，加密 5.0%，无 token 加价， BYOK 政策即将变更。
• OpenRouter 定价页 — BYOK 每月 100 万次免费、超出 5%、计划改月费订阅。
• Anthropic 模型退役表 — Claude Sonnet 4 / Opus 4 于 2026-04-14 弃用、2026-06-15 退役；Sonnet 3.7 于 2026-02-19 退役；Haiku 3 于 2026-04-20 退役。
• OpenRouter / Claude Opus 4.7 — slug、$5/M 输入、$25/M 输出、2026-04-16 发布、1M 上下文。
• OpenRouter / Claude Sonnet 4.6 — slug、$3/M 输入、$15/M 输出、2026-02-17 发布。
• OpenAI: 介绍 GPT-5.5 — 发布日 2026-04-23、API 上线 2026-04-24。
• OpenRouter / GPT-5.5 — slug、$5/M 输入、$30/M 输出、1M+ 上下文。
• Gemini 3.1 Pro Model Card — 2026-02-19 发布、1M 上下文、$2/M 输入、$12/M 输出。
• OpenRouter / Gemini 3.1 Pro Preview — 实际可用的 slug；非 -preview 版不可用。
• DeepSeek V4 changelog — deepseek-v4-pro / deepseek-v4-flash 于 2026-04-24 发布、1M 上下文。
• OpenRouter / DeepSeek V4 Pro — $0.435/M 输入、$0.87/M 输出。
• Meta: Llama 4 Herd — Llama 4 Scout / Maverick 发布。
• OminiGate 模型列表 — 上文所有 OminiGate 端 slug 均以此为准。
• OminiGate API 文档 — OpenAI base https://api.ominigate.ai/v1、 Anthropic base https://api.ominigate.ai、 key 前缀 sk-omg-。
• OminiGate 定价 — 按 token 计费、无订阅、无最低消费，token 计数与上游一致。