Cherry Studio 怎么接入 KL API

Cherry Studio 用「添加提供商」接 KL API:两个端点都填 agent.kl-api.info,模型要手动加入列表。(2026-11-22)

适用系统:Windows / macOS / Linux · 更新于

准备工作

  • 已安装 Cherry Studio 桌面客户端
  • 一个 KL API 的 API Key(在控制台创建)
  • 知道要用的模型 ID,见 [模型清单](/models)

它和前几篇的结构不一样

Cherry Studio 是纯 GUI 客户端,没有配置文件;但它比 Cursor 多一个能力:一个自定义服务商可以同时挂 OpenAI 和 Anthropic 两个端点。所以你能在同一个服务商里既用 gpt-5,也用原生 Anthropic 协议的 claude-sonnet-4-6,不必像 Cursor 那样被迫全走 OpenAI 兼容路径。

两个端点的地址

配置项 填什么 说明
OpenAI 端点 https://agent.kl-api.info 客户端自动补 /v1/chat/completions;要精确控制就写 https://agent.kl-api.info/v1#
Anthropic 端点 https://agent.kl-api.info 地址本身不带 /v1,SDK/客户端自己拼 /v1/messages
API 密钥 你的 KL API Key 支持多个密钥用英文逗号分隔,轮询使用
模型 ID gpt-5、claude-sonnet-4-6 等 见 模型清单,必须一字不差

注意

地址别填成 https://agent.kl-api.info/v1/chat/completions 这种完整路径。官方文档给的规则是:给的是完整地址时,只填根地址即可,客户端会补全;把完整路径填进去会拼出重复路径,报 404。

先验端点

填进客户端之前,用一条命令确认地址和 Key 都对。故意用假的 Key,看它回什么:

Windows PowerShell
curl.exe https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"
macOS / Linux
curl https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"

返回 JSON 格式的鉴权错误,说明端点是真实的;返回一段 HTML,说明地址填错了。

json
{"error":{"message":"Invalid token (request id: 202611220119522926930721cafreY3)","type":"new_api_error"}}

换成真 Key 再跑一次,能返回模型列表就说明 Key 可用,剩下的问题都在客户端配置侧。

注意

这条命令别连着重跑。用错 Key 请求多次会触发按出口 IP 的临时封禁,越重试锁得越久,细节见报错排查指南。

添加服务商

  1. 左下角点 设置(齿轮)→ 模型服务。
  2. 点服务商列表下方的 + 添加服务商。
  3. 填 提供商名称(例如 KL API)和 API 密钥。
  4. 在 端点设置 里填 OpenAI 端点地址;需要原生 Anthropic 协议的话,同时填上 Anthropic 端点。
  5. 点 添加 保存。

官方文档里「更多设置」还能配 OpenAI Responses、Gemini、图像生成和图像编辑的 Base URL。这几个端点我们这边支持情况见文末验证表,别默认全部可用。

模型要手动加进列表

这是最容易漏的一步:填了地址和 Key,不代表模型就能选。

  • 点 获取模型列表,Cherry Studio 会去拉服务商返回的模型,在弹出的列表里点右侧 + 加入。
  • 拉不到就点 + 手动填模型 ID,从 模型清单 复制。
  • 加完打开服务商右上角的 启用开关,否则整个服务商的模型都不会出现在选择器里。

提示

模型名称下面那行才是真正的 API 模型 ID。添加前核对这一行,别凭显示名猜——同名不同版本很常见。

哪些功能会走你配的端点

功能 走自定义端点 说明
对话 走 按你选的模型和端点
知识库 / 向量检索 看配置 需要单独配嵌入模型,本文不涉及
图像生成 看配置 需要另外填图像生成 Base URL
联网搜索、MCP 不走 由 Cherry Studio 或第三方服务提供

验证

先用客户端自带的检测:填好 Key 后点 检测,选一个模型跑一遍。检测通过后再新建对话发一句「只回复 OK」,能流式返回就说明整条链路通了。

检测和实际对话有时不是一回事——检测可能只验密钥或模型列表接口。真发一条消息才算数。

要在客户端之外单独确认 Key 和地址,用 快速开始 里那条 curl,判断标准是返回 JSON 列表。报 404 基本是地址拼错,报 401 是 Key 的问题。

验证状态

项目 状态
字段名是「API 地址」(不是 API Host) 官方文档(2026-11-22 抓取)
填根地址会自动补 /v1/chat/completions;以 # 结尾不再拼接 官方文档
自定义服务商可同时配 OpenAI 与 Anthropic 端点 官方文档
未打开启用开关时模型不出现在选择器 官方文档明确警告
多密钥用英文逗号分隔、轮询使用 官方文档
「多数情况不用重启,新建会话即可」 社区文章(2026-11-19),非官方、未实测
我们的网关在本客户端的真机端到端 未验证
嵌入、图像生成端点在我的网关上的可用性 未验证

待实机验证清单(有客户端和真 Key 时按顺序跑一遍)

  1. OpenAI 端点填根地址 → 对话成功;再试 https://agent.kl-api.info/v1# 是否等价。
  2. Anthropic 端点 → 用 claude-sonnet-4-6 发一条,确认没有打到 api.anthropic.com。
  3. 「获取模型列表」能拉到模型,数量与 模型清单 一致。
  4. 关掉启用开关再开,确认模型列表的显隐行为。
  5. 改完配置不重启、新建会话,确认配置已生效。

参考来源(核对于 2026-11-22)

常见问题

API 地址填根地址还是带 /v1?

填**根地址** https://agent.kl-api.info。官方文档写明:Cherry Studio 会自动补上 /v1/chat/completions,所以填了 /v1 反而可能变成 /v1/v1/chat/completions 报 404。如果你的版本没有自动补,官方给了精确写法:地址以 # 结尾时不再拼接,填 https://agent.kl-api.info/v1# 即可。

配置都填了,为什么模型选择器里看不到?

两个必查项:一是服务商右上角的**启用开关**没打开(官方文档明确警告,不开的话该服务商的模型不会出现在选择列表里);二是模型没有加入列表——只填了地址和 Key 不够,要在「获取模型列表」里点 + 把模型加进来,或用「+」手动填模型 ID。

OpenAI 端点和 Anthropic 端点该填哪个?

两个都可以配,互不冲突:调 gpt-5 这类走 OpenAI 端点,调 claude-sonnet-4-6 走 Anthropic 端点。区别只在地址——OpenAI 端点按客户端规则补路径,Anthropic 端点的地址本身**不带** /v1,因为它的默认值就是 https://api.anthropic.com。

改完配置需要重启 Cherry Studio 吗?

多数情况下不用,新建一个对话就会重新读配置;只有改了系统代理、换了协议类型、或模型列表没刷新时才需要重启。这条依据是社区实践,不是官方文档,我们也没在真机上验证过,先按「新建会话能通就不重启」处理。

报 401 或 429 怎么办?

401 是用错 Key 或 Key 没填对位置;429 要先看原文,invalid tokens multiple times 是用错 Key 触发的临时封禁,不是额度问题。逐层排查见 API 报 401、429、超时怎么排查。