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

The .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 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 (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 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 Examples

Force a Specific Model with High Reasoning Effort

Create .codex/config.toml in your repository root:

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

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

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:

# .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:

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	Documentation for the /codex:setup validation command
plugins/codex/hooks/hooks.json	Hook definitions including broker-related flag handling
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 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.
• 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 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 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.

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