The Ultimate Guide to Cherry Studio: AI Workbench Mastery (Including Local Model Deployment)

You’ve got your favorite AI models—GPT for drafting, Claude for polishing, DeepSeek for research. The hassle isn’t the models themselves; it’s the context switching. Copying prompts, re-uploading files, and jumping between browser tabs wastes more time than the AI actually saves.

Cherry Studio fixes this. It’s an open-source desktop application that integrates APIs from GPT, Claude, DeepSeek, Kimi, and even locally-running models into a single, unified interface.

In this guide, I’ll walk you through the exact setup process—from installation to local deployment—so you can stop wrestling with tabs and start focusing on the work. All the material here is based on hands-on usage, not just the documentation.

What Cherry Studio Actually Does

At its core, Cherry Studio is a model-agnostic desktop workbench. You bring the API keys; it provides the interface. The biggest advantage isn’t any single feature but the persistence of context: your materials, writing instructions, and knowledge bases stay in the workbench even when you switch the underlying model.

For example, if you’re stuck on an article introduction, you can feed the same source material to three different models simultaneously. Each generates a version, and you choose the best direction. No more copy-pasting between ChatGPT and Claude websites.

Need to keep two different rewrites? Use “branches.” Each version evolves independently, and you can always revert to a previous fork. Save your recurring formatting or tone requirements as “Assistants”—you won’t have to re-explain your style guide every session.

For project files, product manuals, or past articles, drop them into the Knowledge Base. When you ask a question, Cherry Studio retrieves the relevant snippets and feeds them to the model. Swap the chat model, and the Knowledge Base stays intact.

When you need batch file processing, Word/PDF generation, or interactive webpage building, that’s where Agents come in. Connect a capable model and the right tools, and it can read files, execute operations, and generate outputs. Miss something? Just tell it to correct it.

It also includes dedicated entries for translation and image generation. If you want to try open-source or uncensored local models, you can plug them in via Ollama or LM Studio—we’ll cover that in detail later.

Everything has a pre-built interface. You don’t need to code scripts from scratch.

How to Install Cherry Studio

Head to the official Cherry Studio download page.

「Mac users」: Download ARM64 if you have an Apple Silicon chip; select x64 for Intel chips. After downloading, drag the app into your Applications folder.
「Windows users」: Typically, choose the x64 installer. Select ARM64 only if you are on an ARM-based Windows device.

When you launch it for the first time, click “Set up later” to skip the initial configuration wizard and go straight to the main dashboard.

On the left sidebar, you’ll see four main sections: 「Chat」 (for writing and questions), 「Workspace」 (for Agent tasks), 「Knowledge Base」 (for reusable documents), and 「Settings」 (for model configuration). The tabbed layout at the top works just like a browser—you can keep the settings panel open while testing changes in a chat tab, saving you from constantly closing and reopening menus.

Connecting Your First AI Model

After installation, you need to connect a model. Cherry Studio is free, but the model API calls will incur costs billed directly to your provider account.

If you like Kimi, grab its API. Prefer DeepSeek? Use theirs. You can also use unified platforms like SiliconFlow that offer multiple models under one account. Start with one provider; add more when you need to compare.

Here’s what an API Key is: it’s the authentication string that lets Cherry Studio use the provider’s service. You generate it in the provider’s “Developer Platform,” not in your regular chat subscription. 「Crucial note」: Having a ChatGPT Plus subscription doesn’t automatically grant you API credits. These are separate billing systems.

Let’s use Kimi as a practical example:

Go to the Moonshot (Kimi) developer platform and log in.
Navigate to API Key management and create a new key.
Copy the key immediately.
Check your account balance. Top up a small amount—don’t load $100 on day one.

Back in Cherry Studio:

Open Settings → Model Service.
Find “Moonshot” (Kimi) in the list.
Paste the API Key and enable the service.
Click Get Model List. Several model IDs will appear—add the specific one you plan to use.

