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.
Note
This package is the supported OpenCode plugin line.
Older package names and config entries should be replaced with oc-codex-multi-auth.
- 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: falseandreasoning.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
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.
oc-codex-multi-auth ships four user-visible surfaces:
| Surface | Purpose |
|---|---|
oc-codex-multi-auth |
npm installer bin; updates ~/.config/opencode/opencode.json, manages tui.json, normalizes stale plugin entries, and clears OpenCode plugin cache |
OpenCode plugin entry (index.ts) |
auth loader, OAuth login modes, provider fetch pipeline, account rotation, retry/failover, and codex-* tool registry |
OpenCode TUI plugin (tui.ts) |
prompt quota status, quota details, shared quota cache, and active-account-aware display |
21 codex-* tools |
setup, help, status, list, switch, limits, health, metrics, doctor, dashboard, backup, keychain, diagnostics, and recovery actions |
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.
Terms and Usage Notice
[!CAUTION] This project is for personal development use with your own ChatGPT Plus/Pro subscription.
By using this plugin, you acknowledge:
- This is an independent open-source project, not an official OpenAI product
- It is not intended for commercial resale, shared multi-user access, or production services
- You are responsible for your own usage and policy compliance
- For production/commercial workloads, use the OpenAI Platform API
For Humans
npx -y oc-codex-multi-auth@latestUse this when you want direct selector IDs such as openai/gpt-5.5-medium in addition to OpenCode variants.
npx -y oc-codex-multi-auth@latest --fullopencode --version
opencode debug config
opencode auth loginThe installer updates ~/.config/opencode/opencode.json, backs up the previous config, normalizes the plugin entry to "oc-codex-multi-auth", enables the TUI status plugin in ~/.config/opencode/tui.json, and clears the OpenCode cached plugin copy so OpenCode reinstalls the latest package.
For LLM Agents
- Install or refresh config:
npx -y oc-codex-multi-auth@latest
- Run first login flow:
opencode auth login
- Validate config:
opencode debug config
- Run a smoke request:
opencode run "Explain this repository" --model=openai/gpt-5.5 --variant=medium
- Inspect plugin state with the OpenCode tool surface:
codex-statuscodex-doctorcodex-list
opencode debug config
opencode auth login
opencode run "ping" --model=openai/gpt-5.5 --variant=mediumInstall and sign in:
npx -y oc-codex-multi-auth@latest
opencode auth loginRun 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=mediumUse Codex-focused routing:
opencode run "Refactor the retry logic and update the tests" --model=openai/gpt-5-codex --variant=highIf browser launch is blocked, use the alternate login paths in docs/getting-started.md.
| Tool | What it answers |
|---|---|
codex-setup |
How do I finish first-run setup safely? |
codex-help |
Which plugin commands exist and what do they do? |
codex-doctor |
What is wrong with auth, config, storage, or routing? |
codex-next |
What should I do next to get unstuck? |
| Tool | What it answers |
|---|---|
codex-list |
Which accounts are saved and which one is active? |
codex-switch |
How do I move to a different saved account? |
codex-status |
Which account, model family, and routing state are active? |
codex-limits |
What quota or rate-limit state is visible now? |
codex-dashboard |
Can I manage accounts from one interactive surface? |
| Tool | What it answers |
|---|---|
codex-label |
How do I name an account? |
codex-tag |
How do I group accounts with tags? |
codex-note |
How do I attach a private note to an account? |
codex-remove |
How do I remove a saved account safely? |
codex-refresh |
How do I refresh or re-login an account? |
| Tool | What it answers |
|---|---|
codex-health |
Which accounts look healthy, limited, or disabled? |
codex-metrics |
What runtime counters and request metrics are visible? |
codex-diag |
Can I export a redacted diagnostic snapshot? |
codex-diff |
What changed between account/config snapshots? |
codex-export |
How do I back up account storage? |
codex-import |
How do I restore accounts with a dry-run first? |
codex-keychain |
Which credential backend is active and can I migrate it? |
- stateless request handling forces
store: false reasoning.encrypted_contentis 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
| File | Default path |
|---|---|
| OpenCode config | ~/.config/opencode/opencode.json |
| OpenCode TUI config | ~/.config/opencode/tui.json |
| OpenCode auth tokens | ~/.opencode/auth/openai.json |
| Plugin config | ~/.opencode/openai-codex-auth-config.json |
| Global account storage | ~/.opencode/oc-codex-multi-auth-accounts.json |
| Per-project accounts | ~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json |
| Flagged accounts | ~/.opencode/oc-codex-multi-auth-flagged-accounts.json |
| Backups | ~/.opencode/backups/ or ~/.opencode/projects/<project-key>/backups/ |
| Logs | ~/.opencode/logs/codex-plugin/ |
| TUI quota cache | OpenCode state path plus ~/.opencode/oc-codex-multi-auth-tui-quota.json fallback |
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.
Primary config files:
~/.config/opencode/opencode.json~/.config/opencode/tui.json~/.opencode/openai-codex-auth-config.json
Selected runtime/environment overrides:
| Variable | Effect |
|---|---|
CODEX_AUTH_REQUEST_TRANSFORM_MODE=legacy |
Re-enable legacy Codex request rewriting |
CODEX_MODE=0/1 |
Disable/enable bridge prompt behavior |
CODEX_TUI_V2=0/1 |
Disable/enable codex-style tool output |
| `CODEX_TUI_COLOR_PROFILE=truecolor | ansi256 |
| `CODEX_TUI_GLYPHS=ascii | unicode |
CODEX_AUTH_PER_PROJECT_ACCOUNTS=0/1 |
Disable/enable per-project account pools |
CODEX_AUTH_AUTO_UPDATE=0/1 |
Disable/enable daily npm update check and cache refresh |
| `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=strict | fallback` |
CODEX_AUTH_ACCOUNT_ID=<id> |
Force a specific workspace/account id |
CODEX_AUTH_FETCH_TIMEOUT_MS=<ms> |
Request timeout override |
CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms> |
SSE stream stall timeout override |
ENABLE_PLUGIN_REQUEST_LOGGING=1 |
Enable request metadata logs |
CODEX_PLUGIN_LOG_BODIES=1 |
Include raw request/response bodies in logs; sensitive |
CODEX_KEYCHAIN=1 |
Opt in to OS-native keychain account storage |
Validate config after changes:
opencode debug config
opencode run "test" --model=openai/gpt-5.5 --variant=mediumModern 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.
Default JSON backend
By default, account pools are stored locally as V3 JSON files. File permissions are restricted where the platform supports them.
Use JSON storage when you want predictable, inspectable local files and easy backup/export behavior.
Optional OS keychain backend
Set CODEX_KEYCHAIN=1 to store account pools in the OS keychain instead:
- macOS: Keychain
- Windows: Credential Manager
- Linux: libsecret, with a running secret service such as GNOME Keyring or KWallet
Manage the backend from OpenCode:
codex-keychain status
codex-keychain migrate
codex-keychain rollback
If the keychain is unavailable, the plugin logs a warning and falls back to JSON storage for that operation. Credentials are never silently deleted.
60-second recovery
codex-doctor --fix
codex-next
codex-status format="json"
If still broken:
opencode auth loginCommon symptoms
- Plugin does not load: rerun
npx -y oc-codex-multi-auth@latest, then restart OpenCode - Config looks wrong: run
opencode debug configand confirm"plugin": ["oc-codex-multi-auth"] - OAuth callback fails: free port
1455, then rerunopencode auth login - Browser launch is blocked: use the remote/headless login path from docs/getting-started.md
- Wrong account is selected: run
codex-list, thencodex-switch - Account pool looks unhealthy: run
codex-health format="json"andcodex-doctor deep=true format="json" - Import/export feels risky: run
codex-import path="..." dryRun=truebefore applying - Debugging model fallback: enable
ENABLE_PLUGIN_REQUEST_LOGGING=1and inspect~/.opencode/logs/codex-plugin/
Diagnostics pack
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"
- 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
- 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.
MIT License. See LICENSE.
Legal
- Not affiliated with OpenAI.
- "ChatGPT", "GPT-5", "Codex", and "OpenAI" are trademarks of OpenAI.
- You assume responsibility for your own usage and compliance.