Configuration Reference

Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Config.

config.toml

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

Project-scoped config can't override machine-local provider, auth, host-owned app request metadata, notification, configuration profile selection, or telemetry routing keys. Codex ignores openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel when they appear in a project-local .codex/config.toml; put provider, notification, and telemetry keys in user-level config instead. Config profile files live next to config.toml as $CODEX_HOME/profile-name.config.toml; select one with --profile profile-name.

For sandbox and approval keys (approval_policy, sandbox_mode, and sandbox_workspace_write.*), pair this reference with Sandbox and approvals, Protected paths in writable roots, and Network access. For beta permission profiles, see Permissions.

<ConfigTable options={[ { key: "model", type: "string", description: "Model to use (e.g., gpt-5.5).", }, { key: "review_model", type: "string", description: "Optional model override used by /review (defaults to the current session model).", }, { key: "model_provider", type: "string", description: "Provider id from model_providers (default: openai).", }, { key: "openai_base_url", type: "string", description: "Base URL override for the built-in openai model provider.", }, { key: "model_context_window", type: "number", description: "Context window tokens available to the active model.", }, { key: "model_auto_compact_token_limit", type: "number", description: "Token threshold that triggers automatic history compaction (unset uses model defaults).", }, { key: "model_auto_compact_token_limit_scope", type: "total | body_after_prefix", description: "Controls whether the auto-compaction threshold counts the full active context (total, the default) or only growth after the carried compaction-window prefix (body_after_prefix).", }, { key: "model_catalog_json", type: "string (path)", description: "Optional path to a JSON model catalog loaded on startup. A selected $CODEX_HOME/profile-name.config.toml profile file can override this per profile.", }, { key: "oss_provider", type: "lmstudio | ollama", description: "Default local provider used when running with --oss (defaults to prompting if unset).", }, { key: "approval_policy", type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }", description: "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.", }, { key: "approval_policy.granular.sandbox_approval", type: "boolean", description: "When true, sandbox escalation approval prompts are allowed to surface.", }, { key: "approval_policy.granular.rules", type: "boolean", description: "When true, approvals triggered by execpolicy prompt rules are allowed to surface.", }, { key: "approval_policy.granular.mcp_elicitations", type: "boolean", description: "When true, MCP elicitation prompts are allowed to surface instead of being auto-rejected.", }, { key: "approval_policy.granular.request_permissions", type: "boolean", description: "When true, prompts from the request_permissions tool are allowed to surface.", }, { key: "approval_policy.granular.skill_approval", type: "boolean", description: "When true, skill-script approval prompts are allowed to surface.", }, { key: "approvals_reviewer", type: "user | auto_review", description: "Who reviews eligible approval prompts under on-request or granular approval policies. Defaults to user; auto_review uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.", }, { key: "auto_review.policy", type: "string", description: "Local Markdown policy instructions for automatic review. Managed guardian_policy_config takes precedence. Blank values are ignored.", }, { key: "allow_login_shell", type: "boolean", description: "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.", }, { key: "sandbox_mode", type: "read-only | workspace-write | danger-full-access", description: "Sandbox policy for filesystem and network access during command execution.", }, { key: "sandbox_workspace_write.writable_roots", type: "array", description: 'Additional writable roots when sandbox_mode = "workspace-write".', }, { key: "sandbox_workspace_write.network_access", type: "boolean", description: "Allow outbound network access inside the workspace-write sandbox.", }, { key: "sandbox_workspace_write.exclude_tmpdir_env_var", type: "boolean", description: "Exclude $TMPDIR from writable roots in workspace-write mode.", }, { key: "sandbox_workspace_write.exclude_slash_tmp", type: "boolean", description: "Exclude /tmp from writable roots in workspace-write mode.", }, { key: "windows.sandbox", type: "unelevated | elevated", description: "Windows-only native sandbox mode when running Codex natively on Windows.", }, { key: "windows.sandbox_private_desktop", type: "boolean", description: "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.", }, { key: "computer_use.windows.always_allowed_app_ids", type: "array", description: "Windows app identifiers that Computer Use can open without prompting. Apps not in the list require approval; remove saved entries from the ChatGPT desktop app's Computer Use settings.", }, { key: "notify", type: "array", description: "Command invoked for notifications; receives a JSON payload from Codex.", }, { key: "check_for_update_on_startup", type: "boolean", description: "Check for Codex updates on startup (set to false only when updates are centrally managed).", }, { key: "feedback.enabled", type: "boolean", description: "Enable feedback submission via /feedback across local clients (default: true).", }, { key: "analytics.enabled", type: "boolean", description: "Enable or disable analytics for this machine/profile. When unset, the client default applies.", }, { key: "instructions", type: "string", description: "Reserved for future use; prefer model_instructions_file or AGENTS.md.", }, { key: "developer_instructions", type: "string", description: "Additional developer instructions injected into the session (optional).", }, { key: "log_dir", type: "string (path)", description: "Directory where Codex writes log files; defaults to $CODEX_HOME/log. Setting this explicitly also enables the opt-in plaintext TUI log, codex-tui.log, in that directory.", }, { key: "sqlite_home", type: "string (path)", description: "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.", }, { key: "compact_prompt", type: "string", description: "Inline override for the history compaction prompt.", }, { key: "model_instructions_file", type: "string (path)", description: "Replacement for built-in instructions instead of AGENTS.md.", }, { key: "personality", type: "none | friendly | pragmatic", description: "Default communication style for models that advertise supportsPersonality; can be overridden per thread/turn or via /personality.", }, { key: "service_tier", type: "string", description: "Preferred service tier for new turns. Built-in values include flex and fast; legacy fast config maps to the request value priority, and catalog-provided tier IDs can also be stored.", }, { key: "experimental_compact_prompt_file", type: "string (path)", description: "Load the compaction prompt override from a file (experimental).", }, { key: "skills.config", type: "array