config.toml Design - Models, Approvals, Sandboxes, and Profiles

config.toml controls how Codex runs. AGENTS.md explains the working agreement, while config.toml sets models, approvals, sandboxes, MCP servers, Hooks, and Subagents.

Configuration layers

Common precedence, from highest to lowest, is:

1. CLI flags and --config
2. .codex/config.toml in trusted projects
3. A profile selected with --profile
4. ~/.codex/config.toml
5. System configuration such as /etc/codex/config.toml
6. Built-in defaults

Keep personal notifications and machine-specific settings in the user layer. Keep project approval and feature settings in the trusted project layer. Never commit credentials directly into project configuration.

Minimal example

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
hooks = true

This grants write access inside the workspace and asks for approval when broader access is needed. Model names and feature maturity change, so check the current official reference before adopting a value.

Separate Task Profiles

Research, implementation, and CI need different permissions. Create profile files under $CODEX_HOME, which defaults to ~/.codex, to avoid repeating many flags.

# ~/.codex/review.config.toml
sandbox_mode = "read-only"
approval_policy = "on-request"

# ~/.codex/implementation.config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Select the review profile with codex --profile review and the implementation profile with codex --profile implementation.

Respect the Trust Boundary

Codex skips project .codex/ layers when a project is not trusted. This prevents unreviewed project Hooks or configuration from running automatically.

After changing configuration, confirm that permissions are no broader than necessary, danger-full-access is not the default, secrets are absent, and Rules do not conflict with legacy sandbox settings.

Next, Rules file design controls specific command decisions.

See the references for the external specifications and background sources used on this page.[1][2]

References

1. OpenAI, Codex documentation
2. OpenAI, OpenAI API documentation