config-reference.md Codex Docs, 2026-04-23 00:46 UTC → 2026-05-12 01:59 UTC

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

11| Key | Type / Values | Details |11<ConfigTable

12| --- | --- | --- |12 options={[

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13 {

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14 key: "model",

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15 type: "string",

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |16 description: "Model to use (e.g., `gpt-5.5`).",

17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17 },

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18 {

19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19 key: "review_model",

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20 type: "string",

21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21 description:

22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |22 "Optional model override used by `/review` (defaults to the current session model).",

23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |23 },

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |24 {

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |25 key: "model_provider",

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |26 type: "string",

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |27 description: "Provider id from `model_providers` (default: `openai`).",

28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28 },

29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29 {

30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30 key: "openai_base_url",

31| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |31 type: "string",

32| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |32 description:

33| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |33 "Base URL override for the built-in `openai` model provider.",

34| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |34 },

35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |35 {

36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36 key: "model_context_window",

37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |37 type: "number",

38| `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. |38 description: "Context window tokens available to the active model.",

39| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |39 },

40| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |40 {

41| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |41 key: "model_auto_compact_token_limit",

42| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |42 type: "number",

43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |43 description:

44| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |44 "Token threshold that triggers automatic history compaction (unset uses model defaults).",

45| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |45 },

46| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46 {

47| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |47 key: "model_catalog_json",

48| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |48 type: "string (path)",

49| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |49 description:

50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off 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.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |51 },

52| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |52 {

53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |53 key: "oss_provider",

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54 type: "lmstudio | ollama",

55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |55 description:

56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56 "Default local provider used when running with `--oss` (defaults to prompting if unset).",

57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |57 },

58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |58 {

59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59 key: "approval_policy",

60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |60 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",

61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |61 description:

62| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |62 "Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.",

63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63 },

64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64 {

65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65 key: "approval_policy.granular.sandbox_approval",

66| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |66 type: "boolean",

67| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |67 description:

68| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |68 "When `true`, sandbox escalation approval prompts are allowed to surface.",

69| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |69 },

70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70 {

71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71 key: "approval_policy.granular.rules",

72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72 type: "boolean",

73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |73 description:

74| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |74 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",

75| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |75 },

76| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |76 {

77| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |77 key: "approval_policy.granular.mcp_elicitations",

78| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |78 type: "boolean",

79| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |79 description:

80| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |80 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",

81| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |81 },

82| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |82 {

83| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |83 key: "approval_policy.granular.request_permissions",

84| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |84 type: "boolean",

85| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |85 description:

86| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |86 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",

87| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |87 },

88| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |88 {

89| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |89 key: "approval_policy.granular.skill_approval",

90| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |90 type: "boolean",

91| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |91 description:

92| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |92 "When `true`, skill-script approval prompts are allowed to surface.",

93| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |93 },

94| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |94 {

95| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |95 key: "approvals_reviewer",

96| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |96 type: "user | auto_review",

97| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |97 description:

98| `memories.disable_on_external_context` | `boolean` | When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`. |98 "Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.",

99| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |99 },

100| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |100 {

101| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |101 key: "auto_review.policy",

102| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |102 type: "string",

103| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |103 description:

104| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |104 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",

105| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |105 },

106| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |106 {

107| `model` | `string` | Model to use (e.g., `gpt-5.4`). |107 key: "allow_login_shell",

108| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |108 type: "boolean",

109| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |109 description:

110| `model_context_window` | `number` | Context window tokens available to the active model. |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_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |111 },

112| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |112 {

113| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |113 key: "sandbox_mode",

114| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |114 type: "read-only | workspace-write | danger-full-access",

115| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |115 description:

116| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |116 "Sandbox policy for filesystem and network access during command execution.",

117| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |117 },

118| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |118 {

119| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |119 key: "sandbox_workspace_write.writable_roots",

120| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |120 type: "array<string>",

121| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |121 description:

122| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |122 'Additional writable roots when `sandbox_mode = "workspace-write"`.',

123| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |123 },

124| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |124 {

125| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |125 key: "sandbox_workspace_write.network_access",

126| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |126 type: "boolean",

127| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |127 description:

128| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |128 "Allow outbound network access inside the workspace-write sandbox.",

129| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |129 },

130| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |130 {

131| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |131 key: "sandbox_workspace_write.exclude_tmpdir_env_var",

132| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |132 type: "boolean",

133| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |133 description:

134| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |134 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",

135| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |135 },

136| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |136 {

137| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |137 key: "sandbox_workspace_write.exclude_slash_tmp",

138| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |138 type: "boolean",

139| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |139 description:

140| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |140 "Exclude `/tmp` from writable roots in workspace-write mode.",

141| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |141 },

142| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |142 {

143| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |143 key: "windows.sandbox",

144| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |144 type: "unelevated | elevated",

145| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |145 description:

146| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |146 "Windows-only native sandbox mode when running Codex natively on Windows.",

147| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |147 },

148| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |148 {

149| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |149 key: "windows.sandbox_private_desktop",

150| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |150 type: "boolean",

151| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |151 description:

152| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |152 "Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\\\Default` behavior.",

153| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |153 },

154| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |154 {

155| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |155 key: "notify",

156| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |156 type: "array<string>",

157| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |157 description:

158| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |158 "Command invoked for notifications; receives a JSON payload from Codex.",

159| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |159 },

160| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |160 {

161| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |161 key: "check_for_update_on_startup",

162| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |162 type: "boolean",

163| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |163 description:

164| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |164 "Check for Codex updates on startup (set to false only when updates are centrally managed).",

165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |165 },

166| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. |166 {

167| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |167 key: "feedback.enabled",

168| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |168 type: "boolean",

169| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |169 description:

170| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |170 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",

171| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |171 },

172| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |172 {

173| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |173 key: "analytics.enabled",

174| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |174 type: "boolean",

175| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |175 description:

176| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |176 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",

177| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |177 },

178| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |178 {

179| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |179 key: "instructions",

180| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |180 type: "string",

181| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |181 description:

182| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |182 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",

183| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |183 },

184| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |184 {

185| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |185 key: "developer_instructions",

186| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |186 type: "string",

187| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |187 description:

188| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |188 "Additional developer instructions injected into the session (optional).",

189| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |189 },

190| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |190 {

191| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |191 key: "log_dir",

192| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |192 type: "string (path)",

193| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |193 description:

194| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |194 "Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.",

195| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |195 },

196| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |196 {

197| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |197 key: "sqlite_home",

198| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |198 type: "string (path)",

199| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |199 description:

200| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |200 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",

201| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |201 },

202| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |202 {

203| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |203 key: "compact_prompt",

204| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |204 type: "string",

205| `service_tier` | `flex | fast` | Preferred service tier for new turns. |205 description: "Inline override for the history compaction prompt.",

206| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |206 },

207| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |207 {

208| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |208 key: "commit_attribution",

209| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |209 type: "string",

210| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |210 description:

211| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |211 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',

212| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |212 },

213| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |213 {

214| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |214 key: "model_instructions_file",

215| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |215 type: "string (path)",

216| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |216 description:

217| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |217 "Replacement for built-in instructions instead of `AGENTS.md`.",

218| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |218 },

219| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |219 {

220| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |220 key: "personality",

221| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |221 type: "none | friendly | pragmatic",

222| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |222 description:

223| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |223 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",

224| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |224 },

225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |225 {

226| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |226 key: "service_tier",

227| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |227 type: "flex | fast",

228| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |228 description: "Preferred service tier for new turns.",

229| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |229 },

230| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |230 {

231| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |231 key: "experimental_compact_prompt_file",

232| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |232 type: "string (path)",

233| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |233 description:

234| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |234 "Load the compaction prompt override from a file (experimental).",

235| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |235 },

236| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |236 {

237 237 key: "skills.config",

238Key238 type: "array<object>",

239 239 description: "Per-skill enablement overrides stored in config.toml.",

240`agents.<name>.config_file`240 },

241 241 {

242Type / Values242 key: "skills.config.<index>.path",

243 243 type: "string (path)",

244`string (path)`244 description: "Path to a skill folder containing `SKILL.md`.",

245 245 },

246Details246 {

247 247 key: "skills.config.<index>.enabled",

248Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.248 type: "boolean",

249 249 description: "Enable or disable the referenced skill.",

250Key250 },

251 251 {

252`agents.<name>.description`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`string`256 },

257 257 {

258Details258 key: "apps._default.enabled",

259 259 type: "boolean",

260Role guidance shown to Codex when choosing and spawning that agent type.260 description:

261 261 "Default app enabled state for all apps unless overridden per app.",

262Key262 },

263 263 {

264`agents.<name>.nickname_candidates`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`array<string>`268 },

269 269 {

270Details270 key: "apps._default.open_world_enabled",

271 271 type: "boolean",

272Optional pool of display nicknames for spawned agents in that role.272 description:

273 273 "Default allow/deny for app tools with `open_world_hint = true`.",

274Key274 },

275 275 {

276`agents.job_max_runtime_seconds`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",

284Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.284 description:

285 285 "Allow or block tools in this app that advertise `open_world_hint = true`.",

286Key286 },

287 287 {

288`agents.max_depth`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`number`292 },

293 293 {

294Details294 key: "apps.<id>.default_tools_approval_mode",

295 295 type: "auto | prompt | approve",

296Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).296 description:

297 297 "Default approval behavior for tools in this app unless a per-tool override exists.",

298Key298 },

299 299 {

300`agents.max_threads`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`number`304 },

305 305 {

306Details306 key: "apps.<id>.tools.<tool>.approval_mode",

307 307 type: "auto | prompt | approve",

308Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.308 description: "Per-tool approval behavior override for a single app tool.",

309 309 },

310Key310 {

311 311 key: "tool_suggest.discoverables",

312`allow_login_shell`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`boolean`316 {

317 317 key: "tool_suggest.disabled_tools",

318Details318 type: "array<table>",

319 319 description:

320Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells.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`analytics.enabled`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.",

332Enable or disable analytics for this machine/profile. When unset, the client default applies.332 },

333 333 {

334Key334 key: "features.codex_git_commit",

335 335 type: "boolean",

336`approval_policy`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`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`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.",

344Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.344 },

345 345 {

346Key346 key: "features.memories",

347 347 type: "boolean",

348`approval_policy.granular.mcp_elicitations`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`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.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.request_permissions`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`, prompts from the `request_permissions` tool 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.rules`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`, approvals triggered by execpolicy `prompt` rules are allowed to surface.380 },

381 381 {

382Key382 key: "mcp_servers.<id>.bearer_token_env_var",

383 383 type: "string",

384`approval_policy.granular.sandbox_approval`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 },

392When `true`, sandbox escalation approval prompts are allowed to surface.392 {

393 393 key: "mcp_servers.<id>.env_http_headers",

394Key394 type: "map<string,string>",

395 395 description:

396`approval_policy.granular.skill_approval`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 {

404When `true`, skill-script approval prompts are allowed to surface.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`approvals_reviewer`408 },

409 409 {

410Type / Values410 key: "mcp_servers.<id>.startup_timeout_sec",

411 411 type: "number",

412`user | guardian_subagent`412 description:

413 413 "Override the default 10s startup timeout for an MCP server.",

414Details414 },

415 415 {

416Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.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._default.destructive_enabled`420 {

421 421 key: "mcp_servers.<id>.tool_timeout_sec",

422Type / Values422 type: "number",

423 423 description:

424`boolean`424 "Override the default 60s per-tool timeout for an MCP server.",

425 425 },

426Details426 {

427 427 key: "mcp_servers.<id>.enabled_tools",

428Default allow/deny for app tools with `destructive_hint = true`.428 type: "array<string>",

429 429 description: "Allow list of tool names exposed by the MCP server.",

430Key430 },

431 431 {

432`apps._default.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 app enabled state for all apps unless overridden per app.440 description:

441 441 "OAuth scopes to request when authenticating to that MCP server.",

442Key442 },

443 443 {

444`apps._default.open_world_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",

452Default allow/deny for app tools with `open_world_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>.default_tools_approval_mode`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`auto | prompt | approve`460 },

461 461 {

462Details462 key: "agents.max_depth",

463 463 type: "number",

464Default approval behavior for tools in this app unless a per-tool override exists.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>.default_tools_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",

476Default enabled state for tools in this app unless a per-tool override exists.476 description:

477 477 "Role guidance shown to Codex when choosing and spawning that agent type.",

478Key478 },

479 479 {

480`apps.<id>.destructive_enabled`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`boolean`484 },

485 485 {

486Details486 key: "agents.<name>.nickname_candidates",

487 487 type: "array<string>",

488Allow or block tools in this app that advertise `destructive_hint = true`.488 description:

489 489 "Optional pool of display nicknames for spawned agents in that role.",

490Key490 },

491 491 {

492`apps.<id>.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",

500Enable or disable a specific app/connector by id (default: true).500 description:

501 501 "When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.",

502Key502 },

503 503 {

504`apps.<id>.open_world_enabled`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`boolean`508 },

509 509 {

510Details510 key: "memories.max_raw_memories_for_consolidation",

511 511 type: "number",

512Allow or block tools in this app that advertise `open_world_hint = true`.512 description:

513 513 "Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.",

514Key514 },

515 515 {

516`apps.<id>.tools.<tool>.approval_mode`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`auto | prompt | approve`520 },

521 521 {

522Details522 key: "memories.max_rollout_age_days",

523 523 type: "number",

524Per-tool approval behavior override for a single app tool.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`apps.<id>.tools.<tool>.enabled`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",

536Per-tool enabled override for an app tool (for example `repos/list`).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`background_terminal_max_timeout`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`number`544 },

545 545 {

546Details546 key: "memories.extract_model",

547 547 type: "string",

548Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.548 description: "Optional model override for per-thread memory extraction.",

549 549 },

550Key550 {

551 551 key: "memories.consolidation_model",

552`chatgpt_base_url`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 base URL used during the ChatGPT login flow.560 },

561 561 {

562Key562 key: "features.shell_snapshot",

563 563 type: "boolean",

564`check_for_update_on_startup`564 description:

565 565 "Snapshot shell environment to speed up repeated commands (stable; on by default).",

566Type / Values566 },

567 567 {

568`boolean`568 key: "features.undo",

569 569 type: "boolean",

570Details570 description: "Enable undo support (stable; off by default).",

571 571 },

572Check for Codex updates on startup (set to false only when updates are centrally managed).572 {

573 573 key: "features.multi_agent",

574Key574 type: "boolean",

575 575 description:

576`cli_auth_credentials_store`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`file | keyring | auto`580 type: "boolean",

581 581 description:

582Details582 "Enable personality selection controls (stable; on by default).",

583 583 },

584Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).584 {

585 585 key: "features.web_search",

586Key586 type: "boolean",

587 587 description:

588`commit_attribution`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 },

596Override the commit co-author trailer text. Set an empty string to disable automatic attribution.596 {

597 597 key: "features.web_search_request",

598Key598 type: "boolean",

599 599 description:

600`compact_prompt`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`string`604 type: "boolean",

605 605 description:

606Details606 "Enable the default `shell` tool for running commands (stable; on by default).",

607 607 },

608Inline override for the history compaction prompt.608 {

609 609 key: "features.enable_request_compression",

610Key610 type: "boolean",

611 611 description:

612`default_permissions`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`616 type: "boolean",

617 617 description:

618Details618 "Allow prompting and installing missing MCP dependencies for skills (stable; on by default).",

619 619 },

620Name of the default permissions profile to apply to sandboxed tool calls.620 {

621 621 key: "features.fast_mode",

622Key622 type: "boolean",

623 623 description:

624`developer_instructions`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`string`628 type: "boolean",

629 629 description:

630Details630 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",

631 631 },

632Additional developer instructions injected into the session (optional).632 {

633 633 key: "suppress_unstable_features_warning",

634Key634 type: "boolean",

635 635 description:

636`disable_paste_burst`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 },

644Disable burst-paste detection in the TUI.644 {

645 645 key: "model_providers.<id>.name",

646Key646 type: "string",

647 647 description: "Display name for a custom model provider.",

648`experimental_compact_prompt_file`648 },

649 649 {

650Type / Values650 key: "model_providers.<id>.base_url",

651 651 type: "string",

652`string (path)`652 description: "API base URL for the model provider.",

653 653 },

654Details654 {

655 655 key: "model_providers.<id>.env_key",

656Load the compaction prompt override from a file (experimental).656 type: "string",

657 657 description: "Environment variable supplying the provider API key.",

658Key658 },

659 659 {

660`experimental_use_unified_exec_tool`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:

668Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.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.apps`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 ChatGPT Apps/connectors support (experimental).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.codex_hooks`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 lifecycle hooks loaded from `hooks.json` (under development; off by default).692 {

693 693 key: "model_providers.<id>.env_http_headers",

694Key694 type: "map<string,string>",

695 695 description:

696`features.enable_request_compression`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 },

704Compress streaming request bodies with zstd when supported (stable; on 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.fast_mode`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 {

716Enable Fast mode selection and the `service_tier = "fast"` path (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.guardian_approval`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 {

728Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.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.memories`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",

740Enable [Memories](https://developers.openai.com/codex/memories) (off by default).740 type: "number",

741 741 description:

742Key742 "Maximum token command runtime in milliseconds (default: 5000).",

743 743 },

744`features.multi_agent`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",

752Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).752 type: "string (path)",

753 753 description: "Working directory for the token command.",

754Key754 },

755 755 {

756`features.personality`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 personality selection controls (stable; on 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.prevent_idle_sleep`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:

776Prevent the machine from sleeping while a turn is actively running (experimental; off by default).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.shell_snapshot`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:

788Snapshot shell environment to speed up repeated commands (stable; on by default).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.shell_tool`792 type: "boolean",

793 793 description: "Force Codex to send or not send reasoning metadata.",

794Type / Values794 },

795 795 {