Configuration Reference

Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Config.

config.toml

User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files. Codex loads project-scoped config files only when you trust the project.

For sandbox and approval keys (approval_policy, sandbox_mode, and sandbox_workspace_write.*), pair this reference with Sandbox and approvals, Protected paths in writable roots, and Network access.

Key

agents.<name>.config_file

Type / Values

string (path)

Details

Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.

Key

agents.<name>.description

Type / Values

string

Details

Role guidance shown to Codex when choosing and spawning that agent type.

Key

agents.<name>.nickname_candidates

Type / Values

array<string>

Details

Optional pool of display nicknames for spawned agents in that role.

Key

agents.job_max_runtime_seconds

Type / Values

number

Details

Default per-worker timeout for spawn_agents_on_csv jobs. When unset, the tool falls back to 1800 seconds per worker.

Key

agents.max_depth

Type / Values

number

Details

Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

Key

agents.max_threads

Type / Values

number

Details

Maximum number of agent threads that can be open concurrently. Defaults to 6 when unset.

Key

allow_login_shell

Type / Values

boolean

Details

Allow shell-based tools to use login-shell semantics. Defaults to true; when false, login = true requests are rejected and omitted login defaults to non-login shells.

Key

analytics.enabled

Type / Values

boolean

Details

Enable or disable analytics for this machine/profile. When unset, the client default applies.

Key

approval_policy

Type / Values

untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }

Details

Controls when Codex pauses for approval before executing commands. You can also use approval_policy = { granular = { ... } } to allow or auto-reject specific prompt categories while keeping other prompts interactive. on-failure is deprecated; use on-request for interactive runs or never for non-interactive runs.

Key

approval_policy.granular.mcp_elicitations

Type / Values

boolean

Details

When true, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

Key

approval_policy.granular.request_permissions

Type / Values

boolean

Details

When true, prompts from the request_permissions tool are allowed to surface.

Key

approval_policy.granular.rules

Type / Values

boolean

Details

When true, approvals triggered by execpolicy prompt rules are allowed to surface.

Key

approval_policy.granular.sandbox_approval

Type / Values

boolean

Details

When true, sandbox escalation approval prompts are allowed to surface.

Key

approval_policy.granular.skill_approval

Type / Values

boolean

Details

When true, skill-script approval prompts are allowed to surface.

Key

approvals_reviewer

Type / Values

user | auto_review

Details

Who reviews eligible approval prompts under on-request or granular approval policies. Defaults to user; auto_review uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.

Key

apps._default.destructive_enabled

Type / Values

boolean

Details

Default allow/deny for app tools with destructive_hint = true.

Key

apps._default.enabled

Type / Values

boolean

Details

Default app enabled state for all apps unless overridden per app.

Key

apps._default.open_world_enabled

Type / Values

boolean

Details

Default allow/deny for app tools with open_world_hint = true.

Key

apps.<id>.default_tools_approval_mode

Type / Values

auto | prompt | approve

Details

Default approval behavior for tools in this app unless a per-tool override exists.

Key

apps.<id>.default_tools_enabled

Type / Values

boolean

Details

Default enabled state for tools in this app unless a per-tool override exists.

Key

apps.<id>.destructive_enabled

Type / Values

boolean

Details

Allow or block tools in this app that advertise destructive_hint = true.

Key

apps.<id>.enabled

Type / Values

boolean

Details

Enable or disable a specific app/connector by id (default: true).

Key

apps.<id>.open_world_enabled

Type / Values

boolean

Details

Allow or block tools in this app that advertise open_world_hint = true.

Key

apps.<id>.tools.<tool>.approval_mode

Type / Values

auto | prompt | approve

Details

Per-tool approval behavior override for a single app tool.

Key

apps.<id>.tools.<tool>.enabled

Type / Values

boolean

Details

Per-tool enabled override for an app tool (for example repos/list).

Key

auto_review.policy

Type / Values

string

Details

Local Markdown policy instructions for automatic review. Managed guardian_policy_config takes precedence. Blank values are ignored.

Key

background_terminal_max_timeout

Type / Values

number

Details

Maximum poll window in milliseconds for empty write_stdin polls (background terminal polling). Default: 300000 (5 minutes). Replaces the older background_terminal_timeout key.

Key

chatgpt_base_url

Type / Values

string

Details

Override the base URL used during the ChatGPT login flow.

Key

check_for_update_on_startup

Type / Values

boolean

Details

Check for Codex updates on startup (set to false only when updates are centrally managed).

Key

