小丸子博客

本站只有一些笔记，请不要有任何恶意

字节开源的 DeerFlow：搭建你自己的 AI 打工人

· 小丸子 · 阅读 49 · 分类： 部署教程

前言

你有没有这样的幻想：

  • 丢给它一个课题，让它自己去搜索、阅读、整理、写报告
  • 给一份 PPT 需求，它自动做出一份像模像样的幻灯片
  • 让它分析一组数据，生成可视化看板
  • 甚至让它自己写代码、跑代码、调试代码，完整处理一个复杂工程任务
你也许会想到 ChatGPT 或者 Claude，但它们本质上还是"一问一答"的助手。要让 AI 像员工一样自主执行长任务——有独立工作区、会用工具、会调用其他 AI 子代理、跨会话记住你的偏好——你需要的是一个Agent 框架。

今天要介绍的 DeerFlow（小鹿流），就是这样一个框架。它是字节跳动在 2026 年初开源的 SuperAgent Harness（超级代理外壳），目前在 GitHub 上已经拥有 61.7k Stars，并在 2026 年 2 月登上 Trending 榜首。

这是一篇从零到跑起来的完整部署 + 使用教程。

一、DeerFlow 是什么？

用一句话总结：它是一个能让大语言模型长时间独立工作的"外壳"。

传统的 LLM 对话是这样的——你问一句，它回一句，上下文一满就得重开。DeerFlow 解决的是另一类问题：

我给 AI 一个"研究 2026 年全球半导体格局并输出 50 页报告"的任务，它能：
1. 自己拆分成 20 个子任务
2. 为每个子任务派生一个子代理（subagent），并行执行
3. 各自拥有独立文件系统、独立上下文窗口
4. 调用网页搜索、下载文档、阅读内容、写代码、生成图表
5. 完成后汇总、写出最终报告
6. 跨会话记住你的偏好（比如"你喜欢 Markdown 格式的表格"）

这就是 SuperAgent 框架的价值。

二、核心特性

1. 多代理编排

  • 主代理可以动态派生子代理
  • 每个子代理有独立上下文、工具、终止条件
  • 子代理可以并行执行，显著缩短总耗时

2. 沙箱执行环境

每个任务有独立文件系统：
  • uploads/ — 上传的输入文件
  • workspace/ — 工作目录
  • output/ — 最终产物
所有 bash 命令、文件操作都在沙箱内，可配置安全级别。

3. 长期记忆

跨会话持久化保存：
  • 用户偏好
  • 已学到的知识
  • 常用的上下文信息

4. 技能系统

内置多种任务模板：
  • 研究（research）
  • 报告生成
  • 幻灯片制作
  • 网页生成
  • 图像 / 视频生成

5. IM 集成

可以直接在聊天软件里指挥它干活：
  • Telegram
  • Slack
  • 飞书 / Lark
  • WeChat / WeCom

6. MCP 协议支持

可以接入任意外部工具（通过 Model Context Protocol），例如数据库、API、私有服务。

7. 多执行模式

  • flash — 快速模式（简单任务）
  • standard — 标准模式
  • pro — 规划模式（先规划后执行）
  • ultra — 子代理模式（最强，长任务）

三、它适合谁？

适合：

  • 有长任务需求的开发者 / 研究者（写报告、做调研、整理资料）
  • 想把 AI 接入工作流的团队（通过 IM 或 API）
  • 想自建私有 Agent 平台的小企业（数据不出本地）
  • 折腾 AI Agent 的 Geek
不适合：
  • 只是想"聊天"的用户（用 ChatGPT/Claude 就够了）
  • 轻度使用者（部署成本不低，跑起来至少要 8GB 内存）
  • 没有 LLM API 预算的个人（每次任务都会烧 token）

四、系统要求

