deer-flow 本地部署教程：字节跳动 SuperAgent 框架安装指南

准备在本地部署 deer-flow 时，先别把它当成普通网页项目。DeerFlow 2.0 的定位是字节跳动开源的 SuperAgent harness，本地跑起来后要同时处理模型配置、搜索配置、沙箱权限、文件写入和运行方式。我的建议是先跑通最小配置，再决定用 Docker 长驻，还是只在开发机上做本地评估。

先确认部署目标

如果只是想看 DeerFlow 的工作流，单人本地评估就够了；如果要让它长期跑任务、多人共享、生成报告或承载更重的 sandbox workload，就要按服务端思路准备资源。官方 README 给的起步参考是：本地评估或 make dev 至少 4 vCPU、8 GB RAM、20 GB 可用 SSD，更舒服的配置是 8 vCPU、16 GB RAM。

我会这样试：第一次不急着上服务器，先在本机或一台临时云主机跑通配置。确认模型能调用、端口能打开、任务能结束，再迁到 Docker 或长期服务环境。这样排错范围更小，日志也更好看。

准备环境和密钥

本地部署前，至少准备 Git、Python 3.12+、Node.js 22+、make，以及一个可用的 LLM provider。选择 Docker 方式时，还要提前装好 Docker。DeerFlow 的 setup 向导会让你选择模型供应商、可选 web search、sandbox mode、bash access、file-write tools 等项，并把密钥写入 .env，把基础配置写入 config.yaml。

这里最容易错的是把“能 clone 仓库”等同于“已经部署完成”。真正的完成标志不是文件下载完，而是 make setup 能走完、make doctor 没有阻断问题、页面或服务端口能访问。

按官方 Quick Start 安装

进入项目目录后，安装主线很直接：先执行 git clone https://github.com/bytedance/deer-flow.git，再进入 deer-flow 目录，运行 make setup。向导结束后，用 make doctor 做一次环境检查；如果检查结果提示缺少配置、依赖或运行条件，先按提示修掉，不要直接开长任务。

DeerFlow 也给 coding agent 准备了一句话启动方式。你可以把“克隆 DeerFlow，并按 Install.md 引导本地开发初始化”的任务交给 Codex、Claude Code、Cursor 或 Windsurf，让 Agent 先完成 clone 和 bootstrap，再停在需要你补密钥或确认配置的地方。密钥仍然要自己确认，不要让 Agent 乱填。

Docker 方式更适合长驻

想让 DeerFlow 跑得稳定，Docker 是更推荐的部署路径。官方 README 的 Docker development 区域给出了 make docker-init 和 make docker-start，前者用于拉取 sandbox 镜像，后者启动服务，并会根据 config.yaml 里的 sandbox 配置自动处理运行模式。

我会这样判断是否该用 Docker：只做一次研究任务，本地开发模式够用；需要持续运行、多 Agent、沙箱隔离、报告生成或团队共享，就用 Docker。注意 Docker 构建、bind mounts 和 sandbox 容器会吃更多资源，2 vCPU、4 GB RAM 这类机器通常不够稳。

本地开发方式怎么跑

偏开发调试时，可以走 Local Development。前提是先完成 make setup，然后再启动本地服务。README 里提醒，make dev 需要有效的 config.yaml，运行状态默认在项目根目录下的 .deer-flow，技能默认在 skills/，必要时可通过环境变量改到别的位置。

Windows 用户要多看一眼说明：本地开发脚本从 Git Bash 启动，原生 cmd.exe 和 PowerShell 不支持 bash 脚本，WSL 也不保证完全适配。这个坑很实在，遇到脚本路径、shell 或 cygpath 问题时，先换到官方建议的 shell，再排查依赖。

部署完成后检查什么

跑起来以后，先检查 5 件事：config.yaml 是否指向正确模型；.env 是否有真实密钥；make doctor 是否还有红色阻断；浏览器是否能访问本地端口；简单任务是否能正常结束并留下结果。不要一开始就把复杂代码库或长报告丢进去。

如果部署失败，优先看三类问题：模型密钥或供应商配置不对，Docker/sandbox 镜像没有拉完整，端口或 CORS 设置和本地前端不匹配。实在要提 issue，再运行 make support-bundle，它会生成用于排查的摘要和证据包，同时避开 .env、原始对话和用户文件内容这类敏感信息。

适合谁本地部署

deer-flow 更适合愿意折腾 Agent 工程化的人：你需要关心模型、工具、沙箱、技能、上下文和任务状态。如果只是想找一个开箱即用的聊天网页，它会显得偏重；如果你想研究 SuperAgent 框架如何在本地持续执行任务，先按 make setup、make doctor、Docker 或 make dev 这条线跑一遍，收获会更清楚。