FastGPT 接入 QCode 图文教程(Windows 11 一步一图)
跟着 11 步截图,在 Windows 11 用 Docker Desktop 装好 FastGPT 4.17.4,在「系统模型」里新增 gpt-6.2-sol、填好 QCode 的 OpenAI 兼容地址和 cr_ 密钥,并在对话 Agent 里收到第一条回复。
需要 API Key? 前往注册 →端点与 Base URL →
照着下面 11 步做,你会在自己的 Windows 11 电脑上跑起 FastGPT,把 QCode 配成模型渠道,然后在对话 Agent 里正常聊天、写知识库问答。
一句话答案:在 FastGPT 的「管理员 → 系统模型」里,先到「模型配置」新增模型 gpt-6.2-sol 并启用,再到「模型渠道」新增一个协议类型为 OpenAI 的渠道,代理地址填 https://api.qcode.cc/openai/v1,API 密钥填 cr_ 开头的那一串。
| 项 | 填写 |
|---|---|
| 协议类型 | OpenAI |
| 代理地址(Base URL) | https://api.qcode.cc/openai/v1 |
| API 密钥 | cr_xxxxxxxx |
| 模型 ID | gpt-6.2-sol |
| 渠道名称 | QCode |
核对于 2026-11-22 · FastGPT 4.17.4 · Windows 11
下载与安装¶
FastGPT 没有 Windows 桌面安装包,它是一个跑在 Docker 里的 Web 服务:装好 Docker Desktop,用官方脚本把服务跑起来,再用浏览器打开 http://localhost:3000 就是 FastGPT 的界面。所以「安装」其实是两件事:先装 Docker Desktop,再跑 FastGPT 的官方部署脚本。
先记下三个官方地址,后面对照截图会用到:
- Docker Desktop 下载页:https://www.docker.com/products/docker-desktop/(Windows 选
Docker Desktop Installer.exe) - FastGPT 官方 Docker 部署文档:https://doc.fastgpt.cn/self-host/deploy/docker
- FastGPT 官方一键部署脚本:https://doc.fastgpt.cn/deploy/install.sh(英文站镜像
https://doc.fastgpt.io/deploy/install.sh)
安装 Docker Desktop 时按向导走完、需要管理员权限、装完按提示重启电脑,第一次启动时接受协议并启用 WSL 2 后端。接着在「Windows 终端」里跑官方部署脚本,它会依次问你部署版本、镜像源、向量数据库、是否自动生成凭据、访问地址和端口——新手一路用默认值就行。脚本跑完会提示执行 docker compose pull 和 docker compose up -d,看到容器起来了,浏览器打开 http://localhost:3000 就能进 FastGPT。
硬件按官方口径准备:最低 2 核 4 GiB,推荐 2 核 8 GiB,并且要给 Docker Desktop 留足内存。整套流程不需要 OpenAI 账号,FastGPT 的管理员账号是部署时在你自己电脑上初始化的。
不同地区的网络情况不一样,先选你所在的地区:
- Docker Desktop:打开 Docker Desktop 官方下载页,按页面上的「Download Docker Desktop」展开 Windows 选项下载安装程序。下载中途变慢时耐心等一会儿,不要反复点,重复下载会让文件更慢。
- FastGPT 部署脚本:部署脚本运行时会问镜像源,选脚本里自带的中国大陆镜像源;第一次拉镜像失败就重跑一次脚本,已经拉好的镜像不会重复下载。
- 网络拦截:如果杀毒软件或防火墙弹窗询问是否允许联网,选择允许,否则容器会一直启动不起来。
- Docker Desktop:直接从官方下载页下载 Windows 安装程序即可。
- FastGPT 部署脚本:镜像源保持脚本的默认选项,脚本结束前会提示执行
docker compose pull与docker compose up -d,跟着执行就能把服务跑起来。 - 完成后:浏览器打开
http://localhost:3000,把地址收藏起来,以后每次开机先启动 Docker Desktop 再打开它。
跟着截图做:一步一图¶
下面 11 步,每步只做一件事,截图都是中文界面。图上的橙色编号和正文里的 ①②③ 一一对应,照着点就不会错。
下载 Docker Desktop 安装程序¶
先装 Docker Desktop。打开 Docker Desktop 官方下载页,点 ① 的「Download Docker Desktop」,菜单展开后选 ② 的「Download for Windows – AMD64」。页面底部如果弹出 Cookie 提示条,先点「Reject All」或「Accept All Cookies」关掉,再去点下载按钮。

