Codex Advanced Configuration

Codex CLIThe advanced configuration layer lets us precisely control model providers, sandbox permissions, hooks, telemetry data, and terminal behavior.

If you are new to Codex, first readConfig basics(Configuration Basics)to build an overall understanding; this article assumes you already know~/.codex/config.tomlits existence and purpose.

Configuration Hierarchy Overview

Codex's configuration is composed of multiple stacked layers. Understanding this is the cornerstone of all subsequent advanced usage.

From bottom to top, the layers are: system layer → user layer (~/.codex/config.toml) → Profile layer → Project layer (.codex/config.toml) → CLI command-line arguments.

Upper layers override lower layers with the same name; the project configuration closest to the current working directory has the highest priority.

The safest way to determine the currently active configuration iscodex --helpto use logs, or explicitly usecodex exec "show my current config"and let the model interpret it for you.

Profiles: Named Configuration Layer

ProfileIs Codex's recommended "scenario-based switching" approach: save a set of configurations as a TOML file, and load it on demand via--profileloading.

Profile files are located in~/.codex/<name>.config.toml, where<name>can only contain letters, digits, hyphens, and underscores.

Create and Use a Profile

Suppose you often perform deep code reviews and want stronger reasoning ability:

Launch Codex with the Profile:

Profile Merge Semantics

Profile files are not a complete configuration; they are an incremental override on top of the user-level~/.codex/config.tomllayer.

This means you only need to write fields "different from the default configuration" in the Profile; other fields automatically inherit user-level settings.

If both user-level and Profile set the same fieldmodel_catalog_json，the Profile value takes precedence.。

Starting from Codex 0.134.0,--profileit no longer readsconfig.tomlin[profiles.<name>]tables, and no longer supports top-levelprofile = "name"selectors. All historical Profile settings must be migrated to separate~/.codex/<name>.config.tomlfiles.

Migrating from Old Configuration to Profile

If your previousconfig.tomllooked like this:

You need to split it into two files:

# 文件路径：~/.codex/config.toml（保留非 profile 部分）
# 注意：删除了 profile = "deep-review" 选择器

# 文件路径：~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

After migration, the originalcodex --profile deep-reviewcommand-line usage remains unchanged.

Command-Line One-Time Override

Sometimes you just want to temporarily change one or two fields for a single task without polluting the configuration files. In that case, you can use CLI overrides:

Prefer Dedicated Flags

