config-reference.md Codex Docs, 2026-04-15 18:31 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| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

74| `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| `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| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

95| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

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

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

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

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

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

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

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

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

104| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |

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

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

107| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

154| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

223 

224Key

225 

226`agents.<name>.config_file`

227 

228Type / Values

229 

230`string (path)`

231 

232Details

233 

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

235 

236Key

237 

238`agents.<name>.description`

239 

240Type / Values

241 

242`string`

243 

244Details

245 

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

247 

248Key

249 

250`agents.<name>.nickname_candidates`

251 

252Type / Values

253 

254`array<string>`

255 

256Details

257 

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

259 

260Key

261 

262`agents.job_max_runtime_seconds`

263 

264Type / Values

265 

266`number`

267 

268Details

269 

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

271 

272Key

273 

274`agents.max_depth`

275 

276Type / Values

277 

278`number`

279 

280Details

281 

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

283 

284Key

285 

286`agents.max_threads`

287 

288Type / Values

289 

290`number`

291 

292Details

293 

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

295 

296Key

297 

298`allow_login_shell`

299 

300Type / Values

301 

302`boolean`

303 

304Details

305 

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

307 

308Key

309 

310`analytics.enabled`

311 

312Type / Values

313 

314`boolean`

315 

316Details

317 

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

319 

320Key

321 

322`approval_policy`

323 

324Type / Values

325 

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

327 

328Details

329 

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

331 

332Key

333 

334`approval_policy.granular.mcp_elicitations`

335 

336Type / Values

337 

338`boolean`

339 

340Details

341 

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

343 

344Key

345 

346`approval_policy.granular.request_permissions`

347 

348Type / Values

349 

350`boolean`

351 

352Details

353 

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

355 

356Key

357 

358`approval_policy.granular.rules`

359 

360Type / Values

361 

362`boolean`

363 

364Details

365 

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

367 

368Key

369 

370`approval_policy.granular.sandbox_approval`

371 

372Type / Values

373 

374`boolean`

375 

376Details

377 

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

379 

380Key

381 

382`approval_policy.granular.skill_approval`

383 

384Type / Values

385 

386`boolean`

387 

388Details

389 

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

391 

392Key

393 

394`approvals_reviewer`

395 

396Type / Values

397 

398`user | guardian_subagent`

399 

400Details

401 

402Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

403 

404Key

405 

406`apps._default.destructive_enabled`

407 

408Type / Values

409 

410`boolean`

411 

412Details

413 

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

415 

416Key

417 

418`apps._default.enabled`

419 

420Type / Values

421 

422`boolean`

423 

424Details

425 

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

427 

428Key

429 

430`apps._default.open_world_enabled`

431 

432Type / Values

433 

434`boolean`

435 

436Details

437 

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

439 

440Key

441 

442`apps.<id>.default_tools_approval_mode`

443 

444Type / Values

445 

446`auto | prompt | approve`

447 

448Details

449 

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

451 

452Key

453 

454`apps.<id>.default_tools_enabled`

455 

456Type / Values

457 

458`boolean`

459 

460Details

461 

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

463 

464Key

465 

466`apps.<id>.destructive_enabled`

467 

468Type / Values

469 

470`boolean`

471 

472Details

473 

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

475 

476Key

477 

478`apps.<id>.enabled`

479 

480Type / Values

481 

482`boolean`

483 

484Details

485 

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

487 

488Key

489 

490`apps.<id>.open_world_enabled`

491 

492Type / Values

493 

494`boolean`

495 

496Details

497 

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

499 

500Key

501 

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

503 

504Type / Values

505 

506`auto | prompt | approve`

507 

508Details

509 

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

511 

512Key

513 

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

515 

516Type / Values

517 

518`boolean`

519 

520Details

521 

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

523 

524Key

525 

526`background_terminal_max_timeout`

527 

528Type / Values

529 

530`number`

531 

532Details

533 

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

535 

536Key

537 

538`chatgpt_base_url`

539 

540Type / Values

541 

542`string`

543 

544Details

545 

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

547 

548Key

549 

550`check_for_update_on_startup`

551 

552Type / Values

553 

554`boolean`

555 

556Details

557 

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

559 

560Key

561 

562`cli_auth_credentials_store`

563 

564Type / Values

565 

566`file | keyring | auto`

567 

568Details

569 

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

571 

572Key

573 

574`commit_attribution`

575 

576Type / Values

577 

578`string`

579 

580Details

581 

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

583 

584Key

585 

586`compact_prompt`

587 