cli_auth_credentials_store

Type / Values

file | keyring | auto

Details

Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

Key

commit_attribution

Type / Values

string

Details

Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

Key

compact_prompt

Type / Values

string

Details

Inline override for the history compaction prompt.

Key

default_permissions

Type / Values

string

Details

Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are :read-only, :workspace, and :danger-no-sandbox; custom profile names require matching [permissions.<name>] tables.

Key

developer_instructions

Type / Values

string

Details

Additional developer instructions injected into the session (optional).

Key

disable_paste_burst

Type / Values

boolean

Details

Disable burst-paste detection in the TUI.

Key

experimental_compact_prompt_file

Type / Values

string (path)

Details

Load the compaction prompt override from a file (experimental).

Key

experimental_use_unified_exec_tool

Type / Values

boolean

Details

Legacy name for enabling unified exec; prefer [features].unified_exec or codex --enable unified_exec.

Key

features.apps

Type / Values

boolean

Details

Enable ChatGPT Apps/connectors support (experimental).

Key

features.codex_hooks

Type / Values

boolean

Details

Enable lifecycle hooks loaded from hooks.json or inline [hooks] config.

Key

features.enable_request_compression

Type / Values

boolean

Details

Compress streaming request bodies with zstd when supported (stable; on by default).

Key

features.fast_mode

Type / Values

boolean

Details

Enable Fast mode selection and the service_tier = "fast" path (stable; on by default).

Key

features.memories

Type / Values

boolean

Details

Enable Memories (off by default).

Key

features.multi_agent

Type / Values

boolean

Details

Enable multi-agent collaboration tools (spawn_agent, send_input, resume_agent, wait_agent, and close_agent) (stable; on by default).

Key

features.personality

Type / Values

boolean

Details

Enable personality selection controls (stable; on by default).

Key

features.prevent_idle_sleep

Type / Values

boolean

Details

Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

Key

features.shell_snapshot

Type / Values

boolean

Details

Snapshot shell environment to speed up repeated commands (stable; on by default).

Key

features.shell_tool

Type / Values

boolean

Details

Enable the default shell tool for running commands (stable; on by default).

Key

features.skill_mcp_dependency_install

Type / Values

boolean

Details

Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

Key

features.undo

Type / Values

boolean

Details

Enable undo support (stable; off by default).

Key

features.unified_exec

Type / Values

boolean

Details

Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

Key

features.web_search

Type / Values

boolean

Details

Deprecated legacy toggle; prefer the top-level web_search setting.

Key

features.web_search_cached

Type / Values

boolean

Details

Deprecated legacy toggle. When web_search is unset, true maps to web_search = "cached".

Key

features.web_search_request

Type / Values

boolean

Details

Deprecated legacy toggle. When web_search is unset, true maps to web_search = "live".

Key

feedback.enabled

Type / Values

boolean

Details

Enable feedback submission via /feedback across Codex surfaces (default: true).

Key

file_opener

Type / Values

vscode | vscode-insiders | windsurf | cursor | none

Details

URI scheme used to open citations from Codex output (default: vscode).

Key

forced_chatgpt_workspace_id

Type / Values

string (uuid)

Details

Limit ChatGPT logins to a specific workspace identifier.

Key

forced_login_method

Type / Values

chatgpt | api

Details

Restrict Codex to a specific authentication method.

Key

hide_agent_reasoning

Type / Values

boolean

Details

Suppress reasoning events in both the TUI and codex exec output.

Key

history.max_bytes

Type / Values

number

Details

If set, caps the history file size in bytes by dropping oldest entries.

Key

history.persistence

Type / Values

save-all | none

Details

Control whether Codex saves session transcripts to history.jsonl.

Key

hooks

Type / Values

table

Details

Lifecycle hooks configured inline in config.toml. Uses the same event schema as hooks.json; see the Hooks guide for examples and supported events.

Key

instructions

Type / Values

string

Details

Reserved for future use; prefer model_instructions_file or AGENTS.md.

Key

log_dir

Type / Values

string (path)

Details

Directory where Codex writes log files (for example codex-tui.log); defaults to $CODEX_HOME/log.

Key

mcp_oauth_callback_port

Type / Values

integer

Details

Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.

Key

mcp_oauth_callback_url

Type / Values

string

Details

Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). mcp_oauth_callback_port still controls the callback listener port.

Key

mcp_oauth_credentials_store

Type / Values

auto | file | keyring

Details

Preferred store for MCP OAuth credentials.

Key

mcp_servers.<id>.args

Type / Values