| 场景 | 最低配置 | 推荐配置 |
|------|---------|---------|
| 本地评估 | 4 核 / 8 GB / 20 GB SSD | 8 核 / 16 GB |
| Docker 开发 | 4 核 / 8 GB / 25 GB SSD | 8 核 / 16 GB |
| 长期服务 | 8 核 / 16 GB / 40 GB SSD | 16 核 / 32 GB |

软件依赖：

  • Python 3.12+
  • Node.js 22+
  • pnpm
  • Docker（强烈推荐）
  • nginx（生产部署）

你还需要至少一个 LLM 的 API Key：
  • 官方推荐 Doubao-Seed-2.0-Code / DeepSeek v3.2 / Kimi 2.5
  • 也支持任何 OpenAI 兼容接口（GPT-4o / Gemini / Qwen 等）
  • 模型要求：100k+ 上下文、工具调用能力、最好有推理能力


五、部署教程

以下步骤全程在 Ubuntu 22.04 / Debian 12 / macOS 上验证。

1. 准备环境

# 检查 Python 和 Node 版本
python3 --version   # 需要 3.12+
node --version      # 需要 22+

# 如果版本不够，先装
# Ubuntu 装 Python 3.12
sudo apt install python3.12 python3.12-venv

# 装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 装 pnpm
npm install -g pnpm

# Docker（如果还没装）
curl -fsSL https://get.docker.com | sh

2. 克隆仓库

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

3. 运行配置向导

make setup

这是一个交互式向导，会问你：

  • 选择 LLM 提供商（OpenAI / DeepSeek / Doubao / Anthropic / 自定义…）
  • 填入 API Key
  • 是否启用网页搜索
  • 沙箱模式级别（推荐 strict）
  • 是否允许 bash 访问
  • 是否允许文件写入
完成后会生成 config.yaml 和 .env 文件。

4. 启动服务

方式 A：Docker 开发部署（推荐新手）

make docker-init     # 拉取沙箱镜像
make docker-start    # 启动所有服务

方式 B：本地开发部署

make check           # 检查依赖
make install         # 安装 Python 和 Node 依赖
make dev             # 启动

方式 C：Docker 生产部署

make up              # 构建镜像并启动全部服务
# 停止
make down

5. 验证安装

make doctor

这个命令会检查：

  • 所有服务是否正常运行
  • LLM 连接是否成功
  • 沙箱是否可用
  • 数据库是否就绪

全部 ✅ 就算成功。

6. 访问 Web UI

打开浏览器，访问：

http://localhost:2026

会看到 DeerFlow 的操作界面。

六、基本使用

通过 Web UI

界面上选择执行模式（flash / standard / pro / ultra），然后输入任务描述。例如：

"帮我研究 2026 年全球电动汽车市场格局，输出一份 10 页的中文 Markdown 报告，包含主要厂商对比表格和趋势分析"

按回车，然后看着它：
1. 规划任务拆解
2. 派生子代理
3. 调用网页搜索
4. 阅读抓取的资料
5. 写代码生成图表
6. 汇总成最终报告

产物会出现在 output/ 目录下，你可以直接下载。

通过 IM 聊天

以 Telegram 为例：

1. 在 BotFather 创建一个 Bot，获取 token
2. 在 DeerFlow 配置里填入 token
3. 重启服务

然后直接在 Telegram 里对 Bot 说话：

/new 研究 AI Agent 领域最近 3 个月的融资情况
/status      查看当前任务进度
/models      切换使用的模型
/memory      查看长期记忆

非常适合 "随时随地给 AI 打工人派活" 的场景。

通过 Python 客户端

from deerflow.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat(
    "分析这篇论文，总结三个要点",
    thread_id="paper-review",
    upload=["paper.pdf"]
)
print(response)

适合嵌入到自己的 Python 项目里。

和 Claude Code 集成

装上 claude-to-deerflow skill 后，在 Claude Code 里直接：

/claude-to-deerflow 帮我做一份 PPT
/claude-to-deerflow status
/claude-to-deerflow upload ./data.csv

