DeerFlow 最近在圈子里热度不低很多人冲着它“复杂任务自动拆解、深度推理”的能力来的。但我发现一个现象不少朋友第一关就卡在 Windows 安装上不是 Python 环境崩了就是前端起不来甚至有人在 .env 配置那一步直接放弃。这种东西其实不难但 Windows 上确实有太多细节和坑官方文档又偏 Linux导致很多人被劝退。我前前后后在 Windows 上完整部署过好几次 DeerFlow踩遍了各种奇奇怪怪的坑包括编码问题、端口冲突、依赖版本打架、模型 API 连不上等等。这篇文章就把我实测下来的完整安装启动流程和排错经验一次讲清楚照着做基本能跑起来。目标是让在 Windows 上折腾 DeerFlow 的人少走弯路尤其是第一次接触这类 Agent 框架的朋友。1. 装前准备先搞懂 DeerFlow 的架构和依赖栈很多人拿到项目就直接 pip install装到一半报错才回来翻文档。我的习惯是先花几分钟把项目的依赖关系和高层架构弄清楚这样后面出问题也能快速定位是哪一层挂了而不是瞎猜。1.1 DeerFlow 到底是个什么东西DeerFlow 本质上是一个基于 LangGraph 的 AI Agent 推理框架。它和你平时直接调用 GPT API 的最大区别在于它内置了一个有向无环图的编排逻辑可以把一个复杂任务拆解成多个子任务然后按顺序或按条件执行多轮推理中间还支持“深度推理模式”和“反思模式”。简单理解普通对话是“一问一答”而 DeerFlow 是“你把一个棘手的活扔给它它自己会拆步骤、反复验证、最终给出结论”。整个框架在本地运行时的结构大概是三部分Python 后端负责核心的 Agent 编排和推理链路Node.js 前端提供一个 Web 控制台用来输入任务和查看推理过程底层则通过调用大模型 API 来完成推理这个 API 可以是云端的比如 OpenAI、DeepSeek、智谱也可以是本地 Ollama 拉起来的。明白了这个结构你就能猜到安装时需要准备什么一套能跑 Python 的环境、一套能跑 Node.js 的环境、一个可用的模型 API 配置以及项目本身的代码和依赖包。哪一块缺失或者版本不对都会导致启动失败。1.2 版本选择Windows 上不能太随缘DeerFlow 对运行环境是有隐性的版本要求的官方文档有时写得比较简略但实际踩下来有几个硬性建议Python 版本建议 3.10 到 3.12我实测 3.11 最稳。Python 3.12 也能跑但部分依赖的 wheel 包在 Windows 上可能需要等新版本容易遇到“building wheel 失败”的尴尬。Node.js 建议用 18 或 20 的 LTS 版本。Node 版本太高比如 22有时会在前端构建时报 OpenSSL 相关的错误这个后面排查部分会细说。包管理器用 pip 就够了不需要额外装 Poetry 之类的东西除非项目文档特别指定。Git 建议装上虽然也可以直接下载 zip 包但后面想拉更新、切分支会非常麻烦。Windows 上还有一个容易被忽视的点项目路径不要带中文和空格。比如D:\deer-flow这种完全没问题但如果放在C:\Users\张三\我的项目\deer flow这种路径下后续 Python 和 Node 的构建工具很容易出幺蛾子报错信息还特别难懂。这不是玄学很多编译工具链对路径编码很敏感。1.3 提前准备好模型 API 密钥启动 DeerFlow 前你必须先有一个可用的 LLM API 配置否则后端服务即使起来了实际跑任务时也会报鉴权失败。如果你用云端 API需要准备好 API Key、接口地址Base URL、模型名称这三个信息。以 OpenAI 兼容接口为例Base URL 通常是https://api.openai.com/v1模型名类似gpt-4o国内的一些服务也是 OpenAI 兼容格式把 Base URL 换成对应的网关地址就行。如果你用本地模型那需要先装好 Ollama并拉取一个可用模型比如ollama pull qwen2.5:7b。DeerFlow 可以通过 OpenAI 兼容模式访问 OllamaBase URL 填http://localhost:11434/v1模型名填你拉取的名称。有一点我要特别提醒不要在配置文件里写错模型名。很多人以为填个模糊名字就行实际上模型名必须和你 API 账户里可用的模型完全一致大小写都不能错否则接口会直接返回类似model_not_found的错误。2. 环境搭建把 Python、Node.js、Git 一次装到位这部分看似基础但恰恰是 Windows 部署翻车的高发区。很多问题不是 DeerFlow 本身的问题而是基础环境没装对后面全盘崩。2.1 Python 安装的两种方式与避坑建议在 Windows 上安装 Python最保险的方式是去 python.org 下载官方安装包而不是用 Microsoft Store 里那个版本。下载时选 3.11 的 64 位安装包安装界面有一个关键选项“Add Python to PATH”一定要勾上。很多人装完 Python 后在终端里敲python没反应99% 是这个复选框没勾或者勾了但没重启终端。如果你之前装过其他版本 Python或者机器环境比较乱我强烈建议先装一个 Miniconda。Conda 的好处是可以为每个项目创建独立虚拟环境不同项目即使依赖冲突也互不影响。安装完 Miniconda 后在终端执行conda create -n deerflow python3.11 -y conda activate deerflow激活后你会看到命令行前面出现了(deerflow)前缀说明你已经进入独立环境。后面所有 Python 相关操作都在这个环境里做不要用系统全局的 Python 去装 DeerFlow 的依赖不然以后很容易和别的项目打架。验证安装的时候注意Windows 下有时候python指向的是 Store 的别名导致你打开了一个类似应用商店的窗口。这种情况可以去“应用执行别名”里关闭 Python 的 Store 别名或者直接使用python.exe的完整路径。总之最终能用python --version看到类似Python 3.11.x的输出才算正常。2.2 Node.js 安装推荐用 nvm-windows 管理版本很多新手直接去 nodejs.org 下载最新版一路 Next结果项目跑不起来。Node.js 在 Windows 上最大的坑是版本兼容性所以我建议花几分钟装一个nvm-windows用它来管理 Node 版本。具体做法是去 nvm-windows 的 GitHub Releases 页面下载nvm-setup.exe安装后打开新的终端执行nvm install 20 nvm use 20 node -v npm -v看到v20.x.x和10.x.x之类的版本号就说明 Node 环境没问题了。为什么不用最新版因为许多前端构建工具尤其是 Vite 和 Webpack 生态对最新的 OpenSSL 3.0 支持还不太完善用 LTS 版本能省掉很多“ERR_OSSL_EVP_UNSUPPORTED”之类的报错。2.3 Git 安装与项目获取Git 在 Windows 上安装也没太多讲究直接去 git-scm.com 下载安装包安装选项基本可以一路默认。有一点要注意安装过程中有个“Adjusting your PATH environment”的选项一定要选中间那个“Git from the command line and also from 3rd-party software”否则后面在终端里用不了git命令。项目获取方式很简单找一个合适的目录推荐D:\projects这种纯英文路径打开终端执行git clone https://github.com/deer-flow/deer-flow.git cd deer-flow如果 GitHub 拉取速度很慢或者超时可以配置代理或者使用镜像站这个大家都有自己的办法我就不展开了。克隆完成后用dir看一下目录结构一般会有后端代码、前端代码、配置文件示例、requirements 文件等。到这里基础环境就算准备好了。很多教程到这一步就直接让读者去装依赖但实际上如果基础环境没弄干净后面每一步都在踩地雷。3. 依赖安装与配置卡住 90% 新手的环节环境和项目都有了接下来是最容易出问题的环节安装 Python 依赖、安装前端依赖、配置 .env 文件。这三个动作环环相扣任何一个失败启动都会失败。3.1 创建虚拟环境并安装后端依赖进入项目根目录后先确认你还在刚才创建的 Conda 环境里。如果中途关了终端重新打开后记得执行conda activate deerflow否则后面装的包都装到全局环境里去了项目还是跑不起来。然后安装依赖pip install --upgrade pip pip install -r requirements.txt如果你的网络环境访问 PyPI 比较慢可以临时用清华源加速实测效果明显pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple安装过程可能出现两个典型问题。第一种是安装某些包时提示“Microsoft Visual C 14.0 is required”这种情况通常是某个 Python 包需要本地编译而 Windows 上缺少 C 构建工具。解决方法很简单去微软官网下载“Microsoft C Build Tools”安装时勾选“使用 C 的桌面开发”工作负载装完重启终端再执行 pip install。第二种是依赖版本冲突比如某个包需要 pydantic 2.x另一个包却说需要 1.x。这种情况别自己去 pip 一个一个改版本容易越弄越乱。正确做法是删除虚拟环境重建或者根据报错信息把相互冲突的包先卸载干净再重新按 requirements 安装。安装完成后可以验证一下关键包是否装好python -c import langgraph; print(langgraph.__version__)如果能正常打印版本号说明核心依赖没问题。如果报ModuleNotFoundError说明某个依赖没装上重新检查安装过程。3.2 安装前端依赖npm install 的注意事项DeerFlow 的 Web 控制台是一个独立的前端工程一般在项目目录下的frontend文件夹里。先进入该目录cd frontend npm install这里有几个常见问题。第一npm 默认源在国外速度可能很慢可以用华为云或腾讯云镜像执行npm config set registry https://registry.npmmirror.com后再 install。第二如果安装过程中报ERR_OSSL_EVP_UNSUPPORTED说明 Node 版本太高了回到 2.2 小节用 nvm 切换到 Node 20 再试。第三有时node_modules已经装了一大半但报错了再执行 install 又各种诡异问题这种情况下直接把node_modules文件夹删掉重装更快别舍不得那几分钟。前端装完后可以快速验证一下构建脚本是否能正常执行npm run build如果构建成功会在前端目录下生成dist文件夹说明前端环境没问题。不用每次都 build但第一次装完建议跑一次早发现问题早解决。3.3 配置 .env每个变量的含义别瞎填配置是启动前的最后一道关卡也是很多人出问题最多的环节。项目根目录下会有一个.env.example文件先把它复制一份并改名为.envcp .env.example .envWindows 的 CMD 里没有cp命令用 PowerShell 的话是Copy-Item或者直接在资源管理器里复制粘贴重命名这些细节不影响结果。打开.env文件你会看到类似下面这种内容不同版本变量名可能略有差异但核心结构一致# LLM 提供商配置 LLM_PROVIDERopenai LLM_API_KEYsk-xxxxx LLM_BASE_URLhttps://api.openai.com/v1 LLM_MODELgpt-4o # 后端服务 BACKEND_HOST127.0.0.1 BACKEND_PORT8000 # 前端服务 FRONTEND_HOST127.0.0.1 FRONTEND_PORT3000这里我重点说几个关键字段。LLM_PROVIDER这是模型提供商的类型常见的有openai、deepseek、ollama等。这个值会决定框架用哪种方式去调用 API填错了后端会走错客户端逻辑。LLM_BASE_URL接口地址。很多服务支持 OpenAI 兼容格式所以不一定非要用官方地址。例如你用的是 DeepSeek可以填https://api.deepseek.com/v1用的是本地 Ollama填http://localhost:11434/v1。LLM_API_KEY对应的密钥。如果使用本地 Ollama可以随便填一个非空字符串比如ollama因为本地服务通常不校验 key但 DeerFlow 的代码可能要求这个字段不能为空。LLM_MODEL模型名。这里的坑最多务必填精确的模型 ID比如gpt-4o、deepseek-chat、qwen2.5:7b。填错一定会导致调用失败。配置完成后别着急启动先在终端里用 curl 或者 Python 验证一下 API 是否通这一步能省下后面很多排查时间。比如用 Python 验证python -c from openai import OpenAI; clientOpenAI(api_keysk-xxx, base_urlhttps://api.deepseek.com/v1); rclient.chat.completions.create(modeldeepseek-chat, messages[{role:user,content:hi}]); print(r.choices[0].message.content)如果这里能正常返回一句话那么 API 链路就是通的问题就只可能在 DeerFlow 的启动和配置细节上。4. 启动与验证让 DeerFlow 真正跑起来环境装好、配置写好激动人心的时刻到了。但这里也要按顺序来建议先启动后端确认无误后再启动前端最后用几条测试任务验证整个推理链路是否通畅。4.1 启动后端服务先确认日志没有异常回到项目根目录确保 Conda 环境是激活状态然后执行python main.py不同版本的 DeerFlow 启动入口可能不一样有的版本是python main.py有的版本需要先执行数据库迁移之类的步骤。如果main.py不是启动入口查看项目根目录下的README或者pyproject.toml中的 scripts 配置通常能找到线索。后端启动成功的样子一般是终端里出现一串日志包括加载了哪些模块、API 文档地址、后端监听端口等最后停在类似Uvicorn running on http://127.0.0.1:8000这样的输出。此时不要关终端再开一个新的终端窗口处理前端。如果后端启动时报错先看堆栈信息里的关键行。常见的有三种第一ModuleNotFoundError说明某个依赖没装好回到第 3 节补装第二.env文件里的某个变量为空或者格式不对报错信息会指向配置解析那部分第三端口被占用报错类似[Errno 10048] error while attempting to bind on address (127.0.0.1, 8000): 通常每个套接字地址(协议/网络地址/端口)都只允许使用一次这时需要换端口或者杀掉占用进程。4.2 启动前端服务访问 Web 控制台后端起来后新开一个终端进入前端目录cd frontend npm run dev前端启动成功的标志是终端里打印出本地访问地址通常是http://localhost:3000或http://127.0.0.1:5173取决于端口配置。用浏览器打开这个地址应该能看到 DeerFlow 的对话界面。这里有个最常见的连接问题前端默认会向后端地址发请求如果你修改过FRONTEND_PORT或后端端口前端的代理配置可能还是旧值导致页面上输入任务后一直转圈或者报“网络错误”。解决方法是检查前端项目里的.env或vite.config.*里的代理配置确保它指向正确的后端地址。一般默认配置都是指向http://127.0.0.1:8000如果你没改过后端端口通常不用动。4.3 验证核心功能输入第一个任务看推理过程前后端都启动后在页面的输入框里输入一个稍微有点难度的任务比如“分析一段文本的情感倾向并给出理由”然后点击提交。DeerFlow 会开始执行它的 Agent 推理流程你会看到类似“节点开始执行”“工具调用”“深度推理完成”等过程日志。这一步骤验证的不只是“服务能跑”而是“整条链路能通”。如果任务提交后报错优先回到第 5 节排查大概率是 API 配置问题或者模型名问题。还有一个判断技巧如果页面能打开但提交任务无反应先看后端终端的日志。后端日志会比前端界面更详细它会明确指出请求是到达了后端还是在前端就被拦截了。定位问题永远是先看日志不要猜。另外强调一点DeerFlow 启动后只要不触发深度推理实际消耗的 token 并不多但如果你在配置里把反思次数或深度推理轮数调得很大每个任务可能会消耗大量 token测试时先用默认配置跑通再逐步调优。5. 高频问题排查Windows 上踩过的坑全记录这一节是全文最有价值的部分也是我反反复复在 Windows 上踩出来的经验。如果你的部署卡住了我强烈建议先把这一节完整看一遍很多问题都是共通的。5.1 UTF-8 编码问题Windows 默认编码的“锅”Windows 系统的默认编码是 GBK而 DeerFlow 的代码和配置文件基本都是 UTF-8。当 Python 读取某些日志文件或模型输出时可能会报类似UnicodeDecodeError: gbk codec cant decode byte 0x...这个问题在 Windows 上非常常见。最简单的解决方案是在启动终端里执行以下命令把当前终端的编码切换为 UTF-8chcp 65001如果你用的是 PowerShell可以先执行[Console]::OutputEncoding [System.Text.Encoding]::UTF8然后重新启动 DeerFlow。如果还不行可以临时设置 Python 环境变量$env:PYTHONIOENCODING utf-8这个方法能解决大部分编码报错。但要注意chcp 65001只对当前终端窗口生效关闭终端后就失效了所以每次启动 DeerFlow 前都要执行一次。嫌麻烦的话可以写一个批处理脚本把这些命令打包。另外如果你在 Windows 的系统设置中把“区域”里的“Beta: 使用 Unicode UTF-8 提供全球语言支持”勾上系统全局默认编码会变成 UTF-8这个设置能一劳永逸解决很多软件的乱码问题但可能影响一些老旧的国产软件自己权衡。5.2 网络请求超时或 SSL 证书报错Windows 上跑 Python 时有时会遇到 SSL 证书校验失败的报错比如SSL: CERTIFICATE_VERIFY_FAILED这个问题的根源通常是系统的证书信任链不完整或者 Python 没有正确加载 Windows 证书。解决方法有几个按推荐程度排序升级 Python 到 3.11 以上新版本对 Windows 证书处理更好。更新certifi包pip install --upgrade certifi。如果是在公司网络环境或使用代理模式可以暂时设置环境变量跳过证书校验仅限本地调试set SSL_CERT_FILE或set REQUESTS_CA_BUNDLE。这个方法不推荐长期使用但如果只是想在本地跑通可以应急。网络请求超时的问题则通常和模型 API 的网络链路有关。如果你用的是海外 API 且网络条件不理想建议换一个国内可直连的 OpenAI 兼容服务或者配置代理环境变量。DeerFlow 后端是 Python 进程代理配置要设置在启动后的终端里比如$env:HTTPS_PROXY http://127.0.0.1:7890然后再启动 DeeerFlow。5.3 端口被占用让出 8000 或 3000 端口如果你本机已经跑着别的服务正好占用了 DeerFlow 用的 8000 或 3000 端口启动时会直接报端口绑定失败。Windows 下找占用端口的方法是netstat -ano | findstr :8000假设输出有一行最后的 PID 是 12345然后用taskkill /PID 12345 /F杀掉占用进程后再启动 DeerFlow。如果你不确定那个进程是不是重要的也可以直接把 .env 里的BACKEND_PORT改成 8001、FRONTEND_PORT改成 3001改完注意前端代理配置也要对应调整。5.4 Node 相关依赖安装失败前端npm install常见的是node-gyp编译失败。这个包需要 Python 2/3 和 Visual Studio Build Tools 配合虽然很多依赖通过预编译二进制就能装上但总有例外。解决方式是装好 Build Tools或者在 npm 里设置使用预编译镜像npm config set node_gyp C:\Program Files\nodejs\node_modules\npm\bin\node-gyp-bin\node-gyp如果报错原因是网络先确认镜像源已经切换。安装完再看node_modules是否完整如果你运行npm run dev提示某个模块找不到很大概率是上次安装中断导致node_modules不完整直接删除重装即可。5.5 模型 API 调用失败别忽略 Base URL 的斜杠接口地址的斜杠问题很不起眼但很致命。有些服务要求的 Base URL 是https://api.example.com/v1有些则是https://api.example.com/v1/。DeerFlow 内部做请求时可能会拼接路径如果地址末尾多了一个斜杠有的服务会返回 404有的会直接报错。如果你确认 API Key 和模型名都没问题但调用还是失败可以试试把 Base URL 末尾的斜杠去掉或加上再测一次。另外要注意有些国内服务要求必须把LLM_BASE_URL填成网关地址而不是官网首页地址很多人习惯性地填成https://platform.example.com这种控制台地址当然连不上。5.6 启动后功能异常检查配置文件的换行符Windows 的记事本编辑 .env 文件时有时会把换行符存成 CRLF而很多解析库能处理 CRLF但有一些版本解析不太兼容导致某些变量后面带着看不见的\r字符API Key 校验失败。遇到这类诡异问题用 VS Code 打开 .env看右下角如果显示“CRLF”点击改成“LF”保存即可。这个坑特别隐蔽我之前排查了半天都没发现最后是打印变量值才看到末尾多了个\r。5.7 快速问题定位一套简单实用的排查思路不管遇到什么报错不要慌着去问 AI 或改代码先按下面的链路排查看终端日志找第一行红色的错误提示那里大概率有根因。确认虚拟环境是否激活、当前目录是否正确。确认 .env 文件是否生效可以在 Python 里打印关键配置项检查。单独用 curl 或 Python 测试模型 API确认上游没问题。最后再怀疑 DeerFlow 本身的代码问题因为大部分情况是我们自己的环境问题。这套思路帮我解决过 90% 的问题。很多时候不是 DeerFlow 不好用而是我们给了它一个有问题的运行环境。最后再分享一个小技巧。DeerFlow 跑通之后建议把启动命令封装成一个.bat脚本比如start_deerflow.bat内容包括激活 Conda 环境、设置 UTF-8 编码、启动后端、等待几秒后再启动前端。这样以后每次使用双击一个脚本就能完成所有启动动作不用再一个个终端去敲命令省事很多。脚本大致长这样echo off chcp 65001 call conda activate deerflow start DeerFlow Backend cmd /k cd /d D:\projects\deer-flow python main.py timeout /t 3 /nobreak nul cd /d D:\projects\deer-flow\frontend start DeerFlow Frontend cmd /k npm run dev根据自己的实际路径调整一下就能一劳永逸。我在实际部署中最大的感受是Windows 下很多问题不是 DeerFlow 本身的问题而是环境隔离和编码规范没做好。只要你把 Python 版本、Node 版本、依赖安装、配置文件这四件事做扎实了启动基本就是水到渠成的事。希望这篇能帮你在 Windows 上顺利把 DeerFlow 跑起来。