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

> Explore Codex config.toml configuration options for model selection, API endpoints, and plugin behavior. Master your OpenAI plugin setup with our complete guide.

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

---

**The [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at the root of your repository to force a specific model and high reasoning effort for that project:

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

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

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

```toml

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) during the `/codex:setup` command flow (documented in [`plugins/codex/commands/setup.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md)). 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 can also be overridden via [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml), including broker-related flags.

## Summary

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