Feature Flags in config.toml and Rules in AGENTS.md: Structuring Codex Configurations

What is the "features" Configuration Block in Codex?

When using OpenAI Codex, the [features] block in ~/.codex/config.toml allows you to toggle additional capabilities and experimental features.

While documented in the official API reference, these options are rarely discussed in detail. Enabling them allows you to customize the agent's behavior, such as persisting conversation context or running custom script hooks before and after executing shell commands.

This article reviews the key settings in the [features] block, provides practical configuration examples, and outlines a structured approach to managing these configurations reliably.

Verified Environment

• OS: Windows 11 (PowerShell 7)
• Tool: Codex v0.142.0
• Runtime: Node.js v22

Configuration Hierarchy and Precedence

Codex settings are evaluated hierarchically, allowing local project configurations to override machine-wide settings.

Settings are applied in the following order of precedence:

flowchart TB
    A[System Defaults] --> B["User Global Config (~/.codex/config.toml)"]
    B --> C["Profile-Specific Config (--profile)"]
    C --> D["Project-Specific Config (.codex/config.toml)"]
    D --> E["CLI Flags & Temporary Config (--config)"]

For most workflows, keeping global settings in ~/.codex/config.toml and overriding only project-specific parameters in a local .codex/config.toml is the cleanest approach.

Note

Project-Specific Configuration Limitations
A local .codex/config.toml is only loaded if the project directory is marked as trusted. This security measure prevents malicious repositories from executing arbitrary lifecycle hooks or altering sandbox permissions without your explicit approval.

features Key Details and Recommendations

Below is a breakdown of the primary settings available under the [features] block, based on the OpenAI Developer Reference as of July 2026.

Web Search Controls are Recommended at the Top Level

Legacy tutorials and documentation often show web_search = true or web_search_request = true placed within the [features] block. These keys are deprecated.

Modern configuration requires specifying this behavior at the top level of your configuration file:

 # ~/.codex/config.toml

 # cached: Uses OpenAI-managed search cache (default)
 # live: Fetches real-time search results
 # disabled: Disables web search capabilities
web_search = "cached"

Using cached maintains deterministic agent behaviors. You can temporarily toggle it to live or use the CLI flag --search when you need to research recent updates or active outages.

Configuration Philosophy for Collaborative Development

In collaborative repositories, configuration design should prioritize repeatability across varying developer machines and clean isolation from global user preferences. Below is a structured approach to separating machine-local settings from project-wide rules.

1. Limit memories to Personal Task History (Use AGENTS.md for Rules)

While memories = true is highly effective for maintaining user-specific context across sessions, these memories reside entirely within the local agent environment.

Relying on interactive training (conversational learning) to teach the agent project coding styles or architectural guidelines is an anti-pattern. This knowledge is not transferable to other team members or freshly provisioned agent instances.

Instead of relying on personal memories, project-wide rules and constraints should be documented in version-controlled instruction files like AGENTS.md. This ensures consistent agent behavior across all development environments.

2. Do Not Declare Stable Features that Default to true

Stable settings (such as multi_agent or shell_snapshot) that default to true do not need to be explicitly listed in your config.toml.

Avoiding redundant configuration lines prevents file bloat and makes it immediately clear which defaults you have intentionally overridden, simplifying troubleshooting.

3. Pair Lifecycle Hooks with Shared Scripts

While hooks = true allows powerful automations, complex inline scripting within a local configuration file hides execution details from other environments.

Keep local hook configurations simple. Instead of writing complex hooks, reference modular scripts stored inside the repository so that the same linting, formatting, or validation tasks run consistently for every contributor.

Practical config.toml Example

Below is a configuration template applying these recommendations.

 # ~/.codex/config.toml

 # Target the flagship model following the deprecation of older models
model = "gpt-5.5"
model_reasoning_effort = "medium"

 # Sandbox and command authorization policies
approval_policy = "on-request"
sandbox_mode = "workspace-write"

 # Optimize web search token consumption by defaulting to cached search
web_search = "cached"

 # Communication style preference
personality = "pragmatic"

[features]
 # Retain personal context history across threads
memories = true

 # Enable hook integrations (actual script scripts are shared within repositories)
hooks = true

 # Stable features defaulting to true are commented out
 # multi_agent = true
 # shell_snapshot = true
 # shell_tool = true

 # Explicitly request elevated permissions for Windows environments
[windows]
sandbox = "elevated"

Conclusion: Balancing Local Preference and Shared Rules

While the [features] block in Codex offers significant customizability, relying solely on local configuration files and memories breaks the reliability of collaborative repository environments.

To ensure your environment remains reproducible for all developers and agents, organize your configuration according to their respective scopes:

flowchart TB
    A["Local Config (~/.codex/config.toml)"] -->|Controls| B["Security, Model Preferences, and Personal Memories"]
    C["Shared Instructions (AGENTS.md / docs/)"] -->|Controls| D["Coding Standards, Workflows, and Shared Agent Skills"]

• Local Settings (config.toml): Dedicated to security levels, model selection, and enabling feature flags. (Note: System-level settings like features cannot be parsed from instruction files like AGENTS.md).
• Shared Instructions (AGENTS.md): Dedicated to repository styling, automation rules, and agent workflows that must remain identical across the team.

Separating these concerns simplifies updates and avoids system configuration issues. We recommend starting with a clean, minimal global config and keeping all team-wide developer rules in your version-controlled AGENTS.md.