Environment Variables

Overview

Codex Multi-Auth supports environment variable overrides for most configuration settings. Environment variables take precedence over settings.json values.

Directory and Path Configuration

CODEX_HOME

string

Override the Codex home directory.Default: ~/.codexExample: export CODEX_HOME="/custom/path"

CODEX_MULTI_AUTH_DIR

string

Override the multi-auth storage directory.Default: ~/.codex/multi-authExample: export CODEX_MULTI_AUTH_DIR="/custom/multi-auth"

CODEX_MULTI_AUTH_CONFIG_PATH

string

Override the config file location (legacy).Note: This is for legacy config.json files. Modern installations use settings.json.

CODEX_CLI_ACCOUNTS_PATH

string

Override the Codex CLI accounts file path.Default: ~/.codex/accounts.json

CODEX_CLI_AUTH_PATH

string

Override the Codex CLI auth file path.Default: ~/.codex/auth.json

Core Features

CODEX_MODE

boolean

default:"1"

Enable CODEX_MODE for Codex CLI parity.Values: 1 = enabled, 0 = disabledExample: export CODEX_MODE=1

CODEX_TUI_V2

boolean

default:"1"

Enable the v2 terminal user interface.Values: 1 = enabled, 0 = disabled

CODEX_TUI_COLOR_PROFILE

string

default:"truecolor"

TUI color profile mode.Options: truecolor, ansi16, ansi256Example: export CODEX_TUI_COLOR_PROFILE=ansi256

CODEX_TUI_GLYPHS

string

default:"ascii"

TUI glyph rendering mode.Options: ascii, unicode, autoExample: export CODEX_TUI_GLYPHS=unicode

Session Management

CODEX_AUTH_FAST_SESSION

boolean

default:"0"

Enable fast session optimization.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_FAST_SESSION_STRATEGY

string

default:"hybrid"

Fast session strategy.Options: hybrid, always

CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS

number

default:"30"

Maximum input items for fast session.Minimum: 8

CODEX_AUTH_SESSION_RECOVERY

boolean

default:"1"

Enable conversation state persistence.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_AUTO_RESUME

boolean

default:"1"

Automatically resume interrupted sessions.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_SESSION_AFFINITY

boolean

default:"1"

Enable session-to-account affinity.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_SESSION_AFFINITY_TTL_MS

number

default:"1200000"

Session affinity TTL in milliseconds (20 minutes).Minimum: 1000

CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES

number

default:"512"

Maximum session affinity cache entries.Minimum: 8

Account Management

CODEX_AUTH_PER_PROJECT_ACCOUNTS

boolean

default:"1"

Enable per-project account storage.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_LIVE_ACCOUNT_SYNC

boolean

default:"1"

Enable live account synchronization.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS

number

default:"250"

Live sync debounce interval in milliseconds.Minimum: 50

CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS

number

default:"2000"

Live sync polling interval in milliseconds.Minimum: 500

Token Refresh

CODEX_AUTH_TOKEN_REFRESH_SKEW_MS

number

default:"60000"

Token refresh skew window in milliseconds.Minimum: 0

CODEX_AUTH_PROACTIVE_GUARDIAN

boolean

default:"1"

Enable proactive token refresh guardian.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS

number

default:"60000"

Proactive refresh check interval in milliseconds.Minimum: 5000

CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS

number

default:"300000"

Buffer time before expiry to refresh in milliseconds (5 minutes).Minimum: 30000

CODEX_AUTH_REFRESH_LEASE

boolean

Enable refresh lease coordination (advanced).Values: 1 = enabled, 0 = disabled

CODEX_AUTH_REFRESH_LEASE_DIR

string

Directory for refresh lease coordination files.

CODEX_AUTH_REFRESH_LEASE_TTL_MS

number

Refresh lease TTL in milliseconds.

CODEX_AUTH_REFRESH_LEASE_WAIT_MS

number

Maximum wait time for refresh lease in milliseconds.

CODEX_AUTH_REFRESH_LEASE_POLL_MS

