@solly922/opencode-codex-multiauth

@solly922/opencode-codex-multiauth is an OpenCode plugin that lets you use multiple ChatGPT OAuth accounts with the ChatGPT Codex backend and rotate between them automatically.

Credits

This project builds on work from:

• guard22-multiauth: https://github.com/guard22/opencode-multi-auth-codex
• crim50n-multiauth: https://github.com/crim50n/opencode-multi-auth-codex

Why use it

• Rotate across multiple ChatGPT OAuth accounts
• Keep using the ChatGPT Codex backend with Codex-style headers and request mapping
• Add accounts through browser OAuth or headless device auth
• Manage accounts from a localhost dashboard
• Pin traffic to a single account with force mode
• Track rate limits, cooldowns, invalid auth, and unsupported models
• Use weighted or health-based rotation strategies
• Sync with Codex auth.json

Features

• Multi-account account store with migration support
• Browser OAuth and headless device auth
• ChatGPT Codex backend forwarding
• Local dashboard for account management and runtime settings
• Rotation strategies:
  • round-robin
  • least-used
  • random
  • weighted-round-robin
• Force mode
• Rate-limit probing and cooldown handling
• Proxy-aware auth and backend networking
• Cross-process store locking

Requirements

• Node.js 20+
• npm
• OpenCode
• One or more ChatGPT accounts with Codex access

Quick Start

1. Install the package.
2. Point OpenCode at the installed plugin entry.
3. Add one or more ChatGPT accounts.
4. Start using OpenCode with the openai provider.

Install

1. Install from npm

npm install -g @solly922/opencode-codex-multiauth

Then point OpenCode at the installed plugin entry.

Run this to get your global node_modules directory:

npm root -g

Then use this file URL in OpenCode:

file://<npm-root>/@solly922/opencode-codex-multiauth/dist/index.js

Example:

file:///Users/you/.npm-global/lib/node_modules/@solly922/opencode-codex-multiauth/dist/index.js

2. Add the plugin to OpenCode

Edit ~/.config/opencode/opencode.json:

{
  "plugin": [
    "file:///absolute/path/to/@solly922/opencode-codex-multiauth/dist/index.js"
  ]
}

Restart OpenCode after updating the config.

Option: Clone and build locally

git clone https://github.com/solly922/opencode-codex-multiauth.git codex-multiauth
cd codex-multiauth
npm ci
npm run build

Then use the built entry at file:///absolute/path/to/codex-multiauth/dist/index.js in the same OpenCode config shown above.

Add accounts

You can add accounts from either the OpenCode UI or the CLI.

OpenCode UI

1. Open auth/provider settings for openai
2. Select ChatGPT OAuth (Multi-Account)
3. Enter an alias such as personal, work, or backup
4. Complete the browser login flow

Headless option:

• ChatGPT OAuth (Headless, Multi-Account) uses a device-style auth flow instead of opening a callback browser flow.

CLI

Primary CLI name:

codex-multiauth add personal
codex-multiauth add work --headless
codex-multiauth list
codex-multiauth status
codex-multiauth remove backup
codex-multiauth path

Compatibility alias:

opencode-multi-auth status

Start the dashboard

codex-multiauth web --host 127.0.0.1 --port 3434

Open http://127.0.0.1:3434 in your browser.

The dashboard is loopback-only and includes:

• account list and health state
• active account display
• enable/disable toggles
• force mode controls
• re-auth actions
• runtime settings updates
• rate-limit refresh/probing
• sync status

Use it in OpenCode

Once the plugin is loaded and you have accounts configured:

1. Use the openai provider in OpenCode
2. Choose a Codex-compatible model
3. Send requests normally

The plugin will:

• select an eligible account
• attach Codex-style headers such as chatgpt-account-id, OpenAI-Beta, and originator
• forward the request to https://chatgpt.com/backend-api
• rotate away from invalid, rate-limited, or temporarily unsupported accounts

Default paths

• Account store: ~/.config/opencode/codex-multiauth-accounts.json
• Codex auth file: ~/.codex/auth.json
• Logs: ~/.config/opencode/codex-multiauth/logs/codex-multiauth.log

Useful environment variables

• OPENCODE_MULTI_AUTH_STORE_FILE: override the account store path
• OPENCODE_MULTI_AUTH_CODEX_AUTH_FILE: override the Codex auth file path
• CODEX_MULTIAUTH_LOG_PATH: override the log file path
• OPENCODE_MULTI_AUTH_PROXY_URL: force a proxy for auth/backend traffic
• HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY: standard proxy environment variables
• OPENCODE_MULTI_AUTH_SYNC_OPENCODE_AUTH=1: import OpenCode's current openai OAuth session into the plugin account pool
• OPENCODE_MULTI_AUTH_MODEL_INJECTION=auto|latest|default|opencode: control whether the plugin preserves OpenCode's model list, injects only the latest model, or injects the full plugin model set
• OPENCODE_MULTI_AUTH_INJECT_MODELS=0: disable runtime model injection
• OPENCODE_MULTI_AUTH_STRIP_ITEM_REFERENCES=0: stop stripping item_reference inputs before forwarding
• OPENCODE_MULTI_AUTH_PREFER_CODEX_LATEST=1: map older Codex selections to the configured latest model

Behavior notes

• Force mode pins traffic to one alias until cleared or expired.
• Dashboard settings affect runtime rotation behavior.
• Forwarded requests keep store: false.
• Browser auth and backend traffic are proxy-aware.
• OpenCode auth-session syncing is disabled by default; enable it only if you want the plugin to import your current OpenCode openai login automatically.
• Model injection defaults to auto: preserve OpenCode's existing OpenAI model list when it already exists, otherwise seed the provider with the plugin's default Codex-compatible models.
• The merged implementation preserves the ChatGPT Codex backend forwarding behavior that made the earlier crim50n fork reliable in practice.

Troubleshooting

The plugin does not load

• Make sure npm run build succeeded
• Verify the plugin entry points to dist/index.js
• Restart OpenCode after editing opencode.json

No accounts are available

codex-multiauth status
codex-multiauth list

Then check whether the accounts are disabled, rate-limited, auth-invalid, or currently pinned by force mode.

Browser OAuth does not complete

• Make sure your machine can accept loopback callbacks on 127.0.0.1
• Retry with --headless
• Check whether your proxy settings are interfering with auth traffic

Dashboard writes fail

• Use the dashboard from the same local origin it was started on
• Mutating endpoints are same-origin protected and loopback-only by design

Migrating from older builds

• The canonical log path is now ~/.config/opencode/codex-multiauth/logs/codex-multiauth.log
• The canonical systemd user service name is now codex-multiauth.service
• The old CODEX_SOFT_LOG_PATH env var is still accepted as a fallback

Development

npm run build
npm run lint
npm run test:unit
npm run test:integration
npm run test:web:headless
npm run test:sandbox

Additional docs

• OPENCODE_SETUP_1TO1.md
• codextesting.md
• docs/