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