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