一个有意思的玩法是——用 Claude Code 调度 DeerFlow，让 DeerFlow 跑长任务,Claude Code 只负责"指挥"。

七、实战场景

场景 1：自动整理技术调研

任务：调研 2026 年主流向量数据库产品，对比 Pinecone、Weaviate、
Qdrant、Milvus、Chroma 的性能、定价、生态，输出 Markdown 报告
并附上 benchmark 图表。

DeerFlow 会自动搜索、下载文档、运行基准测试、生成图表并汇总。

场景 2：批量处理数据

任务：读取 /uploads/logs/ 目录下所有 .log 文件，提取错误信息，
按类型聚合，输出 CSV 和柱状图。

沙箱里跑 Python 脚本，十几秒搞定。

场景 3：生成网页 / 幻灯片

任务：给我做一份 10 页的产品介绍 PPT，主题是"量子计算科普"，
要有动画和图示，风格参考苹果发布会。

支持直接导出 .pptx 或 HTML 网页。

场景 4：代码工程任务

任务：我有一个 Node.js 项目（见上传），请阅读代码，找出性能瓶颈，
提出 3 个优化方案并实现第一个。

由于有沙箱环境,它能真的跑测试看效果。

八、注意事项

1. 安全风险

DeerFlow 默认设计为在本地可信环境部署。

如果要暴露到公网，一定要做：

  • IP 白名单
  • 身份认证网关（如 Cloudflare Zero Trust / Nginx Basic Auth）
  • 网络隔离（DMZ）
  • 不要用 root 跑沙箱

2. Token 成本


长任务一次可能消耗几万到几十万 token。用前算好预算，或者：
  • 先用 flash 模式测试
  • 在 config 里设 token 上限
  • 接入本地模型（Ollama / vLLM）降低成本

3. 沙箱逃逸


开启 bash 访问权限时要谨慎，建议：
  • 用 Docker 沙箱而非本地直接执行
  • 严格限制文件系统权限
  • 不要给它任何生产数据库的凭证

4. 版本迭代


DeerFlow 2.0 是完全重写的版本，与 v1 不兼容。如果你从老版本升级，不能直接迁移，需要重新部署。

九、常见问题

Q1：启动后访问 localhost:2026 显示 502

检查 make doctor 输出,通常是 LLM 连接失败或沙箱镜像没拉下来。

Q2：子代理派生太多，token 爆炸

在 config.yaml 里限制 max_subagents 和 max_tokens_per_task。

Q3：中文模型支持

豆包 / DeepSeek / Kimi 都支持，且在国内访问更快。推荐用 DeepSeek v3.2（性价比高）。

Q4：能连本地 Ollama 吗？

可以。选择"OpenAI 兼容"提供商，填入 Ollama 的 http://localhost:11434/v1。注意本地模型上下文窗口要足够大。

Q5：和 LangChain 的 Agent 有什么区别？

LangChain 更像一个"库"，DeerFlow 是一个完整的产品，包括 Web UI、沙箱、IM 集成、长期记忆、多代理编排——开箱即用。底层其实也用了 LangGraph。

十、结语

DeerFlow 的核心价值是"让 AI 真正能干活"，而不只是聊天。

如果你只是偶尔问问问题，DeerFlow 是大炮打蚊子。但如果你有长任务自动化的需求——调研、报告、代码工程、数据处理——那它几乎是目前开源世界里最完整的方案之一。

字节把这种内部生产力工具开源出来，无论是出于技术展示还是社区扩张，对我们普通开发者而言都是大好事。花一个下午部署一下,你会对"AI 打工人"这个词有新的体会。

仓库地址：https://github.com/bytedance/deer-flow
官方文档：见仓库 README 和 docs/ 目录
推荐配置：8 核 16G 服务器 + DeepSeek v3.2 API

有任何部署报错或使用疑问，欢迎评论区交流。

本文首发于「小丸子博客」。转载请注明出处。

评论 (0)

暂无评论