Config Studio for Codex

Where it lives

The documentation does not say which of these wins when two of them disagree, so this page does not guess.

1. /etc/codex/requirements.toml

   enterpriseManaged hooks; trusted automatically.

2. ~/.codex/hooks.json

   userOr [hooks] in ~/.codex/config.toml.

3. ./.codex/hooks.json

   projectOr [hooks] in .codex/config.toml. Only when the project is trusted.

16 keys

hooks.SessionStartarray

A session starts, resumes, is cleared or compacted. Matcher: startup, resume, clear, compact.

hooks.UserPromptSubmitarray

You send a prompt. Exit 2 or decision block stops it.

hooks.PreToolUsearray

Before a tool runs. Matcher: the tool name (Bash, apply_patch, an MCP tool). Can deny or rewrite the input.

hooks.PermissionRequestarray

Codex is about to ask you. The hook can answer allow or deny instead.

hooks.PostToolUsearray

After a tool ran. Can add context or block the turn; it cannot undo the tool.

hooks.PreCompactarray

Before the context is compacted. Matcher: manual or auto.

hooks.PostCompactarray

After a compaction.

hooks.SubagentStartarray

A subagent starts. Matcher: its agent type.

hooks.SubagentStoparray

A subagent finishes. Block to send it round again.

hooks.Stoparray

Codex is about to stop. Block with a reason to make it carry on.

hooks.Interruptarray

You interrupted a turn. Timeout 1 s by default, 3 at most.

hooks.SessionEndarray

The session ends. Timeout 1 s by default, 3 at most.

hooks[].hooks[].timeoutnumber

Seconds; 600 by default.

hooks[].hooks[].asyncboolean

Runs in the background without holding the turn.

features.hooksboolean

Hooks are on by default; false turns them off.

/hooksstring

Review and trust new or changed hooks; a hook does not run until trusted.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   ./AGENTS.override.mdwins

   projectPer folder from the project root down: AGENTS.override.md, then AGENTS.md, then fallback names; one file a folder.

2. 2

   ./AGENTS.md

   projectThe files are joined root first, so the one nearest your working folder comes last and counts most.

3. 3

   ~/.codex/AGENTS.override.md

   userRead instead of AGENTS.md when it exists. Only the first non-empty file at this level is used.

4. 4

   ~/.codex/AGENTS.md

   userYours, in every project.

2 keys

project_doc_max_bytesnumber

The ceiling on all the files together, 32 KiB by default; past it, the rest is not read.

project_doc_fallback_filenamesarray

Other names to read in a folder without AGENTS.md.

Where it lives

The documentation does not say which of these wins when two of them disagree, so this page does not guess.

1. /etc/codex/skills/<name>/SKILL.md

   enterpriseAdmin skills for everyone on the machine.

2. ./.agents/skills/<name>/SKILL.md

   projectEvery .agents/skills from where you are up to the repository root.

3. ~/.agents/skills/<name>/SKILL.md

   userYours, in every repository.

5 keys

namestring

Front matter: the skill’s name, and the $name you call it by.

descriptionstring

Front matter: when to use it. Codex picks skills by this line, so it decides whether yours is ever used.

agents/openai.yaml policy.allow_implicit_invocationboolean

false: only $name starts it; true by default.

[[skills.config]] path, enabledarray

Turn a skill off in config.toml without deleting it.

skills.max_context_tokensnumber

The budget for the list of skills, 2% of the context window by default.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

10 keys

modelstring

Which model answers.

model_reasoning_effortenum

How hard the model thinks; levels depend on the model.

plan_mode_reasoning_effortstring

The effort used in plan mode.

personalityenum

Communication style: none, friendly or pragmatic.

web_searchenum

disabled, cached (default), indexed or live.

developer_instructionsstring

Extra developer instructions added to every session.

model_auto_compact_token_limitnumber

The token count at which the context is compacted.

project_doc_max_bytesnumber

The most bytes of AGENTS.md read, 32 KiB by default.

project_doc_fallback_filenamesarray

Other file names read like AGENTS.md.

CODEX_HOMEstring

An environment variable that moves ~/.codex somewhere else.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

6 keys

approval_policyenum

on-request, never, or a { granular = {...} } table. "untrusted" is retired.

• on-request Asks before leaving the sandbox.
• never Never asks.
• granular Choose which prompts may appear.

approvals_reviewerenum

user or auto_review.

sandbox_modeenum

read-only, workspace-write or danger-full-access.

