# How to Configure the Codex Plugin for Custom OpenAI‑compatible API Endpoints

> Learn how to configure the Codex plugin for custom OpenAI-compatible API endpoints. Set your openai base url in the config toml file for flexible API integration.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-08-04

---

**Yes — the Codex plugin can use custom base URLs by setting `openai_base_url` in the Codex CLI's [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) file, which the plugin automatically inherits.**

The **Codex plugin** does not implement its own OpenAI client. Instead, it delegates all requests to the locally installed **Codex CLI** and its app-server. This architectural choice means every configuration option available to the CLI — including custom API endpoints — flows directly to the plugin without additional setup.

## How the Plugin Inherits Custom Endpoints

### Architecture Overview

The plugin communicates with the **Codex app-server** through the library at `plugins/codex/scripts/lib/codex.mjs`. The app-server reads configuration from standard **TOML files** at either the user level (`~/.codex/config.toml`) or project level ([`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml)).

When you specify `openai_base_url` in either location, you override the default `https://api.openai.com/v1` endpoint used by the built-in OpenAI provider. The plugin requires no code changes — it simply routes through the already-configured CLI.

### Configuration Sources

| Scope | Path | Best For |
|-------|------|----------|
| Project-level | [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) | Repository-specific endpoints |
| User-level | `~/.codex/config.toml` | Global default across all projects |

## Setting Up Custom OpenAI-compatible Endpoints

### Project-Level Configuration (Recommended for Single Repositories)

Create a `.codex` directory in your repository root and add the endpoint:

```bash
mkdir -p .codex
cat > .codex/config.toml <<'EOF'
openai_base_url = "https://my-custom-openai-proxy.example.com/v1"
openai_api_key = "sk-*****"
EOF

```

Any `/codex:*` command executed in this repository now targets your custom endpoint.

### User-Level Configuration (Global Default)

Apply the setting across your entire machine:

```bash
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
openai_base_url = "https://my-custom-openai-proxy.example.com/v1"
EOF

```

### Verifying Your Configuration

Confirm the plugin will use your custom endpoint:

```bash
codex config show | grep openai_base_url

```

The output displays your configured value, proving the setting is active before the plugin invokes the CLI.

## Evidence from the Source Code

The repository's documentation explicitly supports this approach. As stated in [`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) (lines 316-322):

> "Point the built-in OpenAI provider at a different endpoint, set `openai_base_url` in your Codex config."

The core library at `plugins/codex/scripts/lib/codex.mjs` launches the app-server without hardcoding any API URLs — it relies entirely on the CLI's configuration resolution. This design guarantees that **custom OpenAI-compatible API endpoints** configured in TOML files propagate automatically to plugin operations.

## Compatible Endpoint Requirements

Your custom endpoint must implement the **OpenAI API specification**. Most providers advertising "OpenAI-compatible" support — including Azure OpenAI Service, local inference servers like [`llama.cpp`](https://github.com/openai/codex-plugin-cc/blob/main/llama.cpp), and proxies like `litellm` — work without modification. The `openai_base_url` value should point to the base path preceding `/chat/completions`, `/models`, and other standard endpoints.

## Summary

- The **Codex plugin** delegates all API calls to the local Codex CLI app-server configured in `plugins/codex/scripts/lib/codex.mjs`.
- Set **`openai_base_url`** in `~/.codex/config.toml` or [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) to override the default OpenAI endpoint.
- No plugin code changes or special flags are required — configuration flows automatically from CLI to plugin.
- Use **`codex config show`** to verify your custom endpoint is recognized before running plugin commands.

## Frequently Asked Questions

### Where does the Codex plugin store its API configuration?

The plugin does not store API configuration independently. It reads from the same TOML files used by the Codex CLI: either `~/.codex/config.toml` for user-level settings or [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) for project-specific overrides. Set `openai_base_url` in either file to control where requests are sent.

### Can I use Azure OpenAI Service with the Codex plugin?

Yes — any **OpenAI-compatible API endpoint** works, including Azure OpenAI Service. Configure `openai_base_url` to your Azure endpoint (e.g., `https://your-resource.openai.azure.com/openai/deployments/your-deployment`) and ensure `openai_api_key` contains your Azure API key. The plugin routes requests exactly as the CLI would.

### Do I need to restart my editor after changing the configuration?

No. The Codex plugin launches a fresh app-server process for each operation through `plugins/codex/scripts/lib/codex.mjs`, which reads the current configuration file. Changes to [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) take effect on the next `/codex:*` command without requiring an editor restart.

### What happens if `openai_base_url` is not set?

When `openai_base_url` is absent, the built-in OpenAI provider defaults to `https://api.openai.com/v1`. The plugin continues to function normally, sending all requests to the standard OpenAI API endpoint.