number

Refresh lease polling interval in milliseconds.

CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS

number

Refresh result cache TTL in milliseconds.

Retry and Error Handling

CODEX_AUTH_RETRY_ALL_RATE_LIMITED

boolean

default:"1"

Retry all accounts when rate limited.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS

number

default:"0"

Maximum wait time for retry-all in milliseconds (0 = no limit).Minimum: 0

CODEX_AUTH_RETRY_ALL_MAX_RETRIES

number

default:"Infinity"

Maximum retry attempts when all accounts are rate limited.Minimum: 0

CODEX_AUTH_EMPTY_RESPONSE_MAX_RETRIES

number

default:"2"

Maximum retries for empty responses.Minimum: 0

CODEX_AUTH_EMPTY_RESPONSE_RETRY_DELAY_MS

number

default:"1000"

Delay between empty response retries in milliseconds.Minimum: 0

CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS

number

default:"6000"

Cooldown after network errors in milliseconds.Minimum: 0

CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS

number

default:"4000"

Cooldown after server errors in milliseconds.Minimum: 0

Model Fallback

CODEX_AUTH_UNSUPPORTED_MODEL_POLICY

string

default:"strict"

Policy for unsupported models.Options: strict, fallbackExample: export CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback

CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL

boolean

Legacy. Use CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback instead.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_FALLBACK_GPT53_TO_GPT52

boolean

default:"1"

Fallback GPT-5.3 to GPT-5.2 when unsupported.Values: 1 = enabled, 0 = disabled

Timeouts

CODEX_AUTH_FETCH_TIMEOUT_MS

number

default:"60000"

HTTP fetch timeout in milliseconds (1 minute).Minimum: 1000Example: export CODEX_AUTH_FETCH_TIMEOUT_MS=30000

CODEX_AUTH_STREAM_STALL_TIMEOUT_MS

number

default:"45000"

Stream stall detection timeout in milliseconds (45 seconds).Minimum: 1000

CODEX_AUTH_RATE_LIMIT_TOAST_DEBOUNCE_MS

number

default:"60000"

Rate limit toast debounce in milliseconds.Minimum: 0

CODEX_AUTH_TOAST_DURATION_MS

number

default:"5000"

Toast notification duration in milliseconds.Minimum: 1000

Preemptive Quota

CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED

boolean

default:"1"

Enable preemptive quota checking.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT

number

default:"5"

5-hour quota remaining percentage threshold.Range: 0-100

CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT

number

default:"5"

7-day quota remaining percentage threshold.Range: 0-100

CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS

number

default:"7200000"

Maximum quota deferral time in milliseconds (2 hours).Minimum: 1000

Advanced Features

CODEX_AUTH_PARALLEL_PROBING

boolean

default:"0"

Enable parallel account health probing.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY

number

default:"2"

Maximum concurrent health probes.Minimum: 1

CODEX_AUTH_PID_OFFSET_ENABLED

boolean

default:"0"

Enable process ID offset.Values: 1 = enabled, 0 = disabled

CODEX_AUTH_STORAGE_BACKUP_ENABLED

boolean

default:"1"

Enable automatic storage backups.Values: 1 = enabled, 0 = disabled

Sync and Bypass

CODEX_MULTI_AUTH_SYNC_CODEX_CLI

boolean

Sync accounts with official Codex CLI.Values: 1 = enabled, 0 = disabled

CODEX_MULTI_AUTH_REAL_CODEX_BIN

string

Path to real Codex CLI binary for sync.

CODEX_MULTI_AUTH_BYPASS

boolean

Bypass multi-auth and use direct authentication.Values: 1 = enabled, 0 = disabled

Logging and Debugging

CODEX_PLUGIN_LOG_BODIES

boolean

default:"0"

Log full request/response bodies.Values: 1 = enabled, 0 = disabledWarning: Logs may contain sensitive data.

DEBUG_CODEX_PLUGIN

boolean

default:"0"

Enable debug logging.Values: 1 = enabled, 0 = disabled

