config-reference.md Codex Docs, 2026-03-26 18:27 UTC → 2026-05-02 06:45 UTC

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |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. |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. |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. |

27| `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`. |

28| `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. |

29| `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`. |

34| `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`. |

35| `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. |

36| `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. |

37| `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. |

38| `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. |

39| `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). |

40| `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). |

41| `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. |

42| `compact_prompt` | `string` | Inline override for the history compaction prompt. |44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

43| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |45| `default_permissions` | `string` | 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. |

44| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

45| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

46| `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). |

47| `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`. |

48| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

49| `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). |

50| `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). |

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

51| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |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). |

52| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

53| `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). |

54| `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). |

55| `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). |

56| `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). |

57| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

58| `features.undo` | `boolean` | Enable undo support (stable; off by default). |61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

59| `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). |

60| `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. |

67| `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. |

68| `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. |

69| `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. |

70| `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`. |

71| `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`. |

72| `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. |

81| `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. |

82| `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. |

83| `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. |

84| `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. |

85| `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. |

86| `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. |

87| `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. |

90| `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. |

91| `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. |

92| `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. |

93| `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`). |

94| `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). |

95| `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. |

96| `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. |

97| `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`. |

98| `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). |

99| `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. |

100| `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. |

101| `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. |

110| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |133| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

111| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |134| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

112| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |135| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

136| `model_providers.amazon-bedrock.aws.profile` | `string` | AWS profile name used by the built-in `amazon-bedrock` provider. |

137| `model_providers.amazon-bedrock.aws.region` | `string` | AWS region used by the built-in `amazon-bedrock` provider. |

113| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |138| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

114| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |139| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

115| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |140| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

141| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |166| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

142| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |167| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

143| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |168| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

144| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |169| `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"`. |

145| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |170| `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. |

171| `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. |

146| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |172| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

147| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

148| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |173| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

149| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

150| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |174| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

151| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |175| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

152| `permissions.<name>.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |176| `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. |

153| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |177| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

154| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |178| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

155| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |179| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

156| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |180| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

157| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |181| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

158| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |182| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

183| `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. |

159| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |184| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

160| `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. |185| `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. |

161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |186| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

174| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |199| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

175| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |200| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

176| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |201| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

177| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |202| `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. |

178| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |203| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

179| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |204| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

180| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |205| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

195| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |220| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

196| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |221| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

197| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |222| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

223| `tool_suggest.disabled_tools` | `array<table>` | Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

224| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

198| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |225| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

199| `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. |226| `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. |

200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |227| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

201| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |228| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

202| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |229| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