sandbox_workspace_write.network_accessboolean

Network for sandboxed commands; off by default.

sandbox_workspace_write.writable_rootsarray

Extra writable folders.

windows.sandboxenum

elevated, unelevated or mxc on native Windows.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

7 keys

default_permissionsstring

The profile sessions use: :read-only, :workspace, :danger-full-access or a name of yours.

permissions.<name>.extendsstring

A built-in or another profile to start from; not :danger-full-access.

permissions.<name>.filesystem.":workspace_roots".<path>enum

read, write or deny inside every workspace root; globs allowed for deny.

permissions.<name>.workspace_roots.<path>boolean

Extra folders that count as workspace roots.

permissions.<name>.network.enabledboolean

Network for commands under this profile.

permissions.<name>.network.domains.<pattern>enum

allow or deny a host; *.x is subdomains, **.x includes x; deny wins.

features.network_proxyboolean

Starts the proxy that enforces the domain rules.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

13 keys

mcp_servers.<id>.commandstring

Launcher command, for a stdio server.

mcp_servers.<id>.argsarray

Arguments passed to that command.

mcp_servers.<id>.envobject

Environment for the server process.

mcp_servers.<id>.urlstring

Endpoint, for a streamable HTTP server.

mcp_servers.<id>.bearer_token_env_varstring

The environment variable the bearer token is read from.

mcp_servers.<id>.enabledboolean

Turn one off without removing it.

mcp_servers.<id>.requiredboolean

Fail startup if the server cannot initialise.

mcp_servers.<id>.startup_timeout_secnumber

Startup timeout, 10 seconds by default.

mcp_servers.<id>.tool_timeout_secnumber

Per-tool timeout, 60 seconds by default.

mcp_servers.<id>.enabled_toolsarray

An allowlist of tool names.

mcp_servers.<id>.disabled_toolsarray

A denylist, applied after the allowlist.

mcp_servers.<id>.default_tools_approval_modeenum

auto, prompt, writes or approve.

codex mcp add / list / loginstring

The subcommand that manages servers from the terminal.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   ./.codex/agents/<name>.tomlwins

   projectThis repository’s agents.

2. 2

   ~/.codex/agents/<name>.toml

   userYours, everywhere. A name that matches a built-in (default, worker, explorer) replaces it.

7 keys

namestring

The agent’s name; the file name does not matter.

descriptionstring

When Codex should use it.

developer_instructionsstring

Its instructions.

agents.max_concurrent_threads_per_sessionnumber

How many spawned agents may be open at once.

agents.default_subagent_modelstring

The default model for spawned agents.

agents.default_subagent_reasoning_effortstring

Their default reasoning effort.

agents.enabledboolean

false turns the multi-agent tools off.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

4 keys

agents.max_concurrent_threads_per_sessionnumber

Caps spawned agents running together, not counting the main one. Unset, Codex chooses.

agents.default_subagent_modelstring

Spawned agents use this unless the spawn or the agent file says otherwise. A cheaper model here saves your limits.

agents.default_subagent_reasoning_effortstring

The effort spawned agents use unless told otherwise.

agents.enabledboolean

Off removes the tools that spawn and wait for agents.

Where it lives

1. ~/.codex/<name>.config.toml

   userSince 0.134.0 a [profiles.<name>] table in config.toml is not read, nor the profile = selector.

2 keys

--profile <name>, -pstring

Layers $CODEX_HOME/<name>.config.toml over ~/.codex/config.toml.

-p, --profile <CONFIG_PROFILE_V2>stringfrom the binary

Layer $CODEX_HOME/<name>.config.toml on top of the base user config.

Where it lives

1. ~/.codex/config.toml

   user[tui] status_line, status_line_use_colors and terminal_title. /statusline and /title in Codex edit the same keys.

Where it lives

1. ~/.codex/config.toml

   user[tui] and the top-level notify.

13 keys

tui.themestring

The highlighting theme, kebab-case. Preview them with /theme; your own .tmTheme files go in ~/.codex/themes.

tui.notificationsboolean

Tells you when a turn finishes or Codex needs approval.

tui.notification_conditionstring

Only when the terminal is in the background, or always.

tui.notification_methodstring

OSC 9 for terminals that show it as a notification, BEL for a bell.

notifyarray

notify: a program and its arguments, one per line. Codex runs it with a JSON event added as the last argument.

tui.alternate_screenstring

