config-reference.md Codex Docs, 2026-03-26 18:27 UTC → 2026-05-18 22:01 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).9Project-scoped config can't override machine-local provider, auth,

10 10notification, profile, or telemetry routing keys. Codex ignores

11| Key | Type / Values | Details |11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,

12| --- | --- | --- |12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13`otel` when they appear in a project-local `.codex/config.toml`; put those in

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14user-level config instead.

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

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

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

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

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

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

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

22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

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

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

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

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

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

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

29| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

30| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |

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

32| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

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

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

35| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

36| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

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. |

38| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

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

40| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

41| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

42| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

43| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

44| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

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

46| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

47| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

48| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

49| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

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

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). |

52| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

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

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

55| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

56| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

57| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

58| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

59| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

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

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

62| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

63| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |

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

65| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |

66| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |

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

68| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

69| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

70| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

71| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

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. |

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. |

74| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

75| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |

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

77| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |

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

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

80| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |

81| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |

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

83| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |

84| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |

85| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

86| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

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

88| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

89| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

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

91| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

92| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

93| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |

94| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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. |

96| `model_context_window` | `number` | Context window tokens available to the active model. |

97| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

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

99| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

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

101| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

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

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

104| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |

105| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |

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

107| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |

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

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

110| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

111| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

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. |

113| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

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

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

116| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |

117| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

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

119| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

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

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

122| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

123| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

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

125| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

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

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

128| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |

129| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |

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

131| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |

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

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

134| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

135| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |

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

137| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

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

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

140| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

141| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

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

143| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

144| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

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. |

146| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

147| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

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

149| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

150| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

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

152| `permissions.<name>.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

153| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

154| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

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

156| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

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

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

159| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

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. |

161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

164| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

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). |

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

167| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

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

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

170| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |

171| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

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

173| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

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

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

176| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

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

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

179| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

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

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

182| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

183| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

184| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

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

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

187| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

188| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |

189| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |

190| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |

191| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |

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

193| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

194| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

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

196| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

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

198| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

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. |

200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

201| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

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

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

204| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

205| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

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

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

208| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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. |

210| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

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. |

213 

214Key

215 

216`agents.<name>.config_file`

217 

218Type / Values

219 

220`string (path)`

221 

222Details

223 

224Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.

225 

226Key

227 

228`agents.<name>.description`

229 

230Type / Values

231 

232`string`

233 

234Details

235 

236Role guidance shown to Codex when choosing and spawning that agent type.

237 

238Key

239 

240`agents.<name>.nickname_candidates`

241 

242Type / Values

243 

244`array<string>`

245 

246Details

247 

248Optional pool of display nicknames for spawned agents in that role.

249 

250Key

251 

252`agents.job_max_runtime_seconds`

253 

254Type / Values

255 

256`number`

257 

258Details

259 

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

261 

262Key

263 

264`agents.max_depth`

265 

266Type / Values

267 

268`number`

269 

270Details

271 

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

273 

274Key

275 

276`agents.max_threads`

277 

278Type / Values

279 

280`number`

281 

282Details

283 

284Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

285 

286Key

287 

288`allow_login_shell`

289 

290Type / Values

291 

292`boolean`

293 

294Details

295 

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.

297 

298Key

299 

300`analytics.enabled`

301 

302Type / Values

303 

304`boolean`

305 

306Details

307 

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

309 

310Key

311 

312`approval_policy`

313 

314Type / Values

315 

316`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

317 

318Details

319 

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.

321 

322Key

323 

324`approval_policy.granular.mcp_elicitations`

325 

326Type / Values

327 

328`boolean`

329 

330Details

331 

332When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

333 

334Key

335 

336`approval_policy.granular.request_permissions`

337 

338Type / Values

339 

340`boolean`

341 

342Details

343 

344When `true`, prompts from the `request_permissions` tool are allowed to surface.

345 

346Key

347 

348`approval_policy.granular.rules`

