Configuring AI providers

Claude Octopus orchestrates up to three AI providers: Codex (OpenAI), Gemini (Google), and Claude (Anthropic). This guide covers authentication, cost awareness, and provider selection.

Provider roles

Each provider has a distinct role in multi-AI workflows:

Codex (OpenAI)

🔴 Implementation depth

Code patterns and technical analysis
Architecture decisions
Framework-specific guidance
Debugging assistance

Gemini (Google)

🟡 Ecosystem breadth

Alternatives and market trends
Security review perspectives
Research synthesis
Community insights

Claude (Anthropic)

🔵 Orchestration

Quality gates and validation
Consensus building
Final synthesis
Strategic guidance

Providers run in parallel for research, sequentially for problem scoping, and adversarially for review.

Provider authentication

Claude Octopus supports two authentication methods: OAuth (recommended) and API keys.

OAuth (recommended)

OAuth uses your existing AI subscriptions—no per-token billing.

Codex
Gemini
Claude

Authentication:

codex login

What you need:

Active ChatGPT subscription (Plus, Team, or Enterprise)
Codex CLI installed

Cost:

Included in ChatGPT subscription
No additional per-token charges

OAuth credentials stored:

~/.codex/auth.json

Installation:

# macOS
brew install codex-cli

# Linux
curl -fsSL https://codex.dev/install.sh | sh

Authentication:

gemini auth

What you need:

Google account with AI subscription
Gemini CLI installed

Cost:

Included in AI subscription
No additional per-token charges

OAuth credentials stored:

~/.gemini/oauth_creds.json

Installation:

# macOS
brew install gemini-cli

# Linux
curl -fsSL https://gemini.dev/install.sh | sh

API keys

API keys use per-token billing—you pay for each API call.

Codex
Gemini
Claude

Set environment variable:

export OPENAI_API_KEY="sk-..."

Get API key:

Visit platform.openai.com/api-keys
Create new secret key
Add to environment variables

Cost (per-token billing):

GPT-5.3-Codex: $1.75/$ 14 per MTok input/output
Estimated: ~$0.02-0.10 per query

Add to shell profile:

# ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY="sk-..."

Set environment variable:

export GEMINI_API_KEY="..."
# or
export GOOGLE_API_KEY="..."

Get API key:

Visit aistudio.google.com/apikey
Create API key
Add to environment variables

Cost (per-token billing):

Gemini Pro: ~$0.01-0.03 per query
Flash mode: cheaper for simple queries

Add to shell profile:

# ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="..."

OAuth vs API keys: OAuth users pay nothing beyond existing subscriptions. API key users pay per token. If you have ChatGPT Plus or Google AI subscriptions, use OAuth.

What works with just Claude

Claude Octopus works with zero external providers. You get every feature on day one: Single-provider features:

✅ All 33 personas
✅ Structured workflows (discover, define, develop, deliver)
✅ Smart routing (/octo command)
✅ Context detection
✅ Every skill
✅ Quality gates
✅ Command composition

Multi-AI features activate when external providers are configured:

Parallel research (Codex + Gemini + Claude)
Adversarial debate (three-way)
Cross-model review (consensus building)
Provider-specific strengths (implementation depth + ecosystem breadth)

Running without external providers

# Check provider status
/octo:setup

Output:

Claude Octopus Setup Status

Providers:
  Claude: ✓ Available (built-in)
  Codex CLI: ✗ Not installed
  Gemini CLI: ✗ Not installed

Single-provider mode active.
All workflows available with Claude.
Add Codex or Gemini for multi-AI features.

Workflows adapt automatically:

Research phase uses Claude only (no parallel multi-AI research)
Consensus building uses Claude reasoning (no cross-model debate)
Review uses Claude quality gates (no adversarial cross-checking)

Adding Codex and Gemini

Add external providers to unlock multi-AI orchestration.

Install CLIs

Install Codex and/or Gemini CLIs:

# macOS
brew install codex-cli gemini-cli

