DOCSEARCHbyAlgolia
Submit Docs

oc-codex-multi-auth

repository·main·Indexed 41 days ago

https://github.com/ndycode/oc-codex-multi-auth

OpenCode plugin for ChatGPT Plus/Pro OAuth featuring Codex/GPT-5 routing, multi-account rotation, and health checks. Version 6.21.0 provides advanced routing for GPT-6 Astra, GPT-5.6, and GPT-5.5 models, including automatic fallback chains and a standalone CLI for account management, diagnostics, and quota monitoring.

Tokens
59.3K
Snippets
142
Records
240
Agent score
53%

What's inside oc-codex-multi-auth

  1. Explore oc-codex-multi-auth documentation

    main

    The documentation for oc-codex-multi-auth is organized by user intent. Use the following guides to navigate the project:

    • Getting Started: For full installation, ChatGPT OAuth setup, configuration templates, model selectors, and first-run verification.
    • Tools and CLI: To view the catalog of 24 codex-* tools and standalone binary commands.
    • Architecture Overview: To understand the installer, OpenCode plugin entry, TUI plugin, tool registry, request pipeline, rotation, and storage model.
    • Configuration Reference: For details on config keys, environment variables, fallback behavior, and file locations.
    • Troubleshooting: For common failure modes and recovery steps.
    • FAQ: For quick answers to common questions.
    • Privacy & Data Handling: To understand local storage, upstream data transmission, and data deletion procedures.

  2. Identify the purpose and target audience of oc-codex-multi-auth

    main

    Product Summary

    Purpose: Provides an OpenCode plugin for:

    • ChatGPT Plus/Pro OAuth
    • Codex/GPT-5 routing
    • Multi-account rotation and account switching
    • Health checks and quota status monitoring
    • Diagnostics and recovery tooling
    • TUI (Terminal User Interface) quota visibility

    Target Users: Individual developers using OpenCode who require:

    • ChatGPT OAuth-backed Codex workflows
    • Visible local account state
    • Explicit account switching
    • Health-aware account selection
    • Redacted diagnostics
    • Project-scoped account pools
    • Guided setup and recovery commands

    Not Intended For:

    • Hosted auth services
    • Commercial resale
    • Shared multi-user credential pools
    • Generic API-key users
    • Production workloads that should use the OpenAI Platform API

  3. Use OS Keychain for credential storage

    main

    By default, account pools are stored in local V3 JSON files. You can opt to use the OS-native keychain instead by setting CODEX_KEYCHAIN=1. This uses:

    • macOS: Keychain
    • Windows: Credential Manager
    • Linux: libsecret (requires GNOME Keyring or KWallet)

    If the keychain is unavailable, the plugin logs a warning and falls back to JSON storage without deleting existing credentials.

    codex-keychain command="status"
