GoClaw v2.34.0

Codex OAuth Pools

Pool multiple OpenAI Codex accounts into one unified endpoint. Automatic request routing. Real-time quota monitoring.

scroll

01 — Problem

Rate limits per individual account

OpenAI enforces rate limits per subscription account. With 3–5 Codex accounts (Pro, Plus, Team), you have to juggle them manually.

Manual switching when quota runs out

Don't know which account has remaining capacity

No way to aggregate throughput

For a team of 5–10 sharing a gateway, this problem multiplies.

02 — How it works

Four steps to set up

Register OAuth

Each Codex/ChatGPT account becomes a separate named provider. GoClaw stores refresh tokens and handles token refresh automatically.

Create Pool

Pick one provider as the owner, add others to codex_pool.extra_provider_names.

Choose Strategy

Configure how requests are distributed: primary first, round robin, or priority order.

Agent Inherit

Set override_mode: "inherit" — agent automatically inherits pool config from provider.

Pool Validation

✓ No self-reference ✓ One pool per member ✓ Owner ≠ member ✓ All chatgpt_oauth type

03 — Architecture

Request pipeline

GoClaw Gateway — Request Flow

User Message

→

Agent Loop

→

Resolver

→

Routing Engine

↓

Codex OAuth Pool

codex-pro-1

35%

healthy

codex-pro-2

85%

healthy

codex-team

10%

degraded

04 — Routing

Three routing strategies

Strategy	Behavior
`primary_first`	Always use owner first, failover to members on error
`round_robin`	Round-robin across all accounts in the pool
`priority_order`	Use in priority order, auto-switch on account errors

05 — Key Feature

Inherited Routing Defaults

Agents inherit routing config from the provider — configure once, all agents benefit automatically.

Provider

"codex-main"

Pool owner

codex-backup

codex-team

round_robin

inherit

Agent

"assistant"

Provider: codex-main

Override: inherit

(no pool config needed)

✓ Configure once at provider level — all agents using that provider benefit
✓ Change pool membership? Edit the provider, agents update automatically
✓ Agents can still override if needed — override_mode: "custom"

06 — Monitoring

Quota real-time

GoClaw calls the OpenAI Usage API to fetch quota for each account in the pool.

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

The gateway tracks health per account via tracing data. When an account fails repeatedly, the routing engine switches to another automatically.

Success Rate

94%

Successful requests

Health Score

Composite score

Consec. Failures

Consecutive errors

State

healthy

08 — Security

Access control

Only admin/operator can manage pool

Viewer: dashboard read-only

Tenant isolation — no cross-tenant leak

Badge needs_reauth when token expires

09 — Use Cases

Real-world use cases

Team of 8, 3 Codex Pro accounts

Before v2.34.0

Admin manually rotates keys when quota runs out
Create 3 separate agents, users pick manually → bad UX

After v2.34.0

3 accounts OAuth → 3 named providers
Pool round_robin
Agent set inherit
8 users, 1 agent, auto-distributed evenly
Real-time quota dashboard

Workload separation

Priority Order

codex-heavy (Pro) → heavy tasks agent
codex-light (Plus) → casual chat agent
Heavy first, fallback to light when quota runs out

10 — Internals

Technical summary

Component	File	Role
Pool Validation	chatgpt_oauth_pool_validation.go	Validate graph: no cycles, no dual-ownership
Pool HTTP API	agents_codex_pool.go	CRUD pool config, activity, health
Quota Fetcher	oauth/openai_quota.go	OpenAI Usage API, parse quota windows
Quota Transport	oauth/openai_quota_transport.go	HTTP transport + auth injection
Token Mgmt	oauth/token.go	Refresh token, metadata backfill
Routing	agent/resolver.go	Resolve provider by strategy
Store Types	store/agent_store.go	Constants, routing config structs
Dashboard	agent-codex-pool-page.tsx	Pool management UI
Quota UI	chatgpt-oauth-quota-*.tsx	Bars, badges, readiness

VI EN ZH JA