Introduction

Codex is not just a coding assistant. In serious engineering workflows, it behaves more like a configurable local agent runtime: it can read a repository, reason over project context, execute commands, use external tools, interact with MCP servers, and adapt behaviour based on local, project, and profile-specific configuration.

That flexibility makes configuration important. A weak Codex setup may either be too restricted to be useful or too permissive to be safe. A strong setup gives the agent enough autonomy to move quickly while constraining the blast radius of mistakes, malicious packages, prompt injection, destructive shell commands, or over-eager plugin calls.

For beginners, the key idea is simple: Codex stores durable preferences in a TOML file called config.toml. For advanced users, that file becomes the control plane for model selection, sandboxing, approvals, web search, MCP servers, plugin policy, shell execution, profiles, permissions, project trust, and experimental features.

This article starts with a short primer and then assumes the reader is comfortable with terms like sandboxing, MCP, CLI flags, environment inheritance, tool-call approval, workspace trust, and agentic execution.

The Configuration File As Agent Control Plane

Codex stores user-level configuration at:

For project-specific behaviour, Codex can also read:

The user-level file is the correct place for durable personal defaults: your preferred model, reasoning effort, personality, web-search mode, common MCP servers, plugin settings, and baseline sandbox posture. The project-level file is the correct place for repository-specific behaviour: extra writable roots, project-specific MCP servers, local hooks, skills, or agent rules.

The practical distinction matters. A user-level config follows you across projects. A project-level config should encode only what is actually true for that repository.

Configuration Layers And Precedence

Codex resolves configuration through a precedence stack. Higher-priority values override lower-priority values:

This is the first thing to check when a setting appears not to work. A value in the user file may be overridden by a profile. A project-level file may not load because the project is not trusted. A CLI override may be masking a persistent setting.

A Useful Mental Model

Think of Codex configuration in three layers:

• Global Defaults: stable preferences that should apply almost everywhere.

• Project Policy: repo-specific trust, execution, and integration settings.

• Session Overrides: one-off changes for a specific task.

This separation keeps the configuration understandable. Avoid putting everything in the global file. Also avoid project-local settings for personal preferences that should not travel with the repository.

Minimal Practical Configuration

A minimal but useful configuration might look like this:

This establishes a productive baseline:

• Use a capable default model.

• Give the agent medium reasoning effort.

• Allow workspace edits, but not unrestricted system access.

• Ask for approval when required.

• Use cached web search by default.

• Keep stable productivity features enabled.

For most engineering workflows, this is a better default than either fully read-only operation or danger-full-access.

Root-Level Settings

Root-level keys must appear before TOML tables. This is a common source of broken configuration files. Once you start writing [features], [mcp_servers.], or [plugins.], subsequent bare root keys may no longer parse as intended.

Model Selection

The model key defines the default model used by Codex. Use this for the model you generally want in new CLI, IDE, or app sessions.

For engineering work, the model choice is not only about raw capability. It also affects latency, cost profile, tool-call behaviour, and quality of long-horizon planning. Use a stronger model by default if your tasks involve architecture, cross-file refactors, security-sensitive changes, or complex debugging.

Reasoning Effort

Reasoning effort controls how much reasoning the model applies when the selected model supports it. In practice:

• low is useful for quick edits, formatting, and shallow code changes.

• medium is a sensible daily default.

• high or xhigh is better for architectural refactors, bug isolation, difficult test failures, migrations, or security review.

Do not use high reasoning effort by default unless your workflow justifies the latency. For a technical lead or consultant moving across multiple repositories, profiles are usually a better solution.

Approval Policy

Approval policy controls when Codex pauses before executing generated commands or tool calls. For most local development, on-request is the right balance. It lets Codex move without asking about every trivial action, while still requiring approval for sensitive or potentially destructive operations.

Avoid never unless you are in a controlled environment, using trusted code, and understand the risk. It is convenient, but convenience is not the same as safety.

Sandbox Mode

Sandboxing determines what Codex can read, write, and execute. The key modes are:

workspace-write is the practical default for serious development because the agent can actually edit files and run tests. However, it still constrains write access to the workspace and related allowed paths.

Web Search Mode

Codex supports top-level web-search configuration:

Use cached for general development tasks where current news or changing public documentation is not critical. Use live when the task depends on current SDKs, package versions, changelogs, issue trackers, vendor docs, or newly released APIs.

Do not use the deprecated legacy feature flags such as [features].web_search, [features].web_search_cached, or [features].web_search_request for new configs. Prefer the top-level web_search setting.

Personality

The personality key sets the default communication style. For engineering work, pragmatic is usually a good default because it biases Codex toward direct, implementation-oriented responses.

Useful values include:

This does not replace good instructions. It only controls the default tone and response style where supported.

Feature Flags

Feature flags live under the [features] table. They control optional, stable, experimental, or under-development behaviours.

The important point: do not invent feature keys. If Codex reports that feature flags need specification, it is usually because a key is unknown, deprecated, or has moved.

