跳转到主要内容

​
Agnes 模型的 Claude Desktop 集成指南

​
1. 概述

本指南说明如何通过 CC-Switch 将 Claude Desktop 连接到 Agnes 模型。配置完成后，Claude Desktop 可以通过 CC-Switch 将请求路由到 Agnes AI API 网关，并使用 Agnes 文本模型进行对话或多模态任务。

​
2. 前置条件

在开始之前，请确保你已具备以下条件：
  • 已安装 Claude Desktop。
  • 已安装 CC-Switch。
  • 一个有效的 Agnes AI API Key。
  • 能够访问 Agnes AI API 网关的网络环境。
  • 你想要使用的模型名称。
本指南基于 CC-Switch v3.16.1。 Claude Desktop 下载链接： https://claude.com/download CC-Switch 下载链接： https://github.com/farion1231/cc-switch/releases

​
3. 安装 Claude Desktop

为你的操作系统选择合适的安装程序：
  • Windows：.exe
  • macOS：.dmg
  • Linux：AppImage
安装完成后，打开 Claude Desktop。

​
4. 打开 CC-Switch

启动 CC-Switch，在顶部导航栏中切换到以下选项： 
Claude Desktop
或者： 
ClaudeCode Desktop
此选项用于配置 Claude Desktop 的模型代理。

​
5. 添加新提供商

点击 Add New Provider。 选择： Custom Provider 这意味着你将使用自定义模型提供商。

​
6. 输入 API Key

在 API Key 字段中输入从 Agnes AI 平台获取的 API Key。 示例： YOUR_API_KEY 在大多数情况下，你不需要手动添加 Bearer 前缀。

​
7. 输入请求 URL

输入以下请求 URL： https://apihub.agnes-ai.com/v1 此 URL 用于将 Claude Desktop 请求转发到 Agnes AI API 网关。

​
8. 启用模型映射

启用模型映射功能。 此功能将 Claude Desktop 中的 Claude 模型名称映射到 Agnes 模型。

​
9. 选择 API 格式

对于 API 格式，选择： 
OpenAI Chat Completions
此格式与 Agnes OpenAI 兼容 API 兼容。

​
10. 获取模型列表

点击 Fetch Model List 确认 CC-Switch 能够成功连接到 Agnes AI API 网关。 加载模型列表后，选择你要映射的模型。 推荐映射示例： 
Sonnet  -> agnes-2.0-flash
Opus    -> agnes-2.0-flash
Haiku   -> agnes-2.0-flash

​
11. 保存配置

确认 API Key、请求 URL、API 格式和模型映射正确后，点击 Save。 保存成功后，提供商列表中将出现 Agnes 配置。

​
12. 启用 CC-Switch 路由

进入 CC-Switch 设置页面，选择： 
Route
启用本地路由开关并打开 Claude 路由。

​
13. 验证配置

打开 Claude Desktop，开始一个测试对话。 如果配置正确，Claude Desktop 应该能够通过 Agnes 模型返回响应。

​
14. 故障排查

​
1. Claude Desktop 无法调用模型

确保 CC-Switch 本地路由已启用并且 Claude 路由已打开。

​
2. 无法获取模型列表

检查 API Base URL 是否正确： https://apihub.agnes-ai.com/v1 同时确认 API Key 是有效的。

​
3. 模型映射失败

确保已启用模型映射，并且 Claude 模型已映射到 Agnes 模型。 推荐模型： agnes-2.0-flash

​
4. API 请求失败

检查你的网络、防火墙、代理或 VPN 设置。

​
5. 认证失败

确保 API Key 正确，并且你的账户有足够的余额或积分。