Skip to content
Back to search

oc-codex-multi-auth

OpenCode plugin for ChatGPT Plus/Pro OAuth with Codex/GPT-5 routing, multi-account rotation, account switching, health checks, diagnostics, and recovery tools

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ndycode/oc-codex-multi-auth with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ndycode/oc-codex-multi-auth'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ndycode--oc-codex-multi-auth/badge.svg)](/listings/ndycode--oc-codex-multi-auth)

HTML

<a href="/listings/ndycode--oc-codex-multi-auth"><img src="/api/listings/ndycode--oc-codex-multi-auth/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js `>=22.19` and [OpenCode](https://opencode.ai).

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

> [!NOTE] > The former package name `oc-chatgpt-multi-auth` is retired. Install `oc-codex-multi-auth` for all new setups; see [docs/faq.md](docs/faq.md) for the rename details.

With no flag, the installer only registers the plugin: it adds the plugin entry to `~/.config/opencode/opencode.json`, enables the TUI quota plugin in `~/.config/opencode/tui.json`, and refreshes the cached package. Your existing `provider.openai` model config is left alone. Add a flag to also install a model catalog:

| Flag | Effect | | --- | --- | | (none) / `--plugin-only` | Register the plugin entries only | | `--modern` | Also install the compact catalog: 11 base models with 59 variants | | `--full` | Also install the compact bases plus 59 explicit selector IDs (`openai/gpt-5.5-medium`) | | `--legacy` | Install the explicit-only catalog (59 entries) for older OpenCode | | `--v2` | Register for OpenCode V2 instead (plugin only; see below) | | `--dry-run` | Show what would change without writing | | `--no-cache-clear` | Skip clearing the OpenCode plugin cache | | `--version` | Print the installed version |

Both `opencode.json` and `opencode.jsonc` are supported, comments and trailing commas included. Changed files are backed up first, and the installer refuses to overwrite a config it cannot parse.

To update later without touching either config file:

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

