codex-multi-auth is a multi-account OAuth manager for the official @openai/codex CLI. It gives Codex CLI users explicit ChatGPT account login, account switching, health checks, local diagnostics, project-scoped storage, and default-on runtime Responses rotation without taking over the official codex binary. Use codex-multi-auth ... for account management, or codex-multi-auth-codex ... only when you intentionally want the optional forwarding wrapper.
Use it when you need a local Codex CLI multi-account workflow with visible account state, safer recovery commands, and a loopback-only runtime rotation proxy for request-bearing forwarded Codex sessions.
Note
Legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only.
Use codex-multi-auth for all new installs.
- Codex CLI multi-account OAuth management with a dedicated
codex-multi-auth ...command family - Explicit ChatGPT account login, saved-account listing, account switching, health checks, and diagnostics
- Optional
codex-multi-auth-codex ...forwarding wrapper for official Codex CLI commands when you choose wrapper-launched sessions - Health-aware account selection, quota forecasting, automatic failover, and flagged-account recovery
- Project-scoped account storage under
~/.codex/multi-auth/projects/<project-key>/...for repo-specific workflows - Interactive terminal dashboard for account actions, settings, search, and hotkeys
- Forecast, report, fix, doctor, verify, monitor, and rotation commands for operational confidence
- Local usage ledger, budget guards, account policy controls, routing profiles, and model/account capability views
- Runtime counters, budget/cooldown state, and multi-auth probe visibility in
codex-multi-auth status/codex-multi-auth report - Default-on loopback 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 that do not patch official app binaries
- Session affinity, live account sync, proactive refresh, and preemptive quota deferral controls
- Codex-oriented request/prompt compatibility with strict runtime handling and documented error contracts
- Stable docs for install, configuration, troubleshooting, upgrade, public API, storage paths, and release notes
codex-multi-auth makes local Codex account state visible and recoverable. Instead of one opaque auth file, you get a named account pool, deterministic account switching, health-aware selection, JSON diagnostics for automation, and safe repair commands for stale or damaged local state. The architecture is designed for personal development workflows: credentials stay local, runtime rotation is loopback-only, and official Codex install paths keep owning the codex command.
codex-multi-auth now ships three distinct global binaries:
| Binary | Purpose |
|---|---|
codex-multi-auth |
Primary account manager; accepts bare auth subcommands such as login, status, switch, forecast, and rotation status |
codex-multi-auth-codex |
Optional wrapper that handles auth ... locally and forwards every other command to the official Codex CLI |
codex-multi-auth-app-launcher |
Optional desktop launcher helper for supported user-level shortcuts and wrapper apps |
The package does not publish a global codex binary. Keep codex owned by the official OpenAI install path and use codex-multi-auth-codex ... only when you intentionally want this package's forwarding wrapper.
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? |
codex-multi-auth uninstall |
Remove residual artifacts (run BEFORE npm uninstall; npm@7+ no longer fires preuninstall) |
| 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_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, or CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0 to opt out of the matching default behavior.
Installed wrappers may perform a best-effort daily npm version check during normal forwarded Codex startup. When a newer package is detected, the wrapper only prints a manual notice on an interactive TTY or when CODEX_MULTI_AUTH_DEBUG=1: npm install -g codex-multi-auth@latest. It never runs npm install or update commands for you.
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-multi-authunrecognized: runwhere codex-multi-authorwhich codex-multi-auth, then followdocs/troubleshooting.mdfor install checks- 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.7.md
- Previous stable: docs/releases/v2.1.6.md
- Earlier stable: docs/releases/v2.1.5.md
- Earlier stable: docs/releases/v2.1.4.md
- Earlier 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.