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

> Explore supported configuration options in codex/config.toml. Customize model, API, and broker settings for optimal OpenAI Codex plugin performance.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-07-10

---

**The [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md), validates the presence and syntax of these configuration files. Additionally, [`plugins/codex/hooks/hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at your repository root to force a specific model and reasoning effort:

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

```

### Corporate Proxy Setup

Override the OpenAI endpoint for enterprise environments:

```toml
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:

```toml
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:

```bash
export CODEX_API_KEY=sk-...

```

The CLI automatically reads `CODEX_API_KEY`, allowing you to omit the sensitive field from [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml).

## Summary

- The [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file?

You can place settings in `~/.codex/config.toml` for global defaults or [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`.