Agnes 模型的 Claude Desktop 集成指南

1. 概述

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

2. 前置条件

在开始之前，请确保你已具备以下条件：

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 正确，并且你的账户有足够的余额或积分。