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 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',
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: "features.codex_git_commit",
335`boolean`335 type: "boolean",
336 336 description:
337Details337 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",
338 338 },
339Enable or disable analytics for this machine/profile. When unset, the client default applies.339 {
340 340 key: "hooks",
341Key341 type: "table",
342 342 description:
343`approval_policy`343 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
344 344 },
345Type / Values345 {
346 346 key: "features.memories",
347`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`347 type: "boolean",
348 348 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",
349Details349 },
350 350 {
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 key: "mcp_servers.<id>.command",
352 352 type: "string",
353Key353 description: "Launcher command for an MCP stdio server.",
354 354 },
355`approval_policy.granular.mcp_elicitations`355 {
356 356 key: "mcp_servers.<id>.args",
357Type / Values357 type: "array<string>",
358 358 description: "Arguments passed to the MCP stdio server command.",
359`boolean`359 },
360 360 {
361Details361 key: "mcp_servers.<id>.env",
362 362 type: "map<string,string>",
363When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.363 description: "Environment variables forwarded to the MCP stdio server.",
364 364 },
365Key365 {
366 366 key: "mcp_servers.<id>.env_vars",
367`approval_policy.granular.request_permissions`367 type: 'array<string | { name = string, source = "local" | "remote" }>',
368 368 description:
369Type / Values369 '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.',
370 370 },
371`boolean`371 {
372 372 key: "mcp_servers.<id>.cwd",
373Details373 type: "string",
374 374 description: "Working directory for the MCP stdio server process.",
375When `true`, prompts from the `request_permissions` tool are allowed to surface.375 },
376 376 {
377Key377 key: "mcp_servers.<id>.url",
378 378 type: "string",
379`approval_policy.granular.rules`379 description: "Endpoint for an MCP streamable HTTP server.",
380 380 },
381Type / Values381 {
382 382 key: "mcp_servers.<id>.bearer_token_env_var",
383`boolean`383 type: "string",
384 384 description:
385Details385 "Environment variable sourcing the bearer token for an MCP HTTP server.",
386 386 },
387When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.387 {
388 388 key: "mcp_servers.<id>.http_headers",
389Key389 type: "map<string,string>",
390 390 description: "Static HTTP headers included with each MCP HTTP request.",
391`approval_policy.granular.sandbox_approval`391 },
392 392 {
393Type / Values393 key: "mcp_servers.<id>.env_http_headers",
394 394 type: "map<string,string>",
395`boolean`395 description:
396 396 "HTTP headers populated from environment variables for an MCP HTTP server.",
397Details397 },
398 398 {
399When `true`, sandbox escalation approval prompts are allowed to surface.399 key: "mcp_servers.<id>.enabled",
400 400 type: "boolean",
401Key401 description: "Disable an MCP server without removing its configuration.",
402 402 },
403`approval_policy.granular.skill_approval`403 {
404 404 key: "mcp_servers.<id>.required",
405Type / Values405 type: "boolean",
406 406 description:
407`boolean`407 "When true, fail startup/resume if this enabled MCP server cannot initialize.",
408 408 },
409Details409 {
410 410 key: "mcp_servers.<id>.startup_timeout_sec",
411When `true`, skill-script approval prompts are allowed to surface.411 type: "number",
412 412 description:
413Key413 "Override the default 10s startup timeout for an MCP server.",
414 414 },
415`approvals_reviewer`415 {
416 416 key: "mcp_servers.<id>.startup_timeout_ms",
417Type / Values417 type: "number",
418 418 description: "Alias for `startup_timeout_sec` in milliseconds.",
419`user | auto_review`419 },
420 420 {
421Details421 key: "mcp_servers.<id>.tool_timeout_sec",
422 422 type: "number",
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:
424 424 "Override the default 60s per-tool timeout for an MCP server.",
425Key425 },
426 426 {
427`apps._default.destructive_enabled`427 key: "mcp_servers.<id>.enabled_tools",
428 428 type: "array<string>",
429Type / Values429 description: "Allow list of tool names exposed by the MCP server.",
430 430 },
431`boolean`431 {
432 432 key: "mcp_servers.<id>.disabled_tools",
433Details433 type: "array<string>",
434 434 description:
435Default allow/deny for app tools with `destructive_hint = true`.435 "Deny list applied after `enabled_tools` for the MCP server.",
436 436 },
437Key437 {
438 438 key: "mcp_servers.<id>.scopes",
439`apps._default.enabled`439 type: "array<string>",
440 440 description:
441Type / Values441 "OAuth scopes to request when authenticating to that MCP server.",
442 442 },
443`boolean`443 {
444 444 key: "mcp_servers.<id>.oauth_resource",
445Details445 type: "string",
446 446 description:
447Default app enabled state for all apps unless overridden per app.447 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",
448 448 },
449Key449 {
450 450 key: "mcp_servers.<id>.experimental_environment",
451`apps._default.open_world_enabled`451 type: "local | remote",
452 452 description:
453Type / Values453 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",
454 454 },
455`boolean`455 {
456 456 key: "agents.max_threads",
457Details457 type: "number",
458 458 description:
459Default allow/deny for app tools with `open_world_hint = true`.459 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",
460 460 },
461Key461 {
462 462 key: "agents.max_depth",
463`apps.<id>.default_tools_approval_mode`463 type: "number",
464 464 description:
465Type / Values465 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",
466 466 },
467`auto | prompt | approve`467 {
468 468 key: "agents.job_max_runtime_seconds",
469Details469 type: "number",
470 470 description:
471Default approval behavior for tools in this app unless a per-tool override exists.471 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",
472 472 },
473Key473 {
474 474 key: "agents.<name>.description",
475`apps.<id>.default_tools_enabled`475 type: "string",
476 476 description:
477Type / Values477 "Role guidance shown to Codex when choosing and spawning that agent type.",
478 478 },
479`boolean`479 {
480 480 key: "agents.<name>.config_file",
481Details481 type: "string (path)",
482 482 description:
483Default enabled state for tools in this app unless a per-tool override exists.483 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",
484 484 },
485Key485 {
486 486 key: "agents.<name>.nickname_candidates",
487`apps.<id>.destructive_enabled`487 type: "array<string>",
488 488 description:
489Type / Values489 "Optional pool of display nicknames for spawned agents in that role.",
490 490 },
491`boolean`491 {
492 492 key: "memories.generate_memories",
493Details493 type: "boolean",
494 494 description:
495Allow or block tools in this app that advertise `destructive_hint = true`.495 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",
496 496 },
497Key497 {
498 498 key: "memories.use_memories",
499`apps.<id>.enabled`499 type: "boolean",
500 500 description:
501Type / Values501 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",
502 502 },
503`boolean`503 {
504 504 key: "memories.disable_on_external_context",
505Details505 type: "boolean",
506 506 description:
507Enable or disable a specific app/connector by id (default: true).507 "When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.",
508 508 },
509Key509 {
510 510 key: "memories.max_raw_memories_for_consolidation",
511`apps.<id>.open_world_enabled`511 type: "number",
512 512 description:
513Type / Values513 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",
514 514 },
515`boolean`515 {
516 516 key: "memories.max_unused_days",
517Details517 type: "number",
518 518 description:
519Allow or block tools in this app that advertise `open_world_hint = true`.519 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",
520 520 },
521Key521 {
522 522 key: "memories.max_rollout_age_days",
523`apps.<id>.tools.<tool>.approval_mode`523 type: "number",
524 524 description:
525Type / Values525 "Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.",
526 526 },
527`auto | prompt | approve`527 {
528 528 key: "memories.max_rollouts_per_startup",
529Details529 type: "number",
530 530 description:
531Per-tool approval behavior override for a single app tool.531 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",
532 532 },
533Key533 {
534 534 key: "memories.min_rollout_idle_hours",
535`apps.<id>.tools.<tool>.enabled`535 type: "number",
536 536 description:
537Type / Values537 "Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.",
538 538 },
539`boolean`539 {
540 540 key: "memories.min_rate_limit_remaining_percent",
541Details541 type: "number",
542 542 description:
543Per-tool enabled override for an app tool (for example `repos/list`).543 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",
544 544 },
545Key545 {
546 546 key: "memories.extract_model",
547`auto_review.policy`547 type: "string",
548 548 description: "Optional model override for per-thread memory extraction.",
549Type / Values549 },
550 550 {
551`string`551 key: "memories.consolidation_model",
552 552 type: "string",
553Details553 description: "Optional model override for global memory consolidation.",
554 554 },
555Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.555 {
556 556 key: "features.unified_exec",
557Key557 type: "boolean",
558 558 description:
559`background_terminal_max_timeout`559 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",
560 560 },
561Type / Values561 {
562 562 key: "features.shell_snapshot",
563`number`563 type: "boolean",
564 564 description:
565Details565 "Snapshot shell environment to speed up repeated commands (stable; on by default).",
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 {
568 568 key: "features.undo",
569Key569 type: "boolean",
570 570 description: "Enable undo support (stable; off by default).",
571`chatgpt_base_url`571 },
572 572 {
573Type / Values573 key: "features.multi_agent",
574 574 type: "boolean",
575`string`575 description:
576 576 "Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).",
577Details577 },
578 578 {
579Override the base URL used during the ChatGPT login flow.579 key: "features.personality",
580 580 type: "boolean",
581Key581 description:
582 582 "Enable personality selection controls (stable; on by default).",
583`check_for_update_on_startup`583 },
584 584 {
585Type / Values585 key: "features.web_search",
586 586 type: "boolean",
587`boolean`587 description:
588 588 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",
589Details589 },
590 590 {
591Check for Codex updates on startup (set to false only when updates are centrally managed).591 key: "features.web_search_cached",
592 592 type: "boolean",
593Key593 description:
594 594 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',
595`cli_auth_credentials_store`595 },
596 596 {
597Type / Values597 key: "features.web_search_request",
598 598 type: "boolean",
599`file | keyring | auto`599 description:
600 600 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.',
601Details601 },
602 602 {
603Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).603 key: "features.shell_tool",
604 604 type: "boolean",
605Key605 description:
606 606 "Enable the default `shell` tool for running commands (stable; on by default).",
607`commit_attribution`607 },
608 608 {
609Type / Values609 key: "features.enable_request_compression",
610 610 type: "boolean",
611`string`611 description:
612 612 "Compress streaming request bodies with zstd when supported (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.skill_mcp_dependency_install",
616 616 type: "boolean",
617Key617 description:
618 618 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",
619`compact_prompt`619 },
620 620 {
621Type / Values621 key: "features.fast_mode",
622 622 type: "boolean",
623`string`623 description:
624 624 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).',
625Details625 },
626 626 {
627Inline override for the history compaction prompt.627 key: "features.prevent_idle_sleep",
628 628 type: "boolean",
629Key629 description:
630 630 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",
631`default_permissions`631 },
632 632 {
633Type / Values633 key: "suppress_unstable_features_warning",
634 634 type: "boolean",
635`string`635 description:
636 636 "Suppress the warning that appears when under-development feature flags are enabled.",
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>",
640 640 type: "table",
641Key641 description:
642 642 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",
643`developer_instructions`643 },
644 644 {
645Type / Values645 key: "model_providers.<id>.name",
646 646 type: "string",
647`string`647 description: "Display name for a custom model provider.",
648 648 },
649Details649 {
650 650 key: "model_providers.<id>.base_url",
651Additional developer instructions injected into the session (optional).651 type: "string",
652 652 description: "API base URL for the model provider.",
653Key653 },
654 654 {
655`disable_paste_burst`655 key: "model_providers.<id>.env_key",
656 656 type: "string",
657Type / Values657 description: "Environment variable supplying the provider API key.",
658 658 },
659`boolean`659 {
660 660 key: "model_providers.<id>.env_key_instructions",
661Details661 type: "string",
662 662 description: "Optional setup guidance for the provider API key.",
663Disable burst-paste detection in the TUI.663 },
664 664 {
665Key665 key: "model_providers.<id>.experimental_bearer_token",
666 666 type: "string",
667`experimental_compact_prompt_file`667 description:
668 668 "Direct bearer token for the provider (discouraged; use `env_key`).",
669Type / Values669 },
670 670 {
671`string (path)`671 key: "model_providers.<id>.requires_openai_auth",
672 672 type: "boolean",
673Details673 description:
674 674 "The provider uses OpenAI authentication (defaults to false).",
675Load the compaction prompt override from a file (experimental).675 },
676 676 {
677Key677 key: "model_providers.<id>.wire_api",
678 678 type: "responses",
679`experimental_use_unified_exec_tool`679 description:
680 680 "Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.",
681Type / Values681 },
682 682 {
683`boolean`683 key: "model_providers.<id>.query_params",
684 684 type: "map<string,string>",
685Details685 description: "Extra query parameters appended to provider requests.",
686 686 },
687Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.687 {
688 688 key: "model_providers.<id>.http_headers",
689Key689 type: "map<string,string>",
690 690 description: "Static HTTP headers added to provider requests.",
691`features.apps`691 },
692 692 {
693Type / Values693 key: "model_providers.<id>.env_http_headers",
694 694 type: "map<string,string>",
695`boolean`695 description:
696 696 "HTTP headers populated from environment variables when present.",
697Details697 },
698 698 {
699Enable ChatGPT Apps/connectors support (experimental).699 key: "model_providers.<id>.request_max_retries",
700 700 type: "number",
701Key701 description:
702 702 "Retry count for HTTP requests to the provider (default: 4).",
703`features.codex_hooks`703 },
704 704 {
705Type / Values705 key: "model_providers.<id>.stream_max_retries",
706 706 type: "number",
707`boolean`707 description: "Retry count for SSE streaming interruptions (default: 5).",
708 708 },
709Details709 {
710 710 key: "model_providers.<id>.stream_idle_timeout_ms",
711Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.711 type: "number",
712 712 description:
713Key713 "Idle timeout for SSE streams in milliseconds (default: 300000).",
714 714 },
715`features.enable_request_compression`715 {
716 716 key: "model_providers.<id>.supports_websockets",
717Type / Values717 type: "boolean",
718 718 description:
719`boolean`719 "Whether that provider supports the Responses API WebSocket transport.",
720 720 },
721Details721 {
722 722 key: "model_providers.<id>.auth",
723Compress streaming request bodies with zstd when supported (stable; on by default).723 type: "table",
724 724 description:
725Key725 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",
726 726 },
727`features.fast_mode`727 {
728 728 key: "model_providers.<id>.auth.command",
729Type / Values729 type: "string",
730 730 description:
731`boolean`731 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",
732 732 },
733Details733 {
734 734 key: "model_providers.<id>.auth.args",
735Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).735 type: "array<string>",
736 736 description: "Arguments passed to the token command.",
737Key737 },
738 738 {
739`features.memories`739 key: "model_providers.<id>.auth.timeout_ms",
740 740 type: "number",
741Type / Values741 description:
742 742 "Maximum token command runtime in milliseconds (default: 5000).",
743`boolean`743 },
744 744 {
745Details745 key: "model_providers.<id>.auth.refresh_interval_ms",
746 746 type: "number",
747Enable [Memories](https://developers.openai.com/codex/memories) (off by default).747 description:
748 748 "How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.",
749Key749 },
750 750 {
751`features.multi_agent`751 key: "model_providers.<id>.auth.cwd",
752 752 type: "string (path)",
753Type / Values753 description: "Working directory for the token command.",
754 754 },
755`boolean`755 {
756 756 key: "model_providers.amazon-bedrock.aws.profile",
757Details757 type: "string",
758 758 description:
759Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).759 "AWS profile name used by the built-in `amazon-bedrock` provider.",
760 760 },
761Key761 {
762 762 key: "model_providers.amazon-bedrock.aws.region",
763`features.personality`763 type: "string",
764 764 description: "AWS region used by the built-in `amazon-bedrock` provider.",
765Type / Values765 },
766 766 {
767`boolean`767 key: "model_reasoning_effort",
768 768 type: "minimal | low | medium | high | xhigh",
769Details769 description:
770 770 "Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).",
771Enable personality selection controls (stable; on by default).771 },
772 772 {
773Key773 key: "plan_mode_reasoning_effort",
774 774 type: "none | minimal | low | medium | high | xhigh",
775`features.prevent_idle_sleep`775 description:
776 776 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",
777Type / Values777 },
778 778 {
779`boolean`779 key: "model_reasoning_summary",
780 780 type: "auto | concise | detailed | none",
781Details781 description:
782 782 "Select reasoning summary detail or disable summaries entirely.",
783Prevent the machine from sleeping while a turn is actively running (experimental; off by default).783 },
784 784 {
785Key785 key: "model_verbosity",
786 786 type: "low | medium | high",
787`features.shell_snapshot`787 description:
788 788 "Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.",
789Type / Values789 },
790 790 {
791`boolean`791 key: "model_supports_reasoning_summaries",
792 792 type: "boolean",
793Details793 description: "Force Codex to send or not send reasoning metadata.",
794 794 },
795Snapshot shell environment to speed up repeated commands (stable; on by default).795 {
796 796 key: "shell_environment_policy.inherit",
797Key797 type: "all | core | none",
798 798 description:
799`features.shell_tool`799 "Baseline environment inheritance when spawning subprocesses.",
800 800 },
801Type / Values801 {
802 802 key: "shell_environment_policy.ignore_default_excludes",
803`boolean`803 type: "boolean",
804 804 description:
805Details805 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",
806 806 },
807Enable the default `shell` tool for running commands (stable; on by default).807 {
808 808 key: "shell_environment_policy.exclude",
809Key809 type: "array<string>",
810 810 description:
811`features.skill_mcp_dependency_install`811 "Glob patterns for removing environment variables after the defaults.",
812 812 },
813Type / Values813 {
814 814 key: "shell_environment_policy.include_only",
815`boolean`815 type: "array<string>",
816 816 description:
817Details817 "Whitelist of patterns; when set only matching variables are kept.",
818 818 },
819Allow prompting and installing missing MCP dependencies for skills (stable; on by default).819 {
820 820 key: "shell_environment_policy.set",
821Key821 type: "map<string,string>",
822 822 description:
823`features.undo`823 "Explicit environment overrides injected into every subprocess.",
824 824 },
825Type / Values825 {
826 826 key: "shell_environment_policy.experimental_use_profile",
827`boolean`827 type: "boolean",
828 828 description: "Use the user shell profile when spawning subprocesses.",
829Details829 },
830 830 {
831Enable undo support (stable; off by default).831 key: "project_root_markers",
832 832 type: "array<string>",
833Key833 description:
834 834 "List of project root marker filenames; used when searching parent directories for the project root.",
835`features.unified_exec`835 },
836 836 {
837Type / Values837 key: "project_doc_max_bytes",
838 838 type: "number",
839`boolean`839 description:
840 840 "Maximum bytes read from `AGENTS.md` when building project instructions.",
841Details841 },
842 842 {
843Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).843 key: "project_doc_fallback_filenames",
844 844 type: "array<string>",
845Key845 description: "Additional filenames to try when `AGENTS.md` is missing.",
846 846 },
847`features.web_search`847 {
848 848 key: "profile",
849Type / Values849 type: "string",
850 850 description:
851`boolean`851 "Default profile applied at startup (equivalent to `--profile`).",
852 852 },
853Details853 {
854 854 key: "profiles.<name>.*",
855Deprecated legacy toggle; prefer the top-level `web_search` setting.855 type: "various",
856 856 description:
857Key857 "Profile-scoped overrides for any of the supported configuration keys.",
858 858 },
859`features.web_search_cached`859 {
860 860 key: "profiles.<name>.service_tier",
861Type / Values861 type: "flex | fast",
862 862 description: "Profile-scoped service tier preference for new turns.",
863`boolean`863 },
864 864 {
865Details865 key: "profiles.<name>.plan_mode_reasoning_effort",
866 866 type: "none | minimal | low | medium | high | xhigh",
867Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.867 description: "Profile-scoped Plan-mode reasoning override.",
868 868 },
869Key869 {
870 870 key: "profiles.<name>.web_search",
871`features.web_search_request`871 type: "disabled | cached | live",
872 872 description:
873Type / Values873 'Profile-scoped web search mode override (default: `"cached"`).',
874 874 },
875`boolean`875 {
876 876 key: "profiles.<name>.personality",
877Details877 type: "none | friendly | pragmatic",
878 878 description:
879Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.879 "Profile-scoped communication style override for supported models.",
880 880 },
881Key881 {
882 882 key: "profiles.<name>.model_catalog_json",
883`feedback.enabled`883 type: "string (path)",
884 884 description:
885Type / Values885 "Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).",
886 886 },
887`boolean`887 {
888 888 key: "profiles.<name>.model_instructions_file",
889Details889 type: "string (path)",
890 890 description:
891Enable feedback submission via `/feedback` across Codex surfaces (default: true).891 "Profile-scoped replacement for the built-in instruction file.",
892 892 },
893Key893 {
894 894 key: "profiles.<name>.experimental_use_unified_exec_tool",
895`file_opener`895 type: "boolean",
896 896 description:
897Type / Values897 "Legacy name for enabling unified exec; prefer `[features].unified_exec`.",
898 898 },
899`vscode | vscode-insiders | windsurf | cursor | none`899 {
900 900 key: "profiles.<name>.oss_provider",
901Details901 type: "lmstudio | ollama",
902 902 description: "Profile-scoped OSS provider for `--oss` sessions.",
903URI scheme used to open citations from Codex output (default: `vscode`).903 },
904 904 {
905Key905 key: "profiles.<name>.tools_view_image",
906 906 type: "boolean",
907`forced_chatgpt_workspace_id`907 description: "Enable or disable the `view_image` tool in that profile.",
908 908 },
909Type / Values909 {
910 910 key: "profiles.<name>.analytics.enabled",
911`string (uuid)`911 type: "boolean",
912 912 description: "Profile-scoped analytics enablement override.",
913Details913 },
914 914 {
915Limit ChatGPT logins to a specific workspace identifier.915 key: "profiles.<name>.windows.sandbox",
916 916 type: "unelevated | elevated",
917Key917 description: "Profile-scoped Windows sandbox mode override.",
918 918 },
919`forced_login_method`919 {
920 920 key: "history.persistence",
921Type / Values921 type: "save-all | none",
922 922 description:
923`chatgpt | api`923 "Control whether Codex saves session transcripts to history.jsonl.",
924 924 },
925Details925 {
926 926 key: "tool_output_token_limit",
927Restrict Codex to a specific authentication method.927 type: "number",
928 928 description:
929Key929 "Token budget for storing individual tool/function outputs in history.",
930 930 },
931`hide_agent_reasoning`931 {
932 932 key: "background_terminal_max_timeout",
933Type / Values933 type: "number",
934 934 description:
935`boolean`935 "Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.",
936 936 },
937Details937 {
938 938 key: "history.max_bytes",
939Suppress reasoning events in both the TUI and `codex exec` output.939 type: "number",
940 940 description:
941Key941 "If set, caps the history file size in bytes by dropping oldest entries.",
942 942 },
943`history.max_bytes`943 {
944 944 key: "file_opener",
945Type / Values945 type: "vscode | vscode-insiders | windsurf | cursor | none",
946 946 description:
947`number`947 "URI scheme used to open citations from Codex output (default: `vscode`).",
948 948 },
949Details949 {
950 950 key: "otel.environment",
951If set, caps the history file size in bytes by dropping oldest entries.951 type: "string",
952 952 description:
953Key953 "Environment tag applied to emitted OpenTelemetry events (default: `dev`).",
954 954 },
955`history.persistence`955 {
956 956 key: "otel.exporter",
957Type / Values957 type: "none | otlp-http | otlp-grpc",
958 958 description:
959`save-all | none`959 "Select the OpenTelemetry exporter and provide any endpoint metadata.",
960 960 },
961Details961 {
962 962 key: "otel.trace_exporter",
963Control whether Codex saves session transcripts to history.jsonl.963 type: "none | otlp-http | otlp-grpc",
964 964 description:
965Key965 "Select the OpenTelemetry trace exporter and provide any endpoint metadata.",
966 966 },
967`hooks`967 {
968 968 key: "otel.metrics_exporter",
969Type / Values969 type: "none | statsig | otlp-http | otlp-grpc",
970 970 description:
971`table`971 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",
972 972 },
973Details973 {
974 974 key: "otel.log_user_prompt",
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: "boolean",
976 976 description:
977Key977 "Opt in to exporting raw user prompts with OpenTelemetry logs.",
978 978 },
979`instructions`979 {
980 980 key: "otel.exporter.<id>.endpoint",
981Type / Values981 type: "string",
982 982 description: "Exporter endpoint for OTEL logs.",
983`string`983 },
984 984 {
985Details985 key: "otel.exporter.<id>.protocol",
986 986 type: "binary | json",
987Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.987 description: "Protocol used by the OTLP/HTTP exporter.",
988 988 },
989Key989 {
990 990 key: "otel.exporter.<id>.headers",
991`log_dir`991 type: "map<string,string>",
992 992 description: "Static headers included with OTEL exporter requests.",
993Type / Values993 },
994 994 {
995`string (path)`995 key: "otel.trace_exporter.<id>.endpoint",
996 996 type: "string",
997Details997 description: "Trace exporter endpoint for OTEL logs.",
998 998 },
999Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.999 {
1000 1000 key: "otel.trace_exporter.<id>.protocol",
1001Key1001 type: "binary | json",
1002 1002 description: "Protocol used by the OTLP/HTTP trace exporter.",
1003`mcp_oauth_callback_port`1003 },
1004 1004 {
1005Type / Values1005 key: "otel.trace_exporter.<id>.headers",
1006 1006 type: "map<string,string>",
1007`integer`1007 description: "Static headers included with OTEL trace exporter requests.",
1008 1008 },
1009Details1009 {
1010 1010 key: "otel.exporter.<id>.tls.ca-certificate",
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 type: "string",
1012 1012 description: "CA certificate path for OTEL exporter TLS.",
1013Key1013 },
1014 1014 {
1015`mcp_oauth_callback_url`1015 key: "otel.exporter.<id>.tls.client-certificate",
1016 1016 type: "string",
1017Type / Values1017 description: "Client certificate path for OTEL exporter TLS.",
1018 1018 },
1019`string`1019 {
1020 1020 key: "otel.exporter.<id>.tls.client-private-key",
1021Details1021 type: "string",
1022 1022 description: "Client private key path for OTEL exporter TLS.",
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 {
1025Key1025 key: "otel.trace_exporter.<id>.tls.ca-certificate",
1026 1026 type: "string",
1027`mcp_oauth_credentials_store`1027 description: "CA certificate path for OTEL trace exporter TLS.",
1028 1028 },
1029Type / Values1029 {
1030 1030 key: "otel.trace_exporter.<id>.tls.client-certificate",
1031`auto | file | keyring`1031 type: "string",
1032 1032 description: "Client certificate path for OTEL trace exporter TLS.",
1033Details1033 },
1034 1034 {
1035Preferred store for MCP OAuth credentials.1035 key: "otel.trace_exporter.<id>.tls.client-private-key",
1036 1036 type: "string",
1037Key1037 description: "Client private key path for OTEL trace exporter TLS.",
1038 1038 },
1039`mcp_servers.<id>.args`1039 {
1040 1040 key: "tui",
1041Type / Values1041 type: "table",
1042 1042 description:
1043`array<string>`1043 "TUI-specific options such as enabling inline desktop notifications.",
1044 1044 },
1045Details1045 {
1046 1046 key: "tui.notifications",
1047Arguments passed to the MCP stdio server command.1047 type: "boolean | array<string>",
1048 1048 description:
1049Key1049 "Enable TUI notifications; optionally restrict to specific event types.",
1050 1050 },
1051`mcp_servers.<id>.bearer_token_env_var`1051 {
1052 1052 key: "tui.notification_method",
1053Type / Values1053 type: "auto | osc9 | bel",
1054 1054 description:
1055`string`1055 "Notification method for terminal notifications (default: auto).",
1056 1056 },
1057Details1057 {
1058 1058 key: "tui.notification_condition",
1059Environment variable sourcing the bearer token for an MCP HTTP server.1059 type: "unfocused | always",
1060 1060 description:
1061Key1061 "Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.",
1062 1062 },
1063`mcp_servers.<id>.command`1063 {
1064 1064 key: "tui.animations",
1065Type / Values1065 type: "boolean",
1066 1066 description:
1067`string`1067 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",
1068 1068 },
1069Details1069 {
1070 1070 key: "tui.alternate_screen",
1071Launcher command for an MCP stdio server.1071 type: "auto | always | never",
1072 1072 description:
1073Key1073 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1074 1074 },
1075`mcp_servers.<id>.cwd`1075 {
1076 1076 key: "tui.show_tooltips",
1077Type / Values1077 type: "boolean",
1078 1078 description:
1079`string`1079 "Show onboarding tooltips in the TUI welcome screen (default: true).",
1080 1080 },
1081Details1081 {
1082 1082 key: "tui.status_line",
1083Working directory for the MCP stdio server process.1083 type: "array<string> | null",
1084 1084 description:
1085Key1085 "Ordered list of TUI footer status-line item identifiers. `null` disables the status line.",
1086 1086 },
1087`mcp_servers.<id>.disabled_tools`1087 {
1088 1088 key: "tui.terminal_title",
1089Type / Values1089 type: "array<string> | null",
1090 1090 description:
1091`array<string>`1091 'Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.',
1092 1092 },
1093Details1093 {
1094 1094 key: "tui.theme",
1095Deny list applied after `enabled_tools` for the MCP server.1095 type: "string",
1096 1096 description:
1097Key1097 "Syntax-highlighting theme override (kebab-case theme name).",
1098 1098 },
1099`mcp_servers.<id>.enabled`1099 {
1100 1100 key: "tui.keymap.<context>.<action>",
1101Type / Values1101 type: "string | array<string>",
1102 1102 description:
1103`boolean`1103 "Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`.",
1104 1104 },
1105Details1105 {
1106 1106 key: "tui.keymap.<context>.<action> = []",
1107Disable an MCP server without removing its configuration.1107 type: "empty array",
1108 1108 description:
1109Key1109 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.",
1110 1110 },
1111`mcp_servers.<id>.enabled_tools`1111 {
1112 1112 key: "tui.model_availability_nux.<model>",
1113Type / Values1113 type: "integer",
1114 1114 description: "Internal startup-tooltip state keyed by model slug.",
1115`array<string>`1115 },
1116 1116 {
1117Details1117 key: "hide_agent_reasoning",
1118 1118 type: "boolean",
1119Allow list of tool names exposed by the MCP server.1119 description:
1120 1120 "Suppress reasoning events in both the TUI and `codex exec` output.",
1121Key1121 },
1122 1122 {
1123`mcp_servers.<id>.env`1123 key: "show_raw_agent_reasoning",
1124 1124 type: "boolean",
1125Type / Values1125 description:
1126 1126 "Surface raw reasoning content when the active model emits it.",
1127`map<string,string>`1127 },
1128 1128 {
1129Details1129 key: "disable_paste_burst",
1130 1130 type: "boolean",
1131Environment variables forwarded to the MCP stdio server.1131 description: "Disable burst-paste detection in the TUI.",
1132 1132 },
1133Key1133 {
1134 1134 key: "windows_wsl_setup_acknowledged",
1135`mcp_servers.<id>.env_http_headers`1135 type: "boolean",
1136 1136 description: "Track Windows onboarding acknowledgement (Windows only).",
1137Type / Values1137 },
1138 1138 {
1139`map<string,string>`1139 key: "chatgpt_base_url",
1140 1140 type: "string",
1141Details1141 description: "Override the base URL used during the ChatGPT login flow.",
1142 1142 },
1143HTTP headers populated from environment variables for an MCP HTTP server.1143 {
1144 1144 key: "cli_auth_credentials_store",
1145Key1145 type: "file | keyring | auto",
1146 1146 description:
1147`mcp_servers.<id>.env_vars`1147 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",
1148 1148 },
1149Type / Values1149 {
1150 1150 key: "mcp_oauth_credentials_store",
1151`array<string | { name = string, source = "local" | "remote" }>`1151 type: "auto | file | keyring",
1152 1152 description: "Preferred store for MCP OAuth credentials.",
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_port",
1156 1156 type: "integer",
1157Key1157 description:
1158 1158 "Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.",
1159`mcp_servers.<id>.experimental_environment`1159 },
1160 1160 {
1161Type / Values1161 key: "mcp_oauth_callback_url",
1162 1162 type: "string",
1163`local | remote`1163 description:
1164 1164 "Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.",
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: "experimental_use_unified_exec_tool",
1168 1168 type: "boolean",
1169Key1169 description:
1170 1170 "Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.",
1171`mcp_servers.<id>.http_headers`1171 },
1172 1172 {
1173Type / Values1173 key: "tools.web_search",
1174 1174 type: 'boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }',
1175`map<string,string>`1175 description:
1176 1176 "Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.",
1177Details1177 },
1178 1178 {
1179Static HTTP headers included with each MCP HTTP request.1179 key: "tools.view_image",
1180 1180 type: "boolean",
1181Key1181 description: "Enable the local-image attachment tool `view_image`.",
1182 1182 },
1183`mcp_servers.<id>.oauth_resource`1183 {
1184 1184 key: "web_search",
1185Type / Values1185 type: "disabled | cached | live",
1186 1186 description:
1187`string`1187 'Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool.',
1188 1188 },
1189Details1189 {
1190 1190 key: "default_permissions",
1191Optional RFC 8707 OAuth resource parameter to include during MCP login.1191 type: "string",
1192 1192 description:
1193Key1193 "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.",
1194 1194 },
1195`mcp_servers.<id>.required`1195 {
1196 1196 key: "permissions.<name>.filesystem",
1197Type / Values1197 type: "table",
1198 1198 description:
1199`boolean`1199 "Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.",
1200 1200 },
1201Details1201 {
1202 1202 key: "permissions.<name>.filesystem.glob_scan_max_depth",
1203When true, fail startup/resume if this enabled MCP server cannot initialize.1203 type: "number",
1204 1204 description:
1205Key1205 "Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.",
1206 1206 },
1207`mcp_servers.<id>.scopes`1207 {
1208 1208 key: "permissions.<name>.filesystem.<path-or-glob>",
1209Type / Values1209 type: '"read" | "write" | "none" | table',
1210 1210 description:
1211`array<string>`1211 'Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths.',
1212 1212 },
1213Details1213 {
1214 1214 key: 'permissions.<name>.filesystem.":project_roots".<subpath-or-glob>',
1215OAuth scopes to request when authenticating to that MCP server.1215 type: '"read" | "write" | "none"',
1216 1216 description:
1217Key1217 'Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.',
1218 1218 },
1219`mcp_servers.<id>.startup_timeout_ms`1219 {
1220 1220 key: "permissions.<name>.network.enabled",
1221Type / Values1221 type: "boolean",
1222 1222 description: "Enable network access for this named permissions profile.",
1223`number`1223 },
1224 1224 {
1225Details1225 key: "permissions.<name>.network.proxy_url",
1226 1226 type: "string",
1227Alias for `startup_timeout_sec` in milliseconds.1227 description:
1228 1228 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.",
1229Key1229 },
1230 1230 {
1231`mcp_servers.<id>.startup_timeout_sec`1231 key: "permissions.<name>.network.enable_socks5",
1232 1232 type: "boolean",
1233Type / Values1233 description:
1234 1234 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.",
1235`number`1235 },
1236 1236 {
1237Details1237 key: "permissions.<name>.network.socks_url",
1238 1238 type: "string",
1239Override the default 10s startup timeout for an MCP server.1239 description: "SOCKS5 proxy endpoint used by this permissions profile.",
1240 1240 },
1241Key1241 {
1242 1242 key: "permissions.<name>.network.enable_socks5_udp",
1243`mcp_servers.<id>.tool_timeout_sec`1243 type: "boolean",
1244 1244 description: "Allow UDP over the SOCKS5 listener when enabled.",
1245Type / Values1245 },
1246 1246 {
1247`number`1247 key: "permissions.<name>.network.allow_upstream_proxy",
1248 1248 type: "boolean",
1249Details1249 description:
1250 1250 "Allow the managed proxy to chain to another upstream proxy.",
1251Override the default 60s per-tool timeout for an MCP server.1251 },
1252 1252 {
1253Key1253 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1254 1254 type: "boolean",
1255`mcp_servers.<id>.url`1255 description:
1256 1256 "Permit non-loopback bind addresses for the managed proxy listener.",
1257Type / Values1257 },
1258 1258 {
1259`string`1259 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1260 1260 type: "boolean",
1261Details1261 description:
1262 1262 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.",
1263Endpoint for an MCP streamable HTTP server.1263 },
1264 1264 {
1265Key1265 key: "permissions.<name>.network.mode",
1266 1266 type: "limited | full",
1267`memories.consolidation_model`1267 description: "Network proxy mode used for subprocess traffic.",
1268 1268 },
1269Type / Values1269 {
1270 1270 key: "permissions.<name>.network.domains",
1271`string`1271 type: "map<string, allow | deny>",
1272 1272 description:
1273Details1273 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.",
1274 1274 },
1275Optional model override for global memory consolidation.1275 {
1276 1276 key: "permissions.<name>.network.unix_sockets",
1277Key1277 type: "map<string, allow | none>",
1278 1278 description:
1279`memories.disable_on_external_context`1279 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.",
1280 1280 },
1281Type / Values1281 {
1282 1282 key: "permissions.<name>.network.allow_local_binding",
1283`boolean`1283 type: "boolean",
1284 1284 description:
1285Details1285 "Permit local bind/listen operations through the managed proxy.",
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: "projects.<path>.trust_level",
1289Key1289 type: "string",
1290 1290 description:
1291`memories.extract_model`1291 'Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.',
1292 1292 },
1293Type / Values1293 {
1294 1294 key: "notice.hide_full_access_warning",
1295`string`1295 type: "boolean",
1296 1296 description: "Track acknowledgement of the full access warning prompt.",
1297Details1297 },
1298 1298 {
1299Optional model override for per-thread memory extraction.1299 key: "notice.hide_world_writable_warning",
1300 1300 type: "boolean",
1301Key1301 description:
1302 1302 "Track acknowledgement of the Windows world-writable directories warning.",
1303`memories.generate_memories`1303 },
1304 1304 {
1305Type / Values1305 key: "notice.hide_rate_limit_model_nudge",
1306 1306 type: "boolean",
1307`boolean`1307 description: "Track opt-out of the rate limit model switch reminder.",
1308 1308 },
1309Details1309 {
1310 1310 key: "notice.hide_gpt5_1_migration_prompt",
1311When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.1311 type: "boolean",
1312 1312 description: "Track acknowledgement of the GPT-5.1 migration prompt.",
1313Key1313 },
1314 1314 {
1315`memories.max_raw_memories_for_consolidation`1315 key: "notice.hide_gpt-5.1-codex-max_migration_prompt",
1316 1316 type: "boolean",
1317Type / Values1317 description:
1318 1318 "Track acknowledgement of the gpt-5.1-codex-max migration prompt.",
1319`number`1319 },
1320 1320 {
1321Details1321 key: "notice.model_migrations",
1322 1322 type: "map<string,string>",
1323Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.1323 description: "Track acknowledged model migrations as old->new mappings.",
1324 1324 },
1325Key1325 {
1326 1326 key: "forced_login_method",
1327`memories.max_rollout_age_days`1327 type: "chatgpt | api",
1328 1328 description: "Restrict Codex to a specific authentication method.",
1329Type / Values1329 },
1330 1330 {
1331`number`1331 key: "forced_chatgpt_workspace_id",
1332 1332 type: "string (uuid)",
1333Details1333 description: "Limit ChatGPT logins to a specific workspace identifier.",
1334 1334 },
1335Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.1335 ]}
1336 1336 client:load
1337Key1337/>
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 1338
3019You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).1339You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).
3020 1340
3036Use `[features]` in `requirements.toml` to pin feature flags by the same1356Use `[features]` in `requirements.toml` to pin feature flags by the same
3037canonical keys that `config.toml` uses. Omitted keys remain unconstrained.1357canonical keys that `config.toml` uses. Omitted keys remain unconstrained.
3038 1358
3039| Key | Type / Values | Details |1359<ConfigTable
3040| --- | --- | --- |1360 options={[
3041| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |1361 {
3042| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |1362 key: "allowed_approval_policies",
3043| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |1363 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`. |1364 description:
3045| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |1365 "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",
3046| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |1366 },
3047| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. |1367 {
3048| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. |1368 key: "allowed_approvals_reviewers",
3049| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |1369 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. |1370 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`. |1371 "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`. |1372 },
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. |1373 {
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. |1374 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. |1375 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. |1376 description:
3057| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |1377 "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. |1378 },
3059| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |1379 {
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. |1380 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. |1381 type: "array<string>",
3062| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |1382 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. |1383 },
3064| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |1384 {
3065| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |1385 key: "remote_sandbox_config",
3066| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |1386 type: "array<table>",
3067| `rules.prefix_rules[].justification` | `string` | Optional non-empty rationale surfaced in approval prompts or rejection messages. |1387 description:
3068| `rules.prefix_rules[].pattern` | `array<table>` | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. |1388 "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. |1389 },
3070| `rules.prefix_rules[].pattern[].token` | `string` | A single literal token at this position. |1390 {
3071 1391 key: "remote_sandbox_config[].hostname_patterns",
3072Key1392 type: "array<string>",
3073 1393 description:
3074`allowed_approval_policies`1394 "Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.",
3075 1395 },
3076Type / Values1396 {
3077 1397 key: "remote_sandbox_config[].allowed_sandbox_modes",
3078`array<string>`1398 type: "array<string>",
3079 1399 description:
3080Details1400 "Allowed sandbox modes to apply when this host-specific entry matches.",
3081 1401 },
3082Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).1402 {
3083 1403 key: "allowed_web_search_modes",
3084Key1404 type: "array<string>",
3085 1405 description:
3086`allowed_approvals_reviewers`1406 "Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.",
3087 1407 },
3088Type / Values1408 {
3089 1409 key: "features",
3090`array<string>`1410 type: "table",
3091 1411 description:
3092Details1412 "Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.",
3093 1413 },
3094Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.1414 {
3095 1415 key: "features.<name>",
3096Key1416 type: "boolean",
3097 1417 description:
3098`allowed_sandbox_modes`1418 "Require a specific canonical feature key to stay enabled or disabled.",
3099 1419 },
3100Type / Values1420 {
3101 1421 key: "features.in_app_browser",
3102`array<string>`1422 type: "boolean",
3103 1423 description:
3104Details1424 "Set to `false` in `requirements.toml` to disable the in-app browser pane.",
3105 1425 },
3106Allowed values for `sandbox_mode`.1426 {
3107 1427 key: "features.browser_use",
3108Key1428 type: "boolean",
3109 1429 description:
3110`allowed_web_search_modes`1430 "Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.",
3111 1431 },
3112Type / Values1432 {
3113 1433 key: "features.computer_use",
3114`array<string>`1434 type: "boolean",
3115 1435 description:
3116Details1436 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
3117 1437 },
3118Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.1438 {
3119 1439 key: "hooks",
3120Key1440 type: "table",
3121 1441 description:
3122`features`1442 "Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.",
3123 1443 },
3124Type / Values1444 {
3125 1445 key: "hooks.managed_dir",
3126`table`1446 type: "string (absolute path)",
3127 1447 description:
3128Details1448 "Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.",
3129 1449 },
3130Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.1450 {
3131 1451 key: "hooks.windows_managed_dir",
3132Key1452 type: "string (absolute path)",
3133 1453 description:
3134`features.<name>`1454 "Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.",
3135 1455 },
3136Type / Values1456 {
3137 1457 key: "hooks.<Event>",
3138`boolean`1458 type: "array<table>",
3139 1459 description:
3140Details1460 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
3141 1461 },
3142Require a specific canonical feature key to stay enabled or disabled.1462 {
3143 1463 key: "hooks.<Event>[].hooks",
3144Key1464 type: "array<table>",
3145 1465 description:
3146`features.browser_use`1466 "Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.",
3147 1467 },
3148Type / Values1468 {
3149 1469 key: "permissions.filesystem.deny_read",
3150`boolean`1470 type: "array<string>",
3151 1471 description:
3152Details1472 "Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.",
3153 1473 },
3154Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.1474 {
3155 1475 key: "mcp_servers",
3156Key1476 type: "table",
3157 1477 description:
3158`features.computer_use`1478 "Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.",
3159 1479 },
3160Type / Values1480 {
3161 1481 key: "mcp_servers.<id>.identity",
3162`boolean`1482 type: "table",
3163 1483 description:
3164Details1484 "Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",
3165 1485 },
3166Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.1486 {
3167 1487 key: "mcp_servers.<id>.identity.command",
3168Key1488 type: "string",
3169 1489 description:
3170`features.in_app_browser`1490 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",
3171 1491 },
3172Type / Values1492 {
3173 1493 key: "mcp_servers.<id>.identity.url",
3174`boolean`1494 type: "string",
3175 1495 description:
3176Details1496 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",
3177 1497 },
3178Set to `false` in `requirements.toml` to disable the in-app browser pane.1498 {
3179 1499 key: "rules",
3180Key1500 type: "table",
3181 1501 description:
3182`guardian_policy_config`1502 "Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.",
3183 1503 },
3184Type / Values1504 {
3185 1505 key: "rules.prefix_rules",
3186`string`1506 type: "array<table>",
3187 1507 description:
3188Details1508 "List of enforced prefix rules. Each rule must include `pattern` and `decision`.",
3189 1509 },
3190Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.1510 {
3191 1511 key: "rules.prefix_rules[].pattern",
3192Key1512 type: "array<table>",
3193 1513 description:
3194`hooks`1514 "Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.",
3195 1515 },
3196Type / Values1516 {
3197 1517 key: "rules.prefix_rules[].pattern[].token",
3198`table`1518 type: "string",
3199 1519 description: "A single literal token at this position.",
3200Details1520 },
3201 1521 {
3202Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.1522 key: "rules.prefix_rules[].pattern[].any_of",
3203 1523 type: "array<string>",
3204Key1524 description: "A list of allowed alternative tokens at this position.",
3205 1525 },
3206`hooks.<Event>`1526 {
3207 1527 key: "rules.prefix_rules[].decision",
3208Type / Values1528 type: "prompt | forbidden",
3209 1529 description:
3210`array<table>`1530 "Required. Requirements rules can only prompt or forbid (not allow).",
3211 1531 },
3212Details1532 {
3213 1533 key: "rules.prefix_rules[].justification",
3214Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.1534 type: "string",
3215 1535 description:
3216Key1536 "Optional non-empty rationale surfaced in approval prompts or rejection messages.",
3217 1537 },
3218`hooks.<Event>[].hooks`1538 ]}
3219 1539 client:load
3220Type / Values1540/>
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
