[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
@@ -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/*` 代理接口而不是后台管理接口，请看这里