Configure Codex with config.toml

Back to the Codex learning hub

Goal and preparation

AGENTS.md instructs the agent; config.toml configures the client. Mentioning a model in ordinary Markdown does not change the configured default. Un-commented prose in TOML may make it invalid. Learn location, verification and restoration with one low-impact option before adding other settings you need.

Distinguish user and project configuration

User configuration normally lives at .codex/config.toml under your home directory; check an existing CODEX_HOME override if present. Project configuration is .codex/config.toml inside a repository and loads only for trusted projects. Same filename, different scope. This exercise creates only the lab's file, without moving authentication, changing user defaults or altering system environment variables.

Step 1: Record the starting state

Create a new codex-config-lab and note.txt with the line below. Verify the integrated terminal location using Get-Location in PowerShell or pwd on macOS/Linux, then run git init in this new lab to define the project root. Do not create project configuration yet. If that folder already belongs to another project, choose a new lab location instead of resetting it.

CONFIG-LAB-01

Start codex --cd . in the shell. For a trust prompt, verify it identifies the lab you just created. Inside interactive Codex, run the two slash commands separately; they are not shell commands. /debug-config shows configuration layers and enabled state, while /status checks session context. Record relevant paths/states without publishing full private diagnostics.

/debug-config

/status

If /debug-config is absent, inspect that version's / menu, use /exit to return to the shell and record codex --version. Update through its official installation source, restart CLI and check again. Do not invent a same-named shell command. If diagnostics remain insufficient, mark the effective setting unverified rather than relying on a model assurance. Save your baseline and use /exit.

Step 2: Add one reversible setting

Create .codex/config.toml through the project's file explorer. Verify it is inside .codex, not root config.toml or a .txt file. If it exists, make an identifiable backup, record the original value and modify the existing top-level web_search key without duplicating it. For a new lab file, use the complete sample below.

# Practice setting: disable the built-in web search tool.
web_search = "disabled"

Keep key/value spelling, use straight quotes for the string and # for comments. This is a top-level key: do not blindly append it below [features] or another table header, which changes subsequent key scope. Do not copy the website's surrounding backtick fence into the file. Save as UTF-8 plain text and recheck.

Step 3: Restart and identify the effective source

Launch a fresh codex --cd . from the lab without --search, -c or --profile overrides. Inspect /debug-config for an enabled project layer. If skipped as untrusted, verify the project's origin and follow the normal trust flow. Diagnostics may list layers from low to high precedence: read their labels and enabled state rather than treating the first row as the winner.

Compare effective settings or available-tool information with the file, then send the local-read request below. Expect CONFIG-LAB-01 and no search for this task; if the interface exposes the effective web_search value, it should be disabled. One task not searching proves only non-use, not successful configuration, so retain layer diagnostics as evidence.

Read note.txt from this practice project and report its exact line. Do not edit files, browse websites or call external services. If you cannot verify an effective setting from available diagnostics, say so rather than inferring it from the file alone.

This switch disables the built-in search tool, not every network path. Shell, browser, MCP and external services have their own permissions and settings; see permissions and sandboxing. This exercise neither starts services nor bypasses the setting through another network tool merely to demonstrate it.

Three meanings behind “no search occurred”

Worked case: A only sees disabled in the file; B also sees the project layer skipped as untrusted; C sees it enabled and the effective value disabled. None searched. A's effective value is unknown. B has a loading issue, not an applied project setting. C has diagnostic evidence for this setting, not proof that all network tools are blocked. Record file content, loaded state, effective value and task behavior separately; leave unsupported fields unverified.

Step 4: Restore and record the result

Exit CLI. If no file existed before, move the new config.toml outside the project's configuration directory as a backup. Otherwise restore only web_search's original value or remove only the newly added key. Restart and verify this override is gone and note.txt unchanged. The resulting search mode depends on remaining layers, not an assumed default.

File changed: codex-config-lab/.codex/config.toml
Original state: record whether the file/key existed.
Requested change: web_search = disabled
Loaded layer: record observed path and enabled/skipped state.
Effective value: record verified value, or unverified.
Local read: record actual note.txt result.
Restoration: record the restored file/key state and fresh-session check.

Troubleshooting and next steps

For startup failure, inspect the named TOML file/line for quotes, duplicate keys and table scope. For unchanged values, check path, trust, launch overrides and nearer project layers. For IDE/CLI disagreement, compare OS, user and directory, especially separate Windows and WSL homes. Diagnose the source before choosing reinstallation.

Enforced organization requirements differ from defaults; project keys cannot override forbidden values. Use model selection for models and reasoning rather than replacing provider/auth settings with a copied configuration bundle. Finish with baseline, enabled and restored records plus explicit unknowns. Continue to configuration troubleshooting. File syntax can be checked independently; valid TOML is not proof every client loaded it.

Back to the Codex learning hub

Read the full description

User config to Project config to CLI override

• AI tools
• Tutorials
• Codex