codex-multi-auth: multi-account OAuth for the official Codex CLI

June 7, 2026 · View on GitHub

npm version npm downloads CI MIT license

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.

codex-multi-auth terminal dashboard for Codex CLI multi-account OAuth account status

Note

Legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only. Use codex-multi-auth for all new installs.

What You Get

  • 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

Why Developers Use It

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.

Current Architecture At A Glance

codex-multi-auth now ships three distinct global binaries:

BinaryPurpose
codex-multi-authPrimary account manager; accepts bare auth subcommands such as login, status, switch, forecast, and rotation status
codex-multi-auth-codexOptional wrapper that handles auth ... locally and forwards every other command to the official Codex CLI
codex-multi-auth-app-launcherOptional 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

Installation

For Humans

Option A: Standard install

npm i -g codex-multi-auth

Option B: Migrate from legacy scoped prerelease

npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

Option C: Verify wiring

codex --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 status

Any 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

Step-by-step

  1. Install global package:
    • npm i -g codex-multi-auth
  2. Run first login flow with codex-multi-auth login
  3. Validate state with codex-multi-auth status and codex-multi-auth check
  4. Confirm routing with codex-multi-auth forecast --live

Verification

codex-multi-auth status
codex-multi-auth check

Quick Start

Install and sign in:

npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth login

If 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 login

Verify the manager and the new account:

codex-multi-auth status
codex-multi-auth check

Use these next:

codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --live

If 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 Toolkit

Start here

CommandWhat it answers
codex-multi-auth loginHow do I add or re-open the account menu?
codex-multi-auth statusIs the wrapper active right now?
codex-multi-auth checkDo my saved accounts look healthy?

Daily use

CommandWhat it answers
codex-multi-auth listWhich 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 --liveWhich account looks best for the next session?

Repair

CommandWhat it answers
codex-multi-auth verify-flaggedCan any previously flagged account be restored?
codex-multi-auth verify --pathsDo my storage path chain and sandbox probes still pass self-test?
codex-multi-auth fix --dry-runWhat safe storage or account repairs are available?
codex-multi-auth doctor --fixCan the CLI diagnose and apply the safest fixes now?
codex-multi-auth uninstallRemove residual artifacts (run BEFORE npm uninstall; npm@7+ no longer fires preuninstall)

Advanced

CommandWhat it answers
codex-multi-auth report --live --jsonHow do I get the full machine-readable health report?
codex-multi-auth fix --live --model gpt-5.5How do I run live repair probes with a chosen model?
codex-multi-auth why-selected --jsonWhich account does the selector pick now, and why?
codex-multi-auth usage --since 24h --by projectWhat local usage has been recorded recently?
codex-multi-auth monitor --jsonWhat is the combined usage, policy, quota, runtime, and project state?
codex-multi-auth bridge token create --label local-clientHow do I create a local bridge bearer token?
codex-multi-auth integrations --kind pythonHow do I generate local bridge client snippets?
codex-multi-auth rotation statusIs live runtime account rotation enabled for forwarded Codex sessions?

Reliability behavior

  • 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 status surfaces recent runtime request metrics in text output, and codex-multi-auth report --json exposes the machine-readable cooldown/runtime snapshot

Dashboard Hotkeys

Main dashboard

KeyAction
Up / DownMove selection
EnterSelect/open
1-9Quick switch
/Search
?Toggle help
QBack/cancel

Account details

KeyAction
SSet current account
RRefresh/re-login account
EEnable/disable account
DDelete account

Storage Paths

FileDefault 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>.

Configuration

Primary config root:

  • ~/.codex/multi-auth/settings.json
  • or CODEX_MULTI_AUTH_DIR/settings.json when custom root is set

Selected runtime/environment overrides:

VariableEffect
CODEX_MULTI_AUTH_DIROverride settings/accounts root
CODEX_MULTI_AUTH_CONFIG_PATHAlternate config file path
CODEX_MODE=0/1Disable/enable Codex mode
CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1Opt 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/1Opt out/in of packaged Codex app bind self-heal during install/update or rotation enable
CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1Opt out/in of routing supported app shortcuts during install/update or rotation enable
CODEX_TUI_V2=0/1Disable/enable TUI v2
CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16TUI color profile
CODEX_TUI_GLYPHS=ascii|unicode|autoTUI glyph style
CODEX_AUTH_BACKGROUND_RESPONSES=0/1Opt 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 --live

Responses 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.

Experimental Settings Highlights

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.

Troubleshooting

60-second recovery 
codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --live

If still broken:

codex-multi-auth login
Common symptoms
  • codex-multi-auth unrecognized: run where codex-multi-auth or which codex-multi-auth, then follow docs/troubleshooting.md for 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 --json for runtime traffic and cooldown details
  • Storage cleanup fails with EBUSY / EPERM (Windows): run codex-multi-auth doctor --fix to retry, or manually remove ~/.codex/multi-auth/<project-key>/ and re-login
  • OAuth callback on port 1455 fails: free the port and re-run codex-multi-auth login
  • Browser launch is blocked or you are in a headless shell: prefer codex-multi-auth login --device-auth; use codex-multi-auth login --manual or CODEX_AUTH_NO_BROWSER=1 only 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

Documentation

Release Notes

License

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.