←

GoClaw v2.34.0

Codex OAuth Pools

将多个 OpenAI Codex 账户合并为一个统一池。自动路由请求。实时配额监控。

scroll

01 — 问题

每个账户的独立速率限制

OpenAI 按每个订阅账户实施速率限制。如果您拥有 3–5 个 Codex 账户，必须手动切换管理。

配额用尽时手动切换

不知道哪个账户还有余量

无法聚合吞吐量

对于 5–10 人共享网关的团队，这个问题会成倍增加。

02 — 工作原理

四步配置

注册 OAuth

每个 Codex/ChatGPT 账户注册为独立的命名 Provider。GoClaw 存储刷新令牌并自动处理令牌刷新。

创建 Pool

选择一个 Provider 作为所有者，将其他添加到 codex_pool.extra_provider_names。

选择策略

配置请求分配方式：优先主账户、轮询或优先级排序。

Agent 继承

设置 override_mode: "inherit" — Agent 自动从 Provider 继承池配置。

池验证

✓ 禁止自引用 ✓ 每个成员只属于一个池 ✓ 所有者 ≠ 成员 ✓ 类型必须为 chatgpt_oauth

03 — 架构

请求管道

GoClaw Gateway — Request Flow

用户消息

→

Agent Loop

→

Resolver

→

Routing Engine

↓

Codex OAuth Pool

codex-pro-1

35%

healthy

codex-pro-2

85%

healthy

codex-team

10%

degraded

04 — Routing

三种路由策略

Strategy	行为
`primary_first`	优先使用所有者，出错时故障转移到成员
`round_robin`	在池中所有账户之间轮询
`priority_order`	按优先级顺序使用，账户出错时自动切换

05 — 核心特性

Inherited Routing Defaults

Agent 从 Provider 继承路由配置 — 配置一次，所有 Agent 自动受益。

Provider

"codex-main"

Pool owner

codex-backup

codex-team

round_robin

inherit

Agent

"assistant"

Provider: codex-main

Override: inherit

（无需配置池）

✓ 在 Provider 级别配置一次 — 使用该 Provider 的所有 Agent 都受益
✓ 更改池成员？编辑 Provider，Agent 自动更新
✓ Agent 仍可按需覆盖 — override_mode: "custom"

06 — Monitoring

Quota real-time

GoClaw 调用 OpenAI Usage API 获取池中每个账户的配额。

Pool Dashboard

Codex OAuth Pool

Live

codex-pro-1

65%healthy

5h: 35% remainweekly: 80% used

codex-pro-2

15%healthy

5h: 92% remainweekly: 25% used

codex-team

90%degraded

5h: resets in 2h 15mweekly: resets in 3d 4h

● 2 healthy △ 1 degradedStrategy: round_robinLast → codex-pro-2 (2m ago)

07 — Health

Auto-failover tracking

网关通过追踪数据跟踪每个账户的健康状态。当账户持续失败时，路由引擎自动切换到其他账户。

Success Rate

94%

请求成功

Health Score

综合评分

Consec. Failures

连续错误

State

healthy

08 — Security

Access control

仅 admin/operator 可管理池

Viewer：仪表板只读

租户隔离 — 无跨租户泄漏

令牌过期时显示 needs_reauth 标签

09 — Use Cases

实际应用场景

8 人团队，3 个 Codex Pro 账户

v2.34.0 之前

管理员手动轮换密钥
创建 3 个独立 Agent，用户手动选择 → 体验差

v2.34.0 之后

3 accounts OAuth → 3 named providers
Pool round_robin
Agent set inherit
8 用户，1 个 Agent，自动均匀分配
实时配额仪表板

工作负载分离

Priority Order

codex-heavy（Pro）→ 重任务 Agent
codex-light（Plus）→ 日常聊天 Agent
优先使用 Heavy，配额用尽后回退到 Light

10 — Internals

技术总结

Component	File	职责
Pool Validation	chatgpt_oauth_pool_validation.go	验证图：无循环，无双重所有权
Pool HTTP API	agents_codex_pool.go	CRUD 池配置、活动、健康
Quota Fetcher	oauth/openai_quota.go	OpenAI Usage API，解析配额窗口
Quota Transport	oauth/openai_quota_transport.go	HTTP 传输 + 认证注入
Token Mgmt	oauth/token.go	刷新令牌，元数据回填
Routing	agent/resolver.go	按策略解析 Provider
Store Types	store/agent_store.go	常量、路由配置结构
Dashboard	agent-codex-pool-page.tsx	Pool management UI
Quota UI	chatgpt-oauth-quota-*.tsx	Bars, badges, readiness

VI EN ZH JA