[codex] refresh integration and settings docs for current UI and provider coverage (#398)

* docs: refresh integration and settings guides * docs: address review follow-up
2026-04-02 17:28:27 +08:00
parent 2be0603e6f
commit 19bfed2e33
12 changed files with 977 additions and 233 deletions
@@ -1,6 +1,6 @@
 # 🔌 上游接入指南

-本文档详细说明如何将不同类型的 AI 中转站接入 Metapi。
+本文档详细说明如何将不同类型的 AI 中转站、官方兼容入口和 OAuth 连接接入 Metapi。

 [返回文档中心](./README.md)

@@ -8,12 +8,19 @@

 ## 概述

-Metapi 支持两大类上游站点：
+Metapi 当前支持三类上游接入方式：

-1. **中转聚合平台** — New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等
+1. **中转聚合平台** — New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API / CPA 等
 2. **官方 API 端点** — OpenAI / Claude (Anthropic) / Gemini (Google) 直连
+3. **官方预设与 OAuth 连接** — Coding Plan / DeepSeek / Moonshot / MiniMax / ModelScope 等官方兼容入口，以及 Codex / Claude / Gemini CLI / Antigravity 的浏览器授权登录

-每种站点类型的接入方式略有不同，本文档按站点类型分别说明。
+其中：
+
+- **平台类型** 决定协议适配和管理能力
+- **官方预设** 还是落在 `openai` / `claude` 这类平台上，但会自动带出官方地址和推荐模型
+- **OAuth 连接** 不在「站点管理」里手填账号密码，而是在「OAuth 管理」里单独授权
+
+每种接入方式略有不同，本文档按类型分别说明。

 ---

@@ -24,10 +31,19 @@ Metapi 支持两大类上游站点：
 1. **登录管理后台** — 访问 `http://your-metapi-host:4000`，使用 `AUTH_TOKEN` 登录
 2. **进入站点管理** — 点击左侧菜单「站点管理」
 3. **添加站点** — 点击「添加站点」按钮
-4. **填写站点信息** — 根据站点类型填写对应字段（见下文详细说明）
-5. **添加账号** — 站点创建后，在站点详情页添加账号凭证
+4. **填写站点信息** — 根据站点类型填写对应字段；如果是官方入口，也可以直接选择预设
+5. **添加连接** — 按场景继续添加账号、API Key，或改去「OAuth 管理」授权
 6. **验证连接** — 系统自动验证账号可用性并获取模型列表

+### 一句话判断该走哪条路
+
+| 你手上有什么 | 推荐入口 | 推荐方式 |
+|------|------|------|
+| 有后台面板的聚合站 | 站点管理 | 先加站点，再加账号 / Session |
+| 只有 Base URL + API Key 的兼容接口 | 站点管理 | 先加站点，再加 API Key |
+| 官方 Coding / API 兼容入口 | 站点管理 | 直接选择官方预设 |
+| Codex / Claude / Gemini CLI / Antigravity 的 provider 账号 | OAuth 管理 | 直接浏览器授权 |
+
 ---

 ## 📦 中转聚合平台接入
@@ -50,7 +66,7 @@ Metapi 支持两大类上游站点：

 New API 支持三种凭证类型：

-##### 1. 用户名密码登录（推荐AnyRouter使用）
+##### 1. 用户名密码登录（推荐 AnyRouter 使用）

 - **适用场景：** 有完整账号权限，需要自动签到、余额查询、账号令牌管理
 - **填写方式：**
@@ -64,9 +80,9 @@ New API 支持三种凭证类型：
 - **填写方式：**
  - 在「Access Token」字段填入以下任一格式：
    - Session Cookie：**（最不推荐）**
-    - 可通过浏览器F12获取 ![Session Cookie 获取](./screenshots/session-cookie-f12.png)
+    - 可通过浏览器 F12 获取 ![Session Cookie 获取](./screenshots/session-cookie-f12.png)
    - 一般为如下格式：`session=MTczNjQxMjM0NXxEdi1CQUFFQ180SUFBUkFCRUFBQVB2LUNBQUVHYzNSeWFXNW5EQThBRFhObGMzTnBiMjVmZEdGaWJHVUdjM1J5YVc1bkRBSUFBQT09fGRlYWRiZWVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWY=`
-    - 系统访问令牌和用户ID**（推荐非Anyrouter的其他New API站点使用）**
+    - 系统访问令牌和用户 ID **（推荐非 AnyRouter 的其他 New API 站点使用）**
    - ![](./screenshots/account-management.png)
 - **自动解析：** 系统自动识别凭证类型并提取用户信息

@@ -85,7 +101,7 @@ New API 支持三种凭证类型：
 2. 从 Session Cookie 中提取 User ID（支持 Gob 编码解析）
 3. 通过探测常见 ID 范围验证可用性

-如果以上方法都不能获取到ID，则需要用户手动获取。
+如果以上方法都不能获取到 ID，则需要用户手动获取。

 **防护盾穿透：** 自动处理阿里云盾 / Cloudflare 等 JS 挑战（`acw_sc__v2` / `cdn_sec_tc`），无需手动配置。

@@ -143,7 +159,7 @@ OneHub 继承 One API 的凭证体系，支持用户名密码、Access Token、A

 #### 账号凭证

-DoneHub 完全兼容 OneHub 的凭证体系，配置方式相同，DoneHub获取令牌位置如下图所示：![DoneHub 令牌位置](./screenshots/donehub-token.png)
+DoneHub 完全兼容 OneHub 的凭证体系，配置方式相同，DoneHub 获取令牌位置如下图所示：![DoneHub 令牌位置](./screenshots/donehub-token.png)

 ---

@@ -162,6 +178,7 @@ DoneHub 完全兼容 OneHub 的凭证体系，配置方式相同，DoneHub获取
 #### 账号凭证

 Veloera 基于 New API 架构，支持相同的凭证类型。特别注意：
+
 - Veloera 需要 `Veloera-User` 请求头，Metapi 会自动添加

 ---
@@ -182,21 +199,49 @@ Veloera 基于 New API 架构，支持相同的凭证类型。特别注意：

 Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。按下面步骤进行添加：

-首先去中转站点F12打开如下界面：
+首先去中转站点 F12 打开如下界面：

 ![Sub2API 认证字段示例](./screenshots/sub2api-auth-f12.png)

-然后回到Metapi账号添加处：
+然后回到 Metapi 账号添加处：

 ![Sub2API Session 配置](./screenshots/sub2api-session-config.png)

-1. 在「凭证模式」里选择 Session 模式，分别粘贴F12界面中的auth_token、refresh_token、token_expires_at字段进行验证，无需配置用户ID。
+1. 在「凭证模式」里选择 Session 模式，分别粘贴 F12 界面中的 `auth_token`、`refresh_token`、`token_expires_at` 字段进行验证，无需配置用户 ID。
 2. 不要使用账号密码登录，Metapi 不支持代替 Sub2API 做登录
 3. Sub2API 通常为订阅制使用，不支持签到；如果你只关心代理调用，也可以直接改用 API Key 模式
 4. 若 `GET /v1/models` 为空，先确认该账号下已有可用用户 API Key，Metapi 会再尝试用它发现模型

 ---

+### CLIProxyAPI / CPA
+
+**适用平台：** CLIProxyAPI / CPA 一类标准 API provider
+
+#### 站点配置
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| **站点名称** | 自定义名称 | `本地 CPA` |
+| **站点 URL** | CPA 暴露的 Base URL | `http://127.0.0.1:8317` |
+| **平台类型** | 选择 `cliproxyapi` | - |
+
+#### 账号凭证
+
+CPA 这类站点推荐直接使用 **API Key**：
+
+- 在「API Token」字段填入 CPA 提供的密钥
+- 不建议把它当成可签到、可查余额、可账号登录的传统面板站
+
+#### 特殊说明
+
+- 本地默认地址常见为 `http://127.0.0.1:8317`
+- 远端实例也可能通过 `cliproxy` / `cpa` 风格 URL 或响应头被自动识别
+- 当前重点支持 **模型发现** 与 **代理调用**
+- 不支持用户名密码登录、自动签到、站点余额 / 用户信息抓取
+
+---
+
 ## 🌐 官方 API 端点接入

 ### OpenAI
@@ -215,6 +260,7 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。
 #### 账号凭证

 **仅支持 API Key：**
+
 - 在「API Token」字段填入：`sk-proj-xxxxxxxxxxxxxx`
 - 不支持用户名密码登录（OpenAI 无此接口）

@@ -245,6 +291,7 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。
 #### 账号凭证

 **仅支持 API Key：**
+
 - 在「API Token」字段填入：`sk-ant-api03-xxxxxxxxxxxxxx`

 #### 功能限制
@@ -276,6 +323,7 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。
 #### 账号凭证

 **仅支持 API Key：**
+
 - 在「API Token」字段填入：`AIzaSyxxxxxxxxxxxxxx`

 #### 功能限制
@@ -292,6 +340,71 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。

 ---

+## 🧩 官方兼容预设（推荐）
+
+除了手动选择 `openai` / `claude` 平台，现在站点编辑器里还内置了一批**官方预设**。这类预设更适合：
+
+- 直接接官方兼容入口
+- 自动填入官方推荐 URL
+- 先用 API Key 初始化，再补推荐模型
+- 保留接入语义，后续创建完站点后更容易知道下一步怎么配
+
+### 当前内置预设
+
+| 预设 | 底层平台 | 默认地址 | 推荐说明 |
+|------|------|------|------|
+| 阿里云 CodingPlan / OpenAI | `openai` | `https://coding.dashscope.aliyuncs.com/v1` | 推荐先加 API Key，再补编程模型 |
+| 阿里云 CodingPlan / Claude | `claude` | `https://coding.dashscope.aliyuncs.com/apps/anthropic` | 适合 Claude Code 一类工具直连 |
+| 智谱 Coding Plan / OpenAI | `openai` | `https://open.bigmodel.cn/api/coding/paas/v4` | 推荐先加 API Key，再补 GLM 编程模型 |
+| 智谱 Coding Plan / Claude | `claude` | `https://open.bigmodel.cn/api/anthropic` | 当前更适合手动选择预设 |
+| DeepSeek / OpenAI | `openai` | `https://api.deepseek.com/v1` | 适合直接接 DeepSeek 官方兼容入口 |
+| DeepSeek / Claude | `claude` | `https://api.deepseek.com/anthropic` | 适合 Claude 兼容用法 |
+| Moonshot(Kimi) / OpenAI | `openai` | `https://api.moonshot.cn/v1` | 适合 Kimi 官方 OpenAI 兼容入口 |
+| Moonshot(Kimi) / Claude | `claude` | `https://api.moonshot.cn/anthropic` | 适合 Claude 兼容用法 |
+| MiniMax / OpenAI | `openai` | `https://api.minimaxi.com/v1` | 推荐先加 API Key |
+| MiniMax / Claude | `claude` | `https://api.minimaxi.com/anthropic` | 适合 Claude Code 兼容入口 |
+| ModelScope / OpenAI | `openai` | `https://api-inference.modelscope.cn/v1` | 适合开源编程模型兼容接入 |
+| ModelScope / Claude | `claude` | `https://api-inference.modelscope.cn` | 适合 Claude 兼容接入 |
+| 豆包 Coding Plan / OpenAI | `openai` | `https://ark.cn-beijing.volces.com/api/coding/v3` | 适合火山方舟 Coding Plan |
+
+#### 使用建议
+
+1. 选中预设后，优先保留它自动填好的 URL
+2. 如果你只是接一个普通自建网关，不想保留预设语义，再手动改回通用 `openai` / `claude`
+3. 对官方预设来说，**不要机械地把 `/v1` 或 `/anthropic` 删掉**，以预设默认值为准
+
+---
+
+## 🔐 OAuth 连接接入
+
+有些 provider 更适合在左侧菜单 **OAuth 管理** 里直接授权，而不是在「站点管理 → 账号管理」里手填凭证。
+
+### 当前推荐走 OAuth 的 provider
+
+| Provider | 对应平台 | 自动创建的站点名 | 适用说明 |
+|------|------|------|------|
+| Codex | `codex` | `ChatGPT Codex OAuth` | 直接授权 Codex 账号 |
+| Claude | `claude` | `Anthropic Claude OAuth` | 直接授权 Claude / Anthropic 账号 |
+| Gemini CLI | `gemini-cli` | `Google Gemini CLI OAuth` | 支持浏览器授权，可选 Project ID |
+| Antigravity | `antigravity` | `Google Antigravity OAuth` | 适合 Antigravity provider 登录 |
+
+#### 什么时候应该走 OAuth
+
+- 你接的不是一个普通面板站，而是 provider 自己的账号
+- 你不想手填 Cookie / Session / API Key
+- 你希望后续刷新、重绑也继续走 provider 官方授权流程
+
+#### 使用建议
+
+1. 进入左侧菜单 **OAuth 管理**
+2. 选择对应 provider 发起授权
+3. 如果是远程部署，按页面提示使用 SSH 隧道或手动回填 callback URL
+4. 授权成功后，Metapi 会自动创建或复用对应站点与连接
+
+完整流程见 [OAuth 管理](./oauth.md)。
+
+---
+
 ## 🔧 高级配置

 ### 站点级代理
@@ -303,6 +416,7 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。
 ```

 **配置方式：**
+
 1. 在站点编辑页面填写「代理 URL」字段
 2. 格式：`http://proxy-host:port` 或 `socks5://proxy-host:port`
 3. 支持 HTTP / HTTPS / SOCKS5 代理
@@ -324,17 +438,62 @@ Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。
 **适用场景：** 某些站点的签到接口非标准路径，或需要通过外部服务触发签到。

 **配置方式：**
+
 1. 在站点编辑页面填写「外部签到 URL」
 2. Metapi 会向该 URL 发送 POST 请求执行签到
 3. 请求头自动携带账号凭证

+### AI 请求地址池
+
+现在不少站点已经不是“一个 URL 同时负责后台面板和 `/v1/*` AI 请求”。
+
+Metapi 当前支持把这两层拆开：
+
+- **主站点 URL**：用于登录、签到、后台接口、系统访问令牌管理
+- **AI 请求地址池**：用于真正转发 `/v1/*`、`/chat/completions`、`/responses` 等模型请求
+
+适合填写 AI 请求地址池的场景：
+
+1. 控制台地址和 AI 网关地址不同
+2. 同一个站点有多个 API host，需要健康切换
+3. 你想保留面板地址不变，只把模型流量导向专用网关
+
+简单理解：
+
+```text
+主站点 URL = 控制面
+AI 请求地址池 = 数据面
+```
+
 ---

 ## 🔍 站点自动检测

-Metapi 支持自动识别站点类型，检测优先级如下：
+Metapi 支持自动识别站点类型，当前检测优先级如下：

-### 1. URL 特征检测
+### 1. 官方预设检测
+
+下列地址会优先识别成官方预设，并返回 `initializationPresetId`：
+
+| URL / 特征 | 识别结果 |
+|------|------|
+| `coding.dashscope.aliyuncs.com/v1` | `codingplan-openai` |
+| `coding.dashscope.aliyuncs.com/apps/anthropic` | `codingplan-claude` |
+| `open.bigmodel.cn/api/coding/paas/v4` | `zhipu-coding-plan-openai` |
+| `api.deepseek.com/v1` | `deepseek-openai` |
+| `api.deepseek.com/anthropic` | `deepseek-claude` |
+| `api.moonshot.cn/v1` | `moonshot-openai` |
+| `api.moonshot.cn/anthropic` | `moonshot-claude` |
+| `api.minimaxi.com/v1` | `minimax-openai` |
+| `api.minimaxi.com/anthropic` | `minimax-claude` |
+| `api-inference.modelscope.cn/v1` | `modelscope-openai` |
+| `api-inference.modelscope.cn` | `modelscope-claude` |
+| `ark.cn-beijing.volces.com/api/coding/v3` | `doubao-coding-openai` |
+
+> [!NOTE]
+> 智谱 Coding Plan 的 Claude 兼容入口当前不会按 URL 强制自动识别，更适合手动选预设。
+
+### 2. URL 特征检测

 根据 URL 中的关键字自动识别：

@@ -343,24 +502,28 @@ Metapi 支持自动识别站点类型，检测优先级如下：
 | `api.openai.com` | OpenAI |
 | `api.anthropic.com` | Claude |
 | `generativelanguage.googleapis.com` | Gemini |
+| `chatgpt.com/backend-api/codex` | Codex |
+| `127.0.0.1:8317` / `localhost:8317` / `cliproxy` | CLIProxyAPI / CPA |
 | `anyrouter` | AnyRouter |
 | `donehub` / `done-hub` | DoneHub |
 | `onehub` / `one-hub` | OneHub |
 | `veloera` | Veloera |
 | `sub2api` | Sub2API |

-### 2. 页面标题检测
+### 3. 页面标题检测

 访问站点首页，解析 `<title>` 标签识别平台类型。

-### 3. API 探测
+### 4. API 探测

 依次尝试各平台的特征接口：
+
 - New API：`/api/status` 返回 `system_name`
 - One API：`/api/status` 返回特定结构
 - OpenAI：`/v1/models` 返回模型列表
+- CPA：`/v0/management/openai-compatibility` 返回兼容信息或特征响应头

-**手动指定：** 如果自动检测失败，可在添加站点时手动选择平台类型。
+**手动指定：** 如果自动检测失败，可在添加站点时手动选择平台类型或直接选择官方预设。

 ---

@@ -403,11 +566,16 @@ Metapi 会定期抓取已接入站点的公告，并在首次发现时写入站
 ### 问题：添加站点后无法获取模型列表

 **可能原因：**
-1. 站点 URL 填写错误（检查是否包含 `/v1` 后缀，应去除）
+
+1. 站点 URL 填写错误
+   - 通用平台常见是填根地址，错误地带上了不该带的 `/v1`
+   - 官方预设则相反，**不要**把预设自动带出的 `/v1` / `/anthropic` / `/api/coding/...` 手动删掉
 2. 网络不通（检查代理配置或防火墙）
-3. 凭证无效（重新验证账号密码或 Token）
+3. 凭证无效（重新验证账号密码、Session 或 API Key）
+4. 主站点 URL 和真实 AI 请求地址不同，但还没配置 AI 请求地址池

 **解决方法：**
+
 - 在站点详情页点击「测试连接」
 - 查看「事件日志」中的错误信息
 - 检查「代理日志」中的请求详情
@@ -417,22 +585,44 @@ Metapi 会定期抓取已接入站点的公告，并在首次发现时写入站
 **原因：** 该站点是 New API 衍生版本，需要 User ID。

 **解决方法：**
+
 1. Metapi 会自动探测 User ID，通常无需手动配置
 2. 如果自动探测失败，可在账号编辑页面的「额外配置」中手动填写：
+
   ```json
   {
     "platformUserId": 12345
   }
   ```

+### 问题：CPA 为什么没有账号登录、签到、余额刷新
+
+**原因：** `cliproxyapi` / CPA 在 Metapi 里按标准 API provider 处理，重点支持模型发现与代理调用，不按传统面板站处理。
+
+**解决方法：**
+
+- 直接使用 API Key 模式
+- 不要再按「用户名密码登录 + 自动签到」的思路排查
+
+### 问题：什么时候不该再用账号管理，而应该去 OAuth 管理
+
+**原因：** 你接的不是普通面板站，而是 provider 自己的授权账号。
+
+**解决方法：**
+
+- Codex / Claude / Gemini CLI / Antigravity 这类连接直接去左侧 **OAuth 管理**
+- 不要在账号管理里反复尝试 Cookie / Session / API Key 兜底
+
 ### 问题：签到失败

 **可能原因：**
+
 1. 凭证过期（Access Token 有效期到期）
 2. 站点签到接口变更
 3. 已经签到过（部分站点限制每日一次）

 **解决方法：**
+
 - 查看「签到记录」中的失败原因
 - 尝试重新登录获取新凭证
 - 配置「外部签到 URL」使用备用签到方式
@@ -442,8 +632,9 @@ Metapi 会定期抓取已接入站点的公告，并在首次发现时写入站
 **原因：** 不同平台的余额单位不同。

 **说明：**
+
 - New API 系列：余额单位为「美元」，内部存储为 `quota / 500000`
- OpenAI / Claude / Gemini：官方 API 无余额查询接口，显示为 `N/A`
+- OpenAI / Claude / Gemini / CPA：官方或兼容 API 通常无余额查询接口，显示为 `N/A`

 ---

@@ -453,40 +644,46 @@ Metapi 会定期抓取已接入站点的公告，并在首次发现时写入站

 | 场景 | 推荐凭证类型 | 原因 |
 |------|-------------|------|
-| 个人站点，需要完整功能 | 用户名密码 | 支持自动签到、账号令牌管理 |
+| 个人站点，需要完整功能 | 用户名密码 / Access Token | 支持自动签到、账号令牌管理 |
 | 共享账号，只读权限 | Access Token | 避免密码泄露 |
 | 仅用于模型调用 | API Token | 最小权限原则 |
+| Provider 原生账号 | OAuth | 更适合后续刷新、重绑与统一管理 |

 ### 2. 站点命名规范

 建议使用清晰的命名规则，便于管理：

-```
+```text
 [平台类型] - [站点特征] - [用途]
 ```

 示例：
+
 - `New API - 主站 - 生产环境`
 - `OneHub - 备用 - 测试`
 - `OpenAI - 官方 - 高优先级`
+- `CPA - 本地 - 调试`

 ### 3. 代理配置策略

- **国内访问 OpenAI / Claude / Gemini：** 必须配置代理
+- **国内访问 OpenAI / Claude / Gemini / 部分 OAuth provider：** 通常需要代理
 - **国内中转站：** 通常不需要代理
 - **海外中转站：** 根据网络情况选择
+- **远程 OAuth 部署：** 除了代理，还要考虑回调端口连通性

 ### 4. 定期维护

 - **每周检查：** 账号健康状态、余额预警
 - **每月清理：** 禁用长期不可用的站点和账号
 - **凭证轮换：** 定期更新 Access Token 和 API Key
+- **官方预设站点：** 新增模型时记得补充推荐模型和 AI 请求地址池

 ---

 ## 🔗 相关文档

 - [配置说明](./configuration.md) — 环境变量与路由参数
+- [OAuth 管理](./oauth.md) — Codex / Claude / Gemini CLI / Antigravity 授权接入
 - [客户端接入](./client-integration.md) — 下游应用配置
 - [常见问题](./faq.md) — 故障排查与优化建议

@@ -498,3 +695,4 @@ Metapi 会定期抓取已接入站点的公告，并在首次发现时写入站
 - 支持同时接入多个相同类型的站点（如多个 New API 实例）
 - 站点禁用后，关联的所有账号和路由通道会自动禁用
 - 删除站点会级联删除所有关联账号、Token 和路由配置，请谨慎操作
+- 如果你看到站点创建成功后的“官方预设”提示，请按它建议的下一步走，一般会更省事