opencode-openai-codex-auth/docs/configuration.md

Configuration Guide

Complete reference for configuring the OpenCode OpenAI Codex Auth Plugin.

Quick Reference

{
  "$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
          }
        }
      }
    }
  }
}

---

Configuration Options

reasoningEffort

Controls computational effort for reasoning.

GPT-5 Values:

• minimal - Fastest, least reasoning
• low - Light reasoning
• medium - Balanced (default)
• high - Deep reasoning

GPT-5-Codex Values:

• low - Fastest for code
• medium - Balanced (default)
• high - Maximum code quality

Notes:

• minimal auto-converts to low for gpt-5-codex (API limitation)
• gpt-5-codex-mini* only supports medium or high; lower settings are clamped to medium

Example:

{
  "options": {
    "reasoningEffort": "high"
  }
}

reasoningSummary

Controls reasoning summary verbosity.

Values:

• auto - Automatically adapts (default)
• detailed - Verbose summaries

Example:

{
  "options": {
    "reasoningSummary": "detailed"
  }
}

textVerbosity

Controls output length.

GPT-5 Values:

• low - Concise
• medium - Balanced (default)
• high - Verbose

GPT-5-Codex:

• medium only (API limitation)

Example:

{
  "options": {
    "textVerbosity": "high"
  }
}

include

Array of additional response fields to include.

Default: ["reasoning.encrypted_content"]

Why needed: Enables multi-turn conversations with store: false (stateless mode)

Example:

{
  "options": {
    "include": ["reasoning.encrypted_content"]
  }
}

store

Controls server-side conversation persistence.

⚠️ Required: false (for AI SDK 2.0.50+ compatibility)

Values:

• false - Stateless mode (required for Codex API)
• true - Server-side storage (not supported by Codex API)

Why required: AI SDK 2.0.50+ automatically uses item_reference items when store: true. The Codex API requires stateless operation (store: false), where references cannot be resolved.

Example:

{
  "options": {
    "store": false
  }
}

Note: The plugin automatically injects this via a chat.params hook, but explicit configuration is recommended for clarity.

---

Configuration Patterns

Pattern 1: Global Options

Apply same settings to all models:

{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "high",
        "store": false
      }
    }
  }
}

Use when: You want consistent behavior across all models.

Pattern 2: Per-Model Options

Different settings for different models:

{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "store": false
      },
      "models": {
        "gpt-5-codex-fast": {
          "name": "Fast Codex",
          "options": {
            "reasoningEffort": "low",
            "store": false
          }
        },
        "gpt-5-codex-smart": {
          "name": "Smart Codex",
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed",
            "store": false
          }
        }
      }
    }
  }
}

Use when: You want quick-switch presets for different tasks.

Precedence: Model options override global options.

Pattern 3: Config Key vs Name

Understanding the fields:

{
  "models": {
    "my-custom-id": {           // ← Config key (used everywhere)
      "name": "My Display Name",  // ← Shows in TUI
      "options": { ... }
    }
  }
}

• Config key (my-custom-id): Used in CLI, config lookups, TUI persistence
• name field: Friendly display name in model selector
• id field: DEPRECATED - not used by OpenAI provider

Example Usage:

# Use the config key in CLI
opencode run "task" --model=openai/my-custom-id

# TUI shows: "My Display Name"

See development/CONFIG_FIELDS.md for complete explanation.

---

Advanced Scenarios

Scenario: Quick Switch Presets

Create named variants for common tasks:

{
  "models": {
    "codex-quick": {
      "name": "⚡ Quick Code",
      "options": {
        "reasoningEffort": "low",
        "store": false
      }
    },
    "codex-balanced": {
      "name": "⚖️ Balanced Code",
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    },
    "codex-quality": {
      "name": "🎯 Max Quality",
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "store": false
      }
    }
  }
}

Scenario: Per-Agent Models

Different agents use different models:

{
  "agent": {
    "commit": {
      "model": "openai/codex-quick",
      "prompt": "Generate concise commit messages"
    },
    "review": {
      "model": "openai/codex-quality",
      "prompt": "Thorough code review"
    }
  }
}

Scenario: Project-Specific Overrides

Global config has defaults, project overrides for specific work:

~/.config/opencode/opencode.json (global):

{
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    }
  }
}

my-project/.opencode.json (project):

{
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high",
        "store": false
      }
    }
  }
}

Result: Project uses high, other projects use medium.

---

Plugin Configuration

Advanced plugin settings in ~/.opencode/openai-codex-auth-config.json:

