Codex config.toml Examples: 7 Configs to Copy (2026)

Published 2026-10-28 · 5 min read · by AgentKit Co

OpenAI's Codex CLI and IDE extension read their settings from a TOML file. Your personal defaults live in ~/.codex/config.toml, and a repo can add its own .codex/config.toml on top. One short file sets the model, how often Codex stops to ask before running a command, how much of your disk and network it can touch, and which MCP servers it can call.

This page gives you seven configs to copy, free and without a signup. Everything here was checked on 2026-10-28 against the official Config basics page and the Configuration Reference. Codex changes often (one approval setting was retired this year), so re-check anything you rely on.

Where config.toml lives, and who wins

Codex merges several layers. From highest priority to lowest:

On a work machine, an admin's requirements.toml can also forbid values outright, such as approval_policy = "never" or sandbox_mode = "danger-full-access". Config sets defaults; requirements set limits.

1. A safe everyday default

Put this in ~/.codex/config.toml. Codex can edit files in your project and asks before anything riskier.

# ~/.codex/config.toml
# model = "..."            # optional: any model your account can use
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
web_search = "cached"      # the default; "live", "indexed" or "disabled" also work

approval_policy accepts on-request (interactive work) or never (scripts and codex exec). sandbox_mode accepts read-only, workspace-write or danger-full-access. Leave model out unless you need a specific one; the docs say to pick a model that's actually available to your account.

2. Read-only for reviewing code you don't trust yet

# ~/.codex/review.config.toml  (use with: codex --profile review)
sandbox_mode = "read-only"
approval_policy = "on-request"
web_search = "disabled"

Profiles are separate files next to config.toml, named <profile>.config.toml. Keep only the values that differ from your main file; everything else is inherited.

3. A per-project file the whole team shares

Commit this as .codex/config.toml at the repo root:

# .codex/config.toml
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"
project_doc_fallback_filenames = ["CLAUDE.md", "CONTRIBUTING.md"]

[sandbox_workspace_write]
network_access = false

project_doc_fallback_filenames tells Codex what to read when there's no AGENTS.md, which is handy when the repo already has a CLAUDE.md. Project files can't set provider, auth, notification, profile or telemetry keys: Codex ignores model_provider, model_providers, openai_base_url, notify, profile, profiles and otel in a project file, so keep those in your user config.

4. Mark which projects are trusted

A project's .codex/ folder (config, hooks and rules) only loads when you trust the project. You can record that in your user file:

# ~/.codex/config.toml
[projects."/home/me/code/my-app"]
trust_level = "trusted"

[projects."/home/me/downloads/some-random-repo"]
trust_level = "untrusted"

5. Add MCP servers

A local (stdio) server and a remote (HTTP) server:

# ~/.codex/config.toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/code"]
startup_timeout_sec = 20      # default is 10
tool_timeout_sec = 60         # default is 60

[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"   # token comes from the environment, not the file
enabled_tools = ["search", "fetch"]

Other useful per-server keys: env (variables passed to a stdio server), disabled_tools (a deny list applied after enabled_tools), enabled = false to switch a server off without deleting it, and required = true to make startup fail if the server can't start.

6. Let commands reach the network (carefully)

workspace-write keeps commands offline by default. To allow outbound access for commands in the sandbox:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/home/me/.cache/pip"]   # extra folders Codex may write to

Only turn this on for projects you trust. Codex also has named permission profiles (default_permissions, with built-ins :read-only, :workspace and :danger-full-access) for finer control; don't combine those with sandbox_mode in the same file.

7. Keep secrets out of spawned commands

[shell_environment_policy]
inherit = "core"                 # all | core | none
ignore_default_excludes = false  # turn on automatic filtering of *KEY*, *SECRET*, *TOKEN* names

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

Watch out: ignore_default_excludes defaults to true, which means the automatic secret-name filter is off until you set it to false.

Fixes when Codex ignores your config

• Project file does nothing. The project isn't trusted, so .codex/config.toml is skipped. Trust it (example 4) and restart.
• "untrusted is not supported". approval_policy = "untrusted" was retired. Use on-request or never. (trust_level = "untrusted" under [projects] is still fine; that's a different setting.)
• on-failure warnings. Also deprecated; switch to on-request.
• Provider or notify settings ignored. They're in a project file. Move them to ~/.codex/config.toml.
• A value won't stick on a work laptop. An admin requirements.toml is overriding it. You can't change that locally.
• Old [features] web search flags. features.web_search, web_search_cached and web_search_request are deprecated. Use the top-level web_search key.
• Need a one-off change? Use codex -c key=value instead of editing the file.

Pair it with AGENTS.md

config.toml controls what Codex is allowed to do. What it should know about your project (commands, conventions, folders not to touch) goes in AGENTS.md. See AGENTS.md examples and how to write AGENTS.md.

The free AGENTS.md generator builds a starting AGENTS.md in your browser from your package.json or pyproject.toml. The AI Coding Agent Config Kit adds 12 stack templates and 12 prompts that audit and test them.

Keep reading