Skip to main content

​
Claude Desktop Integration Guide for Agnes Models

​
1. Overview

This guide explains how to connect Claude Desktop to Agnes models through CC-Switch. After configuration, Claude Desktop can route requests through CC-Switch to the Agnes AI API Gateway and use Agnes text models for conversations or multimodal tasks.

​
2. Prerequisites

Before you begin, make sure you have the following:
  • Claude Desktop installed.
  • CC-Switch installed.
  • A valid Agnes AI API Key.
  • A network environment that can access the Agnes AI API Gateway.
  • The model name you want to use.
This guide is based on CC-Switch v3.16.1. Claude Desktop download link: https://claude.com/download CC-Switch download link: https://github.com/farion1231/cc-switch/releases

​
3. Install Claude Desktop

Choose the appropriate installer for your operating system:
  • Windows: .exe
  • macOS: .dmg
  • Linux: AppImage
After installation, open Claude Desktop.

​
4. Open CC-Switch

Launch CC-Switch and switch to the following option in the top navigation bar:
text
Claude Desktop
Or:
text
ClaudeCode Desktop
This option is used to configure the model proxy for Claude Desktop.

​
5. Add a New Provider

Click Add New Provider. Select:
text
Custom Provider
This means you will use a custom model provider.

​
6. Enter the API Key

Enter the API Key obtained from the Agnes AI Platform in the API Key field. Example:
text
YOUR_API_KEY
In most cases, you do not need to manually add the Bearer prefix.

​
7. Enter the Request URL

Enter the following request URL:
text
https://apihub.agnes-ai.com/v1
This URL is used to forward Claude Desktop requests to the Agnes AI API Gateway.

​
8. Enable Model Mapping

Enable the model mapping feature. This feature maps Claude model names in Claude Desktop to Agnes models.

​
9. Select the API Format

For the API format, select:
text
OpenAI Chat Completions
This format is compatible with the Agnes OpenAI-Compatible API.

​
10. Fetch the Model List

Click Fetch Model List to confirm that CC-Switch can connect to the Agnes AI API Gateway successfully. After the model list is loaded, select the model you want to map. Recommended mapping example:
text
Sonnet  -> agnes-2.0-flash
Opus    -> agnes-2.0-flash
Haiku   -> agnes-2.0-flash

​
11. Save the Configuration

After confirming that the API Key, request URL, API format, and model mapping are correct, click Save. Once saved successfully, the Agnes configuration will appear in the provider list.

​
12. Enable CC-Switch Routing

Go to the CC-Switch settings page and select:
text
Route
Enable the local routing switch and turn on Claude routing.

​
13. Verify the Configuration

Open Claude Desktop and start a test conversation. If the configuration is correct, Claude Desktop should be able to return responses through the Agnes model.

​
14. Troubleshooting

​
1. Claude Desktop cannot call the model

Make sure the CC-Switch local route is enabled and Claude routing is turned on.

​
2. Unable to fetch the model list

Check whether the API Base URL is correct:
text
https://apihub.agnes-ai.com/v1
Also confirm that the API Key is valid.

​
3. Model mapping failed

Make sure model mapping is enabled and that Claude models are mapped to Agnes models. Recommended model:
text
agnes-2.0-flash

​
4. API request failed

Check your network, firewall, proxy, or VPN settings.

​
5. Authentication failed

Make sure the API Key is correct and that your account has sufficient balance or credits.