array<string>

Details

Arguments passed to the MCP stdio server command.

Key

mcp_servers.<id>.bearer_token_env_var

Type / Values

string

Details

Environment variable sourcing the bearer token for an MCP HTTP server.

Key

mcp_servers.<id>.command

Type / Values

string

Details

Launcher command for an MCP stdio server.

Key

mcp_servers.<id>.cwd

Type / Values

string

Details

Working directory for the MCP stdio server process.

Key

mcp_servers.<id>.disabled_tools

Type / Values

array<string>

Details

Deny list applied after enabled_tools for the MCP server.

Key

mcp_servers.<id>.enabled

Type / Values

boolean

Details

Disable an MCP server without removing its configuration.

Key

mcp_servers.<id>.enabled_tools

Type / Values

array<string>

Details

Allow list of tool names exposed by the MCP server.

Key

mcp_servers.<id>.env

Type / Values

map<string,string>

Details

Environment variables forwarded to the MCP stdio server.

Key

mcp_servers.<id>.env_http_headers

Type / Values

map<string,string>

Details

HTTP headers populated from environment variables for an MCP HTTP server.

Key

mcp_servers.<id>.env_vars

Type / Values

array<string | { name = string, source = "local" | "remote" }>

Details

Additional environment variables to whitelist for an MCP stdio server. String entries default to source = "local"; use source = "remote" only with executor-backed remote stdio.

Key

mcp_servers.<id>.experimental_environment

Type / Values

local | remote

Details

Experimental placement for an MCP server. remote starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

Key

mcp_servers.<id>.http_headers

Type / Values

map<string,string>

Details

Static HTTP headers included with each MCP HTTP request.

Key

mcp_servers.<id>.oauth_resource

Type / Values

string

Details

Optional RFC 8707 OAuth resource parameter to include during MCP login.

Key

mcp_servers.<id>.required

Type / Values

boolean

Details

When true, fail startup/resume if this enabled MCP server cannot initialize.

Key

mcp_servers.<id>.scopes

Type / Values

array<string>

Details

OAuth scopes to request when authenticating to that MCP server.

Key

mcp_servers.<id>.startup_timeout_ms

Type / Values

number

Details

Alias for startup_timeout_sec in milliseconds.

Key

mcp_servers.<id>.startup_timeout_sec

Type / Values

number

Details

Override the default 10s startup timeout for an MCP server.

Key

mcp_servers.<id>.tool_timeout_sec

Type / Values

number

Details

Override the default 60s per-tool timeout for an MCP server.

Key

mcp_servers.<id>.url

Type / Values

string

Details

Endpoint for an MCP streamable HTTP server.

Key

memories.consolidation_model

Type / Values

string

Details

Optional model override for global memory consolidation.

Key

memories.disable_on_external_context

Type / Values

boolean

Details

When true, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to false. Legacy alias: memories.no_memories_if_mcp_or_web_search.

Key

memories.extract_model

Type / Values

string

Details

Optional model override for per-thread memory extraction.

Key

memories.generate_memories

Type / Values

boolean

Details

When false, newly created threads are not stored as memory-generation inputs. Defaults to true.

Key

memories.max_raw_memories_for_consolidation

Type / Values

number

Details

Maximum recent raw memories retained for global consolidation. Defaults to 256 and is capped at 4096.

Key

memories.max_rollout_age_days

Type / Values

number

Details

Maximum age of threads considered for memory generation. Defaults to 30 and is clamped to 0-90.

Key

memories.max_rollouts_per_startup

Type / Values

number

Details

Maximum rollout candidates processed per startup pass. Defaults to 16 and is capped at 128.

Key

memories.max_unused_days

Type / Values

number

Details

Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to 30 and is clamped to 0-365.

Key

memories.min_rate_limit_remaining_percent

Type / Values

number

Details

Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to 25 and is clamped to 0-100.

Key

memories.min_rollout_idle_hours

Type / Values

number

Details

Minimum idle time before a thread is considered for memory generation. Defaults to 6 and is clamped to 1-48.

Key

memories.use_memories

Type / Values

boolean

Details

When false, Codex skips injecting existing memories into future sessions. Defaults to true.

Key

model

Type / Values

string

Details

Model to use (e.g., gpt-5.5).

Key

model_auto_compact_token_limit

Type / Values

number

Details

Token threshold that triggers automatic history compaction (unset uses model defaults).

Key

model_catalog_json

Type / Values

string (path)

Details

Optional path to a JSON model catalog loaded on startup. Profile-level profiles.<name>.model_catalog_json can override this per profile.

