Codex Configuration Best Practices

Quick Start

Codex configuration lives at ~/.codex/config.toml. Create it if missing:

mkdir -p ~/.codex
touch ~/.codex/config.toml

Configuration File Structure

# ~/.codex/config.toml

# Default model (o4-mini is fast, o3 is most capable)
model = "o4-mini"

# Sandbox policy (see Sandbox section)
sandbox_policy = "workspace-write"

# Approval policy (see Approval section)
approval_policy = "on-failure"

# Shell environment
shell_environment_policy = "inherit"

# MCP servers (see MCP section)
[mcp_servers.my-server]
type = "sse"
url = "http://localhost:8080/sse"

Model Selection

Recommendation: Start with o4-mini, use o3 for complex multi-file changes.

# In config.toml
model = "o4-mini"

Override per-session:

codex -m o3 "complex refactoring task"

Sandbox Policies

Control what Codex can access on your system.

Recommendation: Use workspace-write for most work.

# In config.toml
sandbox_policy = "workspace-write"

Override per-session:

# Read-only for reviewing code
codex -s read-only

# Full access for system setup (use carefully)
codex -s danger-full-access

Approval Policies

Control when Codex asks before running commands.

Recommendation: Start with on-failure for balance.

# In config.toml
approval_policy = "on-failure"

Override per-session:

# Cautious mode
codex -a untrusted

# Autonomous mode
codex -a never

MCP Server Integration

Connect Codex to external tools via MCP (Model Context Protocol).

SSE Server (HTTP streaming)

[mcp_servers.my-api]
type = "sse"
url = "http://localhost:8080/sse"

Stdio Server (subprocess)

[mcp_servers.my-tool]
type = "stdio"
command = "npx"
args = ["-y", "@my-org/mcp-server"]

# Optional environment variables
[mcp_servers.my-tool.env]
API_KEY = "${MY_API_KEY}"

WebSocket Server

[mcp_servers.my-ws]
type = "websocket"
url = "ws://localhost:9000/ws"

Managing MCP Servers

# List connected servers
codex mcp list

# Add a server interactively
codex mcp add

# Remove a server
codex mcp remove my-server

Profiles

Create named profiles for different workflows:

# ~/.codex/profiles/review.toml
model = "o4-mini"
sandbox_policy = "read-only"
approval_policy = "never"

# ~/.codex/profiles/full-dev.toml
model = "o3"
sandbox_policy = "danger-full-access"
approval_policy = "on-failure"

Use a profile:

codex -p review "analyze this codebase"
codex -p full-dev "set up the project"

Local Models (OSS)

Use local models via LM Studio or Ollama:

# In config.toml (when using --oss flag)
local_provider = "lmstudio"  # or "ollama"

# Auto-detect local provider
codex --oss

# Explicit provider
codex --oss --local-provider ollama

Shell Environment

Control which shell variables Codex inherits:

# Options: "inherit", "explicit", "none"
shell_environment_policy = "inherit"

# When using "explicit", specify allowed vars
[shell_environment_variables]
PATH = true
HOME = true
EDITOR = true

Recommended Starter Config

# ~/.codex/config.toml

# Good defaults for most development work
model = "o4-mini"
sandbox_policy = "workspace-write"
approval_policy = "on-failure"
shell_environment_policy = "inherit"

# Optional: MCP servers
# [mcp_servers.my-server]
# type = "sse"
# url = "http://localhost:8080/sse"

Common Flags Reference

Troubleshooting

"Permission denied" errors:

• Check sandbox_policy - may need workspace-write or higher

"Model not found":

• Verify API key in environment or config
• Check model name spelling (o4-mini, not o4mini)

MCP server not connecting:

• Verify server is running: curl http://localhost:PORT/sse
• Check config.toml for typos in URL/command
• Run codex mcp list to see connection status