Cherry Studio
Configure and use AGTCloud in Cherry Studio.
Cherry Studio is a multi-model desktop client supporting Windows, macOS, and Linux. By adding custom OpenAI service providers, Cherry Studio can use AGTCloud's Chat Completions compatible entry.
This tutorial only covers general chat access. File, image, tool calls, inference, knowledge base, agent, MCP, and other advanced capabilities depend on the Cherry Studio version and the actual supported scope of the target model.
Preparation
Before you start, please confirm that you have:
- Be ready with a supported Windows, macOS, or Linux device;
- Register and log in to AGTCloud;
- Create the AGTCloud API Key on the API Keys page;
- Copy the model ID from the Model Marketplace which is available to the current API Key and supports Chat Completions.
Download and install Cherry Studio
Obtain the installation package from the official Cherry Studio download page. Download pages and package names may change between releases, so choose the current package for your operating system and processor architecture.
- Common Intel or AMD computers choose the standard Windows x64 install;
- Windows ARM devices should select the ARM64 installation package;
- After downloading, run the installer and follow the on-screen prompts to complete the installation.
When unsure about the device architecture, you can view "System Type" in the Settings → System → System Information.
After installation, launch Cherry Studio. If initialization, data directory, or update prompts appear on the first startup, please complete the settings according to the current version interface.
Add the AGTCloud service provider
Open Model Service Settings
Open Cherry Studio and enter the Settings → Model Provider. The name in the Chinese interface may appear as "Setting → Model Service."
Add custom service providers
Click Add to create a custom provider. Set the provider name to AGTCloud, then select OpenAI as the provider type.
Fill in the connection information
| Cherry Studio field | Value |
|---|---|
Provider Name | AGTCloud |
Provider Type | OpenAI |
Chat Endpoint / Protocol(If any) | OpenAI Chat Completions |
API Key | your-api-key |
API Host | https://api.agtcloud.cn/v1/ |
Custom Headers | Leave it blank by default |
Replace your-api-key with the AGTCloud API Key created on the API Keys page. If the current version offers chat protocol options, use OpenAI Chat Completions.
Activate service providers
After saving the configuration, turn on the enable switch in the upper right corner of the service provider. If the provider is not enabled, the model already added will not appear in the model list on the chat page.
API Host needs to end with /
Enter https://api.agtcloud.cn/v1/ exactly as shown. Do not enter the full /v1/chat/completions endpoint, or Cherry Studio may generate a duplicated request path.
Get and add models
Open Model Management
Click Manage on the AGTCloud provider configuration page. Cherry Studio will attempt to obtain the visible model based on the current API Host and API Key.
Add the model to the list
In the returned model list, find models that support Chat Completions and click the + on the right. Only models added to the service provider model list will appear in the model selector on the chat page.
Manually added when it cannot load
If the model list does not load, check the API Host, API Key, and provider status. You can also copy a model ID from the Model Marketplace and add the MODEL_ID manually using the entry available in the current Cherry Studio version.
Check the connection
Click the connectivity check button near the API Key field. Cherry Studio typically tests the last chat model in the list. If the check fails, first confirm that the list contains at least one chat model available to the current API Key.
Model configuration is subject to actual capability
It is not necessary to add all models at once. The model's context length, file input, image understanding, tool calls, and reasoning capabilities are based on the actual supported scope of the current model and protocol entry.
The first conversation begins
Create a new topic
Return to the Cherry Studio chat page and create a new topic.
Choose the AGTCloud model
Open the model selector and select AGTCloud → MODEL_ID. MODEL_ID is a placeholder; the actual interface will show the model ID you just added.
Send minimum verification questions
Send in the input box:
Please introduce yourself in three sentences.Inspection results
If the client receives the reply normally, it means the API Host, API Key, and the basic connection to the model have been established. This step will generate normal API usage.
Frequently Asked Questions
| Issue | What to check | Resolution |
|---|---|---|
| The AGTCloud model is not displayed | Service provider toggle and model addition status | Enable the service provider and confirm that the target model has been added to the service provider model list |
Manage returns an empty list | API Host, API Key, and models available to the current account | Enter the API Host and API Key again, or copy a MODEL_ID from the Model Marketplace and add it manually |
| Connectivity check fails | Selected model, protocol support, and API Key permissions | Confirm that the selected chat model can be called by the current API Key through Chat Completions |
Returns 401 | API Key value and token status | Copy a valid API Key again and make sure the field contains no extra spaces |
Returns 403 | Token permissions, model permissions, and account status | Check the API Key status and the models available to the current account in the console |
Returns 404 | API Host, duplicated path, and model ID | Use https://api.agtcloud.cn/v1/, do not enter a full endpoint, and verify the model ID |
| The request path contains duplicated segments | Whether the API Host contains a full request endpoint | Reset the API Host to https://api.agtcloud.cn/v1/, then test the connection again |
| Advanced feature call failed | Model real capabilities, protocol support, and client versions | First, close advanced features like files, tools, knowledge bases, or inference, then use plain text to complete verification |
| Response interruptions or slowness | Network proxy, context length, and model state | Retry with shorter new topics and check the local network against the current model running state |
If you encounter issues that cannot be located, record the request time, model ID, HTTP status, and redacted error messages, then review Error & Troubleshooting. Do not submit the full API Key.
Safety advice
- Do not put API Keys into screenshots, chat exports, logs, or shared configurations;
- Do not submit passwords, customer information, private documents, or other sensitive information during the initial verification;
- When multiple users share the device, delete the credential saved in Cherry Studio after use;
- Before exporting or sharing your Cherry Studio configuration, make sure it does not include an API Key.