Codex CLI-first multi-account OAuth manager for the official Codex CLI. The package installs conflict-free alongside official codex installs; use codex-multi-auth ... for account management or codex-multi-auth-codex ... when you explicitly want the forwarding wrapper.
Note
Legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only.
Use codex-multi-auth for all new installs.
- Conflict-free
codex-multi-auth ...workflow for account login, switching, checks, and diagnostics - Official Codex CLI forwarding for all non-auth commands
- Multi-account OAuth pool with health-aware selection and automatic failover
- Project-scoped account storage under
~/.codex/multi-auth/projects/<project-key>/... - Interactive dashboard for account actions and settings
- Experimental settings tab for staged sync, backup, and refresh-guard controls
- Forecast, report, fix, and doctor commands for operational safety
- Local usage ledger, budgets, account policy controls, routing profiles, and monitor views for local governance
- Runtime counters, budget/cooldown state, and multi-auth probe visibility in
codex-multi-auth status/codex-multi-auth report - Default-on runtime Responses proxy for live account rotation inside forwarded Codex CLI/app sessions
- Optional loopback-only local bridge for
/health,/v1/models, and/v1/responses, protected by hashed local client tokens - Reversible packaged Codex app bind and user-level launcher routing helpers
- Flagged account verification and restore flow
- Session affinity and live account sync controls
- Proactive refresh and preemptive quota deferral controls
- Codex-oriented request/prompt compatibility with strict runtime handling
- Stable docs set for install, config, troubleshooting, and upgrade paths
Terms and Usage Notice
[!CAUTION] This project uses OAuth account credentials and is intended for personal development use.
By using this package, you acknowledge:
- This is an independent open-source project, not an official OpenAI product
- You are responsible for your own usage and policy compliance
- For production/commercial workloads, use the OpenAI Platform API
For Humans
npm i -g codex-multi-authnpm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-authcodex --version confirms the official Codex CLI is reachable. codex-multi-auth --version confirms the installed manager package version. codex-multi-auth-codex --version is the optional forwarding wrapper entrypoint.
codex --version
codex-multi-auth --version
codex-multi-auth statusAny official install path is fine as long as codex is on PATH: npm i -g @openai/codex, brew install --cask codex, or an official release binary.
For LLM Agents
- Install global package:
npm i -g codex-multi-auth
- Run first login flow with
codex-multi-auth login - Validate state with
codex-multi-auth statusandcodex-multi-auth check - Confirm routing with
codex-multi-auth forecast --live
codex-multi-auth status
codex-multi-auth checkInstall and sign in:
npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth loginIf you already installed the official native CLI via Homebrew or a release binary, you only need:
npm i -g codex-multi-auth
codex-multi-auth loginVerify the manager and the new account:
codex-multi-auth status
codex-multi-auth checkUse these next:
codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --liveIf browser launch is blocked, use the alternate login paths in docs/getting-started.md.
For remote or headless shells, prefer codex-multi-auth login --device-auth.
| Command | What it answers |
|---|---|
codex-multi-auth login |
How do I add or re-open the account menu? |
codex-multi-auth status |
Is the wrapper active right now? |
codex-multi-auth check |
Do my saved accounts look healthy? |
| Command | What it answers |
|---|---|
codex-multi-auth list |
Which accounts are saved and which one is active? |
codex-multi-auth switch <index> |
How do I move to a different saved account? |
codex-multi-auth forecast --live |
Which account looks best for the next session? |
| Command | What it answers |
|---|---|
codex-multi-auth verify-flagged |
Can any previously flagged account be restored? |
codex-multi-auth verify --paths |
Do my storage path chain and sandbox probes still pass self-test? |
codex-multi-auth fix --dry-run |
What safe storage or account repairs are available? |
codex-multi-auth doctor --fix |
Can the CLI diagnose and apply the safest fixes now? |
| Command | What it answers |
|---|---|
codex-multi-auth report --live --json |
How do I get the full machine-readable health report? |
codex-multi-auth fix --live --model gpt-5.3-codex |
How do I run live repair probes with a chosen model? |
codex-multi-auth why-selected --json |
Which account does the selector pick now, and why? |
codex-multi-auth usage --since 24h --by project |
What local usage has been recorded recently? |
codex-multi-auth monitor --json |
What is the combined usage, policy, quota, runtime, and project state? |
codex-multi-auth bridge token create --label local-client |
How do I create a local bridge bearer token? |
codex-multi-auth integrations --kind python |
How do I generate local bridge client snippets? |
codex-multi-auth rotation status |
Is live runtime account rotation enabled for forwarded Codex sessions? |
- whole-pool replay is disabled by default when every account is rate-limited
- active requests use a bounded outbound request budget so one prompt cannot walk the full pool indefinitely
- repeated cross-account 5xx bursts trigger a short cooldown instead of continuing aggressive rotation
- proactive refresh is staggered to reduce background refresh bursts
codex-multi-auth statussurfaces recent runtime request metrics in text output, andcodex-multi-auth report --jsonexposes the machine-readable cooldown/runtime snapshot
| Key | Action |
|---|---|
Up / Down |
Move selection |
Enter |
Select/open |
1-9 |
Quick switch |
/ |
Search |
? |
Toggle help |
Q |
Back/cancel |
| Key | Action |
|---|---|
S |
Set current account |
R |
Refresh/re-login account |
E |
Enable/disable account |
D |
Delete account |
| File | Default path |
|---|---|
| Settings | ~/.codex/multi-auth/settings.json |
| Accounts | ~/.codex/multi-auth/openai-codex-accounts.json |
| Flagged accounts | ~/.codex/multi-auth/openai-codex-flagged-accounts.json |
| Quota cache | ~/.codex/multi-auth/quota-cache.json |
| Runtime observability | ~/.codex/multi-auth/runtime-observability.json |
| Usage ledger | ~/.codex/multi-auth/usage/usage-ledger.jsonl |
| Account policies | ~/.codex/multi-auth/account-policies.json |
| Routing profiles | ~/.codex/multi-auth/routing-profiles.json |
| Budget guards | ~/.codex/multi-auth/budget-guards.json |
| Local client tokens | ~/.codex/multi-auth/local-client-tokens.json |
| Runtime app helper status | ~/.codex/multi-auth/runtime-rotation-app-helper.json |
| Persistent app bind state/logs | ~/.codex/multi-auth/app-bind/ |
| Logs | ~/.codex/multi-auth/logs/codex-plugin/ |
| Per-project accounts | ~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json |
Override root with CODEX_MULTI_AUTH_DIR=<path>.
Primary config root:
~/.codex/multi-auth/settings.json- or
CODEX_MULTI_AUTH_DIR/settings.jsonwhen custom root is set
Selected runtime/environment overrides:
| Variable | Effect |
|---|---|
CODEX_MULTI_AUTH_DIR |
Override settings/accounts root |
CODEX_MULTI_AUTH_CONFIG_PATH |
Alternate config file path |
CODEX_MODE=0/1 |
Disable/enable Codex mode |
CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1 |
Opt out/in of live Responses proxy rotation for forwarded Codex CLI/app sessions |
CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS=<ms> |
Override automatic Codex app helper idle shutdown |
CODEX_MULTI_AUTH_APP_BIND_INSTALL=0/1 |
Opt out/in of packaged Codex app bind self-heal during install/update or rotation enable |
CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1 |
Opt out/in of routing supported app shortcuts during install/update or rotation enable |
CODEX_MULTI_AUTH_AUTO_UPDATE=0/1 |
Opt out/in of best-effort global package auto-update checks |
CODEX_TUI_V2=0/1 |
Disable/enable TUI v2 |
CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16 |
TUI color profile |
CODEX_TUI_GLYPHS=ascii|unicode|auto |
TUI glyph style |
CODEX_AUTH_BACKGROUND_RESPONSES=0/1 |
Opt in/out of stateful Responses background: true compatibility |
CODEX_AUTH_FETCH_TIMEOUT_MS=<ms> |
Request timeout override |
CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms> |
Stream stall timeout override |
Validate config after changes:
codex-multi-auth status
codex-multi-auth check
codex-multi-auth forecast --liveResponses background mode stays opt-in. Enable backgroundResponses in settings or CODEX_AUTH_BACKGROUND_RESPONSES=1 only for callers that intentionally send background: true, because those requests switch from stateless store=false routing to stateful store=true. See docs/upgrade.md for rollout guidance.
Runtime rotation is enabled by default for request-bearing wrapper-launched Codex sessions. Global install/update self-heals supported packaged Codex app binds and user-level launcher routing when possible, while codex-multi-auth rotation enable remains the explicit repair command. codex-multi-auth rotation disable turns the setting off and removes the persistent app bind. Set CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0, CODEX_MULTI_AUTH_APP_BIND_INSTALL=0, CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0, or CODEX_MULTI_AUTH_AUTO_UPDATE=0 to opt out of the matching default behavior.
The Settings menu now includes an Experimental section for staged features:
- preview-first sync into
oc-chatgpt-multi-auth - named local pool backup export with filename prompt
- refresh guard toggle and interval controls moved out of Backend Controls
These flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.
60-second recovery
codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --liveIf still broken:
codex-multi-auth loginCommon symptoms
codex authunrecognized: runwhere codexorwhich codex, then followdocs/troubleshooting.mdfor routing fallback commands- Switch succeeds but wrong account appears active: run
codex-multi-auth switch <index>, then restart session - Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect
codex-multi-auth status - Requests fail fast after repeated upstream 5xx errors: inspect
codex-multi-auth report --jsonfor runtime traffic and cooldown details - Storage cleanup fails with
EBUSY/EPERM(Windows): runcodex-multi-auth doctor --fixto retry, or manually remove~/.codex/multi-auth/<project-key>/and re-login - OAuth callback on port
1455fails: free the port and re-runcodex-multi-auth login - Browser launch is blocked or you are in a headless shell: prefer
codex-multi-auth login --device-auth; usecodex-multi-auth login --manualorCODEX_AUTH_NO_BROWSER=1only when you need the callback-paste fallback missing field id_token/token_expired/refresh_token_reused: re-login affected account
Diagnostics pack
codex-multi-auth list
codex-multi-auth status
codex-multi-auth check
codex-multi-auth verify-flagged --json
codex-multi-auth forecast --live
codex-multi-auth fix --dry-run
codex-multi-auth report --live --json
codex-multi-auth doctor --json- Docs portal: docs/README.md
- Getting started: docs/getting-started.md
- Features: docs/features.md
- Configuration: docs/configuration.md
- Troubleshooting: docs/troubleshooting.md
- Commands reference: docs/reference/commands.md
- Public API contract: docs/reference/public-api.md
- Error contracts: docs/reference/error-contracts.md
- Settings reference: docs/reference/settings.md
- Storage paths: docs/reference/storage-paths.md
- Upgrade guide: docs/upgrade.md
- Privacy: docs/privacy.md
- Current stable: docs/releases/v2.1.4.md
- Previous stable: docs/releases/v2.1.3.md
- Earlier stable: docs/releases/v2.1.2.md
- Earlier stable: docs/releases/v2.1.1.md
- Earlier stable: docs/releases/v2.1.0.md
- Earlier stable: docs/releases/v1.3.2.md
- Stable archive: docs/releases/v1.3.1.md
- Full release archive: docs/README.md#release-history
- Archived prerelease: docs/releases/v0.1.0-beta.0.md
MIT License. See LICENSE.
Legal
- Not affiliated with OpenAI.
- "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
- You assume responsibility for your own usage and compliance.