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

> Learn how to configure OpenClaude for OpenAI, Anthropic, or Gemini. This guide covers complete provider setup using profiles for seamless AI model switching.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts) (line 56), [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/scripts/provider-launch.ts) (`parseLaunchOptions`, lines 34-57) |
| **Environment variables** | CI/CD pipelines, temporary keys | [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) (lines 61-130), [`services/api/providerConfig.ts`](https://github.com/Gitlawb/openclaude/blob/main/services/api/providerConfig.ts) (`resolveProviderRequest`, lines 65-70) |
| **Persistent profile file** | Daily development, default preferences | [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) and defines each vendor's metadata:

```ts
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts) at line 56. The launch script [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/scripts/provider-launch.ts) parses this via `parseLaunchOptions` (lines 34-57) and prints a summary via `printSummary` (lines 24-38).

### OpenAI Quick Start

```bash
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

```bash
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

```bash
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) (lines 61-130). The `resolveProviderRequest` function automatically hydrates provider configurations from `process.env`.

### Complete OpenAI Environment Setup

```bash
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

```bash
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

```bash
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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) (line 52). Loading happens via `loadPersistedProfile` in [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/scripts/provider-launch.ts) (lines 80-82).

### Create an Anthropic Default Profile

```bash
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:

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

```

### Create an OpenAI Default Profile

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

```

### Create a Gemini Default Profile

```json
{
  "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`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) with a unique `id` and `envVars`
2. Set the corresponding environment variables or add them to [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.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`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) define metadata for OpenAI, Anthropic, Gemini, and extensible custom vendors
- **`resolveProviderRequest`** in [`services/api/providerConfig.ts`](https://github.com/Gitlawb/openclaude/blob/main/services/api/providerConfig.ts) merges configuration sources into a unified request object
- **Required environment variables** are catalogued in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) (lines 61-130) and validated at runtime
- **Launch script entry point** at [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.