# Chatbox 接入 QCode：Windows 图文教程


**一句话答案**：在 Chatbox 里打开 `Settings → Model Provider`（设置 → 模型服务商），点 `+ Add` 新建自定义服务商，`API Mode`（接口模式）选 `Claude API Compatible`（兼容 Claude API），`API Host`（接口地址）填 `https://api.qcode.cc/api/v1`，贴上 `cr_` 开头的密钥，再手填模型 ID `claude-sonnet-5`。

| 项 | 填写 |
|---|---|
| `Claude API Host` | `https://api.qcode.cc/api/v1` |
| `API Path` | `/messages` |
| `OpenAI API Host` | `https://api.qcode.cc/openai/v1` |
| `API Key` | `cr_xxxxxxxx` |
| `Model ID` | `claude-sonnet-5` |

核对于 2026-11-21 · Chatbox 1.24.6（英文界面截图）· Windows 11


照着下面的截图在一台 Windows 电脑上做完，你的 Chatbox 里就会多出一个 QCode 服务商，聊天窗口里能选中 Claude 模型，屏幕上能收到回答。全程都不需要 Chatbox 账号。


- **适用系统**：Windows 10 / 11（64 位）；截图在 Windows 11 上拍摄
- **软件版本**：Chatbox 1.24.6（英文界面截图）
- **截图更新于**：2026-11
- **预计用时**：约 15 分钟，其中大部分时间花在下载一个 230 MiB 的安装包上
- **需要准备**：一个 `cr_` 开头的 QCode API 密钥


开始第一张截图之前，先确认这几件事：