Never keeps the conversation in your scrollback; auto skips it in Zellij.

tui.animationsboolean

Off for a still screen; on by default.

tui.show_tooltipsboolean

The onboarding tips; on by default.

tui.vim_mode_defaultboolean

Opens the prompt box in Vim normal mode.

tui.mouse_scroll_speednumber

Rows the transcript scrolls per wheel step: 1.0 by default, 0.5 for half as fast, 2 for twice. Above 0.

tui.resume_cwdstring

Whether a resumed session works where you are or where it was.

disable_paste_burstboolean

Codex treats a burst of typing as a paste; turn it off if that misfires in your terminal.

tui.keymap.<context>.<action>string

Rebinds a key in the TUI.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

6 keys

shell_environment_policy.inheritenum

Which of your environment variables commands see: all, a core set (HOME, PATH and the like), or none.

shell_environment_policy.ignore_default_excludesboolean

Off drops variables whose names contain KEY, SECRET or TOKEN before commands see them.

shell_environment_policy.excludearray

Name patterns to remove, one per line.

shell_environment_policy.setobject

KEY=value lines every command gets.

shell_environment_policy.experimental_use_profileboolean

Runs commands with your shell profile, so aliases and PATH changes there apply.

allow_login_shellboolean

Whether shell tools may start a login shell; true by default.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmin requirements: values a user cannot pick. On Windows %ProgramData%\OpenAI\Codex\requirements.toml.

2. 2

   codex -c key=value

   sessionA flag or -c override, for one run.

3. 3

   ./.codex/config.toml

   projectEvery .codex/config.toml from the project root down to where you are; the closest wins. Read only when the project is trusted.

4. 4

   ~/.codex/<name>.config.toml

   userA profile, only when you run codex --profile <name>. Above your config.toml, below the project.

5. 5

   ~/.codex/config.toml

   userYours. $CODEX_HOME moves the whole ~/.codex folder.

16 keys

features.hooksboolean

Lifecycle hooks; on unless set to false.

features.multi_agentboolean

The tools that spawn and manage agents; on by default.

features.memoriesboolean

Codex keeps notes from past threads and uses them later; off by default.

features.fast_modeboolean

Lets you pick the Fast tier with /fast; on by default.

features.goalsboolean

Persisted goals for a thread; on by default.

features.shell_snapshotboolean

Snapshots your shell environment so commands start faster; on by default.

features.unified_execboolean

The PTY-backed exec tool; on by default except on Windows.

features.appsboolean

Connected apps (connectors); on by default.

features.prevent_idle_sleepboolean

Stops sleep while a turn runs; off by default.

features.personalityboolean

The communication style choice; on by default.

memories.use_memoriesboolean

Puts what Codex remembered into new sessions; true by default.

memories.generate_memoriesboolean

Lets finished threads become memories; true by default.

memories.max_rollout_age_daysnumber

Older threads are not used; 30 by default.

memories.min_rollout_idle_hoursnumber

A thread must be idle this long before it is learned from; 6 by default.

memories.min_rate_limit_remaining_percentnumber

Skips learning when your usage limit is lower; 25 by default.

--enable <feature>, --disable <feature>stringfrom the binary

The same switch for one run.

Where it lives

1. ~/.codex/config.toml

   userProvider and auth keys are machine-local: a project file cannot override them.

8 keys

model_providerstring

The provider id to use; openai by default.

model_providers.<id>.base_urlstring

The API base URL.

model_providers.<id>.env_keystring

The environment variable holding its API key.

model_providers.<id>.wire_apienum

The protocol; responses.

model_providers.<id>.http_headersobject

Static headers.

model_providers.<id>.capabilities.external_web_accessboolean

Whether its hosted web search may reach the live web; unset keeps the provider default.

model_providers.<id>.capabilities.remote_compactionenum

unsupported (Codex compacts locally) or v2 (the provider compacts over the Responses endpoint); unset keeps the provider default.

oss_providerenum

lmstudio or ollama, the default for --oss.

Where it lives

1. ~/.codex/config.toml

   userTelemetry routing is machine-local: a project cannot change it.

8 keys

history.persistencestring

save-all keeps ~/.codex/history.jsonl; none keeps nothing. Session files in ~/.codex/sessions are separate.

history.max_bytesnumber

Drops the oldest entries past this size.

otel.exporterstring

Exports events (prompts sent, tool decisions and results, API requests) to your collector. none records and sends nothing.

otel.environmentstring

A tag on every event, dev by default.

