# FastGPT 接入 QCode：Windows 11 图文教程

照着下面 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 终端」
- 已经在[控制台](https://qcode.cc/dashboard)复制好 `cr_` 开头的 QCode API 密钥。还没有账号？先[注册 QCode](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-fastgpt-before)，在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-fastgpt-before)选一个方案，再到[控制台](https://qcode.cc/dashboard)创建密钥。
- 电脑能正常打开 docker.com、doc.fastgpt.cn 和 api.qcode.cc，并且留出约 30 分钟不被打断的时间


## 下载与安装

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 官方下载页：蓝色「Download Docker Desktop」按钮（1）展开后出现平台菜单，其中 Windows 选项为「Download for Windows – AMD64」（2）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/01-docker-desktop-download.webp)


做对了你会看到：浏览器开始下载一个叫 `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）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/02-fastgpt-deploy-cmd.webp)


做对了你会看到：③ 那一条检查命令输出 `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），右上角可以直接切换界面语言，输入框内容已打码](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/03-fastgpt-login.webp)


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


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

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




### 进入「系统模型」

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

![FastGPT 管理后台：左侧主导航底部的「管理员」（1）、次级侧边栏「系统模型」（2），以及右上角「新增模型」按钮（3），中间是空的模型配置列表](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/04-admin-model-config.webp)


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


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

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




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

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

![FastGPT「新增模型」表单：模型ID 与别名都填 gpt-6.2-sol（1），模型提供商选 OpenAI 且「启用」开关已打开（2），底部「确认」按钮（3）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/05-add-custom-model.webp)


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


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

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




### 切换到「模型渠道」页签

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

![FastGPT「系统模型」页面顶部切到「模型渠道」页签（1），右上角出现「新增渠道」按钮（2），此时渠道列表还是空的](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/06-model-channels-tab.webp)


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




### 填好 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 密钥一行已打码](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/07-add-channel-form.webp)

**需要 API Key？**

还没有 QCode 账号的话，先[注册 QCode](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-fastgpt-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-fastgpt-key)，再到[控制台](https://qcode.cc/dashboard)创建密钥。复制 `cr_` 开头的那一整串，粘到弹窗里的「API 密钥」中即可。



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




### 找到渠道右侧的测试按钮

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

![FastGPT「模型渠道」列表里新增的 QCode 渠道行：协议类型 OpenAI、模型数量 1、启用开关已打开（1），右侧操作列的纸飞机图标（2）用于打开渠道测试](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/08-channel-created.webp)


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




### 批量测试模型连通性

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

![FastGPT「渠道测试」弹窗：gpt-6.2-sol 一行显示绿色「成功」徽章与请求时长（1），右下角「批量测试1个模型」按钮（2）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/09-channel-test-success.webp)


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


**卡住了？测试结果一直失败**

按顺序核对三件事：密钥是不是完整地从控制台复制、前后有没有带空格；「代理地址」是不是 `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）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/10-create-chat-agent.webp)


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




### 发一句话验证回复

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

![FastGPT 应用编排页：左栏「AI 模型」已选中 gpt-6.2-sol（1），右侧「调试预览」里发出「你好，用一句话介绍你自己」并收到中文回复，下方带耗时（2）](https://docs.qcode.cc/static/images/tut/fastgpt/202611/zh/11-agent-chat-reply.webp)


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


**卡住了？发出去没有回复，或者提示模型不可用**

先回「模型渠道」再点一次纸飞机做渠道测试，确认 `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 格式](/docs/getting-started/endpoints-and-api-paths)
- [国产模型接入](/docs/usage/cn-models)
- [计费说明](/docs/reference/billing)
- 接下来：在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-fastgpt-done)比较各个方案
- 回到[控制台](https://qcode.cc/dashboard)查看用量和余额


## 常见报错

| 报错原文 | 原因 | 怎么办 |
|---|---|---|
| `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 格式](/docs/getting-started/endpoints-and-api-paths)为准。

### 界面语言怎么切换？

登录页右上角有语言下拉按钮，可以直接选「简体中文」。登录之后则到左侧主导航「账号」→「语言与时区」里切换。

### 重启电脑后 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 见[国产模型接入](/docs/usage/cn-models)。

## 进阶：模型映射与自定义请求地址

渠道弹窗里还有两个字段，新手可以先留空，需要时再看：

- **模型映射**（默认 `{}`）：把 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 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族的对应关系
- [国产模型接入](/docs/usage/cn-models) — 国产模型 ID 清单
- [计费说明](/docs/reference/billing) — 用量怎么算
- [故障排查](/docs/reference/troubleshooting) — 连接类问题排查清单