Key

model_context_window

Type / Values

number

Details

Context window tokens available to the active model.

Key

model_instructions_file

Type / Values

string (path)

Details

Replacement for built-in instructions instead of AGENTS.md.

Key

model_provider

Type / Values

string

Details

Provider id from model_providers (default: openai).

Key

model_providers.<id>

Type / Values

table

Details

Custom provider definition. Built-in provider IDs (openai, ollama, and lmstudio) are reserved and cannot be overridden.

Key

model_providers.<id>.auth

Type / Values

table

Details

Command-backed bearer token configuration for a custom provider. Do not combine with env_key, experimental_bearer_token, or requires_openai_auth.

Key

model_providers.<id>.auth.args

Type / Values

array<string>

Details

Arguments passed to the token command.

Key

model_providers.<id>.auth.command

Type / Values

string

Details

Command to run when Codex needs a bearer token. The command must print the token to stdout.

Key

model_providers.<id>.auth.cwd

Type / Values

string (path)

Details

Working directory for the token command.

Key

model_providers.<id>.auth.refresh_interval_ms

Type / Values

number

Details

How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to 0 to refresh only after an authentication retry.

Key

model_providers.<id>.auth.timeout_ms

Type / Values

number

Details

Maximum token command runtime in milliseconds (default: 5000).

Key

model_providers.<id>.base_url

Type / Values

string

Details

API base URL for the model provider.

Key

model_providers.<id>.env_http_headers

Type / Values

map<string,string>

Details

HTTP headers populated from environment variables when present.

Key

model_providers.<id>.env_key

Type / Values

string

Details

Environment variable supplying the provider API key.

Key

model_providers.<id>.env_key_instructions

Type / Values

string

Details

Optional setup guidance for the provider API key.

Key

model_providers.<id>.experimental_bearer_token

Type / Values

string

Details

Direct bearer token for the provider (discouraged; use env_key).

Key

model_providers.<id>.http_headers

Type / Values

map<string,string>

Details

Static HTTP headers added to provider requests.

Key

model_providers.<id>.name

Type / Values

string

Details

Display name for a custom model provider.

Key

model_providers.<id>.query_params

Type / Values

map<string,string>

Details

Extra query parameters appended to provider requests.

Key

model_providers.<id>.request_max_retries

Type / Values

number

Details

Retry count for HTTP requests to the provider (default: 4).

Key

model_providers.<id>.requires_openai_auth

Type / Values

boolean

Details

The provider uses OpenAI authentication (defaults to false).

Key

model_providers.<id>.stream_idle_timeout_ms

Type / Values

number

Details

Idle timeout for SSE streams in milliseconds (default: 300000).

Key

model_providers.<id>.stream_max_retries

Type / Values

number

Details

Retry count for SSE streaming interruptions (default: 5).

Key

model_providers.<id>.supports_websockets

Type / Values

boolean

Details

Whether that provider supports the Responses API WebSocket transport.

Key

model_providers.<id>.wire_api

Type / Values

responses

Details

Protocol used by the provider. responses is the only supported value, and it is the default when omitted.

Key

model_providers.amazon-bedrock.aws.profile

Type / Values

string

Details

AWS profile name used by the built-in amazon-bedrock provider.

Key

model_providers.amazon-bedrock.aws.region

Type / Values

string

Details

AWS region used by the built-in amazon-bedrock provider.

Key

model_reasoning_effort

Type / Values

minimal | low | medium | high | xhigh

Details

Adjust reasoning effort for supported models (Responses API only; xhigh is model-dependent).

Key

model_reasoning_summary

Type / Values

auto | concise | detailed | none

Details

Select reasoning summary detail or disable summaries entirely.

Key

model_supports_reasoning_summaries

Type / Values

boolean

Details

Force Codex to send or not send reasoning metadata.

Key

model_verbosity

Type / Values

low | medium | high

Details

Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

Key

notice.hide_full_access_warning

Type / Values

boolean

Details

Track acknowledgement of the full access warning prompt.

Key

notice.hide_gpt-5.1-codex-max_migration_prompt

Type / Values

boolean

Details

Track acknowledgement of the gpt-5.1-codex-max migration prompt.

Key

notice.hide_gpt5_1_migration_prompt

Type / Values

boolean

Details

Track acknowledgement of the GPT-5.1 migration prompt.

Key

notice.hide_rate_limit_model_nudge

Type / Values

boolean

Details

Track opt-out of the rate limit model switch reminder.