If official dedicated parameters are provided (such as--model），prefer the dedicated flag, for best readability:

Using --config to Override Arbitrary Keys

For fields without dedicated flags, use-cor--configOverrides. The value is in TOML format, not JSON.

A few pitfall-prone rules:

• Use dot syntax to locate nested fields, e.g.,mcp_servers.context7.enabled=false
• --configThe value is parsed as TOML; strings containing spaces must be quoted.
• If parsing fails, Codex treats the entire value as a string.

The fastest way to tell whether an override took effect is to follow the command with a simple question: "what model are you using?", letting Codex report the current configuration.

Configuration File and State Locations

Codex stores all local state inCODEX_HOMEthe directory, by default~/.codex。

Common files and their meanings:

Just Want to Change the OpenAI Base URL?

Many people use LLM proxies, routers, or data-residency projects, and only need to modifyopenaithe base URL of the built-in provider.

In this case, directly setopenai_base_url, do not create a new one[model_providers.openai], because built-in IDs cannot be overridden:

Project-Level Configuration .codex/config.toml

Project-level configuration is placed in the repository root's.codex/config.toml, used for team-shared defaults.

Codex searches upward from the working directory,The file closest to the current working directory has the highest priority.。

Boundaries of Project-Level Configuration

For security reasons,only when the project is marked as "trusted"will the project-level .codex/ layer be loaded (including config.toml, local hooks, and local rules).

In untrusted projects, the sensitive keys in the table below are ignored and a startup warning is printed:

These keys must be placed in the user-level~/.codex/config.tomlin.

Relative paths (e.g.,model_instructions_file) are resolved relative to their.codex/containing directory.

If the project is untrusted and you setmodel_provider = "proxy", Codex will print a warning at startup and use the default provider; this is a security design, not a bug.

Hooks: Lifecycle Hooks

Hooks allow you to insert custom scripts at key nodes such as tool calls, round starts, etc., suitable for auditing, sensitive-word filtering, commit checks, and more.

Hooks configuration supports two forms, and the event structure is exactly the same:

The four most commonly used loading locations:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Project-level hooks are loaded only when the project is trusted; user-level hooks are always loaded independently.

Inline TOML Hook Example

The following is a pre-check hook that executes before Bash tool calls:

If the same layer already existshooks.jsonInline also exists[hooks]In the table, Codex will load both and print a warning.It is recommended to choose only one form per layer, to avoid doubling maintenance costs.

Custom Model Providers

When you need to connect Codex to non-OpenAI official endpoints such as LLM proxies, Ollama, Mistral, Azure, etc.,model_providersis the entrance.

Built-in provider ID (openai、ollama、lmstudio）Cannot be reusedotherwise it will conflict.

Basic Definition

Adding HTTP Headers

Some proxies require additional headers (such as tenant identifier, feature flags):

Command-Backed Authentication

When the provider's bearer token needs to be dynamically pulled from an external credential helper, use[model_providers.<id>.auth]：

Runtime constraints for the auth command:

• Not receivingstdin, must output the token tostdout
• Codex automatically trims leading/trailing whitespace, and an empty token is treated as an error.
• Settingsrefresh_interval_ms = 0Indicates refresh only after authentication failure
• Cannot be used together with env_key, experimental_bearer_token, requires_openai_auth

Amazon Bedrock Built-In Provider

Built into Codexamazon-bedrockFor built-in providers, you can directly usemodel_providerReference:

The Bedrock built-in provider only supports nesting..awsthe profile and region overrides under ...; for other custom items, please use the standardmodel_providers.<id>Process.

OSS Local Mode

Codex supports connecting to local "open-source" models (e.g., Ollama, LM Studio), via--ossStart.

If only passing--ossIf no provider is specified, Codex will readoss_providerSelect default:

Usage example:

Azure Provider and Fine-Tuning

Azure OpenAI integration example, demonstrating request-level parameters and retry strategy:

Requires modifying built-inopenaiWhen using the provider's base URL, useopenai_base_url, do not create a new one[model_providers.openai]。

ChatGPT Data Residency Projects

ChatGPT projects with "Data Residency" enabled need to use a region-prefixed base URL:

Not all models support data residency; before choosing, consult the "eligible models" list in the OpenAI data residency documentation.

Model Reasoning, Verbosity, and Context

The most common quartet for controlling model behavior:

wheremodel_verbosityOnly takes effect on providers using the Responses API; the Chat Completions provider will ignore this setting.

Approval Policies and Sandbox Modes

approval_policyControls when Codex stops to ask for human confirmation,sandbox_modeControls which files and networks it can access.

The two dimensions can be combined independently; below is a set of typical configurations:

Common Combinations Quick Reference

Disable Sandbox (Use with Caution)

When your environment already has process-level isolation, you can disable the Codex sandbox:

Inworkspace-writeIn mode, some environments will.git/and.codex/Keep read-only. This meansgit commitCommands such as ... still require approval when executed outside the sandbox. To commit directly inside the sandbox, userulesExplicitly allow.

Shell Environment Variable Policy

shell_environment_policyControls which environment variables Codex passes through when launching subprocesses.Default targetis "leaking fewer secrets + preserving the paths needed for the task."

Pattern syntax: case-insensitive glob,*Matches any character,?Matches a single character,[A-Z]Is a character class.

ignore_default_excludes = falseIt will preserve Codex's built-in KEY/SECRET/TOKEN filters, taking effect before include/exclude.

MCP Servers

MCP (Model Context Protocol) servers allow Codex to connect to external tool sets.

For complete MCP configuration instructions, see the officialMCP documentation, not expanded in this article. Common patterns:

Observability and Telemetry (OTel)

Codex supports exporting runtime logs via OpenTelemetry, disabled by default. How to enable:

Choosing an HTTP Exporter

Choosing a gRPC Exporter

Exported Event Types

Codex emits structured events, including but not limited to:

Whenexporter = "none"When ..., Codex still records events in memory but does not send them.When closed, it still triggers asynchronous batch per event, flush on process exit.

Anonymous Metrics (Enabled by Default)

By default, Codex periodically reports a small amount of anonymous usage and health data to detect anomalies.Does not contain PII。

To completely disable:

Hiding and Showing Reasoning Events

In CI logs, reasoning output is often "noisy" and can be globally disabled:

Conversely, when you need to view the model's raw reasoning content:

Only enable it when you have confirmed that your workflow allows exposing raw reasoning. Some models (such asgpt-oss) do not output raw reasoning themselves; in that case, this setting has no effect.

External Notifications (notify)

When Codex completes a turn, it can trigger external scripts to implement desktop notifications, chat webhooks, CI status updates, etc.

The script receives a JSON argument; common fields:

A simple script example that calls terminal-notifier:

Difference Between notify and tui.notifications

autoIn this mode, Codex prefers the OSC 9 terminal escape sequence; some terminals treat it as a desktop notification; when unsupported, it falls back to BEL (\x07）。

Feedback and History

Disable Feedback Collection

By default, Codex is provided in the TUI./feedbackcommand. To disable:

After closing/feedbackwill display a disabled message, and Codex refuses to submit feedback.

History Records (history.jsonl)

By default, Codex writes local session transcripts to~/.codex/history.jsonlHow to disable:

Limits file size (when exceeded, drops the oldest entries and compresses):

Clickable Citations

When the terminal or editor supports it, Codex can render file references as clickable links.

After setting, reference/home/example/project/main.py:42Will be rewritten asvscode://file/.../main.py:42, and clicking in VS Code will jump to that location.

Project Instruction Discovery (AGENTS.md)

Codex will readAGENTS.md(and related files), automatically bring project conventions into the "first turn" of the session.

Two core knobs:

Terminal User Interface (TUI) Options

RuncodexRunning without a subcommand enters the interactive TUI.[tui]Common keys under the table:

Common Configuration Quick Reference Table

Treat this section as a "look it up when you forget" quick-reference checklist:

Frequently Asked Questions

The model_provider set in project-level configuration is not taking effect?

For security reasons,model_provider、model_providers、profile、notifyand other sensitive keysWill be ignored in the project-level .codex/config.toml, and prints a warning at startup.

Move these keys to user level~/.codex/config.tomlJust in it.

Changes written with --config have no effect?

Check three things: whether the value conforms to TOML syntax (arrays use[], strings use"", nesting uses dots); whether the shell split multiple values by treating spaces as separators; whether key names are spelled correctly. Open~/.codex/logs/Under the latest logs, you can see the original string that failed to parse.

Still the default model after launching with a Profile?

Most common cause: the Profile file is still using the old[profiles.<name>]table, or the filename suffix is not.config.toml. Starting from 0.134.0, only ... is recognized~/.codex/<name>.config.tomlformat.

Why is git commit still subject to approval after the sandbox is disabled?

Closesandbox_modedoes not affect approval policy.git commitand other commands may still becauseapproval_policy = "on-request"and triggers a prompt; if you want "fully automatic commits", you need to also set the approval policy tonever。

Can custom models select the gpt-5 series?

Depends onbase_urlwhether the service it points to supports it. Codex itself does notmodelstrictly validate the field; the key is whether your provider side can recognize and respond to it.