Codex
OpenAI Codex configuration file
| Type | object |
|---|---|
| File match |
**/.codex/config.toml
|
| Schema URL | https://catalog.lintel.tools/schemas/schemastore/codex/latest.json |
| Source | https://developers.openai.com/codex/config-schema.json |
Validate with Lintel
npx @lintel/lintel checkBase config deserialized from ~/.codex/config.toml.
Properties
Whether the model may request a login shell for shell-based tools. Default to true
If true, the model may request a login shell (login = true), and omitting login defaults to using a login shell. If false, the model can never use a login shell: login = true requests are rejected, and omitting login defaults to a non-login shell.
When false, disables analytics across Codex product surfaces in this machine. Defaults to true.
Default approval policy for executing commands.
Configures who approval requests are routed to for review once they have been escalated. This does not disable separate safety checks such as ARC.
Machine-local realtime audio device preferences used by realtime voice.
Maximum poll window for background terminal output (write_stdin), in milliseconds. Default: 300000 (5 minutes).
Base URL for requests to ChatGPT (as opposed to the OpenAI API).
When true, checks for Codex updates on startup and surfaces update prompts. Set to false only if your Codex updates are centrally managed. Defaults to true.
Preferred backend for storing CLI auth credentials. file (default): Use a file in the Codex home directory. keyring: Use an OS-specific keyring service. auto: Use the keyring if available, otherwise use a file.
Optional commit attribution text for commit message co-author trailers.
Set to an empty string to disable automatic commit attribution.
Compact prompt used for history compaction.
Default permissions profile to apply. Names starting with : refer to built-in profiles; other names are resolved from the [permissions] table.
Developer instructions inserted as a developer role message.
When true, disables burst-paste detection for typed input entirely. All characters are inserted as they are received, and no buffering or placeholder replacement will occur for fast keypress bursts.
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
Experimental / do not use. Replaces the built-in realtime start instructions inserted into developer messages when realtime becomes active.
Experimental / do not use. Overrides only the realtime conversation websocket transport instructions (the Op::RealtimeConversation /ws session.update instructions) without changing normal prompts.
Experimental / do not use. Overrides only the realtime conversation websocket transport base URL (the Op::RealtimeConversation /v1/realtime connection) without changing normal provider HTTP requests.
Experimental / do not use. Selects the realtime websocket model/snapshot used for the Op::RealtimeConversation connection.
Experimental / do not use. Replaces the synthesized realtime startup context appended to websocket session instructions. An empty string disables startup context injection entirely.
Experimental / do not use. When set, app-server fetches thread-scoped config from a remote service at this endpoint.
Experimental / do not use. Selects the thread store implementation.
Experimental / do not use. When set, app-server uses a remote thread store at this endpoint instead of the local filesystem/SQLite store.
Centralized feature flags (new). Prefer this over individual toggles.
78 nested properties
When false, disables feedback collection across Codex product surfaces. Defaults to true.
Optional URI-based file opener. If set, citations to files in the model output will be hyperlinked using the specified URI scheme.
When set, restricts ChatGPT login to a specific workspace identifier.
Compatibility-only settings retained so legacy ghost_snapshot config still loads.
When set to true, AgentReasoning events will be hidden from the UI/output. Defaults to false.
Whether to inject the <apps_instructions> developer block.
Whether to inject the <environment_context> user block.
Whether to inject the <permissions instructions> developer block.
System instructions.
Directory where Codex writes log files, for example codex-tui.log. Defaults to $CODEX_HOME/log.
Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex will bind to an ephemeral port chosen by the OS.
Optional redirect URI to use during MCP OAuth login. When set, this URI is used in the OAuth authorization request instead of the local listener address. The local callback listener still binds to 127.0.0.1 (using mcp_oauth_callback_port when provided).
Preferred backend for storing MCP OAuth credentials. keyring: Use an OS-specific keyring service. https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs#L2 file: Use a file in the Codex home directory. auto (default): Use the OS-specific keyring service if available, otherwise use a file.
Definition for MCP servers that Codex can reach out to for tool calls.
{}Optional override of model selection.
Token usage threshold triggering auto-compaction of conversation history.
Optional path to a JSON model catalog (applied on startup only). Per-thread config overrides are accepted but do not reapply this (no-ops).
Size of the context window for the model, in tokens.
Optional path to a file containing model instructions that will override the built-in instructions for the selected model. Users are STRONGLY DISCOURAGED from using this field, as deviating from the instructions sanctioned by Codex will likely degrade model performance.
Provider to use from the model_providers map.
User-defined provider entries that extend the built-in list. Built-in IDs cannot be overridden.
{}A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
Override to force-enable reasoning summaries for the configured model.
Optional verbosity control for GPT-5 models (Responses API text.verbosity).
Collection of in-product notices (different from notifications) See [crate::types::Notice] for more details
Optional external command to spawn for end-user notifications.
Base URL override for the built-in openai model provider.
Preferred OSS provider for local models, e.g. "lmstudio" or "ollama".
Profile to use from the profiles map.
Named profiles to facilitate switching between different configurations.
{}Ordered list of fallback filenames to look for when AGENTS.md is missing.
Maximum number of bytes to include from an AGENTS.md project doc file.
Markers used to detect the project root when searching parent directories for .codex folders. Defaults to [".git"] when unset.
Experimental / do not use. Realtime websocket session selection. version controls v1/v2 and type controls conversational/transcription.
Review model override used by the /review feature.
Sandbox configuration to apply if sandbox is WorkspaceWrite.
Optional explicit service tier preference for new turns (fast or flex).
{
"exclude": null,
"experimental_use_profile": null,
"ignore_default_excludes": null,
"include_only": null,
"inherit": null,
"set": null
}When set to true, AgentReasoningRawContentEvent events will be shown in the UI/output. Defaults to false.
Directory where Codex stores the SQLite state DB. Defaults to $CODEX_SQLITE_HOME when set. Otherwise uses $CODEX_HOME.
Suppress warnings about unstable (under development) features.
Token budget applied when storing tool/function outputs in the context manager.
Additional discoverable tools that can be suggested for installation.
Tracks whether the Windows onboarding screen has been acknowledged.
Optional absolute path to patched zsh used by zsh-exec-bridge-backed shell execution.
Definitions
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
Path to a role-specific config layer. Relative paths are resolved relative to the config.toml that defines them.
Human-facing role documentation used in spawn tool guidance. Required unless supplied by the referenced agent role file.
Candidate nicknames for agents spawned with this role.
Whether to record a model-visible message when an agent turn is interrupted. Defaults to true.
Default maximum runtime in seconds for agent job workers.
Maximum nesting depth allowed for spawned agent threads. Root sessions start at depth 0.
Maximum number of agent threads that can be open concurrently. When unset, no limit is enforced.
Controls whether the TUI uses the terminal's alternate screen buffer.
Background: The alternate screen buffer provides a cleaner fullscreen experience without polluting the terminal's scrollback history. However, it conflicts with terminal multiplexers like Zellij that strictly follow the xterm specification, which defines that alternate screen buffers should not have scrollback.
Zellij's behavior: Zellij intentionally disables scrollback in alternate screen mode (see https://github.com/zellij-org/zellij/pull/1032) to comply with the xterm spec. This is by design and not configurable in Zellij—there is no option to enable scrollback in alternate screen mode.
Solution: This setting provides a pragmatic workaround: - auto (default): Automatically detect the terminal multiplexer. If running in Zellij, disable alternate screen to preserve scrollback. Enable it everywhere else. - always: Always use alternate screen mode (original behavior before this fix). - never: Never use alternate screen mode. Runs in inline mode, preserving scrollback in all multiplexers.
The CLI flag --no-alt-screen can override this setting at runtime.
Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.
When false, disables analytics across Codex product surfaces in this profile.
Config values for a single app/connector.
Approval mode for tools in this app unless a tool override exists.
Whether tools are enabled by default for this app.
Whether tools with destructive_hint = true are allowed for this app.
When false, Codex does not surface this app.
Whether tools with open_world_hint = true are allowed for this app.
Per-tool settings for a single app tool.
Whether this tool is enabled. Some(true) explicitly allows this tool.
Tool settings for a single app.
Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to user. auto_review uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value guardian_subagent is accepted for compatibility.
App/connector settings loaded from config.toml.
Default settings that apply to all apps.
Whether tools with destructive_hint = true are allowed by default.
When false, apps are disabled unless overridden by per-app settings.
Whether tools with open_world_hint = true are allowed by default.
Determines the conditions under which the user is consulted to approve running the command proposed by Codex.
Determine where Codex should store CLI auth credentials.
Additional policy instructions inserted into the guardian prompt.
Collection of common configuration options that a user can define as a unit in config.toml.
Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.
1 nested properties
When false, disables analytics across Codex product surfaces in this profile.
Determines the conditions under which the user is consulted to approve running the command proposed by Codex.
Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to user. auto_review uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value guardian_subagent is accepted for compatibility.
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
Optional feature toggles scoped to this profile.
78 nested properties
Optional path to a JSON model catalog (applied on startup only).
Optional path to a file containing model instructions.
The key in the model_providers map identifying the [ModelProviderInfo] to use.
A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.
Optional explicit service tier preference for new turns (fast or flex).
2 nested properties
Enable the view_image tool that lets the agent attach local images.
Optional absolute path to patched zsh used by zsh-exec-bridge-backed shell execution.
Settings for notices we display to users via the tui and app-server clients (primarily the Codex IDE extension). NOTE: these are different from notifications - notices are warnings, NUX screens, acknowledgements, etc.
Tracks whether home-level external config migration prompts are hidden.
Tracks the last time the home-level external config migration prompt was shown.
Tracks the last time a project-level external config migration prompt was shown.
{}Tracks which project paths have opted out of external config migration prompts.
{}When false, disables the feedback flow across Codex product surfaces.
Access mode for a filesystem entry.
When two equally specific entries target the same path, we compare these by conflict precedence rather than by capability breadth: none beats write, and write beats read.
Optional maximum depth for expanding unreadable glob patterns on platforms that snapshot glob matches before sandbox startup.
Legacy no-op setting retained for compatibility.
Legacy no-op setting retained for compatibility.
Legacy no-op setting retained for compatibility.
Whether to allow MCP elicitation prompts.
Whether to allow prompts triggered by execpolicy prompt rules.
Whether to allow shell command approval requests, including inline with_additional_permissions and require_escalated requests.
Whether to allow prompts triggered by the request_permissions tool.
Whether to allow approval prompts triggered by skill script execution.
Settings that govern if and what will be written to ~/.codex/history.jsonl.
If true, history entries will not be written to disk.
If set, the maximum size of the history file in bytes. The oldest entries are dropped once the file exceeds this limit.
[][][][][][]One action binding value in config.
This accepts either:
- A single key spec string (
"ctrl-a"). 2. A list of key spec strings (["ctrl-a", "alt-a"]).
An empty list explicitly unbinds the action in that scope. Because an explicit empty list is still a configured value, runtime resolution must not fall through to global or built-in defaults for that action.
Git revision Codex last successfully activated for this marketplace.
Last time Codex successfully added or refreshed this marketplace.
Git ref to check out when source_type is git.
Source location used when the marketplace was added.
Sparse checkout paths used when source_type is git.
[]Per-tool approval settings for a single MCP server tool.
Memories settings loaded from config.toml.
Model used for memory consolidation.
When true, external context sources mark the thread memory_mode as "polluted".
Model used for thread summarisation.
When false, newly created threads are stored with memory_mode = "disabled" in the state DB.
Maximum number of recent raw memories retained for global consolidation.
Maximum age of the threads used for memories.
Maximum number of rollout candidates processed per pass.
Maximum number of days since a memory was last used before it becomes ineligible for phase 2 selection.
Minimum remaining percentage required in Codex rate-limit windows before memory startup runs.
Minimum idle time between last thread activity and memory creation (hours). > 12h recommended.
When false, skip injecting memory usage instructions into developer prompts.
Configuration for obtaining a provider bearer token from a command.
Command to execute. Bare names are resolved via PATH; paths are resolved against cwd.
Command arguments.
[]Maximum age for the cached token before rerunning the command. Set to 0 to disable proactive refresh and only rerun after a 401 retry path.
Maximum time to wait for the token command to exit successfully.
AWS SigV4 auth configuration for a model provider.
AWS profile name to use. When unset, the AWS SDK default chain decides.
AWS region to use for provider-specific endpoints.
Serializable representation of a provider definition.
Base URL for the provider's OpenAI-compatible API.
Optional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and environment variable whose value should be used. If the environment variable is not set, or the value is empty, the header will not be included in the request.
Environment variable that stores the user's API key for this provider.
Optional instructions to help the user get a valid value for the variable and set it.
Value to use with Authorization: Bearer <token> header. Use of this config is discouraged in favor of env_key for security reasons, but this may be necessary when using this programmatically.
Additional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and value.
Friendly display name.
Optional query parameters to append to the base URL.
Maximum number of times to retry a failed HTTP request to this provider.
Does this provider require an OpenAI API Key or ChatGPT login token? If true, user is presented with login screen on first run, and login preference and token/key are stored in auth.json. If false (which is the default), login screen is skipped, and API key (if needed) comes from the "env_key" environment variable.
Idle timeout (in milliseconds) to wait for activity on a streaming response before treating the connection as lost.
Number of times to retry reconnecting a dropped streaming response before failing.
Whether this provider supports the Responses API WebSocket transport.
Maximum time (in milliseconds) to wait for a websocket connection attempt before treating it as failed.
Tracks scopes where external config migration prompts should be suppressed.
{
"home": null,
"home_last_prompted_at": null,
"project_last_prompted_at": {},
"projects": {}
}Tracks whether the user opted out of Codex-managed fast defaults.
Tracks whether the user has acknowledged the full access warning prompt.
Tracks whether the user has seen the gpt-5.1-codex-max migration prompt
Tracks whether the user has seen the model migration prompt
Tracks whether the user opted out of the rate limit model switch reminder.
Tracks whether the user has acknowledged the Windows world-writable directories warning.
Tracks acknowledged model migrations as old->new model slug mappings.
{}Determine where Codex should store and read MCP credentials.
OTEL settings loaded from config.toml. Fields are optional so we can apply defaults.
Mark traces with environment (dev, staging, prod, test). Defaults to dev.
Log user prompt in traces
Which OTEL exporter to use.
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).
IMPORTANT: When deserializing an AbsolutePathBuf, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.
Per-MCP-server policy overlays for MCP servers contributed by this plugin.
Policy settings for a plugin-provided MCP server.
This intentionally excludes transport settings: plugin manifests own how the MCP server is launched, while user config owns enablement and tool policy.
Approval mode for tools in this server unless a tool override exists.
Explicit deny-list of tools. These tools are removed after applying enabled_tools.
When false, Codex skips initializing this plugin MCP server.
Explicit allow-list of tools exposed from this server.
Per-tool approval settings keyed by tool name.
Represents the trust level for a project directory. This determines the approval policy and sandbox mode applied.
Raw MCP config shape used for deserialization and supported-field JSON Schema generation.
Fields that are accepted only to produce targeted validation errors should be skipped in the generated schema.
Keep TryFrom<RawMcpServerConfig> for McpServerConfig exhaustively destructuring this struct so new TOML fields cannot be added here without updating the validation/mapping logic that produces [McpServerConfig].
Legacy display-name field accepted for backward compatibility.
A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
[]Policy for building the env when spawning a process via either the shell or local_shell tool.
List of regular expressions.
List of regular expressions.
Name-based selector.
1 nested properties
Whether turns receive the automatic skills instructions block.
[][]Enable the view_image tool that lets the agent attach local images.
Represents the trust level for a project directory. This determines the approval policy and sandbox mode applied.
Collection of settings that are specific to the TUI.
Controls whether the TUI uses the terminal's alternate screen buffer.
auto(default): Disable alternate screen in Zellij, enable elsewhere. -always: Always use alternate screen (original behavior). -never: Never use alternate screen (inline mode only, preserves scrollback).
Using alternate screen provides a cleaner fullscreen experience but prevents scrollback in terminal multiplexers like Zellij that follow the xterm spec.
Enable animations (welcome screen, shimmer effects, spinners). Defaults to true.
Keybinding overrides for the TUI.
This supports rebinding selected actions globally and by context. Context bindings take precedence over global bindings.
{
"approval": {
"approve": null,
"approve_for_prefix": null,
"approve_for_session": null,
"cancel": null,
"decline": null,
"deny": null,
"open_fullscreen": null,
"open_thread": null
},
"chat": {
"decrease_reasoning_effort": null,
"edit_queued_message": null,
"increase_reasoning_effort": null
},
"composer": {
"history_search_next": null,
"history_search_previous": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
},
"editor": {
"delete_backward": null,
"delete_backward_word": null,
"delete_forward": null,
"delete_forward_word": null,
"insert_newline": null,
"kill_line_end": null,
"kill_line_start": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_left": null,
"move_word_right": null,
"yank": null
},
"global": {
"clear_terminal": null,
"copy": null,
"open_external_editor": null,
"open_transcript": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
},
"list": {
"accept": null,
"cancel": null,
"move_down": null,
"move_up": null
},
"pager": {
"close": null,
"close_transcript": null,
"half_page_down": null,
"half_page_up": null,
"jump_bottom": null,
"jump_top": null,
"page_down": null,
"page_up": null,
"scroll_down": null,
"scroll_up": null
}
}Startup tooltip availability NUX state persisted by the TUI.
{}Controls whether TUI notifications are delivered only when the terminal is unfocused or regardless of focus. Defaults to unfocused.
Notification method to use for terminal notifications. Defaults to auto.
Enable desktop notifications from the TUI. Defaults to true.
Show startup tooltips in the TUI welcome screen. Defaults to true.
Ordered list of status line item identifiers.
When set, the TUI renders the selected items as the status line. When unset, the TUI defaults to: model-with-reasoning and current-dir.
Trim terminal resize-reflow replay to the most recent rendered terminal rows when the transcript exceeds this cap. Omit to use Codex's terminal-specific default. Set to 0 to keep all rendered rows.
Ordered list of terminal title item identifiers.
When set, the TUI renders the selected items into the terminal window/tab title. When unset, the TUI defaults to: activity and project. The activity item spins while working and shows an action-required message when blocked on the user.
Syntax highlighting theme name (kebab-case).
When set, overrides automatic light/dark theme detection. Use /theme in the TUI or see $CODEX_HOME/themes for custom themes.
Approval overlay keybindings.
Approve with exec-policy prefix when that option exists.
Open the thread that requested approval when shown from another thread.
Chat context keybindings.
Composer context keybindings. These override corresponding global actions.
Move to the next match in reverse history search.
Open reverse history search or move to the previous match.
Editor context keybindings for text editing inside text areas.
Global keybindings. These are used when a context does not define an override.
Open the external editor for the current draft.
Raw keymap configuration from [tui.keymap].
Each context contains action-level overrides. Missing actions inherit from built-in defaults, and selected chat/composer actions can fall back through global during runtime resolution.
This type is intentionally a persistence shape, not the structure used by input handlers. Runtime consumers should resolve it into RuntimeKeymap first so precedence, empty-list unbinding, and duplicate-key validation are applied consistently.
{
"approve": null,
"approve_for_prefix": null,
"approve_for_session": null,
"cancel": null,
"decline": null,
"deny": null,
"open_fullscreen": null,
"open_thread": null
}{
"decrease_reasoning_effort": null,
"edit_queued_message": null,
"increase_reasoning_effort": null
}{
"history_search_next": null,
"history_search_previous": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
}{
"delete_backward": null,
"delete_backward_word": null,
"delete_forward": null,
"delete_forward_word": null,
"insert_newline": null,
"kill_line_end": null,
"kill_line_start": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_left": null,
"move_word_right": null,
"yank": null
}{
"clear_terminal": null,
"copy": null,
"open_external_editor": null,
"open_transcript": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
}{
"close": null,
"close_transcript": null,
"half_page_down": null,
"half_page_up": null,
"jump_bottom": null,
"jump_top": null,
"page_down": null,
"page_up": null,
"scroll_down": null,
"scroll_up": null
}List selection context keybindings for popup-style selectable lists.
Pager context keybindings for transcript and static overlays.
Close the transcript overlay via its dedicated toggle key.
Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.
Defaults to true. Set to false to launch the final sandboxed child process on Winsta0\\Default instead of a private desktop.
Wire protocol that the provider speaks.