The Configuration System manages all user-facing settings for Codex, including model selection, security policies, tool enablement, and runtime behavior. It implements a hierarchical layer-merging architecture that allows settings to be defined at multiple levels (defaults, user-wide, project-specific, profile-based) with well-defined precedence rules. The system also enforces cloud-based requirements that constrain certain settings when operating in managed environments.
For information about specific feature flags and their stages, see Feature Flags and Stages. For details about security policies (approval and sandbox), see Sandbox and Approval Policies.
Codex merges configuration from multiple sources in a well-defined order, with later layers overriding earlier ones:
Sources: codex-rs/core/src/config/mod.rs26-35 codex-rs/core/src/config/mod.rs519-573
The ConfigLayerStack manages the merging of TOML values from all sources, with the following priority (highest to lowest):
| Priority | Layer | Source | Scope |
|---|---|---|---|
| 6 (highest) | Cloud Requirements | Backend-enforced constraints | Global |
| 5 | CLI Overrides | --set key=value flags | Session |
| 4 | Active Profile | [profiles.<name>] section | Session |
| 3 | Project Config | .codex/config.toml in project root | Project |
| 2 | User Config | ~/.codex/config.toml | Global |
| 1 (lowest) | Built-in Defaults | Hardcoded in ConfigToml::default() | Global |
Sources: codex-rs/core/src/config/mod.rs519-573
Sources: codex-rs/core/src/config/mod.rs519-573
The ConfigToml struct is the direct deserialization target of the merged TOML configuration. It uses serde to deserialize TOML values into typed Rust structures. Relative paths in the TOML are resolved to absolute paths using AbsolutePathBufGuard based on the parent directory of the config file.
Sources: codex-rs/core/src/config/mod.rs654-664
The Config struct (codex-rs/core/src/config/mod.rs161-476) is the runtime configuration used throughout the system. It contains:
| Category | Key Fields | Purpose |
|---|---|---|
| Provenance | config_layer_stack, startup_warnings | Tracks how config was derived and issues found during load |
| Model Settings | model, review_model, model_provider, model_reasoning_effort | Controls which model to use and how |
| Permissions | permissions: Permissions | Approval policy, sandbox policy, network config, shell environment |
| Features | features: Features | Centralized feature flags for gating functionality |
| MCP | mcp_servers: Constrained<HashMap<String, McpServerConfig>> | MCP server definitions and constraints |
| Paths | codex_home, log_dir, cwd, active_project | Filesystem locations |
| Tools | include_apply_patch_tool, tool_output_token_limit | Tool-specific settings |
| TUI | tui_alternate_screen, tui_status_line, tui_theme | Terminal UI preferences |
| History | history: History, ephemeral | Persistence settings |
| Analytics | analytics_enabled, feedback_enabled, otel | Telemetry configuration |
Sources: codex-rs/core/src/config/mod.rs161-476
The Permissions struct (codex-rs/core/src/config/mod.rs133-157) encapsulates all security-related configuration:
Sources: codex-rs/core/src/config/mod.rs133-157
The ConfigBuilder (codex-rs/core/src/config/mod.rs478-574) provides a fluent API for constructing a Config instance:
Sources: codex-rs/core/src/config/mod.rs478-574
Sources: codex-rs/core/src/config/mod.rs577-625
When deserializing ConfigToml from merged TOML values, relative paths are resolved to absolute paths using AbsolutePathBufGuard:
This ensures that relative paths in user config (~/.codex/config.toml) are resolved relative to ~/.codex/, and project config paths are resolved relative to .codex/.
Sources: codex-rs/core/src/config/mod.rs654-664
Profiles allow users to define named configuration bundles that can be activated at runtime. A profile is defined in the [profiles.<name>] section of config.toml.
The ConfigProfile struct (codex-rs/core/src/config/profile.rs19-60) defines the settings that can be overridden in a profile:
model, model_provider)approval_policy, sandbox_mode)model_reasoning_effort, plan_mode_reasoning_effort)features)include_apply_patch_tool, experimental_use_unified_exec_tool)js_repl_node_path, zsh_path)Profiles are activated by:
profile = "name" in the root of config.toml--profile <name> CLI flag (if supported by the interface)When a profile is active, the ConfigLayerStack applies the profile's settings after project config but before CLI overrides.
Sources: codex-rs/core/src/config/profile.rs1-75
The configuration system supports atomic mutations through the ConfigEdit enum (codex-rs/core/src/config/edit.rs22-56):
Sources: codex-rs/core/src/config/edit.rs20-56 codex-rs/core/src/config/edit.rs654-705
The ConfigEditsBuilder (codex-rs/core/src/config/edit.rs720-826) provides a fluent API for batching configuration changes:
All edits in a batch are applied atomically to the TOML document using toml_edit::DocumentMut, which preserves comments and formatting.
Sources: codex-rs/core/src/config/edit.rs720-826
The edit system uses toml_edit::DocumentMut to manipulate configuration without losing formatting:
The ConfigDocument helper (codex-rs/core/src/config/edit.rs267-644) manages profile-aware path traversal and value updates while preserving decor (comments, whitespace).
Sources: codex-rs/core/src/config/edit.rs267-644
The Constrained<T> wrapper (codex-rs/core/src/config/mod.rs100-102) enforces requirements on configuration values:
When a constrained value is set, it is validated against the constraint. If the value violates the constraint, an error is returned or a fallback value is used.
Sources: codex-rs/core/src/config/mod.rs133-157
The CloudRequirementsLoader loads requirements from a backend or local file. Requirements can constrain:
McpServerRequirement)When requirements are applied during config loading, they filter or constrain the effective configuration:
If a user-configured value violates a requirement, a warning is added to Config::startup_warnings and the required value is enforced.
Sources: codex-rs/core/src/config/mod.rs687-760
MCP servers can be disabled by requirements. The filter_mcp_servers_by_requirements() function (codex-rs/core/src/config/mod.rs687-710) checks each configured MCP server against the allowlist:
Sources: codex-rs/core/src/config/mod.rs687-725
MCP servers are configured in the [mcp_servers.<name>] section. Each server has:
| Field | Type | Purpose |
|---|---|---|
transport | McpServerTransportConfig | Stdio or StreamableHttp transport details |
enabled | bool | Whether to initialize this server (default: true) |
required | bool | Whether codex exec should fail if server fails to initialize |
startup_timeout_sec | Option<Duration> | Timeout for server initialization |
tool_timeout_sec | Option<Duration> | Default timeout for tool calls to this server |
enabled_tools | Option<Vec<String>> | Allow-list of tools (if set, only these are registered) |
disabled_tools | Option<Vec<String>> | Deny-list of tools (applied after enabled_tools) |
scopes | Option<Vec<String>> | OAuth scopes to request during login |
Sources: codex-rs/core/src/config/types.rs61-226
The History struct (codex-rs/core/src/config/types.rs322-331) controls conversation persistence:
Sources: codex-rs/core/src/config/types.rs322-341
The Tui struct (codex-rs/core/src/config/types.rs642-691) defines terminal UI preferences:
Sources: codex-rs/core/src/config/types.rs642-691
The OtelConfig struct (codex-rs/core/src/config/types.rs589-608) controls telemetry:
Sources: codex-rs/core/src/config/types.rs568-608
Projects can be marked as "trusted" or "untrusted" in the [projects] table:
The set_project_trust_level() function (codex-rs/core/src/config/mod.rs838-905) ensures this is stored as an explicit table (not inline) for readability.
Sources: codex-rs/core/src/config/mod.rs838-919
The ConfigService manages the lifecycle of configuration in long-running processes. It provides methods for:
Sources: codex-rs/core/src/config/service.rs (referenced but not included in provided files)
The load_global_mcp_servers() function (codex-rs/core/src/config/mod.rs782-815) loads MCP servers without a project context. It also validates that no inline bearer tokens are present (a deprecated feature):
Sources: codex-rs/core/src/config/mod.rs782-836
The JSON Schema for config.toml is generated from the Rust types using schemars and is located at codex-rs/core/config.schema.json This schema is used by IDEs and tools to provide autocomplete and validation for config files.
The schema includes all configuration structures with their documentation:
ConfigToml (root)ConfigProfile (profiles)McpServerConfig (MCP servers)Permissions (security)History (persistence)Tui (terminal UI)Refresh this wiki