230| `tui.keymap.<context>.<action>` | `string | array<string>` | 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`. |

231| `tui.keymap.<context>.<action> = []` | `empty array` | Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. |

203| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |232| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

204| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |233| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

234| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |

205| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |235| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

206| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |236| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

207| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |237| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

238| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

208| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |239| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

209| `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. |240| `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. |

210| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |241| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

381 412 

382Key413Key

383 414 

415`approvals_reviewer`

416 

417Type / Values

418 

419`user | auto_review`

420 

421Details

422 

423Who 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.

424 

425Key

426 

384`apps._default.destructive_enabled`427`apps._default.destructive_enabled`

385 428 

386Type / Values429Type / Values

501 544 

502Key545Key

503 546 

547`auto_review.policy`

548 

549Type / Values

550 

551`string`

552 

553Details

554 

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

556 

557Key

558 

504`background_terminal_max_timeout`559`background_terminal_max_timeout`

505 560 

506Type / Values561Type / Values

581 636 

582Details637Details

583 638 

584Name of the default permissions profile to apply to sandboxed tool calls.639Name 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.

585 640 

586Key641Key

587 642 

645 700 

646Key701Key

647 702 

703`features.codex_hooks`

704 

705Type / Values

706 

707`boolean`

708 

709Details

710 

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

712 

713Key

714 

648`features.enable_request_compression`715`features.enable_request_compression`

649 716 

650Type / Values717Type / Values

669 736 

670Key737Key

671 738 

739`features.memories`

740 

741Type / Values

742 

743`boolean`

744 

745Details

746 

747Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

748 

749Key

750 

672`features.multi_agent`751`features.multi_agent`

673 752 

674Type / Values753Type / Values

741 820 

742Key821Key

743 822 

744`features.smart_approvals`

745 

746Type / Values

747 

748`boolean`

749 

750Details

751 

752Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

753 

754Key

755 

756`features.undo`823`features.undo`

757 824 

758Type / Values825Type / Values

897 964 

898Key965Key

899 966 

967`hooks`

968 

969Type / Values

970 

971`table`

972 

973Details

974 

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

976 

977Key

978 

900`instructions`979`instructions`

901 980 

902Type / Values981Type / Values

1069 1148 

1070Type / Values1149Type / Values

1071 1150 

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

1073 1152 

1074Details1153Details

1075 1154 

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

1156 

1157Key

1158 

1159`mcp_servers.<id>.experimental_environment`

1160 

1161Type / Values

1162 

1163`local | remote`

1164 

1165Details

1166 

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

1077 1168 

1078Key1169Key

1079 1170 

1173 1264 

1174Key1265Key

1175 1266 

1267`memories.consolidation_model`

1268 

1269Type / Values

1270 

1271`string`

1272 

1273Details

1274 

1275Optional model override for global memory consolidation.

1276 

1277Key

1278 

1279`memories.disable_on_external_context`

1280 

1281Type / Values

1282 

1283`boolean`

1284 

1285Details

1286 

1287When `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`.

1288 

1289Key

1290 

1291`memories.extract_model`

1292 

1293Type / Values

1294 

1295`string`

1296 

1297Details

1298 

1299Optional model override for per-thread memory extraction.

1300 

1301Key

1302 

1303`memories.generate_memories`

1304 

1305Type / Values

1306 

1307`boolean`

1308 

1309Details

1310 

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

1312 

1313Key

1314 

1315`memories.max_raw_memories_for_consolidation`

1316 

1317Type / Values

1318 

1319`number`

1320 

1321Details

1322 

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

1324 

1325Key

1326 

1327`memories.max_rollout_age_days`

1328 

1329Type / Values

1330 

1331`number`

1332 

1333Details

1334 

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

1336 

1337Key

1338 

1339`memories.max_rollouts_per_startup`

1340 

1341Type / Values

1342 

1343`number`

1344 

1345Details

1346 

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

1348 

1349Key

1350 

1351`memories.max_unused_days`

1352 

1353Type / Values

1354 

1355`number`

1356 

1357Details

1358 

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

1360 

1361Key

1362 

1363`memories.min_rate_limit_remaining_percent`

1364 

1365Type / Values

1366 

1367`number`

1368 

1369Details

1370 

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

1372 

1373Key

1374 

1375`memories.min_rollout_idle_hours`

1376 

1377Type / Values

1378 

1379`number`

1380 

1381Details

1382 

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

1384 

1385Key

1386 

1387`memories.use_memories`

1388 

1389Type / Values

1390 

1391`boolean`

1392 

1393Details

1394 

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

1396 

1397Key

1398 

1176`model`1399`model`

1177 1400 

1178Type / Values1401Type / Values

1181 1404 

1182Details1405Details

1183 1406 

1184Model to use (e.g., `gpt-5-codex`).1407Model to use (e.g., `gpt-5.5`).

1185 1408 

1186Key1409Key

1187 1410 

1245 1468 

1246Key1469Key

1247 1470 

1471`model_providers.<id>`

1472 

1473Type / Values

1474 

1475`table`

1476 

1477Details

1478 

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

1480 

1481Key

1482 

1483`model_providers.<id>.auth`

1484 

1485Type / Values

1486 

1487`table`

1488 

1489Details

1490 

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

1492 

1493Key

1494 

1495`model_providers.<id>.auth.args`

1496 

1497Type / Values

1498 

1499`array<string>`

1500 

1501Details

1502 

1503Arguments passed to the token command.

1504 

1505Key

1506 

1507`model_providers.<id>.auth.command`

1508 

1509Type / Values

1510 

1511`string`

1512 

1513Details

1514 

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

1516 

1517Key

1518 

1519`model_providers.<id>.auth.cwd`

1520 

1521Type / Values

1522 

1523`string (path)`

1524 

1525Details

1526 

1527Working directory for the token command.

1528 

1529Key

1530 

1531`model_providers.<id>.auth.refresh_interval_ms`

1532 

1533Type / Values

1534 

1535`number`

1536 

1537Details

1538 

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

1540 

1541Key

1542 

1543`model_providers.<id>.auth.timeout_ms`

1544 

1545Type / Values

1546 

1547`number`

1548 

1549Details

1550 

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

1552 

1553Key

1554 

1248`model_providers.<id>.base_url`1555`model_providers.<id>.base_url`

1249 1556 

1250Type / Values1557Type / Values

1413 1720 

1414Key1721Key

1415 1722 

1723`model_providers.amazon-bedrock.aws.profile`

1724 

1725Type / Values

1726 

1727`string`

1728 

1729Details

1730 

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

1732 

1733Key

1734 

1735`model_providers.amazon-bedrock.aws.region`

1736 

1737Type / Values

1738 

1739`string`

1740 

1741Details

1742 

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

1744 

1745Key

1746 

1416`model_reasoning_effort`1747`model_reasoning_effort`

1417 1748 

1418Type / Values1749Type / Values

1785 2116 

1786Key2117Key

1787 2118 

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

1789 2120 

1790Type / Values2121Type / Values

1791 2122 

1793 2124 

1794Details2125Details

1795 2126 

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

1797 2128 

1798Key2129Key

1799 2130 

1800`permissions.<name>.filesystem.<path>`2131`permissions.<name>.filesystem.<path-or-glob>`

1801 2132 

1802Type / Values2133Type / Values

1803 2134 

1805 2136 

1806Details2137Details

1807 2138 

1808Grant direct access for a path or special token, or scope nested entries under that root.2139Grant 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.

1809 2140 

1810Key2141Key

1811 2142 

1812`permissions.<name>.network.allow_local_binding`2143`permissions.<name>.filesystem.glob_scan_max_depth`

1813 2144 

1814Type / Values2145Type / Values

1815 2146 

1816`boolean`2147`number`

1817 2148 

1818Details2149Details

1819 2150 

1820Permit local bind/listen operations through the managed proxy.2151Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.

1821 2152 

1822Key2153Key

1823 2154 

1824`permissions.<name>.network.allow_unix_sockets`2155`permissions.<name>.network.allow_local_binding`

1825 2156 

1826Type / Values2157Type / Values

1827 2158 

1828`array<string>`2159`boolean`

1829 2160 

1830Details2161Details

1831 2162 

1832Allowlist of Unix socket paths permitted through the managed proxy.2163Permit local bind/listen operations through the managed proxy.

1833 2164 

1834Key2165Key

1835 2166 

1845 2176 

1846Key2177Key

1847 2178 

1848`permissions.<name>.network.allowed_domains`

1849 

1850Type / Values

1851 

1852`array<string>`

1853 

1854Details

1855 

1856Allowlist of domains permitted through the managed proxy.

1857 

1858Key

1859 

1860`permissions.<name>.network.dangerously_allow_all_unix_sockets`2179`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1861 2180 

