Skip to content

getting-started.md

Latest commit

 

History

History
204 lines (138 loc) · 6.03 KB

getting-started.md

File metadata and controls

204 lines (138 loc) · 6.03 KB

Getting Started

This guide covers the full installation and first-run flow for oc-codex-multi-auth.

Before You Begin

Caution

This plugin is for personal development use with your own ChatGPT Plus/Pro subscription.

  • It is not intended for commercial resale, shared multi-user access, or production services.
  • It uses official OAuth authentication, but it is an independent open-source project and is not affiliated with OpenAI.
  • For production applications, use the OpenAI Platform API.

Prerequisites

Requirement Notes
OpenCode Install from opencode.ai
ChatGPT Plus or Pro Required for OAuth access and model entitlements
Node.js 20+ Needed for local OpenCode runtime and plugin installation

Fastest Install Path

npx -y oc-codex-multi-auth@latest
opencode auth login
opencode run "Explain this repository" --model=openai/gpt-5.4 --variant=medium

The installer updates ~/.config/opencode/opencode.json, backs up the previous config, normalizes the plugin entry to oc-codex-multi-auth, and clears the cached plugin copy so OpenCode reinstalls the latest package.

By default, the installer writes a full catalog config so you get both:

  • modern base model entries such as gpt-5.4 for --variant workflows
  • explicit preset entries such as gpt-5.4-high so the full shipped catalog is visible directly in pickers

If you prefer the compact variant-only config on OpenCode v1.0.210+, use:

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

If you explicitly want the older explicit-only layout, use:

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

Install from Source

Use this only when you want to develop or test the plugin locally.

git clone https://github.com/ndycode/oc-codex-multi-auth.git
cd oc-codex-multi-auth
npm ci
npm run build

Point OpenCode at the built plugin:

{
  "plugin": ["file:///absolute/path/to/oc-codex-multi-auth/dist"]
}

Use the built dist/ directory, not the repository root.

Authentication

Run:

opencode auth login

Then choose:

  1. OpenAI
  2. Codex OAuth (ChatGPT Plus/Pro)

The browser-based OAuth flow uses the same local callback port as Codex CLI: http://127.0.0.1:1455/auth/callback.

Remote or Headless Login

If you are on SSH, WSL, or another environment where the browser callback flow is inconvenient:

  1. rerun opencode auth login
  2. choose Codex OAuth (Device Code)
  3. open the verification link, enter the one-time code, and wait for login to finish
  4. if device code is unavailable on your auth server, fall back to Codex OAuth (Manual URL Paste)

Add the Plugin to OpenCode

If you are not using the installer, edit ~/.config/opencode/opencode.json manually:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oc-codex-multi-auth"]
}

Choose a Config Template

The repository ships two supported templates:

OpenCode version Template
v1.0.210+ config/opencode-modern.json
v1.0.209 and earlier config/opencode-legacy.json

The templates include the supported GPT-5/Codex families, required store: false handling, and reasoning.encrypted_content for multi-turn sessions. Current templates expose 9 shipped base model families and 34 shipped presets overall (34 modern variants or 34 legacy explicit entries).

On OpenCode v1.0.210+, the modern template intentionally shows 9 base model entries because the additional presets are selected through --variant instead of separate model keys.

gpt-5.4-pro ships in the templates but can still be entitlement-gated by your workspace. Add entitlement-gated Spark variants manually only when your workspace supports them.

Verify the Setup

Run one of these commands:

# Modern OpenCode
opencode run "Create a short TODO list for this repo" --model=openai/gpt-5.4 --variant=medium
opencode run "Inspect the retry logic and summarize it" --model=openai/gpt-5-codex --variant=high

# Legacy OpenCode
opencode run "Create a short TODO list for this repo" --model=openai/gpt-5.4-medium

If you want to verify request routing, run a request with logging enabled:

ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.4

The first request should create logs under ~/.opencode/logs/codex-plugin/.

Use opencode debug config when you want to verify that template-defined or custom models were merged into your effective config. opencode models openai currently shows OpenCode's built-in provider catalog and can omit config-defined entries such as gpt-5.4-mini.

Multi-Account Setup

The plugin can manage multiple ChatGPT accounts and choose the healthiest account or workspace for each request.

After your first successful login, you can add more accounts by running opencode auth login again or by using the guided commands below.

Guided Onboarding Commands

These commands are useful after installation:

codex-setup
codex-help topic="setup"
codex-doctor
codex-next

Notes:

  • codex-switch, codex-label, and codex-remove can show interactive account pickers when index is omitted in a supported terminal.
  • The plugin can show a startup preflight summary with the current account health state and suggested next step.

Beginner Safe Mode

If you want conservative retry behavior while learning the workflow, enable beginner safe mode:

{
  "beginnerSafeMode": true
}

Or via environment variable:

CODEX_AUTH_BEGINNER_SAFE_MODE=1 opencode

This mode forces a more conservative retry profile and reduces the chance of long retry loops while you are debugging setup issues.

Update the Plugin

From npm:

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

From a local clone:

git pull
npm ci
npm run build

Next Reading