docs: highlight codex multi-account auth

Author: lidge-jun

README.md

@@ -17,13 +17,33 @@ Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM wi
 
 opencodex is a lightweight local proxy that translates Codex's Responses API into whatever your provider speaks. Streaming, tool calls, reasoning tokens, images — everything works, in both directions.
 
+It can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
+refresh their 5h / weekly / 30d quota in the dashboard, and let new sessions auto-route to the
+lowest-usage healthy account. Existing Codex threads stay pinned to the account that started them,
+so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation.
+
 ```
 Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
                                               │
               Anthropic · Google · xAI · Kimi · Ollama Cloud · Groq
               OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself
 ```
 
+```mermaid
+flowchart LR
+  codex[Codex session<br/>CLI, App, SSH, mobile] --> proxy[opencodex]
+  proxy --> existing{Existing thread?}
+  existing -->|yes| pinned[Keep the same<br/>ChatGPT account]
+  existing -->|new session| quota[Refresh quota<br/>5h, weekly, 30d]
+  quota --> pick[Pick lowest-usage<br/>healthy account]
+  pick --> upstream[ChatGPT / Codex backend]
+  pinned --> upstream
+  upstream --> outcomes[Quota / auth outcome]
+  outcomes -->|429| cooldown[Cooldown + failover]
+  outcomes -->|401 / 403| reauth[Mark reauth needed]
+  cooldown --> quota
+```
+
 ## Supported platforms
 
 | OS | Status | Service manager |
@@ -115,9 +135,27 @@ Routed models also appear in the **Codex App** model picker with per-model reaso
   <img src="assets/codex-app-picker.png" alt="Codex App showing opencodex routed models with reasoning effort picker" width="480">
 </p>
 
+## ChatGPT account pool
+
+Open **Codex Auth** in the dashboard to add pool accounts and choose which account should handle the
+next Codex session. opencodex keeps two separate behaviors:
+
+- **Existing sessions keep affinity.** A thread id is bound to the selected account and reused on
+  later turns, so a long request or a mobile/SSH-attached session keeps using the same account.
+- **New sessions can auto-route.** When auto-switch is enabled, opencodex compares the hottest known
+  quota window across 5h, weekly, and 30d usage, then picks a lower-usage eligible account for new
+  sessions once the active account crosses the threshold.
+- **Quota lookup is built in.** The dashboard can refresh all account quotas in one click, and the
+  request log labels pool traffic with non-PII account ordinals.
+- **Failures fail closed.** Token failures mark reauthentication instead of falling back to another
+  credential silently; 429 quota responses put the account in cooldown and can fail over future work
+  to another eligible pool account.
+
 ## Highlights
 
 - **Use any LLM with Codex.** 5 protocol adapters cover Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint — that's 40+ providers out of the box.
+- **Pool ChatGPT accounts safely.** Keep existing Codex threads on one account while new sessions
+  can auto-pick a lower-usage account from the pool, with quota refresh and non-PII request labels.
 - **Log in once, skip the API key.** OAuth support for xAI, Anthropic, and Kimi means you can authenticate with your existing account. Tokens auto-refresh. Or forward your `codex login`, paste an API key, or use `${ENV_VAR}` references — your call.
 - **Works everywhere Codex does.** Injects into Codex CLI, TUI, App, and SDK automatically. Routed models show up in Codex's model picker just like native ones.
 - **Delegate to the right model.** Feature up to five routed or native models in Codex's subagent picker from the dashboard or config — route complex tasks to a reasoning model, fast tasks to a cheap one.

docs-site/src/assets/multi-auth-routing.svg

