OpenCode OpenAI Codex Auth Plugin

Access GPT-5 Codex through your ChatGPT Plus/Pro subscription in OpenCode

Found this useful? Follow me on X @nummanali for future updates and more projects!

⚠️ Usage Notice

This plugin is for personal development use only. It uses OpenAI’s official OAuth authentication (the same method as OpenAI’s official Codex CLI) for individual coding assistance with your ChatGPT Plus/Pro subscription.

Not for: Commercial services, API resale, or multi-user applications. For production use, see OpenAI Platform API.

Users are responsible for compliance with OpenAI’s Terms of Use.

Quick Links

For Users

Getting Started - Complete installation and setup guide
Configuration Guide - Advanced config options and patterns
Troubleshooting - Debug techniques and common issues
Privacy & Data Handling - How your data is handled and protected
Release Notes - Version history and updates

For Developers

Explore the engineering depth behind this plugin:

Architecture - Technical design, AI SDK compatibility, store:false explained
Config System - How configuration loading and merging works
Config Fields - Understanding config keys, id, and name fields
Testing Guide - Test scenarios, integration testing, verification matrix

Getting Started

Installation

One-command install/update (global config):

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

Legacy OpenCode (v1.0.209 and below):

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

Then run OpenCode and authenticate:

# 1. Add plugin to ~/.config/opencode/opencode.jsonc (or .json)
# 2. Run OpenCode
opencode

# 3. Authenticate
opencode auth login

If the browser callback fails (SSH/WSL/remote), choose “ChatGPT Plus/Pro (Manual URL Paste)” and paste the full redirect URL.

Updating

Re-run the installer to update:

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

Quick Test

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

Features

✅ OAuth Authentication - Secure ChatGPT Plus/Pro login ✅ GPT 5.2 + GPT 5.2 Codex + GPT 5.1 Models - 22 pre-configured variants across GPT 5.2, GPT 5.2 Codex, GPT 5.1, Codex, Codex Max, Codex Mini ✅ Variant system support - Works with OpenCode v1.0.210+ model variants and legacy presets ✅ Per-Model Configuration - Different reasoning effort, including xhigh for GPT 5.2, GPT 5.2 Codex, and Codex Max ✅ Multi-Turn Conversations - Full conversation history with stateless backend ✅ Verified Configuration - Use config/opencode-modern.json (v1.0.210+) or config/opencode-legacy.json (older) ✅ Comprehensive Testing - 200+ unit tests + integration tests

⚠️ Important: GPT 5 models can be temperamental. Use the official config for your OpenCode version (opencode-modern.json or opencode-legacy.json). Older GPT 5.0 models are deprecated.

Why This Plugin?

Use your ChatGPT subscription instead of OpenAI API credits

No separate API key needed
Access Codex models through ChatGPT Plus/Pro
Same OAuth login as official Codex CLI
Full feature parity with Codex CLI

How It Works

The plugin intercepts OpenCode’s OpenAI SDK requests and transforms them for the ChatGPT backend API:

OAuth Token Management - Handles token refresh automatically
Request Transformation - Converts OpenCode SDK format → Codex API format
AI SDK Compatibility - Filters SDK-specific constructs for Codex API
Stateless Operation - Works with ChatGPT backend’s store: false requirement

See Architecture for technical details.

Development

This plugin represents significant engineering effort to bridge OpenCode and the ChatGPT Codex backend:

7-step fetch flow with precise transformations
AI SDK compatibility layer handling item_reference and other SDK constructs
Stateless multi-turn conversations via encrypted reasoning content
15-minute caching to prevent GitHub API rate limits
Comprehensive test coverage with actual API verification

Explore the development docs to see the depth of implementation:

Support

Issues: GitHub Issues
Releases: Release Notes
Main Repo: GitHub

License

MIT License with Usage Disclaimer - See LICENSE for details

Trademark Notice: Not affiliated with OpenAI. ChatGPT, GPT-5, Codex, and OpenAI are trademarks of OpenAI, L.L.C.