Dify 在 Windows 11 上自托管:一步步接入 QCode(13 张截图)
在 Windows 11 上用 Docker Desktop 跑起 Dify,并把 QCode 接成 OpenAI 兼容模型:13 张带编号的截图,从安装到收到第一条回复。
需要 API Key? 前往注册 →端点与 Base URL →
一句话答案:在 Dify 里打开 Integrations → Model Provider,安装 OpenAI-API-compatible 插件,然后点 Add Model,填入接入地址 https://api.qcode.cc/openai/v1、模型名 gpt-6.2-sol、你的 cr_ 密钥,补全模式选 Chat。
| 项目 | 填写 |
|---|---|
| 要安装的集成 | OpenAI-API-compatible |
| API Base URL | https://api.qcode.cc/openai/v1 |
| 模型名(Model Name) | gpt-6.2-sol |
| 模型类型 / 补全模式 | LLM / Chat |
| API 密钥 | cr_xxxxxxxx |
核对于 2026-11-22 · Dify 1.20.0 · Windows 11
照着下面 13 张截图在 Windows 11 电脑上做一遍,最后你就能在 Dify 里用上 QCode:Studio 里有一个 Chatbot 应用,能回答你的第一条消息。Dify 本身不需要任何模型厂商账号 —— 这里唯一的凭证就是一把 QCode API 密钥。
在开始第一张截图之前,先确认你已经具备这些:
- 一台 64 位、能上网打开网页的 Windows 10 或 11 电脑,至少给 Docker 留出 2 个 CPU 核心和 4 GiB 内存
- 一个浏览器 —— Edge 或 Chrome —— 因为 Dify 没有桌面应用;整个教程都在浏览器标签页里完成
- 一个能登录的 Dify 实例:你自己在
http://localhost:8080上用 Docker Compose 部署的那一个,或者 cloud.dify.ai 上的 Dify Cloud - 从控制台复制好的 QCode API 密钥(
cr_xxxxxxxx);这是唯一不能跳过的一项。还没有账号?先注册,在定价页选一个方案,再到控制台创建密钥。
下载与安装 Dify¶
Dify 是 Web 服务,所以 Dify 界面没有 Windows 安装包。你要么在浏览器里打开 Dify Cloud,要么用 Docker Compose 在本机跑同一套界面。两条路最后都会落到下面步骤用的同一个 Model Provider 页面。按你所在的位置选对应的标签页:
打开 dify.ai 走 Cloud 路线:界面就在 cloud.dify.ai,电脑上什么都不用装。
如果想把界面放在自己机器上,就打开 docs.dify.ai 上的官方 Docker Compose 指南,配合 Docker Desktop 照着做。先从 docker.com 装好 Docker Desktop。如果页面加载慢或者下载卡住,等一分钟再重新开始 —— 页面和安装包由同一个主机提供,过一会儿重试通常两个问题都解决了。
打开 dify.ai 走 Cloud 路线:在 cloud.dify.ai 注册,整个教程都在浏览器里完成。
要做本地部署,就打开 docs.dify.ai 上的官方 Docker Compose 指南,从 docker.com 安装 Docker Desktop(Windows,x64),接受协议并保持 Use WSL 2 后端。安装程序需要管理员权限,通常还会要求重启。这个指南的仓库里也有 GitHub Releases,其中 Windows 文件 difyctl-v1.20.0-windows-x64.exe 是给管理员用的命令行工具 —— 它不是 Dify 界面,所以别指望双击后会开窗口。docker compose up -d 之后,界面在 http://localhost:8080。
先看一遍系统需求页¶
在下载任何东西之前,先打开官方的 Docker Compose 指南。① 页面标题确认你打开的就是 Docker Compose 自托管页;② 先决条件区块列出了这台机器必须具备的条件:至少 2 个 CPU 核心、4 GiB 内存,以及 Docker Compose 本身。

