FastGPT 接入 QCode 图文教程(Windows 11 一步一图)

跟着 11 步截图,在 Windows 11 用 Docker Desktop 装好 FastGPT 4.17.4,在「系统模型」里新增 gpt-6.2-sol、填好 QCode 的 OpenAI 兼容地址和 cr_ 密钥,并在对话 Agent 里收到第一条回复。

更新于 2026-11-23

需要 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

  • 适用系统:Windows 10 / 11(64 位)
  • 软件版本:FastGPT 4.17.4(自托管 Web 服务,跑在 Docker Desktop 里)
  • 截图更新于:2026-11
  • 预计用时:30 分钟(首次拉取镜像比较慢,看网速)
  • 需要准备:一个 cr_ 开头的 QCode API 密钥;能访问 docker.com 与 api.qcode.cc 的网络;内存 8 GiB 更稳妥
  • 电脑是 Windows 10 / 11(64 位),BIOS 或 UEFI 里已经开启虚拟化,磁盘至少留出 10 GiB
  • 已经装好或准备安装 Docker Desktop(WSL 2 后端),能打开「Windows 终端」
  • 已经在控制台复制好 cr_ 开头的 QCode API 密钥。还没有账号?先注册 QCode,在定价页选一个方案,再到控制台创建密钥。
  • 电脑能正常打开 docker.com、doc.fastgpt.cn 和 api.qcode.cc,并且留出约 30 分钟不被打断的时间

下载与安装

FastGPT 没有 Windows 桌面安装包,它是一个跑在 Docker 里的 Web 服务:装好 Docker Desktop,用官方脚本把服务跑起来,再用浏览器打开 http://localhost:3000 就是 FastGPT 的界面。所以「安装」其实是两件事:先装 Docker Desktop,再跑 FastGPT 的官方部署脚本。

先记下三个官方地址,后面对照截图会用到:

安装 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 官方下载页:蓝色「Download Docker Desktop」按钮(1)展开后出现平台菜单,其中 Windows 选项为「Download for Windows – AMD64」(2)

做对了你会看到:浏览器开始下载一个叫 Docker Desktop Installer.exe 的安装程序,下载列表里能看到它的进度。

在终端下载并运行 FastGPT 部署脚本

双击装好 Docker Desktop 并重启电脑后,打开「Windows 终端」(PowerShell)。新建一个专门放 FastGPT 的文件夹,在 ① 的位置执行下载命令,把官方部署脚本 install.sh 拉到本地;接着在 ② 的位置进入 WSL 2 环境执行 bash install.sh,按提示选好版本、镜像源和端口,脚本会创建容器并启动服务。

Windows 终端(PowerShell)窗口:curl.exe 下载 FastGPT 官方 install.sh 脚本并列出文件名(1),注释行给出在 WSL 2 与 Docker Desktop 中执行 bash install.sh 和 docker compose up -d 的步骤(2),最后一条命令验证 localhost:3000/login 返回 HTTP/1.1 200 OK(3)

做对了你会看到:③ 那一条检查命令输出 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 管理员账号和密码,再点 ② 的「登录」。

FastGPT 登录页(1):只有「用户名」「密码」两个输入框和蓝色「登录」按钮(2),右上角可以直接切换界面语言,输入框内容已打码

做对了你会看到:页面跳进工作台,左侧主导航出现「门户」「工作台」「知识库」「账号」「管理员」,左下角有一个蓝色头像。

卡住了?不知道 root 密码是什么

部署脚本运行到最后会打印默认管理员账号和密码,回到第 2 步那个终端窗口往上翻一点就能看到。如果你已经把窗口关了,打开 FastGPT 部署目录里的 docker-compose.yml,里面 DEFAULT_ROOT_PSW 一项就是初始密码。

进入「系统模型」

登录后在页面最左侧主导航栏的底部点 ① 的「管理员」,再在展开的次级侧边栏点 ② 的「系统模型」。全新部署的实例默认停在「模型配置」页签,模型列表是空的,写着「暂无模型,请新增模型」,所以先点右上角 ③ 的「新增模型」。

FastGPT 管理后台:左侧主导航底部的「管理员」(1)、次级侧边栏「系统模型」(2),以及右上角「新增模型」按钮(3),中间是空的模型配置列表

做对了你会看到:「系统模型」页面顶部有「模型配置」和「模型渠道」两个页签,模型列表提示「暂无模型,请新增模型」。

卡住了?左边找不到「管理员」这一项

「管理员」在主导航栏最底部,需要 root 管理员账号登录才会出现。如果你的左侧只有「工作台」「知识库」「账号」,说明当前登录的不是管理员账号,退出后改用 root 账号登录。

新增 gpt-6.2-sol 模型并启用

点「新增模型」后选「从空白新建」,类型保持「语言模型(LLM)」,点「下一步」。在 ① 的位置把「模型ID」和「别名」都填成 gpt-6.2-sol;在 ② 的位置把「模型提供商」选成 OpenAI,并打开「启用」开关;最后点 ③ 的「确认」。

