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