Metapi OAuth 管理教程：3 步浏览器授权接入 Codex、Claude、Gemini CLI、Antigravity-平芜编程栈

Metapi OAuth 管理教程：3 步浏览器授权接入 Codex、Claude、Gemini CLI、Antigravity

【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点，汇聚成一个 API Key、一个入口，自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/gh_mirrors/meta/metapi

Metapi 的「OAuth 管理」功能让你不用手填 API Key、Access Token 或 Cookie，仅通过浏览器授权，就能把 Codex、Claude、Gemini CLI、Antigravity 这类 provider 官方账号接入同一个网关，最终汇聚成一个 API Key、一个入口。本文带你 3 步完成接入，并附上常见的排障方法。

为什么这类上游要走 OAuth 而不是 API Key

Metapi 支持多种上游接入方式，判断标准很简单：

你拿到的是什么	适合的方式	典型场景
站点后台地址 + 账号密码	站点管理 / 账号管理	New API、One API、DoneHub、AnyRouter、Sub2API
一段 API Key	API Key 管理	OpenAI-compatible、Claude-compatible 网关
provider 官方登录授权	OAuth 管理	Codex、Claude、Gemini CLI、Antigravity

OAuth 连接的特点：

✅ 使用浏览器授权，而不是手填用户名密码
✅ 授权成功后，Metapi 会自动创建或复用对应 provider 的宿主站点
✅ 账号按 OAuth 连接保存，后续刷新、重绑都走同一套流程

四个内置 provider 一览（来源：providers.ts）：

Provider	自动创建的站点名	备注
Codex	`ChatGPT Codex OAuth`	直接用 Codex 账号授权
Claude	`Anthropic Claude OAuth`	直接用 Claude / Anthropic 账号授权
Gemini CLI	`Google Gemini CLI OAuth`	可选输入 Project ID
Antigravity	`Google Antigravity OAuth`	复用 Antigravity 账号授权

💡 这类站点是 OAuth 账号在 Metapi 里的「宿主站点」，不要把它理解成又多了一个可签到的面板站。

开始前的 2 个准备

准备 1：确认网络能访问 OAuth 端点

如果你的服务器访问外网受限，可先配置全局SYSTEM_PROXY_URL，或在 OAuth 启动 / 重绑时指定单次代理。相关环境变量见 docs/configuration.md 的「OAuth 与 Provider 登录」一节。

准备 2：远程部署提前想好回调方式

OAuth 默认使用 Metapi 本机的 loopback 回调地址（如127.0.0.1端口）。如果 Metapi 跑在远程服务器上、浏览器跑在本地电脑，有两种通行做法：

SSH 隧道：按页面给出的命令，把回调端口转发到远端
手动回填 callback URL：浏览器已完成授权但回调没打通时，把最终回调地址贴回管理页

3 步浏览器授权教程

步骤 1：打开「OAuth 管理」页面

进入管理后台左侧菜单「OAuth 管理」。它是一个和「站点管理」「账号管理」并列的独立页面，不是站点编辑器里的隐藏选项。页面会加载 provider 列表和已有连接，对应源码为 OAuthManagement.tsx。

步骤 2：点击要连接的 provider，启动授权会话

点击目标 provider 后，Metapi 会发起一个 OAuth 会话并弹出授权窗口，同时给出：

🔗 授权链接
🖥️ 本机回调端口
⏱️ 手动回填等待时间
🌐 远程访问时的 SSH 隧道命令模板

Gemini CLI 授权时如需要，可在此处填入 Project ID。

步骤 3：在 provider 页面完成授权，确认两层结果

在弹出的浏览器窗口中完成登录授权。Metapi 会轮询会话状态：pending（等待回调）→success（授权成功）→error（需检查回调或网络）。

成功后通常会看到两层结果：

「OAuth 管理」页里出现新的连接记录
「站点管理」页里出现对应 provider 的站点行

接入完成后，这些账号即可参与统一路由与代理，仪表盘会集中展示各通道的调用情况：

授权卡住了？用手动回填 callback URL

这是新手最常见的坑：浏览器里授权成功了，但 Metapi 页面一直停在「等待授权完成」。优先怀疑回调链路没通：

如果是远程服务器，先按页面提示建立 SSH 隧道
不方便建隧道时，直接手动回填：
- 复制浏览器地址栏里最终形如...?code=...&state=...的回调 URL
- 回到「OAuth 管理」，粘贴到手动回填区域提交
如果 provider 页面最终没有code/state参数，说明授权本身还没成功，需要重新走一遍授权

相关处理逻辑见 localCallbackServer.ts。

授权之后：自动刷新与重新绑定

接入只是开始，Metapi 会持续维护这些 OAuth 连接：

🔄自动刷新：内置刷新调度器按 provider 分别设定提前量（如 Claude 提前 4 小时、Codex 提前 5 天）刷新 access token，无需人工干预，实现见 oauthRefreshScheduler.ts
🔁重新授权：连接失效或换绑账号时，在连接上点击「重新授权」即可走同一套流程
📋路由分组：多个 OAuth 账号可组成路由单元，按轮询或粘滞策略分流
🤖脚本化：如需自动化，可调用GET /api/oauth/providers、POST /api/oauth/providers/:provider/start、POST /api/oauth/connections/:accountId/rebind等管理接口