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

> Explore the complete reference for the Codex plugin's config.toml. Understand all configuration options for model selection, reasoning, API endpoints, and broker behavior.

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

---

**The Codex plugin for Claude Code uses a [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) § Common Configurations:

- **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 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/hooks/hooks.json).

## Practical Configuration Examples

### Project-Level Model Selection

Create [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at your repository root:

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

```

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

### Corporate Proxy Setup

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

```

### Lightweight Brokerless Configuration

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

```

### Environment-Based Authentication

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

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

```

The CLI reads `CODEX_API_KEY` automatically, allowing you to omit `openai_api_key` from [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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.