349 

350Type / Values

351 

352`boolean`

353 

354Details

355 

356When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

357 

358Key

359 

360`approval_policy.granular.sandbox_approval`

361 

362Type / Values

363 

364`boolean`

365 

366Details

367 

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

369 

370Key

371 

372`approval_policy.granular.skill_approval`

373 

374Type / Values

375 

376`boolean`

377 

378Details

379 

380When `true`, skill-script approval prompts are allowed to surface.

381 

382Key

383 

384`apps._default.destructive_enabled`

385 

386Type / Values

387 

388`boolean`

389 

390Details

391 

392Default allow/deny for app tools with `destructive_hint = true`.

393 

394Key

395 

396`apps._default.enabled`

397 

398Type / Values

399 

400`boolean`

401 

402Details

403 

404Default app enabled state for all apps unless overridden per app.

405 

406Key

407 

408`apps._default.open_world_enabled`

409 

410Type / Values

411 

412`boolean`

413 

414Details

415 

416Default allow/deny for app tools with `open_world_hint = true`.

417 

418Key

419 

420`apps.<id>.default_tools_approval_mode`

421 

422Type / Values

423 

424`auto | prompt | approve`

425 

426Details

427 

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

429 

430Key

431 

432`apps.<id>.default_tools_enabled`

433 

434Type / Values

435 

436`boolean`

437 

438Details

439 

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

441 

442Key

443 

444`apps.<id>.destructive_enabled`

445 

446Type / Values

447 

448`boolean`

449 

450Details

451 

452Allow or block tools in this app that advertise `destructive_hint = true`.

453 

454Key

455 

456`apps.<id>.enabled`

457 

458Type / Values

459 

460`boolean`

461 

462Details

463 

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

465 

466Key

467 

468`apps.<id>.open_world_enabled`

469 

470Type / Values

471 

472`boolean`

473 

474Details

475 

476Allow or block tools in this app that advertise `open_world_hint = true`.

477 

478Key

479 

480`apps.<id>.tools.<tool>.approval_mode`

481 

482Type / Values

483 

484`auto | prompt | approve`

485 

486Details

487 

488Per-tool approval behavior override for a single app tool.

489 

490Key

491 

492`apps.<id>.tools.<tool>.enabled`

493 

494Type / Values

495 

496`boolean`

497 

498Details

499 

500Per-tool enabled override for an app tool (for example `repos/list`).

501 

502Key

503 

504`background_terminal_max_timeout`

505 

506Type / Values

507 

508`number`

509 

510Details

511 

512Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

513 

514Key

515 

516`chatgpt_base_url`

517 

518Type / Values

519 

520`string`

521 

522Details

523 

524Override the base URL used during the ChatGPT login flow.

525 

526Key

527 

528`check_for_update_on_startup`

529 

530Type / Values

531 

532`boolean`

533 

534Details

535 

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

537 

538Key

539 

540`cli_auth_credentials_store`

541 

542Type / Values

543 

544`file | keyring | auto`

545 

546Details

547 

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

549 

550Key

551 

552`commit_attribution`

553 

554Type / Values

555 

556`string`

557 

558Details

559 

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

561 

562Key

563 

564`compact_prompt`

565 

566Type / Values

567 

568`string`

569 

570Details

571 

572Inline override for the history compaction prompt.

573 

574Key

575 

576`default_permissions`

577 

578Type / Values

579 

580`string`

581 

582Details

583 

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

585 

586Key

587 

588`developer_instructions`

589 

590Type / Values

591 

592`string`

593 

594Details

595 

596Additional developer instructions injected into the session (optional).

597 

598Key

599 

600`disable_paste_burst`

601 

602Type / Values

603 

604`boolean`

605 

606Details

607 

608Disable burst-paste detection in the TUI.

609 

610Key

611 

612`experimental_compact_prompt_file`

613 

614Type / Values

615 

616`string (path)`

