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

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

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

在 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 会添加这些模型，向其中一个发出一次检测请求（计费，也会出现在控制台 → 日志里），然后启用服务商。如果选择「跳过」，请确认服务商页面右上角的启用开关已经打开：开关打开之前，这个服务商的模型不会出现在任何模型选择器里。填好的端点设置如下：

OpenAI / Anthropic / OpenAI Responses Base URL

https://api.router.one

# 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 两种都接受。

填主机根还是 /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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题