For example, this is suspicious:

There is no general experimental feature switch. Codex expects named features, not a blanket experimental mode.

Stable Feature Flags

These are generally safe to enable if they match your workflow:

For engineering use, multi_agent, shell_snapshot, shell_tool, and personality should normally remain enabled. undo is worth enabling if you frequently let Codex perform multi-file edits. memories is useful if you want Codex to retain durable workflow preferences, but less useful if you prefer every repo to be self-documenting through AGENTS.md, .codex/, tests, and local rules.

Experimental And Under-Development Feature Flags

Experimental flags are powerful but should be treated as unstable API surface.

Use these intentionally:

• apps enables ChatGPT Apps/connectors support.

• codex_git_commit enables Codex-generated commits and commit attribution trailers.

• plugin_hooks opts into lifecycle hooks bundled with enabled plugins.

The most important one to treat carefully is plugin_hooks. Hooks can change agent behaviour around lifecycle events. They are useful for strong automation, but they also increase the amount of implicit behaviour in your environment.

Deprecated Feature Flags

Avoid these in new configuration files:

Use this instead:

This distinction matters because old web-search feature flags can coexist with top-level web-search settings and make your configuration harder to reason about.

Sandbox And Network Configuration

The most important security decision in a Codex config is the balance between autonomy and containment.

For normal development:

For local work that needs package installation, external docs, or networked test services:

Network access is not a harmless toggle. It allows generated shell commands to contact external systems. That may be necessary for npm install, pip install, package registry checks, SDK docs, Sentry, Supabase, Vercel, or integration tests. It also creates an exfiltration path if a dependency, shell command, or prompt-injected instruction is hostile.

Writable Roots

You can add extra writable roots when the workspace alone is insufficient:

Use this sparingly. Every additional writable root increases the possible blast radius of a bad command.

Temporary Directory Controls

Some workflows write to /tmp or $TMPDIR. If you want a tighter sandbox, you can exclude them:

This is useful for high-trust review sessions, security audits, or any workflow where you do not want the agent using temp directories as a side channel.

Windows Configuration

On native Windows, Codex supports Windows-specific sandbox settings:

Use elevated where possible. Use unelevated only as a fallback when administrator permissions or setup constraints prevent the recommended mode.

For WSL-heavy workflows, standardise paths. Mixing Windows paths and WSL paths in project trust settings can become confusing:

This may work, but it creates ambiguity. Prefer one path convention per environment. If you launch Codex inside WSL, prefer /mnt/d/.... If you launch Codex natively on Windows, prefer d:\....

Project Trust

Codex only loads project-scoped .codex/ configuration layers for trusted projects. That is a security feature, not friction.

A project trust entry looks like this:

Do not mark arbitrary cloned repositories as trusted. A trusted repository can carry local instructions, hooks, rules, and configuration that influence agent behaviour.

A practical policy:

• Trust your own active repos.

• Trust client repos only after reviewing .codex/, AGENTS.md, scripts, hooks, and install commands.

• Keep archived repos untrusted unless you are actively working in them.

• Prefer read-only mode for unknown third-party codebases.

MCP Servers

MCP, or Model Context Protocol, lets Codex connect to external tools and services through configured servers. MCP servers can be local stdio processes, HTTP servers, or plugin-provided servers.

A local stdio MCP server looks like this:

An HTTP MCP server looks like this:

Use MCP for tools that genuinely improve the coding workflow. Good examples include browser automation, documentation retrieval, internal knowledge systems, code-search systems, issue trackers, and deployment tools.

Avoid configuring MCP servers just because they exist. Every server expands the tool surface available to the agent.

MCP Approval Modes

For plugin-provided MCP servers, Codex supports approval controls such as:

Typical values include:

The exact safe setting depends on the tool. Search and read tools can often be more permissive. Destructive tools, send actions, delete actions, or external write actions should generally require approval.

Plugins

Plugins bundle reusable workflows for Codex. A plugin can include skills, app integrations, MCP servers, and related assets.

Example plugin declarations:

A broad plugin surface is plausible for a technical consultant working across cloud, AI, SaaS, and automation. It is also operationally broad. The more plugins enabled, the more important approval policy and plugin-specific tool restrictions become.

Recommended Plugin Strategy

Use three plugin tiers:

Sensitive plugins should use stricter approval settings. Reading an issue tracker is lower risk than sending an email or modifying a calendar event.

Skills

Skills are reusable instruction bundles. They are useful when you want Codex to follow a repeatable process for a class of task, such as reviewing pull requests, generating NUnit tests, writing Sentry instrumentation, or updating a Next.js route.

A skill config entry can point to a local skill folder:

Use skills when repeated prompt text becomes too large, too error-prone, or too important to leave implicit.

Good candidates:

• Test generation rules.

• Project documentation rules.

• Security review checklists.

• Architecture decision record generation.

• Repository-specific code style.

• Release note generation.

• Sentry instrumentation policy.

