elizaos--eliza/plugins/plugin-codex-cli/README.md

@elizaos/plugin-codex-cli

ChatGPT Codex model provider for elizaOS. This node-only plugin lets an Eliza agent use a user's ChatGPT Plus/Pro subscription as a frontier-model provider by reusing the OAuth token cache written by the official codex CLI.

This is intentionally a model provider plugin. It does not add a reasoning runtime, planner loop, context manager, or any native-reasoning architecture. It sits alongside providers like @elizaos/plugin-openai and @elizaos/plugin-anthropic and registers handlers for text (TEXT_SMALL, TEXT_NANO, TEXT_MEDIUM, TEXT_LARGE, TEXT_MEGA), RESPONSE_HANDLER, and ACTION_PLANNER model types.

How it works

The plugin reads OAuth tokens from ~/.codex/auth.json by default, sends requests to:

https://chatgpt.com/backend-api/codex/responses

and uses the same codex-oriented request headers as the CLI path:

• Authorization: Bearer <access_token>
• originator: codex_cli_rs
• User-Agent: codex_cli_rs/...
• chatgpt-account-id: <account_id>
• OpenAI-Beta: responses=v1

On a 401, it refreshes the token with the cached refresh token, writing the auth file atomically under a file lock, then retries once.

Supported models

Set CODEX_MODEL to one of:

• gpt-5
• gpt-5-codex
• gpt-5.4
• gpt-5.5
• gpt-5.5-pro

The default is gpt-5.5.

Configuration

CODEX_AUTH_PATH=~/.codex/auth.json
CODEX_BASE_URL=https://chatgpt.com/backend-api/codex # must target chatgpt.com or localhost
CODEX_MODEL=gpt-5.5
CODEX_JITTER_MS_MAX=200
CODEX_ORIGINATOR=codex_cli_rs
CODEX_USER_AGENT=codex_cli_rs/0.124.0

Usage

Install or enable the plugin the same way as other elizaOS model-provider plugins, then configure an agent to load @elizaos/plugin-codex-cli.

Example direct runtime call:

import { ModelType } from "@elizaos/core";

const text = await runtime.useModel(ModelType.RESPONSE_HANDLER, {
  prompt: "Reply as the agent in one short paragraph.",
});

Tool-capable calls can pass provider-neutral tools, toolChoice, and messages. The plugin forwards tools to the OpenAI Responses API function-tool shape and returns a native result object when tools or messages are used:

const result = await runtime.useModel(ModelType.RESPONSE_HANDLER, {
  messages,
  tools: [
    {
      name: "lookup",
      description: "Look up a fact",
      parameters: { type: "object", properties: { query: { type: "string" } } },
    },
  ],
});

// result.text
// result.toolCalls

Soft mitigation

To reduce account/session weirdness against the ChatGPT Codex backend, each backend instance uses:

• a single in-flight FIFO semaphore
• configurable jitter before requests, default 50-200ms

Scope

This plugin provides a Codex-backed model provider surface. It does not own a reasoning loop, planner, or context manager — those concerns belong to the agent runtime and other plugins.