Switch back to the Chat page, click the model name at the top, and select your newly added model. Send a short test message. If it replies correctly, your connection is live.

「What if a provider isn’t listed?」 Scroll to the bottom and click Add Provider. You’ll need:

「Provider Name」: A custom label (e.g., “Internal Corporate API”).
「API Address」: The endpoint URL from your provider.
「API Key」: Your authentication string.
「Model ID」: This must match the exact ID the server expects. Don’t guess this—copy it from the provider’s documentation.

「Troubleshooting failed connections」:

「Invalid Key」: Double-check spaces, copy completeness, and that it’s in the correct provider’s field.
「Insufficient Quota」: Log in to your provider dashboard to check the balance.
「Model Not Found」: Verify the Model ID exactly matches the documentation.

「Security reminder」: Never paste your API Key into chat logs or public screenshots. Anyone with that key can rack up charges on your account.

Stress-Testing Your Models with Real Data

Once connected, skip the “Hello, world!” tests. Use actual materials you work with—drafts, meeting minutes, or product specs. You know the source material well, so you can instantly tell if the output is dropping crucial information.

Let’s say you need to condense meeting notes into a brief team update. Enable multi-model selection by opening the model picker at the top of the chat and selecting two or three models. Then send this prompt:

Condense the following material into a team message (under 200 words).

Requirements:
- Keep confirmed decisions, owners, dates, and unresolved issues.
- Do NOT add information not in the source.
- "Tentative" items must NOT be written as "confirmed."
- Output the message directly, with no preamble.

Material:
[Paste text here]

Compare the responses. Check if the “tentative Friday” deadline was incorrectly stated as “Friday confirmed.” Check if team leads’ names are accurate. These factual checks are easier with your own content.

If you want to measure speed, go to Settings → Appearance and enable Show estimated Token count. After the response, you’ll see stats on latency (time to first token), generation speed (tokens/second), and total usage.

「Token clarification」: Tokens are pieces of text (often ~4 characters). This metric helps you gauge costs, but your final bill depends on your provider’s calculation—treat this as an estimate.

「The “Rewrite” test」: Ask the model to “Keep the second paragraph, rewrite only the first, don’t change the numbers.” If it alters the numbers anyway, that model might be prone to over-editing, which can be exhausting for later revisions.

Save your test prompts and source material as a Note. Whenever you add a new model, open a fresh chat and run the same tests. This ensures a fair comparison—previous conversation contexts won’t bias the outputs.

Cost awareness: Multi-model selection sends separate requests to each model, incurring individual charges. Use it for comparative brainstorming, but once you pick a winner, stick to a single model for the heavy lifting.

Managing Revisions with Branches

You’ve edited an article five times. Suddenly, version two looks better than the final. Or you want to try two completely different tones from the same outline. Branches are built for this scenario.

Find the message you want to preserve. Open its message menu and select Branch. This creates a new path, copying all the context before that point. Your edits on the new branch won’t affect the old one. To switch between them, open the Branch Manager.

Example: You have an outline, but the introduction is undecided. Branch from the outline: On Branch A, start with a hard conclusion. On Branch B, begin with a narrative anecdote. Run a few edits on each, compare the results, and delete the losing branch. There’s no need to save a draft externally to try something risky.

For smaller tweaks, just continue in the existing thread. Only use branches when you genuinely want to preserve two diverging paths.

Creating Reusable Assistants

For repetitive text workflows, set up an Assistant. Go to Chat → Add Assistant. Give it a name (e.g., “General Editor”) and store your permanent guidelines:

Role: You are an editor for general-reader Chinese articles.

Rules:
- Prioritize preserving facts and concrete examples.
- Cut fluff that introduces no new information. Don't rewrite the author's background.
- If I ask to modify a specific paragraph, modify ONLY that paragraph.
- Flag unsupported judgments, but do not invent citations for them.

