Chatbox 接入 QCode:Windows 图文教程(21 张截图)
在 Windows 的 Chatbox 里新建自定义服务商,把 Claude API Host 填成 https://api.qcode.cc/api/v1,贴 cr_ 密钥、手填模型 ID claude-sonnet-5,21 张截图带你走通安装、配置和首条回复,附报错对照。
需要 API Key? 前往注册 →端点与 Base URL →
一句话答案:在 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 账号。
开始第一张截图之前,先确认这几件事:
下载与安装 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,比官网的安装包旧,所以优先用下载页。

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

做对了你会看到:浏览器开始下载一个叫 Chatbox-1.24.6-Setup.exe 的文件,约 230 MiB。文件名里的版本号以后会变。
确认安装包下载完了¶
打开浏览器的下载面板。① 那条记录是下完的安装包,显示着完整大小。

做对了你会看到:① 只有一条已完成的记录,名字是 Chatbox-1.24.6-Setup.exe,后面没有进度条。如果记录以 .crdownload 结尾,说明还在下载 —— 等它变成 .exe 的名字。
选择给谁安装¶
双击下载好的文件。向导第一屏选 ① Only for me (user)(仅为我安装),再点 ② Next >(下一步)。

卡住了?Windows 弹出管理员密码框
选中 Only for me (user) 时,安装包只会写进你自己的 AppData 目录,不需要管理员权限。如果弹出密码框,取消它再重新运行安装包 —— 第一屏必须是 Only for me (user) 处于选中状态。
做对了你会看到:① Only for me (user) 被勾上,向导翻到 Choose Install Location(选择安装位置)。
保持默认安装目录¶
第二屏显示软件装到哪里,默认就在你自己的 AppData 目录下。不用改,直接点 ① Install(安装)。

做对了你会看到:按钮消失,窗口换成 Please wait while Chatbox is being installed.(正在安装 Chatbox,请稍候)。
等进度条走完¶
这一步不用点任何东西。普通电脑上进度条约 20 秒走完。

做对了你会看到:进度条走到头,窗口自己翻到 Completing Chatbox Setup(正在完成 Chatbox 安装)。
跳过欢迎页¶
第一次启动会打开欢迎页。不需要账号:不用管 ① I'm new to this(我是新手),直接点右边的 ② Skip guide(跳过引导)。

卡住了?欢迎页上没有 Skip guide
确认你装的是 1.24.6 或更新的版本:欢迎页底部有两张卡片,I'm new to this 和 Skip guide。两张都看不到,说明安装包还没跑完 —— 回到安装向导最后一屏点 Finish。
做对了你会看到:欢迎页关掉,进到主界面 —— 左边是会话列表,底部是消息输入框,没有登录提示。
打开 Settings → Model Provider¶
点主窗口左下角的 Settings(设置)。在设置页左栏点 ① Model Provider(模型服务商),服务商列表就会打开。添加自己服务商的按钮在列表最后一行:② + Add(+ 添加)。

卡住了?左栏里没有 Model Provider
在 Chatbox 1.24.6 里,这一项就在设置页的左栏。找不到的话,先确认你在设置页而不是某个会话里:点主窗口左下角的 Settings,再顺着左栏往下找列出 OpenAI、Claude、Gemini 这些服务商的那一页。
做对了你会看到:① Model Provider 在左栏呈选中状态,中间是一列服务商,② + Add 就在这一列的最后一行。
打开自定义服务商表单¶
点 + Add。会打开一个内置服务商目录,在搜索框里输入 custom,然后点 ① Add Custom Provider(添加自定义服务商)。

做对了你会看到:弹出一个标题为 Add provider(添加服务商)的窗口,里面有两个字段:Name 和 API Mode。
选择 Claude 接口模式¶
展开 ① API Mode(接口模式)下拉,选 Claude API Compatible(兼容 Claude API)。这一步决定 Chatbox 用 Claude 协议说话,后面几步的地址字段都跟着它走。

做对了你会看到:① API Mode 那一栏现在写着 Claude API Compatible。
给服务商起个名字¶
在 ① Name(名称)里填 QCode Claude。② API Mode 保持 Claude API Compatible,然后点 Add(添加)。

做对了你会看到:窗口关掉,打开新服务商的页面,上面有 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。

卡住了?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 控制台复制的密钥粘进去。输入框只显示一排圆点 —— 这是正常的,密钥照你输入的内容保存。

做对了你会看到:输入框里是一排圆点,灰色占位提示已经消失。如果框里还是空的,先点一下输入框,等半秒再粘一次 —— 密钥前后不要带空格。
添加模型 ID¶
点 + New(+ 新建)。在 Edit Model(编辑模型)窗口里把 ① claude-sonnet-5 填进 Model ID(模型 ID),再点 ② Save(保存)。Chatbox 不会去拉 QCode 的模型列表,所以 ID 要手填。

卡住了?刷新以后模型列表还是空的
Chatbox 里自定义的 Claude 兼容服务商不会拉取模型列表,所以什么都不会自动出现。手动把 ID 加进去,例如 claude-sonnet-5、claude-opus-5-5 或 claude-haiku-5-5;能用的 ID 都列在 qcode.cc/models。照抄 ID,连字符别丢。
做对了你会看到:claude-sonnet-5 成为 QCode Claude 服务商模型列表里的一行。
检查连接¶
点 Check(检查)。它问要测哪个模型时,选 claude-sonnet-5。① Model Test Results(模型测试结果)随后显示 Connection successful(连接成功),文本、视觉和工具调用三项都打勾。

卡住了?检查报错
先核对两个字段: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。

做对了你会看到:右下角的模型选择器现在显示 claude-sonnet-5,而不是 Chatbox 自带的某个模型。
发第一条消息¶
点消息输入框,输入 Say hello in one short sentence,按回车。① 是你在会话里发的那条消息。

卡住了?回复不是文字,而是一条红色报错
打开模型选择器,确认模型是 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?,按回车。① 是这句追问;② 是模型对它的回答。

做对了你会看到:模型会回头引用它上一轮说过的话,说明会话保留了上下文。
验证成功¶
下面四条全部对上,就说明配好了:
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 在聊天窗口里能正常回答了。接下来可以:
- 在定价页比较各个方案,挑一个适合长期用的
- 回到控制台查看用量和余额
- 接入点与 API 路径
- 国产模型接入
- 故障排查
常见报错¶
| 报错原文 | 原因 | 怎么办 |
|---|---|---|
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。照抄 ID,连字符别丢。
同一个应用里能用 GPT 模型吗?¶
可以。再建一个服务商,API Mode 选 OpenAI API Compatible,API Host 填 https://api.qcode.cc/openai/v1,用同一把 cr_ 密钥,模型 ID 填 gpt-6.2-sol。下面那节可选内容会把这一步走一遍。切换模型用模型选择器,每个服务商各自维护自己的模型列表。
密钥到期了,还能续吗?¶
要看这把密钥是从哪来的。包月个人套餐的密钥到期后不能续:重新开一个套餐,在控制台创建一把新密钥,再把新的 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;③ 是它出现在模型列表里的样子。

卡住了?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 出来。

做对了你会看到:① 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;更早的版本可能用别的写法。
相关文档¶
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models
