Config
Design Codex configuration layers, profiles, and safe defaults for team usage.
Key takeaways
- Configuration's job is to make the safe path the default path, not to expose every option.
- Layer config by owner: user defaults, repository rules, team policy, and admin policy that cannot be weakened locally.
- Define purpose-built profiles such as
default,review,automation, andrestrictedfor sensitive work. - On review, confirm explicit sandbox and approval defaults, gated high-risk tools, and a migration note whenever config changes.
- Validate named permission profiles with
codex sandbox -P <profile>, inspect effective modes via/debug-config, and include plugin marketplace JSON in supply-chain audits.
Configuration turns team preferences into repeatable behavior. The goal is not to expose every option; it is to make the safe path the default path.
Config Layers
| Layer | Purpose | Owner |
|---|---|---|
| User config | Personal defaults and editor preferences | Developer |
| Repository config | Project rules, commands, and context | Repo owner |
| Team config | Shared policy, model, and permission defaults | Engineering lead |
| Admin policy | Requirements that cannot be weakened locally | Platform or security |
Profile Design
| Profile | Use |
|---|---|
default | Normal development and documentation |
review | Read-heavy code review and analysis |
automation | Non-interactive commands with tight scope |
restricted | Sensitive repositories or production-adjacent work |
Review Checklist
- Are sandbox and approval defaults explicit?
- Are model and reasoning defaults appropriate for cost and quality?
- Are extra read directories intentionally allowed?
- Are high-risk tools disabled or gated?
- Is there a migration note when config changes?
- Can the team validate named permission profiles with
codex sandbox -P <profile>and inspect effective sandbox modes with/debug-config? - Are plugin marketplace JSON outputs included in config and supply-chain audits?
0.145.0 to 0.146.0 Plugin and Proxy Notes
- Include Agent Plugin manifests and workspace publishing in the supply-chain inventory, and re-check marketplace allowlists for additional Amazon Bedrock and Claude Code sources.
- Smoke-test
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYacross auth, plugins, MCP, remote/WebSocket hosts, redirects, and LM Studio rather than assuming one successful path covers all clients. - Remote Code Mode hosts and executor-provided skills/resources expand the effective tool surface;
capture
/plugins,/skills,/mcp, and/debug-configtogether.
0.147.0 to 0.148.0 Configuration Notes
- Migrate new model defaults to GPT-5.6 Sol or Terra, use Luna for explicit repeated work, and plan the ChatGPT-sign-in retirement of GPT-5.4 and GPT-5.4 mini on 2026-08-31.
- Portable Agent Plugins expand the catalog boundary across local, personal, workspace, and remote sources; record source, version, and trust state in supply-chain reviews.
- Codex 0.148.0 adds the built-in
amazon-bedrockprovider with AWS profile and region configuration:
model_provider = "amazon-bedrock"
[model_providers.amazon-bedrock.aws]
profile = "engineering"
region = "us-west-2"0.151.0 to 0.153.0 Configuration Notes
One default changed in this window, so check it before upgrading a team standard.
# 0.152.0: the planning tool is disabled by default. Enable it explicitly if you rely on it.
[tools.update_plan]
enabled = true
[tui]
# 0.153.0: turn off automatic recaps while keeping manual /recap
auto_recap = false
# 0.153.0: replaces the top-level disable_paste_burst, which still works as a fallback
disable_paste_burst = true
# 0.153.0: disabled-by-default experiment. For eligible ChatGPT Plus, Pro, and Pro Lite
# sessions on the Codex backend it enables token-budget context, history notes, and the
# new_context tool. API-key sessions, custom providers, and temporary structured threads
# are excluded.
[features.context_management]
experimental_mode = truetools.update_plan.enabled: from 0.152.0 the planning tool is off by default. Turn it on explicitly if a runbook depends on its output. This is separate from the/planslash command.- Per-tool MCP output limits: from 0.152.0 an individual MCP tool can set
output_token_limit, with consistent truncation across session resumes. - MCP server naming: from 0.152.0 names may contain
:,@,/, and., so package-style names work across CLI commands and authentication. - Optional MCP discovery grace: 0.151.0 makes the tool-discovery grace period for optional MCP servers configurable; separate required and optional server startup policy.
- App-server timeouts: from 0.152.0 clients can configure
thread/shellCommandtimeouts, including deadlines longer than one hour.