企业官网建设流程全解析

TokenHub 是一款面向企业的私有 AI 模型网关，它把各种 AI 模型统一接入到一个可控、可追踪、可归因的入口。本文将带你完整走通一条链路：用OAuth 登录授权 OpenAI Codex 订阅账号，把 Codex CLI 接入 TokenHub 网关，理解会话亲和如何保证同一会话始终使用同一个订阅账号，并调用codex-gpt-image-2虚拟模型实现用订阅额度生图。

一、为什么要把 Codex 订阅接入 TokenHub？

直接用 Codex 订阅账号存在几个痛点：凭据散落在各台机器上、用量无法归属到人或项目、团队无法统一限流。接入 TokenHub 后：

• 统一入口：Codex CLI、Claude Code、Gemini CLI 都指向同一个 Base URL（以/v1结尾）；
• 凭据集中托管：Codex 账号的 OAuth Token 由 TokenHub 后端加密保存并自动续租，客户端只持有项目 API Key；
• 会话亲和：同一对话被粘性绑定到同一个订阅账号，避免上下文断裂；
• 审计与归因：每个请求记录项目、模型、账号、Token 与成本。

前提：管理员需要先在 TokenHub 中接入 OpenAI Codex Provider、订阅账号资源和模型路由，再为项目创建 API Key（详见 docs/zh-CN/codex-tokenhub-profile-quick-start.md）。

二、OAuth 登录：授权 Codex 订阅账号的完整步骤

2.1 在控制台发起账号 OAuth 授权

1. 登录 TokenHub 控制台，进入「Provider 渠道」，选择OpenAI Codex类型；
2. 在账号（Provider Resource）配置中选择「账号 OAuth 授权」，TokenHub 会生成一个授权链接，点击「打开」或「复制」；
3. 在弹出的页面中登录你的 ChatGPT/Codex 账号并完成授权，TokenHub 后端自动换取并加密保存 Access Token 与 Refresh Token；
4. 账号详情页会展示账号邮箱、套餐类型、Token 过期时间、健康状态等信息（实现见 frontend/features/admin/views/provider-account-ui.tsx）。

2.2 Token 自动续租与重新授权

你不需要手动管理 Token 生命周期：

• TokenHub 后端启动时检查一次，之后每分钟检查一次，只在 Access Token 即将在 5 分钟内过期时才发起续租；
• 集群部署下通过数据库凭证租约保证同一账号只由一个实例续租；
• 在「Provider 渠道 > 高级 > 订阅额度」中可点击「续租 Token」手动续租用于故障恢复；
• 如果 Refresh Token 失效，账号会被标记为需要重新授权，停止定时续租并向管理员显示提示，届时重新走一次 OAuth 授权即可。

此外，OpenAI 返回的权威额度信息（剩余用量、重置次数）也会展示在「订阅额度」卡片上，还可以执行「重置套餐用量」操作（详见 docs/zh-CN/administrator-guide.md）。

三、创建对外模型与路由

账号授权完成后，还需要把模型"发布"出来：

1. 在「模型目录」创建对外模型（例如gpt-5.6-luna），它代表对客户端开放的 API 契约；
2. 在「路由策略」中把该模型映射到 OpenAI Codex Provider 的订阅账号线路，可配置优先级、权重与项目作用域。

模型要出现在GET /v1/models中，必须同时满足：对外模型已启用、至少有一条已启用路由、API Key 白名单已授权。

四、把 Codex CLI 接入 TokenHub：Profile 配置指南

推荐用独立的tokenhubProfile，只影响显式指定--profile tokenhub的会话，随时可回退。

4.1 创建配置文件

在~/.codex/tokenhub.config.toml写入（推荐用环境变量携带 Key）：

model_provider = "tokenhub" model = "填写 GET /v1/models 返回的实际模型 ID" [model_providers.tokenhub] name = "TokenHub" base_url = "填写实际的 TokenHub Base URL（以 /v1 结尾）" env_key = "TOKENHUB_API_KEY" wire_api = "responses"

关键点：

