DeerFlow：字节跳动开源的 Super Agent 框架，从入门到上手完全指南

官网https://deerflow.tech/架构演示目录引言一、DeerFlow 到底是什么二、为什么 DeerFlow 值得关注2.1 字节跳动的工程底蕴2.2 真正隔离执行——Docker 沙箱是安全护城河2.3 V2 彻底重写团队追求做对而非做快2.4 开放生态MIT 协议自由商用三、核心架构Lead Agent Sub-Agents四、核心特性详解4.1 Skills 系统用 Markdown 定义工作流4.2 记忆与上下文不再是金鱼脑4.3 多模型支持五、环境要求六、三步开始快速部署6.1 方式一Docker 部署推荐6.2 方式二本地开发部署6.3 使用本地模型Ollama 完全免费方案七、第一次使用7.1 界面导读7.2 第一次对话八、常用维护命令九、常见问题排查9.1 端口冲突9.2 API 密钥不生效9.3 Docker 镜像拉取失败9.4 模型配置错误十、总结引言你可能听过 AutoGPT、MetaGPT但 DeerFlow 的出现让人眼前一亮——这款由字节跳动出品、采用 MIT 协议完全开源的项目一经问世便引发了全球开发者的关注。自 2025 年开源以来DeerFlow 在 GitHub 上已收获超过 35,000 颗星截至 2026 年 3 月底更是突破了 50,000 星Fork 数超过 6,000。2026 年 2 月 28 日DeerFlow V2 版本一上线就冲上了 GitHub Trending 第一名。DeerFlow 的全称是Deep Exploration and Efficient Research Flow深度探索与高效研究流。它的野心比普通的 Agent 框架要大得多。一、DeerFlow 到底是什么简单来说DeerFlow 不是聊天机器人也不是普通的 Agent 工具链——它是一个Super Agent Harness超级 Agent 运行架构。这个定位在 V2 版本中发生了质的飞跃V1 时代它只是一个深度研究框架而 V2 是一次彻底重写没有任何代码与旧版本共享完成了从深度研究工具到Super Agent 运行时基础设施的彻底蜕变。用官方的话说DeerFlow 结合了 Sub-Agent子代理、Memory记忆、Sandbox沙箱和可扩展的 Skills技能让 AI 能够完成几乎任何复杂任务——从深度研究、代码编写到内容创作任务时长可以从几分钟到几小时不等。把 DeerFlow 想象成一台F1 赛车底盘大模型如 DeepSeek、Kimi、Doubao 等是发动机而 DeerFlow 就是那台复杂的赛车底盘把子 Agent、中间件、记忆系统、沙箱环境等组织在一起让 AI 能够真正地把事情做完。V2 完全重写V1 仍在1.x分支维护这一决策体现了团队对架构的深思熟虑。二、为什么 DeerFlow 值得关注2.1 字节跳动的工程底蕴33K 星和活跃的社区证明了它的生命力。V2 发布以来项目持续得到高频更新累计已经有 1,635 次提交。2.2 真正隔离执行——Docker 沙箱是安全护城河大多数 Agent 框架的 Agent 往往受限只能调用 API、读写文件或执行脚本。而 DeerFlow 利用Docker 容器为每个任务提供完全隔离的环境独立文件系统、Bash 命令、代码执行仿佛坐在真实电脑前操作一样。这意味着 Agent 不仅能想还能真正做而且是安全、可控、可审计的。系统提供本地、Docker、Kubernetes 三种沙箱运行模式Docker 模式采用字节开源的 AIO Sandbox隔离级别更高、运行更稳定。2.3 V2 彻底重写团队追求做对而非做快V1 采用固定 5 节点多智能体架构能力边界相对明确主要聚焦在深度研究场景。而 V2 采用单一主智能体 11 层中间件链 动态子智能体的全新架构只需添加新技能就能完成拓展无需改动底层框架。2.4 开放生态MIT 协议自由商用DeerFlow 采用 MIT 协议任何人可以免费使用、修改和商用。支持模型包括豆包 Seed 2.0 Code、DeepSeek V3.2、Kimi 2.5同时兼容 GPT-4、Claude、Gemini 等主流模型。集成方面支持 Telegram、Slack、飞书/Lark 以及 MCP 服务器。三、核心架构Lead Agent Sub-AgentsDeerFlow V2 引入了Lead Agent Sub-Agents的分层架构Lead Agent主 Agent系统的中枢负责任务分解和协调理解你的意图、判断任务复杂度。它依靠一套 11 层中间件链沙箱、摘要、记忆、标题检测、子 Agent 限流等来管理整个流程。Sub-Agents子 Agent按需动态生成每个拥有独立上下文和工具集可并行处理任务结果汇报给 Lead Agent。Human-in-the-loop关键节点可暂停请求用户确认确保方向正确。底层实现基于LangGraph LangChain——LangGraph 提供有状态图执行框架将每一个 Agent 回合都编排成图中的节点。这种设计让系统能够处理长线复杂任务Lead Agent 可以并行拉起多个 Sub-Agent每个都有独立的上下文、工具集和终止条件互不干扰最后由 Lead Agent 汇总结果。四、核心特性详解4.1 Skills 系统用 Markdown 定义工作流每个 Skill 就是一个 Markdown 文件包含 YAML 头部元数据和具体的指令内容。Skills 按需加载不用的时候不占用上下文窗口对 token 敏感的模型非常友好。内置模板包括研究报告生成自动搜索、分析、撰写结构化报告PPT 制作自动生成幻灯片网页生成生成完整 HTML 页面图片生成根据文字描述生成配图以及数据分析、图表生成、音视频创作等十余种常用技能配合官方提供的 Skill-creator 工具几分钟就能为智能体扩展新能力。4.2 记忆与上下文不再是金鱼脑长期记忆跨会话保存重要信息项目背景、研究结论、个人偏好都能记住。上下文压缩子智能体的上下文完全隔离同时能自动总结、压缩、持久化中间结果解决长线任务中爆上下文和失忆的问题。去重机制自动跳过重复条目防止记忆膨胀。4.3 多模型支持DeerFlow 在模型选择上非常开放兼容任何实现了 OpenAI 兼容 API 的大语言模型。你可以在config.yaml中配置多个模型按需切换。支持本地运行零 API 费用如 Ollama 本地模型也可以用商业模型获得更强推理能力。五、环境要求在开始部署之前请确保你的开发环境满足以下要求依赖版本要求用途Python3.12 或更高后端核心语言Node.js22 或更高前端服务Docker最新稳定版推荐使用 Docker 部署沙箱环境Git最新稳定版克隆仓库内存建议至少 8GB运行 Agent 服务操作系统支持 macOS、Linux 或 Windows通过 WSL2。六、三步开始快速部署6.1 方式一Docker 部署推荐Docker 部署是最快的方式所有依赖都被隔离在容器中不会污染本地环境。第 1 步克隆仓库并生成配置git clone https://github.com/bytedance/deer-flow.git cd deer-flow make configmake config会从模板生成配置文件config.yaml和环境变量文件.env。第 2 步配置模型编辑config.yaml至少定义一个模型。以下是最简配置示例models: - name: deepseek-v3.2 display_name: DeepSeek V3.2 use: langchain_openai:ChatOpenAI model: deepseek-chat api_key: $DEEPSEEK_API_KEY # 从 .env 读取 base_url: https://api.deepseek.com/v1 max_tokens: 4096 temperature: 0.7然后在.env文件中填入实际的 API KeyDEEPSEEK_API_KEYyour-key-here # Web 搜索工具可选 TAVILY_API_KEYyour-tavily-api-key省钱小贴士如果使用 DeepSeek V3价格约为 $0.0014/1K tokens比 GPT-4o 便宜约 50 倍研究任务上质量差异可以忽略不计。你也可以使用本地 Ollama 模型完全免费。第 3 步Docker 启动make docker-start启动成功后在浏览器中访问http://localhost:2026即可看到 DeerFlow 的主界面。6.2 方式二本地开发部署如果你需要进行二次开发或调试可以使用本地部署模式# 使用安装向导交互式配置 make setup # 验证配置是否正确 make doctor # 启动所有服务热重载支持 make dev本地开发模式会启动以下服务Frontend(端口 3000)Next.js 前端界面Gateway API(端口 8001)REST API 网关LangGraph Server(端口 2024)Agent 运行时引擎Nginx(端口 2026)统一访问入口6.3 使用本地模型Ollama 完全免费方案如果想彻底零成本运行可以使用本地 Ollama 模型。以下是一个完整的配置示例models: - name: qwen3.5:9b display_name: Qwen 3.5 9B use: langchain_openai:ChatOpenAI model: qwen3.5:9b api_key: test # Ollama 不需要实际 API Key base_url: http://你的主机IP:11434/v1 max_tokens: 4096 temperature: 0.7 supports_vision: true启动 Ollama 服务并拉取模型后按上述配置即可使用。七、第一次使用7.1 界面导读启动成功后打开http://localhost:2026你会看到 DeerFlow 的工作区。界面采用三栏式布局侧边栏新建对话、浏览历史对话、管理智能体、访问设置。可以通过CtrlBMac 为CmdB切换显示/隐藏。对话主区域显示当前对话的消息流和输入框。制品面板展示 AI 生成的文件代码、图表、文档等点击顶部文件按钮展开。7.2 第一次对话点击侧边栏的新对话按钮进入对话页面。你会看到一个欢迎界面下方有快捷建议按钮助你快速开始写作撰写博客文章、技术文档等研究深度调研某个主题并总结发现收集数据采集和报告生成代码代码编写和调试尝试输入一个任务例如研究一下 RAG 技术的最新发展趋势并生成一份简要报告。DeerFlow 的 Lead Agent 会自动将任务拆解调用 Sub-Agent 进行搜索、分析和撰写并在对话主区推送实时的任务状态信息。八、常用维护命令命令作用make docker-start启动所有 Docker 服务make docker-stop停止所有 Docker 服务make docker-logs查看后端日志make doctor检查配置文件和环境make check检查依赖版本和运行环境make clean清理临时文件和容器九、常见问题排查9.1 端口冲突如果在 macOS/Linux 上运行make docker-start时提示端口 2026 已被占用可以按以下步骤排查# 查看占用端口的进程 lsof -i :2026 # 终止占用端口的进程 kill -9 PID或者修改docker-compose.yml中的端口映射。9.2 API 密钥不生效确保config.yaml中使用$符号引用环境变量如$OPENAI_API_KEY并且.env文件存在于项目根目录。如果修改了.env需要重启容器才能生效。9.3 Docker 镜像拉取失败在网速较慢的环境下Sandbox 镜像拉取可能会超时# 清理 Docker 缓存后重试 docker system prune -a make docker-start9.4 模型配置错误如果添加新模型后出现 Provider 模块缺失的错误需要安装对应的 LangChain 集成包。例如使用 OpenAI 需要langchain-openai使用 Anthropic 需要langchain-anthropic。十、总结DeerFlow 的诞生标志着 AI Agent 正从概念验证走向实际落地。它证明了 Agent 框架可以做到强大、安全、开放、易用强大Lead Agent Sub-Agents 的架构让复杂任务自动拆解并行执行解决长线任务难题。安全Docker 沙箱为每个任务提供完全隔离的运行环境可审计、可追溯。开放MIT 协议兼容多模型集成多平台Skills 系统让扩展变得简单。易用三步就能跑起来内置十余种开箱即用的技能。如果你想探索 AI Agent 的潜力不妨花一个下午试试 DeerFlow——无论是开发者希望深度使用还是仅仅想一睹 Super Agent 框架的风采这趟开发之旅都值得启程。