opencode-codex-auth

OpenCode plugin for OpenAI ChatGPT OAuth with multi-account management, Codex-compatible request modes, and dynamic model behavior controls.

Quick links: Getting Started · Configuration · Multi-account · Troubleshooting · Persona Tool

Why this plugin

• Uses ChatGPT OAuth instead of API keys for OpenAI provider flows.
• Keeps account rotation state in a plugin-owned store (codex-accounts.json).
• Supports native and codex runtime modes.
• Adds account-manager UX to opencode auth login (quotas, toggles, scoped deletes, transfer).

Quick start

Install and register the plugin (recommended):

npx -y @iam-brain/opencode-codex-auth@latest

Then authenticate:

opencode auth login

Use an OpenAI model through OpenCode:

opencode run "say hi" --model=openai/gpt-5

If that model is unavailable on your account, use any available openai/* model.

Usage notice

This plugin is intended for personal development use with your own ChatGPT account. For production multi-user systems, use the OpenAI Platform API.

Install behavior

By default, npx -y @iam-brain/opencode-codex-auth runs the installer.

The installer does four things:

1. Ensures @iam-brain/opencode-codex-auth@latest is present in ~/.config/opencode/opencode.json.
2. Creates ~/.config/opencode/codex-config.json with defaults when missing.
3. Synchronizes ~/.config/opencode/commands/create-personality.md for /create-personality (created/updated as needed).
4. Synchronizes ~/.config/opencode/skills/personality-builder/SKILL.md (plus references) for skill-driven personality workflows.

At plugin startup, managed templates are synchronized to the latest version:

• /create-personality command template
• personality-builder skill bundle

Re-run installer (idempotent):

npx -y @iam-brain/opencode-codex-auth install

Config split

Keep opencode.json minimal (plugin enablement only). Put runtime behavior in:

• ~/.config/opencode/codex-config.json

Canonical config/env docs (complete key + variable reference) are in docs/configuration.md.

Schemas for user-edited JSON files are in:

• schemas/codex-config.schema.json
• schemas/opencode.schema.json
• schemas/codex-accounts.schema.json (advanced/manual recovery)

Personality files live in lowercase directories:

• project-local: .opencode/personalities/
• global: ~/.config/opencode/personalities/

Create guided custom personalities with:

/create-personality

Runtime modes

• native: native-plugin style identity/headers.
• codex: codex-rs style identity/headers.

Account storage

• Provider auth marker: ~/.local/share/opencode/auth.json
• Plugin multi-account store: ~/.config/opencode/codex-accounts.json
• Session affinity cache: ~/.config/opencode/cache/codex-session-affinity.json
• Quota snapshot cache: ~/.config/opencode/cache/codex-snapshots.json

Legacy sources can be imported explicitly from the auth menu:

• ~/.config/opencode/openai-codex-accounts.json
• ~/.local/share/opencode/auth.json

Documentation

• Docs portal
• Getting started
• Configuration
• Compaction
• Multi-account
• Troubleshooting
• Persona tool
• Development docs
• Upstream baseline/sync

Development

npm install
npm run verify