Profiles

Profiles let you save named configuration sets and activate them with:

A profile can override model, reasoning effort, web search, personality, sandbox, tools, feature flags, and other supported keys.

High-Reasoning Profile

Use this for architectural decisions, difficult bugs, refactors, migrations, and security-sensitive reviews:

Live-Research Profile

Use this when current documentation, changelogs, package releases, or vendor information matter:

Safe Review Profile

Use this for untrusted repositories or code review without edits:

Implementation Profile

Use this for normal coding, tests, and local execution:

Shell Environment Policy

The shell environment policy controls which environment variables Codex forwards to commands it spawns.

A conservative configuration:

A stricter allow-list configuration:

This is a high-leverage security control. Many developer environments contain long-lived cloud credentials, package registry tokens, GitHub tokens, deployment tokens, and database connection strings. An agent executing shell commands should not automatically inherit everything.

Tool Output Limits

Codex can store command and tool output in conversation history. Large logs are useful for debugging but can also consume context rapidly.

Use a higher limit when debugging CI failures, compiler errors, build logs, or large test suites. Use a lower limit when working on smaller tasks where excess logs create noise.

TUI Customisation

Codex also supports TUI-specific configuration.

These settings are not essential, but they matter if you live in the terminal. A tuned TUI reduces interaction friction during long-running agent sessions.

A Cleaned Reference Configuration

A solid multi-repo engineering configuration combines several useful pieces: GPT-5.5, medium reasoning effort, pragmatic personality, workspace-write sandboxing, MCP servers for Playwright and Notion, curated plugins, trusted project paths, and network access in workspace-write mode.

Sections that look suspicious unless read by a custom wrapper – like [core], [server], [database], [cache], [security] – are not typical Codex config sections and should be removed from config.toml to reduce ambiguity.

A cleaner version that keeps the intent while aligning with documented Codex-style configuration:

This file is intentionally opinionated. It keeps a broad plugin-enabled workflow, but removes fake-looking app-server sections and replaces a generic experimental = false flag with named feature flags.

Recommended Configuration Patterns

Pattern 1: Safe Default, Powerful Profiles

Keep the global configuration conservative and use profiles for escalation:

This prevents the default environment from becoming too permissive while still allowing fast escalation when you need package installs, live research, or networked integration tests.

Pattern 2: Multi-Repo Consultant Setup

For a consultant or technical lead moving across repositories, define trusted active repos explicitly:

Pair this with read-only mode for unknown repositories and workspace-write only once the repo is understood.

Pattern 3: Security-Review Mode

For vulnerability review, exploit analysis, or dependency triage:

This lets Codex inspect and reason, but avoids accidental modification.

Pattern 4: Implementation Sprint Mode

For a trusted repo where speed matters:

Use this when Codex is making real changes, running tests, and iterating on implementation tasks.

Common Mistakes

Mistake 1: Treating Config As A Junk Drawer

Do not put arbitrary application settings into config.toml unless Codex actually reads them. Sections like [database], [cache], or [server] look plausible but may be ignored.

This is confusing because ignored settings do not necessarily fail loudly. The file can appear valid while giving a false sense of control.

Mistake 2: Enabling Network Access Globally Without Intention

This is useful, but it is also elevated risk. If you need it frequently, keep it. If you only need it for installs or live integration work, move it into a profile.

Mistake 3: Mixing Deprecated And Current Web Search Configuration

Avoid this:

Use this:

Mistake 4: Over-Trusting Repositories

Trusting a repo allows project-scoped configuration, rules, hooks, and instructions to load. That is desirable for your own active projects. It is not desirable for arbitrary codebases.

Mistake 5: Not Versioning Team Configuration

For teams, put project-level .codex/config.toml, AGENTS.md, hooks, and skills under version control where appropriate. Treat agent configuration like infrastructure or CI configuration: it shapes execution behaviour and should be reviewed.

Operational Checklist

Use this checklist when reviewing a Codex setup:

Source Links

• OpenAI Codex: Config Basics

• OpenAI Codex: Configuration Reference

• OpenAI Codex: Advanced Configuration

• OpenAI Codex: Sample Configuration

• OpenAI Codex: MCP

• OpenAI Codex: Plugins

• OpenAI Codex: Permissions

• OpenAI Codex: Agent Approvals And Security

• OpenAI Codex: Best Practices

Conclusion

Codex configuration is not decoration. It is the operational policy layer for an autonomous engineering assistant.

A good configuration gives Codex enough authority to be useful while keeping the environment bounded, reviewable, and predictable. The strongest setups use conservative global defaults, explicit trusted projects, named profiles for risk escalation, carefully scoped plugins, filtered environment variables, and clear comments explaining why each setting exists.

For small edits, a minimal config is enough. For serious engineering workflows across multiple repos, clients, plugins, and toolchains, config.toml becomes part of the development system itself. Treat it with the same discipline you would apply to CI configuration, deployment policy, or local development environment setup.