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

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 and resolved at runtime in 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 [source]. When OpenClaude launches, the resolution logic in src/utils/model/providers.ts loads your selected profile from .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:

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 and persisted to .openclaude-profile.json.

CLI Flag Method

Bypass interactivity by specifying the provider ID directly:

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 handles the rest.

Configuring Multiple Providers

Using a .env File

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

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].

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

openclaude --provider ollama

Since Ollama is grouped under local in the catalog, the validation logic in src/utils/providerValidation.ts skips key checks and attempts connection directly.

Validating and Debugging Your Setup

Verification Commands

# 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 module [source] 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:

# 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, making your last choice the default for future sessions.

Key Implementation Files

• web/src/data/providers.ts – Master catalog of all built-in providers, groups, and envVars definitions
• src/utils/model/providers.ts – Runtime resolution, getAPIProvider() export, and providersInGroup() helper
• src/utils/providerValidation.ts – Key presence checks and user-friendly error generation
• src/utils/providerStartupOverrides.ts – Handles --provider-env-file and per-run environment injection
• 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 prevent misconfiguration
• Persistence: Profiles save to .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, 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 with a new entry containing id, name, group, setupHint, and envVars array. Define required environment variable keys, optionally implement OAuth in 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 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.

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