做对了你会看到:① Docker Compose 安装页的标题,② 先决条件列表里 CPU、内存和 Docker Compose 那几行能在一屏内看清。
卡住了?页面显示的是别的安装方式
Dify 把 Docker Compose 和 Kubernetes 并列写在文档里,搜索结果有时会落到 Kubernetes 那一页。滚到页面顶部,确认地址里带 docker-compose,那才是本教程要走的路线。
安装 Docker Desktop¶
Dify 在 Windows 上跑在容器里,所以要先装 Docker Desktop。在 docker.com 上点 ① Download Docker Desktop,运行下载下来的 Docker Desktop Installer.exe,接受协议,并保持选中 Use WSL 2 后端。安装程序会请求管理员权限,通常还会提示重启,照做即可。

做对了你会看到:下载从 ① 的按钮开始;装好之后通知区域出现鲸鱼图标,状态是 Engine running。
卡住了?Windows 弹出“Windows 已保护你的电脑”
点 More info,再点 Run anyway。SmartScreen 对那些它见得不够多的安装包会弹这个框;这个文件就是刚才 ① 按钮下载下来的。
登录你的 Dify 实例¶
在浏览器里打开 http://localhost:8080。第一次访问会跳到 /install 页面,用邮箱和密码创建管理员账号;之后再访问就直接进登录页。在 ① 里填邮箱和密码,然后点 ② Sign in。

做对了你会看到:① 两个输入框都填好了,密码显示为一串圆点;② Sign in 变成蓝色;点下去之后进入 Dify 首页,左上角显示工作区名称。
卡住了?浏览器提示无法访问此网站
容器还没起来。打开 Docker Desktop,等状态变成 Engine running,然后在 Dify 源码目录里执行 docker compose up -d,再刷新页面。第一次启动要拉好几个镜像,会慢一会儿。
打开 Integrations¶
登录之后进入 Dify 首页。整套导航都在左侧一列自上而下排列:Home、Studio、Agents、Knowledge、Contacts、Skills、Integrations、Marketplace。点 ① Integrations,Dify 会直接带你进 Model Provider。

做对了你会看到:① 左侧的 Integrations 高亮,后面的页面标题是 Model Provider,顶部有一个 Search models... 搜索框。
搜索 OpenAI-API-compatible 提供商¶
Model Provider 列出了 Dify 能对接的所有集成。点 ① Search models... 搜索框,输入 OpenAI-API-compatible。② 匹配的卡片会出现在列表里,上面有蓝色的 Install 按钮。

做对了你会看到:① 搜索框里是你的文字,② 一张名为 OpenAI-API-compatible 的卡片和它的 Install 按钮 —— 不是 OpenAI,那是另一个插件。
卡住了?搜索没有任何结果
只输入 OpenAI,再把列表往下滚。安装插件需要工作区拥有者或管理员权限,普通成员账号可能看得到卡片却没有 Install 按钮。装完之后先刷新页面,再重新搜索。
确认安装插件¶
在卡片上点 Install 不会立刻安装,而是弹出标题为 Install Integration 的对话框。核对对话框里的名字,然后点对话框底部 ① Install。Dify 随后会从它的 Marketplace 下载插件,需要几秒钟。

做对了你会看到:① 对话框自己关闭,OpenAI-API-compatible 卡片移动到 Configuration required 分组里。
卡住了?对话框一直转圈然后失败
插件是从 marketplace.dify.ai 拉的。换个标签页打开这个地址看看通不通;在公司网络或代理后面下载可能被拦掉,换一个网络重试通常就好了。
打开 Add model 对话框¶
装好的插件现在位于 Configuration required 下面,并带一行说明 Set up api-key or add model to use。点这张卡片右侧的 ① Add Model,QCode 的地址和密钥就是在这里填。

做对了你会看到:① Add Model,点开后是一个名为 Add model 的对话框,上面有 Model Name、Model Type 和 API Key。
填模型名并选类型¶
在 ① Model Name 里输入 gpt-6.2-sol —— 这是 QCode 的模型 ID,必须一字不差地照抄。打开 ② Model Type 选 LLM。然后点 API Key 输入框,把 cr_ 开头的密钥粘贴进去;对话框会用圆点把它遮住。

