Codex config.toml Configuration Options: Complete Guide for the OpenAI Plugin

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

The openai/codex-plugin-cc repository provides a Claude Code plugin that integrates OpenAI's Codex models. Configuration management is handled through TOML files that allow you to specify everything from model selection to broker behavior without modifying environment variables directly.

Configuration File Locations

The plugin automatically reads settings from two distinct locations, merging them with project-level values taking precedence over user-level defaults.

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

According to the source code in plugins/codex/scripts/lib/codex.mjs, the runtime merges user, project, and default settings before invoking the Codex app server.

Core Configuration Options

The following options control how the Codex plugin connects to OpenAI services and manages the local broker:

• model – String specifying the Codex model to invoke (e.g., gpt-5.4-mini, gpt-5.3-codex-spark).
• model_reasoning_effort – String controlling how long the model thinks before returning results. Valid values are low, medium, or high.
• openai_base_url – String containing the base URL for the OpenAI endpoint. Use this when running a self-hosted proxy or connecting to a different region.
• openai_api_key – String for the API key. Never commit this value to version control; the CLI can read it from environment variables instead.
• log_level – String setting verbosity of CLI logs. Valid values are error, warn, info, or debug.
• broker_endpoint – String URL of the optional Codex broker server that mediates requests.
• disable_broker – Boolean. When set to true, the plugin skips the broker and communicates directly with the Codex app server.
• reuse_existing_broker – Boolean. When set to true, the plugin reuses a broker that is already running instead of launching a new one.

These options are documented in README.md under the Common Configurations section and match the keys that the Codex CLI expects.

Practical Configuration Examples

Setting Model and Reasoning Effort

Create a .codex/config.toml at the root of your repository to force a specific model and high reasoning effort for that project:

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

When you run any /codex:* command in that project, the plugin automatically uses this model-and-effort pair.

Configuring Corporate Proxy Endpoints

Override the OpenAI endpoint when running behind a corporate proxy:

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

Disabling the Broker for Lightweight Setups

Skip the broker entirely and connect directly to the Codex app server:

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

Securing API Keys with Environment Variables

Do not store sensitive credentials in the TOML file. Instead, export the key before invoking the plugin:

# Do NOT store the key in the file.

# Instead export it before invoking the plugin:

# export CODEX_API_KEY=sk-...

The CLI reads CODEX_API_KEY automatically, so the config.toml can omit the openai_api_key field entirely.

How Configuration is Loaded

The runtime logic in plugins/codex/scripts/lib/codex.mjs handles the merging of configuration layers. It validates the presence of a usable config.toml during the /codex:setup command flow (documented in plugins/codex/commands/setup.md). Additionally, plugins/codex/hooks/hooks.json defines hook-related settings that can also be overridden via config.toml, including broker-related flags.

Summary

• The config.toml file supports eight core options: model, model_reasoning_effort, openai_base_url, openai_api_key, log_level, broker_endpoint, disable_broker, and reuse_existing_broker.
• Configuration can exist at user-level (~/.codex/config.toml) or project-level (.codex/config.toml), with project settings taking precedence.
• Never commit openai_api_key to version control; use environment variables like CODEX_API_KEY instead.
• The broker can be disabled (disable_broker = true) for direct server communication or reused (reuse_existing_broker = true) to avoid launching duplicate instances.
• The runtime merger in plugins/codex/scripts/lib/codex.mjs processes these files before invoking the Codex app server.

Frequently Asked Questions

Where should I place my Codex config.toml file?

You can place configuration in either ~/.codex/config.toml for global settings or .codex/config.toml in your repository root for project-specific settings. The project-level file only loads when the project is marked as trusted, and its values override the user-level defaults.

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

While the openai_api_key field exists, you should never store the actual key in the TOML file. Instead, export CODEX_API_KEY as an environment variable. The CLI reads this variable automatically, keeping sensitive credentials out of version-controlled files.

What is the difference between user-level and project-level configuration?

User-level configuration at ~/.codex/config.toml applies to all projects system-wide, while project-level .codex/config.toml provides repository-specific overrides. According to the implementation in plugins/codex/scripts/lib/codex.mjs, the plugin merges both layers with project values taking precedence over user defaults.

How do I disable the broker server?

Set disable_broker = true in your config.toml. When this boolean is enabled, the plugin bypasses the broker and communicates directly with the Codex app server. This is useful for lightweight setups where you do not need the mediation layer provided by the broker endpoint.

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