# How to Configure Providers for OpenMAIC: A Complete Guide > Learn how to configure providers for OpenMAIC. Customize client-side settings or enforce server-wide policies with a simple YAML file for seamless integration. - Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) - Tags: how-to-guide - Published: 2026-09-10 --- **Configure providers for OpenMAIC by editing the `providersConfig` object in the settings store for client-side customization, or deploy a [`server-providers.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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)](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. ```typescript export const PROVIDERS: Record = { 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)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts)**. The relevant state interface includes separate configuration maps for each service type: ```typescript export interface SettingsState { providersConfig: ProvidersConfig; // LLM providers ttsProvidersConfig: Record; asrProvidersConfig: Record; pdfProvidersConfig: Record; imageProvidersConfig: Record; videoProvidersConfig: Record; } ``` Each provider entry follows this interface: ```typescript { 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: ```typescript 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: ```typescript 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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. ```yaml 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: ```bash 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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)](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)](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)](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)](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)](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)](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)](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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) with default models and endpoints. - **User configurations** are stored in the `providersConfig` slice of [`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts). To maintain persistent configuration, implement a custom storage adapter or use the server-side YAML configuration.