Cherry Studio + JoinGonka Gateway — 桌面 AI 客户端

安装。各系统的构建包都在项目的 releases 页面上：Windows 有安装包和便携版，macOS 有 dmg 镜像，Linux 有 AppImage、deb 和 rpm——x64 和 ARM 架构齐全。对话历史和设置都保存在本地，也就是你自己的机器上。

V1 还是 V2。2026 年 8 月推出了 V2 系列，采用全新的数据结构和重新设计的设置界面；上一系列的最后版本是 1.9.13。两个系列都支持自定义服务商，但添加方式和部分文案有所不同——下文会标注这些差异。从 V1 升级到 V2 时，服务商和模型设置会自动迁移，原有 V1 数据会保留，但新数据不会反向同步，两个系列的备份也不兼容。升级前请先阅读 Cherry Studio 文档中的迁移章节。

JoinGonka 密钥。在网关上注册，打开后台的「API 密钥」板块，点击「创建密钥」。密钥以 jg- 开头，且只显示一次——请立即保存。建议为 Cherry Studio 单独创建一个密钥：在「用量」板块中，它的消耗会单独列出一行。

1. 点击齿轮图标打开设置，选择 Model Provider 板块（英文文档中称为 Model Services）。
2. 在提供商列表下方点击 Add Provider。
3. 在 V2 中会弹出 Add Custom Provider 对话框。填写 Provider Name——例如 JoinGonka。在 Endpoint settings 区块中，把 OpenAI 一行填入地址 https://gate.joingonka.ai/v1：字段下方会出现一行 Request path，显示最终路径——它必须以 /v1/chat/completions 结尾。在 API Key 字段中粘贴 jg-your-key，然后点击 Add。
4. 在 V1 中对话框更简短：提供商名称和 Provider Type——选择 OpenAI。密钥和地址在提供商页面上填写，即 API Key 和 API Host 字段。
5. 确认提供商已启用：开关位于其页面右上角。在 V2 中，新增的提供商默认处于关闭状态，关闭状态的提供商下的模型不会出现在选择列表中。

Cherry Studio 如何拼接地址。 API Host 字段接收基础地址，路径由应用自行追加，并在字段下方的 Preview 行中显示结果。两个版本线的规则相同：

在较早的说明中还有一条规则：地址末尾的斜杠似乎会关闭 /v1。这条规则在早期版本中生效，直到 1.6 版本线（含）为止，并在 1.7 中被移除：在当前版本中，只有 # 会关闭自动补全。

提供商已添加，但在对话中尚不可见：Cherry Studio 的选择列表中仅包含您手动添加的模型。有两种方式。

从服务器获取列表。 在提供商页面点击 Sync models（在 V1 中为 Manage，然后选择 Fetch model list）。Cherry Studio 将向网关发送 GET /v1/models 请求并显示实时网络模型列表；使用 + 按钮添加所需模型。 手动添加。 Add Model 按钮打开表单，其中必填项为 Model ID：标识符需逐字符准确输入。

网络模型的价格相同，因此建议全部添加 — 您将根据模型表现而非预算进行选择：

模型类型。 列表中的每个模型都有一个设置按钮，用于标注其能力：Vision, Reasoning, Tool 等。Cherry Studio 会自动标记部分能力，但对于网关模型，建议手动核对。应取消 Vision 勾选：网络模型仅支持文本。如果使用 MCP 工具，则需要开启 Tool — 表中所有模型均支持原生工具调用。Reasoning 适用于 GLM-5.3 Flash，因为它是网络中的推理模型。

默认模型。 在设置的 Default Model 部分，可指定功能角色的模型。建议将 DeepSeek V4 Flash 设置为主要助手模型。对于负责生成对话标题和准备搜索建议的快速模型，Cherry Studio 文档建议选择轻量级模型，而非推理模型 — 在网络模型中，MiniMax M2.7 最合适；不要设置 GLM-5.3 Flash，因为其推理过程是强制性的。翻译任务两者皆可。

在提供商页面的密钥块中有一个 Model Check（模型检查）按钮（V1 版本中为密钥字段旁边的 Check）。选择一个模型——Cherry Studio 将向其发送一个简短的测试请求，并显示结果以及响应延迟。检查通过后，进入聊天界面，在模型切换器中选择网关模型，然后提出任何问题。

要确保请求确实通过了网关，请打开网关后台，进入“使用情况”部分：“按密钥”块中会显示 Cherry Studio 密钥的请求和最后访问时间，“按模型”块中会显示已选择的模型。V2 版本在 Usage 设置部分还有自己的客户端统计信息：按提供商、模型和密钥分类的令牌和请求。那里的费用仅供参考——Cherry Studio 是根据模型的公开价格估算的，而不是根据 Gonka 网络的价格，因此请查看网关后台以获取准确金额。

如果出现问题，原因几乎总是可以从响应中看出：

客户端本身免费使用，您只需为推理付费。通过 JoinGonka Gateway，输入端每百万个令牌收费 $0.0069，输出端每百万个令牌收费 $0.021——所有网络模型价格相同，并从此页面的实时来源获取。聊天消耗的令牌明显少于智能体工具，因此截至 2026 年 9 月，成本规模大致如下：

关于长对话的重要声明：每次回复时，客户端都会将整个历史记录发送回模型，因此第一百次回复的成本比第一次更高。解决方法是针对新任务开启新对话；在 Cherry Studio 中，这只是一个按钮的事。

在同一个对话中比较模型。 Cherry Studio 可以同时向多个模型提问：在模型切换器中选择它们，每个模型都会通过单独的请求进行响应。由于网络中所有模型采用统一价格，这是了解在自己的任务中何时满足于 MiniMax M2.7、何时需要 DeepSeek V4 Flash 的长回复、以及何时 GLM-5.3 Flash 的推理能力物有所值（其设置已在 模型综述 中分析）的最快方法。

使用相同密钥的第二个协议。 网关也支持 Anthropic 格式。在 V2 对话的 Endpoint settings 模块中有一个单独的 Anthropic 行：在其中填入 https://gate.joingonka.ai，此时 Request path 行应显示为 /v1/messages。在 V1 中，通过 Provider Type 为 Anthropic 且地址相同的单独提供程序即可实现相同结果。在 V2 的 More options 按钮下还有一个 OpenAI Responses 行，网关同样支持，地址与主要的 OpenAI 行相同。

运行终端代理。 在 Code CLI 页面（文档中称为 Coding Companion）上，Cherry Studio 会安装并运行控制台代理，并从其设置中为它们提供提供程序和模型；该列表中的提供程序根据特定工具所需的协议进行过滤。因此，如果您打算从这里运行 Claude Code，请提前填写 Anthropic 地址。关于如何在没有中介的情况下配置同一代理，请参考 Claude Code + Gonka 指南。

知识库。 在 V2 中，即使没有嵌入模型，它也能通过 BM25 文本搜索工作，而使用嵌入模型时则会启用混合搜索。Gonka 网络模型是生成式的，因此对于混合模式，请使用来自其他提供程序的嵌入模型，例如通过 Ollama 使用本地模型；届时，网关模型将根据找到的片段进行回答。

需要浏览器中的团队共享聊天功能吗？ Cherry Studio 是个人桌面客户端。如果需要带有账户功能的共享 Web 界面，请查看 Open WebUI：它可以使用相同的地址和密钥连接到网关。