# 在 Cherry Studio 中把 Router One 添加为自定义提供商

> https://router.one/zh/integrations/cherry-studio 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-29

Cherry Studio 是开源（AGPL-3.0）的桌面 AI 客户端，支持 Windows、macOS 和 Linux。2.x 的自定义提供商可以为每种端点类型分别填写 Base URL，包括 OpenAI、Anthropic、OpenAI Responses 和图像生成，正好对应 Router One 按端点系列提供模型的方式：需要哪个端点，就在那一项填主机根地址 https://api.router.one，一把 Key 就能用上目录中的 Claude、GPT、Gemini、Grok 和 DeepSeek 对话模型以及生图模型，每个请求都记录在控制台 → 日志中。按 Cherry Studio 2.1.3（2026-09-24 发布）的源码与服务商文档核对（2026-09-29）。

## 添加之前：各项 Cherry 功能需要哪个端点

Cherry Studio 会把每个模型的请求发到该模型所用的端点，所以填表之前先想好需要哪些端点。多数人只需要 OpenAI 端点，它覆盖全部对话模型。在控制台 → API 密钥点「创建密钥」，为 Cherry Studio 单独建一把 Key，并设置 maxSpend 上限。Cherry 支持在一个服务商里填多把用英文逗号分隔的 Key 轮询使用，但只用一把专用 Key，消费上限和日志筛选才能集中在一处。

| Cherry Studio 功能 | 需要配置的端点 | 适用的 Router One 模型 ID |
| --- | --- | --- |
| 与任意模型对话 | OpenAI（Chat Completions） | 全部对话模型：Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| 走 Responses API 对话 | OpenAI Responses | GPT 系列、DeepSeek V4 与 Grok 对话模型 ID |
| 走 Anthropic Messages 对话，以及 Cherry 智能体（Agent） | Anthropic | Claude 系列与 DeepSeek V4 的 ID；Cherry 文档写明 Agent 需要这一类型 |
| 图像生成 | 图像生成 Base URL，或默认端点的 Base URL | gpt-image-2 等生图模型，按张计价 |
| 知识库嵌入 | Router One 不提供 | Router One 没有 /v1/embeddings，请使用其他服务商的嵌入模型 |

## 在 Cherry Studio 中添加 Router One 自定义提供商

打开「设置 → 模型服务」（英文界面为 Settings → Model Provider），点服务商列表下方的「添加服务商」，打开「添加自定义提供商」。「提供商名称」填 Router One，「API 密钥」粘贴专用 Key。在「端点设置」中，OpenAI 和 Anthropic 两项都填主机根地址 https://api.router.one。填入根地址后，Cherry 会显示实际的「请求路径」：分别是 https://api.router.one/v1/chat/completions 和 https://api.router.one/v1/messages。在「更多设置」中添加 OpenAI Responses，同样填主机根地址。「图像生成 Base URL」可以留空，留空时 Cherry 使用默认对话端点的 Base URL；Gemini 保持为空。把 OpenAI 保留为默认端点（「设为默认」），这样新添加的模型默认走覆盖全部对话模型的 Chat Completions。点「添加」。填了 Key 时，Cherry 2.1.3 接着会打开「选择模型」步骤：勾选要用的对话模型后点「添加所选模型」，Cherry 会添加这些模型，向其中一个发出一次检测请求（计费，也会出现在控制台 → 日志里），然后启用服务商。如果选择「跳过」，请确认服务商页面右上角的启用开关已经打开：开关打开之前，这个服务商的模型不会出现在任何模型选择器里。填好的端点设置如下：

`cherry-studio-custom-provider`

```text
# Cherry Studio：设置 → 模型服务 → 添加服务商 → 添加自定义提供商
# Cherry Studio: Settings → Model Provider → Add Provider → Add Custom Provider
提供商名称 / Provider Name:   Router One
API 密钥 / API Key:           sk-your-router-one-key

# 端点设置 / Endpoint settings
OpenAI:              https://api.router.one   → …/v1/chat/completions（设为默认 / Set as default）
Anthropic:           https://api.router.one   → …/v1/messages
# 更多设置 / More options
OpenAI Responses:    https://api.router.one   → …/v1/responses
图像生成 Base URL / Image Generation Base URL:   留空 / blank（使用默认端点 / uses the default endpoint）
Gemini:              留空 / leave empty
```

## 每个 Router One 模型 ID 走哪个端点