需要 API Key?
还没有 QCode 账号的话,先注册。不想买月付套餐的话,先在按量包页面买一个包,然后到控制台创建密钥。把 cr_ 开头那一整串复制回来,粘到 cr_xxxxxxxx 的位置即可。
做对了你会看到:① gpt-6.2-sol 一字不差,② 类型字段是 LLM,API Key 里是一行圆点 —— 都不带引号。
填 QCode 的接入地址和补全模式¶
在对话框里往下滚。把 https://api.qcode.cc/openai/v1 填进 ① API Base URL —— 整条路径都要写进这个字段,包括 /openai/v1,末尾不带斜杠,也不要加 /chat/completions。② Completion mode 保持 Chat,然后点 ③ Add 保存并校验密钥。

做对了你会看到:① 地址以 /openai/v1 结尾,② 选中了 Chat,③ Add 关闭对话框而且没有红色报错行。
卡住了?保存时报 401 或 404
401 说明密钥被截断了,或者带了空格、引号 —— 回控制台重新复制,把整个字段重敲一遍。404 说明地址多写或少写了路径;必须正好是 https://api.qcode.cc/openai/v1。
确认模型已启用¶
点过 Add 之后,插件就离开了 Configuration required。点卡片下面的 Show Models 展开模型列表:① 出现 gpt-6.2-sol LLM CHAT 这一行,右侧的开关是打开的。然后点页面右上方工具栏里的 ② Default Models。

做对了你会看到:① 一行模型记录,写着 gpt-6.2-sol、LLM 和 CHAT,右侧开关已打开;② Default Models 是右上角的蓝色按钮。
把它设为默认系统模型¶
Default Model Settings 会以对话框形式弹出。第一行是 ① System Reasoning Model:打开它,在列表里选 gpt-6.2-sol,然后点 ② Save。

做对了你会看到:① System Reasoning Model 一行显示 gpt-6.2-sol;点 ② Save 之后,页面顶部的黄色提示条 Configure a default system model to run applications 会消失。
卡住了?这一行提示模型列表是空的
列表为空说明插件里还没有启用的模型 —— 退回上一步展开 Show Models,确认开关是打开的。在那个列表里被关掉的模型不会出现在这里。
创建一个 Chatbot 应用¶
打开左栏的 Studio,点 Create from Blank。一开始只提供 Workflow 和 Chatflow;点 MORE BASIC APP TYPES 展开其余类型,选 ① Chatbot。在 ② App name 里输入 QCode Assistant,然后点 ③ Create。

做对了你会看到:① 选中后 Chatbot 带蓝色边框,② 名称字段里是 QCode Assistant,③ Create 打开新建的应用。
卡住了?没有 Chatbot 这个选项
Chatbot 默认是折叠起来的:点两张卡片下面的 MORE BASIC APP TYPES,Chatbot、Agent 和 Text Generator 就会出来。另外确认当前页面是 Studio 而不是 Agents。
发第一条消息并检查回复¶
创建应用后会打开 Orchestrate 页面。① 顶部的模型选择器已经显示 gpt-6.2-sol CHAT。在 Debug & Preview 底部 ③ 的 Talk to Bot 输入框里输入 Hello! Please introduce yourself in one sentence.,按 Send;② 回答会流式写进上面的面板。