做对了你会看到:浏览器开始下载一个叫 Docker Desktop Installer.exe 的安装程序,下载列表里能看到它的进度。
在终端下载并运行 FastGPT 部署脚本¶
双击装好 Docker Desktop 并重启电脑后,打开「Windows 终端」(PowerShell)。新建一个专门放 FastGPT 的文件夹,在 ① 的位置执行下载命令,把官方部署脚本 install.sh 拉到本地;接着在 ② 的位置进入 WSL 2 环境执行 bash install.sh,按提示选好版本、镜像源和端口,脚本会创建容器并启动服务。

做对了你会看到:③ 那一条检查命令输出 HTTP/1.1 200 OK,说明 FastGPT 已经在 3000 端口跑起来了。
卡住了?下载脚本时报错或一直不动
先确认 Docker Desktop 已经启动并且能正常运行 Linux 容器,再重跑一次下载命令。如果提示找不到 curl.exe,改用浏览器打开 https://doc.fastgpt.cn/deploy/install.sh,把内容另存为 install.sh 放进同一个文件夹也可以。
登录 root 管理员账号¶
打开浏览器访问 http://localhost:3000,会自动跳到 ① 的登录页;页面底部如果弹出 Cookie 提示条,先点「同意」。然后在「用户名」和「密码」两个输入框里填部署脚本给你生成的 root 管理员账号和密码,再点 ② 的「登录」。

做对了你会看到:页面跳进工作台,左侧主导航出现「门户」「工作台」「知识库」「账号」「管理员」,左下角有一个蓝色头像。
卡住了?不知道 root 密码是什么
部署脚本运行到最后会打印默认管理员账号和密码,回到第 2 步那个终端窗口往上翻一点就能看到。如果你已经把窗口关了,打开 FastGPT 部署目录里的 docker-compose.yml,里面 DEFAULT_ROOT_PSW 一项就是初始密码。
进入「系统模型」¶
登录后在页面最左侧主导航栏的底部点 ① 的「管理员」,再在展开的次级侧边栏点 ② 的「系统模型」。全新部署的实例默认停在「模型配置」页签,模型列表是空的,写着「暂无模型,请新增模型」,所以先点右上角 ③ 的「新增模型」。

做对了你会看到:「系统模型」页面顶部有「模型配置」和「模型渠道」两个页签,模型列表提示「暂无模型,请新增模型」。
卡住了?左边找不到「管理员」这一项
「管理员」在主导航栏最底部,需要 root 管理员账号登录才会出现。如果你的左侧只有「工作台」「知识库」「账号」,说明当前登录的不是管理员账号,退出后改用 root 账号登录。
新增 gpt-6.2-sol 模型并启用¶
点「新增模型」后选「从空白新建」,类型保持「语言模型(LLM)」,点「下一步」。在 ① 的位置把「模型ID」和「别名」都填成 gpt-6.2-sol;在 ② 的位置把「模型提供商」选成 OpenAI,并打开「启用」开关;最后点 ③ 的「确认」。

做对了你会看到:回到「模型配置」列表,出现一行 gpt-6.2-sol(提供商 OpenAI),最右侧「启用」开关是蓝色打开状态。
卡住了?「模型ID」该怎么填
必须和 QCode 那边的模型 ID 一模一样,填 gpt-6.2-sol,大小写和连字符都不要改,别写成 GPT-6.2-Sol,也别多打空格。别名可以随意,但建议和模型 ID 保持一致,方便后面在渠道里勾选。
切换到「模型渠道」页签¶
模型保存好以后,点「系统模型」页面顶部的 ① 「模型渠道」页签,切过去之后再点右上角 ② 的「新增渠道」。

做对了你会看到:页面切换到「模型渠道」,列表区是空的,右上角有蓝底白字的「新增渠道」按钮。
填好 QCode 渠道¶
在「新增渠道」弹窗里,先在 ① 的位置把「名称」填成 QCode,「协议类型」保持 OpenAI;再在 ② 的位置把「代理地址」填成 https://api.qcode.cc/openai/v1。接着在「API 密钥」里粘贴 cr_ 开头的密钥,在「模型」下拉里勾选 gpt-6.2-sol,最后点 ③ 的「新建」。

做对了你会看到:点「新建」后弹窗关闭,「模型渠道」列表里出现一行 QCode,协议类型是 OpenAI,模型数量是 1,操作列有三个图标。
找到渠道右侧的测试按钮¶
① 的位置就是刚建好的 QCode 渠道行,确认「启用」开关已经打开。想验证它能不能连上 QCode,点 ② 的纸飞机图标,也就是渠道测试。