Key

notice.hide_world_writable_warning

Type / Values

boolean

Details

Track acknowledgement of the Windows world-writable directories warning.

Key

notice.model_migrations

Type / Values

map<string,string>

Details

Track acknowledged model migrations as old->new mappings.

Key

notify

Type / Values

array<string>

Details

Command invoked for notifications; receives a JSON payload from Codex.

Key

openai_base_url

Type / Values

string

Details

Base URL override for the built-in openai model provider.

Key

oss_provider

Type / Values

lmstudio | ollama

Details

Default local provider used when running with --oss (defaults to prompting if unset).

Key

otel.environment

Type / Values

string

Details

Environment tag applied to emitted OpenTelemetry events (default: dev).

Key

otel.exporter

Type / Values

none | otlp-http | otlp-grpc

Details

Select the OpenTelemetry exporter and provide any endpoint metadata.

Key

otel.exporter.<id>.endpoint

Type / Values

string

Details

Exporter endpoint for OTEL logs.

Key

otel.exporter.<id>.headers

Type / Values

map<string,string>

Details

Static headers included with OTEL exporter requests.

Key

otel.exporter.<id>.protocol

Type / Values

binary | json

Details

Protocol used by the OTLP/HTTP exporter.

Key

otel.exporter.<id>.tls.ca-certificate

Type / Values

string

Details

CA certificate path for OTEL exporter TLS.

Key

otel.exporter.<id>.tls.client-certificate

Type / Values

string

Details

Client certificate path for OTEL exporter TLS.

Key

otel.exporter.<id>.tls.client-private-key

Type / Values

string

Details

Client private key path for OTEL exporter TLS.

Key

otel.log_user_prompt

Type / Values

boolean

Details

Opt in to exporting raw user prompts with OpenTelemetry logs.

Key

otel.metrics_exporter

Type / Values

none | statsig | otlp-http | otlp-grpc

Details

Select the OpenTelemetry metrics exporter (defaults to statsig).

Key

otel.trace_exporter

Type / Values

none | otlp-http | otlp-grpc

Details

Select the OpenTelemetry trace exporter and provide any endpoint metadata.

Key

otel.trace_exporter.<id>.endpoint

Type / Values

string

Details

Trace exporter endpoint for OTEL logs.

Key

otel.trace_exporter.<id>.headers

Type / Values

map<string,string>

Details

Static headers included with OTEL trace exporter requests.

Key

otel.trace_exporter.<id>.protocol

Type / Values

binary | json

Details

Protocol used by the OTLP/HTTP trace exporter.

Key

otel.trace_exporter.<id>.tls.ca-certificate

Type / Values

string

Details

CA certificate path for OTEL trace exporter TLS.

Key

otel.trace_exporter.<id>.tls.client-certificate

Type / Values

string

Details

Client certificate path for OTEL trace exporter TLS.

Key

otel.trace_exporter.<id>.tls.client-private-key

Type / Values

string

Details

Client private key path for OTEL trace exporter TLS.

Key

permissions.<name>.filesystem

Type / Values

table

Details

Named filesystem permission profile. Each key is an absolute path or special token such as :minimal or :project_roots.

Key

permissions.<name>.filesystem.":project_roots".<subpath-or-glob>

Type / Values

"read" | "write" | "none"

Details

Scoped filesystem access relative to the detected project roots. Use "." for the root itself; glob subpaths such as "**/*.env" can deny reads with "none".

Key

permissions.<name>.filesystem.<path-or-glob>

Type / Values

"read" | "write" | "none" | table

Details

Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use "none" to deny reads for matching paths.

Key

permissions.<name>.filesystem.glob_scan_max_depth

Type / Values

number

Details

Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least 1 when set.

Key

permissions.<name>.network.allow_local_binding

Type / Values

boolean

Details

Permit local bind/listen operations through the managed proxy.

Key

permissions.<name>.network.allow_upstream_proxy

Type / Values

boolean

Details

Allow the managed proxy to chain to another upstream proxy.

Key

permissions.<name>.network.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

Key

permissions.<name>.network.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

Permit non-loopback bind addresses for the managed proxy listener.

Key

permissions.<name>.network.domains

Type / Values

map<string, allow | deny>

Details

Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with allow or deny values.

Key

permissions.<name>.network.enable_socks5

Type / Values

boolean

Details

Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

Key

permissions.<name>.network.enable_socks5_udp

Type / Values

boolean

Details

Allow UDP over the SOCKS5 listener when enabled.

Key

permissions.<name>.network.enabled

