How to Configure OpenClaude for OpenAI, Anthropic, or Gemini: Complete Provider Setup Guide

OpenClaude uses provider profiles—configurations that specify the base URL, API key, and model name—to switch between AI vendors like OpenAI, Anthropic, and Gemini via CLI flags, environment variables, or a persistent JSON file.

OpenClaude abstracts every major AI vendor behind a reusable provider profile system. Whether you need Claude's reasoning, GPT-4's versatility, or Gemini's multimodal capabilities, you can configure OpenClaude to route requests to the right endpoint without modifying your core workflow. This guide walks through the three configuration methods supported by the Gitlawb/openclaude source code.

Provider Configuration Methods Overview

OpenClaude offers three interchangeable ways to set your AI backend. Each method targets a different use case, from one-off experiments to persistent defaults.

Method	Best For	Implementation Location
CLI flag --provider	Single-command overrides	web/src/data/cliFlags.ts (line 56), scripts/provider-launch.ts (parseLaunchOptions, lines 34-57)
Environment variables	CI/CD pipelines, temporary keys	src/utils/providerProfile.ts (lines 61-130), services/api/providerConfig.ts (resolveProviderRequest, lines 65-70)
Persistent profile file	Daily development, default preferences	src/utils/providerProfile.ts (line 52, loadProfileFile/saveProfileFile)

All three methods feed into the same resolution pipeline. The resolveProviderRequest function in services/api/providerConfig.ts (lines 65-70) merges these sources into a final ResolvedProviderRequest object containing transport, baseUrl, requestedModel, and resolvedModel.

Understanding Provider Definitions

Before configuring a specific vendor, it helps to understand how OpenClaude models providers internally. The static registry lives in web/src/data/providers.ts and defines each vendor's metadata:

export interface Provider {
  id: string;          // internal identifier: "openai", "anthropic", "gemini"
  name: string;        // human-readable display name
  group: ProviderGroup;
  setup: string;       // configuration instructions
  envVars?: string[];  // required environment variables
  notes: string;
}

The built-in registry includes:

• Anthropic/Claude — id: 'anthropic' (lines 53-59)
• OpenAI-compatible gateways — openrouter, llmtr, and others (lines 136-150)
• Gemini — accessible via opengateway group entries or direct gemini profile (provider-launch.ts, line 26)

You can extend this list with custom providers by adding entries with unique id values and required envVars.

Method 1: Configure via CLI Flag

The fastest way to switch providers is the --provider flag, defined in web/src/data/cliFlags.ts at line 56. The launch script scripts/provider-launch.ts parses this via parseLaunchOptions (lines 34-57) and prints a summary via printSummary (lines 24-38).

OpenAI Quick Start

export OPENAI_API_KEY="sk-your-key-here"
export OPENAI_MODEL="gpt-4o-mini"

bun run scripts/provider-launch.ts openai -- \
  chat "Refactor this Python function to use generators"

Anthropic Quick Start

export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export ANTHROPIC_MODEL="claude-3-5-sonnet-20240620"

bun run scripts/provider-launch.ts anthropic -- \
  chat "Refactor this Python function to use generators"

Gemini Quick Start

export GEMINI_API_KEY="AIza-your-key-here"
export GEMINI_MODEL="gemini-1.5-flash"

bun run scripts/provider-launch.ts gemini -- \
  chat "Refactor this Python function to use generators"

The first positional argument after provider-launch.ts becomes the requested profile. The double dash (--) separates launch options from command arguments.

Method 2: Configure via Environment Variables

For automation and ephemeral environments, set the variables defined in src/utils/providerProfile.ts (lines 61-130). The resolveProviderRequest function automatically hydrates provider configurations from process.env.

Complete OpenAI Environment Setup

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o-mini"
export OPENAI_BASE_URL="https://api.openai.com/v1"  # optional; uses default if omitted

Complete Anthropic Environment Setup

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-3-5-sonnet-20240620"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"  # optional

Complete Gemini Environment Setup