@@ -21,6 +21,23 @@ the streamed answer back into Responses events — so Codex never knows it isn't
             └─────────────────────────────────────────────────────────────────────┘
 ```
 
+![Codex multi-account routing: existing threads keep the same ChatGPT account, while new sessions can refresh quota and select a lower-usage healthy account.](../../../assets/multi-auth-routing.svg)
+
+## Codex auth account selection
+
+When the selected provider is the ChatGPT/Codex passthrough, opencodex can choose a stored pool
+account before the request is forwarded upstream. The rule is intentionally split:
+
+- **Existing thread ids keep affinity.** A thread is bound to the account generation that started it,
+  so a long SSH, tmux, or mobile-attached Codex session keeps using one account instead of being
+  rebalanced mid-conversation.
+- **New sessions can rebalance.** For a new thread, opencodex compares known quota usage across 5h,
+  weekly, and 30d windows, skips accounts that need reauthentication or are in cooldown, and can
+  switch to a lower-usage eligible account when the active account crosses the configured threshold.
+- **Quota and failure signals feed routing.** The dashboard can force a quota refresh with
+  `GET /api/codex-auth/accounts?refresh=1`; successful upstream responses capture quota headers,
+  429 puts an account in cooldown, and 401/403 marks it for reauthentication.
+
 ## The lifecycle
 
 <Steps>
@@ -38,7 +55,9 @@ the streamed answer back into Responses events — so Codex never knows it isn't
    the `defaultProvider` fallback. See [Model Routing](/opencodex/guides/model-routing/).
 
 3. **Authenticate** — for an `oauth` provider, opencodex swaps in a fresh, auto-refreshed access
-   token as the bearer key, so the existing adapters authenticate unchanged.
+   token as the bearer key, so the existing adapters authenticate unchanged. For ChatGPT/Codex pool
+   accounts, `codex-auth-context.ts` resolves the account first and the passthrough adapter refuses
+   to continue if the required pool credential is unavailable.
 
 4. **Vision sidecar (optional)** — if the routed model is listed in `provider.noVisionModels` and the
    request carries an image, opencodex describes each image with a `gpt-5.4-mini` vision model over

docs-site/src/content/docs/getting-started/how-it-works.mdx

@@ -4,7 +4,8 @@ description: The opencodex GUI — proxy status, provider management, model pick
 ---
 
 opencodex ships a local web dashboard (a Vite/React app under `gui/`) served from the proxy. It's the
-easiest way to add providers, log in with OAuth, choose subagent models, and watch traffic.
+easiest way to add providers, manage Codex/ChatGPT auth accounts, choose subagent models, and watch
+traffic.
 
 ## Opening it
 
@@ -28,11 +29,25 @@ cd gui && bun dev
 | **Providers** | Add, edit, enable/disable, and remove providers. |
 | **Add provider** | A searchable picker of presets — OAuth login (xAI / Anthropic / Kimi), ChatGPT forward, the API-key catalog (incl. Ollama Cloud), local servers, and Custom. |
 | **OAuth login** | Opens the provider's auth page and polls until the token lands; or imports an existing local CLI/keychain token. |
+| **Codex Auth** | Add ChatGPT/Codex pool accounts, choose the next-session account, refresh 5h / weekly / 30d quotas, and set auto-switch / failover thresholds. |
 | **Subagent models** | Pick the ≤5 routed models Codex's `spawn_agent` advertises. |
 | **Models** | Enable/disable individual routed models (hidden ones are excluded from the catalog and `/v1/models`). |
 | **Request log** | Auto-refreshing view of recent requests (model, provider, status). |
 | **Stop** | A sidebar button that gracefully shuts down the proxy, stops the background service if installed, and restores native Codex — all in one click (`POST /api/stop`). |
 
+## Codex Auth and account pools
+
+The **Codex Auth** page is for the native ChatGPT/Codex path. It separates existing sessions from
+new sessions:
+
+- Existing Codex thread ids keep their selected account, which makes SSH, tmux, and mobile-attached
+  sessions stable. A long-running conversation does not silently move between accounts.
+- New sessions can automatically use the lowest-usage eligible account when auto-switch is enabled.
+  The score uses the hottest known quota window across 5h, weekly, and 30d usage.
+- The quota refresh button calls the proxy to re-read account usage immediately, so routing and the
+  visible account cards stay in sync.
+- Pool request logs use non-PII labels such as `chatgpt-1`, not account emails.
+
 ## How the dashboard talks to the proxy
 
 The GUI is a thin client over the proxy's management API. Useful endpoints (all JSON):
@@ -45,6 +60,11 @@ The GUI is a thin client over the proxy's management API. Useful endpoints (all
 | `GET /api/key-providers` | The API-key catalog (incl. Ollama Cloud). |
 | `GET /api/oauth/providers` | Which providers support OAuth login. |
 | `POST /api/oauth/login` · `GET /api/oauth/status` | Start an OAuth flow and poll for completion. |
+| `GET /api/codex-auth/accounts?refresh=1` | List main + pool accounts and force quota refresh. |
+| `PUT /api/codex-auth/active` | Choose the account used for the next new Codex session. |
+| `PUT /api/codex-auth/auto-switch` | Set the quota threshold for automatic new-session account selection. |
+| `PUT /api/codex-auth/failover` | Set how many transient upstream failures trigger future-session failover. |
+| `POST /api/codex-auth/login` · `GET /api/codex-auth/login-status` | Add a pool account through the browser login flow. |
 | `GET` / `PUT /api/subagent-models` | Read / set the featured subagent models. |
 | `POST /api/stop` | Gracefully stop the proxy (and the background service if installed), restore native Codex, then exit. |
 

docs-site/src/content/docs/guides/web-dashboard.md

@@ -28,6 +28,10 @@ and any LLM provider. Codex only speaks the **Responses API** (`/v1/responses`);
 that protocol — in both directions, including streaming, tool calls, reasoning, and images — into
 whatever wire format your provider expects, then translates the answer back.
 
+For Codex's native ChatGPT auth path, opencodex can also manage a **multi-account pool**. Existing
+threads keep the same selected account for reliable SSH, tmux, and mobile-attached sessions, while
+new sessions can automatically pick a lower-usage healthy account after quota refresh.
+
 ```
 Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
                                               │
