官方订阅账号接入
通过 OAuth 连接 ChatGPT / Codex、Claude、Gemini CLI / Code Assist 和 Antigravity,配置模型并交付网关调用。
准备账号与管理权限
使用具有对应服务访问资格的账号和可管理渠道的后台账号。超级管理员管理公共渠道,组织管理员管理本组织私有渠道。订阅渠道同样受组织关联、模型授权、网关 Key、额度和用量记录约束。
账号持有人可通过管理员复制的授权链接完成官方登录,无需登录 BOS 管理后台。应用开发者仍使用 BOS API 网关 Key;上游订阅授权由管理员在渠道中维护。
localhost 回调打不开时继续授权
OpenAI 登录后可能跳转到 localhost:1455/auth/callback;Antigravity 使用 localhost:8085/callback。出现 ERR_CONNECTION_REFUSED 通常表示本机没有回调监听器,单凭这一页面不能判定 OAuth 授权失败。复制地址栏完整地址,包含 code 和 state,回到原 BOS 表单粘贴并保存。
此流程无需在部署服务器开放回调端口,也不会自动跳回 BOS。只有 BOS 成功兑换授权码并保存渠道后,账号才完成连接。
获取模型并授权调用
- OpenAI、Claude 和 Antigravity 使用授权账号访问官方模型目录。获取失败时已保存账号仍保留,可在模型列表重试,或编辑渠道手动添加模型名称。没有配置模型的渠道不能提供模型调用。
- Gemini CLI / Code Assist 当前没有对应模型目录:模型发现验证账号连通性,并保留手动配置的模型,不自动补全模型或推测 Token 上限。只添加该账号实际有权使用的模型。
- 公共渠道须显式关联到组织并启用;组织私有渠道按本组织权限使用。为应用签发授权模型的网关 Key,先验证协议匹配的小请求,再验证流式和工具调用,并核对用量与 Request ID。
按账号选择协议
| 账号 | 主要入口与支持范围 | 限制 |
|---|---|---|
| ChatGPT / Codex | Responses JSON / SSE,以及现有 Codex WebSocket 和压缩路由。 | Chat / Messages 兼容仅限普通非流式对话;Codex 工具与流式使用 Responses。订阅 OAuth 不授予 OpenAI embeddings 或图片 API 权限。 |
| Claude | Messages JSON / SSE、count_tokens,以及现有 Chat 转换。 | 使用 Anthropic 协议的授权模型;跨协议转换仍有原有限制。 |
| Gemini CLI / Code Assist | Gemini generateContent JSON、streamGenerateContent SSE,以及现有 Chat / Messages 转换。 | Token 计数依赖 Google generative-language 端点权限;不支持 Code Assist embeddings。消费级 Gemini 订阅不保证 Code Assist 或所有模型权限。 |
| Antigravity | Gemini generateContent JSON、streamGenerateContent SSE,以及现有 Chat / Messages 转换。 | 使用独立 OAuth 客户端与项目身份;不支持 Token 计数,会返回能力错误。 |
Gemini 项目识别与排错
Gemini 先通过 loadCodeAssist 识别托管项目,符合条件的新用户可自动开通,并等待异步操作完成。仍没有项目时,使用同一账号令牌查询已有 ACTIVE Google Cloud 项目,依次优先选择唯一的 Code Assist / companion 项目、唯一默认项目或仅剩的一个项目。此过程不创建 Cloud 项目、不启用 API,也不修改账单。
没有可访问项目或存在多个同等候选时,在授权表单填写账号对应的 Google Cloud 项目 ID,再重新授权。Google 权限与异步操作错误会直接报告;检查错误详情和账号资格,不能把没有项目当作授权已成功。Antigravity 也可在其授权表单中填写项目 ID。
部署配置与可选 OAuth 客户端
新版后端内置 Gemini CLI 与 Antigravity 各自的默认 OAuth 客户端。对应平台的两个变量均为空或未设置时,直接使用默认值,无需额外配置;只有替换为其他兼容客户端时才填写完整变量对。只设置一项会导致授权和刷新报配置错误,两平台不共用客户端。
BOS_GEMINI_OAUTH_CLIENT_ID=
BOS_GEMINI_OAUTH_CLIENT_SECRET=
BOS_ANTIGRAVITY_OAUTH_CLIENT_ID=
BOS_ANTIGRAVITY_OAUTH_CLIENT_SECRET=Compose 部署在服务器现有私有 deploy/stack.env 中编辑,保留原数据库密码和加密密钥;这些值是 OAuth 应用身份,与上游 API Key、用户访问令牌和回调授权码不同。
./deploy/stack.sh start在应用部署目录执行,先确保后端与 Compose 定义已更新。该命令使用现有镜像并重建环境发生变化的容器;docker restart 或 docker compose restart 不会注入新环境变量。修改源码需先重建部署。
- 自定义 Gemini 客户端须注册 https://codeassist.google.com/authcode;Antigravity 须注册 http://localhost:8085/callback。
- 部署栈不读取 backend/.env.example。直接运行后端时,通过进程环境设置变量并重启进程。
- 待完成的 OAuth 会话保存在内存中,重启后失效。多实例授权期间使用单个应用实例或粘性路由;已保存的账号凭证持久化在 MySQL。
续期、重新授权与验证
访问令牌、刷新令牌、账号 / 项目标识及到期时间保存在现有加密凭证字段,渠道 API 响应不返回它们。令牌剩余不到一分钟时,网关在数据库行锁下刷新并保存轮换结果;共享数据库的请求与副本复用刷新后的凭证。刷新失败时保留原凭证并使请求失败。
账号授权过期、撤销或需要更换时,编辑原渠道并选择“重新发起官方账号登录”,完成后保存,保留渠道 ID 与组织关联。本功能无需新增数据库迁移或后台服务;真实登录、账号资格、上游可用性和推理调用仍需在自己的部署中验证。
按部署版本核对具体能力与操作。 查看文档适用范围