feat: add support for -c/--config to override individual config items (#1137)

This PR introduces support for `-c`/`--config` so users can override
individual config values on the command line using `--config
name=value`. Example:

```
codex --config model=o4-mini
```

Making it possible to set arbitrary config values on the command line
results in a more flexible configuration scheme and makes it easier to
provide single-line examples that can be copy-pasted from documentation.

Effectively, it means there are four levels of configuration for some
values:

- Default value (e.g., `model` currently defaults to `o4-mini`)
- Value in `config.toml` (e.g., user could override the default to be
`model = "o3"` in their `config.toml`)
- Specifying `-c` or `--config` to override `model` (e.g., user can
include `-c model=o3` in their list of args to Codex)
- If available, a config-specific flag can be used, which takes
precedence over `-c` (e.g., user can specify `--model o3` in their list
of args to Codex)

Now that it is possible to specify anything that could be configured in
`config.toml` on the command line using `-c`, we do not need to have a
custom flag for every possible config option (which can clutter the
output of `--help`). To that end, as part of this PR, we drop support
for the `--disable-response-storage` flag, as users can now specify `-c
disable_response_storage=true` to get the equivalent functionality.

Under the hood, this works by loading the `config.toml` into a
`toml::Value`. Then for each `key=value`, we create a small synthetic
TOML file with `value` so that we can run the TOML parser to get the
equivalent `toml::Value`. We then parse `key` to determine the point in
the original `toml::Value` to do the insert/replace. Once all of the
overrides from `-c` args have been applied, the `toml::Value` is
deserialized into a `ConfigToml` and then the `ConfigOverrides` are
applied, as before.

codex-rs/core/src/config.rs

@@ -16,6 +16,7 @@ use serde::Deserialize;
 use std::collections::HashMap;
 use std::path::Path;
 use std::path::PathBuf;
+use toml::Value as TomlValue;
 
 /// Maximum number of bytes of the documentation that will be embedded. Larger
 /// files are *silently truncated* to this size so we do not take up too much of
@@ -108,6 +109,108 @@ pub struct Config {
     pub codex_linux_sandbox_exe: Option<PathBuf>,
 }
 
+impl Config {
+    /// Load configuration with *generic* CLI overrides (`-c key=value`) applied
+    /// **in between** the values parsed from `config.toml` and the
+    /// strongly-typed overrides specified via [`ConfigOverrides`].
+    ///
+    /// The precedence order is therefore: `config.toml` < `-c` overrides <
+    /// `ConfigOverrides`.
+    pub fn load_with_cli_overrides(
+        cli_overrides: Vec<(String, TomlValue)>,
+        overrides: ConfigOverrides,
+    ) -> std::io::Result<Self> {
+        // Resolve the directory that stores Codex state (e.g. ~/.codex or the
+        // value of $CODEX_HOME) so we can embed it into the resulting
+        // `Config` instance.
+        let codex_home = find_codex_home()?;
+
+        // Step 1: parse `config.toml` into a generic JSON value.
+        let mut root_value = load_config_as_toml(&codex_home)?;
+
+        // Step 2: apply the `-c` overrides.
+        for (path, value) in cli_overrides.into_iter() {
+            apply_toml_override(&mut root_value, &path, value);
+        }
+
+        // Step 3: deserialize into `ConfigToml` so that Serde can enforce the
+        // correct types.
+        let cfg: ConfigToml = root_value.try_into().map_err(|e| {
+            tracing::error!("Failed to deserialize overridden config: {e}");
+            std::io::Error::new(std::io::ErrorKind::InvalidData, e)
+        })?;
+
+        // Step 4: merge with the strongly-typed overrides.
+        Self::load_from_base_config_with_overrides(cfg, overrides, codex_home)
+    }
+}
+
+/// Read `CODEX_HOME/config.toml` and return it as a generic TOML value. Returns
+/// an empty TOML table when the file does not exist.
+fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
+    let config_path = codex_home.join("config.toml");
+    match std::fs::read_to_string(&config_path) {
+        Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
+            Ok(val) => Ok(val),
+            Err(e) => {
+                tracing::error!("Failed to parse config.toml: {e}");
+                Err(std::io::Error::new(std::io::ErrorKind::InvalidData, e))
+            }
+        },
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            tracing::info!("config.toml not found, using defaults");
+            Ok(TomlValue::Table(Default::default()))
+        }
+        Err(e) => {
+            tracing::error!("Failed to read config.toml: {e}");
+            Err(e)
+        }
+    }
+}
+
+/// Apply a single dotted-path override onto a TOML value.
+fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue) {
+    use toml::value::Table;
+
+    let segments: Vec<&str> = path.split('.').collect();
+    let mut current = root;
+
+    for (idx, segment) in segments.iter().enumerate() {
+        let is_last = idx == segments.len() - 1;
+
+        if is_last {
+            match current {
+                TomlValue::Table(table) => {
+                    table.insert(segment.to_string(), value);
+                }
+                _ => {
+                    let mut table = Table::new();
+                    table.insert(segment.to_string(), value);
+                    *current = TomlValue::Table(table);
+                }
+            }
+            return;
+        }
+
+        // Traverse or create intermediate object.
+        match current {
+            TomlValue::Table(table) => {
+                current = table
+                    .entry(segment.to_string())
+                    .or_insert_with(|| TomlValue::Table(Table::new()));
+            }
+            _ => {
+                *current = TomlValue::Table(Table::new());
+                if let TomlValue::Table(tbl) = current {
+                    current = tbl
+                        .entry(segment.to_string())
+                        .or_insert_with(|| TomlValue::Table(Table::new()));
+                }
+            }
+        }
+    }
+}
+
 /// Base config deserialized from ~/.codex/config.toml.
 #[derive(Deserialize, Debug, Clone, Default)]
 pub struct ConfigToml {
@@ -171,29 +274,6 @@ pub struct ConfigToml {
     pub tui: Option<Tui>,
 }
 
-impl ConfigToml {
-    /// Attempt to parse the file at `~/.codex/config.toml`. If it does not
-    /// exist, return a default config. Though if it exists and cannot be
-    /// parsed, report that to the user and force them to fix it.
-    fn load_from_toml(codex_home: &Path) -> std::io::Result<Self> {
-        let config_toml_path = codex_home.join("config.toml");
-        match std::fs::read_to_string(&config_toml_path) {
-            Ok(contents) => toml::from_str::<Self>(&contents).map_err(|e| {
-                tracing::error!("Failed to parse config.toml: {e}");
-                std::io::Error::new(std::io::ErrorKind::InvalidData, e)
-            }),
-            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
-                tracing::info!("config.toml not found, using defaults");
-                Ok(Self::default())
-            }
-            Err(e) => {
-                tracing::error!("Failed to read config.toml: {e}");
-                Err(e)
-            }
-        }
-    }
-}
-
 fn deserialize_sandbox_permissions<'de, D>(
     deserializer: D,
 ) -> Result<Option<Vec<SandboxPermission>>, D::Error>
