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

> Learn how to set up your OpenAI API key for OpenMAIC by configuring the .env.local file. Follow this guide to enable all OpenAI features and enhance your MAIC experience.

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

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/provider-config.ts)**, where the application checks for your OpenAI credentials:

```ts
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:

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

```

### Step 2: Add Your OpenAI API Key

Edit `.env.local` and set your key:

```env

# 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`:

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```ts
// 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](https://github.com/THU-MAIC/OpenMAIC/blob/main/.env.example)
- **[`lib/server/provider-config.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/provider-config.ts)** — Loads the OpenAI key and builds provider configuration objects used by the server [GitHub](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/provider-config.ts)
- **[`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md)** (Quick-Start section) — Official setup documentation [GitHub](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md#quick-start)

## 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.