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
default_transport: :exec is the historical compatibility selector for the
default subprocess lane backed by cli_subprocess_core. It does not imply
direct ownership of the Erlang :exec worker.
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.
All env-backed layered config is standalone compatibility behavior. Governed
Codex execution requires explicit authority refs and materialized env for one
bounded effect; normal layered config, shell env, and saved CLI auth files do
not satisfy governed authority.
An explicit layered personality = "none" is meaningful upstream. When the
selected model supports personality instructions, Codex removes the catalog's
# Personality section instead of treating none as a literal personality;
an explicit base_instructions override remains untouched.
Defaults Reference
Transport Timeouts
| Function | Default | Description |
|---|
exec_timeout_ms/0 | 3,600,000 | Overall exec process timeout (1 hour) |
transport_close_grace_ms/0 | 2,000 | Grace period before escalating close |
transport_shutdown_grace_ms/0 | 250 | Grace period before kill |
transport_kill_grace_ms/0 | 250 | Grace period before demonitor |
transport_max_buffer_size/0 | 1,048,576 | Max stdout buffer (1 MiB) |
transport_max_stderr_buffer_size/0 | 262,144 | Max stderr buffer (256 KiB) |
transport_call_timeout_ms/0 | 5,000 | GenServer call timeout |
transport_force_close_timeout_ms/0 | 500 | Force-close timeout |
transport_headless_timeout_ms/0 | 5,000 | Headless transport timeout |
transport_finalize_delay_ms/0 | 25 | Finalize exit drain delay |
transport_max_lines_per_batch/0 | 200 | Max stdout lines per drain batch |
MCP Timeouts
| Function | Default | Description |
|---|
mcp_init_timeout_ms/0 | 10,000 | Initialize handshake timeout |
mcp_list_timeout_ms/0 | 30,000 | tools/list, resources/list timeout |
mcp_call_timeout_ms/0 | 60,000 | tools/call timeout |
mcp_default_retries/0 | 3 | Default retry count |
mcp_notification_timeout_ms/0 | 10,000 | Notification send timeout |
mcp_server_request_timeout_ms/0 | 30,000 | App-server MCP request timeout |
App-Server Timeouts
| Function | Default | Description |
|---|
app_server_init_timeout_ms/0 | 10,000 | Connection init timeout |
app_server_request_timeout_ms/0 | 30,000 | JSON-RPC request timeout |
approval_timeout_ms/0 | 30,000 | Approval callback timeout |
| Function | Default | Description |
|---|
shell_timeout_ms/0 | 60,000 | Shell command timeout |
shell_max_output_bytes/0 | 10,000 | Max shell output before truncation |
file_search_max_results/0 | 100 | File search max results |
web_search_max_results/0 | 10 | Web search max results |
OAuth / HTTP Timeouts
| Function | Default | Description |
|---|
oauth_http_timeout_ms/0 | 10,000 | OAuth token request timeout |
oauth_refresh_skew_ms/0 | 30,000 | Refresh before expiry threshold |
oauth_browser_callback_timeout_ms/0 | 120,000 | Browser callback wait timeout |
oauth_device_code_timeout_ms/0 | 900,000 | Device-code login timeout |
oauth_device_code_max_poll_interval_ms/0 | 10,000 | Max device-code backoff interval |
oauth_wsl_device_fallback_grace_ms/0 | 5,000 | WSL browser-to-device fallback grace period |
remote_models_http_timeout_ms/0 | 10,000 | Model list HTTP timeout |
sessions_apply_timeout_ms/0 | 60,000 | Session apply timeout |
Retry / Backoff
| Function | Default | Runtime Key |
|---|
backoff_base_delay_ms/0 | 100 | — |
backoff_max_ms/0 | 5,000 | — |
backoff_max_exponent/0 | 20 | — |
retry_max_attempts/0 | 4 | — |
retry_base_delay_ms/0 | 200 | — |
retry_max_delay_ms/0 | 10,000 | — |
rate_limit_default_delay_ms/0 | 60,000 | :rate_limit_default_delay_ms |
rate_limit_max_delay_ms/0 | 300,000 | :rate_limit_max_delay_ms |
rate_limit_multiplier/0 | 2.0 | :rate_limit_multiplier |
URLs
| Function | Default |
|---|
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_HOME/sessions (default ~/.codex/sessions) |
Model Defaults
| Function | Default |
|---|
default_api_model/0 | "gpt-5.6-sol" |
default_chatgpt_model/0 | "gpt-5.6-sol" |
remote_models_cache_ttl_seconds/0 | 300 |
Protocol Constants
| Function | Default |
|---|
mcp_protocol_version/0 | "2025-06-18" |
jsonrpc_version/0 | "2.0" |
mcp_tool_name_delimiter/0 | "__" |
mcp_max_tool_name_length/0 | 64 |
Files / Attachments
| Function | Default | Runtime Key |
|---|
attachment_ttl_ms/0 | 86,400,000 | :attachment_ttl_ms |
attachment_cleanup_interval_ms/0 | 60,000 | :attachment_cleanup_interval_ms |
Audio / Voice
| Function | Default |
|---|
pcm16_sample_rate/0 | 24,000 |
pcm16_bytes_per_sample/0 | 2 |
g711_sample_rate/0 | 8,000 |
g711_bytes_per_sample/0 | 1 |
voice_default_sample_rate/0 | 24,000 |
tts_buffer_size/0 | 120 |
tts_stream_timeout_ms/0 | 30,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
| Function | Default |
|---|
telemetry_otel_handler_id/0 | "codex-otel-tracing" |
telemetry_default_originator/0 | :sdk |
telemetry_processor_name/0 | :codex_sdk_processor |
Client Identity
| Function | Default |
|---|
client_name/0 | "codex-elixir" |
client_version/0 | Application version or "0.0.0" |
Other
| Function | Default | Runtime Key |
|---|
preserved_env_keys/0 | 10 standard env keys | — |
stream_queue_pop_timeout_ms/0 | 5,000 | — |
max_agent_turns/0 | 10 | — |
system_config_path/0 | /etc/codex/config.toml | — |
project_root_markers/0 | [".git"] | — |
default_transport/0 | :exec (compatibility selector) | :default_transport |