# Cherry Studio User Guide

Cherry Studio is a cross-platform desktop client that lets you chat with virtually any large language model (LLM) — cloud services like OpenAI, Anthropic, and Google Gemini, plus local models served by Ollama or LM Studio — all from one native application on Windows, macOS, and Linux. Beyond chat, it bundles a knowledge base (RAG), AI image generation, document translation, autonomous agents, Model Context Protocol (MCP) tools, a web-search layer, and even a local API server that re-exposes all your configured providers behind a single OpenAI- and Anthropic-compatible endpoint.

This guide walks you through installing Cherry Studio, configuring your first model provider, and using every major feature. It is written for end users: people who want to *use* Cherry Studio productively. Architecture, deployment, security internals, and developer reference material live in the companion **Admin Guide**.

> [!NOTE]
> Cherry Studio is free and open source under the AGPL-3.0 license. A separately licensed **Enterprise Edition** with centralized model/knowledge management and private deployment is also available — see [About Editions & Licensing](#about-editions--licensing).

---

## Table of Contents

1. [Quick Start](#quick-start)
2. [Installation](#installation)
3. [Connecting a Model Provider](#connecting-a-model-provider)
4. [Chatting with Models](#chatting-with-models)
5. [Assistants & the Library](#assistants--the-library)
6. [Knowledge Bases (RAG)](#knowledge-bases-rag)
7. [Web Search](#web-search)
8. [MCP Servers & Tools](#mcp-servers--tools)
9. [Agents & Channels](#agents--channels)
10. [Skills](#skills)
11. [AI Paintings (Image Generation)](#ai-paintings-image-generation)
12. [Translation](#translation)
13. [Notes, Files & Code](#notes-files--code)
14. [Mini Apps](#mini-apps)
15. [The Built-in API Server](#the-built-in-api-server)
16. [Quick Assistant & Selection Assistant](#quick-assistant--selection-assistant)
17. [Files, Documents & OCR](#files-documents--ocr)
18. [Backup & Data Management](#backup--data-management)
19. [Appearance, Shortcuts & Preferences](#appearance-shortcuts--preferences)
20. [Updating Cherry Studio](#updating-cherry-studio)
21. [Troubleshooting](#troubleshooting)
22. [Frequently Asked Questions](#frequently-asked-questions)
23. [Settings Reference](#settings-reference)
24. [About Editions & Licensing](#about-editions--licensing)

---

## Quick Start

If you just want to send your first message, here is the shortest path:

1. **Download and install** Cherry Studio for your operating system from the [official releases page](https://github.com/CherryHQ/cherry-studio/releases) (see [Installation](#installation)).
2. **Launch the app.** It opens on the Launchpad home screen.
3. **Open `Settings → Providers`** and pick a provider (for example, OpenAI).
4. **Paste your API key** into the provider's API Key field. For local models, point the provider at your Ollama or LM Studio endpoint instead.
5. **Go to the Chat page**, choose a model from the model selector at the top of the input bar, type a message, and press **Enter**.

```text
Launchpad → Settings → Providers → (enter API key) → Chat → pick model → type → Enter
```

> [!TIP]
> Cherry Studio ships with **300+ pre-configured assistants** (specialized system prompts) and a large catalog of known providers and models. You usually only need to supply an API key — the model list, endpoints, and capabilities are already filled in for popular services.

> [!IMPORTANT]
> Cherry Studio never sends your prompts to Cherry Studio's own servers for inference. Requests go directly from your machine to whichever provider you configured. Your API keys are stored locally.

---

## Installation

Cherry Studio is a packaged desktop application. **No environment setup, runtime, or build step is required** — download the installer for your platform and run it.

### Where to download

| Source | URL |
|--------|-----|
| GitHub Releases (recommended) | `https://github.com/CherryHQ/cherry-studio/releases` |
| Official website | `https://cherry-ai.com` |
| Official documentation | `https://docs.cherry-ai.com/docs/en-us` |

### Platform packages

Cherry Studio publishes the following installer types per platform:

=== "Windows"

    - **`Cherry Studio-<version>-<arch>-setup.exe`** — NSIS installer. Lets you choose the install directory and creates a desktop shortcut. Available for `x64` and `arm64`.
    - **`Cherry Studio-<version>-<arch>-portable.exe`** — a no-install portable build you can run from a USB stick or a folder of your choice.

=== "macOS"

    - **`Cherry Studio-<version>-<arch>.dmg`** — standard drag-to-Applications disk image.
    - **`Cherry Studio-<version>-<arch>.zip`** — zipped application bundle (used by the auto-updater).
    - Universal coverage: Apple Silicon (`arm64`) and Intel (`x64`).

=== "Linux"

    - **`Cherry Studio-<version>-<arch>.AppImage`** — portable, no installation needed; mark executable and run.
    - **`Cherry Studio-<version>-<arch>.deb`** — Debian/Ubuntu package.
    - **`Cherry Studio-<version>-<arch>.rpm`** — Fedora/RHEL/openSUSE package.
    - Architectures: `x64` and `arm64`.

> [!NOTE]
> The application registers the `cherrystudio://` URL scheme. This lets web pages and integrations (for example, OAuth callbacks and MCP install links) hand control back to the desktop app.

### System requirements

| Requirement | Detail |
|-------------|--------|
| Operating system | Windows, macOS, or Linux (desktop) |
| Architecture | `x64` or `arm64` |
| Disk | Space for the app plus your chat history, knowledge-base vectors, and downloaded files |
| Network | Outbound HTTPS to your chosen AI providers; optional local network access for Ollama/LM Studio and LAN transfer |
| Git Bash (Windows only) | Required only if you use the **Code/Agent** features that spawn a shell. Cherry Studio auto-detects it and will prompt you to install [Git for Windows](https://git-scm.com/downloads/win) if missing. |

> [!TIP]
> On first launch, no API keys are configured, so model lists will be empty until you add a provider. That is expected — continue to [Connecting a Model Provider](#connecting-a-model-provider).

---

## Connecting a Model Provider

A **provider** is a service (or local server) that hosts models. Cherry Studio talks to many providers and presents their models in one unified interface.

### Add or enable a provider

1. Open **`Settings → Providers`**.
2. Browse the built-in provider list. Popular services — OpenAI, Anthropic, Google Gemini, and many others — are pre-listed with their default API endpoints.
3. Select a provider and enter its **API Key**. Some providers also let you override the **API Host** (base URL) if you use a proxy or compatible gateway.
4. Toggle the provider **on**. Its models now appear in the model selector throughout the app.

> [!TIP]
> You can filter the provider list and even pre-fill a new provider by passing data through the page — the Providers page accepts `addProviderData`, `filter`, and `id` parameters when navigated to from elsewhere in the app (for example, from an MCP or marketplace deep link).

### Provider categories

| Category | Examples | How to connect |
|----------|----------|----------------|
| Major cloud LLMs | OpenAI, Anthropic, Google Gemini | Paste an API key |
| OpenAI-compatible gateways | Any service exposing an OpenAI-style API | Set API Host + key; mark as OpenAI-compatible |
| Anthropic-compatible / Claude Code mode | Providers offering an Anthropic-style endpoint | Some auto-fill the endpoint when you select the mode |
| Local model servers | **Ollama**, **LM Studio** | Point the provider at the local server URL (no key needed) |
| Cloud auth providers | Google **Vertex AI**, GitHub **Copilot** | Use the built-in authentication flow rather than a static key |

> [!IMPORTANT]
> For **Vertex AI**, Cherry Studio uses Google service-account authentication (IAM). You must supply a valid service-account configuration; if it is missing you will see `VertexAI requires iam-gcp auth configuration.` For **GitHub Copilot**, use the in-app sign-in flow on the provider screen rather than entering a key manually.

### Managing models within a provider

Each enabled provider exposes a model list. From **`Settings → Providers`** (and the dedicated **`Settings → Model`** screen) you can:

- Add or remove individual models.
- Mark a model's capabilities (reasoning, tool use, vision, embedding, rerank) when they aren't auto-detected.
- Set default models for chat, the "quick" assistant, translation, and topic naming.

> [!NOTE]
> Cherry Studio keeps a curated model catalog, so newly released models are often recognized automatically with the right capabilities. If a model shows the wrong icon or capability, you can correct it in the model's settings.

---

## Chatting with Models

The **Chat** page is the heart of Cherry Studio. Reach it from the sidebar (it lives at the in-app route `/app/chat`).

### Anatomy of the chat screen

- **Assistant/topic sidebar** — your conversations are grouped into *topics* under an *assistant*. An assistant is a reusable configuration (system prompt + default model + parameters).
- **Message thread** — the running conversation, with full Markdown rendering, syntax-highlighted code blocks, math (KaTeX/MathJax), and Mermaid diagrams.
- **Input bar** — where you type. The model selector, attachment button, and tool toggles live here.

### Sending a message

1. Pick an **assistant** (or use the default) in the left sidebar.
2. Choose a **model** from the model selector in the input bar.
3. Type your prompt. Attach files or images with the attachment control if needed.
4. Press **Enter** to send (configurable; see [Shortcuts](#appearance-shortcuts--preferences)).

### Multi-model conversations

Cherry Studio can send the **same prompt to several models at once** and show their answers side by side — useful for comparing how different models handle a task. Enable multiple models in the model selector for a topic.

### Generation parameters

Each assistant exposes standard sampling controls. The application defaults are:

| Parameter | Default | Meaning |
|-----------|---------|---------|
| Temperature | `1.0` | Higher = more creative/random output |
| Context messages | `5` | How many prior messages are sent as context |
| Max tokens | `8192` | Upper bound on the response length |
| Stream usage | On | Token-usage stats are streamed with the response |
| Request timeout | 30 minutes | How long Cherry Studio waits for a slow/long response |

> [!TIP]
> Lower the **temperature** toward `0` for factual or coding tasks, and raise the **context messages** count when a conversation needs long memory (at the cost of more tokens per request).

### Reasoning, tools, and vision

Where a model supports them, Cherry Studio surfaces:

- **Reasoning effort** controls for reasoning-capable models.
- **Tool use** — the model can call MCP tools and built-in tools mid-conversation (see [MCP Servers & Tools](#mcp-servers--tools)).
- **Vision** — attach images to prompts for multimodal models.

### Topics and history

Conversations are organized as **topics**. You can rename, pin, search, and delete topics. A global search lets you find past messages across all topics. Cherry Studio stores everything locally (see [Backup & Data Management](#backup--data-management)).

---

## Assistants & the Library

An **assistant** packages a system prompt, a default model, and generation settings into a reusable persona. Cherry Studio ships with **300+ pre-configured assistants** covering writing, coding, translation, analysis, and more.

### Using a built-in assistant

1. Open the **Library** (route `/app/library`) or the assistant picker in Chat.
2. Browse or search the catalog.
3. Select an assistant to start a new topic with its prompt and settings applied.

### Creating a custom assistant

1. In the Library, choose **create a new assistant** (or duplicate an existing one).
2. Edit its **name**, **emoji/avatar**, **system prompt**, **default model**, and **parameters** (temperature, context count, max tokens).
3. Optionally attach a knowledge base, enable specific MCP servers, and enable skills.

### Prompts library

The **`Settings → Prompts`** screen manages reusable prompt snippets you can insert into conversations, separate from full assistants.

> [!TIP]
> Assistants are the right tool when you repeatedly need the same behavior (e.g., "translate to formal Japanese" or "review this code for security issues"). Save it once and pick it from the sidebar.

---

## Knowledge Bases (RAG)

A **knowledge base** lets a model answer using *your* documents. Cherry Studio indexes the documents into a local vector store and retrieves the most relevant passages at query time (retrieval-augmented generation, or RAG). Open the **Knowledge** page at `/app/knowledge`.

### Create a knowledge base

1. Go to the **Knowledge** page and create a new knowledge base.
2. Choose an **embedding model** (from any enabled provider that offers embeddings — for example OpenAI, Ollama, or Voyage).
3. Optionally choose a **rerank model** to improve retrieval ordering.

### Add content

You can add knowledge items from several sources:

- **Files** — text, PDF, Office documents, Markdown, CSV, XML, and images (with OCR).
- **Web pages and sitemaps** — fetched and converted to text.
- **Notes and folders** from inside Cherry Studio.

Cherry Studio extracts text, splits it into chunks, embeds the chunks, and stores them in a local vector database.

### Use a knowledge base in chat

Attach the knowledge base to an assistant or select it for a topic. When you ask a question, Cherry Studio retrieves relevant chunks and supplies them to the model as context, so answers are grounded in your documents.

> [!NOTE]
> Knowledge bases are also queryable through the [built-in API server](#the-built-in-api-server) via `POST /v1/knowledge-bases/search`, so external tools can search your indexed documents.

> [!WARNING]
> If a knowledge-base search returns a `400` error after upgrading (a known issue with certain embedding models such as SiliconFlow `bge-m3`), re-check that the embedding model selected for that knowledge base is still valid and re-index if necessary.

---

## Web Search

Cherry Studio can augment answers with live web results. Configure it under **`Settings → Web Search`**.

### Supported search providers

Cherry Studio integrates multiple search backends, including:

| Provider | Notes |
|----------|-------|
| Tavily | API-key based |
| Exa | API-key based |
| SearXNG | Self-hosted meta-search; requires at least one enabled general engine in your SearXNG config |
| Bocha | API-key based |
| Jina (Reader) | Fetches and reads page content |
| Querit | API-key based |
| MCP-based search | Provided through an MCP server (e.g., ExaMCP) |

### Configure web search

1. Open **`Settings → Web Search`**.
2. Select a provider and enter its API key (or host, for SearXNG).
3. Optionally set a **blacklist** of sites or URL patterns to exclude from results.
4. Enable web search per assistant or per message.

> [!TIP]
> You can restrict noisy or low-quality domains with match patterns in the blacklist. Invalid patterns are rejected with `Invalid match pattern` — use standard scheme/host patterns.

---

## MCP Servers & Tools

The **Model Context Protocol (MCP)** lets models use external tools — file access, browsers, search, custom APIs — through a standard interface. Cherry Studio is a full MCP client and even hosts built-in MCP servers. Manage everything under **`Settings → MCP`**.

### Ways to add an MCP server

| Method | Where | What it does |
|--------|-------|--------------|
| Built-in servers | `Settings → MCP → Builtin` | Enable servers that ship inside Cherry Studio (e.g., filesystem, browser) |
| Marketplaces | `Settings → MCP → Marketplaces` | Browse and install community MCP servers |
| NPX search | `Settings → MCP → NPX Search` | Find and install servers published to npm |
| Manual install | `Settings → MCP → MCP Install` | Add a server by command, URL, or config |
| Server list | `Settings → MCP → Servers` | Review, enable/disable, and edit installed servers |

### Server transport types

MCP servers can be **`stdio`** (a local process Cherry Studio spawns) or HTTP/streaming servers. Per-server settings are available at `Settings → MCP → settings/<serverId>`.

> [!IMPORTANT]
> Some MCP servers run local commands and may require runtimes like `uv`, `bun`, or Node. Cherry Studio can install helper binaries for you — see **`Settings → Plugins`** (Environment Dependencies), which can install `uv`, `bun`, and (on Intel Windows) the OpenVINO model server.

### Using tools in chat

Once an MCP server is enabled (globally or for a specific assistant), the model can call its tools during a conversation. You can review tool calls inline and, depending on the agent's permission mode, approve or deny them.

---

## Agents & Channels

The **Agents** page (`/app/agents`) runs more autonomous, multi-step AI workflows than a normal chat. Agents can hold their own instructions, model, allowed tools, MCP servers, and accessible file paths.

### Agent configuration

Each agent stores:

| Setting | Purpose |
|---------|---------|
| Name & description | Identify the agent |
| Instructions | The agent's system prompt / standing orders |
| Model (+ plan model, small model) | Primary model plus optional cheaper models for planning and lightweight steps |
| MCP servers | Which tool servers the agent may use |
| Allowed tools | The specific tools the agent is permitted to call |
| Accessible paths | Folders the agent may read/write |
| Permission mode | How tool calls are authorized (see below) |

### Permission modes

When an agent wants to use a tool (especially file edits or shell commands), the **permission mode** governs how that is approved:

| Mode | Behavior |
|------|----------|
| `default` | Ask for approval as configured |
| `acceptEdits` | Auto-approve edits |
| `bypassPermissions` | Run tools without prompting |
| `plan` | Plan the work without executing changes |

> [!CAUTION]
> `bypassPermissions` lets an agent run tools (including file writes and shell commands) without asking. Use it only with agents and tool sets you trust, and scope **accessible paths** as narrowly as possible.

### Channels — connect agents to messaging apps

Through **`Settings → Channels`**, an agent can be connected to an external messaging platform so people can talk to it where they already are. Supported channel types:

- **Telegram**
- **Feishu (Lark)**
- **QQ**
- **WeChat**
- **Discord**
- **Slack**

Each channel stores its own credentials and can be activated or deactivated independently. You can view per-channel logs and live status from the Channels screen.

> [!NOTE]
> Channel connectivity turns Cherry Studio into a lightweight bot host: an agent answers messages in your chosen app while running locally on your machine.

---

## Skills

**Skills** are packaged capabilities (instructions plus optional helper files) that you can attach to agents — comparable to Claude-style skills. Manage them at **`Settings → Skills`**.

### Installing skills

| Source | How |
|--------|-----|
| From a folder | Install a local skill directory |
| From a ZIP | Install a packaged skill archive |
| Sync builtin skills | Cherry Studio can sync its bundled skills into your skills folder |

Once installed, enable a skill for a specific agent. Each skill records its name, description, source, author, tags, and a content hash so updates can be detected.

> [!WARNING]
> A known issue can cause the builtin-skill sync to create stray folders with backslash paths under `~/Downloads` on some systems. If you see odd directories appear, you can safely remove them; the skills themselves live in Cherry Studio's skills directory.

---

## AI Paintings (Image Generation)

The **Paintings** page (`/app/paintings`) generates images from text prompts using image-capable providers and models you've configured.

1. Open **Paintings**.
2. Choose an image model/provider.
3. Enter a prompt and any model-specific options (size, style, etc., depending on the provider).
4. Generate, preview, and save the resulting image.

Generated images are saved through Cherry Studio's file system, so you can re-open or export them later.

---

## Translation

The **Translate** page (`/app/translate`) provides fast, AI-powered translation independent of the chat thread.

1. Open **Translate**.
2. Paste or type the source text.
3. Choose the **target language**.
4. Cherry Studio streams the translation using your configured translation model.

> [!NOTE]
> If you pick an unsupported target language you'll see `Invalid target language`. Translation can be cancelled mid-flight; an aborted translation is normal and not an error.

---

## Notes, Files & Code

### Notes

The **Notes** page (`/app/notes`) is a built-in rich-text/Markdown notebook. Notes can be organized, searched, and fed into knowledge bases. Renaming a note to a name that already exists is blocked with `Target name already exists`.

### Files

The **Files** page (`/app/files`) is a manager for documents you've uploaded or generated inside Cherry Studio — attachments, exported documents, painting outputs, and knowledge-base sources.

### Code (CLI)

The **Code** page (`/app/code`) and **OpenClaw** page (`/app/openclaw`) provide an agentic coding experience backed by the Claude Agent SDK / Claude Code runtime. These let an agent read and edit code in a working directory using tools, subject to the permission modes described in [Agents & Channels](#agents--channels).

> [!IMPORTANT]
> On Windows, the Code/Agent shell features require **Git Bash**. Cherry Studio auto-discovers it; if it isn't found, install [Git for Windows](https://git-scm.com/downloads/win) and set the path in `Settings → General` if needed.

---

## Mini Apps

**Mini Apps** (`/app/mini-app`) embed external web applications (such as AI web services — Claude, Perplexity, Poe, and others) inside Cherry Studio, so you can use them without leaving the app. Each mini app opens in its own in-app browser view. You can pin frequently used mini apps for quick access.

> [!NOTE]
> Mini apps run in a sandboxed web view that is separate from your main session, with its own storage partition.

---

## The Built-in API Server

One of Cherry Studio's most powerful features is its **local API server** (internally called *CSaaS* — Cherry Studio as a Service). It re-exposes **all your configured providers** behind a single, standard API, so other tools on your machine can use Cherry Studio as a unified AI gateway. Configure it at **`Settings → API Server`**.

### Enable the server

1. Open **`Settings → API Server`**.
2. Set the **host** and **port** to listen on.
3. Copy or set the **API key** clients must present.
4. Start the server.

### Endpoints

| Method | Path | Compatible with | Auth |
|--------|------|-----------------|------|
| `GET` | `/health` | — (status check) | None |
| `GET` | `/` | API info / endpoint list | None |
| `GET` | `/api-docs` | Swagger UI | None |
| `GET` | `/api-docs.json` | OpenAPI spec | None |
| `POST` | `/v1/chat/completions` | **OpenAI** Chat Completions | API key |
| `POST` | `/v1/messages` | **Anthropic** Messages | API key |
| `POST` | `/{provider}/v1/messages` | Anthropic, provider chosen by URL | API key |
| `GET` | `/v1/mcps` | List your MCP servers | API key |
| `GET` | `/v1/mcps/{server_id}` | One MCP server's info | API key |
| `POST` | `/v1/knowledge-bases/search` | Search your knowledge bases | API key |
| `GET` | `/v1/knowledge-bases` | List knowledge bases | API key |

### Authentication

Protected endpoints require your API key, supplied **either** as:

- `x-api-key: <your key>`, **or**
- `Authorization: Bearer <your key>`

The key is compared with a constant-time check. Requests without credentials get `401`; wrong credentials get `403`.

### Model identifiers

For the OpenAI-style `/v1/chat/completions` and the default `/v1/messages` endpoint, name models as **`providerId::modelId`** (the provider id and model id joined by a double colon, e.g. `my-anthropic::claude-3-5-sonnet-20241022`). With the `/{provider}/v1/messages` form, put the provider in the URL and use the bare model id in the body.

### Example: call Cherry Studio like OpenAI

```bash
curl http://127.0.0.1:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "model": "my-openai::gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'
```

```text
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "my-openai:gpt-4o",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hi! ..." }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}
```

Set `"stream": true` to receive a Server-Sent Events stream that ends with `data: [DONE]`.

> [!TIP]
> Point any OpenAI-compatible tool (a coding assistant, a script, another desktop app) at `http://<host>:<port>/v1` with your Cherry Studio API key, and it will transparently use whichever Cherry Studio provider you named in the `model` field. Browse the live, interactive API reference at `http://<host>:<port>/api-docs`.

> [!CAUTION]
> The API server accepts requests from any origin (CORS `*`). Bind it to `127.0.0.1` (localhost) unless you deliberately want other machines on your network to reach it, and always keep a strong API key set.

---

## Quick Assistant & Selection Assistant

Cherry Studio can help you anywhere on your desktop, not just inside its main window.

### Quick Assistant

A floating, global-hotkey popup for fast questions without switching to the main window. Configure it at **`Settings → Quick Assistant`** — set the hotkey and the default model it uses.

### Selection Assistant

The **Selection Assistant** acts on text you highlight in *other* applications: select text anywhere, and a small toolbar offers AI actions (translate, summarize, explain, etc.). Configure it at **`Settings → Selection Assistant`**.

> [!NOTE]
> On macOS, the Selection Assistant needs **Accessibility** permission to read your selection. Cherry Studio will prompt you to grant trust in System Settings the first time you enable it.

### Scheduled Tasks

Under **`Settings → Scheduled Tasks`** you can schedule recurring AI tasks (for example, a daily summary) that run on a timer.

---

## Files, Documents & OCR

Cherry Studio reads a wide range of document formats for chat attachments and knowledge bases, including text, PDF, Microsoft Office files, Markdown, CSV, XML, EPUB, and images.

### OCR and document conversion

For images and scanned documents, Cherry Studio can extract text using a configurable **file-processing** pipeline (`Settings → File Processing`). Available processors include built-in OCR engines and external services. Each processor advertises which capabilities it supports (image-to-text, document-to-markdown); if you pick a processor that lacks a needed capability you'll get a clear error like `File processor ... does not support ...`.

> [!TIP]
> Choose a default processor per capability in **`Settings → File Processing`** so attachments and knowledge-base imports are handled automatically.

---

## Backup & Data Management

All your data — conversations, assistants, knowledge bases, settings — is stored **locally**. Manage it under **`Settings → Data`**.

### Backup destinations

| Destination | Use case |
|-------------|----------|
| **Local directory** | Export a backup file to a folder on disk |
| **WebDAV** | Back up to any WebDAV server (Nextcloud, etc.) |
| **Nutstore (坚果云)** | Built-in WebDAV-based cloud sync with SSO sign-in |
| **Amazon S3** | Back up to an S3-compatible bucket |
| **LAN transfer** | Send a backup directly to another device on your local network |

For each remote destination you can back up, restore, list existing backups, check the connection, and delete old backups.

### Factory reset

The Data settings include a **reset all data** (factory reset) action that clears your Cherry Studio data and returns the app to a clean state.

> [!CAUTION]
> A factory reset is irreversible. Take a backup first. Likewise, restoring a backup overwrites current data.

> [!WARNING]
> **LAN transfer** only accepts ZIP files and enforces a maximum file size. Transfers of unsupported types or oversized files are rejected (`Only ZIP files are supported`, `File too large...`).

---

## Appearance, Shortcuts & Preferences

### Themes

Cherry Studio supports **Light** and **Dark** themes and a **transparent window** effect. The community maintains additional themes you can install (gallery at `https://cherrycss.com`). Set theme and appearance options in **`Settings → General`**.

### Language

The interface is fully internationalized (English, Simplified/Traditional Chinese, Japanese, Korean, Russian, German, and many more). Choose your language in **`Settings → General`**.

### Keyboard shortcuts

Customize shortcuts in **`Settings → Shortcuts`**, including the global hotkeys for the Quick Assistant and Selection Assistant. You can also reset, clear cache, and toggle developer tools from the app.

### Other preferences

| Setting | Where | Notes |
|---------|-------|-------|
| Launch on boot | `Settings → General` | Start Cherry Studio when you log in |
| Spell check | `Settings → General` | Enable/disable and choose languages |
| Zoom factor | `Settings → General` / shortcuts | Scale the whole UI |
| Integrations | `Settings → Integrations` | Connect external services like Obsidian vaults |
| Data path | `Settings → Data` | Change where Cherry Studio stores its data (requires restart) |

---

## Updating Cherry Studio

Cherry Studio checks for updates automatically and can download and install them in place. You can also check manually from **`Settings → About`**.

### How updates flow

The update feed is hosted by Cherry Studio (`releases.cherry-ai.com`), with GitHub and GitCode mirrors. Updates follow a **segmented upgrade path** so very old installs migrate safely:

- Users below **v1.8.1** are first routed to **v1.8.1** (a required "gateway" version).
- The **v2.0.0** major release is a required intermediate stop for moving into the v2.x line.
- Otherwise you receive the latest release in your line (v1.x or v2.x), with optional **rc** and **beta** channels.

> [!NOTE]
> If you are on a very old version, you may be asked to upgrade in two steps. This is intentional — it ensures your data migrates cleanly across breaking changes.

> [!TIP]
> Linux **AppImage** users: if your distribution doesn't auto-update AppImages, just download the newest `.AppImage` from the releases page.

---

## Troubleshooting

Below are common issues and how to resolve them. Errors shown in quotes are the actual messages Cherry Studio produces.

### Models or model lists are empty

**Cause:** No provider is enabled, or the provider has no API key.
**Solution:** Open `Settings → Providers`, enable a provider, and enter a valid API key. For local models, ensure Ollama/LM Studio is running and the provider points to its URL.
**Prevention:** Keep at least one provider enabled and verified.

### Error: `VertexAI requires iam-gcp auth configuration.`

**Cause:** The Vertex AI provider is selected but no valid Google service-account/IAM configuration is supplied.
**Solution:** Provide a valid service-account key/configuration in the Vertex AI provider settings.
**Prevention:** Complete the Vertex AI auth setup before selecting its models.

### Error: `Provider '<id>' not found` (via the API server)

**Cause:** The `model` field used a `providerId::modelId` whose provider isn't configured or enabled.
**Solution:** Verify the provider id matches an enabled provider, and use the exact `providerId::modelId` format (double colon).
**Prevention:** List providers via `GET /v1/...` or check `Settings → Providers` for the correct id.

### Error: `Unauthorized: missing credentials` / `Forbidden` (via the API server)

**Cause:** The request had no `x-api-key`/`Authorization` header, or the key was wrong, or no API key is set in `Settings → API Server`.
**Solution:** Set an API key in API Server settings and send it as `x-api-key` or `Authorization: Bearer`.
**Prevention:** Store the key in your client config and rotate it if exposed.

### Knowledge-base search returns `400`

**Cause:** The embedding model attached to the knowledge base is invalid or incompatible (a reported issue with some `bge-m3` deployments).
**Solution:** Re-select a working embedding model and re-index the knowledge base.
**Prevention:** Use an embedding model from a verified, enabled provider.

### Web search fails or returns nothing

**Cause:** Missing API key/host, or (for SearXNG) no general engine enabled — `No enabled general web search engines found in Searxng configuration`.
**Solution:** Enter the provider's credentials in `Settings → Web Search`; for SearXNG enable at least one general engine on your instance.
**Prevention:** Test the search provider after configuring it.

### Error: `Only ZIP files are supported` / `File too large...` during LAN transfer

**Cause:** LAN transfer received a non-ZIP file or a file over the size limit.
**Solution:** Send a ZIP archive under the limit; for large data use WebDAV/S3 backup instead.
**Prevention:** Use the in-app backup flow, which packages data as ZIP automatically.

### Windows: Code/Agent features fail to run a shell

**Cause:** Git Bash isn't installed or its path isn't set — `Git Bash not found. Please install Git for Windows`.
**Solution:** Install [Git for Windows](https://git-scm.com/downloads/win); Cherry Studio auto-detects it, or set the path manually.
**Prevention:** Install Git Bash before using agentic coding features.

### Assistant stops responding after a tool call

**Cause:** A reported issue where an assistant can stall after a successful tool/search call.
**Solution:** Send a new message to nudge it, or disable the offending tool for that assistant; update to the latest version where fixes land.
**Prevention:** Keep Cherry Studio updated.

### Streaming output looks broken or stops early

**Cause:** Network interruptions or provider-side streaming issues (reported with some models).
**Solution:** Disable streaming for that assistant to receive a single complete response, or retry; update Cherry Studio.
**Prevention:** Use a stable network and an up-to-date version.

### A file or path operation is rejected

**Cause:** Cherry Studio sandboxes file operations and rejects paths outside allowed directories (`Path is outside allowed directory`, `Permission denied`).
**Solution:** Keep operations within the agent's **accessible paths** and ensure you have OS permissions for the target folder.
**Prevention:** Configure accessible paths deliberately for agents.

### The app won't update or is stuck on an old version

**Cause:** You're on a very old version that must pass through a gateway release.
**Solution:** Let the updater route you to v1.8.1 (and v2.0.0 if moving to v2.x), then update again; or download the latest installer manually.
**Prevention:** Update regularly so you stay within one upgrade segment.

---

## Frequently Asked Questions

**Q: Is Cherry Studio free?**
Yes. The Community Edition is open source under AGPL-3.0 and free to use, including for commercial purposes (subject to the AGPL terms). A commercially licensed Enterprise Edition is also available.

**Q: Does Cherry Studio host the AI models?**
No. Cherry Studio is a client. It sends requests directly from your computer to whichever provider you configured (OpenAI, Anthropic, your local Ollama, etc.). It does not run inference on its own servers.

**Q: Where are my API keys and chats stored?**
Locally on your machine, in Cherry Studio's user-data directory. Nothing is uploaded unless you set up a backup destination.

**Q: Can I use local models with no internet?**
Yes. Configure a local provider (Ollama or LM Studio) pointing at your local server. Cloud features (cloud models, web search, some OCR) still need internet.

**Q: Can other programs use Cherry Studio as an AI backend?**
Yes — enable the [built-in API server](#the-built-in-api-server) and point any OpenAI- or Anthropic-compatible client at it.

**Q: How do I move my data to another computer?**
Use `Settings → Data` to back up (local file, WebDAV, S3, Nutstore, or LAN transfer) and restore on the other machine.

**Q: What's the difference between an assistant and an agent?**
An **assistant** is a chat persona (prompt + model + settings). An **agent** is more autonomous: it can plan, use tools/MCP servers, access files, and even connect to messaging channels.

**Q: How do I connect Cherry Studio to Telegram/Discord/Slack?**
Create an agent, then add a channel of that type in `Settings → Channels` with the platform's credentials. Supported: Telegram, Feishu, QQ, WeChat, Discord, Slack.

**Q: Can I add a provider that isn't in the list?**
Yes. Add a custom provider with its API host and key. If it speaks the OpenAI or Anthropic API, mark it compatible and it works like the built-ins.

**Q: How do I get the interactive API documentation?**
Start the API server and open `http://<host>:<port>/api-docs` for Swagger UI, or fetch `/api-docs.json` for the raw OpenAPI spec.

**Q: Does it support themes?**
Yes — light, dark, and a transparent window, plus community themes from the theme gallery.

**Q: What languages does the interface support?**
Many, including English, Simplified and Traditional Chinese, Japanese, Korean, Russian, German, French, Spanish, and more.

**Q: How do I report a bug or request a feature?**
Use the project's [GitHub Issues](https://github.com/CherryHQ/cherry-studio/issues) and [Discussions](https://github.com/CherryHQ/cherry-studio/discussions).

---

## Settings Reference

Every settings panel and what it controls:

| Panel | Route | Controls |
|-------|-------|----------|
| Providers | `/settings/provider` | LLM providers, API keys/hosts, model lists |
| Model | `/settings/model` | Default models, capabilities, per-model options |
| MCP | `/settings/mcp` | MCP servers, marketplaces, NPX search, builtin servers, install |
| Web Search | `/settings/websearch` | Search provider, keys, blacklist |
| General | `/settings/general` | Theme, language, launch on boot, spell check, zoom, Git Bash path |
| File Processing | `/settings/file-processing` | OCR/document processors and defaults |
| Data | `/settings/data` | Backup/restore (local, WebDAV, Nutstore, S3, LAN), data path, factory reset |
| Channels | `/settings/channels` | Connect agents to Telegram/Feishu/QQ/WeChat/Discord/Slack |
| API Server | `/settings/api-server` | Local OpenAI/Anthropic-compatible server (host, port, API key) |
| Integrations | `/settings/integrations` | External integrations (e.g., Obsidian vaults) |
| Prompts | `/settings/prompts` | Reusable prompt snippets |
| Plugins | `/settings/plugins` | Environment dependencies (`uv`, `bun`, OVMS installers) |
| Quick Assistant | `/settings/quick-assistant` | Global popup hotkey and model |
| Selection Assistant | `/settings/selection-assistant` | Actions on text selected in other apps |
| Scheduled Tasks | `/settings/scheduled-tasks` | Timed/recurring AI tasks |
| Shortcuts | `/settings/shortcut` | Keyboard shortcuts |
| Skills | `/settings/skills` | Install/manage agent skills |
| About | `/settings/about` | Version, updates, links |

Main feature pages:

| Page | Route | What it does |
|------|-------|--------------|
| Home / Launchpad | `/home` | Landing screen and app launcher |
| Chat | `/app/chat` | Conversations with assistants and models |
| Agents | `/app/agents` | Autonomous, tool-using agents |
| Knowledge | `/app/knowledge` | Knowledge bases (RAG) |
| Library | `/app/library` | Assistant catalog (300+) |
| Paintings | `/app/paintings` | AI image generation |
| Translate | `/app/translate` | AI translation |
| Notes | `/app/notes` | Rich-text/Markdown notes |
| Files | `/app/files` | File manager |
| Code | `/app/code` | Agentic coding (CLI) |
| OpenClaw | `/app/openclaw` | Agentic coding workspace |
| Mini Apps | `/app/mini-app` | Embedded web apps |

---

## About Editions & Licensing

| | Community Edition | Enterprise Edition |
|--|-------------------|--------------------|
| Open source | Yes (AGPL-3.0) | Partially, to customers |
| Cost | Free (AGPL-3.0) | Buyout / subscription |
| Admin backend | — | Centralized model access, employee management, shared knowledge base, access control, data backup |
| Server | — | Dedicated private deployment |

The Community Edition you are using is governed by the **GNU Affero General Public License v3.0 (AGPL-3.0)**. Commercial use is permitted under the AGPL terms; a commercial license that exempts you from AGPL obligations is available by contacting `[email removed]`.

> [!NOTE]
> For deployment, security hardening, the IPC and data architecture, the full configuration reference, and developer internals, see the **Cherry Studio Admin Guide**.

---

_Generated June 2026 from CherryHQ/cherry-studio at 9751cfb. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._