588Type / Values

589 

590`string`

591 

592Details

593 

594Inline override for the history compaction prompt.

595 

596Key

597 

598`default_permissions`

599 

600Type / Values

601 

602`string`

603 

604Details

605 

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

607 

608Key

609 

610`developer_instructions`

611 

612Type / Values

613 

614`string`

615 

616Details

617 

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

619 

620Key

621 

622`disable_paste_burst`

623 

624Type / Values

625 

626`boolean`

627 

628Details

629 

630Disable burst-paste detection in the TUI.

631 

632Key

633 

634`experimental_compact_prompt_file`

635 

636Type / Values

637 

638`string (path)`

639 

640Details

641 

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

643 

644Key

645 

646`experimental_use_unified_exec_tool`

647 

648Type / Values

649 

650`boolean`

651 

652Details

653 

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

655 

656Key

657 

658`features.apps`

659 

660Type / Values

661 

662`boolean`

663 

664Details

665 

666Enable ChatGPT Apps/connectors support (experimental).

667 

668Key

669 

670`features.codex_hooks`

671 

672Type / Values

673 

674`boolean`

675 

676Details

677 

678Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

679 

680Key

681 

682`features.enable_request_compression`

683 

684Type / Values

685 

686`boolean`

687 

688Details

689 

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

691 

692Key

693 

694`features.fast_mode`

695 

696Type / Values

697 

698`boolean`

699 

700Details

701 

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

703 

704Key

705 

706`features.multi_agent`

707 

708Type / Values

709 

710`boolean`

711 

712Details

713 

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

715 

716Key

717 

718`features.personality`

719 

720Type / Values

721 

722`boolean`

723 

724Details

725 

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

727 

728Key

729 

730`features.prevent_idle_sleep`

731 

732Type / Values

733 

734`boolean`

735 

736Details

737 

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

739 

740Key

741 

742`features.shell_snapshot`

743 

744Type / Values

745 

746`boolean`

747 

748Details

749 

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

751 

752Key

753 

754`features.shell_tool`

755 

756Type / Values

757 

758`boolean`

759 

760Details

761 

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

763 

764Key

765 

766`features.skill_mcp_dependency_install`

767 

768Type / Values

769 

770`boolean`

771 

772Details

773 

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

775 

776Key

777 

778`features.smart_approvals`

779 

780Type / Values

781 

782`boolean`

783 

784Details

785 

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

787 

788Key

789 

790`features.undo`

791 

792Type / Values

793 

794`boolean`

795 

796Details

797 

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

799 

800Key

801 

802`features.unified_exec`

803 

804Type / Values

805 

806`boolean`

807 

808Details

809 

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

811 

812Key

813 

814`features.web_search`

815 

816Type / Values

817 

818`boolean`

819 

820Details

821 

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

823 

824Key

825 

826`features.web_search_cached`

827 

828Type / Values

829 

830`boolean`

831 

832Details

833 

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

835 

836Key

837 

838`features.web_search_request`

839 

840Type / Values

841 

842`boolean`

843 

844Details

845 

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

847 

848Key

849 

850`feedback.enabled`

851 

852Type / Values

853 

854`boolean`

855 

856Details

857 

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

859 

860Key

861 

862`file_opener`

863 

864Type / Values

865 

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

867 

868Details

869 

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

871 

872Key

873 

874`forced_chatgpt_workspace_id`

875 

876Type / Values

877 

878`string (uuid)`

879 

880Details

881 

882Limit ChatGPT logins to a specific workspace identifier.

883 

884Key

885 

886`forced_login_method`

887 

888Type / Values

889 

890`chatgpt | api`

891 

892Details

893 

894Restrict Codex to a specific authentication method.

895 

896Key

897 

898`hide_agent_reasoning`

899 

900Type / Values

901 

902`boolean`

903 

904Details

905 

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

907 

908Key

909 

910`history.max_bytes`

911 

912Type / Values

913 

914`number`

915 

916Details

917 

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

919 

920Key

921 

922`history.persistence`

923 

924Type / Values

925 

926`save-all | none`

927 

928Details

929 

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

931 

932Key

933 

934`instructions`

935 

936Type / Values

937 

938`string`

939 

940Details

941 

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

943 

944Key

945 

946`log_dir`

947 

948Type / Values

949 

950`string (path)`

951 

952Details

953 

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

955 

956Key

957 

958`mcp_oauth_callback_port`

959 

960Type / Values

961 

962`integer`

963 

964Details

965 

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

967 

968Key

969 

