Skip to main content
Codex Multi-Auth enables you to manage multiple ChatGPT Codex accounts, seamlessly switch between them, and track their availability and quota status.

​
Adding Accounts

Add new accounts through the OAuth browser flow:
1

Start the login process

Run the login command to open the OAuth flow:
codex auth login
2

Complete browser authentication

Your default browser will open to http://127.0.0.1:1455/auth/callback to authenticate with ChatGPT. Complete the OAuth flow in the browser window.
3

Return to terminal

After successful authentication, return to your terminal. The account will be added to your pool and automatically selected.
The OAuth callback server runs on port 1455 at 127.0.0.1. If this port is already in use, stop the conflicting process before attempting login.

​
Viewing Accounts

List all accounts in your pool with their current status: 
codex auth list
This displays:
  • Account index (for switching)
  • Email address (case-insensitive deduplication)
  • Health score (0-100)
  • Active status
  • Last used timestamp
For detailed account metadata: 
codex auth status

​
Switching Accounts

Switch to a different account by index:
1

Identify the target account

Run codex auth list to see available accounts and their indices.
2

Switch to the account

codex auth switch <index>
Replace <index> with the account number from the list.
3

Verify the switch

codex auth status
The active account should now reflect your selection.
If the switch succeeds but the wrong account is used, stale Codex CLI state may be cached. Re-run the switch command or restart your terminal session.

​
Account Health Checks

Verify account health and token validity:

​
Quick Health Check

codex auth check
This validates:
  • Token expiration status (with 60-second refresh skew window)
  • Refresh token validity
  • Account reachability

​
Live Forecast

Check real-time quota availability for a specific model: 
codex auth forecast --live --model gpt-5-codex
This queries the ChatGPT backend to determine:
  • 5-hour quota window status
  • 7-day quota window status
  • Recommended account selection

​
Comprehensive Diagnostics

codex auth doctor --json
Outputs:
  • Health scores for all accounts
  • Flagged accounts (expired/invalid tokens)
  • Configuration conflicts
  • Storage path validation

​
Account Health Scoring

Accounts are scored from 0-100 based on:
EventHealth Impact
Successful requestHealth restored to 100
Network error (5xx)Health decremented, cooldown applied (6s default)
Rate limit hitHealth decremented, cooldown applied
Token refresh failureAccount marked unhealthy
Token expirationAccount flagged, requires re-login
The selection algorithm prioritizes accounts with:
  1. Higher health scores
  2. Available quota (5-hour and 7-day windows)
  3. No active cooldown periods

​
Session Affinity

By default, session affinity keeps you on the same account for a conversation:
  • TTL: 20 minutes (configurable via sessionAffinityTtlMs)
  • Max entries: 512 conversations tracked
  • Behavior: Reuses the same account for a session ID unless health degrades
Disable session affinity if you prefer strict round-robin or health-based rotation: 
export CODEX_AUTH_SESSION_AFFINITY=0

​
Proactive Token Refresh

The Proactive Refresh Guardian automatically refreshes tokens before expiration:
  • Check interval: 60 seconds (default)
  • Buffer window: 5 minutes before expiration
  • Background operation: Runs independently of active requests
This prevents mid-conversation token expiration. It respects refresh lease locks to avoid race conditions with concurrent token updates.

​
Fixing Unhealthy Accounts

When accounts become unhealthy due to expired tokens or connectivity issues:
1

Run the doctor command

codex auth doctor --fix
This attempts to refresh all unhealthy accounts automatically.
2

Verify repairs

codex auth check
Confirm that flagged accounts have been restored.
3

Re-login if needed

If automatic repair fails, re-authenticate the affected account:
codex auth login

​
Common Token Errors

ErrorCauseSolution
missing field id_tokenStale auth payloadRe-login the account
refresh_token_reusedToken pair rotated elsewhereRe-login the account
token_expiredRefresh token no longer validRe-login the account
All accounts unhealthyEntire pool staleRun codex auth doctor --fix, then add a fresh account

​
Per-Project Accounts

By default (perProjectAccounts: true), accounts are stored per-project:
  • Global accounts: ~/.codex/multi-auth/openai-codex-accounts.json
  • Project accounts: ~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json

​
Worktree Support

Linked Git worktrees share accounts via resolveProjectStorageIdentityRoot:
  1. Plugin detects .git file in worktree
  2. Reads gitdir pointer to resolve the main repository
  3. Uses the main repository’s project key for account storage
  4. Legacy worktree-keyed accounts are auto-migrated on first load
Legacy worktree-specific account files are retained on migration only if the canonical write fails (to prevent data loss).

​
Removing Accounts

To remove an account from the pool:
1

Identify the account index

codex auth list
2

Remove the account

codex auth remove <index>
3

Confirm removal

codex auth list
Verify the account no longer appears.

​
Email Deduplication

Account email addresses are deduplicated using normalizeEmailKey() (trim + lowercase):

​
Monitoring and Reporting

Generate comprehensive account reports: 
codex auth report --live --json
Outputs:
  • Account pool snapshot
  • Live quota status for all accounts
  • Health scores and cooldown timers
  • Flagged accounts requiring attention
  • Configuration effective values
Include this output when filing issue reports for faster troubleshooting.

Build docs developers (and LLMs) love

Get started for freeTalk to us