The Assistant saves long-term habits. Put the specific article details (topic, length, target audience) in the individual chat thread to prevent cross-contamination from previous tasks.

Need a pure review? Start a new branch or thread specifically for criticism:

Review this draft. Do NOT rewrite it.

Compare against the source material.
Flag:
1. Facts/numbers not backed by the source.
2. "Maybe"/"Tentative" items written as confirmed.
3. Redundant explanations.

Quote the problematic text and state the issue. Mark missing sources as "Needs citation."

Different models catch different errors. However, don’t assume consensus means perfection—always manually verify critical facts.

Agent Tip: When you’re ready to move your finalized draft to an Agent for file generation, remember that the Agent doesn’t automatically inherit your chat history. Explicitly state which draft version to use in the Agent prompt.

Handing Tasks to Agents

Your draft is finalized. Now you need it formatted into a Word template and exported as PDF. The “Workspace” section handles this.

Click Add Agent. Name it based on its function (e.g., “Doc Processor”). Select a Running Mode, choose the supporting model, and fill in the task guidelines. After creation, you can tweak tools, permissions, skills, and Knowledge Bases in the edit panel.

「Mode clarification」: The Running Mode impacts which models and permissions are available. The chat models you use daily might not support Agent functionality. Crucially, you can’t switch the mode after creating the Agent—if you want a different mode, you have to build a new Agent.

Some modes split responsibilities among a Main Model, a Plan Model, and a Small Model. Start by using the same model for all three until you understand the logic, then optimize later.

Create a new Task and select the Working Directory. 「Crucial safety advice」: First, use a dedicated test folder with copies of your files. If the permission settings offer “Confirm Step-by-Step,” enable it. This forces the Agent to ask for approval before reading, executing, or writing to your file system.

Let’s test it with harmless meeting minutes:

Read the meeting minutes in the current directory and summarize the project progress.

Rules:
- Do NOT modify, move, or delete original files.
- Structure output: Completed, In Progress, Pending Confirmation.
- Owners and dates MUST come from the text. If missing, label "Pending Confirmation."
- Cite the source filename for each line.

First, list the files found and your summary outline. Wait for my confirmation.
After confirmation, generate a new file: Project_Progress.md.

Check if it found the correct files and if its preliminary outline looks right. Open the generated .md file and verify it didn’t fabricate names or dates.

For Word/PDF generation, ensure the relevant document tools or dependencies are installed (the system usually prompts you). Find the output in the artifact panel or the working directory—always visually inspect the formatting.

Enabling Web Search

Need the Agent to look up current data? Go to Settings → Web Search to configure a search service like Exa. Get the Search API Key from the provider, test the connection, and then verify the Agent’s search tool is toggled on.

Search isn’t free—it has separate usage fees. If the search tool isn’t connected, the model may just hallucinate an answer based on its training data instead of actually browsing the web.

If a task requires clicking buttons, navigating pages, or downloading files, you’ll need browser automation. Look for the Playwright CLI skill in the skill management section.

Think of “Skills” as specialized instruction manuals (e.g., “How to use Playwright to scrape data”). They often require external installations. Follow the setup guide and test with a minimal task first.

For external enterprise integrations, use MCP (Model Context Protocol). Go to Settings → MCP to add the service, configure it, and then bind it in the Agent’s MCP settings.

A clean setup is a stable setup. Don’t enable browser skills or MCP if you’re just organizing local meeting notes—you’ll just be debugging irrelevant dependencies.

Building a Reusable Knowledge Base

Select your evergreen documents—product manuals, past writing, policies. If a document is only needed for a single chat, just attach it directly to that conversation. Building a Knowledge Base is for things you’ll query repeatedly.

Navigate to the left sidebar and open Knowledge Base. Click “New” and name it descriptively (e.g., “Product Warranty FAQ”). For your first test, set the Embedding Model to “None” to rely purely on keyword retrieval.