# Linux
curl -fsSL https://codex.dev/install.sh | sh
curl -fsSL https://gemini.dev/install.sh | sh

Authenticate

Choose OAuth (recommended) or API keys:OAuth:

codex login
gemini auth

API keys:

export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."

Verify setup

Run setup to verify providers:

/octo:setup

Expected output:

Claude Octopus Setup Status

Providers:
  Claude: ✓ Available (built-in)
  Codex CLI: ✓ Available (OAuth)
  Gemini CLI: ✓ Available (OAuth)

Multi-AI mode active ✓
All workflows ready.

Try: /octo research OAuth patterns

Cost awareness and provider selection

Claude Octopus provides full cost transparency with visual indicators and smart routing.

Visual indicators

When multi-AI workflows run, you’ll see exactly which providers are active:

🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider research mode
🔍 Discover Phase: Researching OAuth authentication patterns

Providers:
🔴 Codex CLI - Technical implementation analysis
🟡 Gemini CLI - Ecosystem and community research  
🔵 Claude - Strategic synthesis

Indicator reference:

Indicator	Provider	Cost Source
🔴	Codex CLI	Your OPENAI_API_KEY or ChatGPT subscription
🟡	Gemini CLI	Your GEMINI_API_KEY or Google AI subscription
🔵	Claude	Included with Claude Code subscription
🐙	Multi-AI mode	Multiple providers active

Visual indicators appear before workflows start. If you see external provider indicators (🔴 🟡), those will hit your API keys or subscriptions.

Cost comparison

Codex (OpenAI)

Models:

GPT-5.3-Codex: $1.75/$ 14 per MTok input/output
Spark: 15x faster than standard
Mini: ~ $0.30/$ 1.25 per MTok

Estimated cost per query:

Simple: ~$0.01-0.02
Complex: ~$0.05-0.10
With context: ~$0.10-0.15

Best for:

Technical implementation analysis
Code generation
Framework-specific guidance

Gemini (Google)

Models:

Gemini Pro: Standard model
Flash: Faster, cheaper for simple queries

Estimated cost per query:

Simple: ~$0.01
Complex: ~$0.02-0.03

Best for:

Ecosystem research
Market trends
Alternative approaches

Claude (Anthropic)

Models:

Sonnet 4.6: Included with Claude Code subscription
Opus 4.6: $5/$ 25 per MTok input/output
Opus 4.6 Fast: $30/$ 150 per MTok (6x cost, lower latency)

Cost:

Sonnet: Included (no additional cost)
Opus: Extra-usage billing
Fast Opus: 6x more expensive (use sparingly)

Best for:

Orchestration and synthesis
Quality gates
Consensus building

Smart cost routing

Claude Octopus routes to the cheapest provider that can handle the job. Routing logic:

Simple tasks → Claude Sonnet (free with subscription)
Technical implementation → Codex if available, else Claude Opus
Ecosystem research → Gemini if available, else Claude Sonnet
Complex reasoning → Claude Opus or Codex depending on task
Interactive queries → Fast mode only when user is actively waiting

Override routing:

# Force specific provider
export OCTOPUS_CODEX_MODEL="claude-opus-4-6"
/octo research advanced ML architectures
# → Uses Opus instead of Codex

# Disable external providers temporarily
export OCTOPUS_DISABLE_CODEX=true
export OCTOPUS_DISABLE_GEMINI=true
/octo research OAuth patterns
# → Uses Claude only

Fast Opus mode (Claude Code v2.1.36+)

Fast Opus is 6x more expensive than standard Opus (

30/

150 per MTok vs

5/

25). It provides lower latency but identical quality.

When fast mode is used:

Interactive single-shot Opus queries where user is actively waiting
Never in autonomous/background mode (no human waiting = no latency benefit)

Default behavior:

Standard mode for all multi-phase workflows
Fast mode only for interactive queries

Override:

# Force fast everywhere (costly!)
export OCTOPUS_OPUS_MODE=fast

