How to Set Up OpenAI API Key for OpenMAIC: Complete Configuration Guide

Set the OPENAI_API_KEY environment variable in a .env.local file created from the provided .env.example template, then restart the OpenMAIC server to enable all OpenAI-powered features.

OpenMAIC is an open-source multimodal AI chat interface developed by THU-MAIC that supports multiple LLM and service providers. To use OpenAI's models for chat completions, image generation, text-to-speech, or speech-to-text, you must configure your API credentials correctly. This guide walks through the exact steps based on the official OpenMAIC source code.

Where OpenMAIC Reads the OpenAI API Key

OpenMAIC loads provider credentials from environment variables during server startup. The key configuration happens in lib/server/provider-config.ts, where the application checks for your OpenAI credentials:

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) return imageConfig;   // skip OpenAI image provider if the key is missing

This pattern applies across all OpenAI-related services. When OPENAI_API_KEY is present, OpenMAIC enables:

• Chat completions (default LLM provider)
• Image generation via openai-image provider
• Text-to-speech via openai-tts
• Speech-to-text via openai-whisper

Step-by-Step: Configure Your OpenAI API Key

Step 1: Copy the Environment Template

OpenMAIC includes a comprehensive template at .env.example that documents all supported environment variables:

cp .env.example .env.local

Step 2: Add Your OpenAI API Key

Edit .env.local and set your key:

# OpenMAIC Environment Variables

# Copy this file to .env.local and fill in the values you need.

# All variables are optional — only configure the providers you want to use.

# --- LLM Providers -----------------------------------------------------------

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional overrides

# OPENAI_BASE_URL=https://your-proxy.example.com/v1

# OPENAI_MODELS=gpt-4o,gpt-4o-mini

The OPENAI_BASE_URL and OPENAI_MODELS variables are optional. Use them if you need to route requests through a proxy or restrict available models.

Step 3: Restart the Server

Environment variables are loaded once at startup. After saving .env.local:

pnpm dev      # development

# or

pnpm start    # production

The server reads process.env.OPENAI_API_KEY during initialization via the provider configuration module.

Optional: YAML Configuration Alternative

You can also define OpenAI credentials in server-providers.yml (format documented in the README). However, the environment variable method in .env.local is the simplest approach for most deployments and aligns with standard Node.js practices.

Verifying Your Configuration

To confirm your OpenAI API key is loaded correctly in custom scripts or extensions:

// custom-script.ts
import { config } from 'dotenv';
config({ path: '.env.local' });

const openAiKey = process.env.OPENAI_API_KEY;
if (!openAiKey) {
  throw new Error('OPENAI_API_KEY is not set');
}

console.log('OpenAI key loaded, length:', openAiKey.length);

For the main application, check server logs on startup—OpenMAIC will skip OpenAI provider initialization if the key is missing, falling back to other configured providers.

Key Source Files Reference

• .env.example — Template for all environment variables, including OPENAI_API_KEY GitHub
• lib/server/provider-config.ts — Loads the OpenAI key and builds provider configuration objects used by the server GitHub
• README.md (Quick-Start section) — Official setup documentation GitHub

Summary

• OpenMAIC requires OPENAI_API_KEY as an environment variable to enable OpenAI services
• Copy .env.example to .env.local and populate your key—this is the standard configuration path
• The key is loaded in lib/server/provider-config.ts and applies to LLM, image, TTS, and ASR providers
• Optional variables OPENAI_BASE_URL and OPENAI_MODELS allow proxy and model customization
• Always restart the server after modifying environment variables

Frequently Asked Questions

What happens if I don't set OPENAI_API_KEY?

OpenMAIC will skip OpenAI provider initialization entirely. According to the applyOpenAIImageProviderConfig function in lib/server/provider-config.ts, when apiKey is undefined, the function returns early with imageConfig, leaving the OpenAI image provider unconfigured. Other services follow the same pattern—no errors occur, but OpenAI features remain unavailable.

Can I use a custom OpenAI-compatible API instead of OpenAI directly?

Yes. Set OPENAI_BASE_URL in your .env.local file to point to any OpenAI-compatible endpoint. This works with proxies, Azure OpenAI Service deployments, or alternative providers implementing the OpenAI API specification.

Where should I deploy .env.local in production?

Place .env.local in the project root directory where OpenMAIC is installed, or use your hosting platform's environment variable management (Vercel, Docker, Kubernetes secrets, etc.). The dotenv loader automatically finds .env.local at runtime. Never commit this file to version control—it contains sensitive credentials.

Does OpenMAIC support multiple API keys for different providers simultaneously?

Yes. OpenMAIC's provider architecture in lib/server/provider-config.ts loads credentials for all configured providers independently. You can set OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and others in the same .env.local file, then select providers per-request or set defaults in your configuration.

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