617 

618Details

619 

620Load the compaction prompt override from a file (experimental).

621 

622Key

623 

624`experimental_use_unified_exec_tool`

625 

626Type / Values

627 

628`boolean`

629 

630Details

631 

632Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

633 

634Key

635 

636`features.apps`

637 

638Type / Values

639 

640`boolean`

641 

642Details

643 

644Enable ChatGPT Apps/connectors support (experimental).

645 

646Key

647 

648`features.enable_request_compression`

649 

650Type / Values

651 

652`boolean`

653 

654Details

655 

656Compress streaming request bodies with zstd when supported (stable; on by default).

657 

658Key

659 

660`features.fast_mode`

661 

662Type / Values

663 

664`boolean`

665 

666Details

667 

668Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

669 

670Key

671 

672`features.multi_agent`

673 

674Type / Values

675 

676`boolean`

677 

678Details

679 

680Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

681 

682Key

683 

684`features.personality`

685 

686Type / Values

687 

688`boolean`

689 

690Details

691 

692Enable personality selection controls (stable; on by default).

693 

694Key

695 

696`features.prevent_idle_sleep`

697 

698Type / Values

699 

700`boolean`

701 

702Details

703 

704Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

705 

706Key

707 

708`features.shell_snapshot`

709 

710Type / Values

711 

712`boolean`

713 

714Details

715 

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

717 

718Key

719 

720`features.shell_tool`

721 

722Type / Values

723 

724`boolean`

725 

726Details

727 

728Enable the default `shell` tool for running commands (stable; on by default).

729 

730Key

731 

732`features.skill_mcp_dependency_install`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

740Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

741 

742Key

743 

744`features.smart_approvals`

745 

746Type / Values

747 

748`boolean`

749 

750Details

751 

752Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

753 

754Key

755 

756`features.undo`

757 

758Type / Values

759 

760`boolean`

761 

762Details

763 

764Enable undo support (stable; off by default).

765 

766Key

767 

768`features.unified_exec`

769 

770Type / Values

771 

772`boolean`

773 

774Details

775 

776Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

777 

778Key

779 

780`features.web_search`

781 

782Type / Values

783 

784`boolean`

785 

786Details

787 

788Deprecated legacy toggle; prefer the top-level `web_search` setting.

789 

790Key

791 

792`features.web_search_cached`

793 

794Type / Values

795 

796`boolean`

797 

798Details

799 

800Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

801 

802Key

803 

804`features.web_search_request`

805 

806Type / Values

807 

808`boolean`

809 

810Details

811 

812Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

813 

814Key

815 

816`feedback.enabled`

817 

818Type / Values

819 

820`boolean`

821 

822Details

823 

824Enable feedback submission via `/feedback` across Codex surfaces (default: true).

825 

826Key

827 

828`file_opener`

829 

830Type / Values

831 

832`vscode | vscode-insiders | windsurf | cursor | none`

833 

834Details

835 

836URI scheme used to open citations from Codex output (default: `vscode`).

837 

838Key

839 

840`forced_chatgpt_workspace_id`

841 

842Type / Values

843 

844`string (uuid)`

845 

846Details

847 

848Limit ChatGPT logins to a specific workspace identifier.

849 

850Key

851 

852`forced_login_method`

853 

854Type / Values

855 

856`chatgpt | api`

857 

858Details

859 

860Restrict Codex to a specific authentication method.

861 

862Key

863 

864`hide_agent_reasoning`

865 

866Type / Values

867 

868`boolean`

869 

870Details

871 

872Suppress reasoning events in both the TUI and `codex exec` output.

873 

874Key

875 

876`history.max_bytes`

877 

878Type / Values

879 

880`number`

881 

882Details

883 

884If set, caps the history file size in bytes by dropping oldest entries.

885 

886Key

887 

888`history.persistence`

889 

890Type / Values

891 

892`save-all | none`

893 

894Details

895 

896Control whether Codex saves session transcripts to history.jsonl.

897 

898Key

899 

900`instructions`

901 

902Type / Values

903 

904`string`

905 

906Details

907 

908Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

909 

910Key

911 

912`log_dir`

913 

914Type / Values

915 

916`string (path)`

917 

918Details

919 

920Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

921 

922Key

923 

924`mcp_oauth_callback_port`

925 

926Type / Values

927 

928`integer`

929 

930Details

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.

933 

934Key

935 

936`mcp_oauth_callback_url`

937 

938Type / Values

939 

940`string`

941 

942Details

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.

945 

946Key

947 

948`mcp_oauth_credentials_store`

949 

950Type / Values

951 

952`auto | file | keyring`

953 

954Details

955 

956Preferred store for MCP OAuth credentials.

957 

958Key

959 

960`mcp_servers.<id>.args`

961 

962Type / Values

963 

964`array<string>`

965 

966Details

967 

968Arguments passed to the MCP stdio server command.

969 

970Key

971 

972`mcp_servers.<id>.bearer_token_env_var`

973 

974Type / Values

975 

976`string`

977 

978Details

979 

980Environment variable sourcing the bearer token for an MCP HTTP server.

981 

982Key

983 

984`mcp_servers.<id>.command`

985 

986Type / Values

987 

988`string`

989 

990Details

991 

992Launcher command for an MCP stdio server.

993 

994Key

995 

996`mcp_servers.<id>.cwd`

997 

998Type / Values

999 

1000`string`

1001 

1002Details

1003 

1004Working directory for the MCP stdio server process.

1005 

1006Key

1007 

1008`mcp_servers.<id>.disabled_tools`

1009 

1010Type / Values

1011 

1012`array<string>`

1013 

1014Details

1015 

1016Deny list applied after `enabled_tools` for the MCP server.

1017 

1018Key

1019 

1020`mcp_servers.<id>.enabled`

1021 

1022Type / Values

1023 

1024`boolean`

1025 

1026Details

1027 

1028Disable an MCP server without removing its configuration.

1029 

1030Key

1031 

1032`mcp_servers.<id>.enabled_tools`

1033 

1034Type / Values

1035 

1036`array<string>`

1037 

1038Details

1039 

1040Allow list of tool names exposed by the MCP server.

1041 

1042Key

1043 

1044`mcp_servers.<id>.env`

1045 

1046Type / Values

1047 

1048`map<string,string>`

1049 

1050Details

1051 

1052Environment variables forwarded to the MCP stdio server.

1053 

1054Key

1055 

1056`mcp_servers.<id>.env_http_headers`

1057 

1058Type / Values

1059 

1060`map<string,string>`

1061 

1062Details

1063 

1064HTTP headers populated from environment variables for an MCP HTTP server.

1065 

1066Key

1067 

1068`mcp_servers.<id>.env_vars`

1069 

1070Type / Values

1071 

1072`array<string>`

1073 

1074Details

1075 

1076Additional environment variables to whitelist for an MCP stdio server.

1077 

1078Key

1079 

1080`mcp_servers.<id>.http_headers`

1081 

1082Type / Values

1083 

1084`map<string,string>`

1085 

1086Details

1087 

1088Static HTTP headers included with each MCP HTTP request.

1089 

1090Key

1091 

1092`mcp_servers.<id>.oauth_resource`

1093 

1094Type / Values

1095 

1096`string`

1097 

1098Details

1099 

1100Optional RFC 8707 OAuth resource parameter to include during MCP login.

1101 

1102Key

1103 

1104`mcp_servers.<id>.required`

1105 

1106Type / Values

1107 

1108`boolean`

1109 

1110Details

1111 

1112When true, fail startup/resume if this enabled MCP server cannot initialize.

1113 

1114Key

1115 

1116`mcp_servers.<id>.scopes`

1117 

1118Type / Values

1119 

1120`array<string>`

1121 

1122Details

