> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.agnes-ai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop  Integration Guide

> Claude Desktop Integration Guide for Agnes Models

# 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](https://claude.com/download)

CC-Switch download link:

[https://github.com/farion1231/cc-switch/releases](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 theme={null}
Claude Desktop
```

Or:

```text theme={null}
ClaudeCode Desktop
```

This option is used to configure the model proxy for Claude Desktop.

## 5. Add a New Provider

Click **Add New Provider**.

Select:

<span class="field-row"><code>Custom Provider</code></span>

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:

<span class="field-row"><code>YOUR\_API\_KEY</code></span>

In most cases, you do not need to manually add the `Bearer` prefix.

## 7. Enter the Request URL

Enter the following request URL:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

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 theme={null}
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 theme={null}
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 theme={null}
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:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

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:

<span class="field-row"><code>agnes-2.0-flash</code></span>

### 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.