Configure repository work by separating standing settings, trusted project overrides, execution boundaries, reviewed hooks, and MCP registrations; one TOML file is not the whole control plane. Use Codex config.toml for persistent and project settings through its configuration basics, while treating the sandbox and approval policy as separate controls in Agent approvals & security. Install the CLI with npm through the Codex CLI documentation, require exact hook definitions to be reviewed through Hooks, and register MCP servers through the MCP documentation.
Install Codex CLI and place the files
The documented installation command is:
npm install -g @openai/codex
That is the complete installation instruction supplied by the Codex CLI documentation; it does not establish a prerequisite npm version or installation profile that you should assume across environments.
Use these paths for the two configuration scopes:
~/.codex/config.toml
.codex/config.toml
The user-level file at ~/.codex/config.toml holds configuration that should apply across your Codex work. A .codex/config.toml file inside a repository scopes settings to that project or subfolder. Codex loads project .codex/ layers only when the project is trusted, so placing a file in the repository is not enough by itself (Config basics).
Repository instructions have a separate path. Codex reads AGENTS.md before doing work and can layer global guidance with project-specific overrides, making that file the place for repository expectations that should reach the agent before implementation starts (Custom instructions with AGENTS.md).
Our operating practice is separate from Codex behavior: we keep one short startup instructions file as the routing entry point. It says what to do, how completion is checked, and which detailed document owns each rule. That avoids copying the same rule into several files until they disagree.
Build the Codex config.toml layer
Configuration precedence determines which value wins. CLI flags and --config overrides have the highest precedence. Project files are then considered from the project root down to the current working directory, with the closest file taking priority; these project layers apply only in trusted projects (Config basics).
That order gives you a practical debugging sequence:
- Check whether a CLI flag or
--configoverride is replacing the repository value. - Start from the directory in which Codex will actually run; the nearest project layer matters.
- Check project trust before assuming a
.codex/config.tomlfile participated. - Move standing preferences into
~/.codex/config.tomlrather than copying them into every checkout.
A repository file can look correct and still have no effect because it is untrusted, shadowed by a nearer layer, or overridden at invocation. Check those boundaries before rewriting the setting itself.
Set the sandbox and approval policy
Codex separates sandbox mode from approval policy. The sandbox controls what commands can technically do, including where they can write and whether they can reach the network. The approval policy controls when Codex must ask before acting (Agent approvals & security).
The documented Auto preset is:
--sandbox workspace-write --ask-for-approval on-request
With that preset, Codex reads files, edits files, and runs commands in the working directory without asking. It asks for approval before editing outside the workspace or running commands that require network access (Agent approvals & security).
The default workspace-write sandbox keeps network access off. Enable it in the applicable configuration layer with:
[sandbox_workspace_write]
network_access = true
If this belongs to a repository-scoped .codex/config.toml, the project must be trusted for that layer to load (Agent approvals & security; Config basics).
Writable workspace roots do not make every path writable. In the default policy, .git, .agents, and .codex directories inside writable roots are protected as read-only, recursively. If .git is a pointer file, its resolved Git directory is protected too. A repository task that needs to edit these paths therefore needs a different, deliberate operating boundary rather than an assumption that workspace-write permits it (Agent approvals & security).
Approval prompts can be disabled independently:
--ask-for-approval never
-a never
These options work with every sandbox mode, so suppressing prompts does not itself remove sandbox constraints. The broader flags are different:
--sandbox danger-full-access
--dangerously-bypass-approvals-and-sandbox
Those modes provide edits, commands, and network access without approval prompts. The documentation explicitly advises caution before using them (Agent approvals & security). For routine repository work, keep the sandbox and approval decision visible rather than making “no prompts” the only configuration goal.
Configure hooks
Codex discovers hooks beside active configuration layers. It accepts either a hooks.json file:
hooks.json
or inline hook tables in config.toml:
[hooks]
These are the two supported forms, not complete hook definitions. The event fields and command structure must come from the current Hooks documentation.
A non-managed hook does not run merely because its file is present. You must review and trust the exact definition. Codex records trust against the hook’s hash, so editing a trusted hook makes the changed definition subject to review again and skips it until you trust the new version (Hooks).
This makes hook verification part of repository configuration, not an afterthought. Review the command, inputs, working directory, and expected event before trusting it. If the hook definition is not documented in enough detail, do not invent a schema; check the current Hooks page.
Configure MCP servers
Codex stores MCP configuration alongside its other settings in config.toml. The default location is ~/.codex/config.toml; a trusted repository can use .codex/config.toml for project-scoped servers (Model Context Protocol).
The documentation provides this CLI example for adding a server:
codex mcp add context7 -- npx -y @upstash/context7-mcp
For an MCP server entry, the documented timeout fields are:
startup_timeout_sec = 10
tool_timeout_sec = 60
These lines belong inside the relevant server entry and are not a complete server definition. startup_timeout_sec controls how long the server has to start and defaults to 10 seconds. tool_timeout_sec controls how long the server has to run a tool and defaults to 60 seconds (Model Context Protocol). Keep the defaults visible when diagnosing startup or tool failures; change them only after identifying which boundary the server reaches.
Check it worked
Check the configuration from the working directory where Codex will run, not from a convenient directory elsewhere.
- Configuration scope: Confirm that the intended
.codex/config.tomlbelongs to a trusted project. If its value has no effect, compare CLI flags and--configoverrides, then look for a nearer project layer (Config basics). - Sandbox behavior: Use the Auto preset for a harmless repository task. In-workspace reads, edits, and commands should proceed without approval, while an out-of-workspace edit or network command should request approval (Agent approvals & security).
- Protected paths: Review whether the task expects changes under
.git,.agents, or.codex. Those paths remain recursively read-only in the default workspace-write policy (Agent approvals & security). - Hook trust: Confirm that the exact current definition—not an earlier revision—has been reviewed and trusted. A changed hash is skipped until that review is complete (Hooks).
- MCP registration: Run:
codex mcp list
The command shows configured servers (Model Context Protocol). Then exercise the intended server with a harmless task and inspect the returned result. Registration alone does not prove that the server starts or that its tool completes.
The documentation does not settle a universal merged-configuration dump command here. Inspect the files, invocation, working directory, trust state, and resulting behavior separately.
In our setup, done means checked. An agent summary or successful exit is a signal, not proof; we read the result from where a user would see it before accepting the work.
Where it breaks
- The repository file appears to be ignored. Check project trust first, then CLI flags and
--configoverrides, followed by the project layer nearest the current working directory (Config basics). - Workspace edits work but network work stops. The default
workspace-writesandbox leaves network access off unless[sandbox_workspace_write]containsnetwork_access = true(Agent approvals & security). - The agent cannot update Git metadata or protected directories. Treat
.git,.agents, and.codexas recursively read-only under the default policy rather than retrying the same write (Agent approvals & security). - A hook stops after an edit. Its hash changed, so Codex requires the new definition to be reviewed and trusted before it runs (Hooks).
- An MCP server is listed but is not usable. Distinguish server startup from tool execution, then check the applicable documented timeout field instead of increasing both blindly (Model Context Protocol).
- Prompts disappear but restrictions remain.
--ask-for-approval neverand-a neverdisable prompts while retaining the selected sandbox. The danger-full-access and bypass flags remove the sandbox boundary as well (Agent approvals & security).
A separate shared-tree failure mode: in our setup, many agent sessions can share one working directory, so uncommitted changes belong to every session. We once had an agent run a plain commit that picked up files another session had staged. Our rule is that an agent commits only its own lines; in a shared tree, the sanctioned process builds the commit through a temporary index from HEAD using read-tree, update-index, write-tree, commit-tree, and update-ref, then resets the real index for those paths. A path argument is not enough when the working copy also contains another session’s edits. This is an operating rule, separate from Codex’s sandbox protection for Git metadata.