{"id":42324235,"url":"https://github.com/ndycode/oc-chatgpt-multi-auth","last_synced_at":"2026-03-08T05:01:53.960Z","repository":{"id":334200893,"uuid":"1128282387","full_name":"ndycode/oc-chatgpt-multi-auth","owner":"ndycode","description":"Multi-account ChatGPT OAuth plugin for OpenCode — GPT-5.3/5.2 Codex with health-aware rotation, auto-failover, and session recovery","archived":false,"fork":false,"pushed_at":"2026-03-06T04:18:07.000Z","size":2083,"stargazers_count":38,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-06T04:55:22.674Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/oc-chatgpt-multi-auth","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ndycode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-05T12:06:53.000Z","updated_at":"2026-03-06T00:25:39.000Z","dependencies_parsed_at":"2026-02-22T10:00:33.335Z","dependency_job_id":null,"html_url":"https://github.com/ndycode/oc-chatgpt-multi-auth","commit_stats":null,"previous_names":["ndycode/opencode-openai-codex-auth-multi","ndycode/opencode-chatgpt-multi-auth"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/ndycode/oc-chatgpt-multi-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndycode%2Foc-chatgpt-multi-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndycode%2Foc-chatgpt-multi-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndycode%2Foc-chatgpt-multi-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndycode%2Foc-chatgpt-multi-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ndycode","download_url":"https://codeload.github.com/ndycode/oc-chatgpt-multi-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndycode%2Foc-chatgpt-multi-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30243735,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-27T13:02:42.311Z","updated_at":"2026-03-08T05:01:53.916Z","avatar_url":"https://github.com/ndycode.png","language":"TypeScript","readme":"# OpenAI Codex Auth Plugin for OpenCode\n\n[![npm version](https://img.shields.io/npm/v/oc-chatgpt-multi-auth.svg)](https://www.npmjs.com/package/oc-chatgpt-multi-auth)\n[![npm downloads](https://img.shields.io/npm/dw/oc-chatgpt-multi-auth.svg)](https://www.npmjs.com/package/oc-chatgpt-multi-auth)\n\nOAuth plugin for OpenCode that lets you use ChatGPT Plus/Pro rate limits with models like `gpt-5.4`, `gpt-5-codex`, and `gpt-5.1-codex-max` (plus optional/manual `gpt-5.4-pro`, entitlement-gated Spark IDs, and legacy Codex aliases).\n\n\u003e [!NOTE]\n\u003e **Renamed from `opencode-openai-codex-auth-multi`** — If you were using the old package, update your config to use `oc-chatgpt-multi-auth` instead. The rename was necessary because OpenCode blocks plugins containing `opencode-openai-codex-auth` in the name.\n\n## What You Get\n\n- **GPT-5.4, GPT-5 Codex, GPT-5.1 Codex Max** and all GPT-5.x variants via ChatGPT OAuth\n- **Multi-account support** — Add up to 20 ChatGPT accounts, health-aware rotation with automatic failover\n- **Per-project accounts** — Each project gets its own account storage (new in v4.10.0)\n- **Workspace-aware identity persistence** — Keeps workspace/org identity stable across token refresh and verify-flagged restore flows\n- **Click-to-switch** — Switch accounts directly from the OpenCode TUI\n- **Beginner command toolkit** — Guided onboarding with `codex-help`, `codex-setup`, `codex-doctor`, and `codex-next`\n- **Account metadata controls** — Per-account labels, tags, and notes with quick filtering\n- **Safer backup/import flow** — Timestamped exports, import dry-run preview, and conditional pre-import backups when existing accounts are present\n- **Startup preflight summary** — One-line health/readiness summary at plugin startup with suggested next step\n- **Strict tool validation** — Automatically cleans schemas for compatibility with strict models\n- **Auto-update notifications** — Get notified when a new version is available\n- **21 template model presets** — Full variant system with reasoning levels (none/low/medium/high/xhigh)\n- **Prompt caching** — Session-based caching for faster multi-turn conversations\n- **Usage-aware errors** — Friendly messages with rate limit reset timing\n- **Plugin compatible** — Works alongside other OpenCode plugins (oh-my-opencode, dcp, etc.)\n\n---\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eTerms of Service Warning — Read Before Installing\u003c/b\u003e\u003c/summary\u003e\n\n\u003e [!CAUTION]\n\u003e This plugin uses OpenAI's official OAuth authentication (the same method as OpenAI's official Codex CLI) for personal development use with your ChatGPT Plus/Pro subscription.\n\u003e\n\u003e **This plugin is for personal development only:**\n\u003e - Not for commercial services, API resale, or multi-user applications\n\u003e - For production use, see [OpenAI Platform API](https://platform.openai.com/)\n\u003e\n\u003e **By using this plugin, you acknowledge:**\n\u003e - This is an unofficial tool not endorsed by OpenAI\n\u003e - Users are responsible for compliance with [OpenAI's Terms of Use](https://openai.com/policies/terms-of-use/)\n\u003e - You assume all risks associated with using this plugin\n\n\u003c/details\u003e\n\n---\n\n## Installation\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eFor Humans\u003c/b\u003e\u003c/summary\u003e\n\n**Option A: Let an LLM do it**\n\nPaste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):\n\n```\nInstall the oc-chatgpt-multi-auth plugin and add the OpenAI model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/ndycode/oc-chatgpt-multi-auth/main/README.md\n```\n\n**Option B: One-command install**\n\n```bash\nnpx -y oc-chatgpt-multi-auth@latest\n```\n\nThis writes the config to `~/.config/opencode/opencode.json`, backs up existing config, and clears the plugin cache.\n\n\u003e Want legacy config (OpenCode v1.0.209 and below)? Add `--legacy` flag.\n\n**Option C: Manual setup**\n\n1. **Add the plugin** to `~/.config/opencode/opencode.json`:\n\n   ```json\n   {\n     \"plugin\": [\"oc-chatgpt-multi-auth@latest\"]\n   }\n   ```\n\n2. **Login** with your ChatGPT account:\n\n   ```bash\n   opencode auth login\n   ```\n\n3. **Add models** — Copy the [full configuration](#models) below\n\n4. **Use it:**\n\n   ```bash\n   opencode run \"Hello\" --model=openai/gpt-5.4 --variant=medium\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFor LLM Agents\u003c/b\u003e\u003c/summary\u003e\n\n### Step-by-Step Instructions\n\n1. Edit the OpenCode configuration file at `~/.config/opencode/opencode.json`\n   \n   \u003e **Note**: This path works on all platforms. On Windows, `~` resolves to your user home directory (e.g., `C:\\Users\\YourName`).\n\n2. Add the plugin to the `plugin` array:\n   ```json\n   {\n     \"plugin\": [\"oc-chatgpt-multi-auth@latest\"]\n   }\n   ```\n\n3. Add the model definitions from the [Full Models Configuration](#full-models-configuration-copy-paste-ready) section\n\n4. Set `provider` to `\"openai\"` and choose a model\n\n### Verification\n\n```bash\nopencode run \"Hello\" --model=openai/gpt-5.4 --variant=medium\n```\n\n\u003c/details\u003e\n\n---\n\n## Models\n\n### Model Reference\n\n| Model | Variants | Notes |\n|-------|----------|-------|\n| `gpt-5.4` | none, low, medium, high, xhigh | Latest GPT-5.4 with reasoning levels |\n| `gpt-5.4-pro` | low, medium, high, xhigh | Optional manual model for deeper reasoning; fallback default is `gpt-5.4-pro -\u003e gpt-5.4` |\n| `gpt-5-codex` | low, medium, high | Canonical Codex model for code generation (default: high) |\n| `gpt-5.3-codex-spark` | low, medium, high, xhigh | Spark IDs are supported by the plugin, but access is entitlement-gated by account/workspace |\n| `gpt-5.1-codex-max` | low, medium, high, xhigh | Maximum context Codex |\n| `gpt-5.1-codex` | low, medium, high | Standard Codex |\n| `gpt-5.1-codex-mini` | medium, high | Lightweight Codex |\n| `gpt-5.1` | none, low, medium, high | GPT-5.1 base model |\n\nConfig templates intentionally omit Spark model IDs by default to reduce entitlement failures on unsupported accounts. Add Spark manually only if your workspace is entitled.\n\n**Using variants:**\n```bash\n# Modern OpenCode (v1.0.210+)\nopencode run \"Hello\" --model=openai/gpt-5.4 --variant=high\n\n# Legacy OpenCode (v1.0.209 and below)\nopencode run \"Hello\" --model=openai/gpt-5.4-high\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull Models Configuration (Copy-Paste Ready)\u003c/b\u003e\u003c/summary\u003e\n\nAdd this to your `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"oc-chatgpt-multi-auth@latest\"],\n  \"provider\": {\n    \"openai\": {\n      \"options\": {\n        \"reasoningEffort\": \"medium\",\n        \"reasoningSummary\": \"auto\",\n        \"textVerbosity\": \"medium\",\n        \"include\": [\"reasoning.encrypted_content\"],\n        \"store\": false\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"GPT 5.4 (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"none\": { \"reasoningEffort\": \"none\" },\n            \"low\": { \"reasoningEffort\": \"low\" },\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" },\n            \"xhigh\": { \"reasoningEffort\": \"xhigh\" }\n          }\n        },\n        \"gpt-5-codex\": {\n          \"name\": \"GPT 5 Codex (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"low\": { \"reasoningEffort\": \"low\" },\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" }\n          },\n          \"options\": {\n            \"reasoningEffort\": \"high\",\n            \"reasoningSummary\": \"detailed\"\n          }\n        },\n        \"gpt-5.1-codex-max\": {\n          \"name\": \"GPT 5.1 Codex Max (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"low\": { \"reasoningEffort\": \"low\" },\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" },\n            \"xhigh\": { \"reasoningEffort\": \"xhigh\" }\n          }\n        },\n        \"gpt-5.1-codex\": {\n          \"name\": \"GPT 5.1 Codex (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"low\": { \"reasoningEffort\": \"low\" },\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" }\n          }\n        },\n        \"gpt-5.1-codex-mini\": {\n          \"name\": \"GPT 5.1 Codex Mini (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" }\n          }\n        },\n        \"gpt-5.1\": {\n          \"name\": \"GPT 5.1 (OAuth)\",\n          \"limit\": { \"context\": 272000, \"output\": 128000 },\n          \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n          \"variants\": {\n            \"none\": { \"reasoningEffort\": \"none\" },\n            \"low\": { \"reasoningEffort\": \"low\" },\n            \"medium\": { \"reasoningEffort\": \"medium\" },\n            \"high\": { \"reasoningEffort\": \"high\" }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nOptional Spark model block (manual add only when entitled):\n```json\n\"gpt-5.3-codex-spark\": {\n  \"name\": \"GPT 5.3 Codex Spark (OAuth)\",\n  \"limit\": { \"context\": 272000, \"output\": 128000 },\n  \"modalities\": { \"input\": [\"text\", \"image\", \"pdf\"], \"output\": [\"text\"] },\n  \"variants\": {\n    \"low\": { \"reasoningEffort\": \"low\" },\n    \"medium\": { \"reasoningEffort\": \"medium\" },\n    \"high\": { \"reasoningEffort\": \"high\" },\n    \"xhigh\": { \"reasoningEffort\": \"xhigh\" }\n  }\n}\n```\n\nFor legacy OpenCode (v1.0.209 and below), use `config/opencode-legacy.json` which has individual model entries like `gpt-5.4-low`, `gpt-5.4-medium`, etc.\n\n\u003c/details\u003e\n\n---\n\n## Multi-Account Setup\n\nAdd multiple ChatGPT accounts for higher combined quotas. The plugin uses **health-aware rotation** with automatic failover and supports up to 20 accounts.\n\n```bash\nopencode auth login  # Run again to add more accounts\n```\n\n---\n\n## Account Management Tools\n\nThe plugin provides built-in tools for managing your OpenAI accounts. These are available directly in OpenCode — just ask the agent or type the tool name.\n\n\u003e **Note:** Tools were renamed from `openai-accounts-*` to `codex-*` in v4.12.0 for brevity.\n\n### codex-list\n\nList all configured accounts with status badges.\n\n```text\ncodex-list\n```\n\nFilter by tag:\n\n```text\ncodex-list tag=\"work\"\n```\n\nShows account labels, IDs, tags, active state, and rate-limit/cooldown markers.\n\n---\n\n### codex-switch\n\nSwitch to a different account. If `index` is omitted and your terminal supports menus, an interactive picker opens.\n\n```text\ncodex-switch index=2\n```\n\nor:\n\n```text\ncodex-switch\n```\n\n---\n\n### codex-label\n\nSet or clear a display label for an account. Useful for workspace naming.\n\n```text\ncodex-label index=2 label=\"Work\"\n```\n\nClear:\n\n```text\ncodex-label index=2 label=\"\"\n```\n\nIf `index` is omitted in interactive terminals, a picker opens.\n\n---\n\n### codex-tag\n\nSet or clear comma-separated tags for filtering and grouping.\n\n```text\ncodex-tag index=2 tags=\"work,team-a\"\n```\n\nClear:\n\n```text\ncodex-tag index=2 tags=\"\"\n```\n\nUse tags with `codex-list tag=\"work\"`.\n\n---\n\n### codex-note\n\nSet or clear a short per-account note for reminders.\n\n```text\ncodex-note index=2 note=\"primary for weekday daytime usage\"\n```\n\nClear:\n\n```text\ncodex-note index=2 note=\"\"\n```\n\n---\n\n### codex-help\n\nShow beginner-friendly command guidance. Optional topic filter:\n\n```text\ncodex-help\ncodex-help topic=\"backup\"\n```\n\nAvailable topics: `setup`, `switch`, `health`, `backup`, `dashboard`, `metrics`.\n\n---\n\n### codex-setup\n\nShow readiness checklist for first-run onboarding and account health.\n\n```text\ncodex-setup\n```\n\nOpen guided wizard (menu-driven when terminal supports it, checklist fallback otherwise):\n\n```text\ncodex-setup wizard=true\n```\n\n---\n\n### codex-doctor\n\nRun diagnostics with actionable findings.\n\n```text\ncodex-doctor\ncodex-doctor deep=true\n```\n\nApply safe auto-fixes (`--fix` equivalent):\n- Refreshes tokens where possible\n- Persists refreshed credentials\n- Switches active account to the healthiest eligible account\n\n```text\ncodex-doctor fix=true\n```\n\n---\n\n### codex-next\n\nShow the single most recommended next action based on current account/runtime state.\n\n```text\ncodex-next\n```\n\n---\n\n### codex-status\n\nShow detailed status including rate limits and health scores.\n\n```text\ncodex-status\n```\n\n---\n\n### codex-metrics\n\nShow live runtime metrics (request counts, latency, errors, retries, and safe mode).\n\n```text\ncodex-metrics\n```\n\n---\n\n### codex-health\n\nCheck if all account tokens are still valid (read-only check).\n\n```text\ncodex-health\n```\n\n---\n\n### codex-refresh\n\nRefresh all OAuth tokens and save them to disk. Use this after long idle periods.\n\n```text\ncodex-refresh\n```\n\n`codex-health` validates. `codex-refresh` validates + refreshes + persists.\n\n---\n\n### codex-remove\n\nRemove an account entry. If `index` is omitted and your terminal supports menus, an interactive picker opens.\n\n```text\ncodex-remove index=3\n```\n\nor:\n\n```text\ncodex-remove\n```\n\n---\n\n### codex-export\n\nExport accounts to JSON for backup/migration.\n\nExplicit path:\n\n```text\ncodex-export path=\"~/backup/accounts.json\"\n```\n\nAuto timestamped backup path (default behavior when `path` is omitted):\n\n```text\ncodex-export\n```\n\nGenerated paths are stored in a `backups/` subdirectory near the active account storage file.\n\n---\n\n### codex-import\n\nImport accounts from a JSON file (dedupe-aware merge).\n\nDry-run preview (no writes):\n\n```text\ncodex-import path=\"~/backup/accounts.json\" dryRun=true\n```\n\nApply import:\n\n```text\ncodex-import path=\"~/backup/accounts.json\"\n```\n\nBefore apply, the plugin creates an automatic timestamped pre-import backup when existing accounts are present. If backup creation fails, import apply is aborted.\n\n---\n\n### codex-dashboard\n\nShow live account eligibility, retry budget usage, refresh queue metrics, and the recommended next step.\n\n```text\ncodex-dashboard\n```\n\n---\n\n### Quick Reference\n\n| Tool | What It Does | Example |\n|------|--------------|---------|\n| `codex-help` | Command guide by topic | `codex-help topic=\"setup\"` |\n| `codex-setup` | Readiness checklist/wizard | `codex-setup wizard=true` |\n| `codex-next` | Best next action | `codex-next` |\n| `codex-doctor` | Diagnostics and optional safe fixes | `codex-doctor fix=true` |\n| `codex-list` | List/filter accounts | `codex-list tag=\"work\"` |\n| `codex-switch` | Switch active account | `codex-switch index=2` |\n| `codex-label` | Set/clear display label | `codex-label index=2 label=\"Work\"` |\n| `codex-tag` | Set/clear tag list | `codex-tag index=2 tags=\"work,team-a\"` |\n| `codex-note` | Set/clear account note | `codex-note index=2 note=\"night backup\"` |\n| `codex-status` | Per-account health/rate limit detail | `codex-status` |\n| `codex-dashboard` | Live selection and retry view | `codex-dashboard` |\n| `codex-metrics` | Runtime metrics summary | `codex-metrics` |\n| `codex-health` | Validate token health (read-only) | `codex-health` |\n| `codex-refresh` | Refresh and persist tokens | `codex-refresh` |\n| `codex-remove` | Remove account entry | `codex-remove index=3` |\n| `codex-export` | Export account backups | `codex-export` |\n| `codex-import` | Dry-run or apply imports | `codex-import path=\"~/backup/accounts.json\" dryRun=true` |\n\n---\n\n### Sample Output (codex-list)\n\n```text\nCodex Accounts (3):\n\n  [1] Account 1 (user@gmail.com, workspace:Work, tags:work,team-a)  active\n  [2] Account 2 (backup@email.com, tags:backup)                      ok\n  [3] Account 3 (personal@email.com)                                 rate-limited\n\nStorage: ~/.opencode/openai-codex-accounts.json\n```\n\n## Rotation Behavior\n\n**How rotation works:**\n- Health scoring tracks success/failure per account\n- Token bucket prevents hitting rate limits\n- Hybrid selection prefers healthy accounts with available tokens\n- Always retries when all accounts are rate-limited (waits for reset with live countdown)\n- 20% jitter on retry delays to avoid thundering herd\n- Auto-removes accounts after 3 consecutive auth failures (new in v4.11.0)\n\n**Per-project accounts (v4.10.0+):**\n\nBy default, each project gets its own account storage namespace. This means you can keep different active accounts per project without writing account files into your repo. Works from subdirectories too; the plugin walks up to find the project root (v4.11.0). Disable with `perProjectAccounts: false` in your config.\n\n**Storage locations:**\n- Per-project: `~/.opencode/projects/{project-key}/openai-codex-accounts.json`\n- Global (when per-project disabled): `~/.opencode/openai-codex-accounts.json`\n\n---\n\n## Troubleshooting\n\n\u003e **Quick reset**: Most issues can be resolved by deleting `~/.opencode/auth/openai.json` and running `opencode auth login` again.\n\n### Configuration Paths (All Platforms)\n\nOpenCode uses `~/.config/opencode/` on **all platforms** including Windows.\n\n| File | Path |\n|------|------|\n| Main config | `~/.config/opencode/opencode.json` |\n| Auth tokens | `~/.opencode/auth/openai.json` |\n| Multi-account (global) | `~/.opencode/openai-codex-accounts.json` |\n| Multi-account (per-project) | `~/.opencode/projects/{project-key}/openai-codex-accounts.json` |\n| Flagged accounts | `~/.opencode/openai-codex-flagged-accounts.json` |\n| Plugin config | `~/.opencode/openai-codex-auth-config.json` |\n| Debug logs | `~/.opencode/logs/codex-plugin/` |\n\n\u003e **Windows users**: `~` resolves to your user home directory (e.g., `C:\\Users\\YourName`).\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e401 Unauthorized Error\u003c/b\u003e\u003c/summary\u003e\n\n**Cause:** Token expired or not authenticated.\n\n**Solutions:**\n1. Re-authenticate:\n   ```bash\n   opencode auth login\n   ```\n2. Check auth file exists:\n   ```bash\n   cat ~/.opencode/auth/openai.json\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBrowser Doesn't Open for OAuth\u003c/b\u003e\u003c/summary\u003e\n\n**Cause:** Port 1455 conflict or SSH/WSL environment.\n\n**Solutions:**\n1. **Manual URL paste:**\n   - Re-run `opencode auth login`\n   - Select **\"ChatGPT Plus/Pro (manual URL paste)\"**\n   - Paste the full redirect URL (including `#code=...`) after login\n\n2. **Check port availability:**\n   ```bash\n   # macOS/Linux\n   lsof -i :1455\n   \n   # Windows\n   netstat -ano | findstr :1455\n   ```\n\n3. **Stop Codex CLI if running** — Both use port 1455\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eModel Not Found\u003c/b\u003e\u003c/summary\u003e\n\n**Cause:** Missing provider prefix or config mismatch.\n\n**Solutions:**\n1. Use `openai/` prefix:\n   ```bash\n   # Correct\n   --model=openai/gpt-5.4\n   \n   # Wrong\n   --model=gpt-5.4\n   ```\n\n2. Verify model is in your config:\n   ```json\n   { \"models\": { \"gpt-5.4\": { ... } } }\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUnsupported Codex Model for ChatGPT Account\u003c/b\u003e\u003c/summary\u003e\n\n**Error example:** `Bad Request: {\"detail\":\"The 'gpt-5.3-codex-spark' model is not supported when using Codex with a ChatGPT account.\"}`\n\n**Cause:** Active workspace/account is not entitled for the requested Codex model.\n\n**Solutions:**\n1. Re-auth to refresh workspace selection (most common Spark fix):\n   ```bash\n   opencode auth login\n   ```\n2. Add another entitled account/workspace. The plugin will try remaining accounts/workspaces before model fallback.\n3. Enable automatic fallback only if you want degraded-model retries when Spark is not entitled:\n   ```bash\n   CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode\n   ```\n4. Use custom fallback chain in `~/.opencode/openai-codex-auth-config.json`:\n   ```json\n   {\n     \"unsupportedCodexPolicy\": \"fallback\",\n     \"fallbackOnUnsupportedCodexModel\": true,\n     \"unsupportedCodexFallbackChain\": {\n       \"gpt-5.4-pro\": [\"gpt-5.4\"],\n       \"gpt-5-codex\": [\"gpt-5.2-codex\"],\n       \"gpt-5.3-codex\": [\"gpt-5-codex\", \"gpt-5.2-codex\"],\n       \"gpt-5.3-codex-spark\": [\"gpt-5-codex\", \"gpt-5.3-codex\", \"gpt-5.2-codex\"]\n     }\n   }\n   ```\n5. Verify effective upstream model when needed:\n   ```bash\n   ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run \"ping\" --model=openai/gpt-5.3-codex-spark\n   ```\n   The UI can keep showing your selected model while fallback is applied internally.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRate Limit Exceeded\u003c/b\u003e\u003c/summary\u003e\n\n**Cause:** ChatGPT subscription usage limit reached.\n\n**Solutions:**\n1. Wait for reset (plugin shows timing in error message)\n2. Add more accounts: `opencode auth login`\n3. Switch to a different model family\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMulti-Turn Context Lost\u003c/b\u003e\u003c/summary\u003e\n\n**Cause:** Old plugin version or missing config.\n\n**Solutions:**\n1. Update plugin:\n   ```bash\n   npx -y oc-chatgpt-multi-auth@latest\n   ```\n2. Ensure config has:\n   ```json\n   {\n     \"include\": [\"reasoning.encrypted_content\"],\n     \"store\": false\n   }\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOAuth Callback Issues (Safari/WSL/Docker)\u003c/b\u003e\u003c/summary\u003e\n\n**Safari HTTPS-only mode:**\n- Use Chrome or Firefox instead, or\n- Temporarily disable Safari \u003e Settings \u003e Privacy \u003e \"Enable HTTPS-only mode\"\n\n**WSL2:**\n- Use VS Code's port forwarding, or\n- Configure Windows → WSL port forwarding\n\n**SSH / Remote:**\n```bash\nssh -L 1455:localhost:1455 user@remote\n```\n\n**Docker / Containers:**\n- OAuth with localhost redirect doesn't work in containers\n- Use SSH port forwarding or manual URL flow\n\n\u003c/details\u003e\n\n---\n\n## Plugin Compatibility\n\n### oh-my-opencode\n\nWorks alongside oh-my-opencode. No special configuration needed.\n\n```json\n{\n  \"plugin\": [\n    \"oc-chatgpt-multi-auth@latest\",\n    \"oh-my-opencode@latest\"\n  ]\n}\n```\n\n### @tarquinen/opencode-dcp\n\nList this plugin before dcp:\n\n```json\n{\n  \"plugin\": [\n    \"oc-chatgpt-multi-auth@latest\",\n    \"@tarquinen/opencode-dcp@latest\"\n  ]\n}\n```\n\n### Plugins You Don't Need\n\n- **openai-codex-auth** — Not needed. This plugin replaces the original.\n\n---\n\n## Configuration\n\nCreate `~/.opencode/openai-codex-auth-config.json` for optional settings:\n\n### Model Behavior\n\n| Option | Default | What It Does |\n|--------|---------|--------------|\n| `requestTransformMode` | `native` | Request shaping mode: `native` keeps OpenCode payloads unchanged; `legacy` enables Codex compatibility rewrites |\n| `codexMode` | `true` | Legacy-only bridge prompt behavior (applies when `requestTransformMode=legacy`) |\n| `codexTuiV2` | `true` | Enables Codex-style terminal UI output (set `false` for legacy output) |\n| `codexTuiColorProfile` | `truecolor` | Terminal color profile for Codex UI (`truecolor`, `ansi256`, `ansi16`) |\n| `codexTuiGlyphMode` | `ascii` | Glyph mode for Codex UI (`ascii`, `unicode`, `auto`) |\n| `fastSession` | `false` | Forces low-latency settings per request (`reasoningEffort=none/low`, `reasoningSummary=auto`, `textVerbosity=low`) |\n| `fastSessionStrategy` | `hybrid` | `hybrid` speeds simple turns but keeps full-depth on complex prompts; `always` forces fast tuning on every turn |\n| `fastSessionMaxInputItems` | `30` | Max input items kept when fast tuning is applied |\n\n### Account Settings (v4.10.0+)\n\n| Option | Default | What It Does |\n|--------|---------|--------------|\n| `perProjectAccounts` | `true` | Each project gets its own account storage namespace under `~/.opencode/projects/` |\n| `toastDurationMs` | `5000` | How long toast notifications stay visible (ms) |\n| `beginnerSafeMode` | `false` | Beginner-safe retry profile: conservative retry budget, disables all-accounts wait/retry, and caps all-accounts retries |\n\n### Retry Behavior\n\n| Option | Default | What It Does |\n|--------|---------|--------------|\n| `retryProfile` | `balanced` | Global retry budget profile (`conservative`, `balanced`, `aggressive`) |\n| `retryBudgetOverrides` | `{}` | Per-class retry budget overrides (`authRefresh`, `network`, `server`, `rateLimitShort`, `rateLimitGlobal`, `emptyResponse`) |\n| `retryAllAccountsRateLimited` | `true` | Wait and retry when all accounts are rate-limited |\n| `retryAllAccountsMaxWaitMs` | `0` | Max wait time (0 = unlimited) |\n| `retryAllAccountsMaxRetries` | `Infinity` | Max retry attempts |\n| `unsupportedCodexPolicy` | `strict` | Unsupported-model behavior: `strict` (return entitlement error) or `fallback` (retry next model in fallback chain) |\n| `fallbackOnUnsupportedCodexModel` | `false` | Legacy fallback toggle mapped to `unsupportedCodexPolicy` (prefer using `unsupportedCodexPolicy`) |\n| `fallbackToGpt52OnUnsupportedGpt53` | `true` | Legacy compatibility toggle for the `gpt-5.3-codex -\u003e gpt-5.2-codex` edge when generic fallback is enabled |\n| `unsupportedCodexFallbackChain` | `{}` | Optional per-model fallback-chain override (map of `model -\u003e [fallback1, fallback2, ...]`) |\n| `fetchTimeoutMs` | `60000` | Request timeout to Codex backend (ms) |\n| `streamStallTimeoutMs` | `45000` | Abort non-stream parsing if SSE stalls (ms) |\n\nDefault unsupported-model fallback chain (used when `unsupportedCodexPolicy` is `fallback`):\n- `gpt-5.4-pro -\u003e gpt-5.4` (if `gpt-5.4-pro` is selected manually)\n- `gpt-5.3-codex -\u003e gpt-5-codex -\u003e gpt-5.2-codex`\n- `gpt-5.3-codex-spark -\u003e gpt-5-codex -\u003e gpt-5.3-codex -\u003e gpt-5.2-codex` (applies if you manually select Spark model IDs)\n- `gpt-5.2-codex -\u003e gpt-5-codex`\n- `gpt-5.1-codex -\u003e gpt-5-codex`\n\nWhen `beginnerSafeMode` is enabled, runtime behavior is intentionally conservative:\n- Retry profile is forced to `conservative`\n- `retryAllAccountsRateLimited` is forced `false`\n- `retryAllAccountsMaxRetries` is capped to `1`\n\n### Environment Variables\n\n```bash\nDEBUG_CODEX_PLUGIN=1 opencode                    # Enable debug logging\nENABLE_PLUGIN_REQUEST_LOGGING=1 opencode         # Log request metadata\nCODEX_PLUGIN_LOG_BODIES=1 opencode               # Include raw request/response payloads in request logs (sensitive)\nCODEX_PLUGIN_LOG_LEVEL=debug opencode            # Set log level (debug|info|warn|error)\nCODEX_AUTH_REQUEST_TRANSFORM_MODE=legacy opencode # Re-enable legacy Codex request rewrites\nCODEX_MODE=0 opencode                            # Temporarily disable bridge prompt\nCODEX_TUI_V2=0 opencode                          # Disable Codex-style UI (legacy output)\nCODEX_TUI_COLOR_PROFILE=ansi16 opencode          # Force UI color profile\nCODEX_TUI_GLYPHS=unicode opencode                # Override glyph mode (ascii|unicode|auto)\nCODEX_AUTH_PREWARM=0 opencode                    # Disable startup prewarm (prompt/instruction cache warmup)\nCODEX_AUTH_FAST_SESSION=1 opencode               # Enable faster response defaults\nCODEX_AUTH_FAST_SESSION_STRATEGY=always opencode # Force fast mode for all prompts\nCODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS=24 opencode # Tune fast-mode history window\nCODEX_AUTH_BEGINNER_SAFE_MODE=1 opencode         # Enable beginner-safe runtime profile\nCODEX_AUTH_RETRY_PROFILE=aggressive opencode     # Override retry profile (ignored when beginner safe mode is on)\nCODEX_AUTH_RETRY_ALL_RATE_LIMITED=0 opencode     # Disable all-accounts wait-and-retry\nCODEX_AUTH_RETRY_ALL_MAX_WAIT_MS=30000 opencode  # Cap all-accounts wait duration\nCODEX_AUTH_RETRY_ALL_MAX_RETRIES=1 opencode      # Cap all-accounts retry attempts\nCODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode # Enable generic unsupported-model fallback\nCODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1 opencode # Legacy fallback toggle (prefer policy var above)\nCODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0 opencode    # Disable only the legacy gpt-5.3 -\u003e gpt-5.2 edge\nCODEX_AUTH_FETCH_TIMEOUT_MS=120000 opencode      # Override request timeout\nCODEX_AUTH_STREAM_STALL_TIMEOUT_MS=60000 opencode # Override SSE stall timeout\n```\n\nFor all options, see [docs/configuration.md](docs/configuration.md).\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) — Complete installation guide\n- [Configuration](docs/configuration.md) — All configuration options\n- [Troubleshooting](docs/troubleshooting.md) — Common issues and fixes\n- [Architecture](docs/development/ARCHITECTURE.md) — How the plugin works\n\n---\n\n## Credits\n\n- [numman-ali/opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) by [numman-ali](https://github.com/numman-ali) — Original plugin\n- [ndycode](https://github.com/ndycode) — Multi-account support and maintenance\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLegal\u003c/b\u003e\u003c/summary\u003e\n\n### Intended Use\n\n- Personal / internal development only\n- Respect subscription quotas and data handling policies\n- Not for production services or bypassing intended limits\n\n### Warning\n\nBy using this plugin, you acknowledge:\n\n- **Terms of Service risk** — This approach may violate ToS of AI model providers\n- **No guarantees** — APIs may change without notice\n- **Assumption of risk** — You assume all legal, financial, and technical risks\n\n### Disclaimer\n\n- Not affiliated with OpenAI. This is an independent open-source project.\n- \"ChatGPT\", \"GPT-5\", \"Codex\", and \"OpenAI\" are trademarks of OpenAI, L.L.C.\n\n\u003c/details\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndycode%2Foc-chatgpt-multi-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndycode%2Foc-chatgpt-multi-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndycode%2Foc-chatgpt-multi-auth/lists"}