bytedance/deer-flow · 上手攻略

  • 仓库：bytedance/deer-flow
  • 链接：https://github.com/bytedance/deer-flow
  • 分类：agent
  • 作者：Tom
  • 更新：2026-07-06

这是什么

DeerFlow（Deep Exploration and Efficient Research Flow）是字节跳动开源的 Super Agent Harness，于 2026 年 2 月 28 日凭借 2.0 重写版本登上 GitHub Trending 第 1 名。它将 Sub-Agent、Memory（记忆）、Sandbox（沙盒）和可扩展 Skills 整合在一起，支持从分钟级到小时级的多层次复杂任务。2.0 是从零重写的版本，与 1.x 分支无任何共用代码。

核心定位：不只是一个 deep research 工具，而是一个可扩展的 Agent 运行框架，适合需要多工具协作、长时程任务执行、代码沙盒隔离的研究与工程场景。

Stars：76,196 | 周增：+273 | 语言：Python | 许可：MIT

解决什么问题

现有 Agent 框架（如 LangChain Agent、AutoGPT）在处理长时程复杂任务时有几个痛点：

  • 缺乏隔离执行环境：代码直接在宿主机执行，存在安全风险
  • 记忆管理薄弱：对话级记忆无法支撑跨会话的长期知识积累
  • 工具扩展性差：新增工具需要改核心代码
  • 多模型编排复杂：不同任务需要不同模型，但切换成本高

DeerFlow 通过 Sandbox 隔离、内置 Memory 系统、Skills 机制、MCP Server 支持和灵活的多模型路由一站式解决上述问题。

快速安装

方式一：Docker 部署（推荐，最简）

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup       # 交互式向导：选择 LLM Provider、Web 搜索、Sandbox 模式
make docker-init # 首次或镜像更新时拉取 sandbox 镜像
make docker-start  # 开发模式（热更新）
# 或
make up          # 生产模式（构建镜像 + 启动）

访问：http://localhost:2026

⚠️ macOS/Windows 用户推荐作为开发/评估环境使用。生产服务更推荐 Linux + Docker。

方式二：本地开发

# 检查依赖
make check  # 需要 Node.js 22+、pnpm、uv、nginx

# 安装依赖
make install  # 安装 backend + frontend 依赖 + pre-commit hooks

# 启动服务
make dev

访问：http://localhost:2026

⚠️ Windows 用户请在 Git Bash 中运行，不支持原生 cmd.exe 或 PowerShell。

安装后验证

make doctor   # 检查配置完整性并给出修复建议

核心配置

安装向导 make setup 会生成 config.yaml 和 .env。手动配置示例：

# .env
OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key    # 可选，搜索功能

config.yaml 核心模型配置示例

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

  # 本地 vLLM 模型示例
  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true

推荐模型：官方推荐 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5；国内用户可通过火山引擎 Coding Plan 获取免费额度（见仓库 README）。

核心用法

Web 界面使用

安装完成后，在浏览器打开 http://localhost:2026，即可通过对话界面与 DeerFlow 交互。输入任务后，DeerFlow 会自动：

  1. 解析任务并拆解为子目标
  2. 调用 Sub-Agent 分别执行
  3. 在 Sandbox 中安全运行代码
  4. 通过 Memory 系统积累上下文

Skills 系统

DeerFlow 支持可扩展的 Skills，即插即用：

# config.yaml 中的 Skills 配置
skills:
  - name: web_search
    type: search  # 或 custom
    config:
      provider: tavily  # 或 infoquest（字节自研，免费体验）

MCP Server 集成

支持连接外部 MCP Server（含 OAuth Token 流程）：

# config.yaml MCP 配置
mcp_servers:
  - name: filesystem
    command: npx -y @modelcontextprotocol/server-filesystem /tmp

IM 渠道（高级用法）

DeerFlow 支持从即时通讯平台接收任务，支持 Telegram、Slack、Discord、飞书、企业微信、钉钉等。配置后无需公网 IP，渠道消息会自动路由为 Agent 任务。

TUI 终端工作台

# 在终端内运行 TUI 界面（无需浏览器）
deerflow tui

典型适用场景

  • 深度研究任务：需要多轮搜索、阅读、整合的长报告生成（如市场分析、竞品调研）
  • 代码开发与执行：Sandbox 隔离下安全运行 AI 生成的代码，适合自动化测试、数据处理脚本
  • 多模型比较：在 config.yaml 中配置多个模型，快速对比不同模型在同一任务上的输出质量
  • 复杂 Agent 系统原型：基于 DeerFlow 的 Sub-Agent + Memory + Skills 机制搭建业务定制 Agent
  • 定时任务：内置 Scheduled Tasks 功能，适合周期性数据采集与分析

坑与注意

  1. 资源要求高：单会话本地体验推荐 8 vCPU + 16 GB 内存；4 核/4 GB 经常不够。长期运行服务建议 16 vCPU + 32 GB 内存。
  2. 2.0 完全重写：1.x 分支不再活跃维护，升级前务必确认所需功能已在 2.0 中实现。
  3. 沙盒镜像首次拉取慢：make docker-init 首次需要拉取较大镜像，网络慢的环境建议提前准备。
  4. 配置有门槛：make setup 向导降低了一定复杂度，但多模型 + MCP + Sandbox 的完整配置仍需要一定理解成本。
  5. 国内访问火山引擎：官方推荐 Doubao-Seed 模型，但火山引擎服务在中国大陆境外访问可能不稳定，国内用户建议用 DeepSeek 或 OpenRouter。
  6. 安全风险：DeerFlow 支持执行 AI 生成的代码，即使有 Sandbox 隔离，公网部署时仍需注意网络安全配置。

与同类对比

项目 定位 优点 缺点
DeerFlow Super Agent Harness Sandbox 安全、Memory 完整、多渠道集成 资源要求高，配置复杂
LangChain Agent 通用 Agent 框架 生态最大，灵活性高 安全执行需额外配置
AutoGPT 自主 Agent 上手快，概念直观 缺乏隔离，易出错
Open Interpreter 代码执行 Agent 本地代码执行，免费 安全隔离较弱
n8n workflow 工作流自动化 图形化，生态丰富 非 Agent 原生定位

一句话推荐结论： 如果你需要安全地运行 AI 生成的长时程复杂任务，尤其是代码执行 + 多步骤研究类任务，DeerFlow 是目前开源方案中完成度最高的选择；如果你只需要轻量 Agent 流程，LangChain 更通用。