feat(plugin-codex-cli): ChatGPT Codex model provider via OAuth token cache

[0xSolace]

Summary

Proposes @elizaos/plugin-codex-cli, a model provider plugin that lets Eliza agents use a user's ChatGPT Plus/Pro subscription as a frontier-model provider through the official codex CLI auth cache.

This is the CodexBackend piece salvaged from closed PR #7435 after Wave 1 superseded the native-reasoning runtime work. It is intentionally scoped as a model provider plugin alongside plugin-openai and plugin-anthropic, not a reasoning runtime, planner, loop, or context architecture change.

Mechanism

The plugin reads OAuth credentials from ~/.codex/auth.json by default, then talks to:

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

It sends the codex-style headers used by the CLI path:

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

Supported models:

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

Provider surface

Registers handlers for:

• ModelType.TEXT_SMALL
• ModelType.TEXT_NANO
• ModelType.TEXT_MEDIUM
• ModelType.TEXT_LARGE
• ModelType.TEXT_MEGA
• ModelType.RESPONSE_HANDLER
• ModelType.ACTION_PLANNER
• ModelType.OBJECT_SMALL
• ModelType.OBJECT_LARGE

Tool-capable calls pass provider-neutral tools, toolChoice, and messages; the plugin forwards tools to OpenAI Responses API native function-tool format and returns native tool-call results for V5 planner/native-tool-calling paths.

Usage

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

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

With native tools:

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

Configuration

CODEX_AUTH_PATH=~/.codex/auth.json
CODEX_BASE_URL=https://chatgpt.com/backend-api/codex
CODEX_MODEL=gpt-5.5
CODEX_JITTER_MS_MAX=200
CODEX_ORIGINATOR=codex_cli_rs

CODEX_BASE_URL is restricted to chatgpt.com or localhost to avoid accidental OAuth bearer-token exfiltration.

Soft mitigation

• Single in-flight FIFO semaphore per runtime backend instance
• 50ms to CODEX_JITTER_MS_MAX pre-request jitter, default max 200ms
• 401 refresh path with atomic file-locked auth refresh, then one retry

Notes

• Node-only at runtime because it reads the local codex CLI auth file.
• Browser export is a stub so package exports stay consistent without bundling node fs/crypto auth code into browser builds.
• Complements Wave 1 native-tool-calling on develop; does not modify packages/core or V5 architecture.

Validation

bun run --cwd plugins/plugin-codex-cli test
bun run --cwd plugins/plugin-codex-cli build
bunx @biomejs/biome check plugins/plugin-codex-cli/

Also ran Codex review against the uncommitted diff and addressed the medium findings it surfaced.

Tags: kind/feat, area/plugin, status/proposal

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c408e517-92c7-4086-9dc3-b06670f4cd42

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[0xSolace]

Runtime load failure: peerDependency workspace:* doesn't resolve outside workspace

Tested baking this PR's @elizaos/plugin-codex-cli into a real eliza runtime (nyx production fleet, plugin staged via the runtime-imports path) and the plugin failed to load:

Failed plugins: @elizaos/plugin-codex-cli (Cannot find package '@elizaos/core' imported from /root/.milady/plugins/.runtime-imports/_elizaos_plugin-codex-cli/.../dist/node/index.node.js)

Root cause

plugins/plugin-codex-cli/package.json declares:

"peerDependencies": {
  "@elizaos/core": "workspace:*",
  "zod": "^4.4.3"
}

When eliza's plugin-resolver stages a custom plugin into ~/.milady/plugins/.runtime-imports/... (a fresh dir outside the original workspace), workspace:* doesn't resolve — there's no parent package.json with workspaces declared, and the staged copy doesn't ship @elizaos/core in its own node_modules.

Comparison with existing patterns

Other custom plugins that load successfully via this same staging path (e.g. the previous @0xsolace/plugin-acpx) declare:

"peerDependencies": {
  "@elizaos/core": "*"
}

Plain * works because the resolver falls through to the host eliza's node_modules/@elizaos/core install.

Fix

In plugins/plugin-codex-cli/package.json, change:

"peerDependencies": {
  "@elizaos/core": "workspace:*",
  "zod": "^4.4.3"
}

to:

"peerDependencies": {
  "@elizaos/core": "*",
  "zod": "^4.4.3"
}

(Keep workspace:* in devDependencies so monorepo-internal builds still work.)

Reproduction

1. Build @elizaos/plugin-codex-cli from this PR's HEAD (63b838d8)
2. Drop the built dir into any path listed in config.plugins.load.paths
3. Boot eliza runtime
4. Plugin fails to import at module-load time

Test signal

Recommend a CI step that stages the built plugin into a temp dir outside the workspace and tries node -e "await import('@elizaos/plugin-codex-cli')" to catch peer resolution issues before publish.

Same issue will affect anyone trying to install this plugin from a published tarball outside the eliza monorepo.

[0xSolace]

Closing — content of this PR was cherry-picked onto develop in commit c6cc595a feat(plugin-codex-cli): add ChatGPT Codex provider (Sol authored, landed 2026-05-07 05:57 UTC) plus follow-up e0ff507d chore(orchestrator): drop subprocess codex-model-provider in favor of plugin-codex-cli (Shaw, 2026-05-07 13:55 UTC).

Rebase confirms zero commits ahead of develop. Functionally identical to what's on develop already.

Thanks @lalalune for landing this cleanly.