{
  "codexMode": true
}

CODEX_MODE

What it does:

• true (default): Uses Codex-OpenCode bridge prompt (Task tool & MCP aware)
• false: Uses legacy tool remap message
• Bridge prompt content is synced with the latest Codex CLI release (ETag-cached)

When to disable:

• Compatibility issues with OpenCode updates
• Testing different prompt styles
• Debugging tool call issues

Override with environment variable:

CODEX_MODE=0 opencode run "task"  # Temporarily disable
CODEX_MODE=1 opencode run "task"  # Temporarily enable

Prompt caching

• When OpenCode provides a prompt_cache_key (its session identifier), the plugin forwards it directly to Codex.
• The same value is sent via headers (conversation_id, session_id) and request body, reducing latency and token usage.
• The plugin does not synthesize a fallback key; hosts that omit prompt_cache_key will see uncached behaviour until they provide one.
• No configuration needed—cache headers are injected during request transformation.

Usage limit messaging

• When the ChatGPT subscription hits a limit, the plugin returns a Codex CLI-style summary (5-hour + weekly windows).
• Messages bubble up in OpenCode exactly where SDK errors normally surface.
• Helpful when working inside the OpenCode UI or CLI—users immediately see reset timing.

---

Configuration Files

Provided Examples:

• config/full-opencode.json - Complete with 11 variants (adds Codex Mini presets)
• config/minimal-opencode.json - Minimal setup

Why choose the full config? OpenCode's auto-compaction and usage widgets rely on the per-model limit metadata present only in full-opencode.json. Use the minimal config only if you don't need those UI features.

Your Configs:

• ~/.config/opencode/opencode.json - Global config
• <project>/.opencode.json - Project-specific config
• ~/.opencode/openai-codex-auth-config.json - Plugin config

---

Validation

Check Config is Valid

# OpenCode will show errors if config is invalid
opencode

Verify Model Resolution

# Enable debug logging
DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model-name

Look for:

[openai-codex-plugin] Model config lookup: "your-model-name" → normalized to "gpt-5-codex" for API {
  hasModelSpecificConfig: true,
  resolvedConfig: { ... }
}

Test Per-Model Options

# Run with different models, check logs show different options
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex-low
ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5-codex-high

# Compare reasoning.effort in logs
cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '.reasoning.effort'

---

Migration Guide

From Old Config Names

Old verbose names still work:

{
  "models": {
    "GPT 5 Codex Low (ChatGPT Subscription)": {
      "id": "gpt-5-codex",
      "options": { "reasoningEffort": "low" }
    }
  }
}

Recommended update (cleaner CLI usage):

{
  "models": {
    "gpt-5-codex-low": {
      "name": "GPT 5 Codex Low (OAuth)",
      "options": {
        "reasoningEffort": "low",
        "store": false
      }
    }
  }
}

Benefits:

• Cleaner: --model=openai/gpt-5-codex-low
• Matches Codex CLI preset names
• No redundant id field

---

Common Patterns

Pattern: Task-Based Presets

{
  "models": {
    "quick-chat": {
      "name": "Quick Chat",
      "options": {
        "reasoningEffort": "minimal",
        "textVerbosity": "low",
        "store": false
      }
    },
    "code-gen": {
      "name": "Code Generation",
      "options": {
        "reasoningEffort": "medium",
        "store": false
      }
    },
    "debug-help": {
      "name": "Debug Analysis",
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "store": false
      }
    }
  }
}

Pattern: Cost vs Quality

{
  "models": {
    "economy": {
      "name": "Economy Mode",
      "options": {
        "reasoningEffort": "low",
        "textVerbosity": "low",
        "store": false
      }
    },
    "premium": {
      "name": "Premium Mode",
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "high",
        "store": false
      }
    }
  }
}

---

Troubleshooting Config

Model Not Found

Error: Model 'openai/my-model' not found

Cause: Config key doesn't match model name in command

Fix: Use exact config key:

{ "models": { "my-model": { ... } } }

opencode run "test" --model=openai/my-model  # Must match exactly

Per-Model Options Not Applied

Check: Is config key used for lookup?

DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model

Look for hasModelSpecificConfig: true in debug output.

Options Ignored

Cause: Model normalizes before lookup

Example Problem:

{ "models": { "gpt-5-codex": { "options": { ... } } } }

--model=openai/gpt-5-codex-low  # Normalizes to "gpt-5-codex" before lookup

Fix: Use exact name you specify in CLI as config key.

---

Next: Troubleshooting | Back to Documentation Home