# How to Set Up OpenClaude with Different LLM Providers: The Complete Configuration Guide

> Master OpenClaude setup with our guide. Learn to configure different LLM providers using IDs, environment variables, and interactive commands for seamless integration.

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

---

**OpenClaude uses a provider abstraction model where each LLM vendor is defined by an ID, group, and environment variables, configured via interactive commands, CLI flags, or `.env` files.**

Every LLM integration in OpenClaude flows through a unified provider system. According to the Gitlawb/openclaude source code, providers are not hardcoded connections but dynamic profiles stored in [`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) and resolved at runtime in [`src/utils/model/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/providers.ts). This architecture lets you switch between cloud APIs and local models without reinstalling the tool.

## Understanding the Provider Model

A **provider** in OpenClaude consists of five core properties defined in the catalog:

- **ID** – the machine name used with `--provider` (e.g., `openai`, `deepseek`, `ollama`)
- **Name** – human-readable label shown in interactive menus
- **Group** – categorization into `subscriptions`, `gateways`, `vendors`, `local`, or `custom`
- **Setup hint** – guidance shown during `/provider` configuration
- **Environment variables** – optional keys like `OPENAI_API_KEY` or `DEEPSEEK_API_KEY`

The full provider catalog lives in [`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) [[source]](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts). When OpenClaude launches, the resolution logic in [`src/utils/model/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/providers.ts) loads your selected profile from [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json) (or defaults) and merges any supplied environment variables.

## Setting Up Your First Provider

### Interactive Setup with `/provider`

The fastest path for most users is the built-in REPL wizard:

```bash
npm i -g openclaude   # or: bun install openclaude

openclaude

# Inside the REPL, type:

/provider

```

The `/provider` command prompts you to select from the catalog, then requests credentials based on each provider's `envVars` definition. Credentials are validated via [`providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/providerValidation.ts) and persisted to [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json).

### CLI Flag Method

Bypass interactivity by specifying the provider ID directly:

```bash
export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
openclaude --provider openai

```

The `--provider` flag accepts any ID from the catalog. The runtime resolver in [`src/utils/model/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/providers.ts) handles the rest.

## Configuring Multiple Providers

### Using a `.env` File

For projects requiring multiple API keys, use `--provider-env-file`:

```bash
cat > .env <<EOF
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...
GEMINI_API_KEY=...
EOF

openclaude --provider-env-file .env --provider deepseek

```

The env-file loader respects the `envVars` array defined per provider in the catalog [[source]](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerStartupOverrides.ts).

### Environment Variable Priority

OpenClaude merges configuration sources in this order (later values override earlier):

1. Built-in default provider (`anthropic` unless changed)
2. [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json) saved profile
3. Shell environment variables
4. `--provider-env-file` contents
5. `--provider` CLI flag

## Local Model Setup with Ollama

Local providers require no API key. The `ollama` provider connects to `localhost:11434` by default:

```bash
openclaude --provider ollama

```

Since Ollama is grouped under `local` in the catalog, the validation logic in [`src/utils/providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerValidation.ts) skips key checks and attempts connection directly.

## Validating and Debugging Your Setup

### Verification Commands

```bash

# Check which provider profile is active

openclaude doctor report --markdown

# Force provider reconfiguration if validation fails

export CLAUDE_CODE_USE_OPENAI=0   # skip failing provider

openclaude /provider

```

The [`providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/providerValidation.ts) module [[source]](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerValidation.ts) checks required key presence and reachability, surfacing actionable errors with hints to re-run `/provider` or adjust environment variables.

### Common Validation Errors

| Error | Cause | Resolution |
|-------|-------|------------|
| Missing API key | `envVars` not satisfied | Export the required variable or use `/provider` |
| Connection timeout | Provider endpoint unreachable | Check network or local service status |
| Invalid key format | Key fails provider regex | Re-paste key via `/provider` prompt |

## Switching Providers on the Fly

OpenClaude requires no restart to change LLM backends:

```bash

# Inside an active REPL session

/provider

# Select new provider from menu

# Or exit and relaunch with different flag

openclaude --provider gemini

```

Each invocation writes to [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json), making your last choice the default for future sessions.

## Key Implementation Files

- **[`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts)** – Master catalog of all built-in providers, groups, and `envVars` definitions
- **[`src/utils/model/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/providers.ts)** – Runtime resolution, `getAPIProvider()` export, and `providersInGroup()` helper
- **[`src/utils/providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerValidation.ts)** – Key presence checks and user-friendly error generation
- **[`src/utils/providerStartupOverrides.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerStartupOverrides.ts)** – Handles `--provider-env-file` and per-run environment injection
- **[`docs/non-technical-setup.md`](https://github.com/Gitlawb/openclaude/blob/main/docs/non-technical-setup.md)** – Step-by-step visual guide for non-developers

## Summary

- **Interactive setup**: Run `/provider` inside the OpenClaude REPL for guided configuration
- **Headless setup**: Use `--provider <id>` with environment variables for automation
- **Multiple providers**: Load keys via `--provider-env-file .env` and switch with `--provider`
- **Local models**: Ollama requires no API key—just the provider flag
- **Validation**: Automatic checks in [`providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/providerValidation.ts) prevent misconfiguration
- **Persistence**: Profiles save to [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json) for automatic reuse

## Frequently Asked Questions

### What LLM providers does OpenClaude support?

OpenClaude supports any provider defined in [`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts), including `openai`, `anthropic`, `deepseek`, `gemini`, `ollama`, `codex`, and custom entries. The catalog groups providers into `subscriptions` (API services), `gateways` (aggregation layers), `vendors` (direct model hosts), `local` (self-hosted), and `custom` (user-defined).

### How do I add a new LLM provider to OpenClaude?

Extend the catalog in [`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) with a new entry containing `id`, `name`, `group`, `setupHint`, and `envVars` array. Define required environment variable keys, optionally implement OAuth in [`providerStartupOverrides.ts`](https://github.com/Gitlawb/openclaude/blob/main/providerStartupOverrides.ts), and the existing CLI infrastructure will automatically recognize the new provider without additional code changes.

### Why does OpenClaude fail to start with a provider error?

The [`providerValidation.ts`](https://github.com/Gitlawb/openclaude/blob/main/providerValidation.ts) module detected missing or invalid configuration. Check `openclaude doctor report --markdown` to identify which `envVars` are unsatisfied. Either export the required keys, run `/provider` to reconfigure interactively, or set `CLAUDE_CODE_USE_OPENAI=0` to skip problematic providers during startup.

### Can I use OpenClaude without an API key?

Yes, for providers in the `local` group. The `ollama` provider connects to `localhost:11434` with no authentication required. All cloud providers (`openai`, `deepseek`, `gemini`, etc.) require valid API keys as defined in their catalog `envVars`.