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