# Codex Plugin for Claude Code: Complete Guide to `.codex/config.toml` Configuration Options

> Explore all eight config options in .codex/config.toml for the Codex plugin with Claude Code. Learn to control models, reasoning, and OpenAI connections for optimal performance.

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

---

**The [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file supports eight core configuration options:** `model`, `model_reasoning_effort`, `openai_base_url`, `openai_api_key`, `log_level`, `broker_endpoint`, `disable_broker`, and `reuse_existing_broker`. These settings control which Codex model runs, how much reasoning effort it applies, and how the plugin connects to OpenAI services.

When using the **OpenAI Codex plugin for Claude Code**, your configuration lives in a simple TOML file that the plugin automatically discovers. The file can exist at two levels: a **user-level** config at `~/.codex/config.toml` for global defaults, or a **project-level** config at [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in your repository root for per-project overrides. The plugin only loads project-level configs when the project is marked as trusted.

## Configuration File Locations and Precedence

The Codex plugin follows a clear hierarchy when resolving settings. According to the source code in `plugins/codex/scripts/lib/codex.mjs`, the runtime merges configurations in this order:

1. **Built-in defaults** — hardcoded fallbacks
2. **User config** — `~/.codex/config.toml`
3. **Project config** — [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) (trusted projects only)
4. **Environment variables** — override any file-based value

This layered approach lets you set sensible defaults globally while tailoring behavior for specific repositories.

## All Available [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) Options

### Core Model Settings

These two options determine which Codex model executes your requests and how thoroughly it reasons before responding.

| Option | Type | Description |
|--------|------|-------------|
| `model` | string | Codex model identifier (e.g., `gpt-5.4-mini`, `gpt-5.3-codex-spark`) |
| `model_reasoning_effort` | string | Effort level: `low`, `medium`, or `high` |

The **`model_reasoning_effort`** parameter directly controls latency and quality tradeoffs. Set `high` for complex refactoring tasks or `low` for quick autocomplete-style suggestions.

### Connection and Authentication

| Option | Type | Description |
|--------|------|-------------|
| `openai_base_url` | string | Base URL for OpenAI API endpoints |
| `openai_api_key` | string | API key for authentication (**use environment variables instead**) |

The **`openai_base_url`** option is essential for corporate deployments or regional proxies. The plugin routes all Codex requests through this endpoint.

### Broker Control

The Codex plugin can operate through an intermediate "broker" server or connect directly. These options govern that behavior:

| Option | Type | Description |
|--------|------|-------------|
| `broker_endpoint` | string | URL of the Codex broker mediation server |
| `disable_broker` | boolean | Skip broker and connect directly to Codex app server |
| `reuse_existing_broker` | boolean | Attach to an already-running broker instead of launching new |

Set **`disable_broker = true`** for lightweight local setups where you want minimal overhead.

### Debugging

| Option | Type | Description |
|--------|------|-------------|
| `log_level` | string | Console verbosity: `error`, `warn`, `info`, or `debug` |

## Practical [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) Examples

### Force a Specific Model with High Reasoning Effort

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

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

```

When you invoke any `/codex:*` command, the plugin automatically selects `gpt-5.4-mini` with maximum reasoning effort.

### Route Through a Corporate Proxy

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

```

This configuration ensures all OpenAI traffic traverses your organization's approved gateway.

### Lightweight Direct Connection

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

```

Eliminates broker overhead for faster startup on resource-constrained environments.

### Secure API Key Handling

Never commit credentials. Instead, reference environment variables:

```toml

# .codex/config.toml — safe to commit

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

# openai_api_key is intentionally omitted

```

Export the key before running Claude Code:

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

```

The CLI automatically detects `CODEX_API_KEY` without requiring the `openai_api_key` field in your config file.

## Key Implementation Files

| Path | Purpose |
|------|---------|
| `plugins/codex/scripts/lib/codex.mjs` | Runtime configuration merging and validation logic |
| [`plugins/codex/commands/setup.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md) | Documentation for the `/codex:setup` validation command |
| [`plugins/codex/hooks/hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/hooks/hooks.json) | Hook definitions including broker-related flag handling |
| [`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) | Official reference for common configurations |

The configuration loader in `codex.mjs` handles edge cases like malformed TOML, missing required fields, and untrusted project detection.

## Summary

- The **[`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml)** file controls model selection, reasoning depth, connection endpoints, and broker behavior for the Codex plugin.
- **Eight configuration options** are available: `model`, `model_reasoning_effort`, `openai_base_url`, `openai_api_key`, `log_level`, `broker_endpoint`, `disable_broker`, and `reuse_existing_broker`.
- **User and project configs layer** — place global defaults in `~/.codex/config.toml` and project-specific overrides in [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml).
- **Never store API keys** in version-controlled config files; use the `CODEX_API_KEY` environment variable instead.
- The **`model_reasoning_effort`** setting provides direct control over latency-quality tradeoffs with `low`/`medium`/`high` levels.

## Frequently Asked Questions

### What happens if both user and project [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) files exist?

The plugin merges both, with **project-level values taking precedence**. In `plugins/codex/scripts/lib/codex.mjs`, the runtime loads user defaults first, then overlays project-specific overrides. This lets you maintain global preferences while customizing individual repositories.

### Is `model_reasoning_effort` required?

No — the option defaults to a sensible value if omitted. However, explicitly setting it is recommended for reproducible behavior across different environments. The `high` setting adds latency but produces more thorough code analysis.

### Can I use [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) without trusting the project?

No. The plugin **only reads project-level configs for trusted projects**. This security measure prevents untrusted repositories from silently redirecting your API calls or exfiltrating credentials through malicious `openai_base_url` values.

### Why would I disable the broker with `disable_broker`?

The broker adds a mediation layer that can simplify multi-user scenarios or caching. For **single-user local development**, disabling it reduces startup time and eliminates a potential point of failure. Set `disable_broker = true` when you want the plugin to communicate directly with Codex services.