@@ -227,28 +307,12 @@ pub struct ConfigOverrides {
     pub cwd: Option<PathBuf>,
     pub approval_policy: Option<AskForApproval>,
     pub sandbox_policy: Option<SandboxPolicy>,
-    pub disable_response_storage: Option<bool>,
     pub model_provider: Option<String>,
     pub config_profile: Option<String>,
     pub codex_linux_sandbox_exe: Option<PathBuf>,
 }
 
 impl Config {
-    /// Load configuration, optionally applying overrides (CLI flags). Merges
-    /// ~/.codex/config.toml, ~/.codex/instructions.md, embedded defaults, and
-    /// any values provided in `overrides` (highest precedence).
-    pub fn load_with_overrides(overrides: ConfigOverrides) -> std::io::Result<Self> {
-        // Resolve the directory that stores Codex state (e.g. ~/.codex or the
-        // value of $CODEX_HOME) so we can embed it into the resulting
-        // `Config` instance.
-        let codex_home = find_codex_home()?;
-
-        let cfg: ConfigToml = ConfigToml::load_from_toml(&codex_home)?;
-        tracing::warn!("Config parsed from config.toml: {cfg:?}");
-
-        Self::load_from_base_config_with_overrides(cfg, overrides, codex_home)
-    }
-
     /// Meant to be used exclusively for tests: `load_with_overrides()` should
     /// be used in all other cases.
     pub fn load_from_base_config_with_overrides(
@@ -264,7 +328,6 @@ impl Config {
             cwd,
             approval_policy,
             sandbox_policy,
-            disable_response_storage,
             model_provider,
             config_profile: config_profile_key,
             codex_linux_sandbox_exe,
@@ -356,8 +419,8 @@ impl Config {
                 .unwrap_or_else(AskForApproval::default),
             sandbox_policy,
             shell_environment_policy,
-            disable_response_storage: disable_response_storage
-                .or(config_profile.disable_response_storage)
+            disable_response_storage: config_profile
+                .disable_response_storage
                 .or(cfg.disable_response_storage)
                 .unwrap_or(false),
             notify: cfg.notify,

codex-rs/core/src/config_types.rs

@@ -89,7 +89,7 @@ pub struct Tui {
 }
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
-
+#[serde(rename_all = "kebab-case")]
 pub enum ShellEnvironmentPolicyInherit {
     /// "Core" environment variables for the platform. On UNIX, this would
     /// include HOME, LOGNAME, PATH, SHELL, and USER, among others.