Skip to main content

​
Overview

The settings.json file is the unified configuration file for Codex Multi-Auth. It contains all plugin configuration and dashboard display settings in a single JSON file. Default Location: ~/.codex/multi-auth/settings.json When CODEX_MULTI_AUTH_DIR is set, this root moves accordingly.

​
File Structure

The settings file contains two top-level sections: 
{
  "version": 1,
  "pluginConfig": { /* ... */ },
  "dashboardDisplaySettings": { /* ... */ }
}

​
Plugin Configuration

The pluginConfig section contains all backend behavior settings.

​
Codex Mode

​
codexMode
boolean
default:"true"
Enable CODEX_MODE for better Codex CLI parity. When enabled, uses bridge prompts instead of tool remapping.
​
codexTuiV2
boolean
default:"true"
Enable the v2 terminal user interface with enhanced features.
​
codexTuiColorProfile
string
default:"truecolor"
TUI color profile mode. Options: truecolor, ansi16, ansi256
​
codexTuiGlyphMode
string
default:"ascii"
TUI glyph rendering mode. Options: ascii, unicode, auto

​
Session Management

​
fastSession
boolean
default:"false"
Enable fast session optimization for reduced latency.
​
fastSessionStrategy
string
default:"hybrid"
Fast session selection strategy. Options: hybrid, always
​
fastSessionMaxInputItems
number
default:"30"
Maximum number of input items for fast session mode. Minimum: 8
​
sessionRecovery
boolean
default:"true"
Enable conversation state persistence and recovery.
​
autoResume
boolean
default:"true"
Automatically resume interrupted sessions.
​
sessionAffinity
boolean
default:"true"
Enable session-to-account affinity to maintain conversation context.
​
sessionAffinityTtlMs
number
default:"1200000"
Session affinity time-to-live in milliseconds (20 minutes). Minimum: 1000
​
sessionAffinityMaxEntries
number
default:"512"
Maximum number of session affinity entries to cache. Minimum: 8

​
Account Management

​
perProjectAccounts
boolean
default:"true"
Enable per-project account storage and isolation.
​
liveAccountSync
boolean
default:"true"
Enable real-time account synchronization across processes.
​
liveAccountSyncDebounceMs
number
default:"250"
Debounce interval for live account sync in milliseconds. Minimum: 50
​
liveAccountSyncPollMs
number
default:"2000"
Polling interval for live account sync in milliseconds. Minimum: 500

​
Token Refresh

​
tokenRefreshSkewMs
number
default:"60000"
Token refresh skew window in milliseconds (1 minute). Minimum: 0
​
proactiveRefreshGuardian
boolean
default:"true"
Enable proactive token refresh to prevent expiry during active sessions.
​
proactiveRefreshIntervalMs
number
default:"60000"
Proactive refresh check interval in milliseconds (1 minute). Minimum: 5000
​
proactiveRefreshBufferMs
number
default:"300000"
Buffer time before expiry to trigger proactive refresh in milliseconds (5 minutes). Minimum: 30000

​
Retry and Error Handling

​
retryAllAccountsRateLimited
boolean
default:"true"
Retry all accounts when rate limited instead of failing immediately.
​
retryAllAccountsMaxWaitMs
number
default:"0"
Maximum wait time for retry-all-accounts in milliseconds. 0 = no limit. Minimum: 0
​
retryAllAccountsMaxRetries
number
default:"Infinity"
Maximum number of retry attempts when all accounts are rate limited. Minimum: 0
​
emptyResponseMaxRetries
number
default:"2"
Maximum retry attempts for empty responses. Minimum: 0
​
emptyResponseRetryDelayMs
number
default:"1000"
Delay between empty response retries in milliseconds. Minimum: 0
​
networkErrorCooldownMs
number
default:"6000"
Cooldown period after network errors in milliseconds. Minimum: 0
​
serverErrorCooldownMs
number
default:"4000"
Cooldown period after server (5xx) errors in milliseconds. Minimum: 0

​
Model Fallback

​
unsupportedCodexPolicy
string
default:"strict"
Policy for handling unsupported Codex models. Options: strict, fallback
  • strict: Fail immediately when model is not supported
  • fallback: Attempt to use fallback models from the fallback chain
