8 8
9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).
10 10
11| Key | Type / Values | Details |11<ConfigTable
12| --- | --- | --- |12 options={[
13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13 {
14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14 key: "model",
15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15 type: "string",
16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |16 description: "Model to use (e.g., `gpt-5.5`).",
17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17 },
18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18 {
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 key: "review_model",
20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20 type: "string",
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. |21 description:
22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |22 "Optional model override used by `/review` (defaults to the current session model).",
23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |23 },
24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |24 {
25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |25 key: "model_provider",
26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |26 type: "string",
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 description: "Provider id from `model_providers` (default: `openai`).",
28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28 },
29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29 {
30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30 key: "openai_base_url",
31| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |31 type: "string",
32| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |32 description:
33| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |33 "Base URL override for the built-in `openai` model provider.",
34| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |34 },
35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35 {
36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36 key: "model_context_window",
37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |37 type: "number",
38| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |38 description: "Context window tokens available to the active model.",
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. |39 },
40| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |40 {
41| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |41 key: "model_auto_compact_token_limit",
42| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |42 type: "number",
43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |43 description:
44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |44 "Token threshold that triggers automatic history compaction (unset uses model defaults).",
45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |45 },
46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |46 {
47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47 key: "model_catalog_json",
48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |48 type: "string (path)",
49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |49 description:
50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",
51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |51 },
52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52 {
53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53 key: "oss_provider",
54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54 type: "lmstudio | ollama",
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). |55 description:
56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56 "Default local provider used when running with `--oss` (defaults to prompting if unset).",
57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |57 },
58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |58 {
59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59 key: "approval_policy",
60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |60 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",
61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |61 description:
62| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |62 "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.",
63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63 },
64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64 {
65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65 key: "approval_policy.granular.sandbox_approval",
66| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |66 type: "boolean",
67| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |67 description:
68| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |68 "When `true`, sandbox escalation approval prompts are allowed to surface.",
69| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |69 },
70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70 {
71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71 key: "approval_policy.granular.rules",
72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72 type: "boolean",
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. |73 description:
74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",
75| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |75 },
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. |76 {
77| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |77 key: "approval_policy.granular.mcp_elicitations",
78| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |78 type: "boolean",
79| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |79 description:
80| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |80 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",
81| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |81 },
82| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |82 {
83| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |83 key: "approval_policy.granular.request_permissions",
84| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |84 type: "boolean",
85| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |85 description:
86| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |86 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",
87| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |87 },
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. |88 {
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. |89 key: "approval_policy.granular.skill_approval",
90| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |90 type: "boolean",
91| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |91 description:
92| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |92 "When `true`, skill-script approval prompts are allowed to surface.",
93| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |93 },
94| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |94 {
95| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |95 key: "approvals_reviewer",
96| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |96 type: "user | auto_review",
97| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |97 description:
98| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |98 "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.",
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`. |99 },
100| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |100 {
101| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |101 key: "auto_review.policy",
102| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |102 type: "string",
103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |103 description:
104| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |104 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",
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`. |105 },
106| `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`. |106 {
107| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |107 key: "allow_login_shell",
108| `model` | `string` | Model to use (e.g., `gpt-5.5`). |108 type: "boolean",
109| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |109 description:
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. |110 "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.",
111| `model_context_window` | `number` | Context window tokens available to the active model. |111 },
112| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |112 {
113| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |113 key: "sandbox_mode",
114| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |114 type: "read-only | workspace-write | danger-full-access",
115| `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`. |115 description:
116| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |116 "Sandbox policy for filesystem and network access during command execution.",
117| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |117 },
118| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |118 {
119| `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. |119 key: "sandbox_workspace_write.writable_roots",
120| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |120 type: "array<string>",
121| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |121 description:
122| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |122 'Additional writable roots when `sandbox_mode = "workspace-write"`.',
123| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |123 },
124| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |124 {
125| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |125 key: "sandbox_workspace_write.network_access",
126| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |126 type: "boolean",
127| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |127 description:
128| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |128 "Allow outbound network access inside the workspace-write sandbox.",
129| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |129 },
130| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |130 {
131| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |131 key: "sandbox_workspace_write.exclude_tmpdir_env_var",
132| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |132 type: "boolean",
133| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |133 description:
134| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |134 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",
135| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |135 },
136| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |136 {
137| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |137 key: "sandbox_workspace_write.exclude_slash_tmp",
138| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |138 type: "boolean",
139| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |139 description:
140| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |140 "Exclude `/tmp` from writable roots in workspace-write mode.",
141| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |141 },
142| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |142 {
143| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |143 key: "windows.sandbox",
144| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |144 type: "unelevated | elevated",
145| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |145 description:
146| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |146 "Windows-only native sandbox mode when running Codex natively on Windows.",
147| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |147 },
148| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |148 {
149| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |149 key: "windows.sandbox_private_desktop",
150| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |150 type: "boolean",
151| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |151 description:
152| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |152 "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.",
153| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |153 },
154| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |154 {
155| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |155 key: "notify",
156| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |156 type: "array<string>",
157| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |157 description:
158| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |158 "Command invoked for notifications; receives a JSON payload from Codex.",
159| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |159 },
160| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |160 {
161| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |161 key: "check_for_update_on_startup",
162| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |162 type: "boolean",
163| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |163 description:
164| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |164 "Check for Codex updates on startup (set to false only when updates are centrally managed).",
165| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |165 },
166| `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"`. |166 {
167| `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. |167 key: "feedback.enabled",
168| `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. |168 type: "boolean",
169| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |169 description:
170| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |170 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",
171| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |171 },
172| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |172 {
173| `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. |173 key: "analytics.enabled",
174| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |174 type: "boolean",
175| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |175 description:
176| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |176 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",
177| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |177 },
178| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |178 {
179| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |179 key: "instructions",
180| `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. |180 type: "string",
181| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |181 description:
182| `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. |182 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",
183| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |183 },
184| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |184 {
185| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |185 key: "developer_instructions",
186| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |186 type: "string",
187| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |187 description:
188| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |188 "Additional developer instructions injected into the session (optional).",
189| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |189 },
190| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |190 {
191| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |191 key: "log_dir",
192| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |192 type: "string (path)",
193| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |193 description:
194| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |194 "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.",
195| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |195 },
196| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |196 {
197| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |197 key: "sqlite_home",
198| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |198 type: "string (path)",
199| `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. |199 description:
200| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |200 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",
201| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |201 },
202| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |202 {
203| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |203 key: "compact_prompt",
204| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |204 type: "string",
205| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |205 description: "Inline override for the history compaction prompt.",
206| `service_tier` | `flex | fast` | Preferred service tier for new turns. |206 },
207| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |207 {
208| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |208 key: "commit_attribution",
209| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |209 type: "string",
210| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |210 description:
211| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |211 "Override the commit co-author trailer text. Set an empty string to disable automatic attribution.",
212| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |212 },
213| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |213 {
214| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |214 key: "model_instructions_file",
215| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |215 type: "string (path)",
216| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |216 description:
217| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |217 "Replacement for built-in instructions instead of `AGENTS.md`.",
218| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |218 },
219| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |219 {
220| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |220 key: "personality",
221| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |221 type: "none | friendly | pragmatic",
222| `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. |222 description:
223| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |223 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",
224| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |224 },
225| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |225 {
226| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |226 key: "service_tier",
227| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |227 type: "flex | fast",
228| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |228 description: "Preferred service tier for new turns.",
229| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |229 },
230| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |230 {
231| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |231 key: "experimental_compact_prompt_file",
232| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |232 type: "string (path)",
233| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |233 description:
234| `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. |234 "Load the compaction prompt override from a file (experimental).",
235| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |235 },
236| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |236 {
237| `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. |237 key: "skills.config",
238 238 type: "array<object>",
239Key239 description: "Per-skill enablement overrides stored in config.toml.",
240 240 },
241`agents.<name>.config_file`241 {
242 242 key: "skills.config.<index>.path",
243Type / Values243 type: "string (path)",
244 244 description: "Path to a skill folder containing `SKILL.md`.",
245`string (path)`245 },
246 246 {
247Details247 key: "skills.config.<index>.enabled",
248 248 type: "boolean",
249Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.249 description: "Enable or disable the referenced skill.",
250 250 },
251Key251 {
252 252 key: "apps.<id>.enabled",
253`agents.<name>.description`253 type: "boolean",
254 254 description:
255Type / Values255 "Enable or disable a specific app/connector by id (default: true).",
256 256 },
257`string`257 {
258 258 key: "apps._default.enabled",
259Details259 type: "boolean",
260 260 description:
261Role guidance shown to Codex when choosing and spawning that agent type.261 "Default app enabled state for all apps unless overridden per app.",
262 262 },
263Key263 {
264 264 key: "apps._default.destructive_enabled",
265`agents.<name>.nickname_candidates`265 type: "boolean",
266 266 description:
267Type / Values267 "Default allow/deny for app tools with `destructive_hint = true`.",
268 268 },
269`array<string>`269 {
270 270 key: "apps._default.open_world_enabled",
271Details271 type: "boolean",
272 272 description:
273Optional pool of display nicknames for spawned agents in that role.273 "Default allow/deny for app tools with `open_world_hint = true`.",
274 274 },
275Key275 {
276 276 key: "apps.<id>.destructive_enabled",
277`agents.job_max_runtime_seconds`277 type: "boolean",
278 278 description:
279Type / Values279 "Allow or block tools in this app that advertise `destructive_hint = true`.",
280 280 },
281`number`281 {
282 282 key: "apps.<id>.open_world_enabled",
283Details283 type: "boolean",
284 284 description:
285Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.285 "Allow or block tools in this app that advertise `open_world_hint = true`.",
286 286 },
287Key287 {
288 288 key: "apps.<id>.default_tools_enabled",
289`agents.max_depth`289 type: "boolean",
290 290 description:
291Type / Values291 "Default enabled state for tools in this app unless a per-tool override exists.",
292 292 },
293`number`293 {
294 294 key: "apps.<id>.default_tools_approval_mode",
295Details295 type: "auto | prompt | approve",
296 296 description:
297Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).297 "Default approval behavior for tools in this app unless a per-tool override exists.",
298 298 },
299Key299 {
300 300 key: "apps.<id>.tools.<tool>.enabled",
301`agents.max_threads`301 type: "boolean",
302 302 description:
303Type / Values303 "Per-tool enabled override for an app tool (for example `repos/list`).",
304 304 },
305`number`305 {
306 306 key: "apps.<id>.tools.<tool>.approval_mode",
307Details307 type: "auto | prompt | approve",
308 308 description: "Per-tool approval behavior override for a single app tool.",
309Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.309 },
310 310 {
311Key311 key: "tool_suggest.discoverables",
312 312 type: "array<table>",
313`allow_login_shell`313 description:
314 314 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
315Type / Values315 },
316 316 {
317`boolean`317 key: "tool_suggest.disabled_tools",
318 318 type: "array<table>",
319Details319 description:
320 320 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',
321Allow 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.321 },
322 322 {
323Key323 key: "features.apps",
324 324 type: "boolean",
325`analytics.enabled`325 description: "Enable ChatGPT Apps/connectors support (experimental).",
326 326 },
327Type / Values327 {
328 328 key: "features.codex_hooks",
329`boolean`329 type: "boolean",
330 330 description:
331Details331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",
332 332 },
333Enable or disable analytics for this machine/profile. When unset, the client default applies.333 {
334 334 key: "hooks",
335Key335 type: "table",
336 336 description:
337`approval_policy`337 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
338 338 },
339Type / Values339 {
340 340 key: "features.memories",
341`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`341 type: "boolean",
342 342 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",
343Details343 },
344 344 {
345Controls 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.345 key: "mcp_servers.<id>.command",
346 346 type: "string",
347Key347 description: "Launcher command for an MCP stdio server.",
348 348 },
349`approval_policy.granular.mcp_elicitations`349 {
350 350 key: "mcp_servers.<id>.args",
351Type / Values351 type: "array<string>",
352 352 description: "Arguments passed to the MCP stdio server command.",
353`boolean`353 },
354 354 {
355Details355 key: "mcp_servers.<id>.env",
356 356 type: "map<string,string>",
357When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.357 description: "Environment variables forwarded to the MCP stdio server.",
358 358 },
359Key359 {
360 360 key: "mcp_servers.<id>.env_vars",
361`approval_policy.granular.request_permissions`361 type: 'array<string | { name = string, source = "local" | "remote" }>',
362 362 description:
363Type / Values363 '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.',
364 364 },
365`boolean`365 {
366 366 key: "mcp_servers.<id>.cwd",
367Details367 type: "string",
368 368 description: "Working directory for the MCP stdio server process.",
369When `true`, prompts from the `request_permissions` tool are allowed to surface.369 },
370 370 {
371Key371 key: "mcp_servers.<id>.url",
372 372 type: "string",
373`approval_policy.granular.rules`373 description: "Endpoint for an MCP streamable HTTP server.",
374 374 },
375Type / Values375 {
376 376 key: "mcp_servers.<id>.bearer_token_env_var",
377`boolean`377 type: "string",
378 378 description:
379Details379 "Environment variable sourcing the bearer token for an MCP HTTP server.",
380 380 },
381When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.381 {
382 382 key: "mcp_servers.<id>.http_headers",
383Key383 type: "map<string,string>",
384 384 description: "Static HTTP headers included with each MCP HTTP request.",
385`approval_policy.granular.sandbox_approval`385 },
386 386 {
387Type / Values387 key: "mcp_servers.<id>.env_http_headers",
388 388 type: "map<string,string>",
389`boolean`389 description:
390 390 "HTTP headers populated from environment variables for an MCP HTTP server.",
391Details391 },
392 392 {
393When `true`, sandbox escalation approval prompts are allowed to surface.393 key: "mcp_servers.<id>.enabled",
394 394 type: "boolean",
395Key395 description: "Disable an MCP server without removing its configuration.",
396 396 },
397`approval_policy.granular.skill_approval`397 {
398 398 key: "mcp_servers.<id>.required",
399Type / Values399 type: "boolean",
400 400 description:
401`boolean`401 "When true, fail startup/resume if this enabled MCP server cannot initialize.",
402 402 },
403Details403 {
404 404 key: "mcp_servers.<id>.startup_timeout_sec",
405When `true`, skill-script approval prompts are allowed to surface.405 type: "number",
406 406 description:
407Key407 "Override the default 10s startup timeout for an MCP server.",
408 408 },
409`approvals_reviewer`409 {
410 410 key: "mcp_servers.<id>.startup_timeout_ms",
411Type / Values411 type: "number",
412 412 description: "Alias for `startup_timeout_sec` in milliseconds.",
413`user | auto_review`413 },
414 414 {
415Details415 key: "mcp_servers.<id>.tool_timeout_sec",
416 416 type: "number",
417Who 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.417 description:
418 418 "Override the default 60s per-tool timeout for an MCP server.",
419Key419 },
420 420 {
421`apps._default.destructive_enabled`421 key: "mcp_servers.<id>.enabled_tools",
422 422 type: "array<string>",
423Type / Values423 description: "Allow list of tool names exposed by the MCP server.",
424 424 },
425`boolean`425 {
426 426 key: "mcp_servers.<id>.disabled_tools",
427Details427 type: "array<string>",
428 428 description:
429Default allow/deny for app tools with `destructive_hint = true`.429 "Deny list applied after `enabled_tools` for the MCP server.",
430 430 },
431Key431 {
432 432 key: "mcp_servers.<id>.scopes",
433`apps._default.enabled`433 type: "array<string>",
434 434 description:
435Type / Values435 "OAuth scopes to request when authenticating to that MCP server.",
436 436 },
437`boolean`437 {
438 438 key: "mcp_servers.<id>.oauth_resource",
439Details439 type: "string",
440 440 description:
441Default app enabled state for all apps unless overridden per app.441 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",
442 442 },
443Key443 {
444 444 key: "mcp_servers.<id>.experimental_environment",
445`apps._default.open_world_enabled`445 type: "local | remote",
446 446 description:
447Type / Values447 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",
448 448 },
449`boolean`449 {
450 450 key: "agents.max_threads",
451Details451 type: "number",
452 452 description:
453Default allow/deny for app tools with `open_world_hint = true`.453 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",
454 454 },
455Key455 {
456 456 key: "agents.max_depth",
457`apps.<id>.default_tools_approval_mode`457 type: "number",
458 458 description:
459Type / Values459 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",
460 460 },
461`auto | prompt | approve`461 {
462 462 key: "agents.job_max_runtime_seconds",
463Details463 type: "number",
464 464 description:
465Default approval behavior for tools in this app unless a per-tool override exists.465 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",
466 466 },
467Key467 {
468 468 key: "agents.<name>.description",
469`apps.<id>.default_tools_enabled`469 type: "string",
470 470 description:
471Type / Values471 "Role guidance shown to Codex when choosing and spawning that agent type.",
472 472 },
473`boolean`473 {
474 474 key: "agents.<name>.config_file",
475Details475 type: "string (path)",
476 476 description:
477Default enabled state for tools in this app unless a per-tool override exists.477 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",
478 478 },
479Key479 {
480 480 key: "agents.<name>.nickname_candidates",
481`apps.<id>.destructive_enabled`481 type: "array<string>",
482 482 description:
483Type / Values483 "Optional pool of display nicknames for spawned agents in that role.",
484 484 },
485`boolean`485 {
486 486 key: "memories.generate_memories",
487Details487 type: "boolean",
488 488 description:
489Allow or block tools in this app that advertise `destructive_hint = true`.489 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",
490 490 },
491Key491 {
492 492 key: "memories.use_memories",
493`apps.<id>.enabled`493 type: "boolean",
494 494 description:
495Type / Values495 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",
496 496 },
497`boolean`497 {
498 498 key: "memories.disable_on_external_context",
499Details499 type: "boolean",
500 500 description:
501Enable or disable a specific app/connector by id (default: true).501 "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`.",
502 502 },
503Key503 {
504 504 key: "memories.max_raw_memories_for_consolidation",
505`apps.<id>.open_world_enabled`505 type: "number",
506 506 description:
507Type / Values507 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",
508 508 },
509`boolean`509 {
510 510 key: "memories.max_unused_days",
511Details511 type: "number",
512 512 description:
513Allow or block tools in this app that advertise `open_world_hint = true`.513 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",
514 514 },
515Key515 {
516 516 key: "memories.max_rollout_age_days",
517`apps.<id>.tools.<tool>.approval_mode`517 type: "number",
518 518 description:
519Type / Values519 "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.",
520 520 },
521`auto | prompt | approve`521 {
522 522 key: "memories.max_rollouts_per_startup",
523Details523 type: "number",
524 524 description:
525Per-tool approval behavior override for a single app tool.525 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",
526 526 },
527Key527 {
528 528 key: "memories.min_rollout_idle_hours",
529`apps.<id>.tools.<tool>.enabled`529 type: "number",
530 530 description:
531Type / Values531 "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.",
532 532 },
533`boolean`533 {
534 534 key: "memories.min_rate_limit_remaining_percent",
535Details535 type: "number",
536 536 description:
537Per-tool enabled override for an app tool (for example `repos/list`).537 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",
538 538 },
539Key539 {
540 540 key: "memories.extract_model",
541`auto_review.policy`541 type: "string",
542 542 description: "Optional model override for per-thread memory extraction.",
543Type / Values543 },
544 544 {
545`string`545 key: "memories.consolidation_model",
546 546 type: "string",
547Details547 description: "Optional model override for global memory consolidation.",
548 548 },
549Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.549 {
550 550 key: "features.unified_exec",
551Key551 type: "boolean",
552 552 description:
553`background_terminal_max_timeout`553 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",
554 554 },
555Type / Values555 {
556 556 key: "features.shell_snapshot",
557`number`557 type: "boolean",
558 558 description:
559Details559 "Snapshot shell environment to speed up repeated commands (stable; on by default).",
560 560 },
561Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.561 {
562 562 key: "features.undo",
563Key563 type: "boolean",
564 564 description: "Enable undo support (stable; off by default).",
565`chatgpt_base_url`565 },
566 566 {
567Type / Values567 key: "features.multi_agent",
568 568 type: "boolean",
569`string`569 description:
570 570 "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).",
571Details571 },
572 572 {
573Override the base URL used during the ChatGPT login flow.573 key: "features.personality",
574 574 type: "boolean",
575Key575 description:
576 576 "Enable personality selection controls (stable; on by default).",
577`check_for_update_on_startup`577 },
578 578 {
579Type / Values579 key: "features.web_search",
580 580 type: "boolean",
581`boolean`581 description:
582 582 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",
583Details583 },
584 584 {
585Check for Codex updates on startup (set to false only when updates are centrally managed).585 key: "features.web_search_cached",
586 586 type: "boolean",
587Key587 description:
588 588 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',
589`cli_auth_credentials_store`589 },
590 590 {
591Type / Values591 key: "features.web_search_request",
592 592 type: "boolean",
593`file | keyring | auto`593 description:
594 594 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.',
595Details595 },
596 596 {
597Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).597 key: "features.shell_tool",
598 598 type: "boolean",
599Key599 description:
600 600 "Enable the default `shell` tool for running commands (stable; on by default).",
601`commit_attribution`601 },
602 602 {
603Type / Values603 key: "features.enable_request_compression",
604 604 type: "boolean",
605`string`605 description:
606 606 "Compress streaming request bodies with zstd when supported (stable; on by default).",
607Details607 },
608 608 {
609Override the commit co-author trailer text. Set an empty string to disable automatic attribution.609 key: "features.skill_mcp_dependency_install",
610 610 type: "boolean",
611Key611 description:
612 612 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",
613`compact_prompt`613 },
614 614 {
615Type / Values615 key: "features.fast_mode",
616 616 type: "boolean",
617`string`617 description:
618 618 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).',
619Details619 },
620 620 {
621Inline override for the history compaction prompt.621 key: "features.prevent_idle_sleep",
622 622 type: "boolean",
623Key623 description:
624 624 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",
625`default_permissions`625 },
626 626 {
627Type / Values627 key: "suppress_unstable_features_warning",
628 628 type: "boolean",
629`string`629 description:
630 630 "Suppress the warning that appears when under-development feature flags are enabled.",
631Details631 },
632 632 {
633Name of the default permissions profile to apply to sandboxed tool calls.633 key: "model_providers.<id>",
634 634 type: "table",
635Key635 description:
636 636 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",
637`developer_instructions`637 },
638 638 {
639Type / Values639 key: "model_providers.<id>.name",
640 640 type: "string",
641`string`641 description: "Display name for a custom model provider.",
642 642 },
643Details643 {
644 644 key: "model_providers.<id>.base_url",
645Additional developer instructions injected into the session (optional).645 type: "string",
646 646 description: "API base URL for the model provider.",
647Key647 },
648 648 {
649`disable_paste_burst`649 key: "model_providers.<id>.env_key",
650 650 type: "string",
651Type / Values651 description: "Environment variable supplying the provider API key.",
652 652 },
653`boolean`653 {
654 654 key: "model_providers.<id>.env_key_instructions",
655Details655 type: "string",
656 656 description: "Optional setup guidance for the provider API key.",
657Disable burst-paste detection in the TUI.657 },
658 658 {
659Key659 key: "model_providers.<id>.experimental_bearer_token",
660 660 type: "string",
661`experimental_compact_prompt_file`661 description:
662 662 "Direct bearer token for the provider (discouraged; use `env_key`).",
663Type / Values663 },
664 664 {
665`string (path)`665 key: "model_providers.<id>.requires_openai_auth",
666 666 type: "boolean",
667Details667 description:
668 668 "The provider uses OpenAI authentication (defaults to false).",
669Load the compaction prompt override from a file (experimental).669 },
670 670 {
671Key671 key: "model_providers.<id>.wire_api",
672 672 type: "responses",
673`experimental_use_unified_exec_tool`673 description:
674 674 "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.",
675Type / Values675 },
676 676 {
677`boolean`677 key: "model_providers.<id>.query_params",
678 678 type: "map<string,string>",
679Details679 description: "Extra query parameters appended to provider requests.",
680 680 },
681Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.681 {
682 682 key: "model_providers.<id>.http_headers",
683Key683 type: "map<string,string>",
684 684 description: "Static HTTP headers added to provider requests.",
685`features.apps`685 },
686 686 {
687Type / Values687 key: "model_providers.<id>.env_http_headers",
688 688 type: "map<string,string>",
689`boolean`689 description:
690 690 "HTTP headers populated from environment variables when present.",
691Details691 },
692 692 {
693Enable ChatGPT Apps/connectors support (experimental).693 key: "model_providers.<id>.request_max_retries",
694 694 type: "number",
695Key695 description:
696 696 "Retry count for HTTP requests to the provider (default: 4).",
697`features.codex_hooks`697 },
698 698 {
699Type / Values699 key: "model_providers.<id>.stream_max_retries",
700 700 type: "number",
701`boolean`701 description: "Retry count for SSE streaming interruptions (default: 5).",
702 702 },
703Details703 {
704 704 key: "model_providers.<id>.stream_idle_timeout_ms",
705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.705 type: "number",
706 706 description:
707Key707 "Idle timeout for SSE streams in milliseconds (default: 300000).",
708 708 },
709`features.enable_request_compression`709 {
710 710 key: "model_providers.<id>.supports_websockets",
711Type / Values711 type: "boolean",
712 712 description:
713`boolean`713 "Whether that provider supports the Responses API WebSocket transport.",
714 714 },
715Details715 {
716 716 key: "model_providers.<id>.auth",
717Compress streaming request bodies with zstd when supported (stable; on by default).717 type: "table",
718 718 description:
719Key719 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",
720 720 },
721`features.fast_mode`721 {
722 722 key: "model_providers.<id>.auth.command",
723Type / Values723 type: "string",
724 724 description:
725`boolean`725 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",
726 726 },
727Details727 {
728 728 key: "model_providers.<id>.auth.args",
729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).729 type: "array<string>",
730 730 description: "Arguments passed to the token command.",
731Key731 },
732 732 {
733`features.memories`733 key: "model_providers.<id>.auth.timeout_ms",
734 734 type: "number",
735Type / Values735 description:
736 736 "Maximum token command runtime in milliseconds (default: 5000).",
737`boolean`737 },
738 738 {
739Details739 key: "model_providers.<id>.auth.refresh_interval_ms",
740 740 type: "number",
741Enable [Memories](https://developers.openai.com/codex/memories) (off by default).741 description:
742 742 "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.",
743Key743 },
744 744 {
745`features.multi_agent`745 key: "model_providers.<id>.auth.cwd",
746 746 type: "string (path)",
747Type / Values747 description: "Working directory for the token command.",
748 748 },
749`boolean`749 {
750 750 key: "model_providers.amazon-bedrock.aws.profile",
751Details751 type: "string",
752 752 description:
753Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).753 "AWS profile name used by the built-in `amazon-bedrock` provider.",
754 754 },
755Key755 {
756 756 key: "model_providers.amazon-bedrock.aws.region",
757`features.personality`757 type: "string",
758 758 description: "AWS region used by the built-in `amazon-bedrock` provider.",
759Type / Values759 },
760 760 {
761`boolean`761 key: "model_reasoning_effort",
762 762 type: "minimal | low | medium | high | xhigh",
763Details763 description:
764 764 "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).",
765Enable personality selection controls (stable; on by default).765 },
766 766 {
767Key767 key: "plan_mode_reasoning_effort",
768 768 type: "none | minimal | low | medium | high | xhigh",
769`features.prevent_idle_sleep`769 description:
770 770 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",
771Type / Values771 },
772 772 {
773`boolean`773 key: "model_reasoning_summary",
774 774 type: "auto | concise | detailed | none",
775Details775 description:
776 776 "Select reasoning summary detail or disable summaries entirely.",
777Prevent the machine from sleeping while a turn is actively running (experimental; off by default).777 },
778 778 {
779Key779 key: "model_verbosity",
780 780 type: "low | medium | high",
781`features.shell_snapshot`781 description:
782 782 "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.",
783Type / Values783 },
784 784 {
785`boolean`785 key: "model_supports_reasoning_summaries",
786 786 type: "boolean",
787Details787 description: "Force Codex to send or not send reasoning metadata.",
788 788 },
789Snapshot shell environment to speed up repeated commands (stable; on by default).789 {
790 790 key: "shell_environment_policy.inherit",
791Key791 type: "all | core | none",
792 792 description:
793`features.shell_tool`793 "Baseline environment inheritance when spawning subprocesses.",
794 794 },
795Type / Values795 {
796 796 key: "shell_environment_policy.ignore_default_excludes",
797`boolean`797 type: "boolean",
798 798 description:
799Details799 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",
800 800 },
801Enable the default `shell` tool for running commands (stable; on by default).801 {
802 802 key: "shell_environment_policy.exclude",
803Key803 type: "array<string>",
804 804 description:
805`features.skill_mcp_dependency_install`805 "Glob patterns for removing environment variables after the defaults.",
806 806 },
807Type / Values807 {
808 808 key: "shell_environment_policy.include_only",
809`boolean`809 type: "array<string>",
810 810 description:
811Details811 "Whitelist of patterns; when set only matching variables are kept.",
812 812 },
813Allow prompting and installing missing MCP dependencies for skills (stable; on by default).813 {
814 814 key: "shell_environment_policy.set",
815Key815 type: "map<string,string>",
816 816 description:
817`features.undo`817 "Explicit environment overrides injected into every subprocess.",
818 818 },
819Type / Values819 {
820 820 key: "shell_environment_policy.experimental_use_profile",
821`boolean`821 type: "boolean",
822 822 description: "Use the user shell profile when spawning subprocesses.",
823Details823 },
824 824 {
825Enable undo support (stable; off by default).825 key: "project_root_markers",
826 826 type: "array<string>",
827Key827 description:
828 828 "List of project root marker filenames; used when searching parent directories for the project root.",
829`features.unified_exec`829 },
830 830 {
831Type / Values831 key: "project_doc_max_bytes",
832 832 type: "number",
833`boolean`833 description:
834 834 "Maximum bytes read from `AGENTS.md` when building project instructions.",
835Details835 },
836 836 {
837Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).837 key: "project_doc_fallback_filenames",
838 838 type: "array<string>",
839Key839 description: "Additional filenames to try when `AGENTS.md` is missing.",
840 840 },
841`features.web_search`841 {
842 842 key: "profile",
843Type / Values843 type: "string",
844 844 description:
845`boolean`845 "Default profile applied at startup (equivalent to `--profile`).",
846 846 },
847Details847 {
848 848 key: "profiles.<name>.*",
849Deprecated legacy toggle; prefer the top-level `web_search` setting.849 type: "various",
850 850 description:
851Key851 "Profile-scoped overrides for any of the supported configuration keys.",
852 852 },
853`features.web_search_cached`853 {
854 854 key: "profiles.<name>.service_tier",
855Type / Values855 type: "flex | fast",
856 856 description: "Profile-scoped service tier preference for new turns.",
857`boolean`857 },
858 858 {
859Details859 key: "profiles.<name>.plan_mode_reasoning_effort",
860 860 type: "none | minimal | low | medium | high | xhigh",
861Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.861 description: "Profile-scoped Plan-mode reasoning override.",
862 862 },
863Key863 {
864 864 key: "profiles.<name>.web_search",
865`features.web_search_request`865 type: "disabled | cached | live",
866 866 description:
867Type / Values867 'Profile-scoped web search mode override (default: `"cached"`).',
868 868 },
869`boolean`869 {
870 870 key: "profiles.<name>.personality",
871Details871 type: "none | friendly | pragmatic",
872 872 description:
873Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.873 "Profile-scoped communication style override for supported models.",
874 874 },
875Key875 {
876 876 key: "profiles.<name>.model_catalog_json",
877`feedback.enabled`877 type: "string (path)",
878 878 description:
879Type / Values879 "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).",
880 880 },
881`boolean`881 {
882 882 key: "profiles.<name>.model_instructions_file",
883Details883 type: "string (path)",
884 884 description:
885Enable feedback submission via `/feedback` across Codex surfaces (default: true).885 "Profile-scoped replacement for the built-in instruction file.",
886 886 },
887Key887 {
888 888 key: "profiles.<name>.experimental_use_unified_exec_tool",
889`file_opener`889 type: "boolean",
890 890 description:
891Type / Values891 "Legacy name for enabling unified exec; prefer `[features].unified_exec`.",
892 892 },
893`vscode | vscode-insiders | windsurf | cursor | none`893 {
894 894 key: "profiles.<name>.oss_provider",
895Details895 type: "lmstudio | ollama",
896 896 description: "Profile-scoped OSS provider for `--oss` sessions.",
897URI scheme used to open citations from Codex output (default: `vscode`).897 },
898 898 {
899Key899 key: "profiles.<name>.tools_view_image",
900 900 type: "boolean",
901`forced_chatgpt_workspace_id`901 description: "Enable or disable the `view_image` tool in that profile.",
902 902 },
903Type / Values903 {
904 904 key: "profiles.<name>.analytics.enabled",
905`string (uuid)`905 type: "boolean",
906 906 description: "Profile-scoped analytics enablement override.",
907Details907 },
908 908 {
909Limit ChatGPT logins to a specific workspace identifier.909 key: "profiles.<name>.windows.sandbox",
910 910 type: "unelevated | elevated",
911Key911 description: "Profile-scoped Windows sandbox mode override.",
912 912 },
913`forced_login_method`913 {
914 914 key: "history.persistence",
915Type / Values915 type: "save-all | none",
916 916 description:
917`chatgpt | api`917 "Control whether Codex saves session transcripts to history.jsonl.",
918 918 },
919Details919 {
920 920 key: "tool_output_token_limit",
921Restrict Codex to a specific authentication method.921 type: "number",
922 922 description:
923Key923 "Token budget for storing individual tool/function outputs in history.",
924 924 },
925`hide_agent_reasoning`925 {
926 926 key: "background_terminal_max_timeout",
927Type / Values927 type: "number",
928 928 description:
929`boolean`929 "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.",
930 930 },
931Details931 {
932 932 key: "history.max_bytes",
933Suppress reasoning events in both the TUI and `codex exec` output.933 type: "number",
934 934 description:
935Key935 "If set, caps the history file size in bytes by dropping oldest entries.",
936 936 },
937`history.max_bytes`937 {
938 938 key: "file_opener",
939Type / Values939 type: "vscode | vscode-insiders | windsurf | cursor | none",
940 940 description:
941`number`941 "URI scheme used to open citations from Codex output (default: `vscode`).",
942 942 },
943Details943 {
944 944 key: "otel.environment",
945If set, caps the history file size in bytes by dropping oldest entries.945 type: "string",
946 946 description:
947Key947 "Environment tag applied to emitted OpenTelemetry events (default: `dev`).",
948 948 },
949`history.persistence`949 {
950 950 key: "otel.exporter",
951Type / Values951 type: "none | otlp-http | otlp-grpc",
952 952 description:
953`save-all | none`953 "Select the OpenTelemetry exporter and provide any endpoint metadata.",
954 954 },
955Details955 {
956 956 key: "otel.trace_exporter",
957Control whether Codex saves session transcripts to history.jsonl.957 type: "none | otlp-http | otlp-grpc",
958 958 description:
959Key959 "Select the OpenTelemetry trace exporter and provide any endpoint metadata.",
960 960 },
961`hooks`961 {
962 962 key: "otel.metrics_exporter",
963Type / Values963 type: "none | statsig | otlp-http | otlp-grpc",
964 964 description:
965`table`965 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",
966 966 },
967Details967 {
968 968 key: "otel.log_user_prompt",
969Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.969 type: "boolean",
970 970 description:
971Key971 "Opt in to exporting raw user prompts with OpenTelemetry logs.",
972 972 },
973`instructions`973 {
974 974 key: "otel.exporter.<id>.endpoint",
975Type / Values975 type: "string",
976 976 description: "Exporter endpoint for OTEL logs.",
977`string`977 },
978 978 {
979Details979 key: "otel.exporter.<id>.protocol",
980 980 type: "binary | json",
981Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.981 description: "Protocol used by the OTLP/HTTP exporter.",
982 982 },
983Key983 {
984 984 key: "otel.exporter.<id>.headers",
985`log_dir`985 type: "map<string,string>",
986 986 description: "Static headers included with OTEL exporter requests.",
987Type / Values987 },
988 988 {
989`string (path)`989 key: "otel.trace_exporter.<id>.endpoint",
990 990 type: "string",
991Details991 description: "Trace exporter endpoint for OTEL logs.",
992 992 },
993Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.993 {
994 994 key: "otel.trace_exporter.<id>.protocol",
995Key995 type: "binary | json",
996 996 description: "Protocol used by the OTLP/HTTP trace exporter.",
997`mcp_oauth_callback_port`997 },
998 998 {
999Type / Values999 key: "otel.trace_exporter.<id>.headers",
1000 1000 type: "map<string,string>",
1001`integer`1001 description: "Static headers included with OTEL trace exporter requests.",
1002 1002 },
1003Details1003 {
1004 1004 key: "otel.exporter.<id>.tls.ca-certificate",
1005Optional 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.1005 type: "string",
1006 1006 description: "CA certificate path for OTEL exporter TLS.",
1007Key1007 },
1008 1008 {
1009`mcp_oauth_callback_url`1009 key: "otel.exporter.<id>.tls.client-certificate",
1010 1010 type: "string",
1011Type / Values1011 description: "Client certificate path for OTEL exporter TLS.",
1012 1012 },
1013`string`1013 {
1014 1014 key: "otel.exporter.<id>.tls.client-private-key",
1015Details1015 type: "string",
1016 1016 description: "Client private key path for OTEL exporter TLS.",
1017Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.1017 },
1018 1018 {
1019Key1019 key: "otel.trace_exporter.<id>.tls.ca-certificate",
1020 1020 type: "string",
1021`mcp_oauth_credentials_store`1021 description: "CA certificate path for OTEL trace exporter TLS.",
1022 1022 },
1023Type / Values1023 {
1024 1024 key: "otel.trace_exporter.<id>.tls.client-certificate",
1025`auto | file | keyring`1025 type: "string",
1026 1026 description: "Client certificate path for OTEL trace exporter TLS.",
1027Details1027 },
1028 1028 {
1029Preferred store for MCP OAuth credentials.1029 key: "otel.trace_exporter.<id>.tls.client-private-key",
1030 1030 type: "string",
1031Key1031 description: "Client private key path for OTEL trace exporter TLS.",
1032 1032 },
1033`mcp_servers.<id>.args`1033 {
1034 1034 key: "tui",
1035Type / Values1035 type: "table",
1036 1036 description:
1037`array<string>`1037 "TUI-specific options such as enabling inline desktop notifications.",
1038 1038 },
1039Details1039 {
1040 1040 key: "tui.notifications",
1041Arguments passed to the MCP stdio server command.1041 type: "boolean | array<string>",
1042 1042 description:
1043Key1043 "Enable TUI notifications; optionally restrict to specific event types.",
1044 1044 },
1045`mcp_servers.<id>.bearer_token_env_var`1045 {
1046 1046 key: "tui.notification_method",
1047Type / Values1047 type: "auto | osc9 | bel",
1048 1048 description:
1049`string`1049 "Notification method for terminal notifications (default: auto).",
1050 1050 },
1051Details1051 {
1052 1052 key: "tui.notification_condition",
1053Environment variable sourcing the bearer token for an MCP HTTP server.1053 type: "unfocused | always",
1054 1054 description:
1055Key1055 "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.",
1056 1056 },
1057`mcp_servers.<id>.command`1057 {
1058 1058 key: "tui.animations",
1059Type / Values1059 type: "boolean",
1060 1060 description:
1061`string`1061 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",
1062 1062 },
1063Details1063 {
1064 1064 key: "tui.alternate_screen",
1065Launcher command for an MCP stdio server.1065 type: "auto | always | never",
1066 1066 description:
1067Key1067 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1068 1068 },
1069`mcp_servers.<id>.cwd`1069 {
1070 1070 key: "tui.show_tooltips",
1071Type / Values1071 type: "boolean",
1072 1072 description:
1073`string`1073 "Show onboarding tooltips in the TUI welcome screen (default: true).",
1074 1074 },
1075Details1075 {
1076 1076 key: "tui.status_line",
1077Working directory for the MCP stdio server process.1077 type: "array<string> | null",
1078 1078 description:
1079Key1079 "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.",
1080 1080 },
1081`mcp_servers.<id>.disabled_tools`1081 {
1082 1082 key: "tui.terminal_title",
1083Type / Values1083 type: "array<string> | null",
1084 1084 description:
1085`array<string>`1085 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.',
1086 1086 },
1087Details1087 {
1088 1088 key: "tui.theme",
1089Deny list applied after `enabled_tools` for the MCP server.1089 type: "string",
1090 1090 description:
1091Key1091 "Syntax-highlighting theme override (kebab-case theme name).",
1092 1092 },
1093`mcp_servers.<id>.enabled`1093 {
1094 1094 key: "tui.keymap.<context>.<action>",
1095Type / Values1095 type: "string | array<string>",
1096 1096 description:
1097`boolean`1097 "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`.",
1098 1098 },
1099Details1099 {
1100 1100 key: "tui.keymap.<context>.<action> = []",
1101Disable an MCP server without removing its configuration.1101 type: "empty array",
1102 1102 description:
1103Key1103 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.",
1104 1104 },
1105`mcp_servers.<id>.enabled_tools`1105 {
1106 1106 key: "tui.model_availability_nux.<model>",
1107Type / Values1107 type: "integer",
1108 1108 description: "Internal startup-tooltip state keyed by model slug.",
1109`array<string>`1109 },
1110 1110 {
1111Details1111 key: "hide_agent_reasoning",
1112 1112 type: "boolean",
1113Allow list of tool names exposed by the MCP server.1113 description:
1114 1114 "Suppress reasoning events in both the TUI and `codex exec` output.",
1115Key1115 },
1116 1116 {
1117`mcp_servers.<id>.env`1117 key: "show_raw_agent_reasoning",
1118 1118 type: "boolean",
1119Type / Values1119 description:
1120 1120 "Surface raw reasoning content when the active model emits it.",
1121`map<string,string>`1121 },
1122 1122 {
1123Details1123 key: "disable_paste_burst",
1124 1124 type: "boolean",
1125Environment variables forwarded to the MCP stdio server.1125 description: "Disable burst-paste detection in the TUI.",
1126 1126 },
1127Key1127 {
1128 1128 key: "windows_wsl_setup_acknowledged",
1129`mcp_servers.<id>.env_http_headers`1129 type: "boolean",
1130 1130 description: "Track Windows onboarding acknowledgement (Windows only).",
1131Type / Values1131 },
1132 1132 {
1133`map<string,string>`1133 key: "chatgpt_base_url",
1134 1134 type: "string",
1135Details1135 description: "Override the base URL used during the ChatGPT login flow.",
1136 1136 },
1137HTTP headers populated from environment variables for an MCP HTTP server.1137 {
1138 1138 key: "cli_auth_credentials_store",
1139Key1139 type: "file | keyring | auto",
1140 1140 description:
1141`mcp_servers.<id>.env_vars`1141 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",
1142 1142 },
1143Type / Values1143 {
1144 1144 key: "mcp_oauth_credentials_store",
1145`array<string | { name = string, source = "local" | "remote" }>`1145 type: "auto | file | keyring",
1146 1146 description: "Preferred store for MCP OAuth credentials.",
1147Details1147 },
1148 1148 {
1149Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.1149 key: "mcp_oauth_callback_port",
1150 1150 type: "integer",
1151Key1151 description:
1152 1152 "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.",
1153`mcp_servers.<id>.experimental_environment`1153 },
1154 1154 {
1155Type / Values1155 key: "mcp_oauth_callback_url",
1156 1156 type: "string",
1157`local | remote`1157 description:
1158 1158 "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.",
1159Details1159 },
1160 1160 {
1161Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.1161 key: "experimental_use_unified_exec_tool",
1162 1162 type: "boolean",
1163Key1163 description:
1164 1164 "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.",
1165`mcp_servers.<id>.http_headers`1165 },
1166 1166 {
1167Type / Values1167 key: "tools.web_search",
1168 1168 type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }',
1169`map<string,string>`1169 description:
1170 1170 "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.",
1171Details1171 },
1172 1172 {
1173Static HTTP headers included with each MCP HTTP request.1173 key: "tools.view_image",
1174 1174 type: "boolean",
1175Key1175 description: "Enable the local-image attachment tool `view_image`.",
1176 1176 },
1177`mcp_servers.<id>.oauth_resource`1177 {
1178 1178 key: "web_search",
1179Type / Values1179 type: "disabled | cached | live",
1180 1180 description:
1181`string`1181 '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.',
1182 1182 },
1183Details1183 {
1184 1184 key: "default_permissions",
1185Optional RFC 8707 OAuth resource parameter to include during MCP login.1185 type: "string",
1186 1186 description:
1187Key1187 "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.",
1188 1188 },
1189`mcp_servers.<id>.required`1189 {
1190 1190 key: "permissions.<name>.filesystem",
1191Type / Values1191 type: "table",
1192 1192 description:
1193`boolean`1193 "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.",
1194 1194 },
1195Details1195 {
1196 1196 key: "permissions.<name>.filesystem.glob_scan_max_depth",
1197When true, fail startup/resume if this enabled MCP server cannot initialize.1197 type: "number",
1198 1198 description:
1199Key1199 "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.",
1200 1200 },
1201`mcp_servers.<id>.scopes`1201 {
1202 1202 key: "permissions.<name>.filesystem.<path-or-glob>",
1203Type / Values1203 type: '"read" | "write" | "none" | table',
1204 1204 description:
1205`array<string>`1205 '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.',
1206 1206 },
1207Details1207 {
1208 1208 key: 'permissions.<name>.filesystem.":project_roots".<subpath-or-glob>',
1209OAuth scopes to request when authenticating to that MCP server.1209 type: '"read" | "write" | "none"',
1210 1210 description:
1211Key1211 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.',
1212 1212 },
1213`mcp_servers.<id>.startup_timeout_ms`1213 {
1214 1214 key: "permissions.<name>.network.enabled",
1215Type / Values1215 type: "boolean",
1216 1216 description: "Enable network access for this named permissions profile.",
1217`number`1217 },
1218 1218 {
1219Details1219 key: "permissions.<name>.network.proxy_url",
1220 1220 type: "string",
1221Alias for `startup_timeout_sec` in milliseconds.1221 description:
1222 1222 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.",
1223Key1223 },
1224 1224 {
1225`mcp_servers.<id>.startup_timeout_sec`1225 key: "permissions.<name>.network.enable_socks5",
1226 1226 type: "boolean",
1227Type / Values1227 description:
1228 1228 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.",
1229`number`1229 },
1230 1230 {
1231Details1231 key: "permissions.<name>.network.socks_url",
1232 1232 type: "string",
1233Override the default 10s startup timeout for an MCP server.1233 description: "SOCKS5 proxy endpoint used by this permissions profile.",
1234 1234 },
1235Key1235 {
1236 1236 key: "permissions.<name>.network.enable_socks5_udp",
1237`mcp_servers.<id>.tool_timeout_sec`1237 type: "boolean",
1238 1238 description: "Allow UDP over the SOCKS5 listener when enabled.",
1239Type / Values1239 },
1240 1240 {
1241`number`1241 key: "permissions.<name>.network.allow_upstream_proxy",
1242 1242 type: "boolean",
1243Details1243 description:
1244 1244 "Allow the managed proxy to chain to another upstream proxy.",
1245Override the default 60s per-tool timeout for an MCP server.1245 },
1246 1246 {
1247Key1247 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1248 1248 type: "boolean",
1249`mcp_servers.<id>.url`1249 description:
1250 1250 "Permit non-loopback bind addresses for the managed proxy listener.",
1251Type / Values1251 },
1252 1252 {
1253`string`1253 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1254 1254 type: "boolean",
1255Details1255 description:
1256 1256 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.",
1257Endpoint for an MCP streamable HTTP server.1257 },
1258 1258 {
1259Key1259 key: "permissions.<name>.network.mode",
1260 1260 type: "limited | full",
1261`memories.consolidation_model`1261 description: "Network proxy mode used for subprocess traffic.",
1262 1262 },
1263Type / Values1263 {
1264 1264 key: "permissions.<name>.network.domains",
1265`string`1265 type: "map<string, allow | deny>",
1266 1266 description:
1267Details1267 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.",
1268 1268 },
1269Optional model override for global memory consolidation.1269 {
1270 1270 key: "permissions.<name>.network.unix_sockets",
1271Key1271 type: "map<string, allow | none>",
1272 1272 description:
1273`memories.disable_on_external_context`1273 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.",
1274 1274 },
1275Type / Values1275 {
1276 1276 key: "permissions.<name>.network.allow_local_binding",
1277`boolean`1277 type: "boolean",
1278 1278 description:
1279Details1279 "Permit local bind/listen operations through the managed proxy.",
1280 1280 },
1281When `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`.1281 {
1282 1282 key: "projects.<path>.trust_level",
1283Key1283 type: "string",
1284 1284 description:
1285`memories.extract_model`1285 '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.',
1286 1286 },
1287Type / Values1287 {
1288 1288 key: "notice.hide_full_access_warning",
1289`string`1289 type: "boolean",
1290 1290 description: "Track acknowledgement of the full access warning prompt.",
1291Details1291 },
1292 1292 {
1293Optional model override for per-thread memory extraction.1293 key: "notice.hide_world_writable_warning",
1294 1294 type: "boolean",
1295Key1295 description:
1296 1296 "Track acknowledgement of the Windows world-writable directories warning.",
1297`memories.generate_memories`1297 },
1298 1298 {
1299Type / Values1299 key: "notice.hide_rate_limit_model_nudge",
1300 1300 type: "boolean",
1301`boolean`1301 description: "Track opt-out of the rate limit model switch reminder.",
1302 1302 },
1303Details1303 {
1304 1304 key: "notice.hide_gpt5_1_migration_prompt",
1305When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.1305 type: "boolean",
1306 1306 description: "Track acknowledgement of the GPT-5.1 migration prompt.",
1307Key1307 },
1308 1308 {
1309`memories.max_raw_memories_for_consolidation`1309 key: "notice.hide_gpt-5.1-codex-max_migration_prompt",
1310 1310 type: "boolean",
1311Type / Values1311 description:
1312 1312 "Track acknowledgement of the gpt-5.1-codex-max migration prompt.",
1313`number`1313 },
1314 1314 {
1315Details1315 key: "notice.model_migrations",
1316 1316 type: "map<string,string>",
1317Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.1317 description: "Track acknowledged model migrations as old->new mappings.",
1318 1318 },
1319Key1319 {
1320 1320 key: "forced_login_method",
1321`memories.max_rollout_age_days`1321 type: "chatgpt | api",
1322 1322 description: "Restrict Codex to a specific authentication method.",
1323Type / Values1323 },
1324 1324 {
1325`number`1325 key: "forced_chatgpt_workspace_id",
1326 1326 type: "string (uuid)",
1327Details1327 description: "Limit ChatGPT logins to a specific workspace identifier.",
1328 1328 },
1329Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.1329 ]}
1330 1330 client:load
1331Key1331/>
1332
1333`memories.max_rollouts_per_startup`
1334
1335Type / Values
1336
1337`number`
1338
1339Details
1340
1341Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.
1342
1343Key
1344
1345`memories.max_unused_days`
1346
1347Type / Values
1348
1349`number`
1350
1351Details
1352
1353Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.
1354
1355Key
1356
1357`memories.min_rollout_idle_hours`
1358
1359Type / Values
1360
1361`number`
1362
1363Details
1364
1365Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.
1366
1367Key
1368
1369`memories.use_memories`
1370
1371Type / Values
1372
1373`boolean`
1374
1375Details
1376
1377When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.
1378
1379Key
1380
1381`model`
1382
1383Type / Values
1384
1385`string`
1386
1387Details
1388
1389Model to use (e.g., `gpt-5.5`).
1390
1391Key
1392
1393`model_auto_compact_token_limit`
1394
1395Type / Values
1396
1397`number`
1398
1399Details
1400
1401Token threshold that triggers automatic history compaction (unset uses model defaults).
1402
1403Key
1404
1405`model_catalog_json`
1406
1407Type / Values
1408
1409`string (path)`
1410
1411Details
1412
1413Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.
1414
1415Key
1416
1417`model_context_window`
1418
1419Type / Values
1420
1421`number`
1422
1423Details
1424
1425Context window tokens available to the active model.
1426
1427Key
1428
1429`model_instructions_file`
1430
1431Type / Values
1432
1433`string (path)`
1434
1435Details
1436
1437Replacement for built-in instructions instead of `AGENTS.md`.
1438
1439Key
1440
1441`model_provider`
1442
1443Type / Values
1444
1445`string`
1446
1447Details
1448
1449Provider id from `model_providers` (default: `openai`).
1450
1451Key
1452
1453`model_providers.<id>`
1454
1455Type / Values
1456
1457`table`
1458
1459Details
1460
1461Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.
1462
1463Key
1464
1465`model_providers.<id>.auth`
1466
1467Type / Values
1468
1469`table`
1470
1471Details
1472
1473Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.
1474
1475Key
1476
1477`model_providers.<id>.auth.args`
1478
1479Type / Values
1480
1481`array<string>`
1482
1483Details
1484
1485Arguments passed to the token command.
1486
1487Key
1488
1489`model_providers.<id>.auth.command`
1490
1491Type / Values
1492
1493`string`
1494
1495Details
1496
1497Command to run when Codex needs a bearer token. The command must print the token to stdout.
1498
1499Key
1500
1501`model_providers.<id>.auth.cwd`
1502
1503Type / Values
1504
1505`string (path)`
1506
1507Details
1508
1509Working directory for the token command.
1510
1511Key
1512
1513`model_providers.<id>.auth.refresh_interval_ms`
1514
1515Type / Values
1516
1517`number`
1518
1519Details
1520
1521How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.
1522
1523Key
1524
1525`model_providers.<id>.auth.timeout_ms`
1526
1527Type / Values
1528
1529`number`
1530
1531Details
1532
1533Maximum token command runtime in milliseconds (default: 5000).
1534
1535Key
1536
1537`model_providers.<id>.base_url`
1538
1539Type / Values
1540
1541`string`
1542
1543Details
1544
1545API base URL for the model provider.
1546
1547Key
1548
1549`model_providers.<id>.env_http_headers`
1550
1551Type / Values
1552
1553`map<string,string>`
1554
1555Details
1556
1557HTTP headers populated from environment variables when present.
1558
1559Key
1560
1561`model_providers.<id>.env_key`
1562
1563Type / Values
1564
1565`string`
1566
1567Details
1568
1569Environment variable supplying the provider API key.
1570
1571Key
1572
1573`model_providers.<id>.env_key_instructions`
1574
1575Type / Values
1576
1577`string`
1578
1579Details
1580
1581Optional setup guidance for the provider API key.
1582
1583Key
1584
1585`model_providers.<id>.experimental_bearer_token`
1586
1587Type / Values
1588
1589`string`
1590
1591Details
1592
1593Direct bearer token for the provider (discouraged; use `env_key`).
1594
1595Key
1596
1597`model_providers.<id>.http_headers`
1598
1599Type / Values
1600
1601`map<string,string>`
1602
1603Details
1604
1605Static HTTP headers added to provider requests.
1606
1607Key
1608
1609`model_providers.<id>.name`
1610
1611Type / Values
1612
1613`string`
1614
1615Details
1616
1617Display name for a custom model provider.
1618
1619Key
1620
1621`model_providers.<id>.query_params`
1622
1623Type / Values
1624
1625`map<string,string>`
1626
1627Details
1628
1629Extra query parameters appended to provider requests.
1630
1631Key
1632
1633`model_providers.<id>.request_max_retries`
1634
1635Type / Values
1636
1637`number`
1638
1639Details
1640
1641Retry count for HTTP requests to the provider (default: 4).
1642
1643Key
1644
1645`model_providers.<id>.requires_openai_auth`
1646
1647Type / Values
1648
1649`boolean`
1650
1651Details
1652
1653The provider uses OpenAI authentication (defaults to false).
1654
1655Key
1656
1657`model_providers.<id>.stream_idle_timeout_ms`
1658
1659Type / Values
1660
1661`number`
1662
1663Details
1664
1665Idle timeout for SSE streams in milliseconds (default: 300000).
1666
1667Key
1668
1669`model_providers.<id>.stream_max_retries`
1670
1671Type / Values
1672
1673`number`
1674
1675Details
1676
1677Retry count for SSE streaming interruptions (default: 5).
1678
1679Key
1680
1681`model_providers.<id>.supports_websockets`
1682
1683Type / Values
1684
1685`boolean`
1686
1687Details
1688
1689Whether that provider supports the Responses API WebSocket transport.
1690
1691Key
1692
1693`model_providers.<id>.wire_api`
1694
1695Type / Values
1696
1697`responses`
1698
1699Details
1700
1701Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.
1702
1703Key
1704
1705`model_reasoning_effort`
1706
1707Type / Values
1708
1709`minimal | low | medium | high | xhigh`
1710
1711Details
1712
1713Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
1714
1715Key
1716
1717`model_reasoning_summary`
1718
1719Type / Values
1720
1721`auto | concise | detailed | none`
1722
1723Details
1724
1725Select reasoning summary detail or disable summaries entirely.
1726
1727Key
1728
1729`model_supports_reasoning_summaries`
1730
1731Type / Values
1732
1733`boolean`
1734
1735Details
1736
1737Force Codex to send or not send reasoning metadata.
1738
1739Key
1740
1741`model_verbosity`
1742
1743Type / Values
1744
1745`low | medium | high`
1746
1747Details
1748
1749Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.
1750
1751Key
1752
1753`notice.hide_full_access_warning`
1754
1755Type / Values
1756
1757`boolean`
1758
1759Details
1760
1761Track acknowledgement of the full access warning prompt.
1762
1763Key
1764
1765`notice.hide_gpt-5.1-codex-max_migration_prompt`
1766
1767Type / Values
1768
1769`boolean`
1770
1771Details
1772
1773Track acknowledgement of the gpt-5.1-codex-max migration prompt.
1774
1775Key
1776
1777`notice.hide_gpt5_1_migration_prompt`
1778
1779Type / Values
1780
1781`boolean`
1782
1783Details
1784
1785Track acknowledgement of the GPT-5.1 migration prompt.
1786
1787Key
1788
1789`notice.hide_rate_limit_model_nudge`
1790
1791Type / Values
1792
1793`boolean`
1794
1795Details
1796
1797Track opt-out of the rate limit model switch reminder.
1798
1799Key
1800
1801`notice.hide_world_writable_warning`
1802
1803Type / Values
1804
1805`boolean`
1806
1807Details
1808
1809Track acknowledgement of the Windows world-writable directories warning.
1810
1811Key
1812
1813`notice.model_migrations`
1814
1815Type / Values
1816
1817`map<string,string>`
1818
1819Details
1820
1821Track acknowledged model migrations as old->new mappings.
1822
1823Key
1824
1825`notify`
1826
1827Type / Values
1828
1829`array<string>`
1830
1831Details
1832
1833Command invoked for notifications; receives a JSON payload from Codex.
1834
1835Key
1836
1837`openai_base_url`
1838
1839Type / Values
1840
1841`string`
1842
1843Details
1844
1845Base URL override for the built-in `openai` model provider.
1846
1847Key
1848
1849`oss_provider`
1850
1851Type / Values
1852
1853`lmstudio | ollama`
1854
1855Details
1856
1857Default local provider used when running with `--oss` (defaults to prompting if unset).
1858
1859Key
1860
1861`otel.environment`
1862
1863Type / Values
1864
1865`string`
1866
1867Details
1868
1869Environment tag applied to emitted OpenTelemetry events (default: `dev`).
1870
1871Key
1872
1873`otel.exporter`
1874
1875Type / Values
1876
1877`none | otlp-http | otlp-grpc`
1878
1879Details
1880
1881Select the OpenTelemetry exporter and provide any endpoint metadata.
1882
1883Key
1884
1885`otel.exporter.<id>.endpoint`
1886
1887Type / Values
1888
1889`string`
1890
1891Details
1892
1893Exporter endpoint for OTEL logs.
1894
1895Key
1896
1897`otel.exporter.<id>.headers`
1898
1899Type / Values
1900
1901`map<string,string>`
1902
1903Details
1904
1905Static headers included with OTEL exporter requests.
1906
1907Key
1908
1909`otel.exporter.<id>.protocol`
1910
1911Type / Values
1912
1913`binary | json`
1914
1915Details
1916
1917Protocol used by the OTLP/HTTP exporter.
1918
1919Key
1920
1921`otel.exporter.<id>.tls.ca-certificate`
1922
1923Type / Values
1924
1925`string`
1926
1927Details
1928
1929CA certificate path for OTEL exporter TLS.
1930
1931Key
1932
1933`otel.exporter.<id>.tls.client-certificate`
1934
1935Type / Values
1936
1937`string`
1938
1939Details
1940
1941Client certificate path for OTEL exporter TLS.
1942
1943Key
1944
1945`otel.exporter.<id>.tls.client-private-key`
1946
1947Type / Values
1948
1949`string`
1950
1951Details
1952
1953Client private key path for OTEL exporter TLS.
1954
1955Key
1956
1957`otel.log_user_prompt`
1958
1959Type / Values
1960
1961`boolean`
1962
1963Details
1964
1965Opt in to exporting raw user prompts with OpenTelemetry logs.
1966
1967Key
1968
1969`otel.metrics_exporter`
1970
1971Type / Values
1972
1973`none | statsig | otlp-http | otlp-grpc`
1974
1975Details
1976
1977Select the OpenTelemetry metrics exporter (defaults to `statsig`).
1978
1979Key
1980
1981`otel.trace_exporter`
1982
1983Type / Values
1984
1985`none | otlp-http | otlp-grpc`
1986
1987Details
1988
1989Select the OpenTelemetry trace exporter and provide any endpoint metadata.
1990
1991Key
1992
1993`otel.trace_exporter.<id>.endpoint`
1994
1995Type / Values
1996
1997`string`
1998
1999Details
2000
2001Trace exporter endpoint for OTEL logs.
2002
2003Key
2004
2005`otel.trace_exporter.<id>.headers`
2006
2007Type / Values
2008
2009`map<string,string>`
2010
2011Details
2012
2013Static headers included with OTEL trace exporter requests.
2014
2015Key
2016
2017`otel.trace_exporter.<id>.protocol`
2018
2019Type / Values
2020
2021`binary | json`
2022
2023Details
2024
2025Protocol used by the OTLP/HTTP trace exporter.
2026
2027Key
2028
2029`otel.trace_exporter.<id>.tls.ca-certificate`
2030
2031Type / Values
2032
2033`string`
2034
2035Details
2036
2037CA certificate path for OTEL trace exporter TLS.
2038
2039Key
2040
2041`otel.trace_exporter.<id>.tls.client-certificate`
2042
2043Type / Values
2044
2045`string`
2046
2047Details
2048
2049Client certificate path for OTEL trace exporter TLS.
2050
2051Key
2052
2053`otel.trace_exporter.<id>.tls.client-private-key`
2054
2055Type / Values
2056
2057`string`
2058
2059Details
2060
2061Client private key path for OTEL trace exporter TLS.
2062
2063Key
2064
2065`permissions.<name>.filesystem`
2066
2067Type / Values
2068
2069`table`
2070
2071Details
2072
2073Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.
2074
2075Key
2076
2077`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`
2078
2079Type / Values
2080
2081`"read" | "write" | "none"`
2082
2083Details
2084
2085Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.
2086
2087Key
2088
2089`permissions.<name>.filesystem.<path-or-glob>`
2090
2091Type / Values
2092
2093`"read" | "write" | "none" | table`
2094
2095Details
2096
2097Grant 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.
2098
2099Key
2100
2101`permissions.<name>.filesystem.glob_scan_max_depth`
2102
2103Type / Values
2104
2105`number`
2106
2107Details
2108
2109Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.
2110
2111Key
2112
2113`permissions.<name>.network.allow_local_binding`
2114
2115Type / Values
2116
2117`boolean`
2118
2119Details
2120
2121Permit local bind/listen operations through the managed proxy.
2122
2123Key
2124
2125`permissions.<name>.network.allow_upstream_proxy`
2126
2127Type / Values
2128
2129`boolean`
2130
2131Details
2132
2133Allow the managed proxy to chain to another upstream proxy.
2134
2135Key
2136
2137`permissions.<name>.network.dangerously_allow_all_unix_sockets`
2138
2139Type / Values
2140
2141`boolean`
2142
2143Details
2144
2145Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.
2146
2147Key
2148
2149`permissions.<name>.network.dangerously_allow_non_loopback_proxy`
2150
2151Type / Values
2152
2153`boolean`
2154
2155Details
2156
2157Permit non-loopback bind addresses for the managed proxy listener.
2158
2159Key
2160
2161`permissions.<name>.network.domains`
2162
2163Type / Values
2164
2165`map<string, allow | deny>`
2166
2167Details
2168
2169Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.
2170
2171Key
2172
2173`permissions.<name>.network.enable_socks5`
2174
2175Type / Values
2176
2177`boolean`
2178
2179Details
2180
2181Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.
2182
2183Key
2184
2185`permissions.<name>.network.enable_socks5_udp`
2186
2187Type / Values
2188
2189`boolean`
2190
2191Details
2192
2193Allow UDP over the SOCKS5 listener when enabled.
2194
2195Key
2196
2197`permissions.<name>.network.enabled`
2198
2199Type / Values
2200
2201`boolean`
2202
2203Details
2204
2205Enable network access for this named permissions profile.
2206
2207Key
2208
2209`permissions.<name>.network.mode`
2210
2211Type / Values
2212
2213`limited | full`
2214
2215Details
2216
2217Network proxy mode used for subprocess traffic.
2218
2219Key
2220
2221`permissions.<name>.network.proxy_url`
2222
2223Type / Values
2224
2225`string`
2226
2227Details
2228
2229HTTP proxy endpoint used when this permissions profile enables the managed network proxy.
2230
2231Key
2232
2233`permissions.<name>.network.socks_url`
2234
2235Type / Values
2236
2237`string`
2238
2239Details
2240
2241SOCKS5 proxy endpoint used by this permissions profile.
2242
2243Key
2244
2245`permissions.<name>.network.unix_sockets`
2246
2247Type / Values
2248
2249`map<string, allow | none>`
2250
2251Details
2252
2253Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.
2254
2255Key
2256
2257`personality`
2258
2259Type / Values
2260
2261`none | friendly | pragmatic`
2262
2263Details
2264
2265Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
2266
2267Key
2268
2269`plan_mode_reasoning_effort`
2270
2271Type / Values
2272
2273`none | minimal | low | medium | high | xhigh`
2274
2275Details
2276
2277Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.
2278
2279Key
2280
2281`profile`
2282
2283Type / Values
2284
2285`string`
2286
2287Details
2288
2289Default profile applied at startup (equivalent to `--profile`).
2290
2291Key
2292
2293`profiles.<name>.*`
2294
2295Type / Values
2296
2297`various`
2298
2299Details
2300
2301Profile-scoped overrides for any of the supported configuration keys.
2302
2303Key
2304
2305`profiles.<name>.analytics.enabled`
2306
2307Type / Values
2308
2309`boolean`
2310
2311Details
2312
2313Profile-scoped analytics enablement override.
2314
2315Key
2316
2317`profiles.<name>.experimental_use_unified_exec_tool`
2318
2319Type / Values
2320
2321`boolean`
2322
2323Details
2324
2325Legacy name for enabling unified exec; prefer `[features].unified_exec`.
2326
2327Key
2328
2329`profiles.<name>.model_catalog_json`
2330
2331Type / Values
2332
2333`string (path)`
2334
2335Details
2336
2337Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).
2338
2339Key
2340
2341`profiles.<name>.model_instructions_file`
2342
2343Type / Values
2344
2345`string (path)`
2346
2347Details
2348
2349Profile-scoped replacement for the built-in instruction file.
2350
2351Key
2352
2353`profiles.<name>.oss_provider`
2354
2355Type / Values
2356
2357`lmstudio | ollama`
2358
2359Details
2360
2361Profile-scoped OSS provider for `--oss` sessions.
2362
2363Key
2364
2365`profiles.<name>.personality`
2366
2367Type / Values
2368
2369`none | friendly | pragmatic`
2370
2371Details
2372
2373Profile-scoped communication style override for supported models.
2374
2375Key
2376
2377`profiles.<name>.plan_mode_reasoning_effort`
2378
2379Type / Values
2380
2381`none | minimal | low | medium | high | xhigh`
2382
2383Details
2384
2385Profile-scoped Plan-mode reasoning override.
2386
2387Key
2388
2389`profiles.<name>.service_tier`
2390
2391Type / Values
2392
2393`flex | fast`
2394
2395Details
2396
2397Profile-scoped service tier preference for new turns.
2398
2399Key
2400
2401`profiles.<name>.tools_view_image`
2402
2403Type / Values
2404
2405`boolean`
2406
2407Details
2408
2409Enable or disable the `view_image` tool in that profile.
2410
2411Key
2412
2413`profiles.<name>.web_search`
2414
2415Type / Values
2416
2417`disabled | cached | live`
2418
2419Details
2420
2421Profile-scoped web search mode override (default: `"cached"`).
2422
2423Key
2424
2425`profiles.<name>.windows.sandbox`
2426
2427Type / Values
2428
2429`unelevated | elevated`
2430
2431Details
2432
2433Profile-scoped Windows sandbox mode override.
2434
2435Key
2436
2437`project_doc_fallback_filenames`
2438
2439Type / Values
2440
2441`array<string>`
2442
2443Details
2444
2445Additional filenames to try when `AGENTS.md` is missing.
2446
2447Key
2448
2449`project_doc_max_bytes`
2450
2451Type / Values
2452
2453`number`
2454
2455Details
2456
2457Maximum bytes read from `AGENTS.md` when building project instructions.
2458
2459Key
2460
2461`project_root_markers`
2462
2463Type / Values
2464
2465`array<string>`
2466
2467Details
2468
2469List of project root marker filenames; used when searching parent directories for the project root.
2470
2471Key
2472
2473`projects.<path>.trust_level`
2474
2475Type / Values
2476
2477`string`
2478
2479Details
2480
2481Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.
2482
2483Key
2484
2485`review_model`
2486
2487Type / Values
2488
2489`string`
2490
2491Details
2492
2493Optional model override used by `/review` (defaults to the current session model).
2494
2495Key
2496
2497`sandbox_mode`
2498
2499Type / Values
2500
2501`read-only | workspace-write | danger-full-access`
2502
2503Details
2504
2505Sandbox policy for filesystem and network access during command execution.
2506
2507Key
2508
2509`sandbox_workspace_write.exclude_slash_tmp`
2510
2511Type / Values
2512
2513`boolean`
2514
2515Details
2516
2517Exclude `/tmp` from writable roots in workspace-write mode.
2518
2519Key
2520
2521`sandbox_workspace_write.exclude_tmpdir_env_var`
2522
2523Type / Values
2524
2525`boolean`
2526
2527Details
2528
2529Exclude `$TMPDIR` from writable roots in workspace-write mode.
2530
2531Key
2532
2533`sandbox_workspace_write.network_access`
2534
2535Type / Values
2536
2537`boolean`
2538
2539Details
2540
2541Allow outbound network access inside the workspace-write sandbox.
2542
2543Key
2544
2545`sandbox_workspace_write.writable_roots`
2546
2547Type / Values
2548
2549`array<string>`
2550
2551Details
2552
2553Additional writable roots when `sandbox_mode = "workspace-write"`.
2554
2555Key
2556
2557`service_tier`
2558
2559Type / Values
2560
2561`flex | fast`
2562
2563Details
2564
2565Preferred service tier for new turns.
2566
2567Key
2568
2569`shell_environment_policy.exclude`
2570
2571Type / Values
2572
2573`array<string>`
2574
2575Details
2576
2577Glob patterns for removing environment variables after the defaults.
2578
2579Key
2580
2581`shell_environment_policy.experimental_use_profile`
2582
2583Type / Values
2584
2585`boolean`
2586
2587Details
2588
2589Use the user shell profile when spawning subprocesses.
2590
2591Key
2592
2593`shell_environment_policy.ignore_default_excludes`
2594
2595Type / Values
2596
2597`boolean`
2598
2599Details
2600
2601Keep variables containing KEY/SECRET/TOKEN before other filters run.
2602
2603Key
2604
2605`shell_environment_policy.include_only`
2606
2607Type / Values
2608
2609`array<string>`
2610
2611Details
2612
2613Whitelist of patterns; when set only matching variables are kept.
2614
2615Key
2616
2617`shell_environment_policy.inherit`
2618
2619Type / Values
2620
2621`all | core | none`
2622
2623Details
2624
2625Baseline environment inheritance when spawning subprocesses.
2626
2627Key
2628
2629`shell_environment_policy.set`
2630
2631Type / Values
2632
2633`map<string,string>`
2634
2635Details
2636
2637Explicit environment overrides injected into every subprocess.
2638
2639Key
2640
2641`show_raw_agent_reasoning`
2642
2643Type / Values
2644
2645`boolean`
2646
2647Details
2648
2649Surface raw reasoning content when the active model emits it.
2650
2651Key
2652
2653`skills.config`
2654
2655Type / Values
2656
2657`array<object>`
2658
2659Details
2660
2661Per-skill enablement overrides stored in config.toml.
2662
2663Key
2664
2665`skills.config.<index>.enabled`
2666
2667Type / Values
2668
2669`boolean`
2670
2671Details
2672
2673Enable or disable the referenced skill.
2674
2675Key
2676
2677`skills.config.<index>.path`
2678
2679Type / Values
2680
2681`string (path)`
2682
2683Details
2684
2685Path to a skill folder containing `SKILL.md`.
2686
2687Key
2688
2689`sqlite_home`
2690
2691Type / Values
2692
2693`string (path)`
2694
2695Details
2696
2697Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.
2698
2699Key
2700
2701`suppress_unstable_features_warning`
2702
2703Type / Values
2704
2705`boolean`
2706
2707Details
2708
2709Suppress the warning that appears when under-development feature flags are enabled.
2710
2711Key
2712
2713`tool_output_token_limit`
2714
2715Type / Values
2716
2717`number`
2718
2719Details
2720
2721Token budget for storing individual tool/function outputs in history.
2722
2723Key
2724
2725`tool_suggest.discoverables`
2726
2727Type / Values
2728
2729`array<table>`
2730
2731Details
2732
2733Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.
2734
2735Key
2736
2737`tools.view_image`
2738
2739Type / Values
2740
2741`boolean`
2742
2743Details
2744
2745Enable the local-image attachment tool `view_image`.
2746
2747Key
2748
2749`tools.web_search`
2750
2751Type / Values
2752
2753`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`
2754
2755Details
2756
2757Optional 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.
2758
2759Key
2760
2761`tui`
2762
2763Type / Values
2764
2765`table`
2766
2767Details
2768
2769TUI-specific options such as enabling inline desktop notifications.
2770
2771Key
2772
2773`tui.alternate_screen`
2774
2775Type / Values
2776
2777`auto | always | never`
2778
2779Details
2780
2781Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
2782
2783Key
2784
2785`tui.animations`
2786
2787Type / Values
2788
2789`boolean`
2790
2791Details
2792
2793Enable terminal animations (welcome screen, shimmer, spinner) (default: true).
2794
2795Key
2796
2797`tui.model_availability_nux.<model>`
2798
2799Type / Values
2800
2801`integer`
2802
2803Details
2804
2805Internal startup-tooltip state keyed by model slug.
2806
2807Key
2808
2809`tui.notification_condition`
2810
2811Type / Values
2812
2813`unfocused | always`
2814
2815Details
2816
2817Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.
2818
2819Key
2820
2821`tui.notification_method`
2822
2823Type / Values
2824
2825`auto | osc9 | bel`
2826
2827Details
2828
2829Notification method for terminal notifications (default: auto).
2830
2831Key
2832
2833`tui.notifications`
2834
2835Type / Values
2836
2837`boolean | array<string>`
2838
2839Details
2840
2841Enable TUI notifications; optionally restrict to specific event types.
2842
2843Key
2844
2845`tui.show_tooltips`
2846
2847Type / Values
2848
2849`boolean`
2850
2851Details
2852
2853Show onboarding tooltips in the TUI welcome screen (default: true).
2854
2855Key
2856
2857`tui.status_line`
2858
2859Type / Values
2860
2861`array<string> | null`
2862
2863Details
2864
2865Ordered list of TUI footer status-line item identifiers. `null` disables the status line.
2866
2867Key
2868
2869`tui.terminal_title`
2870
2871Type / Values
2872
2873`array<string> | null`
2874
2875Details
2876
2877Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.
2878
2879Key
2880
2881`tui.theme`
2882
2883Type / Values
2884
2885`string`
2886
2887Details
2888
2889Syntax-highlighting theme override (kebab-case theme name).
2890
2891Key
2892
2893`web_search`
2894
2895Type / Values
2896
2897`disabled | cached | live`
2898
2899Details
2900
2901Web 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.
2902
2903Key
2904
2905`windows_wsl_setup_acknowledged`
2906
2907Type / Values
2908
2909`boolean`
2910
2911Details
2912
2913Track Windows onboarding acknowledgement (Windows only).
2914
2915Key
2916
2917`windows.sandbox`
2918
2919Type / Values
2920
2921`unelevated | elevated`
2922
2923Details
2924
2925Windows-only native sandbox mode when running Codex natively on Windows.
2926
2927Key
2928
2929`windows.sandbox_private_desktop`
2930
2931Type / Values
2932
2933`boolean`
2934
2935Details
2936
2937Run 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.
2938
2939Expand to view all
2940 1332
2941You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).1333You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
2942 1334
2958Use `[features]` in `requirements.toml` to pin feature flags by the same1350Use `[features]` in `requirements.toml` to pin feature flags by the same
2959canonical keys that `config.toml` uses. Omitted keys remain unconstrained.1351canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
2960 1352
2961| Key | Type / Values | Details |1353<ConfigTable
2962| --- | --- | --- |1354 options={[
2963| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |1355 {
2964| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |1356 key: "allowed_approval_policies",
2965| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |1357 type: "array<string>",
2966| `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`. |1358 description:
2967| `feature_requirements` | `table` | Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key. |1359 "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",
2968| `feature_requirements.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`. |1360 },
2969| `feature_requirements.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`. |1361 {
2970| `feature_requirements.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`. |1362 key: "allowed_approvals_reviewers",
2971| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |1363 type: "array<string>",
2972| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |1364 description:
2973| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |1365 "Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.",
2974| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |1366 },
2975| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |1367 {
2976| `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. |1368 key: "guardian_policy_config",
2977| `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. |1369 type: "string",
2978| `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. |1370 description:
2979| `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. |1371 "Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.",
2980| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |1372 },
2981| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |1373 {
2982| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |1374 key: "allowed_sandbox_modes",
2983| `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. |1375 type: "array<string>",
2984| `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. |1376 description: "Allowed values for `sandbox_mode`.",
2985| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |1377 },
2986| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |1378 {
2987| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |1379 key: "remote_sandbox_config",
2988| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |1380 type: "array<table>",
2989| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |1381 description:
2990| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. |1382 "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.",
2991| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. |1383 },
2992| `rules.prefix_rules[].pattern[].any_of` | `array<string>` | A list of allowed alternative tokens at this position. |1384 {
2993| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. |1385 key: "remote_sandbox_config[].hostname_patterns",
2994 1386 type: "array<string>",
2995Key1387 description:
2996 1388 "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
2997`allowed_approval_policies`1389 },
2998 1390 {
2999Type / Values1391 key: "remote_sandbox_config[].allowed_sandbox_modes",
3000 1392 type: "array<string>",
3001`array<string>`1393 description:
3002 1394 "Allowed sandbox modes to apply when this host-specific entry matches.",
3003Details1395 },
3004 1396 {
3005Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).1397 key: "allowed_web_search_modes",
3006 1398 type: "array<string>",
3007Key1399 description:
3008 1400 "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
3009`allowed_approvals_reviewers`1401 },
3010 1402 {
3011Type / Values1403 key: "features",
3012 1404 type: "table",
3013`array<string>`1405 description:
3014 1406 "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
3015Details1407 },
3016 1408 {
3017Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.1409 key: "features.<name>",
3018 1410 type: "boolean",
3019Key1411 description:
3020 1412 "Require a specific canonical feature key to stay enabled or disabled.",
3021`allowed_sandbox_modes`1413 },
3022 1414 {
3023Type / Values1415 key: "features.in_app_browser",
3024 1416 type: "boolean",
3025`array<string>`1417 description:
3026 1418 "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
3027Details1419 },
3028 1420 {
3029Allowed values for `sandbox_mode`.1421 key: "features.browser_use",
3030 1422 type: "boolean",
3031Key1423 description:
3032 1424 "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
3033`allowed_web_search_modes`1425 },
3034 1426 {
3035Type / Values1427 key: "features.computer_use",
3036 1428 type: "boolean",
3037`array<string>`1429 description:
3038 1430 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
3039Details1431 },
3040 1432 {
3041Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.1433 key: "hooks",
3042 1434 type: "table",
3043Key1435 description:
3044 1436 "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
3045`feature_requirements`1437 },
3046 1438 {
3047Type / Values1439 key: "hooks.managed_dir",
3048 1440 type: "string (absolute path)",
3049`table`1441 description:
3050 1442 "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
3051Details1443 },
3052 1444 {
3053Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key.1445 key: "hooks.windows_managed_dir",
3054 1446 type: "string (absolute path)",
3055Key1447 description:
3056 1448 "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
3057`feature_requirements.browser_use`1449 },
3058 1450 {
3059Type / Values1451 key: "hooks.<Event>",
3060 1452 type: "array<table>",
3061`boolean`1453 description:
3062 1454 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
3063Details1455 },
3064 1456 {
3065Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`.1457 key: "hooks.<Event>[].hooks",
3066 1458 type: "array<table>",
3067Key1459 description:
3068 1460 "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
3069`feature_requirements.computer_use`1461 },
3070 1462 {
3071Type / Values1463 key: "permissions.filesystem.deny_read",
3072 1464 type: "array<string>",
3073`boolean`1465 description:
3074 1466 "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
3075Details1467 },
3076 1468 {
3077Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`.1469 key: "mcp_servers",
3078 1470 type: "table",
3079Key1471 description:
3080 1472 "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.",
3081`feature_requirements.in_app_browser`1473 },
3082 1474 {
3083Type / Values1475 key: "mcp_servers.<id>.identity",
3084 1476 type: "table",
3085`boolean`1477 description:
3086 1478 "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
3087Details1479 },
3088 1480 {
3089Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`.1481 key: "mcp_servers.<id>.identity.command",
3090 1482 type: "string",
3091Key1483 description:
3092 1484 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
3093`features`1485 },
3094 1486 {
3095Type / Values1487 key: "mcp_servers.<id>.identity.url",
3096 1488 type: "string",
3097`table`1489 description:
3098 1490 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",
3099Details1491 },
3100 1492 {
3101Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.1493 key: "rules",
3102 1494 type: "table",
3103Key1495 description:
3104 1496 "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.",
3105`features.<name>`1497 },
3106 1498 {
3107Type / Values1499 key: "rules.prefix_rules",
3108 1500 type: "array<table>",
3109`boolean`1501 description:
3110 1502 "List of enforced prefix rules. Each rule must include `pattern` and `decision`.",
3111Details1503 },
3112 1504 {
3113Require a specific canonical feature key to stay enabled or disabled.1505 key: "rules.prefix_rules[].pattern",
3114 1506 type: "array<table>",
3115Key1507 description:
3116 1508 "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.",
3117`guardian_policy_config`1509 },
3118 1510 {
3119Type / Values1511 key: "rules.prefix_rules[].pattern[].token",
3120 1512 type: "string",
3121`string`1513 description: "A single literal token at this position.",
3122 1514 },
3123Details1515 {
3124 1516 key: "rules.prefix_rules[].pattern[].any_of",
3125Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.1517 type: "array<string>",
3126 1518 description: "A list of allowed alternative tokens at this position.",
3127Key1519 },
3128 1520 {
3129`hooks`1521 key: "rules.prefix_rules[].decision",
3130 1522 type: "prompt | forbidden",
3131Type / Values1523 description:
3132 1524 "Required. Requirements rules can only prompt or forbid (not allow).",
3133`table`1525 },
3134 1526 {
3135Details1527 key: "rules.prefix_rules[].justification",
3136 1528 type: "string",
3137Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.1529 description:
3138 1530 "Optional non-empty rationale surfaced in approval prompts or rejection messages.",
3139Key1531 },
3140 1532 ]}
3141`hooks.<Event>`1533 client:load
3142 1534/>
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
3189`mcp_servers`
3190
3191Type / Values
3192
3193`table`
3194
3195Details
3196
3197Allowlist 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.
3198
3199Key
3200
3201`mcp_servers.<id>.identity`
3202
3203Type / Values
3204
3205`table`
3206
3207Details
3208
3209Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).
3210
3211Key
3212
3213`mcp_servers.<id>.identity.command`
3214
3215Type / Values
3216
3217`string`
3218
3219Details
3220
3221Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.
3222
3223Key
3224
3225`mcp_servers.<id>.identity.url`
3226
3227Type / Values
3228
3229`string`
3230
3231Details
3232
3233Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.
3234
3235Key
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
3285`rules`
3286
3287Type / Values
3288
3289`table`
3290
3291Details
3292
3293Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.
3294
3295Key
3296
3297`rules.prefix_rules`
3298
3299Type / Values
3300
3301`array<table>`
3302
3303Details
3304
3305List of enforced prefix rules. Each rule must include `pattern` and `decision`.
3306
3307Key
3308
3309`rules.prefix_rules[].decision`
3310
3311Type / Values
3312
3313`prompt | forbidden`
3314
3315Details
3316
3317Required. Requirements rules can only prompt or forbid (not allow).
3318
3319Key
3320
3321`rules.prefix_rules[].justification`
3322
3323Type / Values
3324
3325`string`
3326
3327Details
3328
3329Optional non-empty rationale surfaced in approval prompts or rejection messages.
3330
3331Key
3332
3333`rules.prefix_rules[].pattern`
3334
3335Type / Values
3336
3337`array<table>`
3338
3339Details
3340
3341Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.
3342
3343Key
3344
3345`rules.prefix_rules[].pattern[].any_of`
3346
3347Type / Values
3348
3349`array<string>`
3350
3351Details
3352
3353A list of allowed alternative tokens at this position.
3354
3355Key
3356
3357`rules.prefix_rules[].pattern[].token`
3358
3359Type / Values
3360
3361`string`
3362
3363Details
3364
3365A single literal token at this position.
3366
3367Expand to view all
