Configuration Defaults

Copy Markdown View Source

The Codex.Config.Defaults module is the single source of truth for every tunable constant in the Codex SDK. Instead of scattering magic numbers across modules, all defaults live in one place and are referenced via zero-arity function calls.

How It Works

Every default is a public, zero-arity function with a @doc and @spec:

Codex.Config.Defaults.exec_timeout_ms()
#=> 3_600_000

Codex.Config.Defaults.openai_api_base_url()
#=> "https://api.openai.com/v1"

Consuming modules reference these functions either directly or through module attributes:

# Direct call
timeout = Defaults.mcp_call_timeout_ms()

# Module attribute (resolved at compile time)
@default_timeout_ms Defaults.mcp_call_timeout_ms()

Runtime Overrides

A subset of defaults support runtime override via Application.get_env/3. These are clearly documented on each function. Override them in config/runtime.exs:

config :codex_sdk,
  rate_limit_default_delay_ms: 120_000,
  rate_limit_max_delay_ms: 600_000,
  rate_limit_multiplier: 3.0,
  attachment_ttl_ms: 3_600_000,
  attachment_cleanup_interval_ms: 120_000,
  default_transport: :exec

Layered Config Notes

Not every runtime behavior is a Codex.Config.Defaults constant. Two important upstream-parity settings live in layered config.toml files instead:

  • openai_base_url overrides the built-in openai provider base URL and takes precedence over OPENAI_BASE_URL
  • [model_providers.<id>] entries extend the built-in provider set, but reserved IDs (openai, ollama, lmstudio) are rejected

Custom trust roots are also environment-driven rather than Defaults-driven: CODEX_CA_CERTIFICATE is preferred over SSL_CERT_FILE, with blank values treated as unset.

OAuth issuer resolution is also separate from openai_base_url: overriding the OpenAI API base URL does not change the ChatGPT OAuth authority. Use Codex.OAuth auth_issuer: options (or layered auth_issuer) for that.

Defaults Reference

Transport Timeouts

FunctionDefaultDescription
exec_timeout_ms/03,600,000Overall exec process timeout (1 hour)
transport_close_grace_ms/02,000Grace period before escalating close
transport_shutdown_grace_ms/0250Grace period before kill
transport_kill_grace_ms/0250Grace period before demonitor
transport_max_buffer_size/01,048,576Max stdout buffer (1 MiB)
transport_max_stderr_buffer_size/0262,144Max stderr buffer (256 KiB)
transport_call_timeout_ms/05,000GenServer call timeout
transport_force_close_timeout_ms/0500Force-close timeout
transport_headless_timeout_ms/05,000Headless transport timeout
transport_finalize_delay_ms/025Finalize exit drain delay
transport_max_lines_per_batch/0200Max stdout lines per drain batch

MCP Timeouts

FunctionDefaultDescription
mcp_init_timeout_ms/010,000Initialize handshake timeout
mcp_list_timeout_ms/030,000tools/list, resources/list timeout
mcp_call_timeout_ms/060,000tools/call timeout
mcp_default_retries/03Default retry count
mcp_notification_timeout_ms/010,000Notification send timeout
mcp_server_request_timeout_ms/030,000App-server MCP request timeout

App-Server Timeouts

FunctionDefaultDescription
app_server_init_timeout_ms/010,000Connection init timeout
app_server_request_timeout_ms/030,000JSON-RPC request timeout
approval_timeout_ms/030,000Approval callback timeout

Tool Defaults

FunctionDefaultDescription
shell_timeout_ms/060,000Shell command timeout
shell_max_output_bytes/010,000Max shell output before truncation
file_search_max_results/0100File search max results
web_search_max_results/010Web search max results

OAuth / HTTP Timeouts

FunctionDefaultDescription
oauth_http_timeout_ms/010,000OAuth token request timeout
oauth_refresh_skew_ms/030,000Refresh before expiry threshold
oauth_browser_callback_timeout_ms/0120,000Browser callback wait timeout
oauth_device_code_timeout_ms/0900,000Device-code login timeout
oauth_device_code_max_poll_interval_ms/010,000Max device-code backoff interval
oauth_wsl_device_fallback_grace_ms/05,000WSL browser-to-device fallback grace period
remote_models_http_timeout_ms/010,000Model list HTTP timeout
sessions_apply_timeout_ms/060,000Session apply timeout

Retry / Backoff

FunctionDefaultRuntime Key
backoff_base_delay_ms/0100—
backoff_max_ms/05,000—
backoff_max_exponent/020—
retry_max_attempts/04—
retry_base_delay_ms/0200—
retry_max_delay_ms/010,000—
rate_limit_default_delay_ms/060,000:rate_limit_default_delay_ms
rate_limit_max_delay_ms/0300,000:rate_limit_max_delay_ms
rate_limit_multiplier/02.0:rate_limit_multiplier

URLs

FunctionDefault
openai_api_base_url/0"https://api.openai.com/v1"
openai_realtime_ws_url/0"wss://api.openai.com/v1/realtime"
sessions_dir/0~/.codex/sessions

Model Defaults

FunctionDefault
default_api_model/0"gpt-5.4"
default_chatgpt_model/0"gpt-5.4"
remote_models_cache_ttl_seconds/0300

Protocol Constants

FunctionDefault
mcp_protocol_version/0"2025-06-18"
jsonrpc_version/0"2.0"
mcp_tool_name_delimiter/0"__"
mcp_max_tool_name_length/064

Files / Attachments

FunctionDefaultRuntime Key
attachment_ttl_ms/086,400,000:attachment_ttl_ms
attachment_cleanup_interval_ms/060,000:attachment_cleanup_interval_ms

Audio / Voice

FunctionDefault
pcm16_sample_rate/024,000
pcm16_bytes_per_sample/02
g711_sample_rate/08,000
g711_bytes_per_sample/01
voice_default_sample_rate/024,000
tts_buffer_size/0120
tts_stream_timeout_ms/030,000
stt_model/0"gpt-4o-transcribe"
tts_model/0"gpt-4o-mini-tts"
tts_default_voice/0:ash
stt_default_turn_detection/0%{"type" => "semantic_vad"}
tts_default_instructions/0(partial-sentence streaming prompt)

Telemetry

FunctionDefault
telemetry_otel_handler_id/0"codex-otel-tracing"
telemetry_default_originator/0:sdk
telemetry_processor_name/0:codex_sdk_processor

Client Identity

FunctionDefault
client_name/0"codex-elixir"
client_version/0Application version or "0.0.0"

Other

FunctionDefaultRuntime Key
preserved_env_keys/010 standard env keys—
stream_queue_pop_timeout_ms/05,000—
max_agent_turns/010—
system_config_path/0/etc/codex/config.toml—
project_root_markers/0[".git"]—
default_transport/0:exec:default_transport