• base_url必须包含/v1，这是新手最常见的 404 原因；
• 模型 ID 必须以GET /v1/models返回的data[].id为准，不要凭上游名称猜测；
• 不要把真实 Key 写进命令行，可用隐藏输入方式注入：read -r -s "TOKENHUB_API_KEY?输入项目 Key: "后执行export TOKENHUB_API_KEY。

4.2 启动与验证

codex --profile tokenhub

进入 Codex 后执行/status，确认Model provider为 TokenHub、Model与配置一致，再到控制台的请求日志中确认出现 HTTP 200 记录。

💡 首次接入建议先用进程级临时参数（-c 'model_provider="tokenhub"'等）验证连通性，通过后再落盘 Profile 配置。四种配置方式（Profile / 进程级 / CLI 全局 / 桌面端）的完整对比与恢复方法见 docs/zh-CN/codex-tokenhub-configuration.md。

五、会话亲和：为什么同一会话必须绑定同一账号

Codex 的会话是有状态的（依赖 reasoning continuation、会话上下文等），如果同一对话中途切换到另一个订阅账号，上下文会丢失。TokenHub 的会话亲和机制解决了这个问题：

• 对 Responses、Chat、Anthropic Messages、Gemini 路由，网关会根据session-id请求头、client_metadata.session_id或prompt_cache_key等稳定会话提示，生成粘性 Provider Resource 绑定，把连续请求固定到同一个健康的 Codex 订阅账号；
• Claude Code 走/v1/messages时，TokenHub 将请求转换为 Responses 协议再转回 Anthropic 事件，Codex 的推理签名跨工具调用轮次传递，同一 Claude Code 会话保持绑定同一账号（见 docs/zh-CN/user-guide.md）；
• 管理员还可在账号资源中配置「Codex 指纹收敛」，默认的session模式会派生账号级稳定的 installation ID / session ID / thread ID，多客户端共享账号时不会互相干扰，且不会暴露保存的 OAuth 凭据。

六、图像生成：用 Codex 订阅额度调用 codex-gpt-image-2

这是很多订阅用户最惊喜的能力——不消耗 OpenAI API 费用，直接消耗 Codex 订阅额度生图。

6.1 管理员开启生图能力

1. 编辑目标 OpenAI Codex Provider，进入「模型」页签，勾选「Codex 订阅生图」；
2. 选择一个健康的订阅账号完成一次quality: low、1024x1024的实测（消耗少量额度）；
3. 测试通过后，TokenHub 自动创建上游模型为gpt-image-2的线路。服务端直接从已确认支持生图的账号调用 Codex 订阅 Images 接口，无需安装 Codex CLI（能力检测实现见 backend/internal/server/admin_codex_image_capability_test.go）。

6.2 调用生图 API

TokenHub 保留 OpenAI 标准 Image API 形态，只需把模型名换成codex-gpt-image-2：

curl -X POST "${TOKENHUB_BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer ${TOKENHUB_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "codex-gpt-image-2", "prompt": "一只橙色虎斑猫坐在木质书桌前阅读一本书，写实摄影，无文字", "n": 1, "quality": "low", "size": "1024x1024", "response_format": "url" }'

响应中的data[0].url是带签名的下载链接，有效期 24 小时；过期后重新查询任务即可拿到新 URL。

常用能力速查：

完整协议（Base64 响应、异步轮询、原生 Codex JSON 编辑、错误码）见 docs/zh-CN/codex-image-generation-api.md。

七、常见问题排查

八、延伸阅读

• docs/zh-CN/codex-tokenhub-configuration.md —— 四种 Codex 接入方式与恢复指南
• docs/zh-CN/codex-tokenhub-profile-quick-start.md —— Profile 快速配置
• docs/zh-CN/codex-image-generation-api.md —— Codex 生图 API 完整测试指南
• docs/zh-CN/gemini-cli-codex-subscription.md —— Gemini CLI 复用 Codex 订阅额度
• backend/internal/server/codex_compat_route.go —— Codex 协议路由源码

至此，你已经掌握了一条完整的 TokenHub + Codex 订阅链路：OAuth 登录授权账号 → 创建模型路由 → Profile 接入 Codex CLI → 会话亲和保障上下文 → 订阅额度生图。把凭据、用量和治理都收敛到网关之后，团队可以放心地把 Codex 订阅用起来。🚀