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:
Or:
This option is used to configure the model proxy for Claude Desktop.

​
5. Add a New Provider

Click Add New Provider. Select: 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: 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: 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:
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:

​
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:
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: 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: 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.