# How the Codex Plugin Interacts with the OpenAI API: A Technical Deep Dive

> Learn how the Codex plugin interacts with the OpenAI API through a technical deep dive. Discover its indirect communication method via the local codex binary and RPC calls.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-03

---

**The Codex plugin does not call the OpenAI API directly; instead, it invokes the local `codex` binary to start an app-server, then sends RPC calls like `review/start` and `turn/start` that the server forwards to OpenAI endpoints using authentication stored by the Codex CLI.**

The `openai/codex-plugin-cc` repository serves as a bridge between Claude Code and OpenAI's Codex CLI. Rather than implementing direct HTTP requests to OpenAI's REST endpoints, the plugin relies on a local **Codex app-server** to handle all networking, authentication, and provider resolution. This architecture isolates the plugin from API complexities while enabling support for multiple model providers including OpenAI, Ollama, and LM Studio.

## The Indirect Communication Architecture

The plugin's interaction with the OpenAI API is entirely mediated through the locally installed Codex CLI. When you run a slash command like `/codex:review` in Claude Code, the plugin spawns the `codex` binary (installed via `npm install -g @openai/codex`), which starts a lightweight HTTP-JSON server implementing the OpenAI API surface. This **app-server** listens on a Unix socket or TCP port and exposes RPC endpoints that the plugin consumes.

The flow decouples the plugin from direct API management. The plugin only needs to know how to speak to the local app-server; the server handles provider selection, authentication token retrieval, and request formatting. According to the source code in `plugins/codex/scripts/lib/codex.mjs`, the plugin creates a `CodexAppServerClient` instance to manage this connection, while the server reads configuration from `~/.codex/config.toml` to determine whether to route requests to OpenAI or alternative providers.

## Step-by-Step RPC Flow from Plugin to OpenAI

### Step 1: Binary Invocation and Server Startup

The plugin first verifies that the `codex` binary is available (checked via `binaryAvailable` in `plugins/codex/scripts/lib/process.mjs`). Upon confirmation, it launches the binary, which spawns the Codex app-server. This server implements the full OpenAI API surface including models, completions, and chat endpoints.

### Step 2: Client Initialization and Connection

In `plugins/codex/scripts/lib/app-server.mjs`, the plugin instantiates a `CodexAppServerClient` that connects to the server via Unix socket or TCP. This client manages the lifecycle of the connection and provides a `request` method for sending RPC messages.

### Step 3: RPC Call Dispatch

The plugin translates Claude Code commands into specific RPC calls:

- **`review/start`**: Initiated by `runAppServerReview` in `codex.mjs` to begin a code review session
- **`turn/start`**: Initiated by `runAppServerTurn` to execute a model inference turn
- **`thread/start`**: Creates new conversation threads
- **`account/read`** and **`config/read`**: Used by `getCodexAuthStatusFromClient` to retrieve authentication state

These calls are sent as JSON-RPC messages to the app-server, which queues them for processing.

### Step 4: Provider Resolution and OpenAI Forwarding

Before executing requests, the app-server calls `resolveProviderConfig` and `formatProviderLabel` (defined in `codex.mjs`) to parse the user's [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml). When `model_provider` is set to `openai`, the server retrieves authentication credentials—either a ChatGPT login session or API key—stored by the Codex CLI. It then forwards the request to the appropriate OpenAI endpoints, streams the response, and notifies the plugin via server-sent events or similar notification mechanisms.

## Key Source Files and Functions

The integration lives primarily in two modules:

- **`plugins/codex/scripts/lib/codex.mjs`**: Contains the high-level orchestration logic including `runAppServerReview`, `runAppServerTurn`, `getCodexAuthStatus`, and `resolveProviderConfig`. This file builds request payloads, captures turn state, and maps provider configurations to human-readable labels.

