Codex CLI-first multi-account OAuth manager for the official Codex CLI. The installed codex wrapper handles codex auth ... locally, forwards normal Codex commands to the official runtime, and can optionally route live Responses traffic through a localhost account-rotation proxy.
Note
Legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only.
Use codex-multi-auth for all new installs.
- Canonical
codex 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
- Runtime counters, budget/cooldown state, and multi-auth probe visibility in
codex auth status/codex auth report - Default-on runtime Responses proxy for live account rotation inside forwarded Codex CLI/app sessions
- 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 wrapper package version.
codex --version
codex-multi-auth --version
codex 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 auth login - Validate state with
codex auth statusandcodex auth check - Confirm routing with
codex auth forecast --live
codex auth status
codex auth checkInstall and sign in:
npm i -g @openai/codex
npm i -g codex-multi-auth
codex 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 auth loginVerify the wrapper and the new account:
codex auth status
codex auth checkUse these next:
codex auth list
codex auth switch 2
codex auth forecast --liveIf browser launch is blocked, use the alternate login paths in docs/getting-started.md.
| Command | What it answers |
|---|---|
codex auth login |
How do I add or re-open the account menu? |
codex auth status |
Is the wrapper active right now? |
codex auth check |
Do my saved accounts look healthy? |
| Command | What it answers |
|---|---|
codex auth list |
Which accounts are saved and which one is active? |
codex auth switch <index> |
How do I move to a different saved account? |
codex auth forecast --live |
Which account looks best for the next session? |
| Command | What it answers |
|---|---|
codex auth verify-flagged |
Can any previously flagged account be restored? |
codex auth verify --paths |
Do my storage path chain and sandbox probes still pass self-test? |
codex auth fix --dry-run |
What safe storage or account repairs are available? |
codex auth doctor --fix |
Can the CLI diagnose and apply the safest fixes now? |
| Command | What it answers |
|---|---|
codex auth report --live --json |
How do I get the full machine-readable health report? |
codex auth fix --live --model gpt-5.3-codex |
How do I run live repair probes with a chosen model? |
codex auth why-selected --json |
Which account does the selector pick now, and why? |
codex 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 auth statussurfaces recent runtime request metrics in text output, andcodex 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 |
| 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 |
| `CODEX_TUI_GLYPHS=ascii | unicode |
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 auth status
codex auth check
codex 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 auth rotation enable remains the explicit repair command. codex 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 auth doctor --fix
codex auth check
codex auth forecast --liveIf still broken:
codex auth loginCommon symptoms
codex authunrecognized: runwhere codexorwhich codex, then followdocs/troubleshooting.mdfor routing fallback commands- Switch succeeds but wrong account appears active: run
codex auth switch <index>, then restart session - Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect
codex auth status - Requests fail fast after repeated upstream 5xx errors: inspect
codex auth report --jsonfor runtime traffic and cooldown details - Storage cleanup fails with
EBUSY/EPERM(Windows): runcodex 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 auth login - Browser launch is blocked or you are in a headless shell: re-run
codex auth login --manualor setCODEX_AUTH_NO_BROWSER=1 missing field id_token/token_expired/refresh_token_reused: re-login affected account
Diagnostics pack
codex auth list
codex auth status
codex auth check
codex auth verify-flagged --json
codex auth forecast --live
codex auth fix --dry-run
codex auth report --live --json
codex 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.0.1.md
- Previous stable: docs/releases/v1.3.2.md
- Earlier stable: 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.