Codex Plugin config.toml Configuration Options: Complete Reference for openai/codex-plugin-cc

The Codex plugin for Claude Code uses a config.toml file to control model selection, reasoning effort, API endpoints, and broker behavior, supporting both user-level (~/.codex/config.toml) and project-level (.codex/config.toml) configurations.

The openai/codex-plugin-cc repository extends Claude Code with Codex capabilities through a flexible TOML configuration system. Understanding the available Codex plugin config.toml configuration options allows developers to customize model behavior, routing, and security settings without modifying source code. This guide covers every supported setting based on the actual implementation in the plugin's source files.

Configuration File Locations and Precedence

The plugin reads settings from two locations according to README.md § Common Configurations:

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

As implemented in plugins/codex/scripts/lib/codex.mjs, the runtime merges these configurations with internal defaults before invoking the Codex app server.

Complete List of Codex Plugin config.toml Options

Model and Reasoning Settings

• model (string): Specifies the Codex model to invoke. Valid values include gpt-5.4-mini or gpt-5.3-codex-spark.

• model_reasoning_effort (string): Controls computation time with values low, medium, or high.

OpenAI API Configuration

• openai_base_url (string): Overrides the default OpenAI endpoint, essential for corporate proxies or regional deployments.

• openai_api_key (string, sensitive): Authentication token for OpenAI. The plugins/codex/commands/setup.md documentation recommends omitting this field and using the CODEX_API_KEY environment variable instead.

Logging and Debugging

• log_level (string): Sets CLI verbosity to error, warn, info, or debug.

Broker and Network Settings

• broker_endpoint (string): URL for the optional Codex broker server that mediates requests.

• disable_broker (bool): When true, the plugin bypasses the broker and connects directly to the Codex app server.

• reuse_existing_broker (bool): If true, the plugin attaches to a running broker instance rather than spawning a new process, as defined in plugins/codex/hooks/hooks.json.

Practical Configuration Examples

Project-Level Model Selection

Create .codex/config.toml at your repository root:

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

When executing any /codex:* command, the plugin automatically applies these overrides.

Corporate Proxy Setup

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

Lightweight Brokerless Configuration

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

Environment-Based Authentication

Never commit API keys. Instead, export the variable before running Claude Code:

export CODEX_API_KEY=sk-...

The CLI reads CODEX_API_KEY automatically, allowing you to omit openai_api_key from config.toml.

Summary

• The Codex plugin config.toml configuration options include eight primary settings covering model selection, API routing, and broker behavior.
• Configuration files follow a hierarchy: user-level (~/.codex/config.toml) provides defaults, while project-level (.codex/config.toml) allows repository-specific overrides.
• Sensitive values like openai_api_key should use environment variables rather than committed files.
• The merging logic resides in plugins/codex/scripts/lib/codex.mjs, ensuring consistent behavior across different execution contexts.

Frequently Asked Questions

What is the difference between user-level and project-level config.toml files?

The user-level file at ~/.codex/config.toml applies globally to all projects on your machine. The project-level file at .codex/config.toml overrides these settings for a specific repository, but only loads when the project is marked as trusted according to the README documentation.

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

While the openai_api_key field exists, you should never commit this value to version control. The plugin automatically reads the CODEX_API_KEY environment variable, making it the recommended approach for credential management.

How does the model_reasoning_effort setting affect performance?

The model_reasoning_effort parameter accepts low, medium, or high values that control how long the model thinks before generating a response. Higher effort levels produce more thorough results but increase latency and token consumption.

What happens if I disable the broker?

Setting disable_broker = true forces the plugin to communicate directly with the Codex app server rather than routing through the optional broker intermediary. This simplifies network architecture but removes the mediation capabilities provided by the broker endpoint.

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