970`mcp_oauth_callback_url`

971 

972Type / Values

973 

974`string`

975 

976Details

977 

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

979 

980Key

981 

982`mcp_oauth_credentials_store`

983 

984Type / Values

985 

986`auto | file | keyring`

987 

988Details

989 

990Preferred store for MCP OAuth credentials.

991 

992Key

993 

994`mcp_servers.<id>.args`

995 

996Type / Values

997 

998`array<string>`

999 

1000Details

1001 

1002Arguments passed to the MCP stdio server command.

1003 

1004Key

1005 

1006`mcp_servers.<id>.bearer_token_env_var`

1007 

1008Type / Values

1009 

1010`string`

1011 

1012Details

1013 

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

1015 

1016Key

1017 

1018`mcp_servers.<id>.command`

1019 

1020Type / Values

1021 

1022`string`

1023 

1024Details

1025 

1026Launcher command for an MCP stdio server.

1027 

1028Key

1029 

1030`mcp_servers.<id>.cwd`

1031 

1032Type / Values

1033 

1034`string`

1035 

1036Details

1037 

1038Working directory for the MCP stdio server process.

1039 

1040Key

1041 

1042`mcp_servers.<id>.disabled_tools`

1043 

1044Type / Values

1045 

1046`array<string>`

1047 

1048Details

1049 

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

1051 

1052Key

1053 

1054`mcp_servers.<id>.enabled`

1055 

1056Type / Values

1057 

1058`boolean`

1059 

1060Details

1061 

1062Disable an MCP server without removing its configuration.

1063 

1064Key

1065 

1066`mcp_servers.<id>.enabled_tools`

1067 

1068Type / Values

1069 

1070`array<string>`

1071 

1072Details

1073 

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

1075 

1076Key

1077 

1078`mcp_servers.<id>.env`

1079 

1080Type / Values

1081 

1082`map<string,string>`

1083 

1084Details

1085 

1086Environment variables forwarded to the MCP stdio server.

1087 

1088Key

1089 

1090`mcp_servers.<id>.env_http_headers`

1091 

1092Type / Values

1093 

1094`map<string,string>`

1095 

1096Details

1097 

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

1099 

1100Key

1101 

1102`mcp_servers.<id>.env_vars`

1103 

1104Type / Values

1105 

1106`array<string>`

1107 

1108Details

1109 

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

1111 

1112Key

1113 

1114`mcp_servers.<id>.http_headers`

1115 

1116Type / Values

1117 

1118`map<string,string>`

1119 

1120Details

1121 

1122Static HTTP headers included with each MCP HTTP request.

1123 

1124Key

1125 

1126`mcp_servers.<id>.oauth_resource`

1127 

1128Type / Values

1129 

1130`string`

1131 

1132Details

1133 

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

1135 

1136Key

1137 

1138`mcp_servers.<id>.required`

1139 

1140Type / Values

1141 

1142`boolean`

1143 

1144Details

1145 

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

1147 

1148Key

1149 

1150`mcp_servers.<id>.scopes`

1151 

1152Type / Values

1153 

1154`array<string>`

1155 

1156Details

1157 

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

1159 

1160Key

1161 

1162`mcp_servers.<id>.startup_timeout_ms`

1163 

1164Type / Values

1165 

1166`number`

1167 

1168Details

1169 

1170Alias for `startup_timeout_sec` in milliseconds.

1171 

1172Key

1173 

1174`mcp_servers.<id>.startup_timeout_sec`

1175 

1176Type / Values

1177 

1178`number`

1179 

1180Details

1181 

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

1183 

1184Key

1185 

1186`mcp_servers.<id>.tool_timeout_sec`

1187 

1188Type / Values

1189 

1190`number`

1191 

1192Details

1193 

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

1195 

1196Key

1197 

1198`mcp_servers.<id>.url`

1199 

1200Type / Values

1201 

1202`string`

1203 

1204Details

1205 

1206Endpoint for an MCP streamable HTTP server.

1207 

1208Key

1209 

1210`model`

1211 

1212Type / Values

1213 

1214`string`

1215 

1216Details

1217 

1218Model to use (e.g., `gpt-5.4`).

1219 

1220Key

1221 

1222`model_auto_compact_token_limit`

1223 

1224Type / Values

1225 

1226`number`

1227 

1228Details

1229 

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

1231 

1232Key

1233 

1234`model_catalog_json`

1235 

1236Type / Values

1237 

1238`string (path)`

1239 

1240Details

1241 

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

1243 

1244Key

1245 

1246`model_context_window`

1247 

1248Type / Values

1249 

1250`number`

1251 

1252Details

1253 

1254Context window tokens available to the active model.

1255 

1256Key

1257 

1258`model_instructions_file`

1259 

1260Type / Values

1261 

1262`string (path)`

1263 

1264Details

1265 

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

1267 

1268Key

1269 

1270`model_provider`

1271 

1272Type / Values

1273 

1274`string`

1275 

1276Details

1277 

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

1279 

1280Key

1281 

1282`model_providers.<id>`

1283 

1284Type / Values

1285 

1286`table`

1287 

1288Details

1289 

1290Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1291 

1292Key

1293 

1294`model_providers.<id>.auth`

1295 

1296Type / Values

1297 

1298`table`

1299 

1300Details

1301 

1302Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1303 

1304Key

1305 

1306`model_providers.<id>.auth.args`

1307 

1308Type / Values

1309 

1310`array<string>`

1311 

1312Details

1313 

1314Arguments passed to the token command.

1315 

1316Key

1317 

1318`model_providers.<id>.auth.command`

1319 

1320Type / Values

1321 

1322`string`

1323 

1324Details

1325 

1326Command to run when Codex needs a bearer token. The command must print the token to stdout.

1327 

1328Key

1329 

1330`model_providers.<id>.auth.cwd`

1331 

1332Type / Values

1333 

1334`string (path)`

1335 

1336Details

1337 

1338Working directory for the token command.

1339 

1340Key

1341 

1342`model_providers.<id>.auth.refresh_interval_ms`

1343 

1344Type / Values

1345 

1346`number`

1347 

1348Details

1349 

1350How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1351 

1352Key

1353 

1354`model_providers.<id>.auth.timeout_ms`

1355 

1356Type / Values

1357 

1358`number`

1359 

1360Details

1361 

1362Maximum token command runtime in milliseconds (default: 5000).

1363 

1364Key

1365 

1366`model_providers.<id>.base_url`

1367 

1368Type / Values

1369 

1370`string`

1371 

1372Details

1373 

1374API base URL for the model provider.

1375 

1376Key

1377 

1378`model_providers.<id>.env_http_headers`

1379 

1380Type / Values

1381 

1382`map<string,string>`

1383 

1384Details

1385 

1386HTTP headers populated from environment variables when present.

1387 

1388Key

1389 

1390`model_providers.<id>.env_key`

1391 

1392Type / Values

1393 

1394`string`

1395 

1396Details

1397 

1398Environment variable supplying the provider API key.

1399 

1400Key

1401 

1402`model_providers.<id>.env_key_instructions`

1403 

1404Type / Values

1405 

1406`string`

1407 

1408Details

1409 

1410Optional setup guidance for the provider API key.

1411 

1412Key

1413 

1414`model_providers.<id>.experimental_bearer_token`

1415 

1416Type / Values

1417 

1418`string`

1419 

1420Details

1421 

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

1423 

1424Key

1425 

1426`model_providers.<id>.http_headers`

1427 

1428Type / Values

1429 

1430`map<string,string>`

1431 

1432Details

1433 

1434Static HTTP headers added to provider requests.

1435 

1436Key

1437 

1438`model_providers.<id>.name`

1439 

1440Type / Values

1441 

1442`string`

1443 

1444Details

1445 

1446Display name for a custom model provider.

1447 

1448Key

1449 

1450`model_providers.<id>.query_params`

1451 

1452Type / Values

1453 

1454`map<string,string>`

1455 

1456Details

1457 

1458Extra query parameters appended to provider requests.

1459 

1460Key

1461 

1462`model_providers.<id>.request_max_retries`

1463 

1464Type / Values

1465 

1466`number`

1467 

1468Details

1469 

1470Retry count for HTTP requests to the provider (default: 4).

1471 

1472Key

1473 

1474`model_providers.<id>.requires_openai_auth`

1475 

1476Type / Values

1477 

1478`boolean`

1479 

1480Details

1481 

1482The provider uses OpenAI authentication (defaults to false).

1483 

1484Key

1485 

1486`model_providers.<id>.stream_idle_timeout_ms`

1487 

1488Type / Values

1489 

1490`number`

1491 

1492Details

1493 

1494Idle timeout for SSE streams in milliseconds (default: 300000).

1495 

1496Key

1497 

1498`model_providers.<id>.stream_max_retries`

1499 

1500Type / Values

1501 

1502`number`

1503 

1504Details

1505 

