DOCSEARCHbyAlgolia
Submit Docs

OpenCode Multi-Auth Codex

repository·main·Indexed 41 days ago

https://github.com/floze-the-genius/opencode-multi-auth-codex

An open-source account routing and reliability tool for OpenCode's Codex OAuth integration. Version 1.4.3 provides local session controls, request rotation across multiple ChatGPT/Codex accounts (round-robin, least-used, random, weighted), and a monitoring dashboard for account health and limits.

Tokens
30.3K
Snippets
101
Records
143
Agent score
49%

What's inside OpenCode Multi-Auth Codex

  1. Locate current documentation for opencode-multi-auth-codex

    main

    To understand the current state of the project, use the following documentation hierarchy. Note that historical phase records (such as docs/QA.md or docs/PRODUCTION_READINESS.md) are for context only and may contain superseded information.

    Current Reference Documents

    • README.md: The primary source for plugin documentation, including installation, usage, runtime behavior, API, environment variables, and troubleshooting.
    • docs/ADMIN_MERGE_BRIEF.md: Summary of merges and reviews for upstream maintainers and admins.
    • docs/PHASE_H_VALIDATION.md: The final validation matrix and production readiness evidence.
    • codextesting.md: A checklist for live/manual testing and local verification with Codex/OpenCode.

    Rule of Precedence

    If documentation entries conflict, follow this order of truth:

    1. README.md (Defines current behavior)
    2. docs/PHASE_H_VALIDATION.md (Defines final validation)
    3. Historical phase docs (Timeline/context only)

  2. Verify Re-auth per Account functionality

    main

    Re-authentication should be scoped to specific accounts without disrupting the global state.

    • API: POST /api/accounts/:alias/reauth must update credentials for the target alias only.
    • Consistency: Re-authenticating an active alias must keep the active auth pointer consistent.
    • UI Transitions: Headless tests should verify the state machine: idle -> in-progress -> success/error.

  3. Understand limit freshness and confidence states

    main

    The system uses a freshness/confidence model to indicate how reliable the current usage limit data is. This prevents using inaccurate or outdated data for rotation decisions.

    StateCondition
    freshProbe succeeded within the last 5 minutes
    staleProbe succeeded between 5 and 60 minutes ago
    errorThe last probe failed, and it has been < 60 minutes since the last success
    unknownNo successful probe has ever occurred, OR the last success was > 60 minutes ago

    Note: Missing authoritative data is represented as unknown, not 0%.

  4. Verify Force Mode behavior

    main

    Force Mode is a separate mechanism from the account Enabled switch. Validate these rules:

    • Independence: The Force toggle must remain separate from account Enabled switches.
    • Pinning: Enabling force pins the specified alias while it remains eligible.
    • Restoration:
      • Clearing force must restore the prior rotation strategy.
      • Disabling a forced alias must auto-clear the force and restore the prior strategy.
    • TTL: The 24h anchor must not extend upon repeated force toggles.

  5. Manage Antigravity feature via feature flags

    main

    The antigravity functionality is considered a non-core feature and is gated behind a feature flag. By default, this flag is false (off).

    • When Off (Default): Antigravity logic cannot affect core rotation, account selection, or store operations. The Antigravity UI/panel is hidden.
    • When On: Antigravity rules are applied to account selection, and the Antigravity UI/panel becomes visible.

    You can enable the flag via environment variables or the settings API.

  6. Understand the Limits Data Quality Contract

    main

    The system ensures high-quality data for usage limits through several guarantees. When consuming limit data, be aware of the following contract properties:

    • Authority: Results include an isAuthoritative flag to indicate if the probe is the source of truth.
    • Protection: Failed probes are prevented from overwriting existing, valid limits.
    • Freshness States: Data is categorized into fresh, stale, error, or unknown states.
    • Missing Data: If data is missing, the system reports unknown rather than 0% to prevent incorrect rotation decisions.
    • Diagnostics: Probe results include source diagnostics for debugging.

  7. Understand the Store Contract and Data Integrity

    main

    The internal store is designed for high reliability and atomic operations. Key characteristics include:

    • Automatic Migration: Supports seamless v1 to v2 data migration.
    • Atomic Writes: Uses a tmp → fsync → rename pattern to ensure writes are never partially completed.
    • Persistence: The version field is always persisted, and settings are stored and retrieved correctly.
    • Recovery: Maintains last-known-good snapshots to recover from corruption or unexpected shutdowns.

  8. Understand account rotation and rate-limit behavior

    main

    The system manages multiple accounts for Codex usage and implements specific behaviors when accounts encounter rate limits or when specific modes are active:

    Rate Limit Handling (429 Errors)

    When an account hits a rate limit (429), it is placed in a 'sleep' state until its reset time. The system calculates rateLimitedUntil using one of the following:

    • The Retry-After header.
    • Known rate-limit window reset times.
    • Provider reset text extracted from error messages.
    • A fallback cooldown period.

    The rotator will automatically exclude any account where rateLimitedUntil > now.

    Force Mode Strict Pinning

    When Force Mode is active, the system strictly targets the forced alias.

    • No Fallback: If the forced alias is blocked (e.g., rate-limited), the request will fail with a deterministic error instead of falling back to another available account.
    • State Persistence: Force state only auto-clears upon expiry, removal, or if the account is disabled. It does not clear due to transient ineligibility (like a temporary rate limit).

  9. Verify Account Enabled Switch functionality

    main

    The Enabled switch is the sole mechanism for disabling an account. Ensure the following behaviors are validated:

    • API: PUT /api/accounts/:alias/enabled must toggle state with deterministic errors.
    • Rotation: Disabled accounts must never be selected by the rotation logic.
    • Persistence: The enabled/disabled state must survive a process restart.
    • UI (Headless):
      • The switch must render per account with states: off, on, updating, and error.
      • Toggles must be non-reentrant (safe from double-clicks).
    • Legacy Cleanup: Ensure all old disable buttons or controls are removed; only the Enabled switch should control account availability.

  10. Map older Codex selections to the latest backend model

    main

    By default, the plugin preserves exact model selection. However, you can opt-in to routing older Codex selections to the latest backend model using these variables:

    • OPENCODE_MULTI_AUTH_PREFER_CODEX_LATEST=1: Enables mapping to the latest backend model.
    • OPENCODE_MULTI_AUTH_CODEX_LATEST_MODEL=gpt-5.4: Overrides the target model (e.g., to roll back from gpt-5.5 to gpt-5.4).
    • OPENCODE_MULTI_AUTH_DEBUG=1: Enables debug logs for model mapping.
    • OPENCODE_MULTI_AUTH_INJECT_MODELS=0: Disables automatic runtime model backfill.
    # Example: Map all requests to gpt-5.4 even if older models are selected