# Force standard everywhere
export OCTOPUS_OPUS_MODE=standard

Cost estimation

Typical workflow costs:

Workflow	Providers	Estimated Cost
`/octo:discover`	Claude only	$0 (included)
`/octo:discover`	Codex + Gemini + Claude	~$0.05-0.15
`/octo:debate`	Codex + Gemini + Claude	~$0.10-0.30
`/octo:embrace`	Claude only	$0 (included)
`/octo:embrace`	Codex + Gemini + Claude	~$0.30-0.80
`/octo:factory`	Codex + Gemini + Claude	~$0.50-2.00

OAuth users with ChatGPT Plus and Google AI subscriptions pay $0 beyond their subscriptions for Codex and Gemini queries.

Provider configuration reference

Environment variables

# Authentication (API key method)
OPENAI_API_KEY="sk-..."              # Codex API key
GEMINI_API_KEY="..."                 # Gemini API key
GOOGLE_API_KEY="..."                 # Alternative to GEMINI_API_KEY

# Provider control
OCTOPUS_DISABLE_CODEX=true           # Disable Codex temporarily
OCTOPUS_DISABLE_GEMINI=true          # Disable Gemini temporarily

# Model selection
OCTOPUS_CODEX_MODEL="gpt-5.3-codex" # Override Codex model
OCTOPUS_GEMINI_MODEL="gemini-pro"    # Override Gemini model
OCTOPUS_OPUS_MODE="standard"         # Claude Opus mode (standard/fast)

# Timeout configuration
CODEX_TIMEOUT=120                     # Codex timeout in seconds
GEMINI_TIMEOUT=120                    # Gemini timeout in seconds

Provider detection

Check which providers are available:

# System check
/octo:doctor providers

# Full diagnostics
/octo:doctor

Output:

Provider Status:
  Claude Code: v2.1.50 ✓
  Codex CLI: v1.2.3 ✓ (OAuth authenticated)
  Gemini CLI: v0.8.1 ✓ (API key configured)

Authentication:
  Codex: OAuth via ~/.codex/auth.json ✓
  Gemini: API key via GEMINI_API_KEY ✓
  Claude: Built-in ✓

Next steps

Using commands

Learn command structure, the smart router, and the top 8 commands

Working with workflows

Understand workflow progression, quality gates, and autonomy modes

Configuration

Environment variables, settings, and custom hooks

Visual indicators

Deep dive into cost transparency and provider status

Get Started

Core Concepts

Guides

Configuring AI providers

Configuring AI providers

Provider roles

Codex (OpenAI)

Gemini (Google)

Claude (Anthropic)

Provider authentication

OAuth (recommended)

API keys

What works with just Claude

Running without external providers

Adding Codex and Gemini

Cost awareness and provider selection

Visual indicators

Cost comparison

Smart cost routing

Fast Opus mode (Claude Code v2.1.36+)

Cost estimation

Provider configuration reference

Environment variables

Provider detection

Next steps

Using commands

Working with workflows

Configuration

Visual indicators

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Configuring AI providers

​Provider roles

Codex (OpenAI)

Gemini (Google)

Claude (Anthropic)

​Provider authentication

​OAuth (recommended)

​API keys

​What works with just Claude

​Running without external providers

​Adding Codex and Gemini

​Cost awareness and provider selection

​Visual indicators

​Cost comparison

​Smart cost routing

​Fast Opus mode (Claude Code v2.1.36+)

​Cost estimation

​Provider configuration reference

​Environment variables

​Provider detection

​Next steps

Using commands

Working with workflows

Configuration

Visual indicators

Build docs developers (and LLMs) love

Configuring AI providers

Provider roles

Provider authentication

OAuth (recommended)

API keys

What works with just Claude

Running without external providers

Adding Codex and Gemini

Cost awareness and provider selection

Visual indicators

Cost comparison

Smart cost routing

Fast Opus mode (Claude Code v2.1.36+)

Cost estimation

Provider configuration reference

Environment variables

Provider detection

Next steps