GoClaw v2.34.0

Codex OAuth Pools

Gộp nhiều tài khoản OpenAI Codex thành một pool thống nhất. Route request tự động. Theo dõi quota real-time.

scroll

01 — Vấn đề

Rate limit theo từng account

OpenAI giới hạn rate limit theo từng tài khoản subscription. Với 3–5 tài khoản Codex, bạn phải xoay xở thủ công.

Chuyển đổi thủ công khi hết quota

Không biết account nào còn dư

Không aggregate được throughput

Với team 5–10 người dùng chung gateway, vấn đề nhân lên gấp bội.

02 — Cách hoạt động

Bốn bước thiết lập

Đăng ký OAuth

Mỗi tài khoản Codex/ChatGPT thành một named provider riêng biệt. GoClaw lưu refresh token, tự xử lý token refresh.

Tạo Pool

Chọn provider owner, thêm members vào codex_pool.extra_provider_names.

Chọn Strategy

Cấu hình cách phân bổ request: primary first, round robin, hoặc priority order.

Agent Inherit

Set override_mode: "inherit" — agent tự nhận pool config từ provider.

Pool Validation

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

03 — Kiến trúc

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

Ba chiến lược phân bổ

Strategy	Hành vi
`primary_first`	Luôn dùng owner trước, failover sang member khi lỗi
`round_robin`	Xoay vòng đều giữa tất cả accounts trong pool
`priority_order`	Dùng theo thứ tự ưu tiên, tự chuyển khi account gặp lỗi

05 — Điểm đặc biệt

Inherited Routing Defaults

Agent inherit routing config từ provider — cấu hình một lần, tất cả agents tự hưởng.

Provider

"codex-main"

Pool owner

codex-backup

codex-team

round_robin

inherit

Agent

"assistant"

Provider: codex-main

Override: inherit

(no pool config)

✓ Cấu hình một lần tại provider level — tất cả agents dùng provider đó đều được hưởng
✓ Thay đổi pool membership? Sửa ở provider, agents tự cập nhật
✓ Agent vẫn có thể override nếu cần — override_mode: "custom"

06 — Monitoring

Quota real-time

GoClaw gọi OpenAI Usage API để lấy quota cho mỗi account trong 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

Gateway track health mỗi account qua tracing data. Khi một account liên tục lỗi, routing engine tự chuyển sang account khác.

Success Rate

94%

Request thành công

Health Score

Điểm tổng hợp

Consec. Failures

Lỗi liên tiếp

State

healthy

08 — Security

Access control

🔒

Chỉ admin/operator quản lý pool

👁

Viewer: dashboard read-only

🏢

Tenant isolation — no cross-tenant leak

🔑

Badge needs_reauth khi token expired

09 — Use Cases

Thực tế triển khai

Team 8 người, 3 Codex Pro accounts

Trước v2.34.0

Admin rotate key thủ công khi hết quota
Tạo 3 agents riêng, user tự chọn → UX kém

Sau v2.34.0

3 accounts OAuth → 3 named providers
Pool round_robin
Agent set inherit
8 users, 1 agent, tự phân bổ đều
Dashboard quota real-time

Tách biệt workload

Priority Order

codex-heavy (Pro) → agent xử lý task nặng
codex-light (Plus) → agent chat thường
Heavy trước, fallback sang light khi hết quota

10 — Internals

Tóm tắt kỹ thuật

Component	File	Vai trò
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 theo 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