# 在 Chatbox 中把 Router One 添加为自定义提供方

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

Chatbox 是开源的 AI 聊天客户端，有桌面端和移动端。Chatbox 的自定义提供方包含名称、API 模式（OpenAI API 兼容、OpenAI Responses API 兼容、Claude API 兼容或 Google Gemini API 兼容）、API 主机和 Key，正好对应 Router One 的端点系列：OpenAI API 兼容能用上目录中的全部对话模型，Responses 与 Claude 两种模式则适合 Router One 在这两种接口上提供的模型系列。这样一把 Key 就能让 Chatbox 用上 Claude、GPT、Gemini、Grok 和 DeepSeek 对话模型，每个请求都记录在控制台 → 日志中。按 Chatbox 1.23.5（2026-09-24 发布）的源码与模型配置教程核对（2026-09-29）。

## 添加之前：哪种 API 模式对应哪些模型

Chatbox 会通过提供方的 API 模式发送该提供方下的所有模型，所以 API 模式决定了哪些 Router One ID 能用。OpenAI API 兼容走 Chat Completions，覆盖全部对话模型，多数人只需要这一个提供方。只有想换用其他接口格式时才再加一个提供方：OpenAI Responses API 兼容适用于 GPT 系列、DeepSeek V4 与 Grok 对话模型，Claude API 兼容适用于 Claude 系列与 DeepSeek V4 的 ID。Google Gemini API 兼容使用 Gemini 原生接口，Router One 不提供；Gemini 的 ID 用 OpenAI API 兼容模式即可。在控制台 → API 密钥点「创建密钥」，为 Chatbox 建一把 Key 并设置 maxSpend 上限；Chatbox 里的多个提供方可以共用这把 Key。

| API 模式 | API 主机 | 预览（实际请求地址） | 适用的 Router One 模型 ID |
| --- | --- | --- | --- |
| OpenAI API 兼容 | https://api.router.one/v1 | https://api.router.one/v1/chat/completions | 全部对话模型：Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| OpenAI Responses API 兼容 | https://api.router.one/v1 | https://api.router.one/v1/responses | GPT 系列、DeepSeek V4 与 Grok 对话模型 ID |
| Claude API 兼容 | https://api.router.one/v1（必须带 /v1） | https://api.router.one/v1/messages | Claude 系列 ID（含 aws/claude-… 与 vertex/claude-… 渠道 ID），以及 deepseek-v4.1-flash、deepseek-v4-flash |
| Google Gemini API 兼容 | 不支持 | — | Router One 不提供 Gemini 原生接口 |

## 在 Chatbox 中添加 Router One 自定义提供方

打开「设置 → 模型提供方」（英文界面为 Settings → Model Provider），点提供方列表底部的「添加」，选择「添加自定义提供商」。在「添加模型提供方」对话框中，「名称」填 Router One，「API 模式」选「OpenAI API 兼容」，然后点「添加」。在提供方页面，「API 主机」填 https://api.router.one/v1，「API 路径」留空：Chatbox 会自动补上 /chat/completions，输入框下方的「预览」会显示它实际请求的完整地址 https://api.router.one/v1/chat/completions。在这一模式下，Chatbox 还会给不带 /v1 的主机补上 /v1，并把误填进主机里的 /chat/completions 移到路径中，这两种常见错误会被自动纠正。把专用 Key 粘贴到「API 密钥」，再添加模型：「获取」会带着你的 Key 请求 GET /v1/models，「新建」用于手动填写精确的 ID。填好的提供方如下：

`chatbox-custom-provider`

