Configuration Options Supported in the `.codex/config.toml` File

The .codex/config.toml file supports eight primary configuration options—including model, model_reasoning_effort, openai_base_url, openai_api_key, log_level, broker_endpoint, disable_broker, and reuse_existing_broker—that control model selection, reasoning depth, API connectivity, and broker middleware behavior.

The openai/codex-plugin-cc repository provides a Claude Code plugin that integrates OpenAI's Codex models into your development workflow. Understanding the configuration options supported in the .codex/config.toml file allows you to customize model behavior, API endpoints, and broker settings across both user-level and project-level scopes.

Configuration File Locations

The plugin automatically loads settings from two hierarchical locations according to the source code in plugins/codex/scripts/lib/codex.mjs:

• User-level: ~/.codex/config.toml applies globally to all projects
• Project-level: .codex/config.toml in the repository root (only respected when the project is trusted)

Project-level settings override user-level values when both files exist.

Core Configuration Options

The following options are documented in the official Codex configuration reference and implemented in the runtime configuration merger.

Model Selection and Reasoning

• model: Specifies the Codex model to invoke (e.g., gpt-5.4-mini, gpt-5.3-codex-spark)
• model_reasoning_effort: Controls thinking depth with values of low, medium, or high

API Connectivity and Authentication

• openai_base_url: Base URL for the OpenAI endpoint, essential for corporate proxies or self-hosted instances
• openai_api_key: Authentication credential (string). Never commit this value to version control; prefer environment variables like CODEX_API_KEY

Logging and Observability

• log_level: Controls CLI verbosity with options: error, warn, info, or debug

Broker Middleware Settings

• broker_endpoint: URL of the optional Codex broker server that mediates requests (e.g., http://localhost:8080)
• disable_broker: Boolean flag that, when set to true, forces direct communication with the Codex app server, bypassing the broker
• reuse_existing_broker: Boolean that determines whether to reuse a running broker instance (true) or launch a new one (false)

Implementation Details

The runtime configuration logic resides in plugins/codex/scripts/lib/codex.mjs, which merges user-level defaults, project-level overrides, and internal defaults before invoking the Codex app server. The /codex:setup command, documented in plugins/codex/commands/setup.md, validates the presence and syntax of these configuration files. Additionally, plugins/codex/hooks/hooks.json defines hook-related settings that interact with these configuration options.

Practical Configuration Examples

Basic Project Configuration

Create .codex/config.toml at your repository root to force a specific model and reasoning effort:

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

Corporate Proxy Setup

Override the OpenAI endpoint for enterprise environments:

openai_base_url = "https://my-proxy.company.com/v1"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

Disable Broker for Lightweight Operation

Skip the broker middleware entirely:

disable_broker = true
model = "gpt-5.4-mini"

Secure API Key Handling

Do not store openai_api_key in the file. Instead, export it as an environment variable:

export CODEX_API_KEY=sk-...

The CLI automatically reads CODEX_API_KEY, allowing you to omit the sensitive field from config.toml.

Summary

• The .codex/config.toml file supports eight core configuration options across model, API, logging, and broker categories.
• Configuration files are loaded from either ~/.codex/config.toml (user-level) or .codex/config.toml (project-level), with the latter taking precedence.
• The plugins/codex/scripts/lib/codex.mjs file handles the merging of these configuration layers at runtime.
• Never commit the openai_api_key value; use environment variables like CODEX_API_KEY instead.
• Use disable_broker = true to bypass the broker middleware and communicate directly with the Codex app server.

Frequently Asked Questions

Where should I place my .codex/config.toml file?

You can place settings in ~/.codex/config.toml for global defaults or .codex/config.toml in your repository root for project-specific overrides. The plugin reads both locations, with project-level settings taking precedence when the repository is trusted.

Can I store my OpenAI API key directly in the config.toml file?

While the openai_api_key field exists, you should never commit this value to version control. Instead, export CODEX_API_KEY as an environment variable before invoking the plugin, which the CLI reads automatically without requiring the field in your configuration file.

What is the difference between low, medium, and high reasoning effort?

The model_reasoning_effort parameter controls how long the model thinks before returning a result. Set it to low for faster responses, medium for balanced performance, or high when you need the most thorough analysis of complex codebases.

How do I bypass the broker entirely?

Set disable_broker = true in your .codex/config.toml file. This configuration option forces the plugin to communicate directly with the Codex app server rather than routing through the optional broker middleware defined in broker_endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}