1123 

1124OAuth scopes to request when authenticating to that MCP server.

1125 

1126Key

1127 

1128`mcp_servers.<id>.startup_timeout_ms`

1129 

1130Type / Values

1131 

1132`number`

1133 

1134Details

1135 

1136Alias for `startup_timeout_sec` in milliseconds.

1137 

1138Key

1139 

1140`mcp_servers.<id>.startup_timeout_sec`

1141 

1142Type / Values

1143 

1144`number`

1145 

1146Details

1147 

1148Override the default 10s startup timeout for an MCP server.

1149 

1150Key

1151 

1152`mcp_servers.<id>.tool_timeout_sec`

1153 

1154Type / Values

1155 

1156`number`

1157 

1158Details

1159 

1160Override the default 60s per-tool timeout for an MCP server.

1161 

1162Key

1163 

1164`mcp_servers.<id>.url`

1165 

1166Type / Values

1167 

1168`string`

1169 

1170Details

1171 

1172Endpoint for an MCP streamable HTTP server.

1173 

1174Key

1175 

1176`model`

1177 

1178Type / Values

1179 

1180`string`

1181 

1182Details

1183 

1184Model to use (e.g., `gpt-5-codex`).

1185 

1186Key

1187 

1188`model_auto_compact_token_limit`

1189 

1190Type / Values

1191 

1192`number`

1193 

1194Details

1195 

1196Token threshold that triggers automatic history compaction (unset uses model defaults).

1197 

1198Key

1199 

1200`model_catalog_json`

1201 

1202Type / Values

1203 

1204`string (path)`

1205 

1206Details

1207 

1208Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1209 

1210Key

1211 

1212`model_context_window`

1213 

1214Type / Values

1215 

1216`number`

1217 

1218Details

1219 

1220Context window tokens available to the active model.

1221 

1222Key

1223 

1224`model_instructions_file`

1225 

1226Type / Values

1227 

1228`string (path)`

1229 

1230Details

1231 

1232Replacement for built-in instructions instead of `AGENTS.md`.

1233 

1234Key

1235 

1236`model_provider`

1237 

1238Type / Values

1239 

1240`string`

1241 

1242Details

1243 

1244Provider id from `model_providers` (default: `openai`).

1245 

1246Key

1247 

1248`model_providers.<id>.base_url`

1249 

1250Type / Values

1251 

1252`string`

1253 

1254Details

1255 

1256API base URL for the model provider.

1257 

1258Key

1259 

1260`model_providers.<id>.env_http_headers`

1261 

1262Type / Values

1263 

1264`map<string,string>`

1265 

1266Details

1267 

1268HTTP headers populated from environment variables when present.

1269 

1270Key

1271 

1272`model_providers.<id>.env_key`

1273 

1274Type / Values

1275 

1276`string`

1277 

1278Details

1279 

1280Environment variable supplying the provider API key.

1281 

1282Key

1283 

1284`model_providers.<id>.env_key_instructions`

1285 

1286Type / Values

1287 

1288`string`

1289 

1290Details

1291 

1292Optional setup guidance for the provider API key.

1293 

1294Key

1295 

1296`model_providers.<id>.experimental_bearer_token`

1297 

1298Type / Values

1299 

1300`string`

1301 

1302Details

1303 

1304Direct bearer token for the provider (discouraged; use `env_key`).

1305 

1306Key

1307 

1308`model_providers.<id>.http_headers`

1309 

1310Type / Values

1311 

1312`map<string,string>`

1313 

1314Details

1315 

1316Static HTTP headers added to provider requests.

1317 

1318Key

1319 

1320`model_providers.<id>.name`

1321 

1322Type / Values

1323 

1324`string`

1325 

1326Details

1327 

1328Display name for a custom model provider.

1329 

1330Key

1331 

1332`model_providers.<id>.query_params`

1333 

1334Type / Values

1335 

1336`map<string,string>`

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