Codex: Codex Configuration & Customization
Last updated: 2026-08-31
Codex offers rich configuration options — from basic API settings to advanced approval policies and sandbox configurations, everything can be customized to your needs.
📋 Prerequisites: Codex installed and basic usage completed
1. What You Will Learn
- Configuration file locations and structure
- Basic configuration items
- Advanced configuration options
- Project-level vs global configuration
2. Configuration File Locations
| Config Type | Path | Scope |
|---|---|---|
| Global config | ~/.codex/config.toml |
All projects |
| Auth config | ~/.codex/auth.json |
API Keys, etc. |
| Project config | .codex/config.toml |
Current project |
| AGENTS.md | AGENTS.md |
Project rules and context |
3. Global Configuration config.toml
(1) Basic Configuration
TOML
# ~/.codex/config.toml
# Model settings
model = "gpt-5-codex"
# Approval policy: ask / approve / deny
approval_policy = "ask"
# Sandbox mode: readonly / workspace-write / full-access
sandbox_mode = "workspace-write"
# Context window size (tokens)
context_window = 128000
(2) Auth Configuration auth.json
JSON
{
"OPENAI_API_KEY": "sk-your-api-key",
"OPENAI_BASE_URL": "https://api.openai.com/v1"
}
▶ Example 1: Alice's Configuration
TOML
# Alice's global config
model = "gpt-5-codex"
approval_policy = "ask"
sandbox_mode = "workspace-write"
# Custom prompt prefix
system_prompt_prefix = """
You are a senior full-stack engineer, proficient in TypeScript and Python.
Code style guidelines:
- Use type annotations
- Functions no longer than 50 lines
- Every function has a docstring
"""
4. Advanced Configuration
(1) Approval Policy Details
| Policy | Behavior | Use Case |
|---|---|---|
ask |
Confirm each sensitive operation | Daily development (default) |
approve |
Auto-approve all operations | Trusted automation scenarios |
deny |
Deny all sensitive operations | Read-only review |
TOML
# Per-operation-type approval settings
[approval]
shell_commands = "ask" # shell commands need confirmation
file_writes = "approve" # file writes auto-approved
network_access = "deny" # deny network access
sensitive_paths = "ask" # sensitive paths need confirmation
(2) Sandbox Configuration
TOML
# Sandbox mode
[sandbox]
mode = "workspace-write" # Only allow writes within workspace
allowed_paths = ["src/", "test/"] # Restrict writable paths
blocked_paths = [".env", "secrets/"] # Blocked access paths
network = false # Deny network access
(3) Context Management
TOML
[context]
auto_compact = true # Auto-compress context
compact_threshold = 0.8 # Trigger compression at 80% usage
max_file_size = "100KB" # Max single file read size
include_patterns = ["*.py", "*.ts", "*.js"] # Include file patterns
exclude_patterns = ["node_modules/", ".git/"] # Exclude patterns
5. Project-Level Configuration
Create .codex/config.toml in the project root to override global settings:
TOML
# .codex/config.toml (project-level)
# Project-specific model
model = "deepseek-coder"
# Project-specific approval policy
approval_policy = "approve"
# Project-specific sandbox
[sandbox]
allowed_paths = ["src/", "tests/"]
blocked_paths = ["production/", "secrets/"]
▶ Example 2: Bob's Project Configuration
TOML
# Bob's frontend project config
# .codex/config.toml
model = "gpt-5-codex"
approval_policy = "ask"
[context]
include_patterns = ["*.tsx", "*.ts", "*.css"]
exclude_patterns = ["node_modules/", "dist/", ".next/"]
[sandbox]
allowed_paths = ["src/", "public/", "styles/"]
blocked_paths = [".env.local", ".env.production"]
6. AGENTS.md Project Rules
AGENTS.md is a project-level rules file placed in the project root. Codex reads it automatically:
MARKDOWN
# AGENTS.md
## Project Rules
- Use TypeScript strict mode
- All API endpoints must have input validation
- Test coverage no less than 80%
- Run npm run lint before committing
## Code Style
- Use functional components
- Naming: camelCase
- Files: kebab-case
## Prohibited Operations
- Do not modify .env files
- Do not delete test files
- Do not install new dependencies (requires manual confirmation)
7. Environment Variable Configuration
| Variable | Description | Example |
|---|---|---|
OPENAI_API_KEY |
API key | sk-xxx |
OPENAI_BASE_URL |
API endpoint | https://api.deepseek.com |
CODEX_MODEL |
Default model | gpt-5-codex |
CODEX_SANDBOX |
Sandbox mode | workspace-write |
BASH
# Temporary override
CODEX_MODEL=deepseek-coder codex
8. Configuration Priority
TEXT
📖 Display only
CLI arguments > Environment variables > Project config > Global config > Defaults
▶ Example 3: Priority in Practice
BASH
# Global config: model = "gpt-5-codex"
# Project config: model = "deepseek-coder"
# Environment variable: CODEX_MODEL="gpt-4o"
# Final: gpt-4o (env var > project config > global config)
CODEX_MODEL="gpt-4o" codex
# CLI argument has highest priority
codex --model o3
# Final: o3
❓ FAQ
Q What if project and global configs conflict?
A Project config takes priority. Codex reads global config first, then overrides with project config.
Q What's the difference between AGENTS.md and config.toml?
A config.toml is technical configuration (model, sandbox, approval policy); AGENTS.md is natural language rules (code style, prohibited operations, project conventions). They complement each other.
Q Can I put API Keys in project config?
A Not recommended. API Keys should go in
~/.codex/auth.json or environment variables to avoid leaking into git repositories.Q How do I view the current effective configuration?
A Run
codex --show-config to see the merged complete configuration.Q What if I misconfigure something?
A Edit the config file directly, or delete it to restore defaults. Codex re-reads configuration on next startup.
📖 Summary
- Global config:
~/.codex/config.toml, project config:.codex/config.toml - Approval policies: ask / approve / deny
- Sandbox modes: readonly / workspace-write / full-access
- AGENTS.md defines project rules in natural language
- Configuration priority: CLI args > env vars > project > global > defaults
📝 Exercises
- Basic (⭐): Create a global config file and set the default model and approval policy.
- Intermediate (⭐⭐): Create project-level config and AGENTS.md for your project, defining code style and prohibited operations.
- Advanced (⭐⭐⭐): Design a multi-environment configuration scheme — DeepSeek for development, OpenAI for production-related tasks — with automatic switching.
