9.2 KiB
Getting Started
Complete installation and setup guide for the OpenCode OpenAI Codex Auth Plugin.
⚠️ Before You Begin
This plugin is for personal development use only. It uses OpenAI's official OAuth authentication for individual coding assistance with your ChatGPT Plus/Pro subscription.
Not intended for: Commercial services, API resale, multi-user applications, or any use that violates OpenAI's Terms of Use.
For production applications, use the OpenAI Platform API.
Prerequisites
- OpenCode installed (installation guide)
- ChatGPT Plus or Pro subscription (required for Codex access)
- Node.js 18+ (for OpenCode)
Installation
Step 1: Add Plugin to Config
OpenCode automatically installs plugins - no npm install needed!
Choose your configuration style:
Option A: Full Configuration (Recommended)
Get 9 pre-configured model variants with optimal settings.
Add this to ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-openai-codex-auth"],
"provider": {
"openai": {
"options": {
"reasoningEffort": "medium",
"reasoningSummary": "auto",
"textVerbosity": "medium",
"include": ["reasoning.encrypted_content"],
"store": false
},
"models": {
"gpt-5-codex-low": {
"name": "GPT 5 Codex Low (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "low",
"reasoningSummary": "auto",
"textVerbosity": "medium",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-codex-medium": {
"name": "GPT 5 Codex Medium (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "medium",
"reasoningSummary": "auto",
"textVerbosity": "medium",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-codex-high": {
"name": "GPT 5 Codex High (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "high",
"reasoningSummary": "detailed",
"textVerbosity": "medium",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-minimal": {
"name": "GPT 5 Minimal (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "minimal",
"reasoningSummary": "auto",
"textVerbosity": "low",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-low": {
"name": "GPT 5 Low (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "low",
"reasoningSummary": "auto",
"textVerbosity": "low",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-medium": {
"name": "GPT 5 Medium (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "medium",
"reasoningSummary": "auto",
"textVerbosity": "medium",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-high": {
"name": "GPT 5 High (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "high",
"reasoningSummary": "detailed",
"textVerbosity": "high",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-mini": {
"name": "GPT 5 Mini (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "low",
"reasoningSummary": "auto",
"textVerbosity": "low",
"include": ["reasoning.encrypted_content"],
"store": false
}
},
"gpt-5-nano": {
"name": "GPT 5 Nano (OAuth)",
"limit": {
"context": 272000,
"output": 128000
},
"options": {
"reasoningEffort": "minimal",
"reasoningSummary": "auto",
"textVerbosity": "low",
"include": ["reasoning.encrypted_content"],
"store": false
}
}
}
}
}
}
What you get:
- ✅ GPT-5 Codex (Low/Medium/High reasoning)
- ✅ GPT-5 (Minimal/Low/Medium/High reasoning)
- ✅ gpt-5-mini, gpt-5-nano (lightweight variants)
- ✅ 272k context + 128k output window for every preset
- ✅ All visible in OpenCode model selector
- ✅ Optimal settings for each reasoning level
Prompt caching is enabled out of the box: when OpenCode sends its session identifier as prompt_cache_key, the plugin forwards it untouched so multi-turn runs reuse prior work. The plugin no longer synthesizes cache IDs; if the host omits that field, Codex treats the run as uncached. The CODEX_MODE bridge prompt bundled with the plugin is kept in sync with the latest Codex CLI release, so the OpenCode UI and Codex share the same tool contract. If you hit your ChatGPT subscription limits, the plugin returns a friendly Codex-style message with the 5-hour and weekly usage windows so you know when capacity resets.
Heads up: OpenCode's context auto-compaction and usage sidebar only work when this full configuration is installed. The minimal configuration skips the per-model limits, so OpenCode cannot display token usage or compact history automatically.
Option B: Minimal Configuration
Just want to get started quickly?
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-openai-codex-auth"],
"model": "openai/gpt-5-codex"
}
Save to ~/.config/opencode/opencode.json
Trade-off: Uses default settings (medium reasoning), no model variants in selector.
Step 2: Authenticate
opencode auth login
- Select "OpenAI"
- Choose "ChatGPT Plus/Pro (Codex Subscription)"
- Browser opens automatically for OAuth flow
- Log in with your ChatGPT account
- Done! Token saved to
~/.opencode/auth/openai.json
⚠️ Important: If you have the official Codex CLI running, stop it first (both use port 1455 for OAuth callback).
Step 3: Test It
# Quick test
opencode run "write hello world to test.txt" --model=openai/gpt-5-codex
# Or start interactive session
opencode
If using full config, you'll see all 9 variants in the model selector!
Configuration Locations
OpenCode checks multiple config files in order:
- Project config:
./.opencode.json(current directory) - Parent configs: Walks up directory tree
- Global config:
~/.config/opencode/opencode.json
Recommendation: Use global config for plugin, project config for model/agent overrides.
⚠️ Updating the Plugin (Important!)
OpenCode does NOT automatically update plugins.
When a new version is released, you must manually update:
# Step 1: Clear plugin cache
(cd ~ && sed -i.bak '/"opencode-openai-codex-auth"/d' .cache/opencode/package.json && rm -rf .cache/opencode/node_modules/opencode-openai-codex-auth)
# Step 2: Restart OpenCode - it will reinstall the latest version
opencode
When to update:
- New features released
- Bug fixes available
- Security updates
Check for updates: Releases Page
Pro tip: Subscribe to release notifications on GitHub to get notified of updates.
Local Development Setup
For plugin development or testing unreleased changes:
{
"plugin": ["file:///absolute/path/to/opencode-openai-codex-auth/dist"]
}
Note: Must point to dist/ folder (built output), not root.
Build the plugin:
cd opencode-openai-codex-auth
npm install
npm run build
Verifying Installation
Check Plugin is Loaded
opencode --version
# Should not show any plugin errors
Check Authentication
cat ~/.opencode/auth/openai.json
# Should show OAuth credentials (if authenticated)
Test API Access
# Enable logging to verify requests
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex
# Check logs
ls ~/.opencode/logs/codex-plugin/
# Should show request logs
Next Steps
- Configuration Guide - Advanced config options
- Troubleshooting - Common issues and solutions
- Developer Docs - Technical deep dive
Back to: Documentation Home