官方订阅账号接入

通过 OAuth 连接 ChatGPT / Codex、Claude、Gemini CLI / Code Assist 和 Antigravity,配置模型并交付网关调用。

管理员任务指南更新于 2026-10-28

准备账号与管理权限

使用具有对应服务访问资格的账号和可管理渠道的后台账号。超级管理员管理公共渠道,组织管理员管理本组织私有渠道。订阅渠道同样受组织关联、模型授权、网关 Key、额度和用量记录约束。

账号持有人可通过管理员复制的授权链接完成官方登录,无需登录 BOS 管理后台。应用开发者仍使用 BOS API 网关 Key;上游订阅授权由管理员在渠道中维护。

创建渠道并完成官方登录

授权链接有效期为 10 分钟,绑定发起授权的管理员、组织、角色和平台,只能兑换一次。过期或令牌兑换失败时重新发起登录,并回填新会话的结果。

  • 进入“渠道与模型”,新建渠道并填写名称。选择 OpenAI、Anthropic、Gemini 或 Antigravity,凭证方式选择“官方订阅账号(OAuth)”。新渠道默认使用订阅登录;使用 API Key 或上游代理时切换到对应方式。官方订阅的上游地址与协议自动填入并固定。
  • 点击“开始官方账号登录”,在新标签页完成官方登录;也可复制授权链接交给账号持有人。弹窗被拦截时,使用“打开官方登录页”或复制链接。保持生成链接的原表单打开。
  • 将最终完整回调地址或页面显示的授权码回填到同一表单;Claude 也接受 code#state。不要混用其他标签页或重新发起登录前的授权结果。
  • 点击表单底部“保存渠道”。模型可暂时留空,账号先保存,再尝试获取模型;模型区域的“保存并获取模型”会完成这两步。仅完成官方页面登录尚未保存渠道。

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 / CodexResponses JSON / SSE,以及现有 Codex WebSocket 和压缩路由。Chat / Messages 兼容仅限普通非流式对话;Codex 工具与流式使用 Responses。订阅 OAuth 不授予 OpenAI embeddings 或图片 API 权限。
ClaudeMessages JSON / SSE、count_tokens,以及现有 Chat 转换。使用 Anthropic 协议的授权模型;跨协议转换仍有原有限制。
Gemini CLI / Code AssistGemini generateContent JSON、streamGenerateContent SSE,以及现有 Chat / Messages 转换。Token 计数依赖 Google generative-language 端点权限;不支持 Code Assist embeddings。消费级 Gemini 订阅不保证 Code Assist 或所有模型权限。
AntigravityGemini 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 与组织关联。本功能无需新增数据库迁移或后台服务;真实登录、账号资格、上游可用性和推理调用仍需在自己的部署中验证。

按部署版本核对具体能力与操作。 查看文档适用范围

BOS API · TYPEX

销售咨询暂不可用

暂时无法初始化销售接待,请稍后重试。你仍可查看文档并免费自托管。

查看文档免费自托管