1506Retry count for SSE streaming interruptions (default: 5).

1507 

1508Key

1509 

1510`model_providers.<id>.supports_websockets`

1511 

1512Type / Values

1513 

1514`boolean`

1515 

1516Details

1517 

1518Whether that provider supports the Responses API WebSocket transport.

1519 

1520Key

1521 

1522`model_providers.<id>.wire_api`

1523 

1524Type / Values

1525 

1526`responses`

1527 

1528Details

1529 

1530Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1531 

1532Key

1533 

1534`model_reasoning_effort`

1535 

1536Type / Values

1537 

1538`minimal | low | medium | high | xhigh`

1539 

1540Details

1541 

1542Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).

1543 

1544Key

1545 

1546`model_reasoning_summary`

1547 

1548Type / Values

1549 

1550`auto | concise | detailed | none`

1551 

1552Details

1553 

1554Select reasoning summary detail or disable summaries entirely.

1555 

1556Key

1557 

1558`model_supports_reasoning_summaries`

1559 

1560Type / Values

1561 

1562`boolean`

1563 

1564Details

1565 

1566Force Codex to send or not send reasoning metadata.

1567 

1568Key

1569 

1570`model_verbosity`

1571 

1572Type / Values

1573 

1574`low | medium | high`

1575 

1576Details

1577 

1578Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1579 

1580Key

1581 

1582`notice.hide_full_access_warning`

1583 

1584Type / Values

1585 

1586`boolean`

1587 

1588Details

1589 

1590Track acknowledgement of the full access warning prompt.

1591 

1592Key

1593 

1594`notice.hide_gpt-5.1-codex-max_migration_prompt`

1595 

1596Type / Values

1597 

1598`boolean`

1599 

1600Details

1601 

1602Track acknowledgement of the gpt-5.1-codex-max migration prompt.

1603 

1604Key

1605 

1606`notice.hide_gpt5_1_migration_prompt`

1607 

1608Type / Values

1609 

1610`boolean`

1611 

1612Details

1613 

1614Track acknowledgement of the GPT-5.1 migration prompt.

1615 

1616Key

1617 

1618`notice.hide_rate_limit_model_nudge`

1619 

1620Type / Values

1621 

1622`boolean`

1623 

1624Details

1625 

1626Track opt-out of the rate limit model switch reminder.

1627 

1628Key

1629 

1630`notice.hide_world_writable_warning`

1631 

1632Type / Values

1633 

1634`boolean`

1635 

1636Details

1637 

1638Track acknowledgement of the Windows world-writable directories warning.

1639 

1640Key

1641 

1642`notice.model_migrations`

1643 

1644Type / Values

1645 

1646`map<string,string>`

1647 

1648Details

1649 

1650Track acknowledged model migrations as old->new mappings.

1651 

1652Key

1653 

1654`notify`

1655 

1656Type / Values

1657 

1658`array<string>`

1659 

1660Details

1661 

1662Command invoked for notifications; receives a JSON payload from Codex.

1663 

1664Key

1665 

1666`openai_base_url`

1667 

1668Type / Values

1669 

1670`string`

1671 

1672Details

1673 

1674Base URL override for the built-in `openai` model provider.

1675 

1676Key

1677 

1678`oss_provider`

1679 

1680Type / Values

1681 

1682`lmstudio | ollama`

1683 

1684Details

1685 

1686Default local provider used when running with `--oss` (defaults to prompting if unset).

1687 

1688Key

1689 

1690`otel.environment`

1691 

1692Type / Values

1693 

1694`string`

1695 

1696Details

1697 

1698Environment tag applied to emitted OpenTelemetry events (default: `dev`).

1699 

1700Key

1701 

1702`otel.exporter`

1703 

1704Type / Values

1705 

1706`none | otlp-http | otlp-grpc`

1707 

1708Details

1709 

1710Select the OpenTelemetry exporter and provide any endpoint metadata.

1711 

1712Key

1713 

1714`otel.exporter.<id>.endpoint`

1715 

1716Type / Values

1717 

1718`string`

1719 

1720Details

1721 

1722Exporter endpoint for OTEL logs.

1723 

1724Key

1725 

1726`otel.exporter.<id>.headers`

1727 

1728Type / Values

1729 

1730`map<string,string>`

1731 

1732Details

1733 

1734Static headers included with OTEL exporter requests.

1735 

1736Key

1737 

1738`otel.exporter.<id>.protocol`

1739 

1740Type / Values

1741 

1742`binary | json`

1743 

1744Details

1745 