Removal is manual — see [Uninstall / disable](docs/getting-started.md#uninstall--disable).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 248 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # oc-codex-multi-auth
  2. [![npm version](https://img.shields.io/npm/v/oc-codex-multi-auth.svg)](https://www.npmjs.com/package/oc-codex-multi-auth)
  3. [![npm downloads](https://img.shields.io/npm/dw/oc-codex-multi-auth.svg)](https://www.npmjs.com/package/oc-codex-multi-auth)
  4. [![CI](https://github.com/ndycode/oc-codex-multi-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/oc-codex-multi-auth/actions/workflows/ci.yml)
  5. [![MIT license](https://img.shields.io/npm/l/oc-codex-multi-auth.svg)](LICENSE)
  6. <img width="1227" height="702" alt="oc-codex-multi-auth OpenAI accounts picker in OpenCode — add accounts, check quotas, and per-account health" src="https://github.com/user-attachments/assets/b796eb2f-282e-468a-ba6a-acadf09d731b" />
  7. `oc-codex-multi-auth` is an OpenCode plugin that runs Codex-style GPT models on your ChatGPT Plus/Pro subscription over OAuth. It keeps a named pool of ChatGPT accounts on your machine, rotates across them per request with health- and quota-aware selection, shows quota in the TUI prompt line, and ships a 24-tool `codex-*` command kit plus a standalone CLI. Account state stays local under `~/.opencode`.
  8. Use it when one ChatGPT account is not enough: you hit rate limits or quota windows, you split work across accounts and projects, or you run unattended agents that need JSON diagnostics and safe repair commands instead of one opaque auth file.
  9. Using the official Codex CLI rather than OpenCode? The sibling project [`codex-multi-auth`](https://github.com/ndycode/codex-multi-auth) manages the same kind of account pool for `codex` itself.
  10. ## What it does
  11. - **Account pool** — OAuth login for multiple ChatGPT accounts, stored locally under `~/.opencode`, with a shared global pool by default; set `CODEX_AUTH_PER_PROJECT_ACCOUNTS=1` to opt into per-project pools under `projects/<project-key>/`.
  12. - **Rotation** — health-scored hybrid selection picks the best enabled account per request, with cooldowns, automatic token refresh, and failover on rate limits.
  13. - **Model catalog** — 14 base models covering 77 variants: GPT-6.1 Sol/Terra, GPT-6 Astra/Sol/Luna, the GPT-5.6 tiers, GPT-5.5, and more, routed through the stateless Codex contract (`store: false` + `reasoning.encrypted_content`).
  14. - **Quota in the prompt** — the TUI prompt line shows remaining quota for the serving account, the whole pool, or banked reset credits, with rotating screens.
  15. - **`codex-*` tools** — 24 in-session tools for switching, labeling, tagging, limits, diagnostics, and repair.
  16. - **Standalone CLI** — the same package runs `status`, `list`, `limits`, `doctor`, and friends directly — no agent, no token cost.
  17. - **OpenCode V2** — OpenCode 2.0.16+ loads the plugin through a V2 adapter that shares the account pool and request pipeline.
  18. - **Keychain option** — `CODEX_KEYCHAIN=1` stores the pool in macOS Keychain, Windows Credential Manager, or Linux libsecret.
  19. ## Install
  20. Requires Node.js `>=22.19` and [OpenCode](https://opencode.ai).
  21. ```bash
  22. npx -y oc-codex-multi-auth@latest
  23. ```
  24. > [!NOTE]
  25. > The former package name `oc-chatgpt-multi-auth` is retired. Install `oc-codex-multi-auth` for all new setups; see [docs/faq.md](docs/faq.md) for the rename details.
  26. With no flag, the installer only registers the plugin: it adds the plugin entry to `~/.config/opencode/opencode.json`, enables the TUI quota plugin in `~/.config/opencode/tui.json`, and refreshes the cached package. Your existing `provider.openai` model config is left alone. Add a flag to also install a model catalog:
  27. | Flag | Effect |
  28. | --- | --- |
  29. | (none) / `--plugin-only` | Register the plugin entries only |
  30. | `--modern` | Also install the compact catalog: 14 base models with 77 variants |
  31. | `--full` | Also install the compact bases plus 77 explicit selector IDs (`openai/gpt-5.5-medium`) |
  32. | `--legacy` | Install the explicit-only catalog (77 entries) for older OpenCode |
  33. | `--v2` | Register for OpenCode V2 instead (plugin only; see below) |
  34. | `--dry-run` | Show what would change without writing |
  35. | `--no-cache-clear` | Skip clearing the OpenCode plugin cache |
  36. | `--version` | Print the installed version |
  37. Both `opencode.json` and `opencode.jsonc` are supported, comments and trailing commas included. Changed files are backed up first, and the installer refuses to overwrite a config it cannot parse.
  38. To update later without touching either config file:
  39. ```bash
  40. npx -y oc-codex-multi-auth@latest update
  41. ```
  42. Removal is manual — see [Uninstall / disable](docs/getting-started.md#uninstall--disable).
  43. ## Quick start (5 minutes)
  44. ```bash
  45. # 1. Sign in a ChatGPT account (browser OAuth, loopback callback on localhost:1455)
  46. opencode auth login # choose OpenAI, then a Codex OAuth method
  47. # 2. Repeat login per account, then inspect the pool
  48. oc-codex-multi-auth status
  49. oc-codex-multi-auth limits
  50. # 3. Diagnose anything off
  51. oc-codex-multi-auth doctor
  52. # 4. Run a first prompt (catalog installs only)
  53. opencode run "Explain this repository" --model=openai/gpt-5.5 --variant=medium
  54. ```
  55. Headless or remote shell? Four OAuth methods are available (browser, open URL manually, device code, manual URL paste) — see [Getting Started](docs/getting-started.md).
  56. ## OpenCode V2
  57. OpenCode **2.0.16+** loads the plugin through a V2 adapter; the account pool, OAuth login, and request pipeline are shared with V1.
  58. The V2 plugin service does not open a browser. Interactive `opencode auth login` opens the authorization URL; in the TUI, press `o` or open the displayed URL yourself. If the client and service run on different machines, forward the service's callback port 1455 or choose **Device Code** or **Manual URL Paste** before starting login. See [remote login](docs/getting-started.md#remote-or-headless-login).
  59. ```bash
  60. npx -y oc-codex-multi-auth@latest --v2
  61. opencode service restart
  62. opencode auth login # OpenAI -> Codex OAuth (Add account — ChatGPT Plus/Pro)
  63. ```
  64. `--v2` writes a `plugins` entry only — no model catalog — and refuses an existing `opencode.jsonc` or V1 `plugin` entries rather than migrating them (edit the JSONC `plugins` list by hand instead). In V2, tool names normalize to `codex_list`, `codex_switch`, and so on; `/codex-accounts` and the **Codex accounts** palette command list the pool, and **Codex quota details** shows quota. V1's entrypoint remains for OpenCode 1.18.29+. See [Troubleshooting](docs/troubleshooting.md) for V2-specific issues.
  65. ### Subscription image generation
  66. On OpenCode 2.2.7+ hosts with the native `@opencode/ai/providers/openai/images` driver,
  67. select a **Codex OAuth** connection under
  68. OpenAI and request `openai/gpt-image-2`. The plugin routes generation and edits
  69. to Codex's subscription endpoint. Images use the host's selected OpenAI account
  70. and its token refresh; they do not rotate through the chat account pool.
  71. Only `gpt-image-2` is enabled on this subscription route. Other image models are
  72. hidden rather than silently replaced. API-key connections retain the standard
  73. image API route and separate API billing. The newer **Sign in with ChatGPT**
  74. token-sharing flow is separate and currently excludes image generation.
  75. Image requests retain the native provider (including JSON image edits), not
  76. the plugin's language-model bridge. A subscription image request should use
  77. `https://chatgpt.com/backend-api/codex`, not `https://api.openai.com/v1`.
  78. Account and workspace permissions still apply; a rejection is not retried with
  79. another account or billing route.
  80. References: [Codex image generation](https://developers.openai.com/codex/image-generation),
  81. [token-sharing limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations).
  82. ## Command map
  83. Two surfaces: **25 `codex-*` tools** inside an OpenCode session, and a standalone CLI for everything else. The full argument reference is in [docs/tools-and-cli.md](docs/tools-and-cli.md).
  84. | Group | Tools | Purpose |
  85. | --- | --- | --- |
  86. | Setup | `codex-setup`, `codex-help`, `codex-next` | guided first-run checklist, help by topic, suggested next action |
  87. | Accounts | `codex-status`, `codex-list`, `codex-switch`, `codex-enable`, `codex-remove` | inspect the pool, pin or switch the active account, re-enable or drop entries |
  88. | Identity | `codex-label`, `codex-tag`, `codex-note` | name accounts, group them with tags, attach private notes |
  89. | Quota | `codex-limits`, `codex-warm`, `codex-reset` | per-account and pool quota, open usage windows, banked reset credits |
  90. | Health | `codex-health`, `codex-doctor`, `codex-diag`, `codex-dashboard`, `codex-metrics`, `codex-refresh` | health view, diagnostics plus safe repairs, redacted snapshots, counters |
  91. | Routing | `codex-pool` | pin models to preferred accounts |
  92. | Backup | `codex-export` / `codex-import`, `codex-diff`, `codex-keychain` | export/restore storage (import previews with `dryRun=true`), compare snapshots, manage the credential backend |
  93. Everyday standalone commands:
  94. ```bash
  95. oc-codex-multi-auth status # pool summary + storagePath
  96. oc-codex-multi-auth list # accounts, --tag <name> to filter
  97. oc-codex-multi-auth limits # 5h/weekly usage; --sort account|usage|reset --asc|--desc --refresh
  98. oc-codex-multi-auth warm # open every enabled account's usage window
  99. oc-codex-multi-auth doctor # diagnostics; --deep, --fix
  100. oc-codex-multi-auth diag # alias for doctor --deep
  101. oc-codex-multi-auth health # local token/account health
  102. oc-codex-multi-auth dashboard # dashboard guidance
  103. ```
  104. These accept `--json` and `--config-path <file>` (`install`/`update` reject `--config-path`); `status`/`list`/`limits` redact identifiers unless `--include-sensitive` is passed. Via npx: `npx -y oc-codex-multi-auth@latest status --json`.
  105. ## Rotation, in one paragraph
  106. Each request picks the healthiest enabled account (`rotationStrategy`, default `hybrid`): health scores drop on failures and rate limits, cooldowns keep a burned account out of the running, tokens refresh as needed, and failover walks the pool within a bounded retry budget. Logging into the same account again updates its entry rather than duplicating it. The shared global pool is the default. Set `CODEX_AUTH_PER_PROJECT_ACCOUNTS=1` to opt into per-project pools; the plugin then walks up from the working directory looking for a project marker (`.git`, `package.json`, `.opencode`, and friends), stopping at your home directory. Without that opt-in, it uses `~/.opencode/oc-codex-multi-auth-accounts.json`.
  107. Accounts whose plan quota is used up are left alone until it resets, even when they hold Codex credits. Set `spendCredits: true` to spend those credits once no account has plan quota left; a toast names the account and its remaining balance. See [Spending Codex credits](docs/configuration.md#spending-codex-credits).
  108. ## Models
  109. `--modern` and `--full` install **14 base models** covering **77 variants** (selectable via `--variant`); `--legacy` installs the 77 as explicit IDs.
  110. | Base | Notes |
  111. | --- | --- |
  112. | `gpt-6.1-sol` | newest workhorse; the OpenAI Codex catalog's default since 2026-09-29 |
  113. | `gpt-6.1-terra` | distinct model with low, medium, high, xhigh, max, and ultra efforts; default low |
  114. | `gpt-6.2-astra` | GPT-6.2 frontier model released 2026-11-17; low through max plus the client-side ultra tier |
  115. | `gpt-6.2-sol` | GPT-6.2 everyday-work model released 2026-11-17; low through max plus the client-side ultra tier |
  116. | `gpt-6-astra` | frontier; rolled out 2026-09-03 |
  117. | `gpt-6-sol` | workhorse coding model |
  118. | `gpt-6-luna` | fast, affordable |
  119. | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | GPT-5.6 tiers; entitlement-gated |
  120. | `gpt-5.5`, `gpt-5.5-fast` | retires from Codex 2026-10-14 |
  121. | `gpt-5.4-nano` | |
  122. | `gpt-5.1` | |
  123. GPT-6 and GPT-5.6 models use the responses-lite request shape and the `opencode` client identity; other models use `codex_cli_rs`. Requests stay stateless: `store: false` with `reasoning.encrypted_content` for multi-turn continuity.
  124. Retired IDs still route if typed — `gpt-5.4-mini`, `gpt-5-codex`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, and `gpt-5.1-codex-mini` are rescued by the default fallback chains. The Daybreak-gated tiers (`gpt-daybreak-blue-latest`, `gpt-daybreak-red-latest`, `gpt-5.6-cyber`) are routed but deliberately not shipped; add them by hand if your workspace is approved. Full chain details live in [docs/configuration.md](docs/configuration.md).
  125. ## Quota status
  126. The TUI prompt line shows quota for the account that served the current session's last request (OpenCode V2: the last request overall). `quotaStatus.mode` in `~/.opencode/openai-codex-auth-config.json` controls it:
  127. - `active` (default): the serving account's remaining quota
  128. - `overview`: the whole pool on one line, weighted by plan
  129. - `resets`: banked rate-limit reset credits
  130. - `credits`: accounts that still hold Codex credits once plan quota is gone
  131. Pass a list (`["overview", "resets"]`) to rotate screens every `rotateMs` (default 5s). Percentages read as headroom left; set `quotaDisplay: "used"` to show consumption. All layout and forecast options are documented in [docs/configuration.md](docs/configuration.md).
  132. ## Where state lives
  133. | File | Path |
  134. | --- | --- |
  135. | Per-project accounts | `~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json` |
  136. | Global accounts | `~/.opencode/oc-codex-multi-auth-accounts.json` |
  137. | Flagged accounts | `oc-codex-multi-auth-flagged-accounts.json`, beside the active accounts file |
  138. | Pre-write snapshots | `backups/codex-credential-snapshot-*.json`, beside the active accounts file |
  139. | Plugin config | `~/.opencode/openai-codex-auth-config.json` |
  140. | OpenCode config | `~/.config/opencode/opencode.json` (or `opencode.jsonc`) |
  141. | Request logs | `~/.opencode/logs/codex-plugin/`, when logging is enabled |
  142. Plugin settings are re-read per request — most edits need no restart. Boolean env overrides are truthy only for the literal `"1"`. Common ones:
  143. | Setting | Effect |
  144. | --- | --- |
  145. | `CODEX_AUTH_PER_PROJECT_ACCOUNTS=1` | Opt into per-project account pools |
  146. | `CODEX_KEYCHAIN=1` | Store accounts in the OS keychain |
  147. | `CODEX_AUTH_ROTATION_STRATEGY=hybrid\|sticky\|round-robin\|custom` | Account selection strategy |
  148. | `CODEX_AUTH_SPEND_CREDITS=1` | Spend Codex credits once no account has plan quota left |
  149. | `CODEX_AUTH_QUOTA_DISPLAY=free\|used` | Quota percentages as headroom (default) or consumption |
  150. | `CODEX_RETRY_ALL_UNBOUNDED=1` | Let "wait as long as the backend asks" apply when every account is rate-limited; otherwise capped at 10 minutes |
  151. | `ENABLE_PLUGIN_REQUEST_LOGGING=1` | Write request metadata logs |
  152. | `CODEX_PLUGIN_LOG_BODIES=1` | Also log raw bodies (sensitive) |
  153. Full reference, field by field: [docs/configuration.md](docs/configuration.md).
  154. For trusted JavaScript policies and offline validation, see [Custom account rotation](docs/custom-rotation.md).
  155. ## Troubleshooting in 60 seconds
  156. ```bash
  157. oc-codex-multi-auth doctor --fix
  158. opencode auth login
  159. ```
  160. Most issues resolve by signing in again or running `codex-doctor fix=true` inside a session. The callback listener needs port 1455 free. Symptom-by-symptom fixes: [docs/troubleshooting.md](docs/troubleshooting.md); common questions: [docs/faq.md](docs/faq.md).
  161. ## Documentation
  162. | Doc | What it covers |
  163. | --- | --- |
  164. | [docs/index.md](docs/index.md) | Product overview — what it does at runtime and who needs it |
  165. | [docs/README.md](docs/README.md) | Documentation portal and page inventory |
  166. | [docs/getting-started.md](docs/getting-started.md) | Install, login methods, first prompt, uninstall |
  167. | [docs/tools-and-cli.md](docs/tools-and-cli.md) | Full tool/CLI argument reference |
  168. | [docs/configuration.md](docs/configuration.md) | Every config key and env var |
  169. | [docs/upgrade.md](docs/upgrade.md) | Upgrades, package renames, storage migration |
  170. | [docs/architecture.md](docs/architecture.md) | How the pieces fit |
  171. | [docs/troubleshooting.md](docs/troubleshooting.md) / [docs/faq.md](docs/faq.md) | Recovery playbooks and common questions |
  172. | [docs/privacy.md](docs/privacy.md) | What is stored and where |
  173. | [config/README.md](config/README.md) | Modern vs. legacy catalog templates |
  174. | [CHANGELOG.md](CHANGELOG.md) | Release history |
  175. | [docs/development/](docs/development/ARCHITECTURE.md) | Maintainer docs |
  176. ## Release notes
  177. - Current stable: [v6.33.0](CHANGELOG.md) — `npx -y oc-codex-multi-auth@latest`
  178. - Full release archive: [CHANGELOG.md](CHANGELOG.md)
  179. ## Terms and license
  180. `oc-codex-multi-auth` uses OAuth account credentials and is intended for personal development use with your own ChatGPT Plus/Pro subscription. It is an independent open-source project, not an official OpenAI product; for production or commercial workloads, use the OpenAI Platform API. "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
  181. MIT license — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.