1862Type / Values2181Type / Values

1881 2200 

1882Key2201Key

1883 2202 

1884`permissions.<name>.network.denied_domains`2203`permissions.<name>.network.domains`

1885 2204 

1886Type / Values2205Type / Values

1887 2206 

1888`array<string>`2207`map<string, allow | deny>`

1889 2208 

1890Details2209Details

1891 2210 

1892Denylist of domains blocked by the managed proxy.2211Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

1893 2212 

1894Key2213Key

1895 2214 

1965 2284 

1966Key2285Key

1967 2286 

2287`permissions.<name>.network.unix_sockets`

2288 

2289Type / Values

2290 

2291`map<string, allow | none>`

2292 

2293Details

2294 

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

2296 

2297Key

2298 

1968`personality`2299`personality`

1969 2300 

1970Type / Values2301Type / Values

2189 2520 

2190Details2521Details

2191 2522 

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

2193 2524 

2194Key2525Key

2195 2526 

2433 2764 

2434Key2765Key

2435 2766 

2767`tool_suggest.disabled_tools`

2768 

2769Type / Values

2770 

2771`array<table>`

2772 

2773Details

2774 

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

2776 

2777Key

2778 

2779`tool_suggest.discoverables`

2780 

2781Type / Values

2782 

2783`array<table>`

2784 

2785Details

2786 

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

2788 

2789Key

2790 

2436`tools.view_image`2791`tools.view_image`

2437 2792 

2438Type / Values2793Type / Values

2493 2848 

2494Key2849Key

2495 2850 

2851`tui.keymap.<context>.<action>`

2852 

2853Type / Values

2854 

2855`string | array<string>`

2856 

2857Details

2858 

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

2860 

2861Key

2862 

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

2864 

2865Type / Values

2866 

2867`empty array`

2868 

2869Details

2870 

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

2872 

2873Key

2874 

2496`tui.model_availability_nux.<model>`2875`tui.model_availability_nux.<model>`

2497 2876 

2498Type / Values2877Type / Values

