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,看它回什么:
curl.exe https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"
curl https://agent.kl-api.info/v1/models -H "Authorization: Bearer sk-invalid-test"
返回 JSON 格式的鉴权错误,说明端点是真实的;返回一段 HTML,说明地址填错了。
{"error":{"message":"Invalid token (request id: 202611220119522926930721cafreY3)","type":"new_api_error"}}
换成真 Key 再跑一次,能返回模型列表就说明 Key 可用,剩下的问题都在客户端配置侧。
注意
这条命令别连着重跑。用错 Key 请求多次会触发按出口 IP 的临时封禁,越重试锁得越久,细节见报错排查指南。
添加服务商
- 左下角点 设置(齿轮)→ 模型服务。
- 点服务商列表下方的 + 添加服务商。
- 填 提供商名称(例如
KL API)和 API 密钥。 - 在 端点设置 里填 OpenAI 端点地址;需要原生 Anthropic 协议的话,同时填上 Anthropic 端点。
- 点 添加 保存。
官方文档里「更多设置」还能配 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 时按顺序跑一遍)
- OpenAI 端点填根地址 → 对话成功;再试
https://agent.kl-api.info/v1#是否等价。 - Anthropic 端点 → 用
claude-sonnet-4-6发一条,确认没有打到api.anthropic.com。 - 「获取模型列表」能拉到模型,数量与 模型清单 一致。
- 关掉启用开关再开,确认模型列表的显隐行为。
- 改完配置不重启、新建会话,确认配置已生效。
参考来源(核对于 2026-11-22)
- 字段含义、根地址自动补全、
#结尾规则、启用开关警告:Cherry Studio 官方文档 · 模型服务设置 - 自定义服务商的端点类型(OpenAI / Anthropic / Responses / Gemini):Cherry Studio 官方文档 · 自定义服务商
- 接口地址与鉴权方式:快速开始
- 报错原文与分层排查:API 报 401、429、超时怎么排查