Environment Variables for LLM Providers in OpenMAIC: Complete Configuration Guide

OpenMAIC requires eight distinct API key environment variables—defined in skills/openmaic/references/provider-keys.md and consumed by lib/server/provider-config.ts—to authenticate with supported LLM providers, plus an optional DEFAULT_MODEL variable for request routing.

The THU-MAIC/OpenMAIC repository defines a centralized configuration system for managing Large Language Model (LLM) provider credentials through environment variables. Understanding these environment variables for LLM providers is essential for deploying OpenMAIC with external AI services, as the platform validates these keys at startup and uses them to route inference requests to the appropriate backend.

Supported LLM Provider Environment Variables

OpenMAIC supports eight major LLM providers through dedicated API key environment variables. Each variable follows the {PROVIDER}_API_KEY naming convention and is read during server initialization.

Major Cloud Providers

• OpenAI: Set OPENAI_API_KEY to authenticate with OpenAI's GPT models. This serves as the fallback provider when no specific provider is specified in model requests.
• Anthropic: Use ANTHROPIC_API_KEY for Claude-based models, including Claude 3.5 Sonnet and Claude 3 Opus.
• Azure OpenAI: Configure AZURE_OPENAI_API_KEY for Azure-hosted OpenAI deployments. Note that this requires additional Azure endpoint configuration beyond the API key.

Aggregation and Specialized Services

• OpenRouter: Set OPENROUTER_API_KEY to access the OpenRouter gateway, which aggregates multiple LLM providers behind a single API endpoint.
• Atlas Cloud: Use ATLASCLOUD_API_KEY for the Atlas Cloud LLM service.
• Tencent HunYuan: Configure TENCENT_HUNYUAN_API_KEY for the Tencent HunYuan model family, supporting Chinese language optimization.
• MIMO: Set MIMO_API_KEY for the MIMO LLM service.
• Hy3: Use HY3_API_KEY for the Hy3 provider integration.

Configuration Architecture

The environment variables for LLM providers are centralized in lib/server/provider-config.ts, which exports a PROVIDER_KEYS object that maps environment variables to provider configurations.

// lib/server/provider-config.ts
export const PROVIDER_KEYS = {
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
  AZURE_OPENAI_API_KEY: process.env.AZURE_OPENAI_API_KEY,
  OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
  ATLASCLOUD_API_KEY: process.env.ATLASCLOUD_API_KEY,
  TENCENT_HUNYUAN_API_KEY: process.env.TENCENT_HUNYUAN_API_KEY,
  MIMO_API_KEY: process.env.MIMO_API_KEY,
  HY3_API_KEY: process.env.HY3_API_KEY,
};

The getProviderConfig function validates these keys at runtime. When a client requests a specific provider, the system checks for the corresponding environment variable and throws an error if authentication credentials are missing.

Default Model Routing

The DEFAULT_MODEL environment variable controls which provider and model OpenMAIC uses when no specific model is requested. The format follows {PROVIDER}:{MODEL_NAME}.

# Use OpenAI GPT-4o as the default

DEFAULT_MODEL=OPENAI:gpt-4o

# Use Anthropic Claude as the default

DEFAULT_MODEL=ANTHROPIC:claude-3-5-sonnet-20240620

When the provider prefix is omitted from DEFAULT_MODEL, OpenMAIC defaults to the OpenAI provider automatically.

Implementation Examples

Configuring Local Development

Create a .env.local file in the project root to set your provider keys for local development:

# .env.local

OPENAI_API_KEY=sk-openai-xxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx

Runtime Validation

Before initializing a provider client, validate that the environment variable exists:

import { getProviderConfig } from '@openmaic/server/provider-config';

const cfg = getProviderConfig('anthropic');
if (!cfg.apiKey) {
  throw new Error('ANTHROPIC_API_KEY is not set');
}

// Initialize the provider client
const client = new AnthropicClient({ apiKey: cfg.apiKey });

Summary

• Eight provider-specific environment variables control LLM authentication in OpenMAIC, following the {PROVIDER}_API_KEY pattern defined in skills/openmaic/references/provider-keys.md.
• Configuration is centralized in lib/server/provider-config.ts through the PROVIDER_KEYS export and getProviderConfig function.
• Azure OpenAI requires additional configuration beyond the API key, including endpoint setup.
• The DEFAULT_MODEL variable uses a {PROVIDER}:{MODEL} format to route requests, defaulting to OpenAI when unspecified.
• Validation occurs at runtime when providers are instantiated, ensuring clear error messages for missing credentials.

Frequently Asked Questions

What environment variables are required for basic OpenAI integration?

Only OPENAI_API_KEY is required for OpenAI integration. Set this variable to a valid OpenAI API key beginning with sk-. If you omit the DEFAULT_MODEL variable, OpenMAIC automatically uses OpenAI as the fallback provider for all requests.

How do I configure multiple LLM providers simultaneously?

Set multiple API key environment variables in your .env.local file or deployment environment. OpenMAIC supports concurrent provider configuration—simply define OPENAI_API_KEY, ANTHROPIC_API_KEY, and any other required provider keys simultaneously. The system uses the DEFAULT_MODEL variable or explicit request parameters to determine which provider handles each inference request.

What is the format for the DEFAULT_MODEL environment variable?

The DEFAULT_MODEL variable uses the format PROVIDER:MODEL_IDENTIFIER, such as ANTHROPIC:claude-3-5-sonnet-20240620 or OPENAI:gpt-4o. When you provide only a model name without the provider prefix, OpenMAIC assumes the OpenAI provider. This variable is defined alongside your API keys and controls routing when no specific model is requested by the client.

Where does OpenMAIC validate that API keys are properly configured?

OpenMAIC validates API keys in lib/server/provider-config.ts through the getProviderConfig function. When a provider is requested, this function checks the corresponding environment variable and returns a configuration object. If the key is missing, the system throws an error immediately upon provider instantiation, preventing runtime failures during inference requests.

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