Cherry 会自行拼接版本号和路径：根地址里没有版本段时先补上 /v1，再按端点类型拼接 /chat/completions、/responses、/messages 或 /images/generations。Router One 在 Chat Completions 上提供全部对话模型，在 Anthropic Messages 上提供 Claude 系列与 DeepSeek V4 的 ID，在 Responses 上原生提供 GPT 系列、DeepSeek V4 与 Grok 对话模型，所以端点要按模型 ID 来选。Claude ID 发到 OpenAI Responses 端点，会在调用任何模型之前被 HTTP 400 拒绝（model '<id>' must be called via /v1/messages or /v1/chat/completions）；Claude 与 DeepSeek 系列以外的对话模型发到 Anthropic 端点，会收到提示 must be called via /v1/chat/completions 的 400。Cherry 会同时用 Authorization: Bearer 和 X-Api-Key 两种请求头发送 Key，Router One 两种都接受。

| Cherry 端点 | 填写的 Base URL | Cherry 显示的请求路径 | 适用的 Router One 模型 ID |
| --- | --- | --- | --- |
| OpenAI | https://api.router.one | https://api.router.one/v1/chat/completions | 全部对话模型：Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| OpenAI Responses | https://api.router.one | https://api.router.one/v1/responses | GPT 系列、DeepSeek V4 与 Grok 对话模型 ID |
| Anthropic | https://api.router.one | https://api.router.one/v1/messages | Claude 系列 ID（含 aws/claude-… 与 vertex/claude-… 渠道 ID），以及 deepseek-v4.1-flash、deepseek-v4-flash |
| 图像生成 Base URL | https://api.router.one，或留空 | https://api.router.one/v1/images/generations | /models 中的生图模型，例如 gpt-image-2 |
| Gemini | 保持为空 | — | Router One 不提供 Gemini 原生接口；Gemini 的 ID 走 OpenAI 端点即可 |

## 填主机根还是 /v1？本指南为什么填主机根

Cherry 官方文档的约定是只填根地址、其余由 Cherry 自动补全，这种写法在所有版本中都可用。在 Cherry Studio 1.7.0 及以后的版本中，已经带版本段（如 /v1）的地址会原样保留，所以填 https://api.router.one/v1 也可以。1.6.7（2025-11-04 发布）及更早的版本会给任何不以斜杠结尾的地址追加 /v1/，带 /v1 的地址会变成 /v1/v1/…，返回 404；Router One 对这种路径返回的 404 信息会提示客户端已经自行拼接了 /v1。按 Cherry 界面提示和源码，在地址末尾加 # 可以阻止 Cherry 追加版本段；接 Router One 不需要这样做。

## 模型设置：对话协议、上下文窗口与模型能力

「同步模型」会带着你的 Key 请求 GET /v1/models，并列出其中的模型供你添加；「+」（手动添加模型）可以手动添加 ID。这个列表就是整个目录，其中包括图像生成模型和模型页没有列出任何能力的 ID，所以只添加你要用的对话模型。Cherry 会在模型名称下方显示实际的 API 模型 ID，它必须与 /models 上的 ID 完全一致，例如 anthropic/claude-sonnet-5 或 openai/gpt-5.6-sol。对于自定义提供商，每个模型都有「模型用途」（对话、图像生成或图像编辑），对话模型还要从已配置的端点中选择「对话协议」；新模型默认使用服务商的默认端点。只有想换用对应的接口格式时，才把 Claude 或 DeepSeek V4 模型改到 Anthropic，或把 GPT 模型改到 OpenAI Responses。「上下文窗口」按模型页的窗口换算成整数并往小取（anthropic/claude-sonnet-5 的 1.05M 填 1000000，deepseek-v4.1-flash 填 1000000）；「最大输出 Token」除非你想自设上限，否则留空；图片输入、工具调用等「模型能力」只在模型页列出时才勾选。

## Cherry 智能体、知识库与图像生成

Cherry 的服务商文档把 Anthropic 兼容类型标为 Cherry 智能体（Agent）所需的类型，所以智能体请使用 Anthropic 端点，并选择模型页标明支持工具调用的 Claude 系列或 DeepSeek V4 ID，例如 anthropic/claude-sonnet-5 或 deepseek-v4.1-flash。知识库需要嵌入模型来索引文档，而 Router One 不提供 embeddings 端点，所以请在知识库里选择其他服务商的嵌入模型，对话仍然走 Router One。生图时，添加 gpt-image-2 这类生图模型并把用途设为「图像生成」；Cherry 会请求「图像生成 Base URL」下的 /v1/images/generations，该项留空时使用默认端点的 Base URL。生图模型按张计价，价格以各模型页为准，每次生成都会带着费用出现在日志里。

