How to Configure Providers for OpenMAIC: A Complete Guide

Configure providers for OpenMAIC by editing the providersConfig object in the settings store for client-side customization, or deploy a server-providers.yml file to enforce provider policies across all users.

OpenMAIC is an open-source multimodal AI interface that unifies large language models, audio synthesis, image generation, and web search capabilities. Connecting these features to external APIs requires proper provider configuration using the TypeScript-based settings store and optional server-side overrides. This guide details the exact file locations, configuration schemas, and validation rules implemented in the THU-MAIC/OpenMAIC repository.

Understanding the Provider Architecture

The Provider Registry

Built-in AI providers are defined as a constant record in [lib/ai/providers.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts). The PROVIDERS object maps unique identifiers to configuration objects containing default base URLs, authentication requirements, and available model lists.

export const PROVIDERS: Record<ProviderId, ProviderConfig> = {
  openai: {
    id: 'openai',
    name: 'OpenAI',
    type: 'openai',
    defaultBaseUrl: 'https://api.openai.com/v1',
    requiresApiKey: true,
    icon: '/logos/openai.svg',
    models: [ /* model objects … */ ]
  },
  // …anthropic, amazon-bedrock, google-gemini, minimax, etc.
};

Extending this registry requires adding entries with the same shape: id, name, type, defaultBaseUrl, requiresApiKey, icon, and models.

The Settings Store Structure

User-specific overrides live in the Zustand-based settings store defined in [lib/store/settings.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts). The relevant state interface includes separate configuration maps for each service type:

export interface SettingsState {
  providersConfig: ProvidersConfig;          // LLM providers
  ttsProvidersConfig: Record<TTSProviderId, ProviderConfig>;
  asrProvidersConfig: Record<ASRProviderId, ProviderConfig>;
  pdfProvidersConfig: Record<PDFProviderId, ProviderConfig>;
  imageProvidersConfig: Record<ImageProviderId, ProviderConfig>;
  videoProvidersConfig: Record<VideoProviderId, ProviderConfig>;
}

Each provider entry follows this interface:

{
  apiKey: string;          // Authentication token (empty if not required)
  baseUrl: string;          // Custom endpoint overriding defaultBaseUrl
  enabled: boolean;         // UI visibility toggle
  modelId?: string;         // Default model selection
  customModels?: { id: string; name: string }[]; // User-defined models
  serverDisabled?: boolean; // Administrative lock from server config
}

Client-Side Provider Configuration

Editing Built-in Providers

Users modify provider settings through the Settings panel or programmatically via the store. To update a provider programmatically:

import { useSettingsStore } from '@/lib/store/settings';

const updateProvider = () => {
  useSettingsStore.setState((state) => ({
    providersConfig: {
      ...state.providersConfig,
      openai: {
        ...state.providersConfig.openai,
        apiKey: 'sk-new-key-here',
        baseUrl: 'https://proxy.openai.com/v1',
        enabled: true
      }
    }
  }));
};

Changes persist automatically to the KV store under the account scope, synchronizing across devices.

Adding Custom Providers

For OpenAI-compatible endpoints not listed in the built-in registry, add a custom entry to the appropriate configuration map:

import { useSettingsStore } from '@/lib/store/settings';

useSettingsStore.getState().providersConfig['custom-openai'] = {
  apiKey: 'sk-your-key',
  baseUrl: 'https://api.custom-provider.com/v1',
  enabled: true,
  customName: 'Enterprise LLM',
  customDefaultBaseUrl: 'https://api.custom-provider.com/v1',
  requiresApiKey: true,
  isBuiltIn: false,
  customModels: [
    { id: 'enterprise-gpt-4', name: 'Enterprise GPT-4' }
  ]
};

The same pattern applies to ttsProvidersConfig, asrProvidersConfig, imageProvidersConfig, and videoProvidersConfig for multimodal services.

Server-Side Provider Overrides

Using server-providers.yml

Administrators can enforce provider availability by placing a server-providers.yml file at the project root. This YAML configuration overrides client-side toggles and can disable providers entirely or inject server-side API keys.

openai:
  enabled: true          # Force-enable regardless of client preferences

  apiKey: ''             # Optional server-side key (overridden by client if provided)

  
anthropic:
  serverDisabled: true  # Completely disallow, hiding from UI

  
custom-openai:
  enabled: true
  baseUrl: https://api.internal-company.com/v1

The server loader parses this file during initialization and injects the resulting constraints into the client state.

Environment Variable Fallbacks

For containerized deployments, set provider flags via environment variables that map to the configuration schema:

MAIC_PROVIDER_OPENAI_ENABLED=true
MAIC_PROVIDER_ANTHROPIC_DISABLED=true
MAIC_PROVIDER_CUSTOM_BASEURL=https://api.internal.com/v1

These variables are merged with server-providers.yml during the server-side hydration phase defined in [lib/store/settings.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts).

Specialized Provider Types

OpenMAIC uses identical configuration patterns for non-LLM services, each maintained in dedicated constant files:

Service Type	Registry Location	Configuration Key
Web Search	[lib/web-search/constants.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/web-search/constants.ts)	webSearchProviderId
Text-to-Speech	[lib/audio/constants.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/constants.ts)	ttsProvidersConfig
Speech Recognition	[lib/audio/constants.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/constants.ts)	asrProvidersConfig
Image Generation	[lib/media/image-providers.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/media/image-providers.ts)	imageProvidersConfig
Video Generation	[lib/media/video-providers.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/media/video-providers.ts)	videoProvidersConfig

Each registry exports a PROVIDERS constant with the same schema as the LLM providers, allowing uniform configuration across modalities.

Validation and Error Handling

The settings store runs validation logic from [lib/store/settings-validation.ts](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings-validation.ts) on initialization. The isLLMProviderConfigured function checks that enabled providers have valid API keys and at least one accessible model.

If validation fails—such as when a required TTS provider lacks configuration—the UI displays system notices like "No server TTS provider is configured, so nothing was synthesized." Invalid configurations are automatically sanitized to prevent runtime errors during API calls.

Summary

• Built-in providers are defined in lib/ai/providers.ts with default models and endpoints.
• User configurations are stored in the providersConfig slice of lib/store/settings.ts, persisted to the KV store.
• Custom providers can be added programmatically by extending the configuration maps with OpenAI-compatible endpoints.
• Server overrides via server-providers.yml or environment variables enforce administrative policies that supersede client settings.
• Validation occurs automatically on startup, ensuring enabled providers have necessary credentials and model definitions before API calls execute.

Frequently Asked Questions

How do I add a new custom AI provider that is not in the default list?

Extend the providersConfig object in the settings store with a unique identifier and provide the baseUrl, apiKey, and customModels properties. Set isBuiltIn: false to indicate this is a user-defined endpoint. The provider will immediately appear in the model selection dropdown.

Can I disable a provider for all users in my organization?

Yes. Create a server-providers.yml file in the deployment root and set serverDisabled: true for the specific provider ID. This flag overrides any client-side enabled: true settings and removes the provider from the UI entirely.

Where are the API keys stored, and are they secure?

API keys are stored in the browser's localStorage (via the Zustand persist middleware) under the account key, or in server-side environment variables for server-providers.yml configurations. For production deployments, use the server-side configuration to avoid exposing keys to client-side JavaScript.

Why does my provider configuration reset after clearing browser data?

OpenMAIC persists settings to localStorage by default. If you clear site data or use incognito mode, the store reverts to the default configuration defined in getDefaultProvidersConfig within lib/store/settings.ts. To maintain persistent configuration, implement a custom storage adapter or use the server-side YAML configuration.

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