Codex CLI config.toml Guide 2026

Quick answer

For most local development, start with a user-level ~/.codex/config.toml like this:

model = "gpt-5.6"
model_provider = "openai"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

This gives Codex permission to work inside the current workspace while keeping network access off unless you enable it for a specific task. sandbox_mode controls what Codex can technically do; approval_policy controls when it must ask first. Treat them as separate controls.

If you only need installation, login, and first-run examples, start with the Codex CLI Developer Guide. This article covers current configuration, profile migration, project instructions, subagents, and plugin trust boundaries.

Where Codex reads configuration

The main user configuration file is:

~/.codex/config.toml

A trusted repository can also contain a project-scoped file:

.codex/config.toml

Project configuration is useful for repository-specific defaults, but it cannot override every machine-local setting. Provider, authentication, profile-selection, notification, and telemetry settings belong in user-level configuration. Check the official configuration reference before adding a key to a project file.

Codex merges configuration from several layers. In practice, the most specific value wins: command-line flags and -c overrides take priority, followed by trusted project configuration, an explicitly selected profile, user configuration, system configuration, and built-in defaults. Use /status to inspect the effective configuration instead of guessing which file won.

A safe baseline for development

Use this as a starting point, then add only the settings your workflow needs:

model = "gpt-5.6"
model_provider = "openai"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

[agents]
max_threads = 4
max_depth = 1

The exact model IDs and supported reasoning values can change. Treat the current Codex model documentation as the source of truth rather than copying a model name from an older post.

Enable network access only when the task requires it, such as installing dependencies:

codex \
  --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  "install the dependencies and run the tests"

If you need tighter outbound controls, pair network access with the documented network proxy and an explicit domain policy. Turning on the proxy does not grant network access by itself. The agent approvals and security guide explains the interaction.

Profiles: the current format

Profiles are separate configuration files next to config.toml. For example:

~/.codex/review.config.toml
~/.codex/ci.config.toml

Select one explicitly:

codex --profile review "inspect the authentication changes"
codex --profile ci "run the non-interactive checks"

A read-only review profile can look like this:

model = "gpt-5.6"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

A controlled CI profile can look like this:

model = "gpt-5.6-terra"
model_reasoning_effort = "low"
approval_policy = "never"
sandbox_mode = "workspace-write"

Do not copy older examples that put [profiles.review] inside the base config.toml or set profile = "review" there without checking the current documentation. The profile-file format is easier to isolate, review, and migrate.

Migration from older examples

• Replace approval_policy = "on-failure" with on-request for interactive work, or never for controlled non-interactive runs.
• Replace [profiles.review] in config.toml with ~/.codex/review.config.toml.
• Select a profile explicitly with codex --profile review.
• Keep network access off by default and enable it only for the task that needs it.
• Prefer explicit --sandbox and approval flags in new automation; --full-auto is deprecated compatibility behavior.

The important change is conceptual: configuration is a trust boundary, not just a collection of convenience flags.

Sandbox modes and approvals

These controls answer different questions:

• read-only: inspect and reason without editing the workspace.
• workspace-write: edit and run commands in the workspace, with network access off by default.
• danger-full-access: remove the normal filesystem and network restrictions. Reserve it for disposable containers or tightly controlled runners.

Approval policy determines when Codex pauses:

• untrusted: ask before commands outside the trusted set.
• on-request: allow normal sandboxed work and ask when an action needs escalation.
• never: do not prompt. Use only for controlled automation where the environment is already constrained.

--yolo is shorthand for bypassing approvals and sandbox protections. Never use it in a normal production checkout. If you need automation, prefer codex exec with an explicit sandbox and the smallest permission set that works.

Some current Codex releases also expose permission profiles. Treat those as an alternative configuration model, not an additional layer to combine casually with sandbox_mode and [sandbox_workspace_write]. Choose one model, follow its documentation, and inspect the result with /status.