codex-keychain command="migrate"
codex-keychain command="rollback"

  4. Understand Retry Profiles and Budgets

    main

    The retryProfile setting determines the retry budgets for different request classes. You can use retryBudgetOverrides to replace specific class budgets.

    Retry Classes: authRefresh, network, server, rateLimitShort, rateLimitGlobal, and emptyResponse.

    Profiles:

    profileauthRefreshnetworkserverrateLimitShortrateLimitGlobalemptyResponse
    conservative222211
    balanced (default)444432
    aggressive8888104

    Rate Limiting Logic:

    • Short Wait (< 5000ms): If a 429 arrives and the wait is $\le$ 5000ms, it consumes the rateLimitShort budget and retries the same account.
    • Long Wait/Exhaustion: If the wait is $>5000$ms or the rateLimitShort budget is exhausted, the account is marked rate-limited and the system rotates to the next account. If all accounts are limited, it consumes the rateLimitGlobal budget.

  5. Understand the design constraints and technical requirements

    main

    When integrating or using oc-codex-multi-auth, adhere to the following technical constraints:

    • Node.js Requirement: Requires Node engine >=18.
    • Package Exports: The package provides two main entry points:
      • . (the provider plugin)
      • ./tui (the TUI quota plugin)
    • Naming: The canonical name is oc-codex-multi-auth. The legacy name oc-chatgpt-multi-auth is for migration purposes only.
    • OAuth Configuration: The OAuth callback port is fixed at 1455 with the callback path /auth/callback.
    • ChatGPT Request Requirements: For ChatGPT-backed Codex requests, the following parameters are required:
      • store: false
      • stream: true
      • reasoning.encrypted_content
    • Account Pool Limits:
      • Maximum of 20 accounts.
      • 30s cooldown after an authentication failure.
      • Accounts are automatically removed after 3 consecutive authentication failures.
    • Auth Methods: Only four OAuth labels are exposed to OpenCode: default browser, open URL manually, device code, and manual URL paste. Note that there is no API-key login method.
    • Data Locality: Credentials and account metadata are stored locally unless explicitly exported or migrated.

  6. Map Models to Specific Account Pools

    main

    You can use modelAccountPools and modelAccountPoolModes in your runtime config to ensure specific models always use preferred or dedicated accounts (e.g., specific Business-seat identities).

    Pool Modes:

    • preferred (Default): The request pipeline attempts to use accounts in the configured pool. If none are available or healthy, it falls back to the general account pool.
    • strict: The request pipeline only uses the configured accounts. If no accounts in the pool are available, the request fails immediately.

    Mutation via CLI: The codex-pool command allows you to manage these mappings. It supports 1-based account numbers for set, add, and remove operations and can handle both raw accountId and resolved seat identities.

    {
  "modelAccountPools": {
    "gpt-5.6-sol": ["org-example-account-id"],
    "gpt-5.5": ["org-another-account-id"]
  },
  "modelAccountPoolModes": {
    "gpt-5.6-sol": "strict"
  }
}

  7. Model fallback behavior and configuration

    main

    The plugin includes 13 base families and 59 presets. Some models have automatic fallback chains if entitlements are missing:

    • GPT-5.6 Fallback: If access is denied, the plugin falls back in this order: gpt-5.6-sol $\rightarrow$ gpt-5.6-terra $\rightarrow$ gpt-5.6-luna $\rightarrow$ gpt-5.5.
      • Disable this with: CODEX_AUTH_DISABLE_GPT56_AUTO_FALLBACK=1
    • GPT-6 Astra Fallback: Falls back in this order: gpt-6-astra $\rightarrow$ sol $\rightarrow$ terra $\rightarrow$ luna $\rightarrow$ gpt-5.5.
      • Disable this with: CODEX_AUTH_DISABLE_GPT6_AUTO_FALLBACK=1

    Important Notes:

    • gpt-5.5-pro is ChatGPT-only and is not routed through this Codex plugin.
    • Daybreak-gated cyber tiers (gpt-daybreak-blue-latest, gpt-daybreak-red-latest, gpt-5.6-cyber) are routed but have no fallback chain and are not in shipped templates.

  8. How System Instructions are sourced

    main

    The plugin uses two methods to source system instructions depending on the model:

    1. Catalog-sourced: Modern models (e.g., gpt-5.6-*, gpt-5.5, gpt-5.4) pull instructions directly from the Codex model catalog (base_instructions). These are cached per model ID.
    2. File-sourced: Legacy models (e.g., gpt-5-codex, gpt-5.1*, gpt-5.2-codex) use historical *_prompt.md files. These use a family-keyed cache.

    Note on GPT-6 Astra: Currently uses gpt_5_2_prompt.md as a fallback because its catalog entry contains empty instructions.

  9. Configure OpenCode via different config surfaces

    main

    OpenCode configuration is managed through several layers of precedence. Use these surfaces to control model selection and provider behavior:

    1. Global Config: The primary surface managed by the installer at ~/.config/opencode/opencode.json.
    2. Project Overrides: For per-project model or provider settings, create a .opencode.json file in your project root.
    3. One-shot Overrides: Pass configuration via environment variables at process start for immediate, temporary changes.
    4. Plugin Runtime Config: Specific plugin behaviors (retry policy, rotation, TUI output, etc.) are controlled via ~/.opencode/openai-codex-auth-config.json.
    # One-shot override using a config file
OPENCODE_CONFIG=/path/to/config.json opencode

# One-shot override using inline JSON content
OPENCODE_CONFIG_CONTENT='{"model":"openai/gpt-5.5","variant":"medium"}' opencode

  10. Understand the request pipeline and 'responses-lite' reshaping

    main

    The plugin intercepts OpenCode provider fetches to transform requests. For specific 'lite' models (such as gpt-6-astra, Daybreak tiers, and gpt-5.6 variants), the plugin applies a responses-lite reshape to match Codex behavior:

    • Tooling: Tool definitions are moved into the input field as a leading additional_tools developer item; the top-level tools field is omitted.
    • Instructions: Codex instructions follow as a developer message; the top-level instructions field is emptied.
    • Parameters: parallel_tool_calls is forced off, reasoning.context is set to all_turns, and image detail fields are stripped.
    • Headers: The header x-openai-internal-codex-responses-lite: true is attached.

    This reshaping is applied per-attempt. If a model fallback occurs (e.g., from a lite model to gpt-5.5), the request is re-serialized into the classic shape.

  11. Configure OpenAI models using the Legacy template

    main

    Legacy templates do not use variants. Instead, they expose every preset as its own unique model key (e.g., gpt-5.5-high). Each entry includes its own options block to define the specific behavior for that preset.

    Usage Example: Select the specific preset directly via the --model flag:

    opencode run "task" --model=openai/gpt-5.5-high
    {
  "provider": {
    "openai": {
      "models": {
        "gpt-5.5-high": {
          "name": "GPT 5.5 High (OAuth)",
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    }
  }
}

  12. Multi-account rotation and management

    main

    The plugin supports up to 20 saved OAuth accounts with health-aware rotation.

    Rotation Strategies (rotationStrategy):

    • hybrid (default)
    • sticky
    • round-robin

    Account Management Features:

    • Preferred Pools: Use modelAccountPools or codex-pool to map specific models to specific accounts.
    • CLI Tools: Manage accounts using codex-list, codex-switch, and codex-warm.

    Safety Limits:

    • Cooldown: 30s cooldown after authentication failures.
    • Auto-removal: Accounts are automatically removed after 3 consecutive authentication failures.