2505 2884 

2506Key2885Key

2507 2886 

2887`tui.notification_condition`

2888 

2889Type / Values

2890 

2891`unfocused | always`

2892 

2893Details

2894 

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

2896 

2897Key

2898 

2508`tui.notification_method`2899`tui.notification_method`

2509 2900 

2510Type / Values2901Type / Values

2513 2904 

2514Details2905Details

2515 2906 

2516Notification method for unfocused terminal notifications (default: auto).2907Notification method for terminal notifications (default: auto).

2517 2908 

2518Key2909Key

2519 2910 

2553 2944 

2554Key2945Key

2555 2946 

2947`tui.terminal_title`

2948 

2949Type / Values

2950 

2951`array<string> | null`

2952 

2953Details

2954 

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

2956 

2957Key

2958 

2556`tui.theme`2959`tui.theme`

2557 2960 

2558Type / Values2961Type / Values

2636| Key | Type / Values | Details |3039| Key | Type / Values | Details |

2637| --- | --- | --- |3040| --- | --- | --- |

2638| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |3041| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

3042| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

2639| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |3043| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2640| `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`. |3044| `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`. |

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

2642| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |3046| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

3047| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. |

3048| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. |

3049| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |

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

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

3052| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |

3053| `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. |

3054| `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. |

3055| `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. |

2643| `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. |3056| `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. |

2644| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |3057| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2645| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |3058| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2646| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |3059| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

3060| `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. |

3061| `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. |

3062| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

3063| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

2647| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |3064| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2648| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |3065| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2649| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |3066| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

2666 3083 

2667Key3084Key

2668 3085 

3086`allowed_approvals_reviewers`

3087 

3088Type / Values

3089 

3090`array<string>`

3091 

3092Details

3093 

3094Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.

3095 

3096Key

3097 

2669`allowed_sandbox_modes`3098`allowed_sandbox_modes`

2670 3099 

2671Type / Values3100Type / Values

2714 3143 

2715Key3144Key

2716 3145 

3146`features.browser_use`

3147 

3148Type / Values

3149 

3150`boolean`

3151 

3152Details

3153 

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

3155 

3156Key

3157 

3158`features.computer_use`

3159 

3160Type / Values

3161 

3162`boolean`

3163 

3164Details

3165 

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

3167 

3168Key

3169 

3170`features.in_app_browser`

3171 

3172Type / Values

3173 

3174`boolean`

3175 

3176Details

3177 

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

3179 

3180Key

3181 

3182`guardian_policy_config`

3183 

3184Type / Values

3185 

3186`string`

3187 

3188Details

3189 

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

3191 

3192Key

3193 

3194`hooks`

3195 

3196Type / Values

3197 

3198`table`

3199 

3200Details

3201 

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

3203 

3204Key

3205 

3206`hooks.<Event>`

3207 

3208Type / Values

3209 

3210`array<table>`

3211 

3212Details

3213 

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

3215 

3216Key

3217 

3218`hooks.<Event>[].hooks`

3219 

3220Type / Values

3221 

3222`array<table>`

3223 

3224Details

3225 

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

3227 

3228Key

3229 

3230`hooks.managed_dir`

3231 

3232Type / Values

3233 

3234`string (absolute path)`

3235 

3236Details

3237 

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

3239 

3240Key

3241 

3242`hooks.windows_managed_dir`

3243 

3244Type / Values

3245 

3246`string (absolute path)`

3247 

3248Details

3249 

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

3251 

3252Key

3253 

2717`mcp_servers`3254`mcp_servers`

2718 3255 

2719Type / Values3256Type / Values

2762 3299 

2763Key3300Key

2764 3301 

3302`permissions.filesystem.deny_read`

3303 

3304Type / Values

3305 

3306`array<string>`

3307 

3308Details

3309 

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

3311 

3312Key

3313 

3314`remote_sandbox_config`

3315 

3316Type / Values

3317 

3318`array<table>`

3319 

3320Details

3321 

3322Host-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.

3323 

3324Key

3325 

3326`remote_sandbox_config[].allowed_sandbox_modes`

3327 

3328Type / Values

3329 

3330`array<string>`

3331 

3332Details

3333 

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

3335 

3336Key

3337 

3338`remote_sandbox_config[].hostname_patterns`

3339 

3340Type / Values

3341 

3342`array<string>`

3343 

3344Details

3345 

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

3347 

3348Key

3349 

2765`rules`3350`rules`

2766 3351 

2767Type / Values3352Type / Values