[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,7 +1,18 @@
+# Required in production: generate a unique 32+ byte random secret in your local .env, keep it out of git, and do not reuse AUTH_TOKEN.
+ACCOUNT_CREDENTIAL_SECRET=REPLACE_WITH_STRONG_RANDOM_SECRET
 AUTH_TOKEN=change-me-admin-token
-PROXY_TOKEN=change-me-proxy-sk-token
 CHECKIN_CRON=0 8 * * *
 BALANCE_REFRESH_CRON=0 * * * *
+# Optional OAuth overrides. Fill the matching credentials when an override is enabled; Claude requires a client secret with no fallback.
+CLAUDE_CLIENT_ID=
+CLAUDE_CLIENT_SECRET=
+# Codex OAuth override only needs CODEX_CLIENT_ID.
+CODEX_CLIENT_ID=
+# Gemini CLI override requires both GEMINI_CLI_CLIENT_ID and GEMINI_CLI_CLIENT_SECRET together.
+GEMINI_CLI_CLIENT_ID=
+GEMINI_CLI_CLIENT_SECRET=
+PROXY_TOKEN=change-me-proxy-sk-token
+SYSTEM_PROXY_URL=
 WEBHOOK_URL=
 BARK_URL=
 SERVERCHAN_KEY=
@@ -82,15 +82,14 @@

 现在 AI 生态里有越来越多基于 New API / One API 系列的聚合中转站，要管理多个站点的余额、模型列表和 API 密钥，往往既分散又费时。

-**Metapi** 作为这些中转站之上的**元聚合层（Meta-Aggregation Layer）**，把多个站点统一到 **一个入口（可按项目配置多个下游 API Key）**——下游所有工具（Cursor、Claude Code、Codex、Open WebUI 等）即可无感接入全部模型。当前已支持以下上游平台：
+**Metapi** 作为这些中转站之上的**元聚合层（Meta-Aggregation Layer）**，把多个站点统一到 **一个入口（可按项目配置多个下游 API Key）**——下游所有工具（Cursor、Claude Code、Codex、Open WebUI 等）即可无感接入全部模型。当前支持的上游范围已经不止传统聚合面板，还包括：

- [New API](https://github.com/QuantumNous/new-api)
- [One API](https://github.com/songquanpeng/one-api)
- [OneHub](https://github.com/MartialBE/one-hub)
- [DoneHub](https://github.com/deanxv/done-hub)
- [Veloera](https://github.com/Veloera/Veloera)
- [AnyRouter](https://anyrouter.top) — 通用路由平台
- [Sub2API](https://github.com/Wei-Shaw/sub2api) — 订阅制中转
+- 聚合面板： [New API](https://github.com/QuantumNous/new-api)、[One API](https://github.com/songquanpeng/one-api)、[OneHub](https://github.com/MartialBE/one-hub)、[DoneHub](https://github.com/deanxv/done-hub)、[Veloera](https://github.com/Veloera/Veloera)、[AnyRouter](https://anyrouter.top)、[Sub2API](https://github.com/Wei-Shaw/sub2api)
+- 通用兼容接口：OpenAI / Claude / Gemini compatible endpoints，以及 `cliproxyapi` / CPA
+- 官方预设：阿里云 / 智谱 / 豆包 Coding Plan，DeepSeek，Moonshot(Kimi)，MiniMax，ModelScope
+- OAuth 连接：Codex、Claude、Gemini CLI、Antigravity
+
+详细接法见 [上游接入](./docs/upstream-integration.md) 与 [OAuth 管理](./docs/oauth.md)。

 | 痛点                                  | Metapi 怎么解决                                                        |
 | ------------------------------------- | ---------------------------------------------------------------------- |
@@ -58,6 +58,7 @@ export default withMermaid(
        { text: '首页', link: '/' },
        { text: '快速上手', link: '/getting-started' },
        { text: '上游接入', link: '/upstream-integration' },
+        { text: 'OAuth 管理', link: '/oauth' },
        { text: 'FAQ', link: '/faq' },
        { text: '文档维护', link: '/README' },
        { text: '项目主页', link: 'https://github.com/cita-777/metapi' },
@@ -75,6 +76,7 @@ export default withMermaid(
          text: '使用与运维',
          items: [
            { text: '上游接入', link: '/upstream-integration' },
+            { text: 'OAuth 管理', link: '/oauth' },
            { text: '配置说明', link: '/configuration' },
            { text: 'K3s 更新中心（高级）', link: '/k3s-update-center' },
            { text: '客户端接入', link: '/client-integration' },
@@ -28,10 +28,11 @@ npm run docs:build
 |------|--------|------------|
 | 对外第一印象、产品定位、核心入口 | [文档首页](/) | 需要调整公开落地页信息架构、首页 CTA 或首屏导航时 |
 | 新用户部署与首条请求 | [快速上手](./getting-started.md) | 新安装流程、默认端口、首次调用步骤变化时 |
-| 上游平台选择与接法 | [上游接入](./upstream-integration.md) | 平台支持范围、默认连接分段、自动识别规则变化时 |
+| 上游平台选择与接法 | [上游接入](./upstream-integration.md) | 平台支持范围、官方预设、AI 请求地址池、自动识别规则变化时 |
+| Provider OAuth 授权 | [OAuth 管理](./oauth.md) | 支持的 OAuth provider、授权流程、回调方式或自动重绑能力变化时 |
 | 生产部署与回滚 | [部署指南](./deployment.md) | Docker Compose、反向代理、升级回滚策略变更时 |
 | K3s / Helm 高级升级面板 | [K3s 更新中心（高级）](./k3s-update-center.md) | 需要说明谁适合使用更新中心、helper 怎么配、K3s/Helm 发布链路怎么接入时 |
-| 环境变量、参数和配置项 | [配置说明](./configuration.md) | 新增配置、默认值变化、兼容行为变化时 |
+| 环境变量、参数和配置项 | [配置说明](./configuration.md) | 设置页 / 通知设置 / 下游密钥这些 UI 入口变化，或仅剩 env-only 的部署级参数变化时 |
 | 客户端与工具接入 | [客户端接入](./client-integration.md) | Open WebUI、Cherry Studio、Cursor 等接入方式变化时 |
 | 管理后台脚本化调用 | [管理 API](./management-api.md) | 需要说明如何用脚本批量导入站点/账号，或对接外部自动化时 |
 | 运维排障与日常维护 | [运维手册](./operations.md) / [常见问题](./faq.md) | 新排障案例、备份恢复、健康检查、典型报错变化时 |
@@ -1,56 +1,172 @@
 # ⚙️ 配置说明

-本文档列出 Metapi 的环境变量，并单独说明管理后台中的运行时设置。
+本文档按实际使用场景说明 Metapi 的配置入口。
+
+对大多数用户来说，日常配置优先通过管理后台完成；环境变量主要用于首次启动、部署级参数和当前没有 UI 的高级项。

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

 ---

-## 配置来源
+## 概述

-| 配置类型 | 入口 | 生效方式 | 适用场景 |
-|----------|------|----------|----------|
-| 环境变量 | `.env` / 容器环境变量 | 服务启动时读取，作为启动配置或默认值 | 部署、容器编排、首次初始化 |
-| 运行时设置 | 管理后台「设置」 | 持久化到当前运行数据库；大部分即时生效，数据库运行配置保存后需重启 | 在线调整、运维排障 |
+Metapi 当前有三类主要配置入口：

-## 必填配置
+1. **管理后台「设置」** — 适合日常系统设置与运行时调整
+2. **管理后台「通知设置」与「下游密钥」** — 适合通知渠道和项目级下游 Key 管理
+3. **环境变量** — 适合首次启动、部署级参数、OAuth client 覆盖、Deploy Helper token 等当前没有 UI 的项

-> ⚠️ 以下变量**必须修改**，不要使用默认值。
+下表可用于快速判断：
+
+| 你要改什么 | 优先去哪里 | 说明 |
+|----------|------------|------|
+| 日常系统设置 | 管理后台「设置」 | 大部分运行时配置都在这里，保存后直接生效或按提示重启 |
+| 通知渠道 | 管理后台「通知设置」 | Webhook / Bark / Server酱 / Telegram / SMTP 都有 UI |
+| 下游项目级 Key | 管理后台「下游密钥」 | 不要再回到环境变量里硬塞 |
+| 首次启动令牌、端口、数据目录 | `.env` / 容器环境变量 | 这类属于部署级初始化 |
+| OAuth 客户端 ID / Secret | `.env` / 容器环境变量 | 当前没有 UI |
+| Deploy Helper token / helper 进程参数 | `.env` / helper manifest | 当前没有 UI，且属于集群侧部署参数 |
+| 少数高级部署级参数 | `.env` / 容器环境变量 | 例如日志保留、部分探测细粒度参数 |
+
+---
+
+## 配置入口总览
+
+### 1. 管理后台「设置」
+
+侧边栏入口：**系统 → 设置**
+
+当前已经能直接在这里配置的内容包括：
+
+| UI 项 | 对应能力 | 生效方式 |
+|------|----------|----------|
+| 管理员登录令牌 | `AUTH_TOKEN` 的后续修改 | 保存后即时生效 |
+| 定时任务 | `CHECKIN_CRON`、`BALANCE_REFRESH_CRON`、日志清理计划 | 保存后即时生效 |
+| 系统代理 | `SYSTEM_PROXY_URL` | 保存后即时生效 |
+| 代理失败判定 | 失败关键词、空内容失败判定 | 保存后即时生效 |
+| Codex 上游传输与会话并发 | WebSocket 开关、并发与队列参数 | 保存后即时生效 |
+| 批量测活 | 后台模型可用性探测开关 | 保存后即时生效 |
+| 下游访问令牌 | `PROXY_TOKEN` | 保存后即时生效 |
+| 路由策略 | 成本/余额/使用率权重、默认单价、首字超时、协议回退、失败冷却上限 | 保存后即时生效 |
+| 全局品牌屏蔽 | 全局品牌屏蔽 | 保存后即时生效，并触发路由重建 |
+| 全局模型白名单 | 全局模型白名单 | 保存后即时生效，并触发路由重建 |
+| 数据库迁移 / 运行数据库 | `DB_TYPE`、`DB_URL`、`DB_SSL` | 保存后下次后端重启生效 |
+| 更新中心 | K3s / Helm 更新中心配置 | 保存后即时生效 |
+| 会话与安全 | `ADMIN_IP_ALLOWLIST` | 保存后即时生效 |
+
+> [!TIP]
+> `AUTH_TOKEN` 和 `PROXY_TOKEN` 并不是“只能靠环境变量改”的配置。
+> 正常情况下，**首次启动先给一个值，后续都可以在 UI 里改**。
+
+### 2. 管理后台「通知设置」
+
+侧边栏入口：**系统 → 通知设置**
+
+当前已经有独立页面可直接配置：
+
+| UI 项 | 说明 | 生效方式 |
+|------|------|----------|
+| Webhook | 企业微信 / 飞书 / 通用 Webhook | 保存后即时生效 |
+| Bark | Bark 推送地址与开关 | 保存后即时生效 |
+| Server酱 | SendKey 与开关 | 保存后即时生效 |
+| Telegram | API Base URL、Chat ID、Topic ID、Bot Token、是否走系统代理 | 保存后即时生效 |
+| SMTP | SMTP 主机、端口、账号、密码、发件/收件地址 | 保存后即时生效 |
+| 告警冷静期 | `NOTIFY_COOLDOWN_SEC` | 保存后即时生效 |
+
+通知设置页面已经支持：
+
+- 直接保存
+- 直接发测试通知
+- 屏蔽回显已保存的敏感字段
+
+通知配置可直接在该页面完成，无需先记环境变量名。
+
+### 3. 管理后台「下游密钥」
+
+侧边栏入口：**控制台 → 下游密钥**
+
+「下游密钥」页面负责的是项目级下游 API Key，而不是全局 `PROXY_TOKEN`。
+
+适合在这里配置的内容：
+
+- Key 名称
+- 过期时间
+- 费用 / 请求上限
+- 模型白名单
+- 路由白名单
+- 站点权重倍率
+- 启停、重置用量、趋势与统计
+
+这类能力可直接在页面里完成，不需要额外依赖环境变量。
+
+---
+
+## 首次启动时，至少准备这些环境变量
+
+**首次把服务跑起来**时，建议先在环境变量里准备以下几项：

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
-| `AUTH_TOKEN` | 管理后台登录令牌 | `change-me-admin-token` |
-| `PROXY_TOKEN` | 代理接口 Bearer Token（下游客户端使用此值作为 API Key） | `change-me-proxy-sk-token` |
+| `AUTH_TOKEN` | 初始管理员登录令牌 | `change-me-admin-token` |
+| `PROXY_TOKEN` | 初始下游访问令牌 | `change-me-proxy-sk-token` |
+| `PORT` | 服务监听端口 | `4000` |
+| `DATA_DIR` | 数据目录（SQLite 默认落这里） | `./data` |
+| `TZ` | 时区 | `Asia/Shanghai` |

-## 基础配置
+说明：
+
+- `AUTH_TOKEN` 只是**第一次登录前**必须要有；登录后可以去「设置」里改。
+- `PROXY_TOKEN` 也只是建议先给一个初始值；后续可以在「设置」里改。
+- `PORT`、`DATA_DIR`、`TZ` 这类属于部署级参数，更适合留在环境变量。
+
+---
+
+## 环境变量配置
+
+### 1. 启动与部署级
+
+这类配置要么属于进程启动参数，要么属于当前确实没有 UI 的部署项：

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
 | `PORT` | 服务监听端口 | `4000` |
 | `DATA_DIR` | 数据目录（SQLite 数据库存储位置） | `./data` |
 | `TZ` | 时区 | `Asia/Shanghai` |
-| `SYSTEM_PROXY_URL` | 系统代理 URL（留空表示不使用） | 空 |
 | `ACCOUNT_CREDENTIAL_SECRET` | 账号凭证加密密钥（用于加密存储的上游账号密码） | 默认使用 `AUTH_TOKEN` |

-## 更新中心与 Deploy Helper
+### 2. OAuth 与 Provider 登录

-如果你现在只是一个普通 Docker / Docker Compose 部署，没有 K3s / Kubernetes、没有 Helm release、也没有 Deploy Helper，那么这一节可以先跳过。
+这一节只在你需要覆盖默认 OAuth client 配置时才看。

-这一节只写给已经准备使用“K3s 更新中心”的用户。除了设置页里的运行时字段，还需要补齐主服务和 helper 的环境变量。
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `CODEX_CLIENT_ID` | 覆盖内置 Codex OAuth Client ID | 内置默认值 |
+| `CLAUDE_CLIENT_ID` | 覆盖内置 Claude OAuth Client ID | 内置默认值 |
+| `CLAUDE_CLIENT_SECRET` | 预留的 Claude OAuth Client Secret（默认留空） | 空 |
+| `GEMINI_CLI_CLIENT_ID` | 覆盖内置 Gemini CLI OAuth Client ID | 内置默认值 |
+| `GEMINI_CLI_CLIENT_SECRET` | 覆盖内置 Gemini CLI OAuth Client Secret | 内置默认值 |

-如果你是老用户，正在从 Docker Compose 迁到 K3s / Helm，这一节可以提前看，先把迁移后的环境变量和组件关系理解清楚。
+说明：

-### 主 Metapi 服务
+- `Antigravity` 当前不需要额外环境变量即可启用。
+- 如果你的部署环境访问 provider 受限，优先先在 UI 里配置**系统代理**。
+- 如果 OAuth 页面运行在远程服务器上，还要考虑 SSH 隧道或手动回填 callback，详见 [OAuth 管理](./oauth.md)。
+
+### 3. K3s 更新中心与 Deploy Helper
+
+这里要分清楚两层：
+
+- **主 Metapi 后台里的日常更新中心配置**：优先在 UI 里填
+- **主服务访问 helper 的 token / helper 自己的监听参数**：仍然是环境变量
+
+#### 主 Metapi 服务

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
 | `DEPLOY_HELPER_TOKEN` | 主服务访问 Deploy Helper 的 Bearer Token | 空 |
 | `UPDATE_CENTER_HELPER_TOKEN` | `DEPLOY_HELPER_TOKEN` 的兼容别名，二选一即可 | 空 |

-> [!IMPORTANT]
-> 主 Metapi 和 Deploy Helper 必须使用同一个 token，否则更新中心可以显示页面但无法完成 helper 状态查询或部署。
-
-### Deploy Helper 服务
+#### Deploy Helper 服务

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
@@ -58,9 +174,11 @@
 | `DEPLOY_HELPER_PORT` | helper 监听端口 | `9850` |
 | `DEPLOY_HELPER_TOKEN` | helper Bearer Token，必须和主服务一致 | 空 |

-### 设置页里的持久化字段
+#### 更新中心里真正建议在 UI 配的字段

-更新中心页面本身还会把下面这些字段持久化到运行数据库：
+这些字段不建议再教用户去改 env，而是直接去：
+
+**设置 → 更新中心**

 - `helperBaseUrl`
 - `namespace`
@@ -71,161 +189,101 @@
 - `dockerHubTagsEnabled`
 - `defaultDeploySource`

-完整接入步骤见：
+完整接入步骤见 [K3s 更新中心（高级）](./k3s-update-center.md)。

- [K3s 更新中心](./k3s-update-center.md)
+### 4. 当前没有 UI 的高级部署级参数

-## 数据库配置
+下面这些参数目前更偏部署级，仍然建议通过环境变量维护：

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
-| `DB_TYPE` | 运行数据库类型：`sqlite` / `mysql` / `postgres` | `sqlite` |
-| `DB_URL` | 数据库连接串；使用 `mysql` / `postgres` 时必填 | 空 |
-| `DB_SSL` | 连接 MySQL / Postgres 时启用 SSL | `false` |
+| `TOKEN_ROUTER_CACHE_TTL_MS` | Token 路由缓存 TTL（毫秒） | `1500` |
+| `PROXY_LOG_RETENTION_DAYS` | 代理日志保留天数 | `30` |
+| `PROXY_LOG_RETENTION_PRUNE_INTERVAL_MINUTES` | 代理日志清理任务执行间隔（分钟） | `30` |
+| `MODEL_AVAILABILITY_PROBE_INTERVAL_MS` | 批量测活间隔（毫秒） | `1800000` |
+| `MODEL_AVAILABILITY_PROBE_TIMEOUT_MS` | 批量测活单次探测超时（毫秒） | `15000` |
+| `MODEL_AVAILABILITY_PROBE_CONCURRENCY` | 批量测活并发数 | `1` |

-`DB_TYPE=sqlite` 时，`DB_URL` 留空即可，服务会使用默认 SQLite 路径。
+注意：

-## 定时任务
+- **批量测活开关本身**已经在 UI 里有了
+- 这里只剩下间隔、超时、并发这些更高级的细项还没有 UI

-| 变量名 | 说明 | 默认值 | 示例 |
-|--------|------|--------|------|
-| `CHECKIN_CRON` | 自动签到计划 | `0 8 * * *` | 每天 8:00 |
-| `BALANCE_REFRESH_CRON` | 余额刷新计划 | `0 * * * *` | 每小时整点 |
+---

-Cron 表达式格式：`分 时 日 月 周`（标准五段式）
+## 常见配置与入口对照

-常用示例：
- `0 8 * * *` — 每天 08:00
- `0 */2 * * *` — 每 2 小时
- `30 7,12,20 * * *` — 每天 07:30、12:30、20:30
+### 通常已经有 UI 的配置

-## 智能路由
+- 管理员令牌
+- 下游访问令牌
+- 系统代理
+- 定时任务
+- 路由策略
+- 批量测活开关
+- 安全白名单
+- 通知渠道
+- 下游密钥
+- 数据库运行配置
+- 更新中心主体配置

-Metapi 的路由引擎按多因子加权选择最优通道。
+### 通常仍需看环境变量的配置

-### 成本信号优先级
+- 端口
+- 数据目录
+- 时区
+- 账号凭证加密密钥
+- OAuth client 覆盖
+- Deploy Helper token
+- helper 进程自身监听参数
+- 少数高级部署级性能 / 清理参数

-```
-实测成本（代理日志） → 账号配置成本 → 目录参考价 → 兜底默认值
-```
+---

-### 路由权重参数
+## UI 与环境变量的关系

-| 变量名 | 说明 | 默认值 | 范围 |
-|--------|------|--------|------|
-| `ROUTING_FALLBACK_UNIT_COST` | 无成本信号时的默认单价 | `1` | > 0 |
-| `BASE_WEIGHT_FACTOR` | 基础权重因子 | `0.5` | 0~1 |
-| `VALUE_SCORE_FACTOR` | 性价比评分因子 | `0.5` | 0~1 |
-| `COST_WEIGHT` | 成本权重（越大越偏向低成本通道） | `0.4` | 0~1 |
-| `BALANCE_WEIGHT` | 余额权重（越大越偏向余额充足的通道） | `0.3` | 0~1 |
-| `USAGE_WEIGHT` | 使用率权重（越大越偏向使用较少的通道） | `0.3` | 0~1 |
+Metapi 当前的配置关系可以概括为：

-> 三个权重之和建议为 1.0，但不强制。
+1. **环境变量负责启动默认值和部署参数**
+2. **UI 负责用户日常操作和运行时调整**
+3. **UI 保存后的值会持久化到当前运行数据库**
+4. **大多数 UI 设置会覆盖原始默认值**

-### 路由缓存
+例外主要有两类：

-| 变量名 | 说明 | 默认值 | 范围 |
-|--------|------|--------|------|
-| `TOKEN_ROUTER_CACHE_TTL_MS` | Token 路由缓存 TTL（毫秒） | `1500` | >= 100 |
+- **纯部署级参数**：例如端口、数据目录
+- **保存后需重启的配置**：例如运行数据库类型 / 连接串 / SSL

-### 模型弹活探测
+---

-用于异步校正“上游 `/models` 能看到，但实际调用不可用”的假阳性模型。
+## 通知渠道详细说明

-| 变量名 | 说明 | 默认值 | 范围 |
-|--------|------|--------|------|
-| `MODEL_AVAILABILITY_PROBE_ENABLED` | 启用后台模型可用性探测 | `false` | `true` / `false` |
-| `MODEL_AVAILABILITY_PROBE_INTERVAL_MS` | 后台定时探测间隔（毫秒） | `1800000` | >= 60000 |
-| `MODEL_AVAILABILITY_PROBE_TIMEOUT_MS` | 单次探测超时（毫秒） | `15000` | >= 3000 |
-| `MODEL_AVAILABILITY_PROBE_CONCURRENCY` | 单账号模型探测并发数，默认串行避免对上游形成批量测活 | `1` | 1 ~ 16 |
-
-说明：
-
- 探测任务在后台异步执行，不阻塞前台请求。
- 只对看起来像对话/推理模型的条目发最小化探测请求，明显的 embedding、rerank、moderation、tts、image/video 等模型会先跳过。
- 只有“明确模型不存在 / 不支持 / 无权限”的错误才会写回不可用；超时、5xx、网络抖动会归为“不确定”，不会误杀现有模型。
- 为了避免对上游形成意外的批量测活，默认关闭；只有显式开启后才会按间隔执行，且不会在服务启动后立刻扫全量模型。
- 同一批探测任务带去重，上一轮未结束时不会并发堆积；默认并发为 `1`，建议只在确认上游允许主动探测时启用。
-
-### 路由预设建议
-
-| 场景 | COST_WEIGHT | BALANCE_WEIGHT | USAGE_WEIGHT | 说明 |
-|------|:-----------:|:--------------:|:------------:|------|
-| **成本优先** | 0.7 | 0.2 | 0.1 | 适合预算敏感场景，总是选最便宜的通道 |
-| **均衡（默认）** | 0.4 | 0.3 | 0.3 | 兼顾成本、余额和负载均衡，推荐大多数用户 |
-| **稳定优先** | 0.2 | 0.5 | 0.3 | 适合生产环境，优先选余额充足的通道避免中断 |
-| **轮转均匀** | 0.1 | 0.1 | 0.8 | 适合测试场景，尽量让每个通道都被使用到 |
-
-**调参建议：**
-
- 如果某个站点总是被选中导致余额很快耗尽 → 调高 `BALANCE_WEIGHT`
- 如果你有几个很便宜的站点想优先用 → 调高 `COST_WEIGHT`
- 如果你想让请求均匀分散到所有站点 → 调高 `USAGE_WEIGHT`
- 如果你需要对特定项目偏好某个站点 → 使用[下游 API Key 的 `siteWeightMultipliers`](#下游-api-key-策略) 而非调全局权重
-
-## 代理日志保留
-
-| 变量名 | 说明 | 默认值 | 范围 |
-|--------|------|--------|------|
-| `PROXY_LOG_RETENTION_DAYS` | 代理日志保留天数 | `30` | >= 0 |
-| `PROXY_LOG_RETENTION_PRUNE_INTERVAL_MINUTES` | 代理日志清理任务执行间隔（分钟） | `30` | >= 1 |
-
-## 安全配置
-
-| 变量名 | 说明 | 默认值 |
-|--------|------|--------|
-| `ADMIN_IP_ALLOWLIST` | 管理端 IP 白名单（逗号分隔，支持单个 IP 与 IPv4 CIDR） | 空（不限制） |
-
-示例：`ADMIN_IP_ALLOWLIST=192.168.1.10,192.168.1.0/24,10.0.0.0/8`
-
-## 下游 API Key 策略
-
-除了全局 `PROXY_TOKEN`，Metapi 支持在管理后台「设置 → 下游 API Key」中创建多个项目级下游 Key。
-
-每个 Key 可独立配置以下约束：
-
-| 字段 | 说明 | 示例 |
-|------|------|------|
-| `name` | Key 名称（仅供标识） | `team-backend` |
-| `expiresAt` | 过期时间 | `2026-12-31T23:59:59Z` |
-| `maxCost` | 累计费用上限 | `100`（超限后拒绝请求） |
-| `maxRequests` | 累计请求数上限 | `10000` |
-| `supportedModels` | 模型白名单（JSON 数组） | `["gpt-4o", "claude-*", "re:deepseek.*"]` |
-| `allowedRouteIds` | 可走的路由 ID 白名单 | `[1, 3, 5]` |
-| `siteWeightMultipliers` | 站点权重倍率 | `{"1": 2.0, "3": 0.5}` |
-
-模型白名单支持三种匹配模式：
-
- **精确匹配**：`gpt-4o`
- **通配符**：`claude-*`（glob 风格）
- **正则表达式**：`re:deepseek.*`（`re:` 前缀）
-
-## 通知渠道
+虽然我更推荐直接去「通知设置」页面，但为了方便查字段，这里保留一个速查表。

 ### Webhook

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
 | `WEBHOOK_ENABLED` | 启用 Webhook 通知 | `true` |
 | `WEBHOOK_URL` | Webhook 推送地址 | 空 |

 ### Bark（iOS 推送）

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
 | `BARK_ENABLED` | 启用 Bark 推送 | `true` |
 | `BARK_URL` | Bark 推送地址 | 空 |

 ### Server酱

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
 | `SERVERCHAN_ENABLED` | 启用 Server酱 通知 | `true` |
 | `SERVERCHAN_KEY` | Server酱 SendKey | 空 |

 ### Telegram Bot

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
 | `TELEGRAM_ENABLED` | 启用 Telegram 通知 | `false` |
 | `TELEGRAM_BOT_TOKEN` | Telegram Bot Token（形如 `123456:abc`） | 空 |
@@ -233,18 +291,18 @@ Metapi 的路由引擎按多因子加权选择最优通道。

 **配置步骤：**

-1. **创建 Bot**：在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)，发送 `/newbot`，按提示设置名称后获取 Bot Token（格式如 `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`）
+1. **创建 Bot**：在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)，发送 `/newbot`，按提示设置名称后获取 Bot Token
 2. **获取 Chat ID**：
-   - **个人聊天**：向你的 Bot 发送任意消息，然后访问 `https://api.telegram.org/bot<你的Token>/getUpdates`，在返回的 JSON 中找到 `chat.id`，或者在 Telegram 搜索 @userinfobot 或是 @getmyid_bot。点击 Start，它会立刻回复一串数字（通常是 9 到 10 位）。
-   - **群组**：将 Bot 邀请进群组，在群内发送消息后同样通过 `getUpdates` 接口获取群组 Chat ID（通常为负数，如 `-1001234567890`）
-   - **频道**：使用频道用户名，如 `@your_channel`（需先将 Bot 添加为频道管理员）
-3. **填入配置**：将获取的 Token 和 Chat ID 填入管理后台「通知设置」页面
-4. **大陆服务器反代**：如果服务器无法直连 Telegram，可在「通知设置」里填写 `Telegram API Base URL`，例如 `https://your-proxy.example.com`，Metapi 将请求 `https://your-proxy.example.com/bot<token>/sendMessage`
-5. **测试**：保存后点击页面上的「测试通知」按钮验证是否收到消息
+   - 个人聊天：给 Bot 发消息后，通过 `getUpdates` 或 @userinfobot / @getmyid_bot 查看 `chat.id`
+   - 群组：把 Bot 拉进群并发送消息后，通过 `getUpdates` 查看群组 Chat ID
+   - 频道：可直接使用 `@your_channel`（前提是 Bot 是频道管理员）
+3. **填入位置**：优先去 **通知设置** 页面填写
+4. **大陆服务器反代**：如果服务器不能直连 Telegram，可在 UI 里填写 `Telegram API Base URL`
+5. **测试**：保存后直接点“发送测试通知”

 ### SMTP 邮件

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
 | `SMTP_ENABLED` | 启用邮件通知 | `false` |
 | `SMTP_HOST` | SMTP 服务器地址 | 空 |
@@ -257,23 +315,11 @@ Metapi 的路由引擎按多因子加权选择最优通道。

 ### 告警控制

-| 变量名 | 说明 | 默认值 |
+| UI / 变量 | 说明 | 默认值 |
 |--------|------|--------|
-| `NOTIFY_COOLDOWN_SEC` | 相同告警冷却时间（秒），防止同一事件重复通知 | `300` |
+| `NOTIFY_COOLDOWN_SEC` | 相同告警冷静期（秒），防止同一事件重复通知 | `300` |

-## 运行时设置
-
-管理后台「设置」中的运行时设置与环境变量分开管理：环境变量负责启动默认值；保存后的运行时设置会持久化到当前运行数据库，并覆盖对应默认值。
-
-| 分类 | 对应项 | 生效方式 |
-|------|--------|----------|
-| 代理访问与网络 | `PROXY_TOKEN`、`SYSTEM_PROXY_URL`、`ADMIN_IP_ALLOWLIST` | 保存后即时生效 |
-| 定时任务 | `CHECKIN_CRON`、`BALANCE_REFRESH_CRON` | 保存后即时生效 |
-| 智能路由 | `ROUTING_FALLBACK_UNIT_COST`、各路由权重 | 保存后即时生效 |
-| 通知渠道 | Webhook / Bark / Telegram / Server酱 / SMTP / `NOTIFY_COOLDOWN_SEC` | 保存后即时生效 |
-| 数据库运行配置 | `DB_TYPE`、`DB_URL`、`DB_SSL` | 保存后在下次 Metapi 后端启动时生效 |
-
-> `TOKEN_ROUTER_CACHE_TTL_MS`、`PROXY_LOG_RETENTION_DAYS`、`PROXY_LOG_RETENTION_PRUNE_INTERVAL_MINUTES` 当前仍属于部署级环境变量，不在后台运行时设置里单独维护。
+---

 ## 站点公告

@@ -296,6 +342,8 @@ Metapi 的路由引擎按多因子加权选择最优通道。
 ## 下一步

 - [部署指南](./deployment.md) — Docker Compose 与反向代理
+- [K3s 更新中心（高级）](./k3s-update-center.md) — K3s / Helm 用户的后台升级入口
 - [客户端接入](./client-integration.md) — 对接下游应用
 - [上游接入](./upstream-integration.md) — 添加和管理上游平台
+- [OAuth 管理](./oauth.md) — 授权 Codex / Claude / Gemini CLI / Antigravity
 - [运维手册](./operations.md) — 备份、日志与健康检查
@@ -6,35 +6,51 @@

 <a id="account-auth-guide"></a>

-## 账号认证方式与兼容性（Access Token / Cookie）
+## 账号认证方式与兼容性（Session / API Key / OAuth）

-### Q: Access Token 和 Cookie 有什么区别？优先用哪个？
+### Q: Access Token、Cookie、API Key、OAuth 应该选哪个？

-**A:** Metapi 支持两种 Session 凭证来源（都用于管理接口，如余额、签到等）：
+**A:** 现在最稳妥的判断方式不是只看“有没有 Token”，而是先看你接的是哪一类上游：

-| 凭证 | 特点 | 适用场景 |
+| 方式 | 特点 | 适用场景 |
 |------|------|----------|
-| **Access Token（系统访问令牌）** | 支持多账号、通常更稳定、更适合长期使用 | 标准 NewAPI / OneAPI / OneHub / DoneHub / Veloera 等站点 |
-| **Cookie（浏览器登录态）** | 兼容性强，但可能过期，且多账号体验较差 | 访问令牌不可用、魔改站点、特殊兼容场景 |
+| **Access Token（系统访问令牌）** | 稳定、适合长期使用、适合多账号 | 标准 New API / One API / OneHub / DoneHub / Veloera 等面板站 |
+| **Cookie（浏览器登录态）** | 兼容性强，但更容易过期 | Access Token 不可用、AnyRouter 一类魔改站点、特殊兜底场景 |
+| **API Key** | 最简单，适合代理调用 | OpenAI / Claude / Gemini 兼容入口、CPA、各类官方预设 |
+| **OAuth** | 不手填普通凭证，走浏览器授权 | Codex、Claude、Gemini CLI、Antigravity |

-> 结论：优先使用 **Access Token**。仅在站点不支持或令牌不可用时使用 Cookie。
+结论：
+
+1. 面板型站点优先 **Access Token**
+2. Access Token 拿不到时再考虑 **Cookie**
+3. 兼容接口、CPA、官方预设优先 **API Key**
+4. Provider 原生授权优先 **OAuth**

 ### Q: 在 Metapi 里怎么切换认证方式？

-**A:** 在「账号管理 → 添加账号 → Cookie / Token 导入」中：
+**A:** 入口已经分成两条：

-1. 选择站点
-2. 在「凭证模式」下拉选择：
-   - 自动识别（推荐）
-   - Session 模式（Access Token / Cookie）
-   - API Key 模式（仅代理）
-3. 粘贴凭证并点击「验证 Token」
+1. **普通站点**：在「账号管理 / API Key 管理」里选择 Session 或 API Key
+2. **OAuth provider**：在左侧「OAuth 管理」里完成授权
+
+如果你不确定该去哪一页，先看 [上游接入](/upstream-integration)。

 ### Q: 以 NewAPI 为例，Access Token 在哪里生成？

 **A:** 通常路径是：**控制台 → 个人设置 → 安全设置 → 系统访问令牌**。  
 如果你确实需要 Cookie 兜底，可在浏览器 `F12 → Application → Cookie` 获取对应登录态。

+### Q: 什么情况下应该直接走 OAuth？
+
+**A:** 当你接的不是一个普通面板站，而是 provider 自己的账号授权时：
+
+- Codex
+- Claude
+- Gemini CLI
+- Antigravity
+
+这时不要再把它当成“账号管理里的一条普通 Session”去处理，直接看 [OAuth 管理](/oauth)。
+
 ### Q: AnyRouter 这类魔改站点为什么更容易报错？

 **A:** AnyRouter 在 Metapi 中按 NewAPI 兼容站点处理，但不少实例会隐藏 Access Token 入口，或额外加登录盾。建议：
@@ -43,6 +59,10 @@
 2. 如果没有 Access Token 入口，或验证时被盾/认证页拦截，再改用 Cookie 导入
 3. 若返回 HTML 盾页错误，先在浏览器完成验证后再重新绑定

+### Q: CPA / CLIProxyAPI 应该怎么接？
+
+**A:** 这类站点现在走 `cliproxyapi` 平台类型，推荐直接加 API Key，不建议把它当成可签到、可登录的面板站。详细步骤见 [上游接入](/upstream-integration)。
+
 ### Q: Sub2API 站点怎么处理？

 **A:** Sub2API 常见 JWT 短期会话机制，和传统 NewAPI 站点差异较大。当前建议：
@@ -52,7 +72,7 @@
 3. Sub2API 通常为订阅制使用，不支持签到；如果你只关心代理调用，也可以直接改用 API Key 模式
 4. 若 `GET /v1/models` 为空，先确认该账号下已有可用用户 API Key，Metapi 会再尝试用它发现模型

-详细操作截图见 [上游接入 → Sub2API](./upstream-integration.md#sub2api)。
+详细操作说明见 [上游接入](/upstream-integration)。

 ## 部署相关

@@ -137,15 +137,27 @@ npm run dev
 进入 **站点管理**，添加你使用的上游中转站：

 - 填写站点名称（自己想怎么取就怎么取）和 URL
- 选择平台类型（`new-api` / `one-api` / `one-hub` / `done-hub` / `veloera` / `anyrouter` / `sub2api` / `openai` / `claude` / `gemini` / `cliproxyapi`），通常可自动检测，检测有误或者因为防护页导致检测失败可以手动选择。
+- 按你手上的上游形态选择：
+  - 有后台面板：`new-api` / `one-api` / `one-hub` / `done-hub` / `veloera` / `anyrouter` / `sub2api`
+  - 通用兼容接口：`openai` / `claude` / `gemini` / `cliproxyapi`
+  - 官方入口：直接在下拉里选对应**官方预设**，例如阿里云 / 智谱 / 豆包 Coding Plan，DeepSeek，Moonshot，MiniMax，ModelScope
+- 平台通常可自动检测；如果因为防护页、反向代理或特殊路径导致检测失败，再手动选择。
 - 可选是否开启系统代理，方便国内机器访问国外中转站。
 - 可选站点权重，站点权重越大，路由将更加频繁使用这个站点的模型。
+- 如果这个站点的控制台 URL 和真实 AI 请求地址不同，不要直接把主站点 URL 改掉，而是在表单下方补「AI 请求地址池」。

-如果你不确定该选哪个平台，先看 [上游接入](./upstream-integration.md)。
+> [!IMPORTANT]
+> 通用平台常见写法是填控制台地址或 provider base URL；但如果你选的是**官方预设**，请保留预设自动带出的完整路径，哪怕它本来就包含 `/v1`、`/anthropic` 或 `/api/coding/...`。
+
+如果你不确定该选哪个平台或预设，先看 [上游接入](/upstream-integration)。

 ![站点管理](./screenshots/site-management.png)

-### 步骤 2：添加账号(可签到、查询余额等)
+### 步骤 2：添加连接（账号 / API Key / OAuth）
+
+这一步不要再死记“所有站点都先加账号”。现在推荐按场景分流：
+
+#### 2A. 面板型站点：添加账号 / Session

 进入 **连接管理中的账号管理**，为每个站点添加已注册的账号：

@@ -161,15 +173,42 @@ npm run dev

 - 启用自动签到（如站点支持）

-### 步骤 3：添加 API Key（Base URL+Key模式，只可获取模型和使用模型）
+适合这一分支的平台：

-首先你需要在步骤1中，确保添加了（`new-api` / `one-api` / `one-hub` / `done-hub` / `veloera` / `anyrouter` / `sub2api` / `openai` / `claude` / `gemini` / `cliproxyapi`）的类型的Base URL。
+- `new-api`
+- `one-api`
+- `one-hub`
+- `done-hub`
+- `veloera`
+- `anyrouter`
+- `sub2api`

- 进入 **连接管理中的API Key管理**，为每个站点添加你的API Key：
+#### 2B. 兼容接口 / 官方预设 / CPA：添加 API Key
+
+进入 **连接管理中的 API Key 管理**，为站点添加你的 API Key：

 ![API Key 管理](./screenshots/api-key-management.png)

-### 步骤 4：同步账号令牌
+适合这一分支的平台：
+
+- `openai`
+- `claude`
+- `gemini`
+- `cliproxyapi`
+- 所有官方预设（Coding Plan、DeepSeek、Moonshot、MiniMax、ModelScope 等）
+
+#### 2C. Provider 原生授权：走 OAuth 管理
+
+如果你要接的是：
+
+- Codex
+- Claude provider 账号
+- Gemini CLI
+- Antigravity
+
+那就不要在这里手填普通账号，而是直接去左侧菜单 **OAuth 管理** 完成授权，详见 [OAuth 管理](/oauth)。
+
+### 步骤 3：同步账号令牌（可选，仅面板型站点）

 进入 **连接管理中的账号令牌管理**：

@@ -179,14 +218,16 @@ npm run dev

  ![Token管理](./screenshots/token-management.png)

-### 步骤 5：路由管理
+如果你走的是 API Key-only 或 OAuth 流程，这一步通常不是必需的。
+
+### 步骤 4：路由管理

 进入 **路由管理**：

 - 系统会自动发现模型并生成路由规则
 - 点击右上角的刷新选中概率可以显示并将概率载入缓存中
 - 可以手动调整通道的优先级和权重
- 关于路由权重参数调优，参考 [配置说明 → 智能路由](./configuration.md#智能路由)
+- 关于路由权重参数调优，参考 [配置说明 → 智能路由](/configuration#智能路由)
 - 左侧可以进行品牌、站点、接口等的筛选，如下图所示：

 ![路由筛选](./screenshots/routes-filter.png)
@@ -24,8 +24,11 @@ features:
    details: 从部署到第一条请求，按步骤完成最小可用环境搭建。
    link: /getting-started
  - title: 上游接入
-    details: 按当前代码支持的平台类型，快速判断该选什么平台、先走哪个连接分段。
+    details: 按平台类型、官方预设和 AI 请求地址池的现状，快速判断站点该怎么接。
    link: /upstream-integration
+  - title: OAuth 管理
+    details: 直接接入 Codex、Claude、Gemini CLI、Antigravity 等 provider 授权账号。
+    link: /oauth
  - title: 问题排查
    details: 汇总高频报错、根因定位和标准修复路径，降低重复沟通成本。
    link: /faq
@@ -4,7 +4,19 @@

 ---

-这页写给已经把 Metapi 部署到 **K3s / Kubernetes + Helm** 的用户。
+本页适用于已经把 Metapi 部署到 **K3s / Kubernetes + Helm** 的用户。
+
+K3s 更新中心的日常入口位于：
+
+```text
+设置 → 更新中心
+```
+
+本文主要说明三件事：
+
+- 哪些配置直接在后台页面里填写
+- 哪些配置仍然需要主服务环境变量或 helper manifest
+- 哪些前提不满足时，页面虽然能打开，但无法真正部署

 如果你现在的环境只是一个最普通的 **Docker Compose 安装**，只有一个 Metapi 容器，其他什么都没有，那么先记住一句话：

@@ -15,12 +27,32 @@
 >
 > 但如果你是老用户，正打算 **从 Docker Compose 迁到 K3s / Helm，以获得滚动更新能力**，那这页仍然值得看，因为它描述的就是迁移完成后的目标形态。

-## 先判断：你需不需要看这页
+## 配置到底在哪里配

-| 你的现状 | 要不要看这页 | 你现在该怎么做 |
+更新中心涉及后台页面、主服务环境变量、helper 部署清单三层配置，最容易混淆，建议先看下面这张对照表。
+
+| 你要配什么 | 去哪里配 | 说明 |
+|------|------|------|
+| 是否启用更新中心 | UI：设置 → 更新中心 | 日常使用优先在 UI 操作 |
+| Deploy Helper URL | UI：设置 → 更新中心 | 例如集群内 Service 地址 |
+| Namespace / Release Name / Chart Ref / Image Repository | UI：设置 → 更新中心 | 都是页面里直接填的部署配置 |
+| GitHub Releases / Docker Hub / 默认部署来源 | UI：设置 → 更新中心 | 属于页面里的版本来源策略 |
+| 主 Metapi 到 helper 的认证 token | 主 Metapi 环境变量 | `DEPLOY_HELPER_TOKEN` 或 `UPDATE_CENTER_HELPER_TOKEN` |
+| helper 自己监听在哪个地址和端口 | helper 环境变量 / manifest | `DEPLOY_HELPER_HOST` / `DEPLOY_HELPER_PORT` |
+| helper 自己的 Bearer Token | helper 环境变量 / manifest | `DEPLOY_HELPER_TOKEN`，且必须与主服务一致 |
+| chart 是否真的支持 digest 部署 | chart 文件本身 | 这不是 UI，也不是普通 env，要看 chart 模板 |
+
+其中可以这样理解：
+
+- 日常使用时，更新中心的大部分配置直接在 **设置 → 更新中心** 页面填写
+- 环境变量主要负责主服务与 helper 之间的认证，以及 helper 自身的监听参数
+
+## 先判断：是否适用
+
+| 你的现状 | 是否适用 | 你现在该怎么做 |
 |------|------------|--------------|
 | 只有一个 `docker compose up -d` 跑起来的 Metapi 容器 | 不需要 | 继续用普通 Docker 升级方式 |
-| 目前是 Docker Compose，准备迁到 K3s / Helm 来获得滚动更新 | 需要 | 把这页当成迁移后的目标架构说明，先完成迁移，再启用更新中心 |
+| 目前是 Docker Compose，准备迁到 K3s / Helm 来获得滚动更新 | 需要 | 把本页当成迁移后的目标架构说明，先完成迁移，再启用更新中心 |
 | 有 K3s / Kubernetes 集群，但 Metapi 不是用 Helm release 部署的 | 暂时不建议 | 这套更新中心无法直接接管现有部署 |
 | Metapi 已经是 Helm release，想在后台里看版本并手动点一次升级 | 需要 | 继续看下文 |

@@ -45,7 +77,7 @@ docker compose up -d
 - 额外的 Bearer Token
 - 集群内 Service 地址

-也就是说，除非你本来就在用 K3s / Helm，否则这页可以直接跳过。
+除非你本来就在用 K3s / Helm，否则本页可以直接跳过。

 ## 如果你正准备从 Docker Compose 迁到 K3s

@@ -57,7 +89,7 @@ docker compose up -d
 - 用 Helm 管理版本和回滚
 - 后续在后台里看版本来源，并人工触发一次升级

-对这类用户来说，这页不是“现在立刻就能用”的操作手册，而是：
+对这类用户来说，本页不是“现在立刻就能用”的操作手册，而是：

 - “迁移完成后，你会得到什么能力”
 - “为了用上这个能力，集群侧要提前满足什么前提”
@@ -160,7 +192,7 @@ Deploy Helper 是一个跑在集群里的小服务。它不负责对外提供 Me

 那答案是：

- 这是一个合理场景，这页正是给你看迁移后该怎么接入的。
+- 这是一个合理场景，本页正是说明迁移后该如何接入更新中心。

 ## K3s / Helm 用户的接入步骤

@@ -253,8 +285,12 @@ helper 端使用：

 它们的值必须完全一致。

+这一步仍然是**环境变量级配置**，因为它本质上是主服务与 helper 之间的认证，而不是普通用户日常在 UI 里调的业务参数。
+
 ### 3. 在后台“设置 → 更新中心”里填配置

+从这一步开始，**优先按 UI 来操作**，不要再回头把下面这些字段硬塞进环境变量。
+
 需要填写的核心字段有：

 | 字段 | 怎么理解 | 典型示例 |
@@ -272,6 +308,12 @@ helper 端使用：
 - `GitHub Releases`
 - `Docker Hub`

+对已经跑起来的 K3s / Helm 用户来说，更新中心的日常配置主要就在这一页：
+
+```text
+设置 → 更新中心
+```
+
 ### 4. 实际操作顺序

 推荐这样用：
@@ -329,9 +371,9 @@ About 页里的“更新提醒”更像一个轻量入口：
 - K3s / Kubernetes
 - Helm release
 - Deploy Helper
+- 主服务的 `DEPLOY_HELPER_TOKEN`（或兼容别名 `UPDATE_CENTER_HELPER_TOKEN`）与 helper 侧 `DEPLOY_HELPER_TOKEN` 保持一致

 另外，如果你想用“按 digest 精确部署/回退”这条链路，还要确认你的 chart 没有忽略 `image.digest` 这个值；否则页面虽然能显示 digest，真正部署时还是只会落到 tag 语义。
- 对齐的 token

 缺其中任何一项，都只能看，不能真正部署。

@@ -77,9 +77,12 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites" \
 脚本化添加一个新站点并绑定账号，通常按下面顺序：

 1. `POST /api/sites/detect` 自动识别平台
-2. `POST /api/sites` 创建站点
-3. `POST /api/accounts/verify-token` 验证凭证
-4. `POST /api/accounts` 保存账号
+2. 如命中官方预设，记下返回的 `initializationPresetId`
+3. `POST /api/sites` 创建站点
+4. `POST /api/accounts/verify-token` 验证凭证
+5. `POST /api/accounts` 保存账号
+
+如果你要自动化的是 Codex / Claude / Gemini CLI / Antigravity 这类 provider 授权，则改看本文后面的 **OAuth 接口**，不要强行走普通账号导入。

 最小流程示例：

@@ -159,13 +162,13 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites" \

 `POST /api/sites/detect`

-用于在真正创建站点前，先根据 URL 探测平台类型。
+用于在真正创建站点前，先根据 URL 探测平台类型；如果命中官方预设，还会顺带返回 `initializationPresetId`。

 请求体：

 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `url` | `string` | 是 | 站点根地址，**不要**带 `/v1` |
+| `url` | `string` | 是 | 待识别的站点地址。通用平台通常传根地址；如果你想命中官方预设，则直接传预设对应的完整地址 |

 示例：

@@ -187,6 +190,16 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites/detect" \
 }
 ```

+命中预设时，响应可能类似：
+
+```json
+{
+  "url": "https://coding.dashscope.aliyuncs.com/v1",
+  "platform": "openai",
+  "initializationPresetId": "codingplan-openai"
+}
+```
+
 失败响应：

 ```json
@@ -204,8 +217,9 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites/detect" \
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | `string` | 是 | 站点名称 |
-| `url` | `string` | 是 | 站点根地址，**不要**带 `/v1` |
+| `url` | `string` | 是 | 站点地址。通用平台通常用根地址；官方预设可直接保留完整官方路径 |
 | `platform` | `string` | 否 | 平台类型；留空时服务端会再次尝试自动识别 |
+| `initializationPresetId` | `string` | 否 | 官方预设 ID；用于保留预设语义、初始化建议和后续跳转 |
 | `proxyUrl` | `string \| null` | 否 | 站点专用代理地址，支持 `http(s)` / `socks` |
 | `useSystemProxy` | `boolean` | 否 | 是否使用全局 `SYSTEM_PROXY_URL` |
 | `customHeaders` | `string \| null` | 否 | 自定义请求头，注意这里传的是 **JSON 字符串** |
@@ -214,6 +228,7 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites/detect" \
 | `isPinned` | `boolean` | 否 | 是否置顶 |
 | `sortOrder` | `number` | 否 | 排序值，非负整数 |
 | `globalWeight` | `number` | 否 | 站点全局权重，必须为正数 |
+| `apiEndpoints` | `array` | 否 | 仅用于 AI 请求的数据面地址池；不替代主站点 URL |

 示例：

@@ -258,6 +273,24 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites" \
 > [!TIP]
 > `customHeaders` 不是对象，而是 JSON 字符串；并且 value 必须是字符串。

+### 4. 使用官方预设创建站点
+
+如果你前一步 `detect` 已经拿到了 `initializationPresetId`，推荐在创建时显式带回去：
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/sites" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Aliyun CodingPlan",
+    "url": "https://coding.dashscope.aliyuncs.com/v1",
+    "platform": "openai",
+    "initializationPresetId": "codingplan-openai"
+  }'
+```
+
+这样响应里也会保留该预设信息，便于脚本按预设类型做后续分流。
+
 ## 账号接口

 ### 1. 获取账号列表
@@ -481,6 +514,127 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/accounts/1/rebind-session" \
 }
 ```

+## OAuth 接口
+
+如果你要自动化的是 Codex / Claude / Gemini CLI / Antigravity 这类 provider 授权，请使用下面这组接口。
+
+### 1. 获取可用 provider
+
+`GET /api/oauth/providers`
+
+示例：
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/oauth/providers" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}"
+```
+
+示例响应：
+
+```json
+{
+  "providers": [
+    {
+      "provider": "codex",
+      "label": "Codex",
+      "platform": "codex",
+      "enabled": true,
+      "loginType": "oauth",
+      "requiresProjectId": false,
+      "supportsDirectAccountRouting": true,
+      "supportsCloudValidation": true,
+      "supportsNativeProxy": true
+    }
+  ]
+}
+```
+
+### 2. 启动 OAuth 授权
+
+`POST /api/oauth/providers/:provider/start`
+
+请求体字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `projectId` | `string` | 否 | 某些 provider 可选传入的项目 ID，例如 Gemini CLI |
+| `proxyUrl` | `string \| null` | 否 | 本次 OAuth 流程使用的显式代理；传 `null` 可清空继承代理 |
+
+示例：
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/oauth/providers/codex/start" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+成功响应：
+
+```json
+{
+  "provider": "codex",
+  "state": "oauth-state-123",
+  "authorizationUrl": "https://auth.example.com/authorize?...",
+  "instructions": {
+    "redirectUri": "http://localhost:1455/auth/callback",
+    "callbackPort": 1455,
+    "callbackPath": "/auth/callback",
+    "manualCallbackDelayMs": 15000
+  }
+}
+```
+
+### 3. 查询 OAuth 会话状态
+
+`GET /api/oauth/sessions/:state`
+
+示例：
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/oauth/sessions/oauth-state-123" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}"
+```
+
+典型状态包括：
+
+- `pending`
+- `success`
+- `error`
+
+### 4. 手动回填 callback URL
+
+`POST /api/oauth/sessions/:state/manual-callback`
+
+当浏览器已经完成授权，但回调没有自动打到 Metapi 时，可以手动提交最终 callback URL。
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/oauth/sessions/oauth-state-123/manual-callback" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "callbackUrl": "http://localhost:1455/auth/callback?code=demo&state=oauth-state-123"
+  }'
+```
+
+### 5. 列出已有 OAuth 连接
+
+`GET /api/oauth/connections`
+
+示例：
+
+```bash
+curl -sS "${METAPI_ADMIN_BASE_URL}/api/oauth/connections?limit=50&offset=0" \
+  -H "Authorization: Bearer ${METAPI_AUTH_TOKEN}"
+```
+
+### 6. 重绑或删除 OAuth 连接
+
+| 接口 | 作用 |
+|------|------|
+| `POST /api/oauth/connections/:accountId/rebind` | 为已有 OAuth 账号重新发起授权 |
+| `DELETE /api/oauth/connections/:accountId` | 删除 OAuth 连接 |
+
 ## 常见失败返回

 ### 站点创建冲突
@@ -545,5 +699,6 @@ curl -sS "${METAPI_ADMIN_BASE_URL}/api/accounts/1/rebind-session" \
 ## 下一步

 - [上游接入](./upstream-integration.md) — 查看不同站点类型应该怎么填 URL、凭证和 User ID
+- [OAuth 管理](/oauth) — 查看浏览器授权、回调和重绑逻辑
 - [配置说明](./configuration.md) — 查看 `AUTH_TOKEN`、`ADMIN_IP_ALLOWLIST`、系统代理等配置项
 - [客户端接入](./client-integration.md) — 如果你要接的是 `/v1/*` 代理接口而不是后台管理接口，请看这里
@@ -0,0 +1,224 @@
+# 🔐 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 这类**普通站点或网关**，请看 [上游接入](/upstream-integration)。
+
+---
+
+## 入口在哪里
+
+管理后台左侧菜单已经有独立入口：
+
+```text
+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. 确保 Metapi 能访问 provider 的 OAuth 端点
+
+如果你的部署环境访问外网受限，可以：
+
+- 先配置全局 `SYSTEM_PROXY_URL`
+- 或在 OAuth 启动 / 重绑时使用单次代理参数
+
+相关环境变量见 [配置说明](/configuration) 里的「OAuth 与 Provider 登录」一节。
+
+### 2. 远程部署要提前考虑回调方式
+
+OAuth 默认使用 Metapi 本机上的 loopback 回调地址，例如本机 `127.0.0.1` 端口。
+
+如果你的 Metapi 跑在远程服务器上，而浏览器跑在本地电脑上，常见做法有两个：
+
+1. **SSH 隧道**：按页面给出的命令，把回调端口转发到远端
+2. **手动回填 callback URL**：如果浏览器已经完成授权，但自动回调没打通，可把最终回调地址手动贴回管理页
+
+### 3. 了解它和普通站点接入的边界
+
+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 页面还没成功：
+
+1. 复制浏览器最终回调 URL
+2. 回到「OAuth 管理」
+3. 粘贴到手动回填区域提交
+
+### 步骤 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 |
+
+简单判断：
+
+- 你拿到的是 **站点后台地址**，优先看 [上游接入](/upstream-integration)
+- 你拿到的是 **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](/management-api)。
+
+---
+
+## 常见问题
+
+### provider 显示“当前不可用”
+
+通常说明回调监听器不可用，或当前 provider 的启动条件不满足。优先检查：
+
+1. 服务是否刚启动但回调监听失败
+2. 端口是否被占用
+3. 当前环境是否缺少必要的 OAuth 配置
+
+### 浏览器授权成功了，但页面一直停在“等待授权完成”
+
+优先怀疑回调链路没通：
+
+1. 如果是远程服务器，先按页面提示建 SSH 隧道
+2. 如果不方便建隧道，直接用手动 callback 回填
+3. 如果 provider 页面最终没有 `code` / `state` 参数，说明授权本身还没成功
+
+### OAuth 连接需要系统代理吗
+
+有可能需要，尤其是：
+
+- 国内服务器访问 OpenAI / Anthropic / Google OAuth 端点
+- 服务器本身不能直连 provider
+
+优先使用：
+
+1. 全局 `SYSTEM_PROXY_URL`
+2. OAuth 启动 / 重绑时指定单次代理
+
+### OAuth 成功后为什么还会在站点管理看到一行站点
+
+这是预期行为。Metapi 需要一个明确的站点记录来承载：
+
+- 账号所属平台
+- 路由与通道归属
+- 后续重绑 / 刷新逻辑
+
+它不代表你又新增了一个普通面板站点。
+
+---
+
+## 相关文档
+
+- [上游接入](/upstream-integration)
+- [管理 API](/management-api)
+- [配置说明](/configuration)
+- [常见问题 FAQ](/faq)
@@ -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 和路由配置，请谨慎操作
+- 如果你看到站点创建成功后的“官方预设”提示，请按它建议的下一步走，一般会更省事