## 检测连接，再到日志核对

「检测」会向你选定的模型发出一次真实请求，因此会计费，也会出现在控制台 → 日志里；Cherry 自己也提示，一次检测所有模型会发出大量真实请求。检测失败时按状态码排查：401 表示 Key 缺失或错误；404 通常是 Base URL 与端点不匹配，例如在 1.7.0 之前的版本里填了带 /v1 的地址；400 且提示 must be called via，说明这个端点不服务该模型的 ID，请把模型改到错误信息指明的端点；402 表示钱包余额或该 Key 的 maxSpend 已用完。日志中的每条记录显示模型、Token、费用、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。首次测试时，服务商「API 设置」里的 Developer Message、service_tier 等开关保持默认即可。

## Cherry Studio 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Cherry Studio 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

## Cherry Studio 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在请求日志里核对 Cherry Studio 的调用

先在 Cherry Studio 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 在 Cherry Studio 里从哪里添加 Router One？

在「设置 → 模型服务」中，点服务商列表下方的「添加服务商」，会打开「添加自定义提供商」。填好「提供商名称」「API 密钥」和「端点设置」里的 Base URL 后点「添加」，再在 Cherry 2.1.3 打开的「选择模型」步骤里选好模型：「添加所选模型」会发出一次检测请求并启用服务商；如果点了「跳过」，就自己打开服务商页面右上角的启用开关。「更多设置」里还有「从预设创建（可选）」，Cherry 文档说明它适用于 Coding Plan 接入、多个账号管理或项目隔离；接 Router One 用普通的自定义提供商就够了。

### API 地址要以 /v1 结尾吗？

按本指南不需要：填 https://api.router.one，Cherry 在所有版本中都会自动补上 /v1 和路径。在 Cherry Studio 1.7.0 及以后的版本中，填 https://api.router.one/v1 也可以，因为 Cherry 会保留已有的版本段；1.6.7 及更早的版本会拼成 /v1/v1/…，返回 404。保存前，各端点下方的「请求路径」预览会显示最终的地址。

### 对话里的模型选择器找不到 Router One 的模型，为什么？

取决于两点：服务商页面右上角的启用开关必须打开，每个模型也必须通过「同步模型」或「+」（手动添加模型）加入服务商的模型列表，只拉取而没有添加的模型不会出现。另外确认模型用途是「对话」，因为生图模型只出现在 Cherry 生成图片的地方。

### Claude 应该走 OpenAI 端点还是 Anthropic 端点？

接 Router One 两种都可以：Router One 在 Chat Completions 和 Anthropic Messages 上都提供 Claude 系列 ID。普通对话保留默认的 OpenAI 端点即可；当某个 Cherry 功能需要时，例如 Cherry 文档要求 Anthropic 类型的智能体，再把 Claude 模型的对话协议改为 Anthropic。Gemini 的 ID 保持在 OpenAI 端点；GPT 与 Grok 的 ID 也可以用 OpenAI Responses。

### Router One 能用于 Cherry 的知识库吗？

只能承担对话部分。知识库需要嵌入模型来索引文档，而 Router One 不提供 embeddings 端点，所以创建知识库时请选择其他服务商的嵌入模型。对知识库提问时仍可以使用 Router One 的对话模型，检索到的段落会作为输入 Token 计入日志。

### Cherry Studio 能通过网关用哪些模型？

选用当前目录中同时支持 Cherry Studio 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到控制台 → 日志核对这条请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Cherry Studio 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Chatbox 接入：https://router.one/zh/integrations/chatbox
- Cline 接入：https://router.one/zh/integrations/cline
- 在国内用 Chatbox / Cherry Studio：直连与付款：https://router.one/zh/chatbox-cherry-studio
- 生图 API：https://router.one/zh/image-generation-api
- 通过网关使用工具调用：https://router.one/zh/llm-tool-calling
- Cherry Studio 官方文档：自定义服务商：https://docs.cherryai.com.cn/pre-basic/providers/zi-ding-yi-fu-wu-shang
- Cherry Studio 官方文档：服务商类型：https://docs.cherryai.com.cn/pre-basic/providers
- Cherry Studio 官方文档：模型服务设置：https://docs.cherryai.com.cn/pre-basic/providers/providers
- Cherry Studio 发布记录：https://github.com/CherryHQ/cherry-studio/releases
- 统一 LLM API 网关概览：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/cherry-studio
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md