CODEX-MULTI-AUTH(1)
NAME
codex-multi-auth — OpenAI Codex CLI multi-account OAuth manager with resilient routing, quota-aware rotation, and terminal-first…
SYNOPSIS
INFO
29 stars
6 forks
0 views
DESCRIPTION
OpenAI Codex CLI multi-account OAuth manager with resilient routing, quota-aware rotation, and terminal-first diagnostics.
README
codex-multi-auth
Codex CLI-first multi-account OAuth manager for the official @openai/codex CLI.
[!NOTE] Legacy scoped prerelease package
@ndycode/codex-multi-authis migration-only. Usecodex-multi-authfor all new installs.
What You Get
- Canonical
codex auth ...workflow for account login, switching, checks, and diagnostics - 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 - 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 plugin, 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 wrapper package version.
codex --version
codex-multi-auth --version
codex auth status
For LLM Agents
Step-by-step
- 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
Verification
codex auth status
codex auth check
Quick Start
Install and sign in:
npm i -g @openai/codex
npm i -g codex-multi-auth
codex auth login
Verify the wrapper and the new account:
codex auth status
codex auth check
Use these next:
codex auth list
codex auth switch 2
codex auth forecast --live
If browser launch is blocked, use the alternate login paths in docs/getting-started.md.
Command Toolkit
Start here
| 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? |
Daily use
| 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? |
Repair
| Command | What it answers |
|---|---|
codex auth verify-flagged | Can any previously flagged account be restored? |
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? |
Advanced
| 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-codex | How do I run live repair probes with a chosen model? |
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 auth statussurfaces recent runtime request metrics in text output, andcodex auth report --jsonexposes the machine-readable cooldown/runtime snapshot
Dashboard Hotkeys
Main dashboard
| Key | Action |
|---|---|
Up / Down | Move selection |
Enter | Select/open |
1-9 | Quick switch |
/ | Search |
? | Toggle help |
Q | Back/cancel |
Account details
| Key | Action |
|---|---|
S | Set current account |
R | Refresh/re-login account |
E | Enable/disable account |
D | Delete account |
Storage Paths
| 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 |
| 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.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_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 --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.
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 auth doctor --fix
codex auth check
codex auth forecast --live
If still broken:
codex auth login
Common symptoms
codex authunrecognized: runwhere 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
Documentation
- 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
Release Notes
- Current stable: docs/releases/v1.2.6.md
- Previous stable: docs/releases/v1.2.5.md
- Earlier stable: docs/releases/v1.2.4.md
- Full release archive: docs/README.md#release-history
- Archived prerelease: docs/releases/v0.1.0-beta.0.md
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.
SEE ALSO
claude-code(1)— Anthropic's agentic coding assistant — AI pair programming in your terminalneovim(1)— Hyperextensible Vim-based text editor — the future of Vimtmux(1)— Terminal multiplexer — split panes, detach sessions, pair programaider(1)— AI pair programming in your terminal — works with any LLMhyperfine(1)— A command-line benchmarking tool — measure execution times
clihub4/10/2026CODEX-MULTI-AUTH(1)