Add one or two files you’re very familiar with. Wait for processing and check the extracted text. 「Special attention」: Scanned PDFs often fail OCR. If the text isn’t extracted, the search will miss it entirely.

Run a “Recall Test” by asking a question with a known answer. For a product manual about return policies, ask: “Can I return this after opening?” Click the results and check the retrieved snippets. 「Does it directly quote the warranty policy paragraph?」 This test checks if the retrieval works, not the chat model’s summarization.

Once retrieval is accurate, go back to a Chat thread. Click the “Add” button in the input area, select “Knowledge Base,” and check your specific library. Ask a question:

Using the selected product documents, compile a list of most-asked customer support questions.

Requirements:
- Cite the source file for each answer.
- If the info isn't in the documents, respond with: "Not found in materials." Do not make promises.
- If the documents conflict, list the differences—don't choose one side for me.

If the Knowledge Base icon is grayed out, check if your current chat model supports tool calling, and ensure no files are manually attached to the message (that can override the KB context).

Advanced Retrieval: Embedding & Reranking

When expanding your KB, pure keyword search fails. For instance, the source says “Accommodation standard,” but you ask, “What’s the max hotel reimbursement?” Embedding models bridge this gap by searching for semantic meaning.

To set this up, treat it like connecting a chat model. In Settings → Model Service, configure the key for a provider (like SiliconFlow), get the model list, and find an embedding model (e.g., bge-m3). Add it. Then return to your Knowledge Base settings, select this Embedding Model, and wait for indexing (this may take time). Rerun your recall test.

If the correct snippet appears but is buried beneath irrelevant ones, consider a Reranking model (bge-reranker-v2-m3). This model reorders the retrieved chunks, pushing the most relevant to the top.

「Do you need both?」 Not necessarily. For precise keyword matches (model numbers, terms of service), standard retrieval works fine.

「Troubleshooting order」:

No results found → Is the file processed? Did the OCR fail?
Chunk found, but missing context → Check if the chunking size is cutting off sentences.
Chunks correct, but answer is wrong → Rewrite the prompt or switch the chat model.

When updating a manual, remove outdated entries—keeping two conflicting versions will confuse the retriever. Also, ask a “trick question” (something not in the docs) to see if it correctly admits it doesn’t know.

Data Privacy Note: Using cloud embeddings, rerankers, or chat models sends your data to those providers. Ensure compliance before uploading internal company documents.

Deploying Local Models (Ollama & LM Studio)

Want to try open-source models or explore less-restricted models without paying per-token? Run them locally and plug them into Cherry Studio. The interface stays the same, but the compute happens on your hardware.

The two most common launchers are 「Ollama」 and 「LM Studio」. Pick one.

Option 1: Ollama

Download and install from the Ollama website.
Open your terminal and pull a small test model:
```
ollama run dolphin-mistral
```
(This is a ~4GB, 7B model—great for starting out). Wait for the download and test a prompt in the terminal first to ensure it works.
In Cherry Studio, go to Settings → Model Service. Find 「Ollama」.
Set the API Address to:
```
http://localhost:11434
```
Enable the service, click Get Model List, and add dolphin-mistral.
Switch to this model in a chat and test it.

localhost means your own machine. If it fails, ensure Ollama is still running (background process), the model is downloaded, and the port (11434) is unchanged. 「Never expose this local service to the public internet」 just to connect two local apps.

Option 2: LM Studio

If you prefer a GUI over a terminal, get LM Studio. Search for a model in its UI, download it, load it into memory, and start the Local Server. Return to Cherry Studio, find “LM Studio” in the providers, fill in the address LM Studio provides, and fetch the model list.

Finding Models on Hugging Face

To find “uncensored” or fine-tuned models, search Hugging Face with:

uncensored GGUF

“Uncensored” usually means fewer refusal policies, not smarter reasoning or higher accuracy. Cherry Studio has no “unlock” button—you are simply selecting a different model with different training data.

