# Provider Keys

## Critical Boundary

OpenMAIC generation does not automatically reuse the OpenClaw agent's current model or API key.

OpenMAIC server APIs resolve their own model and provider keys from OpenMAIC server-side config.

This skill does not rely on runtime overrides for model, provider, API key, base URL, or provider type.

If the user wants to change any of those, they must edit OpenMAIC server-side config files.

## Interaction Policy

- Do not begin by asking the user to paste an API key into chat.
- First, recommend a provider path.
- Then ask how the user wants to configure it.
- The user should edit `.env.local` or `server-providers.yml` themselves.
- Do not offer to write the key for them.
- Do not ask for the literal key in chat.
- Do not suggest temporary request-time overrides.
- If generation fails because of auth, provider, or model selection, direct the user back to server-side config files.

## Preferred User Flow

1. Recommend a provider option.
2. Ask where the user wants to configure it:
   - `.env.local` (recommended for most users)
   - `server-providers.yml`
3. Tell the user exactly which variables or YAML fields to edit.
4. Wait for the user to confirm they finished editing before continuing.

## Recommendation Paths

### 1. Lowest-Friction Setup

Recommended when the user wants the smallest amount of configuration.

Set:

```env
ANTHROPIC_API_KEY=sk-ant-...
```

Why:

- OpenMAIC server fallback is currently `gpt-4o-mini` if `DEFAULT_MODEL` is unset.
- If the user wants Anthropic or Google by default, they should set `DEFAULT_MODEL` explicitly.

### 2. Better Speed / Cost Balance

Recommended when the user is willing to set one extra variable.

Set:

```env
GOOGLE_API_KEY=...
DEFAULT_MODEL=google:gemini-3-flash-preview
```

Why:

- Good quality-to-speed balance
- Matches the repo's current recommendation direction better than the default fallback
- The `google:` prefix is important. Without a provider prefix, model parsing defaults to OpenAI.

### 3. Existing Provider Reuse

Use when the user already has OpenAI or another supported provider configured and wants to stick with it.

Examples:

```env
OPENAI_API_KEY=sk-...
DEFAULT_MODEL=openai:gpt-4o-mini
```

```env
DEEPSEEK_API_KEY=...
DEFAULT_MODEL=deepseek:deepseek-chat
```

## Model String Rule

When recommending or showing `DEFAULT_MODEL`, always include the provider prefix:

- `google:gemini-3-flash-preview`
- `anthropic:claude-3-5-haiku-20241022`
- `openai:gpt-4o-mini`
- `deepseek:deepseek-chat`

Do not recommend bare model IDs such as `gemini-3-flash-preview` by themselves, because OpenMAIC will otherwise parse them as OpenAI models.

Do not work around a wrong `DEFAULT_MODEL` by changing request parameters. The user should fix the server-side config instead.

## Preferred Config Method

For first setup, prefer `.env.local`:

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

Then fill the chosen keys.

Alternative: `server-providers.yml`

```yaml
providers:
  anthropic:
    apiKey: sk-ant-...

  google:
    apiKey: ...

  openai:
    apiKey: sk-...
```

If using a non-default provider for classroom generation, also set the model selection explicitly:

```env
DEFAULT_MODEL=google:gemini-3-flash-preview
```

## Recommended Prompts To The User

Preferred:

- "I recommend configuring OpenMAIC through `.env.local` first. Please edit that file locally and tell me when you're done."
- "For the simplest setup, I recommend Anthropic. For better speed/cost balance, I recommend Google plus `DEFAULT_MODEL=google:gemini-3-flash-preview`. Which path do you want?"

Avoid as the first move:

- "Send me your API key"
- "Paste your API key here"
- "Do you want me to write the key for you?"

## Confirmation Requirements

- Recommend one provider path first.
- Ask the user which config-file path they want.
- Instruct the user to modify the file themselves.
- Wait for the user to confirm they finished editing before continuing.
- Do not request the literal key.
- If provider/model/auth errors happen later, tell the user exactly which config entry to fix and wait for confirmation before retrying.

## Optional Features

These features require additional provider keys beyond the core LLM provider. Ask the user if they want to enable any of these after the core LLM key is configured.

| Feature | Env Variable(s) | Description |
|---------|-----------------|-------------|
| Web Search | `TAVILY_API_KEY` | Enriches outlines with real-time web research |
| Image Generation | `IMAGE_SEEDREAM_API_KEY`, `IMAGE_QWEN_IMAGE_API_KEY`, `IMAGE_NANO_BANANA_API_KEY` | Generates images for slides (any one suffices) |
| Video Generation | `VIDEO_SEEDANCE_API_KEY`, `VIDEO_KLING_API_KEY`, `VIDEO_VEO_API_KEY`, `VIDEO_SORA_API_KEY` | Generates short videos (any one suffices) |
| TTS | `TTS_OPENAI_API_KEY`, `TTS_AZURE_API_KEY`, `TTS_GLM_API_KEY`, `TTS_QWEN_API_KEY` | Text-to-speech narration (any one suffices) |

These are all optional. The classroom generation works without them — they only unlock richer content.

Alternatively, configure via `server-providers.yml`:

```yaml
web-search:
  tavily:
    apiKey: tvly-...

image:
  seedream:
    apiKey: ...

video:
  seedance:
    apiKey: ...

tts:
  openai-tts:
    apiKey: sk-...
```