export GEMINI_API_KEY="AIza..."
export GEMINI_MODEL="gemini-1.5-flash"
export GEMINI_BASE_URL="https://generativelanguage.googleapis.com"  # optional

export GEMINI_ACCESS_TOKEN="ya29..."  # alternative to API key for OAuth flows

If required variables are missing, the resolver marks the provider unconfigured and the CLI emits a descriptive error before attempting any network calls.

Method 3: Persist a Default Provider Profile

For daily development, create ~/.openclaude-profile.json. The filename constant is exported from src/utils/providerProfile.ts (line 52). Loading happens via loadPersistedProfile in scripts/provider-launch.ts (lines 80-82).

Create an Anthropic Default Profile

cat > ~/.openclaude-profile.json << 'EOF'
{
  "profile": "anthropic",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-key-here",
    "ANTHROPIC_MODEL": "claude-3-5-sonnet-20240620"
  }
}
EOF

Now any invocation without --provider uses Anthropic automatically:

bun run scripts/provider-launch.ts -- chat "Explain monads in simple terms"

Create an OpenAI Default Profile

{
  "profile": "openai",
  "env": {
    "OPENAI_API_KEY": "sk-your-key-here",
    "OPENAI_MODEL": "gpt-4o"
  }
}

Create a Gemini Default Profile

{
  "profile": "gemini",
  "env": {
    "GEMINI_API_KEY": "AIza-your-key-here",
    "GEMINI_MODEL": "gemini-1.5-pro"
  }
}

The --provider auto default (implicit when omitted) triggers this file lookup.

Adding Custom or Private Providers

For internal endpoints or niche vendors, extend the provider system without forking:

1. Add a new entry to the providers array in web/src/data/providers.ts with a unique id and envVars
2. Set the corresponding environment variables or add them to .openclaude-profile.json
3. Invoke with bun run scripts/provider-launch.ts your-custom-id -- <command>

OpenClaude treats custom entries identically to built-ins—same resolution, same validation, same CLI integration.

Configuration Priority and Override Behavior

When multiple configuration sources exist, OpenClaude resolves them in this order (later sources override earlier ones):

1. Built-in defaults from DEFAULT_OPENAI_BASE_URL, DEFAULT_GEMINI_BASE_URL, etc.
2. Persisted profile from ~/.openclaude-profile.json
3. Environment variables from process.env
4. CLI flag --provider with explicit arguments

This hierarchy lets you set safe defaults while keeping override flexibility for special cases.

Summary

• Three configuration methods cover every workflow: CLI flags for one-offs, environment variables for automation, and ~/.openclaude-profile.json for persistent defaults
• Provider profiles in web/src/data/providers.ts define metadata for OpenAI, Anthropic, Gemini, and extensible custom vendors
• resolveProviderRequest in services/api/providerConfig.ts merges configuration sources into a unified request object
• Required environment variables are catalogued in src/utils/providerProfile.ts (lines 61-130) and validated at runtime
• Launch script entry point at scripts/provider-launch.ts handles --provider parsing and profile loading

Frequently Asked Questions

What happens if I don't set any API keys?

OpenClaude's resolveProviderRequest function detects missing required variables and marks the provider as unconfigured. The CLI prints a specific error message listing which envVars are needed for your selected provider, sourced from the provider registry in web/src/data/providers.ts.

Can I use different models from the same provider in different commands?

Yes. Set the *_MODEL environment variable per command, or maintain separate profile files and switch between them with --provider. The model name flows through requestedModel/resolvedModel in the ResolvedProviderRequest object built by services/api/providerConfig.ts.

Does OpenClaude support OpenAI-compatible proxies like Azure or LocalAI?

The openrouter and llmtr gateway entries in web/src/data/providers.ts (lines 136-150) demonstrate OpenAI-compatible transport patterns. For private proxies, create a custom provider entry with id: 'localai' and set OPENAI_BASE_URL (or your custom equivalent) to your proxy endpoint.

How do I verify which provider is active?

The printSummary function in scripts/provider-launch.ts (lines 24-38) logs the resolved profile, base URL, and model name on every launch. Check this output to confirm your configuration loaded correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}