# How to Add a New LLM Provider to Cherry Studio: A Complete Guide

> Effortlessly add a new LLM provider to Cherry Studio. Follow our guide to declare provider metadata, register models, and integrate seamlessly into the Model Selector.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**To add a new LLM provider to Cherry Studio, declare the provider metadata in [`src/renderer/src/config/providers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/providers.ts), register its models in [`src/renderer/src/config/models/default.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/models/default.ts), and optionally add a logo asset, after which the Redux store automatically surfaces the provider in the Model Selector dropdown.**

Cherry Studio is an open-source desktop client for large language models hosted at `cherryhq/cherry-studio`. Its provider architecture centralizes all LLM configurations in the renderer process, allowing you to integrate any OpenAI-compatible API—or custom protocol—without touching UI components.

## Step 1: Declare the Provider Configuration

All system providers are registered in the **SYSTEM_PROVIDERS_CONFIG** object inside [`src/renderer/src/config/providers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/providers.ts). This `Record<SystemProviderId, SystemProvider>` maps a unique provider ID to its configuration, including API endpoints, authentication placeholders, and branding.

Add your provider following the `SystemProvider` interface structure:

```typescript
// src/renderer/src/config/providers.ts
export const SYSTEM_PROVIDERS_CONFIG: Record<SystemProviderId, SystemProvider> = {
  // …existing providers…

  mycoolai: {
    id: 'mycoolai',                     // unique identifier used throughout the app
    name: 'MyCoolAI',
    type: 'openai',                     // protocol type (openai, anthropic, etc.)
    apiKey: '',                         // placeholder for user’s API key
    apiHost: 'https://api.mycool.ai',   // base URL for requests
    anthropicApiHost: undefined,        // only required for mixed-type providers
    models: [],                         // populated automatically from models config
    isSystem: true,
    enabled: false                      // default state; enable in Settings → Provider Settings
  },
};

```

The `type` field determines how **providerConfig.ts** normalizes the API host. When the application initializes, `formatProviderApiHost` automatically appends version paths (e.g., `/v1`) to OpenAI-compatible endpoints.

## Step 2: Register the Provider’s Models

Each model must be defined as a **Model** record and associated with your provider ID through the `provider` field. In [`src/renderer/src/config/models/default.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/models/default.ts), export the model objects and add them to **SYSTEM_MODELS**:

```typescript
// src/renderer/src/config/models/default.ts
export const mycoolModelA: Model = {
  id: 'mycool-chat-1.0',
  name: 'MyCool Chat 1.0',
  provider: 'mycoolai',      // must match the ID in SYSTEM_PROVIDERS_CONFIG
  group: 'MyCool'
};

export const mycoolModelB: Model = {
  id: 'mycool-image-1.0',
  name: 'MyCool Image 1.0',
  provider: 'mycoolai',
  group: 'MyCool'
};

export const SYSTEM_MODELS: Record<SystemProviderId | 'defaultModel', Model[]> = {
  // …other provider entries…
  mycoolai: [mycoolModelA, mycoolModelB],
};

```

The `SYSTEM_MODELS` record is keyed by provider ID. When the application loads, helper functions like `getProviderByModel` and `getProviderById` resolve the relationship between models and their parent providers using these exact structures.

## Step 3: Add Provider Branding (Optional)

To display a logo in the provider settings and model dropdown, place a PNG or SVG file in `src/renderer/src/assets/images/providers/` (e.g., `mycoolai.png`), then import and map it in **PROVIDER_LOGO_MAP** at the bottom of [`providers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/providers.ts):

```typescript
// src/renderer/src/config/providers.ts
import MyCoolAIProviderLogo from '@renderer/assets/images/providers/mycoolai.png';

export const PROVIDER_LOGO_MAP: Record<SystemProviderId, string> = {
  // …existing mappings…
  mycoolai: MyCoolAIProviderLogo,
};

```

## How the Architecture Propagates Changes

Cherry Studio uses a **Redux-driven store** to manage provider state. The `llmSlice` in [`src/renderer/src/store/llm.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/llm.ts) initializes its provider list from `SYSTEM_PROVIDERS` (the values of `SYSTEM_PROVIDERS_CONFIG`):

```typescript
// src/renderer/src/store/llm.ts
initialState: {
  providers: SYSTEM_PROVIDERS,  // seeded from your config changes
  // …other state…
}

```

The **ModelSelector** component ([`src/renderer/src/components/ModelSelector.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/components/ModelSelector.tsx)) consumes `state.llm.providers` via Redux selectors. Because the UI resolves models through this global state rather than hardcoded lists, your new provider appears immediately in the dropdown after configuration—no rebuild of React components required.

## Verifying Your Implementation

Launch the development server to test the integration:

```bash
pnpm dev

```

1. Navigate to **Settings → Provider Settings** and enable your new provider (e.g., *MyCoolAI*).
2. Open the **Model Selector** from any chat interface.
3. Verify that your registered models (e.g., `mycool-chat-1.0`) appear in the dropdown and respect the grouping defined in the `group` field.

## Summary

- **Configuration-driven**: Adding a provider requires only editing [`src/renderer/src/config/providers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/providers.ts) and [`src/renderer/src/config/models/default.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/config/models/default.ts).
- **Automatic UI sync**: The Redux store in [`src/renderer/src/store/llm.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/llm.ts) and the `ModelSelector` component read from centralized config objects, eliminating the need for UI modifications.
- **Type-safe architecture**: The `SystemProvider` and `Model` interfaces enforce consistent metadata across the application.
- **API normalization**: The [`providerConfig.ts`](https://github.com/cherryhq/cherry-studio/blob/main/providerConfig.ts) utility ensures host URLs conform to provider-specific expectations automatically.

## Frequently Asked Questions

### Do I need to modify the React components to display the new provider?

No. The `ModelSelector` component in [`src/renderer/src/components/ModelSelector.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/components/ModelSelector.tsx) renders providers from the Redux store (`state.llm.providers`), which is initialized from `SYSTEM_PROVIDERS_CONFIG`. Once you add your provider to the configuration files and enable it in settings, it automatically appears in all relevant UI dropdowns.

### What values are valid for the `type` field in the provider configuration?

The `type` field accepts protocol identifiers like `'openai'`, `'anthropic'`, or `'gemini'`. This value determines how [`src/renderer/src/aiCore/provider/providerConfig.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/aiCore/provider/providerConfig.ts) processes the `apiHost` via `formatProviderApiHost`. For OpenAI-compatible services, use `'openai'` to ensure proper URL normalization (e.g., automatic `/v1` path handling).

### Can I add a provider that requires custom authentication headers beyond a standard API key?

Yes. While the `SystemProvider` interface includes a standard `apiKey` field, Cherry Studio’s architecture routes all provider configurations through [`providerConfig.ts`](https://github.com/cherryhq/cherry-studio/blob/main/providerConfig.ts). For custom authentication schemes, you would extend the `SystemProvider` interface in the TypeScript definitions and update the AI core logic to handle your specific headers, though the basic registration steps in [`providers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/providers.ts) and [`models/default.ts`](https://github.com/cherryhq/cherry-studio/blob/main/models/default.ts) remain unchanged.

### Why don’t my new models appear immediately after editing the configuration files?

Ensure you have enabled the provider in **Settings → Provider Settings**. The `enabled` field in `SYSTEM_PROVIDERS_CONFIG` defaults to `false` for system providers. Additionally, verify that the `provider` field in your `Model` definitions exactly matches the `id` used in `SYSTEM_PROVIDERS_CONFIG`, as the lookup functions are case-sensitive.