YouTip

The advanced configuration layer of Codex CLI allows us to finely control model providers, sandbox permissions, hooks, telemetry data, and terminal behavior. If this is your first time using Codex, first read (https://example.com/codex/codex-config-file.html) to build an overall understanding; this article assumes you already know the existence and function of ~/.codex/config.toml. * * * ## Configuration Hierarchy Overview Codex's configuration is composed of multiple layers stacked together. Understanding this is the cornerstone for all advanced usage going forward. From bottom to top: System Level → User Level (~/.codex/config.toml) → Profile Level → Project Level (.codex/config.toml) → CLI Command Line Arguments. Upper layers override lower layers with the same name. The project configuration closest to the current working directory has the highest priority. > The most reliable way to determine the currently active configuration is to use codex --help with logs, or explicitly use codex exec "show my current config" to have the model help interpret it. * * * ## Profiles Named Configuration Layer Profile is Codex's recommended "scenario-based switching" solution: save a group of configurations as a TOML file, and load it on demand via --profile. Profile files are located at ~/.codex/.config.toml, where can only contain letters, numbers, hyphens, and underscores. ### Creating and Using a Profile Suppose you frequently perform deep code reviews and want to use stronger reasoning capabilities: ## Example # File path: ~/.codex/deep-review.config.toml model = "gpt-5.5"# Use a model with stronger reasoning capabilities model_reasoning_effort = "xhigh"# Max reasoning effort approval_policy = "on-request"# Prompt for approval on every tool call model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"# Optional: custom model catalog Start Codex using Profile: ## Example # Start interactive TUI codex --profile deep-review # Or use in non-interactive exec mode codex exec--profile deep-review "review this change" ### Profile Merge Semantics Profile files are not complete configurations; they are an incremental overlay on top of the user-level ~/.codex/config.toml. This means Profile only needs to write fields that are "different from the default configuration", and other fields will automatically inherit from user-level settings. If both user-level and Profile set model_catalog_json, the Profile's value takes precedence. > Starting from Codex 0.134.0, --profile no longer reads [profiles.] tables from config.toml, and no longer supports the top-level profile = "name" selector. All historical Profile settings must be migrated to independent ~/.codex/.config.toml files. ### Migrating from Old Configuration to Profile If your previous config.toml looked like this: ## Example # OldSyntax (deprecated) profile = "deep-review" [profiles.deep-review] model = "gpt-5.5" model_reasoning_effort = "xhigh" Needs to be split into two files: # File path: ~/.codex/config.toml (keep non-profile parts)# Note: deleted profile = "deep-review" selector# File path: ~/.codex/deep-review.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" After migration, the original codex --profile deep-review command line usage remains unchanged. * * * ## One-time Command Line Overrides Sometimes you only want to temporarily change one or two fields to run a task once without polluting the configuration file. In this case, you can use CLI overrides: ### Prefer Using Dedicated Flags If the official provides dedicated parameters (such as --model), prefer using the dedicated flag for the best readability: ## Example # Use dedicated flag to switch models codex --model gpt-5.4 ### Use --config to Override Any Key For fields without dedicated flags, use -c or --config to override. The value is in TOML format, not JSON. ## Example # String values need double quotes nested in quotes codex --config model='"gpt-5.4"' # Boolean values are written directly codex --config sandbox_workspace_write.network_access=true # Arrays use TOML array syntax codex --config'shell_environment_policy.include_only=["PATH","HOME"]' A few rules that are easy to stumble on: * Use dot syntax to locate nested fields, e.g., mcp_servers.context7.enabled=false * The value of --config will be parsed as TOML; strings with spaces must be quoted * When parsing fails, Codex will treat the entire value as a string > The fastest way to determine if an override took effect is to follow the command with a simple question: "what model are you using?", and let Codex proactively report the current configuration. * * * ## Configuration File and State Locations Codex places all local state under the CODEX_HOME directory, which defaults to ~/.codex. Common files and their meanings: | File | Purpose | Sensitive | | --- | --- | --- | | config.toml | Local main configuration, all custom items are written here | No | | auth.json | File-based credentials (if not using system keychain) | Yes, recommend 600 permissions | | history.jsonl | Session history (can be disabled) | May contain sensitive content | | logs/, caches/ | Runtime logs and caches | May contain request body fragments | ### Only Want to Change OpenAI Base URL? Many users using LLM proxies, routers, or data residency projects only need to modify the base URL of the built-in OpenAI provider. In this case, directly set openai_base_url, do not create [model_providers.openai], because the built-in ID cannot be overridden: ## Example # File path: ~/.codex/config.toml # Point the built-in OpenAI provider's base URL to the proxy openai_base_url = "https://us.api.openai.com/v1" * * * ## Project-level Configuration .codex/config.toml Project-level configuration is placed in .codex/config.toml at the repository root, used for team sharing of default values. Codex will search upward from the working directory level by level. The file closest to the current working directory has the highest priority. ### Project-level Configuration Boundaries For security reasons, project-level .codex/ layers (including config.toml, local hooks, local rules) are only loaded when the project is marked as "trusted". In untrusted projects, the sensitive keys in the following table will be ignored and a startup warning will be printed: | Ignored Key | Reason | | --- | --- | | openai_base_url, chatgpt_base_url | Prevent credential redirection / changing host metadata | | apps_mcp_product_sku | Affects Codex Apps product identification | | model_provider, model_providers | Prevent credential / provider identity replacement | | notify | Prevent executing arbitrary local machine commands | | profile, profiles | Project-level cannot select config profile | | experimental_realtime_ws_base_url, otel | Telemetry and real-time channels | These keys must be placed in the user-level ~/.codex/config.toml. Relative paths (such as model_instructions_file) are resolved relative to the directory where their .codex/ is located. > If the project is untrusted and you set model_provider = "proxy", Codex will print a warning at startup and use the default provider; this is a security design, not a bug. * * * ## Hooks Lifecycle Hooks Hooks allow you to insert custom scripts at key nodes such as tool calls and turn starts, suitable for auditing, sensitive word filtering, commit checks, etc. Hooks configuration supports two forms, and the event structure is exactly the same: | Form | Location | Suitable Scenario | | --- | --- | --- | | hooks.json file | Same directory as config.toml | Friendly to JSON toolchains, easy to reuse | | Inline [[hooks.*]] table | Inside config.toml | All configurations centrally managed | Four most commonly used loading locations: * ~/.codex/hooks.json * ~/.codex/config.toml * /.codex/hooks.json * /.codex/config.toml Project-level hooks are only loaded when the project is trusted. User-level hooks are always loaded independently. ### Inline TOML Hook Example Below is a pre-check hook that executes before Bash tool calls: ## Example # File path: ~/.codex/config.toml # Match all Bash tool calls [[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" # Call the pre-check script in the repository (path relative to .codex/ directory) command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre