Single source of truth for all Codex SDK default configuration values.
Every tunable constant lives here as a zero-arity function. Consumers call
these functions instead of defining their own module attributes or inline
magic numbers. A handful of values support runtime override via
Application.get_env/3 — these are noted in the function docs.
Quick example
# In config/runtime.exs
config :codex_sdk,
rate_limit_default_delay_ms: 120_000,
attachment_ttl_ms: 3_600_000
# In your code — always resolved at call time
Codex.Config.Defaults.rate_limit_default_delay_ms()
#=> 120_000See the Configuration Defaults guide for the full table of tunables.
Summary
Functions
App-server initialization/ready timeout (default: 10,000ms).
App-server JSON-RPC request timeout (default: 30,000ms).
Approval callback timeout (default: 30,000ms).
Interval between attachment cleanup sweeps (default: 60,000ms — 1 minute).
Time-to-live for file attachments (default: 86,400,000ms — 24 hours).
Base delay for exponential backoff (default: 100ms).
Maximum exponent for exponential backoff (default: 20).
Maximum backoff delay for exponential backoff (default: 5,000ms).
Client name sent during MCP initialization.
Client version sent during MCP/app-server initialization.
Default model for API auth contexts.
Default model for ChatGPT auth contexts.
Default transport for thread options.
Overall exec process timeout in milliseconds (default: 3,600,000 — 1 hour).
Default maximum results for file search tool (default: 100).
G.711 bytes per sample (default: 1).
G.711 audio sample rate in Hz (default: 8,000).
JSON-RPC version.
Default maximum agent turns for RunConfig (default: 10).
MCP tools/call timeout (default: 60,000ms).
Default number of retries for MCP tool calls (default: 3).
MCP initialize handshake timeout (default: 10,000ms).
MCP tools/list and resources/list timeout (default: 30,000ms).
Maximum length for qualified MCP tool names.
MCP notification send timeout (default: 10,000ms).
MCP protocol version string.
Timeout for app-server MCP server requests like list/reload (default: 30,000ms).
Delimiter for qualified MCP tool names.
Default localhost callback port for browser OAuth login (default: 1455).
Overall timeout for browser login callback completion (default: 120,000ms).
Maximum device code polling interval (default: 10,000ms).
Overall timeout for device code login completion (default: 900,000ms).
HTTP timeout for OAuth token requests (default: 10,000ms).
OAuth token refresh skew — refresh this many ms before expiry (default: 30,000ms).
WSL grace window before browser flow falls back to device flow (default: 5,000ms).
Default OpenAI API base URL.
Default OpenAI Realtime WebSocket URL.
PCM16 bytes per sample (default: 2).
PCM16 audio sample rate in Hz (default: 24,000).
Environment variable keys preserved when running with a cleared environment.
Markers used to find project root (default: [".git"]).
Default delay when rate-limited without an explicit Retry-After header.
Maximum delay for rate-limit backoff.
Multiplier for exponential rate-limit backoff.
Cache TTL for remote model list in seconds (default: 300 — 5 min).
HTTP timeout for remote model list fetches (default: 10,000ms).
Base delay for Codex.Retry backoff (default: 200ms).
Default maximum retry attempts for Codex.Retry (default: 4).
Maximum delay cap for Codex.Retry backoff (default: 10,000ms).
Session apply patch timeout (default: 60,000ms).
Default sessions storage directory.
Maximum shell command output before truncation (default: 10,000 bytes).
Shell command execution timeout (default: 60,000ms).
Default pop timeout for StreamQueue and RunResultStreaming (default: 5,000ms).
Default STT turn detection configuration.
Default STT model name.
System-level config file path (default: /etc/codex/config.toml).
Default originator tag for telemetry metadata.
OpenTelemetry handler ID.
Default OpenTelemetry processor name.
GenServer call timeout for transport operations (default: 5,000ms).
Grace period for transport close before escalation (default: 2,000ms).
Delay before finalizing exit to drain remaining output (default: 25ms).
Timeout for force-close operations (default: 500ms).
Timeout for headless transport without subscribers (default: 5,000ms).
Grace period for transport kill before demonitor (default: 250ms).
Maximum stdout buffer size in bytes (default: 1,048,576 — 1 MiB).
Maximum stdout lines drained per batch (default: 200).
Maximum stderr buffer size in bytes (default: 262,144 — 256 KiB).
Grace period for transport shutdown before kill (default: 250ms).
Default TTS audio buffer size in bytes (default: 120).
Default TTS instructions for partial-sentence streaming.
Default TTS voice.
Default TTS model name.
TTS stream receive timeout (default: 30,000ms).
Default voice input sample rate in Hz (default: 24,000).
Default maximum results for web search tool (default: 10).
Functions
@spec app_server_init_timeout_ms() :: pos_integer()
App-server initialization/ready timeout (default: 10,000ms).
@spec app_server_request_timeout_ms() :: pos_integer()
App-server JSON-RPC request timeout (default: 30,000ms).
@spec approval_timeout_ms() :: pos_integer()
Approval callback timeout (default: 30,000ms).
@spec attachment_cleanup_interval_ms() :: pos_integer()
Interval between attachment cleanup sweeps (default: 60,000ms — 1 minute).
Overridable at runtime:
config :codex_sdk, attachment_cleanup_interval_ms: 120_000@spec attachment_ttl_ms() :: pos_integer()
Time-to-live for file attachments (default: 86,400,000ms — 24 hours).
Overridable at runtime:
config :codex_sdk, attachment_ttl_ms: 3_600_000@spec backoff_base_delay_ms() :: pos_integer()
Base delay for exponential backoff (default: 100ms).
@spec backoff_max_exponent() :: pos_integer()
Maximum exponent for exponential backoff (default: 20).
@spec backoff_max_ms() :: pos_integer()
Maximum backoff delay for exponential backoff (default: 5,000ms).
@spec client_name() :: String.t()
Client name sent during MCP initialization.
@spec client_version() :: String.t()
Client version sent during MCP/app-server initialization.
@spec default_api_model() :: String.t()
Default model for API auth contexts.
@spec default_chatgpt_model() :: String.t()
Default model for ChatGPT auth contexts.
@spec default_transport() :: :exec | {:app_server, pid()}
Default transport for thread options.
Overridable at runtime:
config :codex_sdk, default_transport: :exec@spec exec_timeout_ms() :: pos_integer()
Overall exec process timeout in milliseconds (default: 3,600,000 — 1 hour).
@spec file_search_max_results() :: pos_integer()
Default maximum results for file search tool (default: 100).
@spec g711_bytes_per_sample() :: pos_integer()
G.711 bytes per sample (default: 1).
@spec g711_sample_rate() :: pos_integer()
G.711 audio sample rate in Hz (default: 8,000).
@spec jsonrpc_version() :: String.t()
JSON-RPC version.
@spec max_agent_turns() :: pos_integer()
Default maximum agent turns for RunConfig (default: 10).
@spec mcp_call_timeout_ms() :: pos_integer()
MCP tools/call timeout (default: 60,000ms).
@spec mcp_default_retries() :: non_neg_integer()
Default number of retries for MCP tool calls (default: 3).
@spec mcp_init_timeout_ms() :: pos_integer()
MCP initialize handshake timeout (default: 10,000ms).
@spec mcp_list_timeout_ms() :: pos_integer()
MCP tools/list and resources/list timeout (default: 30,000ms).
@spec mcp_max_tool_name_length() :: pos_integer()
Maximum length for qualified MCP tool names.
@spec mcp_notification_timeout_ms() :: pos_integer()
MCP notification send timeout (default: 10,000ms).
@spec mcp_protocol_version() :: String.t()
MCP protocol version string.
@spec mcp_server_request_timeout_ms() :: pos_integer()
Timeout for app-server MCP server requests like list/reload (default: 30,000ms).
@spec mcp_tool_name_delimiter() :: String.t()
Delimiter for qualified MCP tool names.
@spec oauth_browser_callback_port() :: non_neg_integer()
Default localhost callback port for browser OAuth login (default: 1455).
Overridable at runtime:
config :codex_sdk, oauth_browser_callback_port: 1455@spec oauth_browser_callback_timeout_ms() :: pos_integer()
Overall timeout for browser login callback completion (default: 120,000ms).
@spec oauth_device_code_max_poll_interval_ms() :: pos_integer()
Maximum device code polling interval (default: 10,000ms).
@spec oauth_device_code_timeout_ms() :: pos_integer()
Overall timeout for device code login completion (default: 900,000ms).
@spec oauth_http_timeout_ms() :: pos_integer()
HTTP timeout for OAuth token requests (default: 10,000ms).
@spec oauth_refresh_skew_ms() :: pos_integer()
OAuth token refresh skew — refresh this many ms before expiry (default: 30,000ms).
@spec oauth_wsl_device_fallback_grace_ms() :: pos_integer()
WSL grace window before browser flow falls back to device flow (default: 5,000ms).
@spec openai_api_base_url() :: String.t()
Default OpenAI API base URL.
@spec openai_realtime_ws_url() :: String.t()
Default OpenAI Realtime WebSocket URL.
@spec pcm16_bytes_per_sample() :: pos_integer()
PCM16 bytes per sample (default: 2).
@spec pcm16_sample_rate() :: pos_integer()
PCM16 audio sample rate in Hz (default: 24,000).
@spec preserved_env_keys() :: [String.t()]
Environment variable keys preserved when running with a cleared environment.
@spec project_root_markers() :: [String.t()]
Markers used to find project root (default: [".git"]).
@spec rate_limit_default_delay_ms() :: pos_integer()
Default delay when rate-limited without an explicit Retry-After header.
Overridable at runtime:
config :codex_sdk, rate_limit_default_delay_ms: 120_000@spec rate_limit_max_delay_ms() :: pos_integer()
Maximum delay for rate-limit backoff.
Overridable at runtime:
config :codex_sdk, rate_limit_max_delay_ms: 600_000@spec rate_limit_multiplier() :: float()
Multiplier for exponential rate-limit backoff.
Overridable at runtime:
config :codex_sdk, rate_limit_multiplier: 3.0@spec remote_models_cache_ttl_seconds() :: pos_integer()
Cache TTL for remote model list in seconds (default: 300 — 5 min).
@spec remote_models_http_timeout_ms() :: pos_integer()
HTTP timeout for remote model list fetches (default: 10,000ms).
@spec retry_base_delay_ms() :: pos_integer()
Base delay for Codex.Retry backoff (default: 200ms).
@spec retry_max_attempts() :: pos_integer()
Default maximum retry attempts for Codex.Retry (default: 4).
@spec retry_max_delay_ms() :: pos_integer()
Maximum delay cap for Codex.Retry backoff (default: 10,000ms).
@spec sessions_apply_timeout_ms() :: pos_integer()
Session apply patch timeout (default: 60,000ms).
@spec sessions_dir() :: String.t()
Default sessions storage directory.
@spec shell_max_output_bytes() :: pos_integer()
Maximum shell command output before truncation (default: 10,000 bytes).
@spec shell_timeout_ms() :: pos_integer()
Shell command execution timeout (default: 60,000ms).
@spec stream_queue_pop_timeout_ms() :: pos_integer()
Default pop timeout for StreamQueue and RunResultStreaming (default: 5,000ms).
@spec stt_default_turn_detection() :: map()
Default STT turn detection configuration.
@spec stt_model() :: String.t()
Default STT model name.
@spec system_config_path() :: String.t()
System-level config file path (default: /etc/codex/config.toml).
@spec telemetry_default_originator() :: atom()
Default originator tag for telemetry metadata.
@spec telemetry_otel_handler_id() :: String.t()
OpenTelemetry handler ID.
@spec telemetry_processor_name() :: atom()
Default OpenTelemetry processor name.
@spec transport_call_timeout_ms() :: pos_integer()
GenServer call timeout for transport operations (default: 5,000ms).
@spec transport_close_grace_ms() :: pos_integer()
Grace period for transport close before escalation (default: 2,000ms).
@spec transport_finalize_delay_ms() :: pos_integer()
Delay before finalizing exit to drain remaining output (default: 25ms).
@spec transport_force_close_timeout_ms() :: pos_integer()
Timeout for force-close operations (default: 500ms).
@spec transport_headless_timeout_ms() :: pos_integer()
Timeout for headless transport without subscribers (default: 5,000ms).
@spec transport_kill_grace_ms() :: pos_integer()
Grace period for transport kill before demonitor (default: 250ms).
@spec transport_max_buffer_size() :: pos_integer()
Maximum stdout buffer size in bytes (default: 1,048,576 — 1 MiB).
@spec transport_max_lines_per_batch() :: pos_integer()
Maximum stdout lines drained per batch (default: 200).
@spec transport_max_stderr_buffer_size() :: pos_integer()
Maximum stderr buffer size in bytes (default: 262,144 — 256 KiB).
@spec transport_shutdown_grace_ms() :: pos_integer()
Grace period for transport shutdown before kill (default: 250ms).
@spec tts_buffer_size() :: pos_integer()
Default TTS audio buffer size in bytes (default: 120).
@spec tts_default_instructions() :: String.t()
Default TTS instructions for partial-sentence streaming.
@spec tts_default_voice() :: atom()
Default TTS voice.
@spec tts_model() :: String.t()
Default TTS model name.
@spec tts_stream_timeout_ms() :: pos_integer()
TTS stream receive timeout (default: 30,000ms).
@spec voice_default_sample_rate() :: pos_integer()
Default voice input sample rate in Hz (default: 24,000).
@spec web_search_max_results() :: pos_integer()
Default maximum results for web search tool (default: 10).