1746Protocol used by the OTLP/HTTP exporter.

1747 

1748Key

1749 

1750`otel.exporter.<id>.tls.ca-certificate`

1751 

1752Type / Values

1753 

1754`string`

1755 

1756Details

1757 

1758CA certificate path for OTEL exporter TLS.

1759 

1760Key

1761 

1762`otel.exporter.<id>.tls.client-certificate`

1763 

1764Type / Values

1765 

1766`string`

1767 

1768Details

1769 

1770Client certificate path for OTEL exporter TLS.

1771 

1772Key

1773 

1774`otel.exporter.<id>.tls.client-private-key`

1775 

1776Type / Values

1777 

1778`string`

1779 

1780Details

1781 

1782Client private key path for OTEL exporter TLS.

1783 

1784Key

1785 

1786`otel.log_user_prompt`

1787 

1788Type / Values

1789 

1790`boolean`

1791 

1792Details

1793 

1794Opt in to exporting raw user prompts with OpenTelemetry logs.

1795 

1796Key

1797 

1798`otel.metrics_exporter`

1799 

1800Type / Values

1801 

1802`none | statsig | otlp-http | otlp-grpc`

1803 

1804Details

1805 

1806Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1807 

1808Key

1809 

1810`otel.trace_exporter`

1811 

1812Type / Values

1813 

1814`none | otlp-http | otlp-grpc`

1815 

1816Details

1817 

1818Select the OpenTelemetry trace exporter and provide any endpoint metadata.

1819 

1820Key

1821 

1822`otel.trace_exporter.<id>.endpoint`

1823 

1824Type / Values

1825 

1826`string`

1827 

1828Details

1829 

1830Trace exporter endpoint for OTEL logs.

1831 

1832Key

1833 

1834`otel.trace_exporter.<id>.headers`

1835 

1836Type / Values

1837 

1838`map<string,string>`

1839 

1840Details

1841 

1842Static headers included with OTEL trace exporter requests.

1843 

1844Key

1845 

1846`otel.trace_exporter.<id>.protocol`

1847 

1848Type / Values

1849 

1850`binary | json`

1851 

1852Details

1853 

1854Protocol used by the OTLP/HTTP trace exporter.

1855 

1856Key

1857 

1858`otel.trace_exporter.<id>.tls.ca-certificate`

1859 

1860Type / Values

1861 

1862`string`

1863 

1864Details

1865 

1866CA certificate path for OTEL trace exporter TLS.

1867 

1868Key

1869 

1870`otel.trace_exporter.<id>.tls.client-certificate`

1871 

1872Type / Values

1873 

1874`string`

1875 

1876Details

1877 

1878Client certificate path for OTEL trace exporter TLS.

1879 

1880Key

1881 

1882`otel.trace_exporter.<id>.tls.client-private-key`

1883 

1884Type / Values

1885 

1886`string`

1887 

1888Details

1889 

1890Client private key path for OTEL trace exporter TLS.

1891 

1892Key

1893 

1894`permissions.<name>.filesystem`

1895 

1896Type / Values

1897 

1898`table`

1899 

1900Details

1901 

1902Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1903 

1904Key

1905 

1906`permissions.<name>.filesystem.":project_roots".<subpath>`

1907 

1908Type / Values

1909 

1910`"read" | "write" | "none"`

1911 

1912Details

1913 

1914Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1915 

1916Key

1917 

1918`permissions.<name>.filesystem.<path>`

1919 

1920Type / Values

1921 

1922`"read" | "write" | "none" | table`

1923 

1924Details

1925 

1926Grant direct access for a path or special token, or scope nested entries under that root.

1927 

1928Key

1929 

1930`permissions.<name>.network.allow_local_binding`

1931 

1932Type / Values

1933 

1934`boolean`

1935 

1936Details

1937 

1938Permit local bind/listen operations through the managed proxy.

1939 

1940Key

1941 

1942`permissions.<name>.network.allow_upstream_proxy`

1943 

1944Type / Values

1945 

1946`boolean`

1947 

1948Details

1949 

1950Allow the managed proxy to chain to another upstream proxy.

1951 

1952Key

1953 

1954`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1955 

1956Type / Values

1957 

1958`boolean`

1959 

1960Details

1961 

1962Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

1963 

1964Key

1965 

1966`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

1967 

1968Type / Values

1969 

1970`boolean`

1971 

1972Details

1973 

1974Permit non-loopback bind addresses for the managed proxy listener.

1975 

1976Key

1977 

1978`permissions.<name>.network.domains`

1979