做对了你会看到:① 页头显示 gpt-6.2-sol CHAT,③ 输入框里是你的那句话,② 一段简短的英文回答逐词出现 —— 不是 401、404 或“找不到模型”的报错。
卡住了?回答一直不开始
再打开 Default Model Settings,确认 System Reasoning Model 里仍然是 gpt-6.2-sol;在保存默认模型之前创建的应用启动时是没有模型的。如果回复是红色的,说明密钥或地址写错了 —— 见下面的常见报错。
验证是否成功¶
下面四条全部对上,就说明配置完成了:
Model Provider的已安装集成里列着OpenAI-API-compatible,并且在Show Models里启用了gpt-6.2-sol。Default Model Settings里System Reasoning Model显示的是gpt-6.2-sol,而不是空行。QCode Assistant能在Debug & Preview里回答,回复是流式到达的,而不是 401、404 或“找不到模型”。- 关掉浏览器标签页再打开 Dify,模型、默认设置和应用都还在。
全部完成¶
你已经把 QCode 接进了 Dify,并且有一个 Chatbot 应用通过它在回答。接下来可以:
- 接入点与 API 路径 —— 三个 QCode 主机以及它们各自提供的全部路径
- 计费 —— 一把密钥、一份额度如何在各个应用和工具之间共享
- 故障排查
- 在定价页比较各个方案
- 回到控制台查看用量和余额
常见报错¶
| 报错原文 | 原因 | 怎么办 |
|---|---|---|
Set up api-key or add model to use |
插件已经装好,但还没往里加模型,所以 Dify 没有可选项 | 打开 Model Provider,在 OpenAI-API-compatible 卡片上点 Add Model,把四个字段都填好 |
Configure a default system model to run applications |
有模型,但没选默认模型,新建应用启动时就没有模型 | 点右上角的 Default Models,把 System Reasoning Model 设成 gpt-6.2-sol,再点 Save |
401 |
密钥已经到 QCode 但被拒绝:复制时带了空格、引号,或者只复制了一部分,也可能所属套餐已经结束 | 回控制台重新复制 cr_ 密钥,原样粘进 API Key,不要多加任何字符,并在控制台确认套餐状态 |
404 |
地址多写或少写了路径,QCode 收到的是它不提供的请求 | API Base URL 必须正好是 https://api.qcode.cc/openai/v1 —— 末尾不带斜杠,也不带 /chat/completions |
常见问题¶
需要 Dify 账号,还是 Anthropic、OpenAI 账号?¶
不需要任何模型厂商账号。Dify Cloud 要的是 Dify 账号;自托管实例要的是你在 /install 页面创建的管理员账号。两种情况里,真正到模型这一端的密钥都是你的 QCode cr_ 密钥,本教程没有任何一步要求登录 Anthropic 或 OpenAI。
列表里为什么找不到 OpenAI-API-compatible?¶
通常是三种原因:搜索框里还留着更长的词(只输入 OpenAI,再往下滚)、插件已经装过所以从页面的 Marketplace 部分移走了、或者这个账号不是工作区拥有者或管理员,而安装插件需要该权限。重新搜索之前先刷新一次页面。
模型名为什么必须是 gpt-6.2-sol?¶
Model Name 不是标签 —— Dify 会把这个字符串当作模型 ID 发给 QCode。QCode 的模型 ID 必须与 QCode 文档里列出的写法完全一致,所以 gpt-6.2-sol 能用,GPT 6.2 Sol 不行。同一个接入点提供的其他 ID 也填在同一个字段里,比如 gpt-6.2-astra。
在 Dify 里能通过 QCode 用 Claude 模型吗?¶
可以,走 Dify 自带的 Anthropic 集成,把 OpenAI 兼容地址换成 Anthropic 兼容地址 https://api.qcode.cc/api。那里的 QCode 默认模型是 claude-opus-5-5。本页 13 张截图走的是 OpenAI-API-compatible 插件,因为这是本教程完整覆盖的路线;Anthropic 地址可以当作以后要用的选项。
密钥到期后会怎样?¶
取决于你买的是什么。个人套餐附带的密钥不能续期 —— 需要重新开通套餐、创建一把新密钥,再粘贴到 API Key 字段里。按量包的密钥在再买一个包之后就会恢复:同一把密钥继续可用,Dify 里什么都不用改。
Dify 重启后会保留模型设置吗?¶
会。模型、它们的密钥以及默认模型都存在 Dify 数据库里,而不是浏览器会话里,所以退出登录或重启容器都不会把它们清掉。只有删除数据卷才会清空,而那同时也会删掉管理员账号和所有应用。
补全模式该选 Chat 还是 Completion?¶
用 Chat。QCode 在这个接入点上提供的是 chat-completions 系列模型,而 Completion 期望的是 prompt-completion 接口,这些模型并不提供。这里选错会直接在 Add 时报错,而不是等到应用里才暴露。
该用哪些模型¶
同一把 QCode 密钥可以使用多个厂商的模型,模型 ID 填进 Model Name。挑一个,其余字段保持不变。
| 模型 | 协议与地址 | 适用场景 |
|---|---|---|
gpt-6.2-sol |
OpenAI 兼容 —— https://api.qcode.cc/openai/v1 |
本教程的默认选择:日常对话、写作、代码问题 |
gpt-6.2-astra |
OpenAI 兼容 —— https://api.qcode.cc/openai/v1 |
GPT 系列更高一档,用于最难的 Agent 任务 |
claude-opus-5-5 |
Anthropic 兼容 —— https://api.qcode.cc/api |
Claude 旗舰,用于长推理和大规模重构 |
claude-haiku-5-5 |
Anthropic 兼容 —— https://api.qcode.cc/api |
轻量 Claude,用于快速、便宜的回答 |
把 claude-* 的 ID 发到 OpenAI 兼容接入点会被拒绝,把 gpt-* 的 ID 发到 Anthropic 接入点同样会被拒绝 —— 模型家族必须和地址匹配。最新的 ID 列表在控制台里。
地址是怎么用的¶
API Base URL 是基地址,不是完整的请求路径。Dify 会保留 /openai/v1 这一段,自己再拼上 chat/completions,所以这个字段必须停在 /v1。
| 字段 | 值 | 说明 |
|---|---|---|
API Base URL |
https://api.qcode.cc/openai/v1 |
保留 /openai/v1,末尾不带斜杠 |
| Dify 实际请求的地址 | https://api.qcode.cc/openai/v1/chat/completions |
由上面的字段自动拼出来 —— 不用手输 |
Model Name |
gpt-6.2-sol |
该接入点上提供的任意模型 ID |
Model Type |
LLM |
负责应答聊天请求的类型 |
Completion mode |
Chat |
不是 Completion |
API Key |
cr_xxxxxxxx |
与模型存在一起,所以只需填一次 |
备用接入点¶
如果默认主机在你的网络里很慢或者不通,只换域名,地址其余部分保持不变:
| 接入点 | OpenAI 兼容基地址 | Anthropic 兼容基地址 |
|---|---|---|
| 默认 | https://api.qcode.cc/openai/v1 |
https://api.qcode.cc/api |
| 亚洲 | https://asia.qcode.cc/openai/v1 |
https://asia.qcode.cc/api |
| 北美与欧洲 | https://us.qcode.cc/openai/v1 |
https://us.qcode.cc/api |
两个备用主机接受同一把密钥和同样的路径。如果换了主机,就在模型卡片上改 API Base URL,再点一次 Add 校验。完整说明见接入点与 API 路径。
自托管注意事项¶
- Windows 需要 Docker Desktop 加 WSL 2。 Dify 仓库是一组服务,而不是一个双击就能运行的程序;Docker Desktop 负责把它们跑起来,指南要求至少 2 个 CPU 核心和 4 GiB 内存。
- 源码放在 Linux 文件系统里。 Dify 目录放在 WSL 2 里而不是
C:\上时,性能和文件权限的表现都更好。 - 第一次启动很慢。 首次启动要拉好几个容器镜像,在 API 容器报告就绪之前页面一直是空白。之后的启动只要几秒。
http://localhost:8080是界面,不是 API。 Dify 本身不需要为浏览器下载任何东西;这个端口由容器提供。- Dify 界面语言和浏览器无关。 它是在账号菜单的
Preferences→General→Display Language里切换的;本教程使用英文界面,所以这里每个标签都和截图一致。
相关文档¶
- 接入点与 API 路径 —— 每个入口域名及其路径
- 计费 —— 共享额度规则
- 故障排查 —— 请求返回 401、404 或模型报错时
- Claude Code 教程 —— 同一把密钥用在终端里
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models