# How to Configure LLM Providers in OpenMAIC: Environment Variables vs. YAML Setup

> Configure LLM providers in OpenMAIC using environment variables or YAML. Securely manage API keys on the server for seamless integration with OpenAI-compatible models. Learn how now.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-01

---

**OpenMAIC supports any OpenAI-compatible LLM through server-side configuration using either environment variables in `.env.local` or a structured [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) file, ensuring API keys never reach the browser.**

OpenMAIC (THU-MAIC/OpenMAIC) is a provider-neutral platform that allows you to integrate any large language model speaking the OpenAI-compatible API. When you configure LLM providers in OpenMAIC, all sensitive credentials remain server-side, protecting your API keys from client exposure while supporting generation, media, TTS, and ASR backends.

## Understanding OpenMAIC's Provider-Neutral Architecture

The core abstraction lives in the `lib/ai` package, specifically within [`providerRegistry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providerRegistry.ts) and [`modelResolver.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/modelResolver.ts). This architecture accepts any provider implementing the standard OpenAI API format, including OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, Google Gemini, MiniMax, and Grok.

Configuration occurs exclusively on the server. The startup script reads your settings from either environment variables or the YAML file, registers each provider in the **ProviderRegistry**, and makes them available to all AI backends. The browser only sends the `providerId` and model name; the server injects the actual credentials.

## Method 1: Configure LLM Providers Using Environment Variables

The most common approach uses a `.env.local` file copied from the project's `.env.example`. This method stores API keys, base URLs, and default models as environment variables that the server reads during boot.

First, copy the example environment file from the repository root:

```bash
cp .env.example .env.local

```

Next, add your provider credentials to `.env.local`. You can configure multiple providers simultaneously. For example, to set up OpenAI and Azure OpenAI according to the README (lines 25-38):

```env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
AZURE_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=YOUR-DEPLOYMENT-NAME
DEFAULT_MODEL=openai:gpt-5.5

```

Finally, restart the server using `pnpm dev` or Docker. OpenMAIC automatically reads the variables from `process.env` and registers each provider in the registry.

## Method 2: Configure LLM Providers Using server-providers.yml

For advanced use cases requiring multiple models per provider or centralized management, create a [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) file at the repository root. When this file exists, OpenMAIC parses it on startup and **overrides** any corresponding environment variables.

Structure the YAML with provider IDs as top-level keys:

```yaml
providers:
  openai:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
  azure:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models:
      - YOUR-DEPLOYMENT-NAME
  anthropic:
    apiKey: sk-ant-xxxxxxxxxxxxxxxxxxxx

```

You can also specify a default model per provider within the YAML:

```yaml
providers:
  openai:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
    defaultModel: gpt-5.5

```

## Setting the Default Model

You can configure a default LLM that OpenMAIC uses when requests omit specific model parameters. Set this globally via environment variable:

```env
DEFAULT_MODEL=openai:gpt-5.5

```

Or set provider-specific defaults in [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml). If no default is configured, OpenMAIC falls back to the first enabled provider according to the fallback configuration in [`opencode.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/opencode.json) (lines 1-8).

## Runtime Provider Resolution

When the server receives a generation or media request, the resolution logic in [`lib/ai/modelResolver.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/modelResolver.ts) performs the following sequence:

1. Extracts the **provider id** (e.g., `openai`, `azure`, `anthropic`, `minimax`) from the request payload
2. Validates the provider against the **ProviderRegistry** to ensure it is enabled
3. Injects the stored API key and base URL into the request context
4. Applies fallback logic only if the provider's `allow_fallbacks` flag is true, as defined in [`opencode.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/opencode.json)

If a request references a disabled or unknown provider, the system returns a clear `PROVIDER_DISABLED` or `PROVIDER_NOT_FOUND` error. No automatic fallback occurs unless explicitly enabled in the fallback configuration.

## Complete Configuration Examples

**Example 1:** OpenAI and MiniMax via `.env.local`

```env

# .env.local

OPENAI_API_KEY=sk-abcdef1234567890
MINIMAX_API_KEY=abc123def456
MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic/v1
DEFAULT_MODEL=openai:gpt-5.5

```

**Example 2:** Anthropic and AWS Bedrock via [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml)

```yaml

# server-providers.yml

providers:
  anthropic:
    apiKey: sk-ant-abcdef123456
  bedrock:
    models:
      - us.anthropic.claude-sonnet-5
      - us.anthropic.claude-opus-4-8

```

**Example 3:** Calling the generation API with an explicit provider

```javascript
const response = await fetch('http://localhost:3000/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    providerId: 'openai',          // matches the key in .env or YAML
    model: 'gpt-5.5',
    prompt: 'Explain quantum computing in simple terms.'
  })
});

```

## Summary

- OpenMAIC keeps all LLM credentials server-side in either `.env.local` or [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml), never exposing keys to the browser
- Environment variables offer the fastest setup for simple configurations and follow 12-factor app principles
- The YAML file provides structured, multi-model configurations and overrides environment variables when both exist
- The `lib/ai` package handles provider registration, model resolution, and error handling through `ProviderRegistry` and [`modelResolver.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/modelResolver.ts)
- Set a global default using `DEFAULT_MODEL` or per-provider defaults in YAML; otherwise, OpenMAIC uses the first configured provider
- Runtime resolution validates provider IDs and enforces error codes like `PROVIDER_DISABLED` without automatic fallbacks unless configured in [`opencode.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/opencode.json)

## Frequently Asked Questions

### Can I configure LLM providers on the client side in OpenMAIC?

No. OpenMAIC strictly prevents API key exposure to browsers by design. All provider configuration happens server-side through environment variables or the [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) file. The client only transmits the `providerId` and model name; the server retrieves the actual API key from its secure registry.

### What happens if I specify both environment variables and a YAML file?

When [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) exists at the repository root, OpenMAIC loads it during the boot process and **overrides** any corresponding environment variables. The YAML file takes precedence, allowing you to maintain a single declarative source of truth for complex multi-provider setups while keeping `.env.local` for simpler overrides.

### How do I set a default model for all generation requests?

Configure the `DEFAULT_MODEL` environment variable in `.env.local` using the format `provider:model` (e.g., `openai:gpt-5.5` or `minimax:MiniMax-M2.7-highspeed`), or set `defaultModel` within the specific provider block in [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml). If neither is set, OpenMAIC defaults to the first provider in the registry.

### Which provider IDs are valid when configuring OpenMAIC?

Valid provider IDs include `openai`, `azure`, `anthropic`, `minimax`, `bedrock`, `gemini`, and `grok`, along with any custom OpenAI-compatible endpoints. These IDs must match the keys in your `.env.local` file (e.g., `OPENAI_API_KEY` maps to provider `openai`) or the top-level keys under `providers` in your [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) file.