```text
# Chatbox：设置 → 模型提供方 → 添加 → 添加自定义提供商
# Chatbox: Settings → Model Provider → Add → Add Custom Provider
名称 / Name:          Router One
API 模式 / API Mode:  OpenAI API 兼容 / OpenAI API Compatible
API 主机 / API Host:  https://api.router.one/v1
API 路径 / API Path:  留空 / empty   → 预览 / Preview: …/v1/chat/completions
API 密钥 / API Key:   sk-your-router-one-key
模型 / Models:        获取 / Fetch，或新建 / New: anthropic/claude-sonnet-5

# Claude API 兼容 / Claude API Compatible（Claude 与 DeepSeek V4 的 ID）
API 主机 / API Host:  https://api.router.one/v1   → …/v1/messages（必须带 /v1 / /v1 is required）
```

## Claude API 兼容模式：API 主机必须带 /v1

在 Claude API 兼容模式下，只有当主机恰好是 https://api.anthropic.com 时，Chatbox 才会补上 /v1；其他主机则直接在所填地址后拼接 /messages。所以请填 https://api.router.one/v1，「预览」会显示 https://api.router.one/v1/messages。如果填主机根地址，Chatbox 会请求 https://api.router.one/messages，返回 404。这个 404 的提示说 Anthropic 客户端应填主机根地址，那是针对会自行补上 /v1 的 Anthropic SDK 的建议；Chatbox 的 Claude 模式不会补，所以要保留 /v1。这一模式只用于 Claude 系列与 DeepSeek V4 的 ID；其他对话模型会收到提示 must be called via /v1/chat/completions 的 HTTP 400。在这一模式下「获取」也帮不上忙：Chatbox 只保留带有 Anthropic 模型类型标记的列表项，而 Router One 返回的 OpenAI 风格模型列表没有这个标记，所以请用「新建」逐个添加 ID。

## 「获取」「新建」与「检查」分别会发出什么

在两种 OpenAI 模式下，「获取」会带着你的 Key 请求 GET /v1/models，列出整个目录，其中包括图像生成模型和模型页没有列出任何能力的 ID。只添加你要用的对话模型，或者用「新建」填入 /models 上的精确 ID，例如 anthropic/claude-sonnet-5、openai/gpt-5.6-sol 或 deepseek-v4.1-flash。「检查」会对一个模型最多发出三次真实请求：先发一次普通请求，通过后再各发一次带图片和带工具调用的请求。这些请求都会计费，也会出现在控制台 → 日志里；纯文本模型或不支持工具的模型在图片或工具测试中失败是正常的。按 Chatbox 教程，没有勾选任何能力的模型会被当作纯文本模型。

## 模型设置：能力、上下文窗口与输出上限

打开模型的设置（「编辑模型」），决定 Chatbox 可以向它发送什么。「测试模型」会执行同样的检查，在对应请求成功时自动勾选「视觉」和「工具使用」；你也可以按模型页自行勾选。「工具使用」不只影响对话：按 Chatbox 源码，智能体模式的工具（MCP、技能、代码执行）、联网浏览、知识库和文件读取，都只会提供给勾选了「工具使用」的模型；未勾选时，智能体模式会拒绝这个模型（提示「该模型不支持智能体模式」）。「上下文窗口」按模型页的窗口换算成整数并往小取（anthropic/claude-sonnet-5 的 1.05M 填 1000000，deepseek-v4.1-flash 填 1000000）；「最大输出Token数」除非你想自设上限，否则留空；「推理」只给会思考的模型勾选。

## 知识库与生图交给其他服务商

Chatbox 的知识库需要嵌入模型来索引文件，而 Router One 不提供 /v1/embeddings，所以创建知识库时请选择其他服务商的嵌入模型；根据知识库回答问题的对话模型仍然可以是勾选了「工具使用」的 Router One 模型。按 Chatbox 1.23.5 源码，自定义的 OpenAI 兼容提供方不提供生图模型，所以「获取」列出的 gpt-image-2 等图像生成 ID 无法在 Chatbox 里生成图片；请在代码或其他客户端中通过 /v1/images/generations 调用它们。

## Chatbox 发出哪些请求，4xx 报错怎么看