​
fallbackOnUnsupportedCodexModel
boolean
default:"false"
Legacy field. Use unsupportedCodexPolicy: "fallback" instead.
​
fallbackToGpt52OnUnsupportedGpt53
boolean
default:"true"
Automatically fallback to GPT-5.2 when GPT-5.3 is not supported.
​
unsupportedCodexFallbackChain
object
default:"{}"
Custom model fallback chains. Maps model names to arrays of fallback models.Example:
{
  "gpt-5.3": ["gpt-5.2", "gpt-4o"],
  "claude-4.5": ["claude-3.5"]
}

​
Timeouts

​
fetchTimeoutMs
number
default:"60000"
HTTP fetch timeout for requests in milliseconds (1 minute). Minimum: 1000
​
streamStallTimeoutMs
number
default:"45000"
Stream stall detection timeout in milliseconds (45 seconds). Minimum: 1000
​
rateLimitToastDebounceMs
number
default:"60000"
Debounce interval for rate limit toast notifications in milliseconds (1 minute). Minimum: 0
​
toastDurationMs
number
default:"5000"
Toast notification display duration in milliseconds (5 seconds). Minimum: 1000

​
Preemptive Quota

​
preemptiveQuotaEnabled
boolean
default:"true"
Enable preemptive quota checking to avoid hitting limits.
​
preemptiveQuotaRemainingPercent5h
number
default:"5"
Remaining percentage threshold for 5-hour quota window. Range: 0-100
​
preemptiveQuotaRemainingPercent7d
number
default:"5"
Remaining percentage threshold for 7-day quota window. Range: 0-100
​
preemptiveQuotaMaxDeferralMs
number
default:"7200000"
Maximum deferral time for quota-limited accounts in milliseconds (2 hours). Minimum: 1000

​
Advanced Features

​
parallelProbing
boolean
default:"false"
Enable parallel account health probing for faster selection.
​
parallelProbingMaxConcurrency
number
default:"2"
Maximum concurrent probes when parallel probing is enabled. Minimum: 1
​
pidOffsetEnabled
boolean
default:"false"
Enable process ID offset for multi-process environments.
​
storageBackupEnabled
boolean
default:"true"
Enable automatic storage backups (.bak files).

​
Dashboard Display Settings

The dashboardDisplaySettings section controls the interactive CLI dashboard appearance and behavior.

​
Account List View

Controls how accounts are displayed in the dashboard:
  • Status badge visibility
  • Current account badge visibility
  • Last-used timestamp display
  • Quota/cooldown information
  • Fetch status indicators
  • Current row highlighting
  • Smart sort enable and mode
  • Compact vs expanded layout

​
Summary Fields

Controls which detail fields are shown and their order:
  • last-used - Last usage timestamp
  • limits - Rate limit and quota information
  • status - Account health status

​
Behavior

Controls dashboard interaction behavior:
  • Auto-return delay after actions
  • Pause-on-key behavior
  • Auto-fetch limits configuration
  • Fetch TTL (time-to-live)

​
Theme

Controls visual styling:
  • Theme preset selection
  • Accent color customization
  • Focus style preferences

​
Quick Reference Table

SettingTypeDefaultDescription
codexModebooleantrueEnable CODEX_MODE
perProjectAccountsbooleantruePer-project account isolation
liveAccountSyncbooleantrueReal-time account sync
sessionAffinitybooleantrueSession-to-account affinity
sessionRecoverybooleantrueConversation state persistence
proactiveRefreshGuardianbooleantrueProactive token refresh
preemptiveQuotaEnabledbooleantruePreemptive quota checking
retryAllAccountsRateLimitedbooleantrueRetry all when rate limited
storageBackupEnabledbooleantrueAutomatic backups
fetchTimeoutMsnumber60000Request timeout (ms)
streamStallTimeoutMsnumber45000Stream stall timeout (ms)
tokenRefreshSkewMsnumber60000Token refresh window (ms)
sessionAffinityTtlMsnumber1200000Session affinity TTL (ms)

​
Editing Settings

​
Via Dashboard

Access settings through the CLI: 
codex auth login
# Navigate to Settings menu
Press Q to cancel without saving.

​
Manual Editing

Edit ~/.codex/multi-auth/settings.json directly: 
{
  "version": 1,
  "pluginConfig": {
    "codexMode": true,
    "perProjectAccounts": true,
    "sessionAffinity": true
  },
  "dashboardDisplaySettings": {
    "theme": "default"
  }
}

​
Validation

After making changes, verify settings: 
codex auth status
codex auth check

Build docs developers (and LLMs) love

Get started for freeTalk to us