Welcome to the OpenCode OpenAI Codex Auth Plugin documentation.
- Getting Started - Installation, configuration, and quick start
- Configuration Guide - Complete config reference
- Troubleshooting - Common issues and debugging
- Changelog - Version history and release notes
Explore the engineering depth behind this plugin:
- Architecture - Technical design, request transform modes, AI SDK compatibility
- API Contract Audit (v5.4.0) - Public API compatibility assessment, error contracts, and versioning guidance
- Configuration System - How config loading and merging works
- Config Fields Guide - Understanding config keys,
id, andname - Testing Guide - Test scenarios, verification procedures, integration testing
- OMX Team + Ralph Playbook - WSL2-first atomic workflow, fallback routing, and completion evidence gates
- TUI Parity Checklist - Auth dashboard/UI parity requirements for future changes
- Architecture Audit (2026-02-28) - Full security/reliability audit findings and remediation summary
- Audit Artifacts (2026-03-01) - Findings ledger, IA map, naming guide, validation evidence
This plugin bridges OpenCode and the ChatGPT Codex backend with explicit mode controls:
- Request Transform Mode Split -
nativemode (default) preserves OpenCode payload shape;legacymode applies Codex compatibility rewrites. - Stateless Operation - ChatGPT backend requires
store: false, verified via testing. - Full Context Preservation - Sends complete message history and always includes
reasoning.encrypted_content. - Stale-While-Revalidate Caching - Keeps prompt/instruction fetches fast while avoiding GitHub rate limits; optional startup prewarm for first-turn latency.
- Per-Model Configuration - Enables quality presets with quick switching.
- Fast Session Mode - Optional low-latency tuning (clamps reasoning/verbosity on trivial turns) without changing defaults.
- Entitlement-Aware Fallback Flow - Unsupported models try remaining accounts/workspaces first, then optional fallback chain if enabled.
- Beginner Operations Layer - Setup checklist/wizard, guided doctor flow, next-step recommender, and startup preflight summaries.
- Safety-First Account Backup Flow - Timestamped exports, import dry-run previews, and pre-import snapshots before apply when existing accounts are present.
Testing: 1,700+ tests plus integration coverage.