Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ndycode/opencode-openai-codex-auth-multi

Fork of opencode-openai-codex-auth with multi-account rotation
https://github.com/ndycode/opencode-openai-codex-auth-multi

Last synced: 2 months ago
JSON representation

Fork of opencode-openai-codex-auth with multi-account rotation

Awesome Lists containing this project

README 

          
# OpenAI Codex Auth Plugin for OpenCode



[![npm version](https://img.shields.io/npm/v/opencode-openai-codex-auth-multi.svg)](https://www.npmjs.com/package/opencode-openai-codex-auth-multi)

[![npm downloads](https://img.shields.io/npm/dw/opencode-openai-codex-auth-multi.svg)](https://www.npmjs.com/package/opencode-openai-codex-auth-multi)

[![Tests](https://github.com/ndycode/opencode-openai-codex-auth-multi/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/opencode-openai-codex-auth-multi/actions)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)



Enable OpenCode to authenticate against **OpenAI's Codex backend** via OAuth so you can use ChatGPT Plus/Pro rate limits and access models like `gpt-5.2`, `gpt-5.2-codex`, and `gpt-5.1-codex-max` with your ChatGPT credentials.



## What You Get



- **GPT-5.2, GPT-5.2 Codex, GPT-5.1 Codex Max** and all GPT-5.x variants via ChatGPT OAuth

- **Multi-account support** — add multiple ChatGPT accounts, health-aware rotation with automatic failover

- **Auto-update notifications** — get notified when a new version is available

- **22 model presets** — full variant system with reasoning levels (none/low/medium/high/xhigh)

- **Prompt caching** — session-based caching for faster multi-turn conversations

- **Usage-aware errors** — friendly messages with rate limit reset timing

- **Plugin compatible** — works alongside other OpenCode plugins (oh-my-opencode, dcp, etc.)



---



Terms of Service Warning — Read Before Installing



> [!CAUTION]

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

>

> **This plugin is for personal development only:**

> - Not for commercial services, API resale, or multi-user applications

> - For production use, see [OpenAI Platform API](https://platform.openai.com/)

>

> **By using this plugin, you acknowledge:**

> - This is an unofficial tool not endorsed by OpenAI

> - Users are responsible for compliance with [OpenAI's Terms of Use](https://openai.com/policies/terms-of-use/)

> - You assume all risks associated with using this plugin



---



## Installation



For Humans



**Option A: Let an LLM do it**



Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):



```

Install the opencode-openai-codex-auth-multi plugin and add the OpenAI model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/ndycode/opencode-openai-codex-auth-multi/main/README.md

```



**Option B: One-command install**



```bash

npx -y opencode-openai-codex-auth-multi@latest

```



This writes the config to `~/.config/opencode/opencode.json`, backs up existing config, and clears the plugin cache.



> Want legacy config (OpenCode v1.0.209 and below)? Add `--legacy` flag.



**Option C: Manual setup**



1. **Add the plugin** to `~/.config/opencode/opencode.json`:



   ```json

   {

     "plugin": ["opencode-openai-codex-auth-multi@latest"]

   }

   ```



2. **Login** with your ChatGPT account:



   ```bash

   opencode auth login

   ```



3. **Add models** — copy the [full configuration](#models) below



4. **Use it:**



   ```bash

   opencode run "Hello" --model=openai/gpt-5.2 --variant=medium

   ```



For LLM Agents



### Step-by-Step Instructions



1. Edit the OpenCode configuration file at `~/.config/opencode/opencode.json`

   

   > **Note**: This path works on all platforms. On Windows, `~` resolves to your user home directory (e.g., `C:\Users\YourName`).



2. Add the plugin to the `plugin` array:

   ```json

   {

     "plugin": ["opencode-openai-codex-auth-multi@latest"]

   }

   ```



3. Add the model definitions from the [Full models configuration](#full-models-configuration-copy-paste-ready) section



4. Set `provider` to `"openai"` and choose a model



### Verification



```bash

opencode run "Hello" --model=openai/gpt-5.2 --variant=medium

```



---



## Models



### Model Reference



| Model | Variants | Notes |

|-------|----------|-------|

| `gpt-5.2` | none, low, medium, high, xhigh | Latest GPT-5.2 with reasoning levels |

| `gpt-5.2-codex` | low, medium, high, xhigh | GPT-5.2 Codex for code generation |

| `gpt-5.1-codex-max` | low, medium, high, xhigh | Maximum context Codex |

| `gpt-5.1-codex` | low, medium, high | Standard Codex |

| `gpt-5.1-codex-mini` | medium, high | Lightweight Codex |

| `gpt-5.1` | none, low, medium, high | GPT-5.1 base model |



**Using variants:**

```bash

# Modern OpenCode (v1.0.210+)

opencode run "Hello" --model=openai/gpt-5.2 --variant=high



# Legacy OpenCode (v1.0.209 and below)

opencode run "Hello" --model=openai/gpt-5.2-high

```



Full models configuration (copy-paste ready)



Add this to your `~/.config/opencode/opencode.json`:



```json

{

  "$schema": "https://opencode.ai/config.json",

  "plugin": ["opencode-openai-codex-auth-multi@latest"],

  "provider": {

    "openai": {

      "options": {

        "reasoningEffort": "medium",

        "reasoningSummary": "auto",

        "textVerbosity": "medium",

        "include": ["reasoning.encrypted_content"],

        "store": false

      },

      "models": {

        "gpt-5.2": {

          "name": "GPT 5.2 (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "none": { "reasoningEffort": "none" },

            "low": { "reasoningEffort": "low" },

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" },

            "xhigh": { "reasoningEffort": "xhigh" }

          }

        },

        "gpt-5.2-codex": {

          "name": "GPT 5.2 Codex (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "low": { "reasoningEffort": "low" },

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" },

            "xhigh": { "reasoningEffort": "xhigh" }

          }

        },

        "gpt-5.1-codex-max": {

          "name": "GPT 5.1 Codex Max (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "low": { "reasoningEffort": "low" },

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" },

            "xhigh": { "reasoningEffort": "xhigh" }

          }

        },

        "gpt-5.1-codex": {

          "name": "GPT 5.1 Codex (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "low": { "reasoningEffort": "low" },

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" }

          }

        },

        "gpt-5.1-codex-mini": {

          "name": "GPT 5.1 Codex Mini (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" }

          }

        },

        "gpt-5.1": {

          "name": "GPT 5.1 (OAuth)",

          "limit": { "context": 272000, "output": 128000 },

          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },

          "variants": {

            "none": { "reasoningEffort": "none" },

            "low": { "reasoningEffort": "low" },

            "medium": { "reasoningEffort": "medium" },

            "high": { "reasoningEffort": "high" }

          }

        }

      }

    }

  }

}

```



For legacy OpenCode (v1.0.209 and below), use `config/opencode-legacy.json` which has individual model entries like `gpt-5.2-low`, `gpt-5.2-medium`, etc.



---



## Multi-Account Setup



Add multiple ChatGPT accounts for higher combined quotas. The plugin uses **health-aware rotation** with automatic failover.



```bash

opencode auth login  # Run again to add more accounts

```



**Manage accounts:**

- `openai-accounts` — List all accounts

- `openai-accounts-switch` — Switch active account

- `openai-accounts-status` — Show rate limit status



**How rotation works (v4.4.0+):**

- Health scoring tracks success/failure per account

- Token bucket prevents hitting rate limits

- Hybrid selection prefers healthy accounts with available tokens

- Always retries when all accounts are rate-limited (waits for reset)



**Storage:** `~/.opencode/openai-codex-accounts.json`



---



## Troubleshoot



> **Quick Reset**: Most issues can be resolved by deleting `~/.opencode/auth/openai.json` and running `opencode auth login` again.



### Configuration Path (All Platforms)



OpenCode uses `~/.config/opencode/` on **all platforms** including Windows.



| File | Path |

|------|------|

| Main config | `~/.config/opencode/opencode.json` |

| Auth tokens | `~/.opencode/auth/openai.json` |

| Multi-account | `~/.opencode/openai-codex-accounts.json` |

| Plugin config | `~/.opencode/openai-codex-auth-config.json` |

| Debug logs | `~/.opencode/logs/codex-plugin/` |



> **Windows users**: `~` resolves to your user home directory (e.g., `C:\Users\YourName`).



---



401 Unauthorized Error



**Cause:** Token expired or not authenticated.



**Solutions:**

1. Re-authenticate:

   ```bash

   opencode auth login

   ```

2. Check auth file exists:

   ```bash

   cat ~/.opencode/auth/openai.json

   ```



Browser Doesn't Open for OAuth



**Cause:** Port 1455 conflict or SSH/WSL environment.



**Solutions:**

1. **Manual URL paste:**

   - Re-run `opencode auth login`

   - Select **"ChatGPT Plus/Pro (Manual URL Paste)"**

   - Paste the full redirect URL after login



2. **Check port availability:**

   ```bash

   # macOS/Linux

   lsof -i :1455

   

   # Windows

   netstat -ano | findstr :1455

   ```



3. **Stop Codex CLI if running** — both use port 1455



Model Not Found



**Cause:** Missing provider prefix or config mismatch.



**Solutions:**

1. Use `openai/` prefix:

   ```bash

   # Correct

   --model=openai/gpt-5.2

   

   # Wrong

   --model=gpt-5.2

   ```



2. Verify model is in your config:

   ```json

   { "models": { "gpt-5.2": { ... } } }

   ```



Rate Limit Exceeded



**Cause:** ChatGPT subscription usage limit reached.



**Solutions:**

1. Wait for reset (plugin shows timing in error message)

2. Add more accounts: `opencode auth login`

3. Switch to a different model family



Multi-Turn Context Lost



**Cause:** Old plugin version or missing config.



**Solutions:**

1. Update plugin:

   ```bash

npx -y opencode-openai-codex-auth-multi@latest

   ```

2. Ensure config has:

   ```json

   {

     "include": ["reasoning.encrypted_content"],

     "store": false

   }

   ```



OAuth Callback Issues (Safari/WSL/Docker)



**Safari HTTPS-Only Mode:**

- Use Chrome or Firefox instead, or

- Temporarily disable Safari > Settings > Privacy > "Enable HTTPS-Only Mode"



**WSL2:**

- Use VS Code's port forwarding, or

- Configure Windows → WSL port forwarding



**SSH / Remote:**

```bash

ssh -L 1455:localhost:1455 user@remote

```



**Docker / Containers:**

- OAuth with localhost redirect doesn't work in containers

- Use SSH port forwarding or manual URL flow



---



## Plugin Compatibility



### oh-my-opencode



Works alongside oh-my-opencode. No special configuration needed.



```json

{

  "plugin": [

    "opencode-openai-codex-auth-multi@latest",

    "oh-my-opencode@latest"

  ]

}

```



### @tarquinen/opencode-dcp



List this plugin BEFORE DCP:



```json

{

  "plugin": [

    "opencode-openai-codex-auth-multi@latest",

    "@tarquinen/opencode-dcp@latest"

  ]

}

```



### Plugins you don't need



- **openai-codex-auth** — Not needed. This plugin replaces the original.



---



## Configuration



Create `~/.opencode/openai-codex-auth-config.json` for optional settings:



### Model Behavior



| Option | Default | What it does |

|--------|---------|--------------|

| `codexMode` | `true` | Uses Codex-OpenCode bridge prompt (synced with latest Codex CLI) |



### Retry Behavior (v4.4.0+)



| Option | Default | What it does |

|--------|---------|--------------|

| `retryAllAccountsRateLimited` | `true` | Wait and retry when all accounts are rate-limited |

| `retryAllAccountsMaxWaitMs` | `0` | Max wait time (0 = unlimited) |

| `retryAllAccountsMaxRetries` | `Infinity` | Max retry attempts |



### Environment Variables



```bash

DEBUG_CODEX_PLUGIN=1 opencode                    # Enable debug logging

ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode         # Log all API requests

CODEX_PLUGIN_LOG_LEVEL=debug opencode            # Set log level (debug|info|warn|error)

CODEX_MODE=0 opencode                            # Temporarily disable bridge prompt

```



For all options, see [docs/configuration.md](docs/configuration.md).



---



## Documentation



- [Getting Started](docs/getting-started.md) — Complete installation guide

- [Configuration](docs/configuration.md) — All configuration options

- [Troubleshooting](docs/troubleshooting.md) — Common issues and fixes

- [Architecture](docs/development/ARCHITECTURE.md) — How the plugin works



---



## Credits



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

- [ndycode](https://github.com/ndycode) — Multi-account support and maintenance



## License



MIT License. See [LICENSE](LICENSE) for details.



Legal



### Intended Use



- Personal / internal development only

- Respect subscription quotas and data handling policies

- Not for production services or bypassing intended limits



### Warning



By using this plugin, you acknowledge:



- **Terms of Service risk** — This approach may violate ToS of AI model providers

- **No guarantees** — APIs may change without notice

- **Assumption of risk** — You assume all legal, financial, and technical risks



### Disclaimer



- Not affiliated with OpenAI. This is an independent open-source project.

- "ChatGPT", "GPT-5", "Codex", and "OpenAI" are trademarks of OpenAI, L.L.C.