# How to Set the Default Model in OpenMAIC: Token Plans, Settings UI, and Code-Level Configuration

> Easily set the default model in OpenMAIC using token plans or the Settings UI. Learn to configure your default model permanently for seamless AI interactions.

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

---

**Set the default model in OpenMAIC by editing token-plan presets for permanent configuration or using the Settings UI for interactive changes, with both paths persisting the `defaultModelId` to the application's settings store.**

OpenMAIC manages default models through a two-tier system that bridges preset definitions and user-configurable settings. The **default model** determines which concrete model runs when a provider (TTS, ASR, or LLM) is selected without an explicit model ID. This article explains both configuration approaches based on the THU-MAIC/OpenMAIC source code.

---

## Default Model Sources in OpenMAIC

OpenMAIC determines the default model from two primary sources, applied in priority order:

1. **User-specific settings** – stored per-provider in the settings store ([`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts))
2. **Token-plan preset definitions** – hardcoded defaults in [`lib/config/token-plan-presets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/token-plan-presets.ts)

When no user override exists, the system falls back to the preset's `defaultModelId` value.

---

## Method 1: Configure Default Models via Token-Plan Presets

The most reliable way to set system-wide defaults is modifying **token-plan presets**. These define provider configurations including voice, capability flags, and the critical `defaultModelId` field.

### Where Presets Define Default Models

In [`lib/config/token-plan-presets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/token-plan-presets.ts), each preset object includes a `defaultModelId` property:

```typescript
// lib/config/token-plan-presets.ts
export const TOKEN_PLAN_PRESETS = [
  {
    id: 'speech',
    name: 'Speech',
    // The model the Speech provider will use by default
    defaultModelId: 'speech-2.8-hd',
    // additional configuration...
  },
];

```

The preset with id **`speech-2.8-hd`** at line 115 demonstrates this pattern. When OpenMAIC applies a token plan, it seeds the provider configuration from `target.defaultModelId` if present.

### Applying Preset Defaults Programmatically

The settings store logic (in [`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts)) propagates preset values to runtime configuration:

```typescript
// lib/store/settings.ts – store schema and initialization
export interface AudioProviderConfig {
  modelId?: string;  // stores the user-chosen or preset-derived default model
  // ...
}

// When applying a token plan, defaultModelId transfers to modelId
if (target.defaultModelId) {
  config.modelId = target.defaultModelId;
}

```

---

## Method 2: Set Default Models Through the Settings UI

For per-user customization without code changes, OpenMAIC exposes **default model selectors** in provider-specific settings panels.

### ASR Settings Panel

The ASR settings component at [`components/settings/asr-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/asr-settings.tsx) renders a dropdown bound to the provider's default:

```tsx
// components/settings/asr-settings.tsx (lines 374-376)
<Select
  value={asrProvidersConfig[selectedProviderId]?.modelId || asrProvider?.defaultModelId}
  onChange={newId => {
    updateProviderConfig(selectedProviderId, { modelId: newId });
  }}
>
  {/* model options */}
</Select>

```

The `|| asrProvider?.defaultModelId` fallback ensures the preset default appears when no user override exists.

### TTS Settings Panel

Similarly, [`components/settings/tts-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/tts-settings.tsx) at line 192 uses the same pattern for text-to-speech providers:

```tsx
// components/settings/tts-settings.tsx (line 192)
// TTS provider default model fallback
ttsProvider?.defaultModelId

```

### Custom Provider Default Models

When adding non-preset providers, the **Add Audio Provider dialog** at [`components/settings/add-audio-provider-dialog.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/add-audio-provider-dialog.tsx) captures a custom default model:

```tsx
// components/settings/add-audio-provider-dialog.tsx (lines 15-108)
const [defaultModel, setDefaultModel] = useState('');

// On submission, the default model passes to the store
addCustomTTSProvider(id, name, baseUrl, requiresApiKey, defaultModel.trim());

```

This allows arbitrary model identifiers for self-hosted or experimental providers.

---

## Method 3: Direct Settings Store Manipulation

For headless deployments or initialization scripts, modify the settings store directly:

```typescript
// Programmatic default model assignment
import { useSettingsStore } from 'lib/store/settings';

// Update specific provider configuration
const updateDefaultModel = (providerId: string, modelId: string) => {
  const { updateProviderConfig } = useSettingsStore.getState();
  updateProviderConfig(providerId, { modelId });
};

```

The **settings store** ([`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts)) persists these values to local storage or configured backend, becoming the authoritative source on subsequent application launches.

---

## Default Model Resolution Priority

OpenMAIC resolves the effective model through this cascade:

1. **Explicit model ID** in API call or request parameter
2. **User-configured `modelId`** from settings store (`audioProviderConfig.modelId`)
3. **Preset `defaultModelId`** from active token plan
4. **Provider hardcoded fallback** (if implemented by specific provider)

This design allows granular override at each layer without breaking existing workflows.

---

## Key Files for Default Model Configuration

| File Path | Purpose |
|-----------|---------|
| [`lib/config/token-plan-presets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/token-plan-presets.ts) | Defines preset-level `defaultModelId` for system-wide defaults |
| [`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts) | Persists and serves user-override default models |
| [`components/settings/asr-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/asr-settings.tsx) | UI for ASR default model selection (lines 374-376) |
| [`components/settings/tts-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/tts-settings.tsx) | UI for TTS default model selection (line 192) |
| [`components/settings/add-audio-provider-dialog.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/add-audio-provider-dialog.tsx) | Dialog for custom provider default model entry (lines 15-108) |

---

## Summary

- **Token-plan presets** in [`lib/config/token-plan-presets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/token-plan-presets.ts) provide durable, deployable default models via the `defaultModelId` field
- **Settings UI components** in [`components/settings/asr-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/asr-settings.tsx) and [`components/settings/tts-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/tts-settings.tsx) enable user-level customization with preset fallback
- **Custom providers** accept default models through [`add-audio-provider-dialog.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/add-audio-provider-dialog.tsx) for external service integration
- The **settings store** at [`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts) maintains `modelId` overrides that supersede preset values at runtime

---

## Frequently Asked Questions

### How do I change the default model for all users in OpenMAIC?

Edit [`lib/config/token-plan-presets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/token-plan-presets.ts) and modify the `defaultModelId` value in the relevant preset object. Redeploy the application for changes to take effect. According to the OpenMAIC source, the preset's `defaultModelId` seeds the provider configuration when `applyTokenPlan` runs.

### Why does my default model reset after restarting OpenMAIC?

The settings store likely lacks persistence configuration, or a token plan re-initialization overwrites your change. Verify that [`lib/store/settings.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/settings.ts) properly hydrates from storage, and check whether your deployment reapplies presets on startup. User-specific `modelId` values should survive restarts if the store persists correctly.

### Can I set different default models for ASR and TTS providers?

Yes. OpenMAIC maintains separate provider configurations in the settings store. Use [`components/settings/asr-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/asr-settings.tsx) for speech recognition defaults and [`components/settings/tts-settings.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/settings/tts-settings.tsx) for text-to-speech defaults. Each provider type has independent `defaultModelId` resolution.

### What format should I use for custom default model IDs?

OpenMAIC accepts arbitrary strings through [`add-audio-provider-dialog.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/add-audio-provider-dialog.tsx), mapping directly to provider API expectations. For built-in providers, use identifiers matching the upstream service's model catalog (e.g., `speech-2.8-hd` for THU Speech services).