otel.log_user_promptboolean

Off keeps the text of your prompts out of the export; only their length is sent.

analytics.enabledboolean

Off stops the small anonymous usage and health metrics Codex sends by default.

feedback.enabledboolean

Off removes /feedback.

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonlstring

One file per session: every turn, token count and tool call. Older ones are compressed to .jsonl.zst.

Where it lives

1. ~/.codex/config.toml

   user[projects."<path>"] trust_level. Codex asks the first time you open a folder.

1 key

projects."<path>".trust_levelenum

trusted or untrusted.

• trusted Loads the project’s .codex/ config, hooks and rules.
• untrusted Skips them; replaces the retired approval_policy = "untrusted".

Where it lives

1. 1

   /etc/codex/requirements.toml

   enterprisemacOS and Linux. Windows: %ProgramData%\OpenAI\Codex\requirements.toml. Cloud and MDM requirements layer above it.

9 keys

allowed_approval_policiesarray

One per line. Leaving out never blocks --ask-for-approval never. untrusted here keeps the stricter approvals of untrusted projects.

allowed_sandbox_modesarray

For setups that still use sandbox_mode. Leaving out danger-full-access blocks --yolo.

allowed_permission_profilesarray

Once set, every profile not listed is denied, built-ins and future ones included. Prefer this to sandbox modes from 0.138.0.

default_permissionsstring

The profile sessions start with.

allowed_web_search_modesarray

Leaving out live keeps sessions off live web pages.

allowed_approvals_reviewersarray

user, auto_review, or both.

allow_managed_hooks_onlyboolean

User and project hooks stop running; only hooks from requirements do.

features.memoriesboolean

Pins Memories on or off for everyone.

features.multi_agentboolean

Pins multi-agent on or off for everyone.

Where it lives

1. codex [flags]

   sessionthis run only

10 keys

-m, --model <MODEL>string

Model the agent should use.

-p, --profile <CONFIG_PROFILE_V2>string

Layer $CODEX_HOME/<name>.config.toml on top of the base user config.

-a, --ask-for-approval <APPROVAL_POLICY>string

Configure when the model requires human approval before executing a command.

• on-request
• never

-s, --sandbox <SANDBOX_MODE>string

Select the sandbox policy to use when executing model-generated shell commands.

• read-only
• workspace-write
• danger-full-access

--add-dir <DIR>string

Additional directories that should be writable alongside the primary workspace.

-C, --cd <DIR>string

Tell the agent to use the specified directory as its working root.

--searchstring

Enable live web search. When enabled, the native Responses `web_search` tool is available to the model (no per‑call approval).

-c, --config <key=value>string

Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`. Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed as TOML. If it fails to parse as TOML, the raw string is used as a literal. Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c shell_environment_policy.inherit=all`.

--dangerously-bypass-approvals-and-sandboxstring

Skip all confirmation prompts and execute commands without sandboxing. EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed.

--ossstring

Use open-source provider.

Where it lives

1. codex exec

   sessionthis run only

6 keys

codex exec [PROMPT]string

Runs one prompt and exits; also codex e.

--jsonboolean

Machine-readable progress, one JSON event a line.

--output-last-message <file>string

Writes the final answer to a file.

-m, --model <MODEL>stringfrom the binary

Model the agent should use.

-s, --sandbox <SANDBOX_MODE>stringfrom the binary

Select the sandbox policy to use when executing model-generated shell commands.

• read-only
• workspace-write
• danger-full-access

-p, --profile <CONFIG_PROFILE_V2>stringfrom the binary

Layer $CODEX_HOME/<name>.config.toml on top of the base user config.

Where it lives

Listed in order of precedence: the top one wins when two disagree.

1. 1

   /etc/codex/requirements.tomlwins

   enterpriseAdmins can enforce restrictive prefix rules from requirements.

2. 2

   ./.codex/rules/*.rules

   projectRead only when the project is trusted.

3. 3

   ~/.codex/rules/default.rules

   userWhere Codex writes a command you allow for good from the approval prompt.

3 keys

prefix_rule(pattern, decision, justification, match, not_match)object

One rule in Starlark: a command prefix and what happens when a command starts with it.

decisionenum

allow, prompt or forbidden; the strictest match wins.

• allow Runs outside the sandbox without asking.
• prompt Asks every time.
• forbidden Refused without asking.

codex execpolicy check --pretty --rules <file> -- <command>string

Tests which decision a command gets.