diff --git a/codex-rs/core/config_template.toml b/codex-rs/core/config_template.toml
new file mode 100644
index 0000000000..9c772eecac
--- /dev/null
+++ b/codex-rs/core/config_template.toml
@@ -0,0 +1,45 @@
+# Codex configuration template
+# See https://github.com/openai/codex/blob/main/codex-rs/config.md for details.
+# All values below represent defaults. Uncomment to override them.
+
+# model = "codex-mini-latest"
+# model_provider = "openai"
+# approval_policy = "unless-allow-listed"
+# disable_response_storage = false
+# project_doc_max_bytes = 32768
+# file_opener = "vscode"
+# hide_agent_reasoning = false
+# model_reasoning_effort = "medium"
+# model_reasoning_summary = "auto"
+
+[shell_environment_policy]
+# inherit = "core"
+# ignore_default_excludes = false
+# exclude = []
+# set = {}
+# include_only = []
+
+[sandbox]
+# mode = "read-only"
+# writable_roots = []
+# network_access = false
+
+[history]
+# persistence = "save-all"
+
+[tui]
+# disable_mouse_capture = false
+
+# Example provider override
+#[model_providers.openai]
+# name = "OpenAI"
+# base_url = "https://api.openai.com/v1"
+# env_key = "OPENAI_API_KEY"
+# wire_api = "chat"
+
+# Example profile
+#[profiles.example]
+# model = "o3"
+# model_provider = "openai"
+# approval_policy = "never"
+
diff --git a/codex-rs/core/src/config.rs b/codex-rs/core/src/config.rs
index 240c6eaf29..b5a85c8992 100644
--- a/codex-rs/core/src/config.rs
+++ b/codex-rs/core/src/config.rs
@@ -20,6 +20,8 @@ use std::path::Path;
 use std::path::PathBuf;
 use toml::Value as TomlValue;
 
+const DEFAULT_CONFIG_TEMPLATE: &str = include_str!("../config_template.toml");
+
 /// 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
 /// the context window.
@@ -179,7 +181,8 @@ fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
             }
         },
         Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
-            tracing::info!("config.toml not found, using defaults");
+            tracing::info!("config.toml not found, writing template");
+            write_default_config_template(&config_path);
             Ok(TomlValue::Table(Default::default()))
         }
         Err(e) => {
@@ -189,6 +192,19 @@ fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
     }
 }
 
+fn write_default_config_template(config_path: &Path) {
+    if let Some(parent) = config_path.parent() {
+        if let Err(e) = std::fs::create_dir_all(parent) {
+            tracing::error!("Failed to create config dir: {e}");
+            return;
+        }
+    }
+    match std::fs::write(config_path, DEFAULT_CONFIG_TEMPLATE) {
+        Ok(_) => tracing::info!("wrote default config template at {}", config_path.display()),
+        Err(e) => tracing::error!("Failed to write default config template: {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;