oc-codex-multi-auth: ChatGPT OAuth and multi-account Codex routing for OpenCode

oc-codex-multi-auth is an OpenCode plugin for ChatGPT Plus/Pro OAuth, Codex and GPT-5 model routing, multi-account rotation, account switching, health checks, quota visibility, diagnostics, and recovery tools. It installs the OpenCode provider/TUI configuration, registers a codex-* command toolkit, and routes OpenCode OpenAI SDK requests through the ChatGPT-backed Codex flow with local account state.

Use it when you want OpenCode to run Codex-style coding workflows from your own ChatGPT subscription while keeping accounts visible, switchable, health-checked, and recoverable from the terminal.

What You Get

• OpenCode plugin support for ChatGPT Plus/Pro OAuth and Codex/GPT-5 coding workflows
• Ready-to-use GPT-5.5, GPT-5.5 Fast, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.1, and Codex model templates
• Compact modern OpenCode config with variant-based selectors, plus explicit legacy selector IDs when needed
• Stateless Codex-compatible request handling with store: false and reasoning.encrypted_content
• Multi-account rotation with health-aware selection, cooldowns, automatic token refresh, and failover
• Explicit saved-account listing, account switching, labeling, tagging, notes, health checks, and diagnostics
• Per-project account storage under ~/.opencode/projects/<project-key>/...
• Guided setup, doctor, next-action, dashboard, export/import, keychain, and troubleshooting tools
• Optional OS-native keychain backend for stored account pools
• TUI prompt quota status and quota detail views for OpenCode sessions
• Request logging, runtime metrics, routing visibility, and redacted diagnostic snapshots for debugging
• Stable docs for install, configuration, troubleshooting, privacy, architecture, testing, and release history

Why Developers Use It

oc-codex-multi-auth makes OpenCode's ChatGPT OAuth state understandable and operable. Instead of treating auth as one opaque provider file, you get a local account pool, deterministic account switching, health-aware request selection, visible quota status, JSON-friendly diagnostics, and safe repair commands for stale or damaged state. The plugin is designed for personal development workflows: credentials stay local, OpenCode keeps owning the host runtime, and the plugin only handles the OAuth-backed Codex routing layer it is installed for.

Current Architecture At A Glance

oc-codex-multi-auth ships four user-visible surfaces:

The plugin does not replace OpenCode. OpenCode remains the host; this package installs provider/TUI config and supplies the OAuth-backed Codex request pipeline that OpenCode calls.

Installation

npx -y oc-codex-multi-auth@latest

npx -y oc-codex-multi-auth@latest --full

opencode --version
opencode debug config
opencode auth login

opencode debug config
opencode auth login
opencode run "ping" --model=openai/gpt-5.5 --variant=medium

Quick Start

Install and sign in:

npx -y oc-codex-multi-auth@latest
opencode auth login

Run a prompt with compact modern selectors:

opencode run "Summarize the failing test and suggest a fix" --model=openai/gpt-5.5 --variant=medium
opencode run "Summarize the failing test and suggest a fix" --model=openai/gpt-5.5-fast --variant=medium

Use Codex-focused routing:

opencode run "Refactor the retry logic and update the tests" --model=openai/gpt-5-codex --variant=high

If browser launch is blocked, use the alternate login paths in docs/getting-started.md.

Command Toolkit

Start here

Daily use

Account management

Diagnostics and backup

Reliability behavior

• stateless request handling forces store: false
• reasoning.encrypted_content is preserved for multi-turn continuity
• account rotation is health-aware and avoids repeatedly selecting cooling accounts
• 5xx bursts, network failures, and quota responses penalize account health
• token refresh is queued to avoid refresh races
• unsupported-model handling is strict by default, with opt-in fallback controls
• TUI quota status follows the account/workspace used by the latest request

Storage Paths

Per-project storage is enabled by default. The plugin walks up from the current directory to find a project root, then stores account pools under the project-specific key. If no project root is found, it falls back to global storage.

Configuration

Primary config files:

• ~/.config/opencode/opencode.json
• ~/.config/opencode/tui.json
• ~/.opencode/openai-codex-auth-config.json

Selected runtime/environment overrides:

Validate config after changes:

opencode debug config
opencode run "test" --model=openai/gpt-5.5 --variant=medium

Modern OpenCode versions use config/opencode-modern.json. Older versions can use config/opencode-legacy.json. See config/README.md for the full model template matrix.

Credential Storage

codex-keychain status
codex-keychain migrate
codex-keychain rollback

Troubleshooting

codex-doctor --fix
codex-next
codex-status format="json"

opencode auth login

codex-status format="json"
codex-limits format="json"
codex-health format="json"
codex-next format="json"
codex-list format="json"
codex-dashboard format="json"
codex-metrics format="json"
codex-doctor deep=true format="json"

Documentation

• Docs portal: docs/README.md
• Documentation map: docs/DOCUMENTATION.md
• Getting started: docs/getting-started.md
• Configuration: docs/configuration.md
• Config templates: config/README.md
• Troubleshooting: docs/troubleshooting.md
• FAQ: docs/faq.md
• Privacy: docs/privacy.md
• Public architecture: docs/architecture.md
• Maintainer architecture: docs/development/ARCHITECTURE.md
• Testing: docs/development/TESTING.md
• Discoverability guide: docs/development/GITHUB_DISCOVERABILITY.md
• Audit index: docs/audits/INDEX.md

Release Notes

• Current package version: 6.1.8
• Changelog: CHANGELOG.md
• Releases are automated with release-please

Merging the release-please PR cuts the tagged release and publishes the package through the configured release workflow. Manual npm publish is not required for routine releases.

License

MIT License. See LICENSE.