GGUF is the standard file format for local quantized models. When you click a model page, check the base model, language support, and license. Download the specific .gguf file that matches your hardware.

Hardware Considerations

「Understanding labels」: “7B” = 7 billion parameters. “Q4” = quantization level (compresses weights to use less RAM, slightly sacrificing quality).
「Hardware minimums」: dolphin-mistral (~4 GB download). A 30B Q4 model can be 15-16 GB plus RAM overhead for context caching.
「For 16 GB RAM machines」: Stick to 7B-8B quantized models. Performance depends on your CPU/GPU and context length. The model might run initially but slow to a crawl with large document attachments.

Fully local runs mean no per-API-token costs, but they tax your GPU/CPU heavily. If you combine a local model with cloud search or embedding, those external services still transmit data externally.

Clarification: The local OCR/embedding components downloadable in Cherry Studio are for indexing text—they aren’t the chat models themselves.

Quick Reference Checklist

「Setup」

[ ] Download the correct OS version (ARM64 for M-series Macs; x64 for others).
[ ] Generate an API Key on your provider’s platform.
[ ] Paste the key in Settings → Model Service → Enable → Fetch List.
[ ] Test with a short message.

「Testing & Comparison」

[ ] Test using your own documents, not random prompts.
[ ] Enable multi-model selection to compare responses side-by-side.
[ ] Save standardized test prompts to benchmark new models.

「Daily Operations」

[ ] Use Branches to preserve divergent edits.
[ ] Store permanent formatting rules in Assistants.
[ ] Use the Workspace for file processing; start with “Confirm Step-by-Step.”

「Knowledge Base」

[ ] Only upload files you’ll reuse multiple times.
[ ] Run a “Recall Test” before relying on it.
[ ] Delete outdated documents to avoid confusion.

「Local Models」

[ ] Install Ollama or LM Studio (not both unless you’re testing).
[ ] Verify the model runs in the terminal/GUI before connecting Cherry Studio.
[ ] Start with 7B Q4 models for standard hardware.

Frequently Asked Questions

「Q: Where do I find an API Key if I have a paid chat subscription?」
You don’t. Chat subscriptions and API credits are separate. Go to the provider’s “Developer” or “Platform” portal to create a key and top up credits.

「Q: If I attach files to a chat, does it go to the Knowledge Base?」
No. Chat attachments are temporary context for that single conversation. The Knowledge Base stores documents for long-term, indexed retrieval.

「Q: How do Branches differ from just continuing in the same thread?」
Continuing writes linearly. Branches allow you to diverge from a specific message without affecting the previous path, letting you explore radically different ideas simultaneously.

「Q: Why does my Agent ignore the Knowledge Base?」
You must explicitly bind the Knowledge Base to the Agent in the Agent’s editing panel. It doesn’t automatically “see” all your libraries.

「Q: My local model works, but it’s extremely slow and unresponsive.」
Check your memory usage (Task Manager/Activity Monitor). A 13B+ model often exhausts 16GB RAM, leading to swap file thrashing. Try smaller models (3B-7B) or higher quantization (Q2/Q3).

「Q: What is an “Embedding Model” and do I need it?」
It translates text into vector numbers to find meaning, not just keywords. You need it if your knowledge base questions use synonyms (e.g., “flight” vs “airplane”). If you only search serial numbers, you don’t.

「Q: Can I use the Assistant feature to block the model from outputting JSON?」
Yes, but instructions in the Assistant field are guidelines, not hard rules. For deterministic outputs, use system prompts in the task or Agent instructions. If the model still outputs JSON, switch to a model with better instruction-following capabilities.

「Q: My API connection says “invalid key” but I just regenerated it.」
Check your quota first. Many providers return a generic “key invalid” error when you are out of credits. Second, check for leading/trailing spaces in the paste.

How to Use Ollama to Run Uncensored AI Models Locally with Cherry Studio