FastGPT「新增模型」表单:模型ID 与别名都填 gpt-6.2-sol(1),模型提供商选 OpenAI 且「启用」开关已打开(2),底部「确认」按钮(3)

做对了你会看到:回到「模型配置」列表,出现一行 gpt-6.2-sol(提供商 OpenAI),最右侧「启用」开关是蓝色打开状态。

卡住了?「模型ID」该怎么填

必须和 QCode 那边的模型 ID 一模一样,填 gpt-6.2-sol,大小写和连字符都不要改,别写成 GPT-6.2-Sol,也别多打空格。别名可以随意,但建议和模型 ID 保持一致,方便后面在渠道里勾选。

切换到「模型渠道」页签

模型保存好以后,点「系统模型」页面顶部的 ① 「模型渠道」页签,切过去之后再点右上角 ② 的「新增渠道」。

FastGPT「系统模型」页面顶部切到「模型渠道」页签(1),右上角出现「新增渠道」按钮(2),此时渠道列表还是空的

做对了你会看到:页面切换到「模型渠道」,列表区是空的,右上角有蓝底白字的「新增渠道」按钮。

填好 QCode 渠道

在「新增渠道」弹窗里,先在 ① 的位置把「名称」填成 QCode,「协议类型」保持 OpenAI;再在 ② 的位置把「代理地址」填成 https://api.qcode.cc/openai/v1。接着在「API 密钥」里粘贴 cr_ 开头的密钥,在「模型」下拉里勾选 gpt-6.2-sol,最后点 ③ 的「新建」。

FastGPT「新增渠道」弹窗:名称 QCode 与协议类型 OpenAI(1)、代理地址 https://api.qcode.cc/openai/v1(2)、底部「新建」按钮(3),API 密钥一行已打码

需要 API Key?

还没有 QCode 账号的话,先注册 QCode。想按用量付费,可以先买一个按量包,再到控制台创建密钥。复制 cr_ 开头的那一整串,粘到弹窗里的「API 密钥」中即可。

做对了你会看到:点「新建」后弹窗关闭,「模型渠道」列表里出现一行 QCode,协议类型是 OpenAI,模型数量是 1,操作列有三个图标。

找到渠道右侧的测试按钮

① 的位置就是刚建好的 QCode 渠道行,确认「启用」开关已经打开。想验证它能不能连上 QCode,点 ② 的纸飞机图标,也就是渠道测试。

FastGPT「模型渠道」列表里新增的 QCode 渠道行:协议类型 OpenAI、模型数量 1、启用开关已打开(1),右侧操作列的纸飞机图标(2)用于打开渠道测试

做对了你会看到:渠道行里没有红色报错,鼠标移到纸飞机图标上会弹出提示,点下去能打开「渠道测试」弹窗。

批量测试模型连通性

在弹出的「渠道测试」窗口里点 ② 的「批量测试1个模型」,然后等几秒。① 的位置会显示 gpt-6.2-sol 的测试状态,通过之后变成绿色「成功」,后面还跟着「请求时长」。

FastGPT「渠道测试」弹窗:gpt-6.2-sol 一行显示绿色「成功」徽章与请求时长(1),右下角「批量测试1个模型」按钮(2)

做对了你会看到:状态列是绿色「成功」,请求时长在几秒内,没有红色失败标记。

卡住了?测试结果一直失败

按顺序核对三件事:密钥是不是完整地从控制台复制、前后有没有带空格;「代理地址」是不是 https://api.qcode.cc/openai/v1,末尾不要多写 /chat/completions;「模型」下拉里勾选的模型 ID 是不是和「模型配置」里的 gpt-6.2-sol 完全一致。三项都对上再点一次「批量测试1个模型」。

新建一个对话 Agent

先点「取消」关掉测试窗口,再点左侧主导航的「工作台」。在空工作台中间点「创建你的第一个 Agent」,类型选 ① 的「对话 Agent」,在 ② 的名称框里填 QCode 对话测试,最后点 ③ 的「创建」。

FastGPT「创建 Agent」页面:类型卡片选中「对话 Agent」(1),名称输入框已填 QCode 对话测试(2),右侧「创建」按钮(3)

做对了你会看到:页面直接进入应用编排页,左侧「AI 配置 → AI 模型」里已经默认选中 gpt-6.2-sol,右侧是「调试预览」。

发一句话验证回复

① 的位置确认「AI 模型」选中的是 gpt-6.2-sol。接着在右侧「调试预览」底部的输入框里发一句「你好,用一句话介绍你自己」,稍等几秒,② 的位置就会出现中文回复气泡。

FastGPT 应用编排页:左栏「AI 模型」已选中 gpt-6.2-sol(1),右侧「调试预览」里发出「你好,用一句话介绍你自己」并收到中文回复,下方带耗时(2)

做对了你会看到:右侧出现一整段通顺的中文回答,气泡下方标着耗时,还能展开「运行详情」。

卡住了?发出去没有回复,或者提示模型不可用

先回「模型渠道」再点一次纸飞机做渠道测试,确认 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 兼容接口把它接通了。接下来可以:

常见报错

报错原文 原因 怎么办
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。

相关文档

开始使用 QCode

一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models

企业团队版 →