Type / Values

boolean

Details

Enable network access for this named permissions profile.

Key

permissions.<name>.network.mode

Type / Values

limited | full

Details

Network proxy mode used for subprocess traffic.

Key

permissions.<name>.network.proxy_url

Type / Values

string

Details

HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

Key

permissions.<name>.network.socks_url

Type / Values

string

Details

SOCKS5 proxy endpoint used by this permissions profile.

Key

permissions.<name>.network.unix_sockets

Type / Values

map<string, allow | none>

Details

Unix socket rules for the managed proxy. Use socket paths as keys, with allow or none values.

Key

personality

Type / Values

none | friendly | pragmatic

Details

Default communication style for models that advertise supportsPersonality; can be overridden per thread/turn or via /personality.

Key

plan_mode_reasoning_effort

Type / Values

none | minimal | low | medium | high | xhigh

Details

Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

Key

profile

Type / Values

string

Details

Default profile applied at startup (equivalent to --profile).

Key

profiles.<name>.*

Type / Values

various

Details

Profile-scoped overrides for any of the supported configuration keys.

Key

profiles.<name>.analytics.enabled

Type / Values

boolean

Details

Profile-scoped analytics enablement override.

Key

profiles.<name>.experimental_use_unified_exec_tool

Type / Values

boolean

Details

Legacy name for enabling unified exec; prefer [features].unified_exec.

Key

profiles.<name>.model_catalog_json

Type / Values

string (path)

Details

Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level model_catalog_json for that profile).

Key

profiles.<name>.model_instructions_file

Type / Values

string (path)

Details

Profile-scoped replacement for the built-in instruction file.

Key

profiles.<name>.oss_provider

Type / Values

lmstudio | ollama

Details

Profile-scoped OSS provider for --oss sessions.

Key

profiles.<name>.personality

Type / Values

none | friendly | pragmatic

Details

Profile-scoped communication style override for supported models.

Key

profiles.<name>.plan_mode_reasoning_effort

Type / Values

none | minimal | low | medium | high | xhigh

Details

Profile-scoped Plan-mode reasoning override.

Key

profiles.<name>.service_tier

Type / Values

flex | fast

Details

Profile-scoped service tier preference for new turns.

Key

profiles.<name>.tools_view_image

Type / Values

boolean

Details

Enable or disable the view_image tool in that profile.

Key

profiles.<name>.web_search

Type / Values

disabled | cached | live

Details

Profile-scoped web search mode override (default: "cached").

Key

profiles.<name>.windows.sandbox

Type / Values

unelevated | elevated

Details

Profile-scoped Windows sandbox mode override.

Key

project_doc_fallback_filenames

Type / Values

array<string>

Details

Additional filenames to try when AGENTS.md is missing.

Key

project_doc_max_bytes

Type / Values

number

Details

Maximum bytes read from AGENTS.md when building project instructions.

Key

project_root_markers

Type / Values

array<string>

Details

List of project root marker filenames; used when searching parent directories for the project root.

Key

projects.<path>.trust_level

Type / Values

string

Details

Mark a project or worktree as trusted or untrusted ("trusted" | "untrusted"). Untrusted projects skip project-scoped .codex/ layers, including project-local config, hooks, and rules.

Key

review_model

Type / Values

string

Details

Optional model override used by /review (defaults to the current session model).

Key

sandbox_mode

Type / Values

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

Details

Sandbox policy for filesystem and network access during command execution.

Key

sandbox_workspace_write.exclude_slash_tmp

Type / Values

boolean

Details

Exclude /tmp from writable roots in workspace-write mode.

Key

sandbox_workspace_write.exclude_tmpdir_env_var

Type / Values

boolean

Details

Exclude $TMPDIR from writable roots in workspace-write mode.

Key

sandbox_workspace_write.network_access

Type / Values

boolean

Details

Allow outbound network access inside the workspace-write sandbox.

Key

sandbox_workspace_write.writable_roots

Type / Values

array<string>

Details

Additional writable roots when sandbox_mode = "workspace-write".

Key

service_tier

Type / Values

flex | fast

Details

Preferred service tier for new turns.

Key

shell_environment_policy.exclude

Type / Values

array<string>

Details

Glob patterns for removing environment variables after the defaults.

Key

shell_environment_policy.experimental_use_profile

Type / Values

boolean

Details

Use the user shell profile when spawning subprocesses.

Key

shell_environment_policy.ignore_default_excludes

Type / Values

boolean

Details