每条消息是一次请求；开启工具后，一次回复可能经过多轮调用，每一轮都计费；「检查」与「测试模型」还会产生各自的测试请求。在控制台 → 日志中按 Chatbox 专用的 Key 筛选：每条记录显示模型、Token、费用、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。401 表示 Key 缺失或错误；404 通常是 API 主机与 API 模式不匹配，最常见的是在 Claude API 兼容模式下填了主机根地址；400 且提示 must be called via，说明该模式对应的端点不服务这个 ID；402 表示钱包余额或该 Key 的 maxSpend 已用完。

## Chatbox 该填哪个模型 ID？

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

## Chatbox 用的是哪种 API 协议？

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

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

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

## 常见问题

### 在 Chatbox 里接 Router One，该选哪种 API 模式？

选「OpenAI API 兼容」，API 主机填 https://api.router.one/v1。它走 Chat Completions，Router One 在这个端点上提供全部对话模型，所以一个提供方就能覆盖 Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID。只有想让 Claude 或 DeepSeek V4 的 ID 走 Anthropic Messages 时，才再加一个「Claude API 兼容」提供方（API 主机相同）；想让 GPT、DeepSeek V4 与 Grok 的 ID 走 Responses 时，再加一个「OpenAI Responses API 兼容」提供方。「Google Gemini API 兼容」无法接入 Router One。

### Claude API 兼容模式返回 404，哪里错了？

几乎都是 API 主机的问题。在这一模式下，Chatbox 只会给 https://api.anthropic.com 补上 /v1，所以主机填 https://api.router.one 时，它会请求 Router One 不提供的 https://api.router.one/messages。请把 API 主机改为 https://api.router.one/v1，并确认「预览」显示 https://api.router.one/v1/messages。404 的提示说 Anthropic 客户端应填主机根地址，那是针对会自行补 /v1 的 SDK 的建议，Chatbox 不属于这种情况。

### Claude API 兼容模式下「获取」不到任何模型，为什么？

在这一模式下，Chatbox 会用 Anthropic 的请求头请求模型列表，并且只保留带有 Anthropic 模型类型标记的列表项。Router One 的 GET /v1/models 返回的是 OpenAI 风格的列表，没有这个标记，所以一个都不会保留。请改用「新建」，逐个填写 /models 上的精确 ID，例如 anthropic/claude-sonnet-5 或 deepseek-v4.1-flash。

### 智能体模式下 Router One 的模型是灰色的，怎么启用？

Chatbox 只把智能体模式、MCP 工具、联网浏览和知识库工具提供给勾选了「工具使用」的模型，而通过「获取」或「新建」加入的模型一开始没有任何能力标记。打开模型设置运行「测试模型」，工具调用成功时它会自动勾选「工具使用」；也可以对 /models 详情页标明支持工具调用的 ID 手动勾选。

### API 主机该填主机根地址还是带 /v1？

所有模式都填 https://api.router.one/v1。在 OpenAI API 兼容模式下，即使填主机根地址 Chatbox 也会补上 /v1；OpenAI Responses API 兼容模式规则相同，只是路径是 /responses；在 Claude API 兼容模式下则必须带 /v1。

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

选用当前目录中同时支持 Chatbox 所用端点和所需功能的模型。精确 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
- Chatbox 的 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
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- Cherry Studio 接入：端点设置：https://router.one/zh/integrations/cherry-studio
- 在国内用 Chatbox / Cherry Studio：直连与付款：https://router.one/zh/chatbox-cherry-studio
- NextChat：同一把 Key 的自托管网页聊天：https://router.one/zh/integrations/nextchat
- 通过网关使用工具调用：https://router.one/zh/llm-tool-calling
- Chatbox 官方教程：模型配置：https://docs.chatboxai.app/guides/providers
- Chatbox 发布记录：https://github.com/chatboxai/chatbox/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/chatbox
- 模型与每模型 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