开头先说说我的结论把 DeerFlow 装进 Windows 这件事我前后折腾了两天踩完坑之后觉得有必要把整个过程完整记录下来。DeerFlow 是一个基于大语言模型做自动化任务编排的开源项目核心思路是把“拆解需求、调用工具、汇总结果”这一连串步骤交给 agent 去跑而不是像传统脚本那样每一步都要人手动指定。它自带一个本地 Web 控制台你可以在浏览器里创建任务、观察执行日志、查看最终产出。这篇文章就是给那些想在 Windows 机器上把 DeerFlow 跑起来、又不想在报错里迷失方向的朋友写的我会从环境准备讲起一直到启动成功、跑通第一个 demo把常见坑也一并列出来。1. 安装前准备先看清楚依赖关系再动手1.1 DeerFlow 是什么它到底解决了什么问题DeerFlow 本质上是一个面向任务编排的 agent 框架它把大模型和外部工具串成一条流水线。传统的大模型调用是“你问一句它答一句”但真实业务场景里往往需要多步操作比如先读取一个文件、再根据内容生成摘要、接着把摘要发到某个接口、最后把结果写入本地数据库。这种场景如果用手工脚本去写每一步的输入输出都得自己维护逻辑一复杂就很容易乱。DeerFlow 的思路是你只需要在控制台里用自然语言描述整个目标模型会自己规划步骤、调用注册好的工具、检查中间结果最后把结论整理出来。它把“规划能力”和“执行能力”拆开规划由大模型完成执行由具体的工具函数完成两者通过 agent 的循环机制连接起来。所以它适合的群体非常明确想快速搭建自动化工作流、又不想从零写 agent 框架的人。很多人在 Windows 上装这个项目碰壁不是因为项目本身有多难而是它的运行依赖涉及 Python 虚拟环境、Node.js 前端构建、API Key 配置再加上 Windows 的路径分隔符、编码规则、防火墙策略和 Linux 差异不小任何一个环节出问题启动时都会给你一个看不懂的报错。我先把它需要的依赖摸清楚再一步步来。1.2 Windows 环境清单Python、Git、Node.js 一个都不能少DeerFlow 的后端是 Python 写的前端是 Node.js 生态构建的Git 负责拉取代码和子模块。所以在动手之前先把三样东西装齐。我给一份我实测可用的环境版本作为参考依赖推荐版本检查命令说明Python3.10 或 3.11python --version3.10 以上最稳3.12 部分依赖可能还没适配Git2.40git --version需要支持拉取子模块Node.js18 LTS 或 20 LTSnode -v、npm -v前端构建必须建议用 LTS 版本如果python --version提示找不到命令大概率是安装时没有勾选“Add Python to PATH”或者系统里装了好几个 Python 版本导致环境变量混乱。我建议你打开“设置 - 系统 - 关于 - 高级系统设置 - 环境变量”确认 PATH 里指向的是你期望的 Python 安装目录。这个检查看起来很基础但很多人后面启动失败根源就是这里。Git 安装时有一个关键选项建议选择“Checkout as-is, commit as-is”不要选自动转换换行符否则后续克隆下来的脚本可能出现格式错乱。Node.js 安装一路默认即可装完记得重启终端让新加的环境变量生效。这一步做完先别急着继续老老实实跑一遍检查命令确认三行版本号都能正常输出再往下走。2. 搭建 Python 运行环境从 Miniconda 到虚拟环境2.1 为什么我推荐 Miniconda 而不是官方 PythonDeerFlow 的依赖库很多numpy、pydantic、fastapi、uvicorn 这些包对版本都有要求直接装进系统 Python 环境很容易和别的项目起冲突。我早期吃过这个亏电脑里有个老项目锁定了 pydantic 1.xDeerFlow 需要 pydantic 2.x两边一起 import 的时候直接崩溃排查了半天才想到是环境串了。所以这次我改用 Miniconda。它比完整版 Anaconda 轻量很多只带 conda 包管理器和 Python 基础环境够用又不臃肿。Miniconda 的核心优势是环境隔离一个项目一个环境环境之间互不干扰想删就删想重建就重建成本非常低。安装 Miniconda 的时候有几个细节要留意。第一安装界面里有个“Add Miniconda3 to my PATH environment variable”选项默认是勾选状态有人建议取消但我建议勾上省得后面终端里找不到 conda 命令。第二安装路径尽量不要带空格和中文我用的是C:\Miniconda3后面凡是涉及路径拼接的操作都没出过问题。第三装完以后重新打开终端执行conda --version验证一下。2.2 创建虚拟环境并激活打开“Anaconda Prompt”或者 Windows Terminal执行以下命令创建 DeerFlow 专用的虚拟环境我指定 Python 3.10 而不是最新的 3.12因为实测下来部分依赖对 3.12 的 wheel 支持还不完整3.10 是最稳妥的选择conda create -n deerflow python3.10 -y conda activate deerflow激活成功以后终端提示符前面会出现(deerflow)标记这说明你现在已经在这个虚拟环境里了。接下来再确认一次 Python 和 pip 的路径都指向环境内部避免出现“conda 环境激活了pip 装的包却跑进系统目录”的诡异情况where python where pip正常情况下输出路径应该指向C:\Miniconda3\envs\deerflow\这个目录。如果指向系统 Python 目录说明激活失败或者环境变量优先级有问题这时候先把所有终端窗口关掉重新打开再激活。接下来我把 DeerFlow 的代码克隆到本地仓库体积不大放到任意纯英文目录下都行git clone --recurse-submodules https://github.com/你的项目地址/deerflow.git cd deerflow--recurse-submodules这个参数很重要它会一并拉取子模块否则前端依赖目录是空的后面构建必失败。3. 正式安装 DeerFlow 依赖镜像源与版本锁定3.1 pip 安装过程的几个选择虚拟环境就绪后开始安装依赖。DeerFlow 仓库里一般会有一个requirements.txt它锁定了后端 Python 包的版本范围直接让 pip 按清单装就行pip install -r requirements.txt如果你的网络访问 PyPI 官方源比较慢这一步可能会卡很久甚至超时。我在第一次安装时就遇到了这个问题后来换了清华镜像源速度提升非常明显pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里有个容易忽略的点requirements.txt里的依赖是相互有约束的比如某个包要求 fastapi 的版本必须大于某个值另一个包可能要求小于某个值。pip 在解析这些约束的时候如果网络不稳定导致部分包下载失败可能会产生一个不完整的版本集合这时候安装完启动会报 ImportError。所以我建议装完以后补一个版本一致性检查pip check如果输出结果什么提示都没有说明依赖关系没冲突可以做下一步。如果提示某个包缺失或者版本不符就用pip install 包名版本号手动修正。另外前端部分的依赖用 npm 安装在仓库根目录执行npm install这一步会拉取 React、Vite 之类的前端库耗时取决于网速耐心等它跑完就行。3.2 验证 DeeerFlow 是否正确安装依赖装完先别急着启动做两个快速验证。第一确认核心包已经进入当前环境pip list | findstr deerflow第二尝试在 Python 里直接导入它python -c import deerflow; print(deerflow.__version__)如果看到版本号输出说明后端安装成功。如果提示 ModuleNotFoundError先检查当前终端是不是还处于(deerflow)虚拟环境里。这个坑我在换终端窗口时踩过新开的终端默认没有激活虚拟环境直接执行 python 用的还是系统解释器包当然找不到。遇到这种情况重新执行conda activate deerflow就好。4. 启动配置与首次运行API Key 与配置文件4.1 配置文件 .env 的编写逻辑DeerFlow 通过环境变量读取模型接口的配置仓库里一般会提供一个.env.example模板文件。首次使用需要把它复制一份并改名为.env然后在里面填上你自己的 API Key 和模型服务地址。我以最常见的配置为例说明每个字段的含义MODEL_API_KEY你的密钥 MODEL_BASE_URLhttps://你的模型服务地址/v1 MODEL_NAMEgpt-4o-mini PORT8080MODEL_API_KEY是调用模型服务时用的身份凭证这个值一定要保密不要提交到 Git 仓库里。MODEL_BASE_URL指向你实际使用的模型服务不同服务商的格式不一样以官方文档为准。MODEL_NAME决定 agent 实际调用的模型名称建议选一个上下文窗口大、稳定性好的型号。PORT是 Web 控制台的监听端口默认 8080如果你本机这个端口被占用了可以改成 8081 或者其他空闲端口。这里我特别强调一下.env文件的编码在 Windows 上新建这个文件的时候记事本默认可能是 UTF-8 with BOM这在某些解析库下会导致第一个字段名带上隐藏字符启动时报错。最稳妥的做法是用 VS Code 打开文件确认右下角编码显示为 UTF-8如果没有 BOM 那更保险。4.2 启动命令与日志解读配置完成后启动命令取决于你的部署方式。我用的本地源码启动方式命令如下deerflow run如果你下载的是较旧版本可能需用 Python 模块方式启动python -m deerflow执行之后终端会开始打印启动日志。日志里出现类似下面的内容说明启动成功INFO: Uvicorn running on http://127.0.0.1:8080 INFO: Application startup complete.看到 Uvicorn 的提示就可以打开浏览器访问http://127.0.0.1:8080进入控制台页面了。日志里如果出现[Errno 10048]或者Address already in use这类提示说明PORT端口被其他程序占用了。我先查看端口占用情况然后决定换端口还是清掉占用进程netstat -ano | findstr :8080 taskkill /PID 对应进程号 /F另一个常见情况是防火墙弹窗拦截了 Python 的监听行为第一次启动时系统防火墙会询问是否允许 Python 访问网络这时候一定要勾选“专用网络”和“公用网络”并点击允许。如果当时误点了取消后续访问页面就会迟迟打不开。可以在“Windows 安全中心 - 防火墙和网络保护 - 允许应用通过防火墙”里手动把 Python 加进去。4.3 跑通第一个 Demo启动成功后进入控制台创建一个简单任务比如“把下面这段英文总结成三个要点”然后在输入框粘贴一段文本。DeerFlow 会展示 agent 的完整执行过程先是模型规划步骤接着逐步调用工具最后输出总结结果。我在第一次跑通这个流程时看到日志里工作流一步步推进那种感觉比单纯调模型 API 有意思得多因为它真的在“做事”。如果任务执行到一半卡住优先检查模型服务是否能正常访问。可以用一个小脚本直接测试接口连通性python -c import requests; r requests.post(https://你的模型服务地址/v1/chat/completions, json{model: 你的模型名称, messages: [{role: user, content: hi}]}, headers{Authorization: Bearer 你的密钥}, timeout15); print(r.status_code)如果返回 200说明接口正常问题出在 DeerFlow 配置上。如果返回 401 或 403则密钥或服务地址填错了。5. 高频报错与排查实录我从 Windows 上踩过的坑5.1 Python 路径混乱与虚拟环境失效Windows 上最常见的问题就是系统里同时存在多个 Python导致import实际用的解释器和pip装包的解释器不是同一个。明明pip list里能看到包但一运行就 ModuleNotFoundError。排查思路很简单先确定当前激活的虚拟环境再用where python看实际路径。如果发现路径不对重新激活虚拟环境或者检查 PATH 环境变量里系统 Python 的优先级是否过高。还有一个笨办法但很有效完全退出终端、重新打开、重新激活环境让所有环境变量重新加载一遍。5.2 编码问题导致日志乱码和解析失败Windows 终端默认用 GBK 编码而 Python 3 的源码和日志默认是 UTF-8这在打印中文日志时会直接报 UnicodeEncodeError或者输出乱码。解决方法有两种一是在终端执行chcp 65001把代码页切到 UTF-8二是在环境变量里设置PYTHONUTF81让 Python 强制使用 UTF-8 模式。我比较推荐第二种因为它对项目内所有子进程全局生效不用每次开终端都执行一次。5.3 防火墙拦截与安全日志DeerFlow 的 Web 控制台启动后外部设备要访问需要防火墙放行。如果局域网其他电脑访问不到先看看 Windows 安全日志里有没有记录被拦截的连接。我遇到过一种情况防火墙没有弹窗但安全日志里有大量丢弃记录问题就出在“公用网络”的入站规则默认全拒。把监听端口加到防火墙入站规则里或者把当前网络配置文件改成“专用网络”一般就能解决。这个排查思路同样适用于 Windows 上其他 Web 服务起不来、但本机 localhost 能访问的场景。5.4 依赖版本冲突DeerFlow 会用到 pydantic 和 fastapi这两个项目在版本升级时 API 调整过几次如果你用了最新的安装命令可能拉到一起不兼容的版本。报错形式通常是ImportError: cannot import name xxx from pydantic。我的处理方式是先读报错信息里的包名再用 pip 固定版本给装回去。比如我在一次启动时遇到 pydantic 相关报错就把 pydantic 固定成 2.x 系列里较新的版本pip install pydantic2.5,3 pip check5.5 端口占用与重启失败Windows 上服务重启后报端口占用这个问题不仅在 DeerFlow 上有很多服务都有这个通病。原因是上一个进程虽然退出了但 TCP 连接还处于 TIME_WAIT 状态或者进程没有完全结束。解决方式是先查端口对应的 PID确认是残留进程后直接结束进程。我一般会在启动脚本里加一个端口检测逻辑提前清理。还有一种情况是改了配置文件里的端口但浏览器还缓存着旧页面这时候用无痕窗口访问就能排除缓存干扰。6. 进阶用 Docker 方式部署的替代方案6.1 Docker Desktop 与 WSL2 的配合如果你不想在 Windows 上折腾本地 Python 环境也可以考虑用 Docker 容器跑 DeerFlow。前提是先装好 Docker Desktop并且把 WSL2 作为后端引擎。Windows 下装 Docker 的注意点比较多要确保 BIOS 里开启了虚拟化安装 Docker Desktop 时勾选使用 WSL2安装完成后还需要在“设置”里检查 WSL 集成是否启用。用 Docker 部署的好处是环境完全隔离不污染本机 Python删掉容器后一点痕迹不留。启动命令类似这样docker run -p 8080:8080 -v /path/to/.env:/app/.env deerflow:latest-p参数把容器内的 8080 端口映射到宿主机-v参数把本地的.env文件挂载进容器这样改配置不用重建镜像。6.2 本地安装与容器安装怎么选对比项本地 Python 安装Docker 容器安装环境隔离中依赖 conda 虚拟环境高容器内完全独立上手成本低装完依赖直接跑中需要理解 Docker 基本概念资源占用中高WSL2 本身会占内存适合场景快速试用、二次开发调试长期部署、多机迁移我个人建议如果只是想在 Windows 上快速体验 DeerFlow 的功能用本地安装就够了因为修改 Python 代码后可以立即生效调试方便。如果目的是部署一个长期运行的服务或者换机器部署那用 Docker 镜像更省心把镜像和.env文件复制过去就能跑。最后再分享一个小技巧不管用哪种方式启动把.env文件中的PORT设置成一个不常用的高位端口比如 18080能有效避免和其他开发服务器抢 8080 这个默认端口。我后来一直这么用再也没遇到过一次端口占用导致的服务启动失败。