- **`plugins/codex/scripts/lib/app-server.mjs`**: Implements the `CodexAppServerClient` class that manages the TCP/Unix socket connection, sends RPC requests, and handles server notifications. This is the low-level transport layer between the plugin and the local Codex binary.

- **`plugins/codex/scripts/lib/process.mjs`**: Provides utility functions like `binaryAvailable` to verify the Codex CLI installation before attempting to spawn the app-server.

## Practical Code Examples

### Starting a Code Review

To initiate a review session that ultimately calls OpenAI models, use `runAppServerReview`:

```javascript
import { runAppServerReview } from './plugins/codex/scripts/lib/codex.mjs';

await runAppServerReview(process.cwd(), {
  model: 'gpt-5.4',          // optional – defaults to config.toml
  delivery: 'inline',        // "inline" or "detached"
  target: { type: 'uncommitted' },
  onProgress: (msg) => console.log(msg)   // receives streaming notifications
});

```

### Executing a Model Turn

For direct chat interactions, `runAppServerTurn` sends a `turn/start` RPC that the app-server forwards to OpenAI:

```javascript
import { runAppServerTurn } from './plugins/codex/scripts/lib/codex.mjs';

await runAppServerTurn(process.cwd(), {
  prompt: 'Explain why the current test suite is flaky.',
  model: 'gpt-5.4-mini',
  sandbox: 'read-only',
  onProgress: (msg) => console.log(msg)
});

```

### Checking Authentication Status

Verify whether the local Codex CLI has valid OpenAI credentials before executing expensive operations:

```javascript
import { getCodexAuthStatus } from './plugins/codex/scripts/lib/codex.mjs';

const auth = await getCodexAuthStatus(process.cwd());
console.log(auth);
// Returns status indicating ChatGPT login or API key presence

```

## Summary

- The **Codex plugin** never directly contacts the OpenAI API; all communication flows through the local Codex CLI.
- The plugin spawns the `codex` binary to start an **app-server**, then sends RPC calls like `review/start` and `turn/start` via a `CodexAppServerClient`.
- The **app-server** handles provider resolution by reading `~/.codex/config.toml`, supporting OpenAI, Ollama, and LM Studio backends.
- Authentication credentials are managed by the Codex CLI, not the plugin, which simply queries status via `getCodexAuthStatus`.
- Core implementation files include `plugins/codex/scripts/lib/codex.mjs` for orchestration and `plugins/codex/scripts/lib/app-server.mjs` for transport.

## Frequently Asked Questions

### Does the Codex plugin store my OpenAI API key?

No. The plugin does not handle API keys directly. Authentication is managed by the locally installed **Codex CLI**, which stores credentials in `~/.codex/config.toml`. The plugin only queries the authentication status via `getCodexAuthStatus` to determine if a valid OpenAI session or API key exists before initiating requests.

### Can the Codex plugin work with models other than OpenAI's GPT?

Yes. The plugin supports any provider configured in the Codex CLI configuration file. According to `resolveProviderConfig` in `codex.mjs`, the app-server can route requests to **Ollama**, **LM Studio**, or other local model providers. The plugin remains agnostic to the underlying model, communicating only through the standardized RPC interface.

### What happens if the Codex app-server crashes during a request?

The plugin establishes connections through `CodexAppServerClient` in `app-server.mjs`, which manages the TCP or Unix socket lifecycle. If the server becomes unavailable, subsequent RPC calls will fail with connection errors, and the plugin will surface these failures back to Claude Code. The `binaryAvailable` check in `process.mjs` helps ensure the binary exists before attempting to spawn the server, but runtime crashes would require restarting the CLI.

### How does the plugin handle streaming responses from OpenAI models?

The plugin receives streaming updates via the app-server's notification system. When calling `runAppServerTurn` or `runAppServerReview`, you provide an `onProgress` callback that receives real-time messages containing reasoning steps, file changes, and command execution updates. The app-server handles the actual OpenAI streaming API and forwards relevant chunks to the plugin as RPC notifications.