18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |
19| `allow_login_shell` | `boolean` | 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. |19| `allow_login_shell` | `boolean` | 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. |
20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |
21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to 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. |21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | 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. |
22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |
23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |
24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |
25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |
26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |
27| `approvals_reviewer` | `user | auto_review` | 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. |
25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |
26| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |
27| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |
32| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |
33| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |
34| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |
38| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |
35| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |39| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |
36| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |40| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |
37| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |41| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |
38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |42| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |
40| `compact_prompt` | `string` | Inline override for the history compaction prompt. |44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |
45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |
41| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |
42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |
43| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |
44| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |
45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |
46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |
47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |
48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |
50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |
51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |
52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |
53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |
54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |
55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |
56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |
57| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |
58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |
59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |
60| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |
61| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |
62| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |
63| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |
64| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |
65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |
66| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |
67| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |
68| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |
69| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |
70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |
71| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |
72| `features.undo` | `boolean` | Enable undo support (stable; off by default). |61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |
73| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |62| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |
74| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |
75| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |
76| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |
77| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |
82| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |
83| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |
84| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |
73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |
85| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
86| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |75| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |
87| `mcp_oauth_callback_port` | `integer` | 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. |76| `mcp_oauth_callback_port` | `integer` | 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. |
96| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |85| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |
97| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |86| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |
98| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |87| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |
99| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |88| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | 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. |
89| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |
100| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |90| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |
101| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |91| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |
102| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |92| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |
105| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |95| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |
106| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |96| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |
107| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |97| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |
108| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |98| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |
99| `memories.disable_on_external_context` | `boolean` | 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`. |
100| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |
101| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |
102| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |
103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |
104| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |
105| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |
106| `memories.min_rate_limit_remaining_percent` | `number` | Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`. |
107| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |
108| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |
109| `model` | `string` | Model to use (e.g., `gpt-5.5`). |
109| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |110| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |
110| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |111| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |
111| `model_context_window` | `number` | Context window tokens available to the active model. |112| `model_context_window` | `number` | Context window tokens available to the active model. |
112| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |113| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |
113| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |114| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |
115| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |
116| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |
117| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |
118| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |
119| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |
120| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |
121| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |
114| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |122| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |
115| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |123| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |
116| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |124| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |
136| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |144| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |
137| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |145| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |
138| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |146| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |
147| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |
139| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |148| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |
140| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |149| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |
141| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |150| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |
154| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |163| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |
155| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |164| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |
156| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |165| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |
157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |166| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |
158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |167| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |
159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |168| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | 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. |
160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |169| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |
161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |170| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |
162| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |171| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |
163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |172| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |
164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |173| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |
165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |174| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |
166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |175| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |
167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |176| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |
168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |177| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |
169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |178| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |
170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |179| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |
171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |180| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |
181| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |
172| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |182| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |
173| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |183| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |
174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |184| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |
187| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |197| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |
188| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |198| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |
189| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |199| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |
190| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |200| `projects.<path>.trust_level` | `string` | 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. |
191| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |201| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |
192| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |202| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |
193| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |203| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |
194| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |204| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |
195| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |205| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |
196| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |206| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |
197| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |207| `service_tier` | `flex | fast` | Preferred service tier for new turns. |
198| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |208| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |
199| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |209| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |
200| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |210| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |
208| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |218| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |
209| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |219| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |
210| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |220| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |
221| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |
211| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |222| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |
212| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |223| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | 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. |
213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |224| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |
214| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |225| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |
215| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |226| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |
216| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |227| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |
217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |228| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |
229| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |
218| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |230| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |
219| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |231| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |
220| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |232| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |
233| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |
221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |234| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |
222| `web_search` | `disabled | cached | live` | 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. |235| `web_search` | `disabled | cached | live` | 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. |
223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |236| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |
224| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |237| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |
238| `windows.sandbox_private_desktop` | `boolean` | 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. |
225 239
226Key240Key
227 241
325 339
326Type / Values340Type / Values
327 341
328`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`342`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`
329 343
330Details344Details
331 345
332Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to 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.346Controls 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.
333 347
334Key348Key
335 349
336`approval_policy.reject.mcp_elicitations`350`approval_policy.granular.mcp_elicitations`
337 351
338Type / Values352Type / Values
339 353
341 355
342Details356Details
343 357
344When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.358When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.
345 359
346Key360Key
347 361
348`approval_policy.reject.rules`362`approval_policy.granular.request_permissions`
349 363
350Type / Values364Type / Values
351 365
353 367
354Details368Details
355 369
356When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.370When `true`, prompts from the `request_permissions` tool are allowed to surface.
357 371
358Key372Key
359 373
360`approval_policy.reject.sandbox_approval`374`approval_policy.granular.rules`
361 375
362Type / Values376Type / Values
363 377
365 379
366Details380Details
367 381
368When `true`, sandbox escalation approval prompts are auto-rejected.382When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.
383
384Key
385
386`approval_policy.granular.sandbox_approval`
387
388Type / Values
389
390`boolean`
391
392Details
393
394When `true`, sandbox escalation approval prompts are allowed to surface.
395
396Key
397
398`approval_policy.granular.skill_approval`
399
400Type / Values
401
402`boolean`
403
404Details
405
406When `true`, skill-script approval prompts are allowed to surface.
407
408Key
409
410`approvals_reviewer`
411
412Type / Values
413
414`user | auto_review`
415
416Details
417
418Who 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.
369 419
370Key420Key
371 421
489 539
490Key540Key
491 541
542`auto_review.policy`
543
544Type / Values
545
546`string`
547
548Details
549
550Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.
551
552Key
553
492`background_terminal_max_timeout`554`background_terminal_max_timeout`
493 555
494Type / Values556Type / Values
561 623
562Key624Key
563 625
626`default_permissions`
627
628Type / Values
629
630`string`
631
632Details
633
634Name of the default permissions profile to apply to sandboxed tool calls.
635
636Key
637
564`developer_instructions`638`developer_instructions`
565 639
566Type / Values640Type / Values
621 695
622Key696Key
623 697
624`features.apps_mcp_gateway`698`features.codex_hooks`
625 699
626Type / Values700Type / Values
627 701
629 703
630Details704Details
631 705
632Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).706Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.
633 707
634Key708Key
635 709
636`features.artifact`710`features.enable_request_compression`
637 711
638Type / Values712Type / Values
639 713
641 715
642Details716Details
643 717
644Enable native artifact tools such as slides and spreadsheets (under development).718Compress streaming request bodies with zstd when supported (stable; on by default).
645 719
646Key720Key
647 721
648`features.child_agents_md`722`features.fast_mode`
649 723
650Type / Values724Type / Values
651 725
653 727
654Details728Details
655 729
656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).730Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).
657 731
658Key732Key
659 733
660`features.collaboration_modes`734`features.memories`
661 735
662Type / Values736Type / Values
663 737
665 739
666Details740Details
667 741
668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.742Enable [Memories](https://developers.openai.com/codex/memories) (off by default).
669 743
670Key744Key
671 745
672`features.default_mode_request_user_input`746`features.multi_agent`
673 747
674Type / Values748Type / Values
675 749
677 751
678Details752Details
679 753
680Allow `request_user_input` in default collaboration mode (under development; off by default).754Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).
681 755
682Key756Key
683 757
684`features.elevated_windows_sandbox`758`features.personality`
685 759
686Type / Values760Type / Values
687 761
689 763
690Details764Details
691 765
692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.766Enable personality selection controls (stable; on by default).
693 767
694Key768Key
695 769
696`features.enable_request_compression`770`features.prevent_idle_sleep`
697 771
698Type / Values772Type / Values
699 773
701 775
702Details776Details
703 777
704Compress streaming request bodies with zstd when supported (stable; on by default).778Prevent the machine from sleeping while a turn is actively running (experimental; off by default).
705 779
706Key780Key
707 781
708`features.experimental_windows_sandbox`782`features.shell_snapshot`
709 783
710Type / Values784Type / Values
711 785
713 787
714Details788Details
715 789
716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.790Snapshot shell environment to speed up repeated commands (stable; on by default).
717 791
718Key792Key
719 793
720`features.fast_mode`794`features.shell_tool`
721 795
722Type / Values796Type / Values
723 797
725 799
726Details800Details
727 801
728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).802Enable the default `shell` tool for running commands (stable; on by default).
729 803
730Key804Key
731 805
732`features.image_detail_original`806`features.skill_mcp_dependency_install`
733 807
734Type / Values808Type / Values
735 809
737 811
738Details812Details
739 813
740Allow image outputs with `detail = "original"` on supported models (under development).814Allow prompting and installing missing MCP dependencies for skills (stable; on by default).
741 815
742Key816Key
743 817
744`features.image_generation`818`features.undo`
745 819
746Type / Values820Type / Values
747 821
749 823
750Details824Details
751 825
752Enable the built-in image generation tool (under development).826Enable undo support (stable; off by default).
753 827
754Key828Key
755 829
756`features.personality`830`features.unified_exec`
757 831
758Type / Values832Type / Values
759 833
761 835
762Details836Details
763 837
764Enable personality selection controls (stable; on by default).838Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).
765 839
766Key840Key
767 841
768`features.powershell_utf8`842`features.web_search`
769 843
770Type / Values844Type / Values
771 845
773 847
774Details848Details
775 849
776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.850Deprecated legacy toggle; prefer the top-level `web_search` setting.
777 851
778Key852Key
779 853
780`features.prevent_idle_sleep`854`features.web_search_cached`
781 855
782Type / Values856Type / Values
783 857
785 859
786Details860Details
787 861
788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).862Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.
789 863
790Key864Key
791 865
792`features.remote_models`866`features.web_search_request`
793 867
794Type / Values868Type / Values
795 869
797 871
798Details872Details
799 873
800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.874Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.
801 875
802Key876Key
803 877
804`features.request_rule`878`feedback.enabled`
805 879
806Type / Values880Type / Values
807 881
809 883
810Details884Details
811 885
812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.886Enable feedback submission via `/feedback` across Codex surfaces (default: true).
813 887
814Key888Key
815 889
816`features.responses_websockets`890`file_opener`
817 891
818Type / Values892Type / Values
819 893
820`boolean`894`vscode | vscode-insiders | windsurf | cursor | none`
821 895
822Details896Details
823 897
824Prefer the Responses API WebSocket transport for supported providers (under development).898URI scheme used to open citations from Codex output (default: `vscode`).
825 899
826Key900Key
827 901
828`features.responses_websockets_v2`902`forced_chatgpt_workspace_id`
829 903
830Type / Values904Type / Values
831 905
832`boolean`906`string (uuid)`
833 907
834Details908Details
835 909
836Enable Responses API WebSocket v2 mode (under development).910Limit ChatGPT logins to a specific workspace identifier.
837 911
838Key912Key
839 913
840`features.runtime_metrics`914`forced_login_method`
841 915
842Type / Values916Type / Values
843 917
844`boolean`918`chatgpt | api`
845 919
846Details920Details
847 921
848Show runtime metrics summary in TUI turn separators (experimental).922Restrict Codex to a specific authentication method.
849 923
850Key924Key
851 925
852`features.search_tool`926`hide_agent_reasoning`
853 927
854Type / Values928Type / Values
855 929
857 931
858Details932Details
859 933
860Legacy toggle for an older Apps discovery flow. Current builds do not use it.934Suppress reasoning events in both the TUI and `codex exec` output.
861 935
862Key936Key
863 937
864`features.shell_snapshot`938`history.max_bytes`
865 939
866Type / Values940Type / Values
867 941
868`boolean`942`number`
869 943
870Details944Details
871 945
872Snapshot shell environment to speed up repeated commands (stable; on by default).946If set, caps the history file size in bytes by dropping oldest entries.
873 947
874Key948Key
875 949
876`features.shell_tool`950`history.persistence`
877 951
878Type / Values952Type / Values
879 953
880`boolean`954`save-all | none`
881 955
882Details956Details
883 957
884Enable the default `shell` tool for running commands (stable; on by default).958Control whether Codex saves session transcripts to history.jsonl.
885 959
886Key960Key
887 961
888`features.skill_env_var_dependency_prompt`962`hooks`
889 963
890Type / Values964Type / Values
891 965
892`boolean`966`table`
893 967
894Details968Details
895 969
896Prompt for missing skill environment-variable dependencies (under development).970Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.
897 971
898Key972Key
899 973
900`features.skill_mcp_dependency_install`974`instructions`
901 975
902Type / Values976Type / Values
903 977
904`boolean`978`string`
905 979
906Details980Details
907 981
908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).982Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
909 983
910Key984Key
911 985
912`features.sqlite`986`log_dir`
913 987
914Type / Values988Type / Values
915 989
916`boolean`990`string (path)`
917 991
918Details992Details
919 993
920Enable SQLite-backed state persistence (stable; on by default).994Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.
921 995
922Key996Key
923 997
924`features.steer`998`mcp_oauth_callback_port`
925 999
926Type / Values1000Type / Values
927 1001
928`boolean`1002`integer`
929 1003
930Details1004Details
931 1005
932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1006Optional 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.
933 1007
934Key1008Key
935 1009
936`features.undo`1010`mcp_oauth_callback_url`
937 1011
938Type / Values1012Type / Values
939 1013
940`boolean`1014`string`
941 1015
942Details1016Details
943 1017
944Enable undo support (stable; off by default).1018Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.
945 1019
946Key1020Key
947 1021
948`features.unified_exec`1022`mcp_oauth_credentials_store`
949 1023
950Type / Values1024Type / Values
951 1025
952`boolean`1026`auto | file | keyring`
953 1027
954Details1028Details
955 1029
956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).1030Preferred store for MCP OAuth credentials.
957 1031
958Key1032Key
959 1033
960`features.use_linux_sandbox_bwrap`1034`mcp_servers.<id>.args`
961 1035
962Type / Values1036Type / Values
963 1037
964`boolean`1038`array<string>`
965 1039
966Details1040Details
967 1041
968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).1042Arguments passed to the MCP stdio server command.
969 1043
970Key1044Key
971 1045
972`features.web_search`1046`mcp_servers.<id>.bearer_token_env_var`
973 1047
974Type / Values1048Type / Values
975 1049
976`boolean`1050`string`
977 1051
978Details1052Details
979 1053
980Deprecated legacy toggle; prefer the top-level `web_search` setting.1054Environment variable sourcing the bearer token for an MCP HTTP server.
981 1055
982Key1056Key
983 1057
984`features.web_search_cached`1058`mcp_servers.<id>.command`
985 1059
986Type / Values1060Type / Values
987 1061
988`boolean`1062`string`
989 1063
990Details1064Details
991 1065
992Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.1066Launcher command for an MCP stdio server.
993 1067
994Key1068Key
995 1069
996`features.web_search_request`1070`mcp_servers.<id>.cwd`
997 1071
998Type / Values1072Type / Values
999 1073
1000`boolean`1074`string`
1001 1075
1002Details1076Details
1003 1077
1004Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.1078Working directory for the MCP stdio server process.
1005 1079
1006Key1080Key
1007 1081
1008`feedback.enabled`1082`mcp_servers.<id>.disabled_tools`
1083
1084Type / Values
1085
1086`array<string>`
1087
1088Details
1089
1090Deny list applied after `enabled_tools` for the MCP server.
1091
1092Key
1093
1094`mcp_servers.<id>.enabled`
1009 1095
1010Type / Values1096Type / Values
1011 1097
1013 1099
1014Details1100Details
1015 1101
1016Enable feedback submission via `/feedback` across Codex surfaces (default: true).1102Disable an MCP server without removing its configuration.
1017 1103
1018Key1104Key
1019 1105
1020`file_opener`1106`mcp_servers.<id>.enabled_tools`
1021 1107
1022Type / Values1108Type / Values
1023 1109
1024`vscode | vscode-insiders | windsurf | cursor | none`1110`array<string>`
1025 1111
1026Details1112Details
1027 1113
1028URI scheme used to open citations from Codex output (default: `vscode`).1114Allow list of tool names exposed by the MCP server.
1029 1115
1030Key1116Key
1031 1117
1032`forced_chatgpt_workspace_id`1118`mcp_servers.<id>.env`
1033 1119
1034Type / Values1120Type / Values
1035 1121
1036`string (uuid)`1122`map<string,string>`
1037 1123
1038Details1124Details
1039 1125
1040Limit ChatGPT logins to a specific workspace identifier.1126Environment variables forwarded to the MCP stdio server.
1041 1127
1042Key1128Key
1043 1129
1044`forced_login_method`1130`mcp_servers.<id>.env_http_headers`
1045 1131
1046Type / Values1132Type / Values
1047 1133
1048`chatgpt | api`1134`map<string,string>`
1049 1135
1050Details1136Details
1051 1137
1052Restrict Codex to a specific authentication method.1138HTTP headers populated from environment variables for an MCP HTTP server.
1053 1139
1054Key1140Key
1055 1141
1056`hide_agent_reasoning`1142`mcp_servers.<id>.env_vars`
1057 1143
1058Type / Values1144Type / Values
1059 1145
1060`boolean`1146`array<string | { name = string, source = "local" | "remote" }>`
1061 1147
1062Details1148Details
1063 1149
1064Suppress reasoning events in both the TUI and `codex exec` output.1150Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.
1065 1151
1066Key1152Key
1067 1153
1068`history.max_bytes`1154`mcp_servers.<id>.experimental_environment`
1069 1155
1070Type / Values1156Type / Values
1071 1157
1072`number`1158`local | remote`
1073 1159
1074Details1160Details
1075 1161
1076If set, caps the history file size in bytes by dropping oldest entries.1162Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.
1077 1163
1078Key1164Key
1079 1165
1080`history.persistence`1166`mcp_servers.<id>.http_headers`
1081 1167
1082Type / Values1168Type / Values
1083 1169
1084`save-all | none`1170`map<string,string>`
1085 1171
1086Details1172Details
1087 1173
1088Control whether Codex saves session transcripts to history.jsonl.1174Static HTTP headers included with each MCP HTTP request.
1089 1175
1090Key1176Key
1091 1177
1092`instructions`1178`mcp_servers.<id>.oauth_resource`
1093 1179
1094Type / Values1180Type / Values
1095 1181
1097 1183
1098Details1184Details
1099 1185
1100Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.1186Optional RFC 8707 OAuth resource parameter to include during MCP login.
1101 1187
1102Key1188Key
1103 1189
1104`log_dir`1190`mcp_servers.<id>.required`
1105 1191
1106Type / Values1192Type / Values
1107 1193
1108`string (path)`1194`boolean`
1109 1195
1110Details1196Details
1111 1197
1112Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.1198When true, fail startup/resume if this enabled MCP server cannot initialize.
1113 1199
1114Key1200Key
1115 1201
1116`mcp_oauth_callback_port`1202`mcp_servers.<id>.scopes`
1117 1203
1118Type / Values1204Type / Values
1119 1205
1120`integer`1206`array<string>`
1121 1207
1122Details1208Details
1123 1209
1124Optional 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.1210OAuth scopes to request when authenticating to that MCP server.
1125 1211
1126Key1212Key
1127 1213
1128`mcp_oauth_callback_url`1214`mcp_servers.<id>.startup_timeout_ms`
1129 1215
1130Type / Values1216Type / Values
1131 1217
1132`string`1218`number`
1133 1219
1134Details1220Details
1135 1221
1136Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.1222Alias for `startup_timeout_sec` in milliseconds.
1137 1223
1138Key1224Key
1139 1225
1140`mcp_oauth_credentials_store`1226`mcp_servers.<id>.startup_timeout_sec`
1141 1227
1142Type / Values1228Type / Values
1143 1229
1144`auto | file | keyring`1230`number`
1145 1231
1146Details1232Details
1147 1233
1148Preferred store for MCP OAuth credentials.1234Override the default 10s startup timeout for an MCP server.
1149 1235
1150Key1236Key
1151 1237
1152`mcp_servers.<id>.args`1238`mcp_servers.<id>.tool_timeout_sec`
1153 1239
1154Type / Values1240Type / Values
1155 1241
1156`array<string>`1242`number`
1157 1243
1158Details1244Details
1159 1245
1160Arguments passed to the MCP stdio server command.1246Override the default 60s per-tool timeout for an MCP server.
1161 1247
1162Key1248Key
1163 1249
1164`mcp_servers.<id>.bearer_token_env_var`1250`mcp_servers.<id>.url`
1165 1251
1166Type / Values1252Type / Values
1167 1253
1169 1255
1170Details1256Details
1171 1257
1172Environment variable sourcing the bearer token for an MCP HTTP server.1258Endpoint for an MCP streamable HTTP server.
1173 1259
1174Key1260Key
1175 1261
1176`mcp_servers.<id>.command`1262`memories.consolidation_model`
1177 1263
1178Type / Values1264Type / Values
1179 1265
1181 1267
1182Details1268Details
1183 1269
1184Launcher command for an MCP stdio server.1270Optional model override for global memory consolidation.
1185 1271
1186Key1272Key
1187 1273
1188`mcp_servers.<id>.cwd`1274`memories.disable_on_external_context`
1189 1275
1190Type / Values1276Type / Values
1191 1277
1192`string`1278`boolean`
1193 1279
1194Details1280Details
1195 1281
1196Working directory for the MCP stdio server process.1282When `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`.
1197 1283
1198Key1284Key
1199 1285
1200`mcp_servers.<id>.disabled_tools`1286`memories.extract_model`
1201 1287
1202Type / Values1288Type / Values
1203 1289
1204`array<string>`1290`string`
1205 1291
1206Details1292Details
1207 1293
1208Deny list applied after `enabled_tools` for the MCP server.1294Optional model override for per-thread memory extraction.
1209 1295
1210Key1296Key
1211 1297
1212`mcp_servers.<id>.enabled`1298`memories.generate_memories`
1213 1299
1214Type / Values1300Type / Values
1215 1301
1217 1303
1218Details1304Details
1219 1305
1220Disable an MCP server without removing its configuration.1306When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.
1221 1307
1222Key1308Key
1223 1309
1224`mcp_servers.<id>.enabled_tools`1310`memories.max_raw_memories_for_consolidation`
1225 1311
1226Type / Values1312Type / Values
1227 1313
1228`array<string>`1314`number`
1229 1315
1230Details1316Details
1231 1317
1232Allow list of tool names exposed by the MCP server.1318Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.
1233 1319
1234Key1320Key
1235 1321
1236`mcp_servers.<id>.env`1322`memories.max_rollout_age_days`
1237 1323
1238Type / Values1324Type / Values
1239 1325
1240`map<string,string>`1326`number`
1241 1327
1242Details1328Details
1243 1329
1244Environment variables forwarded to the MCP stdio server.1330Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.
1245 1331
1246Key1332Key
1247 1333
1248`mcp_servers.<id>.env_http_headers`1334`memories.max_rollouts_per_startup`
1249 1335
1250Type / Values1336Type / Values
1251 1337
1252`map<string,string>`1338`number`
1253 1339
1254Details1340Details
1255 1341
1256HTTP headers populated from environment variables for an MCP HTTP server.1342Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.
1257 1343
1258Key1344Key
1259 1345
1260`mcp_servers.<id>.env_vars`1346`memories.max_unused_days`
1261 1347
1262Type / Values1348Type / Values
1263 1349
1264`array<string>`1350`number`
1265 1351
1266Details1352Details
1267 1353
1268Additional environment variables to whitelist for an MCP stdio server.1354Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.
1269 1355
1270Key1356Key
1271 1357
1272`mcp_servers.<id>.http_headers`1358`memories.min_rate_limit_remaining_percent`
1273 1359
1274Type / Values1360Type / Values
1275 1361
1276`map<string,string>`1362`number`
1277 1363
1278Details1364Details
1279 1365
1280Static HTTP headers included with each MCP HTTP request.1366Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.
1281 1367
1282Key1368Key
1283 1369
1284`mcp_servers.<id>.oauth_resource`1370`memories.min_rollout_idle_hours`
1285 1371
1286Type / Values1372Type / Values
1287 1373
1288`string`1374`number`
1289 1375
1290Details1376Details
1291 1377
1292Optional RFC 8707 OAuth resource parameter to include during MCP login.1378Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.
1293 1379
1294Key1380Key
1295 1381
1296`mcp_servers.<id>.required`1382`memories.use_memories`
1297 1383
1298Type / Values1384Type / Values
1299 1385
1301 1387
1302Details1388Details
1303 1389
1304When true, fail startup/resume if this enabled MCP server cannot initialize.1390When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.
1305 1391
1306Key1392Key
1307 1393
1308`mcp_servers.<id>.scopes`1394`model`
1309 1395
1310Type / Values1396Type / Values
1311 1397
1312`array<string>`1398`string`
1313 1399
1314Details1400Details
1315 1401
1316OAuth scopes to request when authenticating to that MCP server.1402Model to use (e.g., `gpt-5.5`).
1403
1404Key
1405
1406`model_auto_compact_token_limit`
1407
1408Type / Values
1409
1410`number`
1411
1412Details
1413
1414Token threshold that triggers automatic history compaction (unset uses model defaults).
1415
1416Key
1417
1418`model_catalog_json`
1419
1420Type / Values
1421
1422`string (path)`
1423
1424Details
1425
1426Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.
1317 1427
1318Key1428Key
1319 1429
1320`mcp_servers.<id>.startup_timeout_ms`1430`model_context_window`
1321 1431
1322Type / Values1432Type / Values
1323 1433
1325 1435
1326Details1436Details
1327 1437
1328Alias for `startup_timeout_sec` in milliseconds.1438Context window tokens available to the active model.
1329 1439
1330Key1440Key
1331 1441
1332`mcp_servers.<id>.startup_timeout_sec`1442`model_instructions_file`
1333 1443
1334Type / Values1444Type / Values
1335 1445
1336`number`1446`string (path)`
1337 1447
1338Details1448Details
1339 1449
1340Override the default 10s startup timeout for an MCP server.1450Replacement for built-in instructions instead of `AGENTS.md`.
1341 1451
1342Key1452Key
1343 1453
1344`mcp_servers.<id>.tool_timeout_sec`1454`model_provider`
1345 1455
1346Type / Values1456Type / Values
1347 1457
1348`number`1458`string`
1349 1459
1350Details1460Details
1351 1461
1352Override the default 60s per-tool timeout for an MCP server.1462Provider id from `model_providers` (default: `openai`).
1353 1463
1354Key1464Key
1355 1465
1356`mcp_servers.<id>.url`1466`model_providers.<id>`
1357 1467
1358Type / Values1468Type / Values
1359 1469
1360`string`1470`table`
1361 1471
1362Details1472Details
1363 1473
1364Endpoint for an MCP streamable HTTP server.1474Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.
1365 1475
1366Key1476Key
1367 1477
1368`model`1478`model_providers.<id>.auth`
1369 1479
1370Type / Values1480Type / Values
1371 1481
1372`string`1482`table`
1373 1483
1374Details1484Details
1375 1485
1376Model to use (e.g., `gpt-5-codex`).1486Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.
1377 1487
1378Key1488Key
1379 1489
1380`model_auto_compact_token_limit`1490`model_providers.<id>.auth.args`
1381 1491
1382Type / Values1492Type / Values
1383 1493
1384`number`1494`array<string>`
1385 1495
1386Details1496Details
1387 1497
1388Token threshold that triggers automatic history compaction (unset uses model defaults).1498Arguments passed to the token command.
1389 1499
1390Key1500Key
1391 1501
1392`model_catalog_json`1502`model_providers.<id>.auth.command`
1393 1503
1394Type / Values1504Type / Values
1395 1505
1396`string (path)`1506`string`
1397 1507
1398Details1508Details
1399 1509
1400Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.1510Command to run when Codex needs a bearer token. The command must print the token to stdout.
1401 1511
1402Key1512Key
1403 1513
1404`model_context_window`1514`model_providers.<id>.auth.cwd`
1405 1515
1406Type / Values1516Type / Values
1407 1517
1408`number`1518`string (path)`
1409 1519
1410Details1520Details
1411 1521
1412Context window tokens available to the active model.1522Working directory for the token command.
1413 1523
1414Key1524Key
1415 1525
1416`model_instructions_file`1526`model_providers.<id>.auth.refresh_interval_ms`
1417 1527
1418Type / Values1528Type / Values
1419 1529
1420`string (path)`1530`number`
1421 1531
1422Details1532Details
1423 1533
1424Replacement for built-in instructions instead of `AGENTS.md`.1534How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.
1425 1535
1426Key1536Key
1427 1537
1428`model_provider`1538`model_providers.<id>.auth.timeout_ms`
1429 1539
1430Type / Values1540Type / Values
1431 1541
1432`string`1542`number`
1433 1543
1434Details1544Details
1435 1545
1436Provider id from `model_providers` (default: `openai`).1546Maximum token command runtime in milliseconds (default: 5000).
1437 1547
1438Key1548Key
1439 1549
1737 1847
1738Key1848Key
1739 1849
1850`openai_base_url`
1851
1852Type / Values
1853
1854`string`
1855
1856Details
1857
1858Base URL override for the built-in `openai` model provider.
1859
1860Key
1861
1740`oss_provider`1862`oss_provider`
1741 1863
1742Type / Values1864Type / Values
1953 2075
1954Key2076Key
1955 2077
1956`permissions.network.admin_url`2078`permissions.<name>.filesystem`
1957 2079
1958Type / Values2080Type / Values
1959 2081
1960`string`2082`table`
1961 2083
1962Details2084Details
1963 2085
1964Admin endpoint for the managed network proxy.2086Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.
1965 2087
1966Key2088Key
1967 2089
1968`permissions.network.allow_local_binding`2090`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`
1969 2091
1970Type / Values2092Type / Values
1971 2093
1972`boolean`2094`"read" | "write" | "none"`
1973 2095
1974Details2096Details
1975 2097
1976Permit local bind/listen operations through the managed proxy.2098Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.
1977 2099
1978Key2100Key
1979 2101
1980`permissions.network.allow_unix_sockets`2102`permissions.<name>.filesystem.<path-or-glob>`
1981 2103
1982Type / Values2104Type / Values
1983 2105
1984`array<string>`2106`"read" | "write" | "none" | table`
1985 2107
1986Details2108Details
1987 2109
1988Allowlist of Unix socket paths permitted through the managed proxy.2110Grant 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.
1989 2111
1990Key2112Key
1991 2113
1992`permissions.network.allow_upstream_proxy`2114`permissions.<name>.filesystem.glob_scan_max_depth`
1993 2115
1994Type / Values2116Type / Values
1995 2117
1996`boolean`2118`number`
1997 2119
1998Details2120Details
1999 2121
2000Allow the managed proxy to chain to another upstream proxy.2122Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.
2001 2123
2002Key2124Key
2003 2125
2004`permissions.network.allowed_domains`2126`permissions.<name>.network.allow_local_binding`
2005 2127
2006Type / Values2128Type / Values
2007 2129
2008`array<string>`2130`boolean`
2009 2131
2010Details2132Details
2011 2133
2012Allowlist of domains permitted through the managed proxy.2134Permit local bind/listen operations through the managed proxy.
2013 2135
2014Key2136Key
2015 2137
2016`permissions.network.dangerously_allow_all_unix_sockets`2138`permissions.<name>.network.allow_upstream_proxy`
2017 2139
2018Type / Values2140Type / Values
2019 2141
2021 2143
2022Details2144Details
2023 2145
2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.2146Allow the managed proxy to chain to another upstream proxy.
2025 2147
2026Key2148Key
2027 2149
2028`permissions.network.dangerously_allow_non_loopback_admin`2150`permissions.<name>.network.dangerously_allow_all_unix_sockets`
2029 2151
2030Type / Values2152Type / Values
2031 2153
2033 2155
2034Details2156Details
2035 2157
2036Permit non-loopback bind addresses for the managed proxy admin listener.2158Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.
2037 2159
2038Key2160Key
2039 2161
2040`permissions.network.dangerously_allow_non_loopback_proxy`2162`permissions.<name>.network.dangerously_allow_non_loopback_proxy`
2041 2163
2042Type / Values2164Type / Values
2043 2165
2049 2171
2050Key2172Key
2051 2173
2052`permissions.network.denied_domains`2174`permissions.<name>.network.domains`
2053 2175
2054Type / Values2176Type / Values
2055 2177
2056`array<string>`2178`map<string, allow | deny>`
2057 2179
2058Details2180Details
2059 2181
2060Denylist of domains blocked by the managed proxy.2182Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.
2061 2183
2062Key2184Key
2063 2185
2064`permissions.network.enable_socks5`2186`permissions.<name>.network.enable_socks5`
2065 2187
2066Type / Values2188Type / Values
2067 2189
2069 2191
2070Details2192Details
2071 2193
2072Expose a SOCKS5 listener from the managed network proxy.2194Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.
2073 2195
2074Key2196Key
2075 2197
2076`permissions.network.enable_socks5_udp`2198`permissions.<name>.network.enable_socks5_udp`
2077 2199
2078Type / Values2200Type / Values
2079 2201
2085 2207
2086Key2208Key
2087 2209
2088`permissions.network.enabled`2210`permissions.<name>.network.enabled`
2089 2211
2090Type / Values2212Type / Values
2091 2213
2093 2215
2094Details2216Details
2095 2217
2096Enable the managed network proxy configuration for subprocesses.2218Enable network access for this named permissions profile.
2097 2219
2098Key2220Key
2099 2221
2100`permissions.network.mode`2222`permissions.<name>.network.mode`
2101 2223
2102Type / Values2224Type / Values
2103 2225
2109 2231
2110Key2232Key
2111 2233
2112`permissions.network.proxy_url`2234`permissions.<name>.network.proxy_url`
2113 2235
2114Type / Values2236Type / Values
2115 2237
2117 2239
2118Details2240Details
2119 2241
2120HTTP proxy endpoint used by the managed network proxy.2242HTTP proxy endpoint used when this permissions profile enables the managed network proxy.
2121 2243
2122Key2244Key
2123 2245
2124`permissions.network.socks_url`2246`permissions.<name>.network.socks_url`
2125 2247
2126Type / Values2248Type / Values
2127 2249
2129 2251
2130Details2252Details
2131 2253
2132SOCKS5 proxy endpoint used by the managed network proxy.2254SOCKS5 proxy endpoint used by this permissions profile.
2255
2256Key
2257
2258`permissions.<name>.network.unix_sockets`
2259
2260Type / Values
2261
2262`map<string, allow | none>`
2263
2264Details
2265
2266Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.
2133 2267
2134Key2268Key
2135 2269
2357 2491
2358Details2492Details
2359 2493
2360Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.2494Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.
2361 2495
2362Key2496Key
2363 2497
2441 2575
2442Details2576Details
2443 2577
2444Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.2578Preferred service tier for new turns.
2445 2579
2446Key2580Key
2447 2581
2601 2735
2602Key2736Key
2603 2737
2738`tool_suggest.discoverables`
2739
2740Type / Values
2741
2742`array<table>`
2743
2744Details
2745
2746Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.
2747
2748Key
2749
2604`tools.view_image`2750`tools.view_image`
2605 2751
2606Type / Values2752Type / Values
2617 2763
2618Type / Values2764Type / Values
2619 2765
2620`boolean`2766`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`
2621 2767
2622Details2768Details
2623 2769
2624Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.2770Optional 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.
2625 2771
2626Key2772Key
2627 2773
2673 2819
2674Key2820Key
2675 2821
2822`tui.notification_condition`
2823
2824Type / Values
2825
2826`unfocused | always`
2827
2828Details
2829
2830Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.
2831
2832Key
2833
2676`tui.notification_method`2834`tui.notification_method`
2677 2835
2678Type / Values2836Type / Values
2681 2839
2682Details2840Details
2683 2841
2684Notification method for unfocused terminal notifications (default: auto).2842Notification method for terminal notifications (default: auto).
2685 2843
2686Key2844Key
2687 2845
2721 2879
2722Key2880Key
2723 2881
2882`tui.terminal_title`
2883
2884Type / Values
2885
2886`array<string> | null`
2887
2888Details
2889
2890Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.
2891
2892Key
2893
2724`tui.theme`2894`tui.theme`
2725 2895
2726Type / Values2896Type / Values
2767 2937
2768Windows-only native sandbox mode when running Codex natively on Windows.2938Windows-only native sandbox mode when running Codex natively on Windows.
2769 2939
2940Key
2941
2942`windows.sandbox_private_desktop`
2943
2944Type / Values
2945
2946`boolean`
2947
2948Details
2949
2950Run 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.
2951
2770Expand to view all2952Expand to view all
2771 2953
2772You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2954You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
2791 2973
2792| Key | Type / Values | Details |2974| Key | Type / Values | Details |
2793| --- | --- | --- |2975| --- | --- | --- |
2794| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2976| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |
2977| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |
2795| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2978| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |
2796| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2979| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |
2797| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |2980| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |
2798| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |2981| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |
2982| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. |
2983| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. |
2984| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |
2985| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |
2986| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |
2987| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |
2988| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |
2989| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |
2990| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |
2799| `mcp_servers` | `table` | 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. |2991| `mcp_servers` | `table` | 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. |
2800| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2992| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |
2801| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2993| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |
2802| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |2994| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |
2995| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |
2996| `remote_sandbox_config` | `array<table>` | 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. |
2997| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |
2998| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |
2803| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |2999| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |
2804| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |3000| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |
2805| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |3001| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |
2818 3014
2819Details3015Details
2820 3016
2821Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).3017Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).
3018
3019Key
3020
3021`allowed_approvals_reviewers`
3022
3023Type / Values
3024
3025`array<string>`
3026
3027Details
3028
3029Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.
2822 3030
2823Key3031Key
2824 3032
2870 3078
2871Key3079Key
2872 3080
3081`features.browser_use`
3082
3083Type / Values
3084
3085`boolean`
3086
3087Details
3088
3089Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.
3090
3091Key
3092
3093`features.computer_use`
3094
3095Type / Values
3096
3097`boolean`
3098
3099Details
3100
3101Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.
3102
3103Key
3104
3105`features.in_app_browser`
3106
3107Type / Values
3108
3109`boolean`
3110
3111Details
3112
3113Set to `false` in `requirements.toml` to disable the in-app browser pane.
3114
3115Key
3116
3117`guardian_policy_config`
3118
3119Type / Values
3120
3121`string`
3122
3123Details
3124
3125Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.
3126
3127Key
3128
3129`hooks`
3130
3131Type / Values
3132
3133`table`
3134
3135Details
3136
3137Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.
3138
3139Key
3140
3141`hooks.<Event>`
3142
3143Type / Values
3144
3145`array<table>`
3146
3147Details
3148
3149Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.
3150
3151Key
3152
3153`hooks.<Event>[].hooks`
3154
3155Type / Values
3156
3157`array<table>`
3158
3159Details
3160
3161Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.
3162
3163Key
3164
3165`hooks.managed_dir`
3166
3167Type / Values
3168
3169`string (absolute path)`
3170
3171Details
3172
3173Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.
3174
3175Key
3176
3177`hooks.windows_managed_dir`
3178
3179Type / Values
3180
3181`string (absolute path)`
3182
3183Details
3184
3185Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.
3186
3187Key
3188
2873`mcp_servers`3189`mcp_servers`
2874 3190
2875Type / Values3191Type / Values
2918 3234
2919Key3235Key
2920 3236
3237`permissions.filesystem.deny_read`
3238
3239Type / Values
3240
3241`array<string>`
3242
3243Details
3244
3245Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.
3246
3247Key
3248
3249`remote_sandbox_config`
3250
3251Type / Values
3252
3253`array<table>`
3254
3255Details
3256
3257Host-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.
3258
3259Key
3260
3261`remote_sandbox_config[].allowed_sandbox_modes`
3262
3263Type / Values
3264
3265`array<string>`
3266
3267Details
3268
3269Allowed sandbox modes to apply when this host-specific entry matches.
3270
3271Key
3272
3273`remote_sandbox_config[].hostname_patterns`
3274
3275Type / Values
3276
3277`array<string>`
3278
3279Details
3280
3281Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.
3282
3283Key
3284
2921`rules`3285`rules`
2922 3286
2923Type / Values3287Type / Values
