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