🔐 OAuth 管理
本文档介绍 Metapi 里的「OAuth 管理」页面，适合需要直接授权 provider 账号的场景。
这页解决什么问题
不是所有上游都适合手填 API Key、Access Token 或 Cookie。
对下面这类 provider 账号，更推荐直接走 OAuth：
- Codex
- Claude
- Gemini CLI
- Antigravity
这类接法的特点是：
- 使用浏览器授权，而不是手填用户名密码
- 授权成功后，Metapi 会自动创建或复用对应 provider 的站点
- 账号会按 OAuth 连接保存，后续刷新和重绑也走同一套流程
如果你接的是 New API、One API、Sub2API、CPA、OpenAI-compatible、Claude-compatible 这类普通站点或网关，请看 上游接入。
入口在哪里
管理后台左侧菜单已经有独立入口：
OAuth 管理这不是站点编辑器里的一个隐藏选项，而是和「站点管理」「账号管理」并列的一页。
当前支持的 provider
| Provider | 对应平台 | 自动创建的站点名 | 典型用途 |
|---|---|---|---|
| Codex | codex | ChatGPT Codex OAuth | 直接用 Codex 账号授权 |
| Claude | claude | Anthropic Claude OAuth | 直接用 Claude / Anthropic 账号授权 |
| Gemini CLI | gemini-cli | Google Gemini CLI OAuth | 复用 Gemini CLI / Google Cloud 账号授权，可选输入 Project ID |
| Antigravity | antigravity | Google Antigravity OAuth | 复用 Antigravity 账号授权 |
授权完成后，这些站点会出现在「站点管理」里，但通常不建议你手动创建它们。
授权前的准备
1. 准备 Google OAuth client 凭据
Gemini CLI 和 Antigravity 都不包含内置的 Google OAuth client 凭据。下面四个环境变量的默认值均为空，并且只在使用对应 provider 时必填：
- 使用 Gemini CLI OAuth 时，同时提供
GEMINI_CLI_CLIENT_ID和GEMINI_CLI_CLIENT_SECRET - 使用 Antigravity OAuth 时，同时提供
ANTIGRAVITY_CLIENT_ID和ANTIGRAVITY_CLIENT_SECRET
请通过部署 secret manager，或未跟踪的本地 .env / 容器环境变量提供这些值；不要把真实凭据写入仓库。未使用的 provider 可以保持对应字段为空，.env.example 也只保留空白模板。缺少对应配置时，该 provider 的 OAuth 流程无法启动。
2. 确保 Metapi 能访问 provider 的 OAuth 端点
如果你的部署环境访问外网受限，可以：
- 先配置全局
SYSTEM_PROXY_URL - 或在 OAuth 启动 / 重绑时使用单次代理参数
相关环境变量见 配置说明 里的「OAuth 与 Provider 登录」一节。
3. 远程部署要提前考虑回调方式
OAuth 默认使用 Metapi 本机上的 loopback 回调地址，例如本机 127.0.0.1 端口。
如果你的 Metapi 跑在远程服务器上，而浏览器跑在本地电脑上，常见做法有两个：
- SSH 隧道：按页面给出的命令，把回调端口转发到远端
- 手动回填 callback URL：如果浏览器已经完成授权，但自动回调没打通，可把最终回调地址手动贴回管理页
4. 了解它和普通站点接入的边界
OAuth 连接更适合“provider 原生账号授权”，而不是：
- 面板站点账号密码登录
- New API / One API 后台管理
- CPA / OpenAI-compatible 的普通 API Key 托管
标准流程
步骤 1：打开 OAuth 管理
进入左侧菜单「OAuth 管理」，等待页面加载 provider 列表和已有连接。
步骤 2：点击要连接的 provider
页面会为 provider 发起一个 OAuth 会话，并弹出授权窗口。
Metapi 会同时给出：
- 授权链接
- 本机回调端口
- 手动回填等待时间
- 如果当前是远程访问，还会给出 SSH 隧道命令模板
步骤 3：在 provider 页面完成授权
完成授权后，Metapi 会轮询当前会话状态：
pending：等待回调success：授权成功error：授权失败，需要重新检查浏览器回调或网络
步骤 4：必要时手动回填 callback URL
如果弹窗里已经能看到类似 ...?code=...&state=... 的回调地址，但 Metapi 页面还没成功：
- 复制浏览器最终回调 URL
- 回到「OAuth 管理」
- 粘贴到手动回填区域提交
步骤 5：确认站点与连接都已出现
成功后通常会看到两层结果：
- 「OAuth 管理」页里出现新的连接记录
- 「站点管理」页里出现对应 provider 的站点行
和普通站点 / API Key 的区别
| 方式 | 入口 | 适合什么 | 典型例子 |
|---|---|---|---|
| 普通站点 + Session | 站点管理 / 账号管理 | 有后台面板，需要签到、余额、账号令牌管理 | New API、One API、DoneHub、AnyRouter、Sub2API |
| 普通站点 + API Key | 站点管理 / API Key 管理 | 只关心代理调用和模型列表 | OpenAI-compatible、Claude-compatible、CPA |
| OAuth 连接 | OAuth 管理 | 需要 provider 官方授权、刷新、重绑 | Codex、Claude、Gemini CLI、Antigravity |
简单判断：
- 你拿到的是 站点后台地址，优先看 上游接入
- 你拿到的是 provider 登录授权，优先看这页
自动生成的站点有什么用
OAuth 成功后，Metapi 会确保对应 provider 的站点存在。这样做是为了让 OAuth 连接也能融入现有的：
- 站点列表
- 路由通道
- 账号归属
- 代理与重绑逻辑
但这类站点和普通面板站点仍然不同：
- 它们通常不是拿来手动登录的
- 不要把它理解成“我又多了一个可签到的面板站”
- 更准确地说，它是 OAuth 账号在 Metapi 里的宿主站点
管理 API 里怎么自动化
如果你想脚本化处理 OAuth，可以用这些接口：
| 接口 | 作用 |
|---|---|
GET /api/oauth/providers | 获取当前可用 provider 列表 |
POST /api/oauth/providers/:provider/start | 启动 OAuth 流程 |
GET /api/oauth/sessions/:state | 轮询会话状态 |
POST /api/oauth/sessions/:state/manual-callback | 手动回填 callback URL |
GET /api/oauth/connections | 列出现有连接 |
POST /api/oauth/connections/:accountId/rebind | 重绑已有 OAuth 连接 |
DELETE /api/oauth/connections/:accountId | 删除 OAuth 连接 |
脚本示例见 管理 API。
常见问题
provider 显示“当前不可用”
通常说明回调监听器不可用，或当前 provider 的启动条件不满足。优先检查：
- 服务是否刚启动但回调监听失败
- 端口是否被占用
- 当前环境是否缺少必要的 OAuth 配置
浏览器授权成功了，但页面一直停在“等待授权完成”
优先怀疑回调链路没通：
- 如果是远程服务器，先按页面提示建 SSH 隧道
- 如果不方便建隧道，直接用手动 callback 回填
- 如果 provider 页面最终没有
code/state参数，说明授权本身还没成功
OAuth 连接需要系统代理吗
有可能需要，尤其是：
- 国内服务器访问 OpenAI / Anthropic / Google OAuth 端点
- 服务器本身不能直连 provider
优先使用：
- 全局
SYSTEM_PROXY_URL - OAuth 启动 / 重绑时指定单次代理
OAuth 成功后为什么还会在站点管理看到一行站点
这是预期行为。Metapi 需要一个明确的站点记录来承载：
- 账号所属平台
- 路由与通道归属
- 后续重绑 / 刷新逻辑
它不代表你又新增了一个普通面板站点。