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

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)
2. Token-plan preset definitions – hardcoded defaults in 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, each preset object includes a defaultModelId property:

// 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) propagates preset values to runtime configuration:

// 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 renders a dropdown bound to the provider's default:

// 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 at line 192 uses the same pattern for text-to-speech providers:

// 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 captures a custom default model:

// 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:

// 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) 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	Defines preset-level defaultModelId for system-wide defaults
lib/store/settings.ts	Persists and serves user-override default models
components/settings/asr-settings.tsx	UI for ASR default model selection (lines 374-376)
components/settings/tts-settings.tsx	UI for TTS default model selection (line 192)
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 provide durable, deployable default models via the defaultModelId field
• Settings UI components in components/settings/asr-settings.tsx and components/settings/tts-settings.tsx enable user-level customization with preset fallback
• Custom providers accept default models through add-audio-provider-dialog.tsx for external service integration
• The settings store at 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 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 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 for speech recognition defaults and 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, 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).

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