oc-codex-multi-auth is an OpenCode plugin for ChatGPT Plus/Pro OAuth, Codex and GPT-5/GPT-6 model routing (including GPT-6 Astra, the Daybreak cyber tiers, and 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.

• OpenCode plugin support for ChatGPT Plus/Pro OAuth and Codex/GPT-5 coding workflows
• GPT-6 Astra, GPT-5.6 Sol/Terra/Luna, and the Daybreak Blue/Red cyber tiers on the responses-lite request path, plus GPT-5.5, GPT-5.5 Fast, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.1, and Codex model templates
• Routing for the Daybreak-gated cyber tiers (gpt-daybreak-blue-latest, gpt-daybreak-red-latest, gpt-5.6-cyber), deliberately kept out of the shipped templates since they need program approval
• Compact modern OpenCode config with 13 base families and 59 variant presets; explicit legacy selector IDs when needed
• Stateless Codex-compatible request handling with store: false and reasoning.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:

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.

[!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

Default mode registers the OpenCode and TUI plugin entries without changing provider.openai.

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

Installer flags:

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

Use this when OpenCode does not already provide the OAuth model definitions or you want the shipped variant presets.

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 --full

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

update clears only the OpenCode-managed package cache. It does not read or write opencode.json or tui.json; restart OpenCode afterward to install the current package.

opencode --version
opencode debug config
opencode auth login

The default installer only normalizes the plugin entry in ~/.config/opencode/opencode.json, enables the TUI status plugin in ~/.config/opencode/tui.json, and clears the cached plugin copy. Catalog modes also merge their selected provider.openai definitions. Changed config files are backed up before writing.

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 --json

1. Register the plugin without changing provider.openai:
   • npx -y oc-codex-multi-auth@latest
   • Use --modern only when the shipped compact model catalog is required.
2. Run first login flow:
   • opencode auth login
3. Validate config:
   • opencode debug config
4. Run a smoke request (after OpenCode or --modern supplies the selector):
   • opencode run "Explain this repository" --model=openai/gpt-5.5 --variant=medium
5. Inspect plugin state with the OpenCode tool surface:
   • codex-status
   • codex-doctor
   • codex-list

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

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
opencode run "Plan the refactor" --model=openai/gpt-6-astra --variant=high

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.

Most of these also run as a direct CLI with no agent or model involvement, so there is no token cost. Examples are 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.

• stateless request handling forces store: false
• reasoning.encrypted_content is preserved for multi-turn continuity
• GPT-6 Astra, the Daybreak tiers and the GPT-5.6 tiers use the responses-lite request shape and default client identity opencode; other models default to codex_cli_rs
• account rotation is health-aware (rotationStrategy default hybrid) and avoids repeatedly selecting cooling accounts
• The quota guard checks each enabled account at a bounded interval (30 minutes by default). When it finds a fully spent 5-hour or weekly subscription quota, rotation skips that account until its reported reset instead of drawing from paid Credits. codex-limits applies the same guard immediately when run manually. After running standalone limits, restart an already-running OpenCode instance or wait for its next quota poll to reload the updated account state.
• same-host OpenCode processes sharing an account file serialize refresh-token exchange and commit so one current single-use token is exchanged once
• 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
• Business workspace memberships and Personal accounts keep separate usage and quota windows. Business members sharing one workspace are distinguished by their member/seat identity, so their usage is not collapsed into one row.
• An account identifies itself by its own ChatGPT email and the last 6 characters of its account id, with the email masked when maskEmail is on. The OAuth id_token also lists the API-platform organizations the login belongs to; those are not ChatGPT workspaces and are never used to name an account, so logging in clears a label left behind by one. A label you set with codex-label is always kept.
• The ChatGPT plan (Free, Plus, Pro, Business, Business Premium, Enterprise) is read from the access token, refreshed on every token refresh, and shown by codex-list and codex-status. codex-limits and the TUI read the plan live from the usage endpoint and name it the same way. An unrecognized plan is reported verbatim rather than renamed.

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

Quota notifications are an optional macOS-only feature. Separately, the quota guard checks enabled accounts every 30 minutes by default and prevents rotation from drawing paid Credits after the backend reports a fully spent subscription window. While notifications are enabled, the same poll also alerts through Notification Center when the best remaining 5-hour or weekly pool quota crosses 25%, 10%, or 0%. Alerts are disabled by default; the quota guard is enabled.

Each line reports the enabled account with the most headroom in that window, together with that same account's reset time, so the pair always describes a quota that one account actually has. When a different account recovers sooner, that reset is appended under its own label rather than folded into the first one. Windows a plan has switched off are skipped rather than counted as full. Account identities are omitted for readability and lock-screen privacy:

5h: 10% | resets 02:00 | another account resets 22:30
Weekly: 72% | resets 22:30 on Aug 30

{
  "quotaNotifications": {
    "enabled": true,
    "autoProtectCredits": true,
    "intervalMs": 1800000,
    "notifyEveryCheck": false,
    "thresholds": [25, 10, 0]
  }
}

Add the object above to ~/.opencode/openai-codex-auth-config.json, or set CODEX_AUTH_QUOTA_NOTIFICATIONS=1, then quit and restart OpenCode. The minimum interval is 30 seconds. If macOS blocks the alert, allow notifications for the process shown in System Settings > Notifications. The setting is ignored on Windows and Linux.

Set "notifyEveryCheck": true to show the aggregate quota notification after every successful poll interval instead of only when a configured threshold is crossed. Set "thresholds": [] to turn threshold alerts off entirely; pair it with "notifyEveryCheck": true to keep receiving alerts. The quota guard keeps polling unless "autoProtectCredits": false is set.

Delivery state lives beside the accounts file the alerts are computed from, so OpenCode processes working in the same account scope show only one alert per interval. With the default perProjectAccounts, that scope is one project: two projects have separate account pools and therefore alert independently.

Use modelAccountPools to assign one or more preferred ChatGPT accounts or Business seats to a model. Account references use stable account or Business-seat identities, so adding, removing, or reordering accounts does not silently change a model's routing. A Business membership and a Personal account remain separate pool and usage identities even when they belong to the same login.

{
  "modelAccountPools": {
    "gpt-5.6-sol": [
      "org-example-account-id",
      "00000000-0000-0000-0000-000000000000"
    ],
    "gpt-5.6-terra": [
      "org-another-account-id"
    ]
  },
  "modelAccountPoolModes": {
    "gpt-5.6-sol": "strict",
    "gpt-5.6-terra": "preferred"
  }
}

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="set-mode" model="gpt-5.6-sol" poolMode="strict"
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 defaults to preferred mode and uses healthy, selectable accounts in its pool.
• Existing rotation strategy, quota, cooldown, and token-health rules still apply within the preferred pool.
• In preferred mode, an unavailable pool falls back to the healthy general account pool.
• In strict mode, routing never leaves the configured pool and immediately returns strict_pool_unavailable when no pooled account is selectable.
• An unmapped model or an empty account list uses the general account pool directly.
• codex-status, codex-dashboard, and routing diagnostics also report strict and strict-unavailable modes.

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:

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=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.

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.

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 command="status"
codex-keychain command="migrate"
codex-keychain command="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.

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

If still broken:

opencode auth login

• Plugin does not load: rerun npx -y oc-codex-multi-auth@latest, then restart OpenCode
• Config looks wrong: run opencode debug config and confirm "plugin": ["oc-codex-multi-auth"]
• OAuth callback fails: free port 1455, then rerun opencode auth login
• Browser launch is blocked: use the remote/headless login path from docs/getting-started.md
• Wrong account is selected: run codex-list, then codex-switch
• Account pool looks unhealthy: run codex-health format="json" and codex-doctor deep=true format="json"
• Import/export feels risky: run codex-import path="..." dryRun=true before applying
• Debugging model fallback: enable ENABLE_PLUGIN_REQUEST_LOGGING=1 and inspect ~/.opencode/logs/codex-plugin/

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

• Current published version: see the npm badge above, or run npm view oc-codex-multi-auth version
• 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.

• Not affiliated with OpenAI.
• "ChatGPT", "GPT-5", "Codex", and "OpenAI" are trademarks of OpenAI.
• You assume responsibility for your own usage and compliance.