Add an example for config.toml in the repository root

Resolved 💬 3 comments Opened Aug 24, 2025 by llk23r Closed Nov 11, 2025
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What feature would you like to see?

Proposal

Add a config.toml.example file to clarify which configuration options are available and the required order in which they must appear.

What problem will this solve?

This will help answer the questions: Which configuration keys are available? and How and where should they be set?

Relevant issues:

The preferred_auth_method is mentioned in README but it's not present in config.md.

"Recall that in TOML, root keys must be listed before tables."

^This comment is under the model_providers section in config.md, pretty easy to miss when reading other sections of the doc directly. For instance:
notify in config.md doesn't indicate that adding it at the bottom will not work and will practically fail silently because of the mismatch in order of declaration of root keys.

While this might be a common knowledge to some, it's better to provide an example, will also be handy to streamline nested configs in the future.

Are you interested in implementing this feature?

Yes! I'd love pick it up.

Additional information

Some examples of repos doing this:

View original on GitHub ↗

3 Comments

Alfredo-Sandoval · 1 year ago

@llk23r - what I am using - hope it helps!

# =========================
# Codex CLI config.toml
# =========================
# Rule: In each "CHOOSE ONE" block, uncomment EXACTLY ONE line.

# -------------------------
# Model (string)
# -------------------------
# CHOOSE ONE:
model = "gpt-5"
# model = "o3"
# model = "o4-mini"

# -------------------------
# Model provider (string)
# -------------------------
# CHOOSE ONE:
model_provider = "openai"
# model_provider = "openai-chat-completions"   # if you define that provider below
# model_provider = "ollama"                     # local
# model_provider = "azure"                      # Azure OpenAI

# -------------------------
# Reasoning effort (string)
# -------------------------
# CHOOSE ONE:
model_reasoning_effort = "high"
# model_reasoning_effort = "medium"
# model_reasoning_effort = "low"
# model_reasoning_effort = "minimal"

# -------------------------
# Reasoning summaries (string)
# -------------------------
# CHOOSE ONE:
model_reasoning_summary = "auto"
# model_reasoning_summary = "concise"
# model_reasoning_summary = "detailed"
# model_reasoning_summary = "none"

# -------------------------
# Verbosity (string)
# -------------------------
# CHOOSE ONE:
model_verbosity = "medium"
# model_verbosity = "low"
# model_verbosity = "high"

# -------------------------
# Force reasoning summaries on non-default combos (bool)
# -------------------------
# CHOOSE ONE:
model_supports_reasoning_summaries = true
# model_supports_reasoning_summaries = false

# -------------------------
# Approval policy (string)
# -------------------------
# CHOOSE ONE:
approval_policy = "on-request"
# approval_policy = "untrusted"
# approval_policy = "on-failure"
# approval_policy = "never"

# -------------------------
# Sandbox mode (string)
# -------------------------
# CHOOSE ONE:
sandbox_mode = "danger-full-access"   # no sandbox
# sandbox_mode = "workspace-write"     # writes allowed in cwd/tmp only
# sandbox_mode = "read-only"           # default in docs: no writes, no network

# If you select "workspace-write", you may also configure:
# [sandbox_workspace_write]
# # Writable roots (bool/array) — CHOOSE ONE for each:
# # exclude_tmpdir_env_var = true
# exclude_tmpdir_env_var = false
# # exclude_slash_tmp = true
# exclude_slash_tmp = false
# # Optional additional writable roots:
# # writable_roots = ["/Users/YOU/.pyenv/shims"]
# # Network inside sandbox — CHOOSE ONE:
# # network_access = true
# # network_access = false

# -------------------------
# Response storage (bool)
# -------------------------
# CHOOSE ONE:
disable_response_storage = false
# disable_response_storage = true   # use for ZDR / no caching

# -------------------------
# Shell environment policy
# -------------------------
[shell_environment_policy]
# inherit — CHOOSE ONE:
inherit = "core"
# inherit = "all"
# inherit = "none"

# Keep default secret filtering?
ignore_default_excludes = false

# Drop patterns (array of globs); keep empty if not needed
exclude = ["AWS_*", "AZURE_*"]
# exclude = []

# Force-set environment vars (table); keep empty if not needed
set = { }
# set = { CI = "1" }

# Whitelist patterns (array of globs); empty means no whitelist
include_only = []
# include_only = ["PATH", "HOME"]

# -------------------------
# Providers (optional — define only what you use)
# -------------------------
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1"
# env_key = "OPENAI_API_KEY"
# # Per-provider network tuning (optional):
# # request_max_retries = 4
# # stream_max_retries = 10
# # stream_idle_timeout_ms = 300000

# [model_providers.openai-chat-completions]
# name = "OpenAI using Chat Completions"
# base_url = "https://api.openai.com/v1"
# env_key = "OPENAI_API_KEY"
# wire_api = "chat"

# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# env_key = "AZURE_OPENAI_API_KEY"
# query_params = { api-version = "2025-04-01-preview" }

# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"

# -------------------------
# MCP servers (optional)
# -------------------------
# [mcp_servers.example]
# command = "npx"
# args = ["-y", "mcp-server"]
# env = { API_KEY = "value" }

# -------------------------
# Profiles (optional)
# -------------------------
# [profiles.default]
# model = "gpt-5"
# model_provider = "openai"
# approval_policy = "on-request"
# model_reasoning_effort = "high"
# model_reasoning_summary = "auto"
# model_verbosity = "medium" 
llk23r · 1 year ago

Thanks a lot for sharing it, @Alfredo-Sandoval! It's pretty comprehensive and looks like most keys are covered! 🙌🏼

I'll also add preferred_auth_method and notify to the list.

etraut-openai contributor · 9 months ago

An example config.toml was recently added to the documentation.