AGENTS.md and project instructions

AGENTS.md supplies persistent instructions that Codex reads before doing work. Use it for commands, architecture constraints, test requirements, package-manager rules, and security boundaries.

A useful project file is concrete:

# AGENTS.md

## Commands
- Run `bun test` before handoff.
- Use the repository package manager; do not create a second lockfile.

## Rules
- Prefer minimal diffs.
- Do not edit secrets or environment files.
- Ask before adding dependencies.

Codex can load global instructions from ~/.codex/AGENTS.md or AGENTS.override.md, then applicable project and nested-directory instructions as it walks toward the working directory. Use AGENTS.override.md when a narrower directory needs to replace broader guidance. See the AGENTS.md documentation.

Project configuration and instructions are trust-sensitive. Review them before allowing hooks, plugins, MCP servers, or other automation to run in a repository you do not control.

Subagents

Subagents are useful for bounded, mostly independent work: repository exploration, test-gap review, documentation lookup, and summarization. Keep delegation narrow and cap concurrency so a simple task does not become an expensive fan-out.

The current configuration reference supports agent controls such as:

[agents]
max_threads = 4
max_depth = 1

Use a strong parent workflow for synthesis and smaller workers for read-heavy tasks. Parallel write-heavy work increases merge conflicts and makes review harder.

Plugins and marketplaces

Plugins package reusable skills, app integrations, MCP configuration, and sometimes hooks. Start with the curated plugin directory, inspect the manifest and permissions, and treat every marketplace as a software distribution channel for agent behavior.

Useful commands include:

codex plugin marketplace add owner/repo@v1.2.0
codex plugin marketplace list
codex plugin list
codex plugin add my-plugin@my-marketplace

Prefer project-scoped installs for repository-specific tools and globally installed plugins only for utilities you personally trust. Audit plugins that include hooks, MCP servers, or external app access. Pin a repository reference when the installer supports it.

The official plugins documentation covers plugin layout and marketplace sources. Do not treat a plugin as harmless prompt text: it may add executable hooks and external tool access.

Non-interactive Codex

Use codex exec in scripts and CI:

codex exec \
  --sandbox read-only \
  "summarize the repository and list the five riskiest areas"

For an automation step that must edit files, use --sandbox workspace-write explicitly and run it in an isolated, reviewable environment. codex exec is read-only by default, and --full-auto is deprecated compatibility behavior.

For machine-readable output:

codex exec --json "summarize the repository structure" | jq

To continue a previous non-interactive run:

codex exec resume --last "apply the smallest safe fix"

See the official non-interactive mode guide for CI authentication and output details.

Troubleshooting configuration

If a setting appears to be ignored, check these in order:

1. Confirm the file path and CODEX_HOME value.
2. Confirm the repository is trusted before relying on .codex/config.toml.
3. Check whether the key is allowed at project scope.
4. Look for a command-line flag, -c override, or selected profile taking precedence.
5. Run /status and compare the effective configuration with the file you edited.
6. Check the current configuration reference for renamed or deprecated keys.

Security checklist

• Keep read-only for review and exploration.
• Use workspace-write for normal development.
• Leave network access off unless a task needs it.
• Treat danger-full-access and --yolo as disposable-environment options.
• Review AGENTS.md, hooks, plugins, and MCP configuration before trusting a repository.
• Keep credentials out of project files and logs.
• Create a Git checkpoint before allowing automated edits.

Codex configuration is now an operating policy for an agent, not just a preference file. Keep the defaults narrow, make exceptions explicit, and verify the effective settings before a high-impact run.

Related reading

For the 0.42.0-era commands, shell helpers, and sandbox flags this guide supersedes, see the Codex CLI Developer Guide.

For what Codex became past the CLI: Codex is becoming a workspace, not a chatbot and The Codex operating manual for knowledge workers.

For keeping this configuration portable across harnesses: Portable Agent Ops.