OpenCode OpenAI Codex Authentication Plugin

4.4.0 · active · verified Wed Apr 22

This package provides an authentication plugin for the OpenCode AI platform, enabling users to leverage their existing ChatGPT Plus/Pro subscriptions with the OpenAI Codex backend instead of consuming API credits. The current stable version is 4.4.0, and the project demonstrates a very active release cadence with multiple minor and patch releases in quick succession, indicating ongoing development and maintenance. Key differentiators include a simplified one-command installer (`npx opencode-openai-codex-auth@latest`), comprehensive support for various GPT-5.x and Codex model families (including GPT-5.2 Codex), and an official OAuth flow for seamless integration. It handles multimodal input and automatically manages token refresh, aiming to provide a 'one config, every model' philosophy for OpenCode users. It is designed primarily for personal development use, with a warning against production or multi-user applications.

Common errors

```
Invalid JSON response
```
cause The `/agent create` command failed due to issues in handling SSE/JSON responses or overly aggressive filtering of tool calls during compaction.

fix Upgrade to version 4.0.2 or newer, which contains fixes for agent creation failing and correct handling of SSE/JSON responses.
```
400 errors during summary/compaction requests when OpenCode sends item_reference pointers to server-stored function calls
```
cause The plugin was aggressively filtering out `function_call` and `function_call_output` items, even when tools were present, leading to orphaned `function_call_output` errors.

fix Upgrade to version 4.0.1 or newer. This version fixes the compaction context loss by only filtering orphaned outputs (without matching calls), preserving matched pairs for context.
```
GitHub API rate limiting when fetching Codex instructions
```
cause Frequent requests to GitHub for Codex instructions could trigger API rate limits, causing failures in fetching necessary data.

fix Upgrade to version 4.0.1 or newer, which includes a fallback mechanism to handle GitHub API rate limiting.

Warnings

breaking The plugin enforced GPT 5.1 model identifiers, deprecating and removing legacy GPT 5.0 models. Existing configurations using GPT-5.0 model names will break.
Fix: Update all configurations to use GPT-5.1 model identifiers. Refer to `config/full-opencode.json` for the officially supported configuration structure.
breaking Version 4.0.0 migrated all GPT-5.0 models to GPT-5.1. This change requires users to update their model references in configurations and commands.
Fix: Switch all references from `gpt-5.0` to `gpt-5.1` in your OpenCode commands and configurations, specifically updating model presets.
gotcha Codex variants (Codex, Codex Max, Codex Mini) do NOT support `reasoning_effort: "none"`. Attempting to set this will auto-convert it to 'low' for Codex/Codex Max, or 'medium' for Codex Mini.
Fix: Avoid setting `reasoning_effort: "none"` for Codex variants. If faster responses are desired, use other reasoning effort levels or non-Codex GPT models that support 'none'.
gotcha This plugin is strictly for personal development use with your own ChatGPT Plus/Pro subscription. It is not intended for production or multi-user applications.
Fix: For production or multi-user applications, utilize the official OpenAI Platform API directly instead of this plugin to ensure proper scalability and credential management.

Install

npm install opencode-openai-codex-auth npm
yarn add opencode-openai-codex-auth yarn
pnpm add opencode-openai-codex-auth pnpm

Imports

OpenAICodexAuthPlugin
```
import { OpenAICodexAuthPlugin } from 'opencode-openai-codex-auth';
```
While this package ships TypeScript types, its primary interaction method for end-users is via CLI commands (`npx`, `opencode`), not direct programmatic imports. This symbol represents the likely main plugin class for integration within the OpenCode framework itself.
IOpenAICodexAuthOptions
```
import type { IOpenAICodexAuthOptions } from 'opencode-openai-codex-auth';
```
This type likely defines the configuration options for the OpenCode OpenAI Codex authentication plugin, used when configuring the plugin within the OpenCode ecosystem or for advanced development. Direct programmatic configuration by end-users is not the primary use case, which focuses on CLI-driven setup.
Installer
```
import { Installer } from 'opencode-openai-codex-auth/installer';
```
Although the primary interaction is via `npx` to run the installer script, this path might be used for programmatic interaction with the installer's underlying logic, perhaps for testing or custom setup automation. For typical use, the `npx` command is preferred.

Quickstart

This quickstart demonstrates the one-command installation and subsequent authentication and model usage with the OpenCode CLI.

npx -y opencode-openai-codex-auth@latest

opencode auth login
opencode run "write hello world to test.txt" --model=openai/gpt-5.2 --variant=medium

# For legacy OpenCode (v1.0.209 and below):
npx -y opencode-openai-codex-auth@latest --legacy
opencode run "write hello world to test.txt" --model=openai/gpt-5.2-medium

view raw JSON →