做对了你会看到:渠道行里没有红色报错,鼠标移到纸飞机图标上会弹出提示,点下去能打开「渠道测试」弹窗。
批量测试模型连通性¶
在弹出的「渠道测试」窗口里点 ② 的「批量测试1个模型」,然后等几秒。① 的位置会显示 gpt-6.2-sol 的测试状态,通过之后变成绿色「成功」,后面还跟着「请求时长」。

做对了你会看到:状态列是绿色「成功」,请求时长在几秒内,没有红色失败标记。
卡住了?测试结果一直失败
按顺序核对三件事:密钥是不是完整地从控制台复制、前后有没有带空格;「代理地址」是不是 https://api.qcode.cc/openai/v1,末尾不要多写 /chat/completions;「模型」下拉里勾选的模型 ID 是不是和「模型配置」里的 gpt-6.2-sol 完全一致。三项都对上再点一次「批量测试1个模型」。
新建一个对话 Agent¶
先点「取消」关掉测试窗口,再点左侧主导航的「工作台」。在空工作台中间点「创建你的第一个 Agent」,类型选 ① 的「对话 Agent」,在 ② 的名称框里填 QCode 对话测试,最后点 ③ 的「创建」。

做对了你会看到:页面直接进入应用编排页,左侧「AI 配置 → AI 模型」里已经默认选中 gpt-6.2-sol,右侧是「调试预览」。
发一句话验证回复¶
① 的位置确认「AI 模型」选中的是 gpt-6.2-sol。接着在右侧「调试预览」底部的输入框里发一句「你好,用一句话介绍你自己」,稍等几秒,② 的位置就会出现中文回复气泡。

