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