> ## 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 CLI Integration Guide

> Claude CLI Integration Guide for Agnes Models

# Claude CLI Integration Guide for Agnes Models

## 1. Overview

This document explains how to connect Claude CLI to Agnes models through CC-Switch.

After the configuration is complete, Claude CLI can route requests through CC-Switch to the Agnes AI API Gateway and use Agnes text models for local Agent tasks or coding tasks.

## 2. Prerequisites

Before you start, make sure you have the following:

* Claude CLI installed.
* CC-Switch installed.
* A valid Agnes AI API Key.
* A network environment that can access the Agnes AI API Gateway.
* The target model name you want to use.

This guide is based on CC-Switch v3.16.1.

CC-Switch download page:

[https://github.com/farion1231/cc-switch/releases](https://github.com/farion1231/cc-switch/releases)

## 3. Get an Agnes API Key

Visit the Agnes AI Platform:

[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)

After logging in, go to the API Key page, create an API Key, and copy it.

## 4. Open CC-Switch

Launch CC-Switch.

In the top toolbar, select:

```text theme={null}
Claude CLI
```

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

## 5. Add a New Provider

Click the plus button in the upper-right corner to add a new provider.

For the provider type, select:

```text theme={null}
Claude Provider
```

Then 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 unless the tool explicitly requires the full Authorization Header.

## 7. Configure 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 CLI model requests to the Agnes AI API Gateway.

## 8. Select the API Format

For the API format, select:

```text theme={null}
OpenAI Chat Completions
```

This format is suitable for OpenAI-compatible API integration.

## 9. Configure the Authentication Field

Use the default authentication field.

If manual configuration is required, you can use:

```text theme={null}
ANTHROPIC_AUTH_TOKEN
```

## 10. Fetch the Model List and Configure Model Mapping

Click **Fetch Model List** to check whether CC-Switch can successfully connect to the Agnes AI API Gateway.

After the model list is fetched successfully, map the Claude CLI models to Agnes text models.

Recommended mapping:

```text theme={null}
Sonnet  -> agnes-2.0-flash
Opus    -> agnes-2.0-flash
Haiku   -> agnes-2.0-flash
```

You may also select other available models based on your actual needs.

## 11. Add Custom Parameters

To avoid incompatible parameters in model requests, it is recommended to add the following configuration to the custom parameters:

```json theme={null}
{
  "allowed_openai_params": ["thinking", "context_management"],
  "litellm_settings": {
    "drop_params": true
  }
}
```

This configuration is used to:

* Allow the specified OpenAI parameters to pass through.
* Automatically drop unknown parameters that are incompatible with the model.
* Improve compatibility when Claude CLI calls an OpenAI-compatible API through the proxy.

## 12. Save the Provider Configuration

After confirming that the API Key, request URL, API format, model mapping, and custom parameters are correct, click **Save** or **Add**.

After the configuration is saved successfully, the Agnes configuration item will appear in the provider list.

## 13. Enable CC-Switch Routing

Click the settings button in the upper-left corner of CC-Switch and go to the routing configuration.

Select:

```text theme={null}
Route
```

Then enable:

```text theme={null}
Local Route
```

In the local route settings, enable the Claude route switch.

## 14. Enable the Agnes Provider

Return to the provider list.

Find the Agnes Provider and click **Enable**.

After it is enabled, Claude CLI requests will be forwarded through CC-Switch to the Agnes AI API Gateway.

## 15. Verify the Configuration

Open Claude CLI and run a test conversation or coding task.

If the configuration is correct, Claude CLI should return responses from the Agnes model normally.

## 16. Troubleshooting

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

### 2. Authentication failed

Check whether the API Key is entered correctly.

In most cases, you only need to enter the key itself. You do not need to manually add the `Bearer` prefix.

### 3. Request error or incompatible parameters

Confirm that the following compatibility configuration has been added:

```json theme={null}
{
  "allowed_openai_params": ["thinking", "context_management"],
  "litellm_settings": {
    "drop_params": true
  }
}
```

### 4. Claude CLI is not using the Agnes model

Check whether CC-Switch local routing is enabled and confirm that the Claude route switch has been turned on.

### 5. Abnormal model responses

Check whether the model mapping is correct.

It is recommended to use the following model first:

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