Skip to content
NLEN
← Apps overview

Codex: technical tutorial

By Ivo Donker · — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash)

Codex: ReviewInstall & set upNewsTechnical tutorial

As of September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation.

This tutorial picks up where installation leaves off. It covers config.toml, sandbox and approval policy, project instructions via AGENTS.md, MCP servers, profiles, your own proxy or gateway, and Codex in scripts and CI. Keys and flags have been checked against the official documentation (as of September 2026).

config.toml: where and in what order

A basic configuration:

model = "gpt-6-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Sandbox and approval

Codex has two controls that together determine what the agent may do independently.

sandbox_mode, the boundary at OS level:

approval_policy, when Codex asks you:

untrusted is no longer supported and on-failure is deprecated; do not use them in new configurations.

The sandbox uses Seatbelt on macOS, bubblewrap on Linux and WSL 2, and the native Windows sandbox in PowerShell. In September 2026, two escapes were closed: Heapjack (a host action from read-only without an approval prompt) and Overpatch (writing outside the working directory). Use at least CLI 0.149.0.

Project instructions with AGENTS.md

Codex builds up the instructions in this order:

  1. Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md.
  2. Project: from the repository root to your current directory. At each level, first AGENTS.override.md, otherwise AGENTS.md.
  3. Files closer to your current directory take precedence over earlier instructions.

Together, the files may be 32 KiB by default (project_doc_max_bytes); above that, Codex stops adding. If your instruction file has a different name, add the name:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

A practical pattern for monorepos: general conventions in the root AGENTS.md, and a short AGENTS.md per package with the specific build and test commands.

MCP servers

Adding a local server from the command line:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Or directly in config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.context7.env]
MY_ENV_VAR = "waarde"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

By default, Codex waits 10 seconds for a server to start (startup_timeout_sec) and 60 seconds per tool call (tool_timeout_sec). Servers that first need to download something via npx often need more startup time.

Profiles

A profile lets you switch quickly between settings, for example a lean profile for small jobs and a heavy profile for reviews. Since version 0.134.0, each profile is a separate file alongside your main configuration, containing only the values that differ. The old [profiles.x] table in config.toml is no longer supported.

~/.codex/deep-review.config.toml:

model = "gpt-6-astra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

To use:

codex --profile deep-review

A proxy or your own provider

Do you want all traffic to run through your own LLM proxy, for logging, cost monitoring or key management? Then put this in your user configuration:

openai_base_url = "https://proxy.example.com/v1"

For a separate provider, you define your own block and select it with model_provider:

model_provider = "mijnproxy"

[model_providers.mijnproxy]
name = "Eigen LLM-proxy"
base_url = "https://proxy.example.com/v1"
env_key = "MIJNPROXY_API_KEY"
wire_api = "responses"

env_key is the name of the environment variable containing the key, not the key itself. wire_api determines the API format: "responses" for the Responses API; without that line, Codex uses the Chat Completions format. Check which format your proxy passes through, because not every gateway supports both.

Codex in scripts and CI

codex exec runs without an interface and is intended for pipelines, pre-merge checks and scheduled tasks.

codex exec --sandbox workspace-write "Draai de tests en repareer wat faalt"

Useful flags:

An example that returns only a verdict:

CODEX_API_KEY="$CODEX_KEY" codex exec --sandbox read-only \
  --output-schema review-schema.json -o review.json \
  "Beoordeel de wijzigingen in deze branch op beveiligingsrisico's"

Be careful with keys in CI. OpenAI recommends passing CODEX_API_KEY only to the command itself, as above, and not as an environment variable for the whole job. Otherwise, code from the repository that you run in the same job can read the key.

Common problems

Documentation: learn.chatgpt.com/docs.