@@ -48,6 +52,10 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
     Log in with your xAI, Anthropic, or Kimi account (OAuth, auto-refreshed), forward your ChatGPT
     login, or paste an API key. Keys can be `${ENV_VARS}`.
   </Card>
+  <Card title="ChatGPT account pool" icon="puzzle">
+    Add multiple Codex/ChatGPT accounts, refresh 5h / weekly / 30d quota from the dashboard, and let
+    new sessions auto-route to the lowest-usage eligible account without moving existing threads.
+  </Card>
   <Card title="Drops into Codex" icon="rocket">
     `ocx init` injects a provider into `$CODEX_HOME/config.toml` (default
     `~/.codex/config.toml`) and writes a shared Codex catalog, so Codex CLI, TUI, App, and SDK

docs-site/src/content/docs/index.mdx

@@ -21,6 +21,23 @@ Responses 이벤트로 변환합니다 — 그래서 Codex는 자신이 OpenAI
             └─────────────────────────────────────────────────────────────────────┘
 ```
 
+![Codex 멀티 계정 라우팅: 기존 thread는 같은 ChatGPT 계정을 유지하고, 새 세션은 할당량을 조회해 사용량이 낮은 정상 계정을 선택할 수 있습니다.](../../../../assets/multi-auth-routing.svg)
+
+## Codex 인증 계정 선택
+
+선택된 프로바이더가 ChatGPT/Codex 패스스루일 때, opencodex는 업스트림으로 전달하기 전에 저장된
+pool 계정을 고를 수 있습니다. 규칙은 의도적으로 둘로 나뉩니다.
+
+- **기존 thread id는 같은 계정을 유지합니다.** thread는 시작할 때 선택된 account generation에
+  묶입니다. 그래서 SSH, tmux, 모바일 연결로 이어지는 긴 Codex 세션은 대화 중간에 다른 계정으로
+  재분배되지 않습니다.
+- **새 세션은 다시 분배할 수 있습니다.** 새 thread에서는 5시간, 주간, 30일 할당량 중 알려진
+  사용량을 비교하고, 재인증이 필요하거나 cooldown 중인 계정을 건너뛴 뒤, 활성 계정이 설정된
+  임계값을 넘으면 사용량이 더 낮은 정상 계정으로 전환할 수 있습니다.
+- **할당량과 실패 신호가 라우팅에 반영됩니다.** 대시보드는
+  `GET /api/codex-auth/accounts?refresh=1`로 할당량을 강제 재조회할 수 있습니다. 성공한 업스트림
+  응답은 할당량 헤더를 저장하고, 429는 계정을 cooldown에 넣으며, 401/403은 재인증 필요 상태로 표시합니다.
+
 ## 수명 주기
 
 <Steps>
@@ -38,7 +55,9 @@ Responses 이벤트로 변환합니다 — 그래서 Codex는 자신이 OpenAI
    `defaultProvider` 폴백. [모델 라우팅](/opencodex/ko/guides/model-routing/)을 참고하세요.
 
 3. **Authenticate** — `oauth` 프로바이더의 경우, opencodex가 새로 자동 갱신된 access
-   토큰을 bearer 키로 교체하므로, 기존 adapter들은 변경 없이 인증됩니다.
+   토큰을 bearer 키로 교체하므로, 기존 adapter들은 변경 없이 인증됩니다. ChatGPT/Codex pool
+   계정에서는 `codex-auth-context.ts`가 먼저 계정을 해석하고, 필요한 pool credential이 없으면
+   passthrough adapter가 계속 진행하지 않습니다.
 
 4. **Vision sidecar(선택)** — 라우팅된 모델이 `provider.noVisionModels`에 나열되어 있고
    요청에 이미지가 포함된 경우, opencodex는 ChatGPT 로그인을 통한 `gpt-5.4-mini` vision 모델로