CODEX_PLUGIN_LOG_LEVEL

string

Set log level.Options: debug, info, warn, error

CODEX_CONSOLE_LOG

boolean

default:"0"

Enable console logging (in addition to file logging).Values: 1 = enabled, 0 = disabled

Prompt Customization

CODEX_PROMPT_SOURCE_URL

string

Override URL for Codex prompt templates.

CODEX_CODEX_PROMPT_URL

string

Legacy. Use CODEX_PROMPT_SOURCE_URL instead.

CODEX_COLLABORATION_MODE

string

Set collaboration mode for multi-user scenarios.

Quick Reference Table

Variable	Default	Type	Description
`CODEX_HOME`	`~/.codex`	string	Codex home directory
`CODEX_MULTI_AUTH_DIR`	`~/.codex/multi-auth`	string	Multi-auth directory
`CODEX_MODE`	`1`	boolean	Enable CODEX_MODE
`CODEX_TUI_V2`	`1`	boolean	Enable TUI v2
`CODEX_AUTH_FETCH_TIMEOUT_MS`	`60000`	number	Request timeout
`CODEX_AUTH_STREAM_STALL_TIMEOUT_MS`	`45000`	number	Stream timeout
`CODEX_AUTH_SESSION_AFFINITY`	`1`	boolean	Session affinity
`CODEX_AUTH_LIVE_ACCOUNT_SYNC`	`1`	boolean	Live sync
`CODEX_AUTH_PROACTIVE_GUARDIAN`	`1`	boolean	Proactive refresh
`CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED`	`1`	boolean	Quota checks

Boolean Value Format

For boolean environment variables:

1 = enabled/true
0 = disabled/false

Any other value is ignored and the default from settings.json or built-in default is used.

Examples

Basic Configuration

# Enable debug logging
export DEBUG_CODEX_PLUGIN=1

# Use custom directory
export CODEX_MULTI_AUTH_DIR="/custom/path"

# Increase timeout
export CODEX_AUTH_FETCH_TIMEOUT_MS=120000

Development Setup

# Enable all debugging
export DEBUG_CODEX_PLUGIN=1
export CODEX_PLUGIN_LOG_BODIES=1
export CODEX_PLUGIN_LOG_LEVEL=debug

# Disable production features
export CODEX_AUTH_PROACTIVE_GUARDIAN=0
export CODEX_AUTH_LIVE_ACCOUNT_SYNC=0

Performance Tuning

# Enable fast mode
export CODEX_AUTH_FAST_SESSION=1
export CODEX_AUTH_FAST_SESSION_STRATEGY=always

# Parallel probing
export CODEX_AUTH_PARALLEL_PROBING=1
export CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY=4

Commands

Configuration

Dashboard

Overview

Directory and Path Configuration

Core Features

Session Management

Account Management

Token Refresh

Retry and Error Handling

Model Fallback

Timeouts

Preemptive Quota

Advanced Features

Sync and Bypass

Logging and Debugging

Prompt Customization

Quick Reference Table

Boolean Value Format

Examples

Basic Configuration

Development Setup

Performance Tuning

Build docs developers (and LLMs) love

Commands

Configuration

Dashboard

​Overview

​Directory and Path Configuration

​Core Features

​Session Management

​Account Management

​Token Refresh

​Retry and Error Handling

​Model Fallback

​Timeouts

​Preemptive Quota

​Advanced Features

​Sync and Bypass

​Logging and Debugging

​Prompt Customization

​Quick Reference Table

​Boolean Value Format

​Examples

​Basic Configuration

​Development Setup

​Performance Tuning

​Related

Build docs developers (and LLMs) love

Overview

Directory and Path Configuration

Core Features

Session Management

Account Management

Token Refresh

Retry and Error Handling

Model Fallback

Timeouts

Preemptive Quota

Advanced Features

Sync and Bypass

Logging and Debugging

Prompt Customization

Quick Reference Table

Boolean Value Format

Examples

Basic Configuration

Development Setup

Performance Tuning

Related