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

To add a new LLM provider to Cherry Studio, declare the provider metadata in src/renderer/src/config/providers.ts, register its models in 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. 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:

// 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, export the model objects and add them to SYSTEM_MODELS:

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

// 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 initializes its provider list from SYSTEM_PROVIDERS (the values of SYSTEM_PROVIDERS_CONFIG):

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

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 and src/renderer/src/config/models/default.ts.
• Automatic UI sync: The Redux store in 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 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 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 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. 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 and 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.

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