Skip to main content

​
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

​
3. Get an Agnes API Key

Visit the Agnes AI Platform: 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
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
Claude Provider
Then 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 unless the tool explicitly requires the full Authorization Header.

​
7. Configure the Request URL

Enter the following request URL:
text
https://apihub.agnes-ai.com/v1
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
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
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
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: 
{
  "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
Route
Then enable:
text
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:
text
https://apihub.agnes-ai.com/v1
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: 
{
  "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:
text
agnes-2.0-flash