oc-codex-multi-auth is an OpenCode plugin for ChatGPT Plus/Pro OAuth, Codex and GPT-5 model routing (including GPT-5.6 Sol/Terra/Luna), multi-account rotation, account switching, health checks, quota visibility, diagnostics, and recovery tools. It installs the OpenCode provider/TUI configuration, registers a 24-tool 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
- GPT-5.6 Sol, Terra, and Luna (responses-lite path) plus 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 12 base families and 53 variant presets; explicit legacy selector IDs when needed
- Stateless Codex-compatible request handling with
store: falseandreasoning.encrypted_content - Multi-account rotation with hybrid health scoring, 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. Also runs standalone commands: doctor, status, list, limits, dashboard, health, diag, warm |
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 |
24 codex-* tools |
setup, help, status, list, switch, warm, limits, health, metrics, doctor, dashboard, pool, 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
Default mode writes 12 base OAuth model families and leaves reasoning depth to OpenCode's variant picker.
npx -y oc-codex-multi-auth@latestInstaller flags:
| Flag | Effect |
|---|---|
(default) / --modern |
Compact modern catalog: 12 bases, 53 variants |
--full |
Compact bases plus 53 explicit selector IDs |
--legacy |
Explicit-only catalog for older OpenCode |
--dry-run |
Show actions without writing |
--no-cache-clear |
Skip clearing the OpenCode plugin cache |
Use 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.
oc-codex-multi-auth status
oc-codex-multi-auth list
oc-codex-multi-auth warm
oc-codex-multi-auth doctor
oc-codex-multi-auth health
oc-codex-multi-auth limits
oc-codex-multi-auth dashboard
oc-codex-multi-auth diag
# or: npx -y oc-codex-multi-auth@latest warm --jsonFor 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 (compact modern selectors):
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=medium
opencode run "Plan the refactor" --model=openai/gpt-5.6-sol --variant=highUse 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-warm |
How do I start every account's usage window now (stagger quota cooldowns)? |
codex-status |
Which account, model family, and routing state are active? |
codex-limits |
What quota or rate-limit state is visible now? |
codex-reset |
Do I have a banked rate-limit reset credit, and how do I redeem it? |
codex-dashboard |
Can I manage accounts from one interactive surface? |
codex-pool |
Which accounts are preferred for each model, and how do I change them? |
Most of these also run as a direct CLI with no agent/model involvement (no token cost) — e.g. oc-codex-multi-auth warm, oc-codex-multi-auth status, or npx -y oc-codex-multi-auth@latest warm. Use oc-codex-multi-auth warm to open every enabled account's usage window at the start of a session and stagger the rolling quota cooldowns. Add --json for scriptable output.
| 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- GPT-5.6 tiers use the responses-lite request shape and default client identity
opencode; other models default tocodex_cli_rs - account rotation is health-aware (
rotationStrategydefaulthybrid) 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
Use modelAccountPools to assign one or more preferred ChatGPT accounts to a
model. Account references use stable account IDs, so adding, removing, or
reordering accounts does not silently change a model's routing.
{
"modelAccountPools": {
"gpt-5.6-sol": [
"org-example-account-id",
"00000000-0000-0000-0000-000000000000"
],
"gpt-5.6-terra": [
"org-another-account-id"
]
}
}Save this configuration in ~/.opencode/openai-codex-auth-config.json, then
restart OpenCode. Model matching is case-insensitive and uses the effective
model after request model normalization.
Use codex-pool to manage these mappings with ordinary 1-based account
numbers. The tool resolves those numbers and writes stable IDs to disk:
codex-pool
codex-pool action="set" model="gpt-5.6-sol" accounts=[7,8]
codex-pool action="add" model="gpt-5.6-sol" accounts=[9]
codex-pool action="remove" model="gpt-5.6-sol" accounts=[7]
codex-pool action="clear" model="gpt-5.6-sol"
Add dryRun=true to preview a mutation. Use format="json" for structured
output; stable IDs remain redacted unless includeSensitive=true is also set.
Restart OpenCode after an applied mutation. The plugin configuration is global
while account storage is per-project by default, so a reference unresolved in
the current project is reported but never automatically deleted.
Routing behavior:
- A mapped model uses only healthy, selectable accounts in its preferred pool.
- Existing rotation strategy, quota, cooldown, and token-health rules still apply within the preferred pool.
- If every preferred account is unavailable, disabled, unknown, cooling down, or rate-limited, routing automatically falls back to the healthy general account pool.
- An unmapped model or an empty account list uses the general account pool directly.
codex-status,codex-dashboard, and routing diagnostics report the account-pool mode aspreferred,general, orgeneral-fallback.
Account IDs are local account metadata but should still be treated as private configuration. Do not publish a populated configuration file.
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|ansi16 |
Force terminal color profile |
CODEX_TUI_GLYPHS=ascii|unicode|auto |
Force terminal glyph style |
CODEX_TUI_MASK_EMAIL=0/1 |
Mask account emails across account-display surfaces (list/status/limits/health/dashboard/menus + TUI quota status) |
CODEX_TUI_MASK_EMAIL_DETAILS=0/1 |
Also hide account email in quota details when prompt masking is enabled |
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_ROTATION_STRATEGY=hybrid|sticky|round-robin |
Account selection strategy |
CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=strict|fallback |
Control unsupported-model retry behavior |
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 |
Boolean env overrides are truthy only for the literal string "1".
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.9.1 - 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.