YouTip

Codex CLI is customized through configuration files. This section introduces the structure of the configuration file, various configuration options, and how to adjust them according to your needs. * * * ## Configuration File Location Codex's configuration file is located at `~/.codex/config.toml` in the user's home directory: ~/.codex/config.toml If the file does not exist, you need to create it manually. Codex will create a default configuration file on its first startup. > After modifying the configuration, you need to restart Codex for the changes to take effect. * * * ## Configuration File Structure A complete configuration file may contain the following sections:  Figure: Codex CLI Configuration Structure ## Complete Configuration Example # ~/.codex/config.toml # Basic settings default = "o4-mini" # Default model to use # TUI settings alternate_screen = "auto" # Alternate screen mode: auto/always/never # Skills configuration enabled = true # Feature flags js_repl = false # Whether to enable JavaScript REPL # MCP server configuration # Notification settings enabled = false * * * ## Model Configuration Codex supports multiple models, and you can choose according to your task requirements: | Configuration Item | Type | Description | | --- | --- | --- | | `model.default` | string | Default model to use | | `model.reasoning_effort` | string | Reasoning effort: low/medium/high | ### Available Models Available models for Codex CLI include: * `o4-mini` - Fast and efficient, suitable for simple tasks * `o4-mini-high` - High reasoning version of o4-mini * `o3` - Powerful reasoning capabilities * `o3-pro` - Professional version of o3 > Different models have different speeds and prices. Choosing the right model can optimize the user experience and cost. * * * ## TUI Configuration Settings related to the Terminal User Interface: | Configuration Item | Type | Description | Default Value | | --- | --- | --- | --- | | `tui.alternate_screen` | string | Alternate screen mode: auto/always/never | auto | | `tui.width` | number | Terminal width | 0 (auto) | | `tui.height` | number | Terminal height | 0 (auto) | ### Alternate Screen Mode Explanation * `auto` - Auto-detect, automatically disabled in terminal multiplexers like Zellij * `always` - Always use alternate screen (default experience) * `never` - Never use alternate screen (preserves scroll history) ### Runtime Override You can override these settings at runtime via command-line arguments: ## Command-line Override Configuration # Disable alternate screen mode codex --no-alt-screen * * * ## Skills Configuration Skills are Codex's extension mechanism, allowing you to customize your workflow: | Configuration Item | Type | Description | | --- | --- | --- | | `skills.enabled` | boolean | Whether to enable the skills system | | `skills.directory` | string | Skills file directory | ### Custom Skills Directory ## Configure Skills Directory enabled = true directory = "~/my-codex-skills" * * * ## MCP Server Configuration MCP (Model Context Protocol) servers allow Codex to integrate with external tools and services: ## Configure MCP Servers [mcp_servers.docs] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"] # Tool permission configuration [mcp_servers.docs.tools.search] approval_mode = "approve" ### MCP Tool Permissions You can set permissions individually for each MCP server's tools: * `approve` - Automatically approve, no asking required * `deny` - Automatically deny * `ask` - Ask before each execution (default) > Be careful when configuring MCP servers, ensure you only enable tools you trust. * * * ## Feature Flags Enable or disable specific features of Codex: | Configuration Item | Type | Description | | --- | --- | --- | | `features.js_repl` | boolean | Enable JavaScript REPL | | `features.js_repl_tools_only` | boolean | Restrict to js_repl tools only | ### JavaScript REPL Configuration ## Enable JavaScript REPL js_repl = true You can also specify the Node.js path: ## Specify Node.js Path js_repl_node_path = "/usr/local/bin/node" * * * ## Notification Configuration Codex can send notifications when a task is completed: | Configuration Item | Type | Description | | --- | --- | --- | | `notify.enabled` | boolean | Enable notifications | ### Configure Notification Hooks You can configure custom notification scripts via environment variables: CODEX_NOTIFY_HOOK=/path/to/your/notify-script.sh * * * ## SQLite State Database Codex uses SQLite to store internal state: | Environment Variable | Description | Default Value | | --- | --- | --- | | `CODEX_SQLITE_HOME` | SQLite database directory | Same as CODEX_HOME | ## Configure SQLite Directory export CODEX_SQLITE_HOME=/path/to/sqlite codex * * * ## Log Configuration Codex uses Rust's env_logger, and you can configure the log level: ## Configure Log Output # View logs tail-f ~/.codex/log/codex-tui.log # Set log level RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info codex | Log Level | Description | | --- | --- | | `error` | Only show errors | | `warn` | Show warnings and errors | | `info` | Show general info, warnings, and errors | | `debug` | Show debug info | | `trace` | Show detailed trace info | > By default, the log level for TUI mode is info, and for non-interactive mode (exec) the default level is error. * * * ## Plan Mode Configuration Configure Codex's behavior in plan mode: ## Configure Plan Mode # Set the default reasoning effort for plan mode # Optional values: low/medium/high/none plan_mode_reasoning_effort = "medium" * * * ## Common Configuration Examples ### Basic Configuration ## Minimal Configuration # Use default settings # Codex already provides reasonable defaults ### High-Performance Configuration ## Performance Optimization Configuration default = "o4-mini" alternate_screen = "always" js_repl = true ### Developer Configuration ## Developer Configuration default = "o4-mini" reasoning_effort = "high" alternate_screen = "never" enabled = true directory = "~/codex-skills"