Keep variables containing KEY/SECRET/TOKEN before other filters run.

Key

shell_environment_policy.include_only

Type / Values

array<string>

Details

Whitelist of patterns; when set only matching variables are kept.

Key

shell_environment_policy.inherit

Type / Values

all | core | none

Details

Baseline environment inheritance when spawning subprocesses.

Key

shell_environment_policy.set

Type / Values

map<string,string>

Details

Explicit environment overrides injected into every subprocess.

Key

show_raw_agent_reasoning

Type / Values

boolean

Details

Surface raw reasoning content when the active model emits it.

Key

skills.config

Type / Values

array<object>

Details

Per-skill enablement overrides stored in config.toml.

Key

skills.config.<index>.enabled

Type / Values

boolean

Details

Enable or disable the referenced skill.

Key

skills.config.<index>.path

Type / Values

string (path)

Details

Path to a skill folder containing SKILL.md.

Key

sqlite_home

Type / Values

string (path)

Details

Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

Key

suppress_unstable_features_warning

Type / Values

boolean

Details

Suppress the warning that appears when under-development feature flags are enabled.

Key

tool_output_token_limit

Type / Values

number

Details

Token budget for storing individual tool/function outputs in history.

Key

tool_suggest.disabled_tools

Type / Values

array<table>

Details

Disable suggestions for specific discoverable connectors or plugins. Each entry uses type = "connector" or "plugin" and an id.

Key

tool_suggest.discoverables

Type / Values

array<table>

Details

Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses type = "connector" or "plugin" and an id.

Key

tools.view_image

Type / Values

boolean

Details

Enable the local-image attachment tool view_image.

Key

tools.web_search

Type / Values

boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }

Details

Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.

Key

tui

Type / Values

table

Details

TUI-specific options such as enabling inline desktop notifications.

Key

tui.alternate_screen

Type / Values

auto | always | never

Details

Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).

Key

tui.animations

Type / Values

boolean

Details

Enable terminal animations (welcome screen, shimmer, spinner) (default: true).

Key

tui.keymap.<context>.<action>

Type / Values

string | array<string>

Details

Keyboard shortcut binding for a TUI action. Supported contexts include global, chat, composer, editor, pager, list, and approval; context-specific bindings override tui.keymap.global.

Key

tui.keymap.<context>.<action> = []

Type / Values

empty array

Details

Unbind the action in that keymap context. Key names use normalized strings such as ctrl-a, shift-enter, or page-down.

Key

tui.model_availability_nux.<model>

Type / Values

integer

Details

Internal startup-tooltip state keyed by model slug.

Key

tui.notification_condition

Type / Values

unfocused | always

Details

Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to unfocused.

Key

tui.notification_method

Type / Values

auto | osc9 | bel

Details

Notification method for terminal notifications (default: auto).

Key

tui.notifications

Type / Values

boolean | array<string>

Details

Enable TUI notifications; optionally restrict to specific event types.

Key

tui.show_tooltips

Type / Values

boolean

Details

Show onboarding tooltips in the TUI welcome screen (default: true).

Key

tui.status_line

Type / Values

array<string> | null

Details

Ordered list of TUI footer status-line item identifiers. null disables the status line.

Key

tui.terminal_title

Type / Values

array<string> | null

Details

Ordered list of terminal window/tab title item identifiers. Defaults to ["spinner", "project"]; null disables title updates.

Key

tui.theme

Type / Values

string

Details

Syntax-highlighting theme override (kebab-case theme name).

Key

web_search

Type / Values

disabled | cached | live

Details

Web search mode (default: "cached"; cached uses an OpenAI-maintained index and does not fetch live pages; if you use --yolo or another full access sandbox setting, it defaults to "live"). Use "live" to fetch the most recent data from the web, or "disabled" to remove the tool.

Key

windows_wsl_setup_acknowledged

Type / Values

boolean

Details

Track Windows onboarding acknowledgement (Windows only).

Key

windows.sandbox

Type / Values

unelevated | elevated

Details

Windows-only native sandbox mode when running Codex natively on Windows.

Key

windows.sandbox_private_desktop

Type / Values

boolean

Details

Run the final sandboxed child process on a private desktop by default on native Windows. Set false only for compatibility with the older Winsta0\\Default behavior.

Expand to view all

You can find the latest JSON schema for config.toml here.

To get autocompletion and diagnostics when editing config.toml in VS Code or Cursor, you can install the Even Better TOML extension and add this line to the top of your config.toml:

#:schema https://developers.openai.com/codex/config-schema.json

Note: Rename experimental_instructions_file to model_instructions_file. Codex deprecates the old key; update existing configs to the new name.

requirements.toml

requirements.toml is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see Admin-enforced requirements.

For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched requirements. See the security page for precedence details.

Use [features] in requirements.toml to pin feature flags by the same canonical keys that config.toml uses. Omitted keys remain unconstrained.

Key

allowed_approval_policies

Type / Values

array<string>

Details

Allowed values for approval_policy (for example untrusted, on-request, never, and granular).

Key

allowed_approvals_reviewers

Type / Values

array<string>

Details

Allowed values for approvals_reviewer, such as user and auto_review.

Key

allowed_sandbox_modes

Type / Values

array<string>

Details

Allowed values for sandbox_mode.

Key

allowed_web_search_modes

Type / Values

array<string>

Details

Allowed values for web_search (disabled, cached, live). disabled is always allowed; an empty list effectively allows only disabled.

Key

features

Type / Values

table

Details

Pinned feature values keyed by the canonical names from config.toml's [features] table.

Key

features.<name>

Type / Values

boolean

Details

Require a specific canonical feature key to stay enabled or disabled.

Key

features.browser_use

Type / Values

boolean

Details

Set to false in requirements.toml to disable Browser Use and Browser Agent availability.

Key

features.computer_use

Type / Values

boolean

Details

Set to false in requirements.toml to disable Computer Use availability and related install or enablement flows.

Key

features.in_app_browser

Type / Values

boolean

Details

Set to false in requirements.toml to disable the in-app browser pane.

Key

guardian_policy_config

Type / Values

string

Details

Managed Markdown policy instructions for automatic review. This takes precedence over local [auto_review].policy. Blank values are ignored.

Key

hooks

Type / Values

table

Details

Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline [hooks] in config.toml.

Key

hooks.<Event>

Type / Values

array<table>

Details

Matcher groups for a hook event such as PreToolUse, PostToolUse, PermissionRequest, SessionStart, UserPromptSubmit, or Stop.

Key

hooks.<Event>[].hooks

Type / Values

array<table>

Details

Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

Key

hooks.managed_dir

Type / Values

string (absolute path)

Details

Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.

Key

hooks.windows_managed_dir

Type / Values

string (absolute path)

Details

Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.

Key

mcp_servers

Type / Values

table

Details

Allowlist of MCP servers that may be enabled. Both the server name (<id>) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.

Key

mcp_servers.<id>.identity

Type / Values

table

Details

Identity rule for a single MCP server. Set either command (stdio) or url (streamable HTTP).

Key

mcp_servers.<id>.identity.command

Type / Values

string

Details

Allow an MCP stdio server when its mcp_servers.<id>.command matches this command.

Key

mcp_servers.<id>.identity.url

Type / Values

string

Details

Allow an MCP streamable HTTP server when its mcp_servers.<id>.url matches this URL.

Key

permissions.filesystem.deny_read

Type / Values

array<string>

Details

Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.

Key

remote_sandbox_config

Type / Values

array<table>

Details

Host-specific sandbox requirements. The first entry whose hostname_patterns match the resolved host name overrides top-level allowed_sandbox_modes for that requirements source. Host-specific entries currently override sandbox modes only.

Key

remote_sandbox_config[].allowed_sandbox_modes

Type / Values

array<string>

Details

Allowed sandbox modes to apply when this host-specific entry matches.

Key

remote_sandbox_config[].hostname_patterns

Type / Values

array<string>

Details

Case-insensitive host name patterns. Supports * for any sequence of characters and ? for one character.

Key

rules

Type / Values

table

Details

Admin-enforced command rules merged with .rules files. Requirements rules must be restrictive.

Key

rules.prefix_rules

Type / Values

array<table>

Details

List of enforced prefix rules. Each rule must include pattern and decision.

Key

rules.prefix_rules[].decision

Type / Values

prompt | forbidden

Details

Required. Requirements rules can only prompt or forbid (not allow).

Key

rules.prefix_rules[].justification

Type / Values

string

Details

Optional non-empty rationale surfaced in approval prompts or rejection messages.

Key

rules.prefix_rules[].pattern

Type / Values

array<table>

Details

Command prefix expressed as pattern tokens. Each token sets either token or any_of.

Key

rules.prefix_rules[].pattern[].any_of

Type / Values

array<string>

Details

A list of allowed alternative tokens at this position.

Key

rules.prefix_rules[].pattern[].token

Type / Values

string

Details

A single literal token at this position.

Expand to view all