- 一台能打开网站的 Windows 10 / 11 电脑（64 位）
- 约 1 GB 空闲磁盘空间；安装包装在你自己的用户账户下，不需要管理员密码
- 一个从控制台复制好的 QCode API 密钥（`cr_xxxxxxxx`），这是唯一不能省的一步。还没有账号？先[注册](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-chatbox-before)，在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-chatbox-before)挑一个方案，再到[控制台](https://qcode.cc/dashboard)创建密钥。
- 不需要 Chatbox 账号：欢迎页上有一个 `Skip guide` 按钮，所有配置都存在本地


## 下载与安装 Chatbox

Chatbox 只为 Windows 提供了一个安装包。按你所在的地区选一行：

**中国大陆**

打开 **chatboxai.app/zh/download**，在 `Windows` 下面写着 `64-bit` 的那一行点 `Download`。文件名是 `Chatbox-1.24.6-Setup.exe`，约 230 MiB。国际站（chatboxai.app/en/download）给的是同一个安装包，中文页面慢的时候可以用它。


**其他地区**

打开 **chatboxai.app/en/download**。在 `Desktop App`（桌面版）下面，Windows 那一行写着 `64-bit`，点它右边的 `Download` 按钮。下到的是 `Chatbox-1.24.6-Setup.exe`，约 230 MiB。

如果页面打不开，可以用 **GitHub Releases**（github.com/chatboxai/chatbox/releases）：展开 `Downloads` 一栏，点 `Windows (x64)`。那里最新的版本是 v1.24.4，比官网的安装包旧，所以优先用下载页。

![GitHub Releases 页面：Downloads 列表里有 Windows (x64) 链接，最新版本是 v1.24.4，比官网的安装包旧](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/03-github-releases.webp)




### 打开下载页

打开下载页（中国大陆用 **chatboxai.app/zh/download**，其他地区用 **chatboxai.app/en/download**，两页布局相同）。在 `Desktop App`（桌面版）下面，① 的 Windows 那一行写着 `64-bit`，② 是它右边的 `Download` 按钮。点 ②。

![官方英文下载页：Desktop App 下面 Windows 那一行写着 64-bit，右侧的 Download 按钮被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/01-download-page.webp)


做对了你会看到：浏览器开始下载一个叫 `Chatbox-1.24.6-Setup.exe` 的文件，约 230 MiB。文件名里的版本号以后会变。




### 确认安装包下载完了

打开浏览器的下载面板。① 那条记录是下完的安装包，显示着完整大小。

![浏览器下载面板：一条已完成的 Chatbox-1.24.6-Setup.exe 下载记录，约 230 MiB](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/02-download-done.webp)


做对了你会看到：① 只有一条已完成的记录，名字是 `Chatbox-1.24.6-Setup.exe`，后面没有进度条。如果记录以 `.crdownload` 结尾，说明还在下载 —— 等它变成 `.exe` 的名字。




### 选择给谁安装

双击下载好的文件。向导第一屏选 ① `Only for me (user)`（仅为我安装），再点 ② `Next >`（下一步）。

![Chatbox 安装向导第一屏 Choose Installation Options：Only for me (user) 已被选中，Next 按钮被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/04-installer-options.webp)

**卡住了？Windows 弹出管理员密码框**

选中 `Only for me (user)` 时，安装包只会写进你自己的 AppData 目录，不需要管理员权限。如果弹出密码框，取消它再重新运行安装包 —— 第一屏必须是 `Only for me (user)` 处于选中状态。



做对了你会看到：① `Only for me (user)` 被勾上，向导翻到 `Choose Install Location`（选择安装位置）。




### 保持默认安装目录

第二屏显示软件装到哪里，默认就在你自己的 AppData 目录下。不用改，直接点 ① `Install`（安装）。

![Chatbox 安装向导第二屏 Choose Install Location：默认的用户 AppData 目录，Install 按钮被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/05-installer-location.webp)


做对了你会看到：按钮消失，窗口换成 `Please wait while Chatbox is being installed.`（正在安装 Chatbox，请稍候）。




### 等进度条走完

这一步不用点任何东西。普通电脑上进度条约 20 秒走完。

![Chatbox 安装进度画面：安装进度条走到一半](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/06-installer-installing.webp)


做对了你会看到：进度条走到头，窗口自己翻到 `Completing Chatbox Setup`（正在完成 Chatbox 安装）。




### 启动 Chatbox

最后一屏保持 `Run Chatbox`（运行 Chatbox）勾选，点 ① `Finish`（完成）。

![正在完成 Chatbox 安装这一屏：Run Chatbox 保持勾选，Finish 按钮被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/07-installer-finish.webp)


做对了你会看到：安装向导关掉，Chatbox 窗口自己打开。




### 跳过欢迎页

第一次启动会打开欢迎页。不需要账号：不用管 ① `I'm new to this`（我是新手），直接点右边的 ② `Skip guide`（跳过引导）。

![首次启动的欢迎页：左边是 I'm new to this 卡片，右边是 Skip guide 卡片](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/08-first-run-welcome.webp)

**卡住了？欢迎页上没有 Skip guide**

确认你装的是 1.24.6 或更新的版本：欢迎页底部有两张卡片，`I'm new to this` 和 `Skip guide`。两张都看不到，说明安装包还没跑完 —— 回到安装向导最后一屏点 `Finish`。



做对了你会看到：欢迎页关掉，进到主界面 —— 左边是会话列表，底部是消息输入框，没有登录提示。




### 打开 `Settings → Model Provider`

点主窗口左下角的 `Settings`（设置）。在设置页左栏点 ① `Model Provider`（模型服务商），服务商列表就会打开。添加自己服务商的按钮在列表最后一行：② `+ Add`（+ 添加）。

![设置页：左栏选中了 Model Provider，服务商列表最底部是 + Add](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/09-settings-model-provider.webp)

**卡住了？左栏里没有 Model Provider**

在 Chatbox 1.24.6 里，这一项就在设置页的左栏。找不到的话，先确认你在设置页而不是某个会话里：点主窗口左下角的 `Settings`，再顺着左栏往下找列出 OpenAI、Claude、Gemini 这些服务商的那一页。



做对了你会看到：① `Model Provider` 在左栏呈选中状态，中间是一列服务商，② `+ Add` 就在这一列的最后一行。




### 打开自定义服务商表单

点 `+ Add`。会打开一个内置服务商目录，在搜索框里输入 `custom`，然后点 ① `Add Custom Provider`（添加自定义服务商）。

![服务商目录：搜索框里输入了 custom，只剩 Add Custom Provider 一条结果](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/10-add-provider-picker.webp)


做对了你会看到：弹出一个标题为 `Add provider`（添加服务商）的窗口，里面有两个字段：`Name` 和 `API Mode`。




### 选择 Claude 接口模式

展开 ① `API Mode`（接口模式）下拉，选 `Claude API Compatible`（兼容 Claude API）。这一步决定 Chatbox 用 Claude 协议说话，后面几步的地址字段都跟着它走。

![添加服务商窗口：API Mode 下拉已展开，Claude API Compatible 被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/11-add-provider-mode.webp)


做对了你会看到：① `API Mode` 那一栏现在写着 `Claude API Compatible`。




### 给服务商起个名字

在 ① `Name`（名称）里填 `QCode Claude`。② `API Mode` 保持 `Claude API Compatible`，然后点 `Add`（添加）。

![添加服务商窗口：名称填了 QCode Claude，API Mode 保持 Claude API Compatible](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/12-add-provider-filled.webp)


做对了你会看到：窗口关掉，打开新服务商的页面，上面有 `API Host`、`API Path` 和 `Preview` 三个字段。




### 填 Claude 的接口地址

在 ① `API Host`（接口地址）里填 `https://api.qcode.cc/api/v1`。`API Path`（接口路径）保持 `/messages`。Chatbox 会自己把两段拼起来：② `Preview`（预览）应该显示 `https://api.qcode.cc/api/v1/messages`。

![服务商页面：API Host 填了 https://api.qcode.cc/api/v1，Preview 一行显示 https://api.qcode.cc/api/v1/messages](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/13-claude-api-host.webp)

**卡住了？Preview 显示 /api/messages，没有 /v1**

对自定义的 Claude 地址，Chatbox 只会往后拼 `/messages` —— 不像对 `api.anthropic.com` 那样补 `/v1`，也不像 Cherry Studio 那样补 `/v1`。所以要自己把版本段写进 Host 字段：`https://api.qcode.cc/api/v1`。QCode 通用的 Anthropic 根地址 `https://api.qcode.cc/api` 是给那些 SDK 自己会补 `/v1/messages` 的客户端用的。



做对了你会看到：① 以 `/api/v1` 结尾，② 显示 `https://api.qcode.cc/api/v1/messages`。




### 粘贴 API 密钥

点 `API Key`（API 密钥）输入框，把从 QCode 控制台复制的密钥粘进去。输入框只显示一排圆点 —— 这是正常的，密钥照你输入的内容保存。

![API Key 输入框：填入的 QCode 密钥被遮住，只显示一排圆点](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/14-api-key-filled.webp)

**需要 API Key？**

还没有 QCode 账号的话，先[注册](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-chatbox-key)。不想用包月方案，可以先在[按量包](https://qcode.cc/pay-as-you-go?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-chatbox-key)页面买一个包开始用，再到[控制台](https://qcode.cc/dashboard)创建密钥，复制 `cr_` 开头的那一串贴回上面的输入框。



做对了你会看到：输入框里是一排圆点，灰色占位提示已经消失。如果框里还是空的，先点一下输入框，等半秒再粘一次 —— 密钥前后不要带空格。




### 添加模型 ID

点 `+ New`（+ 新建）。在 `Edit Model`（编辑模型）窗口里把 ① `claude-sonnet-5` 填进 `Model ID`（模型 ID），再点 ② `Save`（保存）。Chatbox 不会去拉 QCode 的模型列表，所以 ID 要手填。

![编辑模型窗口：Model ID 填了 claude-sonnet-5，Save 按钮被高亮](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/15-add-model.webp)

**卡住了？刷新以后模型列表还是空的**

Chatbox 里自定义的 Claude 兼容服务商不会拉取模型列表，所以什么都不会自动出现。手动把 ID 加进去，例如 `claude-sonnet-5`、`claude-opus-5-5` 或 `claude-haiku-5-5`；能用的 ID 都列在 [qcode.cc/models](https://qcode.cc/models)。照抄 ID，连字符别丢。



做对了你会看到：`claude-sonnet-5` 成为 `QCode Claude` 服务商模型列表里的一行。




### 检查连接

点 `Check`（检查）。它问要测哪个模型时，选 `claude-sonnet-5`。① `Model Test Results`（模型测试结果）随后显示 `Connection successful`（连接成功），文本、视觉和工具调用三项都打勾。

![模型测试结果窗口：claude-sonnet-5 显示 Connection successful，文本、视觉和工具调用都打勾](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/16-check-result.webp)

**卡住了？检查报错**

先核对两个字段：`API Host` 必须是 `https://api.qcode.cc/api/v1`，`API Key` 框里必须是一排圆点。然后再点一次 `Check` —— 一次网络抖动是最常见的原因。如果报错里提到模型，确认模型 ID 正好是 `claude-sonnet-5`。



做对了你会看到：① 绿色的 `Connection successful`，文本、视觉和工具调用每一项后面都有一个勾。




### 在聊天窗口里选中模型

关掉设置，新建一个会话。打开右下角的模型选择器，把列表切到 `More Providers (BYOK)`（更多服务商），展开 ① `QCode Claude`，点 ② `claude-sonnet-5`。

![聊天模型选择器：More Providers (BYOK) 下面的 QCode Claude 分组已展开，列出 claude-sonnet-5](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/19-model-picker.webp)


做对了你会看到：右下角的模型选择器现在显示 `claude-sonnet-5`，而不是 Chatbox 自带的某个模型。




### 发第一条消息

点消息输入框，输入 `Say hello in one short sentence`，按回车。① 是你在会话里发的那条消息。

![聊天区域：发出的消息是 Say hello in one short sentence，下面是回复 Hello!](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/20-first-reply.webp)

**卡住了？回复不是文字，而是一条红色报错**

打开模型选择器，确认模型是 `QCode Claude` 下面的 `claude-sonnet-5`，不是 OpenAI 服务商下面的某个 GPT 模型。Claude 模型只能通过 `Claude API Compatible` 的服务商、配 `https://api.qcode.cc/api/v1` 来回答。



做对了你会看到：① 是你发的那条消息，下面是一句很短的回复，例如 `Hello!`，回复下方还有一行小字，写着 `claude-sonnet-5` 和 token 数。




### 追问一句

输入 `Was that last sentence your own answer just now?`，按回车。① 是这句追问；② 是模型对它的回答。

![同一个会话：接着上一句的追问，下面是模型的回答](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/21-followup-reply.webp)


做对了你会看到：模型会回头引用它上一轮说过的话，说明会话保留了上下文。




## 验证成功

下面四条全部对上，就说明配好了：

- `Settings → Model Provider` 里有一个叫 `QCode Claude` 的服务商，它的 `API Mode` 是 `Claude API Compatible`，`API Host` 是 `https://api.qcode.cc/api/v1`。
- 这个服务商的 `Preview` 行显示 `https://api.qcode.cc/api/v1/messages`，密钥框里是一排圆点。
- 这个服务商的 `Check` 对 `claude-sonnet-5` 报告 `Connection successful`。
- 在新会话里发一句话能收到正常回答，回复下方写着 `claude-sonnet-5` 和 token 数。

想亲眼看请求本身，打开 **probe.qcode.cc**，贴上同一把密钥，就能看到发到 QCode 的流量。


### 全部完成

你已经把 QCode 接进 Chatbox，Claude 在聊天窗口里能正常回答了。接下来可以：

- 在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-chatbox-done)比较各个方案，挑一个适合长期用的
- 回到[控制台](https://qcode.cc/dashboard)查看用量和余额
- [接入点与 API 路径](/docs/getting-started/endpoints-and-api-paths)
- [国产模型接入](/docs/usage/cn-models)
- [故障排查](/docs/reference/troubleshooting)


## 常见报错

| 报错原文 | 原因 | 怎么办 |
|---|---|---|
| `Fetch uses /models while API Path is /v1/chat/completions` | `API Host` 里少了版本段，拉模型列表的请求打到了错误的路径 | 把版本段写进 Host：`https://api.qcode.cc/openai/v1`，`API Path` 保持 `/chat/completions` |
| `API Error: Error from Custom Claude: TypeError: Load failed (api.example.com)` | 请求根本没离开应用：报错里的主机连不上，要么地址写错了，要么网络把它挡住了 | 核对拆分方式：`API Host` 是 `https://api.qcode.cc/api/v1`，`API Path` 是 `/messages`；`Preview` 必须是 `https://api.qcode.cc/api/v1/messages`。还不行就打开 `Improve Network Compatibility`（改善网络兼容性） |
| `API Error: Error from Claude: TypeError: Failed to fetch(192.168.1.206:8080)` | 请求在离开本机之前就被应用内部挡住了，通常是 WebView 的网络限制 | 在自定义服务商上打开 `Improve Network Compatibility`，再确认 `API Host` 是 `https://api.qcode.cc/api/v1` |
| `API Error: Error from Custom OpenAl: Network Error: Failed to fetch (api.firefllyai.chat)` | 自定义服务商上同样的网络限制；报错里的主机是你自己填的那个，不是 QCode 的 | 在这个自定义服务商上打开 `Improve Network Compatibility`，再确认 `API Host` 是 `https://api.qcode.cc/openai/v1` |

## 常见问题

### 需要注册 Chatbox 账号吗？

不需要。Chatbox 是本地客户端：在欢迎页点 `Skip guide`，填上 QCode 的地址和密钥就能用。这篇教程里没有任何一步需要登录。

### 为什么 Claude 的接口地址要以 /v1 结尾？

因为 Chatbox 不会替你补。自定义的 Claude 地址只会被追加 `/messages`，所以 `https://api.qcode.cc/api` 会变成 `https://api.qcode.cc/api/messages`，返回 404。QCode 通用的 Anthropic 根地址 `https://api.qcode.cc/api` 是给那些 SDK 自己会补 `/v1/messages` 的客户端用的 —— Cherry Studio 是那样，Chatbox 不是。

### 模型列表为什么是空的？

Chatbox 里的自定义服务商不会拉取模型列表，所以什么都不会自动出现。用 `+ New` 手动逐个添加模型 ID，例如 `claude-sonnet-5`、`claude-opus-5-5` 或 `claude-haiku-5-5`；完整清单在 [qcode.cc/models](https://qcode.cc/models)。照抄 ID，连字符别丢。

### 同一个应用里能用 GPT 模型吗？

可以。再建一个服务商，`API Mode` 选 `OpenAI API Compatible`，`API Host` 填 `https://api.qcode.cc/openai/v1`，用同一把 `cr_` 密钥，模型 ID 填 `gpt-6.2-sol`。下面那节可选内容会把这一步走一遍。切换模型用模型选择器，每个服务商各自维护自己的模型列表。

### 密钥到期了，还能续吗？

要看这把密钥是从哪来的。包月个人套餐的密钥到期后不能续：重新开一个套餐，在[控制台](https://qcode.cc/dashboard)创建一把新密钥，再把新的 `cr_` 值粘进 `API Key` 框。按量包的密钥在你再买一个包之后会恢复 —— 还是同一把密钥，Chatbox 这边什么都不用改。

### Chatbox 能通过 QCode 调用 Gemini 吗？

不能。QCode 不提供 Gemini 模型。请用 `Claude API Compatible` 走 Claude 模型，或者用 `OpenAI API Compatible` 走 GPT 和国产模型。

## 可选：同时使用 GPT 模型

QCode 的 GPT 和国产模型走 OpenAI 协议。Chatbox 的一个服务商只能说一种协议，所以这是用同一把密钥再建一个服务商。只需要 Claude 的话，这一节可以跳过。



### 再建一个 OpenAI 兼容的服务商

回到 `Settings → Model Provider`，再点 `+ Add`，然后点 `Add Custom Provider`。名字填 `QCode OpenAI`，`API Mode` 选 `OpenAI API Compatible`（兼容 OpenAI API），把 `https://api.qcode.cc/openai/v1` 填进 ① `API Host` —— 同样要带版本段，因为这个模式也不会自己补。② `Preview` 应该显示 `https://api.qcode.cc/openai/v1/chat/completions`。贴上同一把密钥，然后加上模型 ID `gpt-6.2-sol`；③ 是它出现在模型列表里的样子。

![第二个服务商 QCode OpenAI：API Host 填了 https://api.qcode.cc/openai/v1，Preview 显示 /openai/v1/chat/completions，模型列表里有 gpt-6.2-sol](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/17-openai-provider.webp)

**卡住了？Claude 模型在这里不回答**

OpenAI 兼容的服务商跑不了 Claude 模型。Claude 继续放在 `QCode Claude` 服务商里、配 `https://api.qcode.cc/api/v1`，这第二个服务商只用来跑 GPT 和国产模型。



做对了你会看到：① 以 `/openai/v1` 结尾，② 以 `/openai/v1/chat/completions` 结尾，③ 的 `QCode OpenAI` 模型列表里有 `gpt-6.2-sol`。




### 检查 GPT 连接

点 `Check`，它问模型时选 `gpt-6.2-sol`，等 ① `Model Test Results` 出来。

![QCode OpenAI 服务商的模型测试结果：gpt-6.2-sol 报告 Connection successful](https://docs.qcode.cc/static/images/tut/chatbox/202611/en/18-openai-check-result.webp)


做对了你会看到：① `gpt-6.2-sol` 显示 `Connection successful`，说明同一把密钥在两个服务商上都能用。




## 服务商类型与 QCode 地址

Chatbox 按 `API Mode` 决定协议，然后把 `API Path` 拼到 `API Host` 后面。照着这张表填就不会错：

| API 模式 | 你填的 API Host | API Path | Preview 显示 | 能用的模型 |
|---|---|---|---|---|
| `Claude API Compatible` | `https://api.qcode.cc/api/v1` | `/messages` | `https://api.qcode.cc/api/v1/messages` | Claude；国产模型也能走这个接口 |
| `OpenAI API Compatible` | `https://api.qcode.cc/openai/v1` | `/chat/completions` | `https://api.qcode.cc/openai/v1/chat/completions` | GPT 和国产模型 —— 不能跑 Claude |
| `Google Gemini API Compatible` | QCode 不提供 Gemini | — | — | 没有 |

- **另外两个接入点**：`asia.qcode.cc` 和 `us.qcode.cc` 接受同样的路径和同样的密钥 —— 把 `api.qcode.cc` 换掉，其余不动，包括 `/api/v1` 或 `/openai/v1`。默认域名在你这儿慢的时候可以试。
- **`/v1` 段属于 Host。** Chatbox 只拼 Path，所以上面两个 QCode 地址都以版本段结尾。这是 Chatbox 和 Cherry Studio 这类客户端唯一的区别：后者的 SDK 会把 `/v1/messages` 补到 QCode 通用的 Anthropic 根地址 `https://api.qcode.cc/api` 后面。
- **`Preview` 是最快的自检。** 它显示 Chatbox 实际会请求的完整 URL；如果显示的是 `/api/messages` 或 `/openai/chat/completions`，说明 Host 里少了版本段。

## 可以使用的模型

- **Claude** —— 走 `Claude API Compatible`，例如 `claude-sonnet-5`、`claude-opus-5-5`、`claude-haiku-5-5`
- **GPT** —— 走 `OpenAI API Compatible`，例如 `gpt-6.2-sol`、`gpt-6.1-terra`
- **国产模型** —— 走 `OpenAI API Compatible`，例如 `glm-5.3`、`kimi-k3`、`deepseek-v4-pro`
- **Gemini** —— QCode 不提供；Chatbox 的 Gemini 模式没有对应的 QCode 地址

每个模型 ID 都用 `+ New` 手动添加，之后还能改。最新清单在 **qcode.cc/models**。

## 关键设置项说明

| 设置项 | 说明 |
|---|---|
| `Name` | 只是给你自己看的标签，填 `QCode Claude` 就够。它会成为模型选择器里的分组名 |
| `API Mode` | 决定协议和 Chatbox 追加的路径。模式选错的表现是 404，或者 Claude 模型拒绝回答 |
| `API Host` | 到版本段为止的地址：`https://api.qcode.cc/api/v1` 或 `https://api.qcode.cc/openai/v1` |
| `API Path` | Chatbox 补上的最后一段：Claude 是 `/messages`，OpenAI 是 `/chat/completions` |
| `Preview` | 只读的一行，显示由 Host 和 Path 拼出的完整 URL |
| `API Key` | `cr_` 开头的 QCode 密钥，只存在本地，显示为圆点 |
| `Model ID` | 精确的模型名，在 `Edit Model` 窗口里手填 |
| `Check` | 用你选的模型发一次测试请求，并报告 `Model Test Results` |

## 已知限制

- **自定义 Claude 地址不会自动补 `/v1`。** Chatbox 会把 `https://api.anthropic.com` 改写成带 `/v1` 的形式，但自定义地址按原样使用，只会追加 `/messages`。所以这里 QCode 的 Claude 地址是 `https://api.qcode.cc/api/v1`，而不是通用的 `https://api.qcode.cc/api`。
- **不会自动拉模型列表。** Chatbox 里的自定义服务商不拉模型列表，每个模型 ID 都要手填；刷新也不会把列表填上。
- **一个服务商一种协议。** Claude 需要 `Claude API Compatible` 服务商，GPT 和国产模型需要 `OpenAI API Compatible`；同一把密钥两边都能用。
- **不同版本的按钮名字不一样。** Chatbox 1.24.6（英文）写的是 `Model Provider`、`+ Add`、`Add Custom Provider` 和 `Check`；更早的版本可能用别的写法。

## 相关文档

- [接入点与 API 路径](/docs/getting-started/endpoints-and-api-paths)
- [工具兼容总览](/docs/ide/tool-compatibility)
- [国产模型接入](/docs/usage/cn-models)
- [订阅、官方 API 与 QCode Key](/docs/reference/subscription-vs-api-key)
- [故障排查](/docs/reference/troubleshooting)