做对了你会看到:右侧出现一整段通顺的中文回答,气泡下方标着耗时,还能展开「运行详情」。
卡住了?发出去没有回复,或者提示模型不可用
先回「模型渠道」再点一次纸飞机做渠道测试,确认 gpt-6.2-sol 仍是绿色「成功」;如果测试失败,基本就是密钥或代理地址的问题。另外确认这个应用里选中的模型名和「模型配置」里的模型 ID 完全一致。
验证成功¶
四件事都对上,就说明 FastGPT 已经接通 QCode:
- 「模型渠道」里能看到
QCode这一行,测试结果显示绿色「成功」; - 「模型配置」里的
gpt-6.2-sol处于启用状态; - 对话 Agent 里选中该模型后能收到正常中文回复,不是
401、404或模型不存在; - 关掉 Docker Desktop 再重新启动、执行
docker compose up -d之后,渠道和模型配置还在(数据存在 Docker 数据卷里)。
全部完成¶
你已经在 Windows 11 上跑起了 FastGPT,并且用 QCode 的 OpenAI 兼容接口把它接通了。接下来可以:
- 接入点与 API 格式
- 国产模型接入
- 计费说明
- 接下来:在定价页比较各个方案
- 回到控制台查看用量和余额
常见报错¶
| 报错原文 | 原因 | 怎么办 |
|---|---|---|
401 |
密钥没粘全、末尾带了空格或引号,或者这把密钥已经失效 | 回控制台重新复制 cr_ 开头的那一整串,粘进「API 密钥」后先点空白处再保存;同时确认「代理地址」是 https://api.qcode.cc/openai/v1 |
404 |
「代理地址」填成了完整的请求地址,多写了 /chat/completions,或者漏了 /v1 |
渠道里的「代理地址」只填 https://api.qcode.cc/openai/v1;只有单个模型页里的「自定义请求地址」才需要填完整的 https://api.qcode.cc/openai/v1/chat/completions |
模型不存在 |
渠道里勾选的模型和「模型配置」里的模型 ID 不一致,或者该模型没有启用 | 到「模型配置」核对模型 ID 与 gpt-6.2-sol 完全一致并打开「启用」,再回「模型渠道」重新勾选这个模型 |
提示 WSL 2 未安装 |
Windows 还没装 WSL 2,或者 Docker Desktop 没有启用 WSL 2 后端 | 用管理员身份打开 PowerShell 执行 wsl --install 后重启电脑,再在 Docker Desktop 的设置里确认已启用 WSL 2 后端 |
暂无模型,请新增模型 |
全新部署的 FastGPT 没有预置模型,「模型渠道」里「模型」下拉是空的 | 先到「模型配置」新增 gpt-6.2-sol 并启用(本文第 4、5 步),再回「模型渠道」新增渠道勾选它 |
常见问题¶
密钥到期后怎么办?¶
分两种情况:
- 个人套餐的密钥到期后不能续,只能重新开通、换一把新密钥;
- 按量包的密钥到期后再买一个包,同一把密钥会自动恢复。
换了新密钥之后,到「模型渠道」里点齿轮图标编辑 QCode 那一行,把「API 密钥」换成新的,再点一次纸飞机做渠道测试。
3000 端口被占用,页面打不开怎么办?¶
部署脚本会问你宿主端口,遇到占用就换一个(例如 3001),脚本跑完后浏览器改成 http://localhost:3001。也可以在任务管理器里关掉占用 3000 端口的程序,再重新执行 docker compose up -d。
「模型」下拉里找不到 gpt-6.2-sol 怎么办?¶
说明「模型配置」里还没有这个模型。先到「管理员 → 系统模型 → 模型配置」用「新增模型 → 从空白新建」加上它,模型 ID 必须是 gpt-6.2-sol 并处于启用状态,然后回「模型渠道」重新打开新增渠道弹窗,下拉里就能勾选了。
想用 Claude 模型可以吗?¶
QCode 的 Claude 系列默认推荐 claude-opus-5-5,轻量场景可以用 claude-haiku-5-5,它们走的是 Anthropic 兼容端点和 OpenAI 兼容端点不同的地址。本篇的 FastGPT 自托管走的是 OpenAI 兼容协议,所以主线用 gpt-6.2-sol;协议与模型的对应关系以接入点与 API 格式为准。
界面语言怎么切换?¶
登录页右上角有语言下拉按钮,可以直接选「简体中文」。登录之后则到左侧主导航「账号」→「语言与时区」里切换。
重启电脑后 FastGPT 还在吗?¶
在。数据放在 Docker 数据卷里,重启后先启动 Docker Desktop,再到部署目录执行 docker compose up -d,然后打开 http://localhost:3000,模型、渠道和 Agent 都还在。
内存不够、容器反复重启怎么办?¶
官方口径是最低 2 核 4 GiB、推荐 2 核 8 GiB。可以在 Docker Desktop 的设置里调大内存上限,同时关掉其他占内存的容器和程序,再重新 docker compose up -d。
接入速览¶
| 项目 | 说明 |
|---|---|
| 接入方式 | 「管理员 → 系统模型 → 模型渠道 → 新增渠道」,协议类型选 OpenAI |
| 代理地址 | https://api.qcode.cc/openai/v1(不带 /chat/completions) |
| 推荐模型 | gpt-6.2-sol(OpenAI 兼容协议下的默认推荐) |
| 密钥格式 | cr_ 开头,例如 cr_xxxxxxxx |
| 数据存放 | Docker 数据卷,重启容器后配置不丢 |
其他接入点¶
三个接入域的业务能力相同,只是网络路由不同,同一把密钥都能用。默认用 https://api.qcode.cc/openai/v1;如果所在网络到默认地址不稳,可以把「代理地址」换成亚洲节点 https://asia.qcode.cc/openai/v1 或北美节点 https://us.qcode.cc/openai/v1,改完点一次纸飞机重新做渠道测试。
可用模型¶
| 模型 | 模型 ID(填到「模型配置」里) | 说明 |
|---|---|---|
| GPT 6.2 Sol | gpt-6.2-sol |
默认推荐,对话、知识库问答都够用 |
| GPT 6.2 Astra | gpt-6.2-astra |
最高阶备选,复杂推理更稳,消耗更高 |
| Claude Opus 5.5 | claude-opus-5-5 |
Claude 系列默认推荐,走 Anthropic 兼容端点 |
| Claude Haiku 5.5 | claude-haiku-5-5 |
Claude 轻量备选,响应快、消耗低 |
本文主线只用到 gpt-6.2-sol;想换模型,先在「模型配置」里新增对应模型 ID 并启用,再去渠道里勾选。国产模型的完整模型 ID 见国产模型接入。
进阶:模型映射与自定义请求地址¶
渠道弹窗里还有两个字段,新手可以先留空,需要时再看:
- 模型映射(默认
{}):把 FastGPT 里的模型名映射到 QCode 的模型 ID。只有在同一个渠道里想用别的名字调用同一个模型时才需要填,例如把my-gpt映射到gpt-6.2-sol。 - 自定义请求地址:这是单个模型级别的覆盖项,和渠道里的「代理地址」不是一回事。渠道的「代理地址」只填 Base URL(
https://api.qcode.cc/openai/v1);如果改用单个模型的「自定义请求地址」,则必须填完整路径https://api.qcode.cc/openai/v1/chat/completions,Key 填cr_开头的那一串。
两者的区别一句话记住:渠道填到 /v1 为止,自定义请求地址要填到 /chat/completions。
相关文档¶
- 接入点与 API 格式 — 协议 × 模型家族的对应关系
- 国产模型接入 — 国产模型 ID 清单
- 计费说明 — 用量怎么算
- 故障排查 — 连接类问题排查清单
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models