export OPENCODE_MULTI_AUTH_PREFER_CODEX_LATEST=1
export OPENCODE_MULTI_AUTH_CODEX_LATEST_MODEL=gpt-5.4
export OPENCODE_MULTI_AUTH_DEBUG=1

  11. Understand Limits Confidence States

    main

    The system tracks the reliability of rate limit data using a LimitsConfidence enum. This helps users understand how 'fresh' the current limit information is.

    StateDescriptionThreshold
    freshHighly reliable, recent data< 5 minutes old
    staleData is aging but still usable5 - 60 minutes old
    errorData could not be retrievedN/A
    unknownNo recent data available> 60 minutes old

    In the UI, unknown is displayed instead of 0% to avoid confusion when data is missing.

  12. Use Codex 5.3 via backend mapping

    main

    If OpenCode does not natively list openai/gpt-5.3-codex, this plugin provides backend mapping. By default, selecting openai/gpt-5.2-codex or openai/gpt-5-codex will automatically route requests to gpt-5.3-codex.

    Configuration via Environment Variables

    • OPENCODE_MULTI_AUTH_PREFER_CODEX_LATEST=0: Disables mapping.
    • OPENCODE_MULTI_AUTH_CODEX_LATEST_MODEL=gpt-5.3-codex: Overrides the target model.
    • OPENCODE_MULTI_AUTH_DEBUG=1: Enables debug logging for mapping operations.

    Verify Mapping

    You can verify the mapping works by running the opencode-cli with debug flags enabled:

    OPENCODE_MULTI_AUTH_DEBUG=1 \
OPENCODE_MULTI_AUTH_CODEX_LATEST_MODEL=gpt-5.3-codex \
/Applications/OpenCode.app/Contents/MacOS/opencode-cli run \
  -m openai/gpt-5.2-codex "Reply ONLY with OK." \
  --print-logs --log-level INFO

    Expected Log Output: model map: gpt-5.2-codex -> gpt-5.3-codex